在多台主机上部署网关节点，就近处理请求，断网时仍能继续服务
网关节点
网关节点是一台运行 Zenova 网关的主机。控制面所在的主机本身就是第一个节点（中心节点，名为 office-primary）；你可以再添加任意多个远端节点，让请求在离用户或上游更近的地方处理。
本页只有平台管理员（root）能看到：侧栏「平台 → 网关」。网关页有四个页签：概览（节点数、入口池、入口证书与运行态一屏看全）、入口与证书（公开访问地址与入口证书）、节点（本页主要内容）、出口判定（各渠道在各节点上的出口状态）。
1. 节点能做什么
- 就近处理请求：节点自己完成鉴权、路由、限流、护栏检测和计费预授权，请求不绕回控制面。
- 断网继续服务：节点与控制面断开时，按最近一次拿到的配置继续处理请求；请求记录先暂存在节点本地，恢复连接后自动补传。
- 统一入口：把多个节点加入入口池，公开访问地址的 DNS 解析到这些节点，任何一个节点故障都可以摘掉而不影响整体。
每个节点启用哪些「面」（模型网关、A2A 等）由你在界面上勾选；没有启用的面，节点会直接拒绝对应的请求。
2. 网络要求
开通前请确认：
| 方向 | 要求 |
|---|---|
| 节点 → 控制面 | 节点能通过 HTTPS 访问控制面回连地址（默认 443）。控制面使用自签证书时，在添加节点时粘贴 CA 证书。 |
| 客户端 → 节点 | 节点入口端口对客户端开放。业务访问地址是 HTTPS 时，节点地址需要被「网关 → 入口与证书」里的入口证书覆盖（通配符证书即可）；是 HTTP 时入口不使用证书。 |
| 控制面 → 节点 | 不需要。控制面从不主动连接节点，节点主动拉取配置、上报心跳。 |
节点主机需要 Linux（systemd）或 macOS（launchd），x86_64 或 arm64。
3. 添加节点
- 点击 创建并生成安装命令，复制命令。
在目标主机上创建独立的暂存目录，所在文件系统须允许执行程序，例如：
mkdir -p "$HOME/zenova-node-install"将两个文件放入该目录：与控制面版本一致、与节点主机平台对应的安装器（例如 zenova-<版本>-linux-amd64.tar.gz），以及定制站「网关节点」下载项 zenova-node.zpkg。不要在安装根的父目录（如 /opt）直接解压：压缩包会解出名为 zenova 的文件，占用中心平台默认安装目录 /opt/zenova。进入暂存目录并解压安装器后，在该目录以 root 执行复制的命令，命令形如：
cd "$HOME/zenova-node-install"
tar xzf zenova-<版本>-linux-amd64.tar.gz
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token <一次性安装令牌>控制面使用自建 CA 或私网 http 回连时，生成的命令会自动带上对应参数，请完整复制，不要手工删改。
安装目录的规则与单机安装的 --install-dir 相同：必须是至少两级的绝对路径，只能包含字母、数字、点、下划线、短横线和斜杠；不能位于中心平台安装目录（/opt/zenova）之内，同机已有中心安装时也不能与其目录重叠；Linux 上不能位于 /tmp、/var/tmp、/home、/root、/run/user、/usr、/etc、/boot。不符合时，控制台的「安装目录」字段会标红并说明原因，节点安装器也会在写入任何文件前拒绝。节点安装器在写入任何文件前会一次性执行完整的主机检查（CPU 架构、内存、磁盘、服务托管器、可执行权限与安全模块、时钟偏差、监听端口以及到控制面的连通性），如有阻断项会汇总打印稳定诊断代码与处理建议。
安装命令中的令牌只显示一次，有效期见界面提示。过期或丢失时，在节点详情页点击 重新签发安装命令；重新签发时同样可以填写安装目录，留空则安装到默认目录。也可以在控制面主机上执行 zenova gateway-node issue --names <节点名> --control-plane-url <控制面回连地址> --install-method systemd（macOS 节点为 launchd）批量签发，输出中包含每个节点的一次性安装令牌。
安装完成后，向导里的状态会从「等待节点首次上线」变为「在线」，无需刷新页面。安装失败时，安装器会打印失败原因（例如令牌已过期或已使用、节点包校验失败、系统服务启动失败）并以非零状态退出。
4. 入口池与负载均衡
节点上线后不会自动承接公开流量，需要手动 加入入口池：
- 在节点列表的「更多」菜单或节点详情页点击 加入入口池。
- 控制面会先做入口自检：节点地址是否填写、入口证书是否覆盖节点地址、从控制面能否访问到节点入口、节点是否就绪。任何一项不通过都会逐条列出原因，节点不会入池。
- 自检通过后，到 平台 → 网关 → 概览 页签查看「统一入口」卡片，把公开访问地址的 DNS 解析到卡片里所有「可服务」节点的地址（多条 A/AAAA 记录或你的负载均衡器后端）。
节点离开入口池、排空或变为不可服务时，请同步调整 DNS 或负载均衡器。入口池里没有任何可服务节点时，会触发「入口池没有可服务的节点」告警。
入口证书统一在 平台 → 网关 → 入口与证书 页签设置，控制面会自动下发到每个节点入口：
- 业务访问地址是 HTTP 时，入口不使用证书，页签上只显示入口协议。
- 业务访问地址是 HTTPS 时，在「证书来源」中选择「上传证书」（PEM 证书链加私钥，或 PFX 文件）或「自动签发」。证书需要覆盖的名称由业务访问地址决定，页签上会列出；要换名称，请在「部署配置」中修改业务访问地址。
- 用 IP 地址或单段主机名访问时只能上传证书，证书的使用者可选名称里需要包含该 IP 地址或主机名。
- 自动签发默认使用公共证书颁发机构；企业有内部证书颁发机构时，把「证书颁发机构地址」改为它的目录地址。
页签底部提示入口是否已就绪；证书缺失、未覆盖所需名称或已过期时会写明原因。
5. 断网时会发生什么
| 状态 | 节点行为 |
|---|---|
| 断网 2 分钟内 | 正常服务，界面状态仍为在线。 |
| 断网超过 2 分钟 | 界面标为「离线」并触发告警；节点仍按最后一份配置继续服务。 |
| 断网期间 | 请求记录写入本地暂存；计费按节点上已领取的配额额度扣减。 |
| 暂存写满 | 按「暂存满时」的设置拒绝新请求，或丢弃请求正文只保留计量。 |
| 护栏服务不可达 | 按运行参数「护栏不可达时」处理：放行、拒绝，或只放行只读请求。 |
| 恢复连接 | 自动补传暂存的记录、拉取最新配置，状态恢复为在线。 |
6. 运维操作
节点详情页提供：
- 编辑运行参数：启用的面、暂存配额与策略、护栏不可达时的处理方式。节点在线时数秒内生效。
- 编辑网络：节点地址、控制面回连地址、CA 证书，以及「经本节点转发控制台」（见下文）。
- 轮换实例密钥：节点在线时自动换用新密钥，请求不受影响。
- 排空：节点停止接收新请求，等待进行中的请求、回传积压和本地暂存清空。可以随时取消排空；命令行为
sudo zenova gateway-node join-pool --name <节点名>，入口自检通过后取消排空并回到入口池。 - 退役：排空完成后才能退役；退役会作废节点上的全部实例身份，且不可恢复。中心节点不能退役。
- 删除：只有从未上线的节点可以删除，删除后安装命令立即失效。
升级
节点版本低于最新版本时，详情页会出现「节点可以升级」。按第 3 节的方法将新版本安装器与 zenova-node.zpkg 放入独立的可执行暂存目录。点击 签发升级命令，进入该目录并解压新安装器，再以 root 执行复制的命令，命令形如：
cd "$HOME/zenova-node-install"
tar xzf zenova-<目标版本>-linux-amd64.tar.gz
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token <新签发的令牌> --upgrade没有浏览器时，在控制面主机上执行 sudo zenova gateway-node upgrade-command --name <节点名> 签发，输出 JSON 中的 command 即上面的命令（令牌一次性，expiresAt 为过期时间）；与「签发升级命令」一样会作废该节点此前签发的令牌。
控制面升级包含节点所在系统的节点包时，控制面升级会在控制台切换之前逐台自动升级在线节点：先排空、换包，入口自检通过后回到入口池；任一节点失败时控制台不切换，失败节点自行回到旧版本。升级包不含某个在线节点所在系统的节点包（例如节点与控制面平台不同）时，升级前检查「网关节点」一项不通过，须先用上面的命令逐台手工升级这些节点，升到目标版本的节点会被跳过。排空与回池都不改 DNS 或负载均衡：入口池只有一个节点时，它升级期间公开入口不可用。
升级命令不带 --install-dir：安装器从节点主机上已安装的系统服务单元读出首次安装时的目录，升级只替换程序文件与服务配置，保留节点身份、暂存与账本数据。安装目录不能通过升级更换；在升级命令上另指目录会被拒绝，需要换目录时请先清空重装。
早期版本的节点把数据放在 /var/lib/zenova-node、配置放在 /etc/zenova-node（macOS 为 /usr/local/var/zenova-node、/usr/local/etc/zenova-node）。升级到本版本时会自动把数据与配置迁移到默认安装目录下的 data/ 与 etc/，无需手工操作：手工执行升级命令与控制台发起的自动升级都会迁移。迁移先停止节点服务；同一磁盘上直接移动，跨磁盘时先复制、逐项核对内容与权限后再删除原目录。任何一步失败都会倒序恢复原目录、重新启动原有服务，并以中文说明失败原因，处理后重新执行升级即可。旧布局的节点升级时不能同时指定其他安装目录。
通过控制台自动升级旧布局节点时，迁移与换包由新版本程序一次完成；节点系统日志中会出现一条「网关节点已迁移到安装目录布局并完成换包（结果以新回执为准）；旧版本执行器到此停止」的失败记录，这是旧版本升级执行器按设计停止，属于正常现象，升级结果以节点详情页显示的版本为准。列表的「版本」列会把需要升级的节点标黄。
无论节点早于还是晚于单进程合并版本，升级都会由安装器自动完成切换（旧版双进程节点会自动停用并清理旧 zr 服务单元与配置，迁移至单进程 edge），完成后请直接核对终端输出的验收报告。
经本节点转发控制台
远端节点的入口默认只承载网关与业务入口路径，在节点地址上打开控制台页面会得到 404。当管理员只能经某个远端节点访问平台（例如控制面只在内网隧道里可达）时，可以为该节点打开 经本节点转发控制台：
- 在控制台打开：节点详情 → 编辑网络 → 打开「经本节点转发控制台」→ 保存。详情页「网络」一栏显示当前状态。
- 在命令行打开：在控制面主机上执行（
off为关闭）：
sudo zenova gateway-node set --name gw-sh --forward-console on命令与「编辑网络」使用同一套校验；输出 JSON 报告，changed 表示本次是否改了值。
打开后，控制面把新配置随节点配置一同下发，节点在数秒内重写入口路由并平滑重载，不中断正在处理的请求。转发规则：
- 网关与业务入口路径照常在节点本地处理，不受影响；其余路径（控制台页面与控制台接口）转发到中心管理入口。
- 转发目标由平台自动推导：节点控制面回连地址的主机，加上中心管理入口的端口（安装时确定，可在部署配置页修改），以明文 HTTP 转发。回连地址本身的端口是节点专用的内部入口，不提供控制台，不作为转发目标。
- 转发的请求仍经过节点入口的 WAF 防护。
- 节点以平台下发的可信代理凭据把访问者的真实地址带给中心，管理网段白名单仍按访问者的真实地址判定：不在白名单内的地址经节点访问控制台同样被拒绝，无需为节点另行配置可信代理。
关闭后节点恢复为控制台路径返回 404。只有远端节点有这个选项；中心节点本身就承载控制台。
7. 告警
以下告警默认关闭，在「告警规则」中订阅渠道后才会投递：
| 告警 | 触发条件 |
|---|---|
| 网关节点离线 | 节点心跳中断超过 2 分钟 |
| 回传积压 | 节点最早未回传的记录超过 10 分钟 |
| 本地暂存过高 | 暂存已用超过 80% |
| 配置落后 | 节点落后超过 2 个配置版本 |
| 入口证书即将过期 | 剩余不足 30 天 |
| 入口池没有可服务的节点 | 入口池非空但全部不可服务 |
| 节点出口降级 | 节点访问部分上游渠道失败率偏高 |
| 渠道只剩最后一个节点 | 某渠道其余节点均被判定避开 |
8. 常见问题
安装时提示「安装命令已过期」？ 在节点详情页重新签发安装命令，用新命令重新运行。
节点一直「等待首次上线」？ 在节点主机上确认能访问控制面回连地址（curl -v https://<控制面地址>），并查看服务日志：Linux 执行 journalctl -u zenova-node-edge，macOS 查看 /usr/local/var/zenova-node/edge.log。节点上处理请求的只有这一个服务，鉴权、路由与上游调用的日志都在这里。
加入入口池时提示「入口证书不覆盖节点地址」？ 在「网关 → 入口与证书」上传覆盖该节点地址的证书（例如 *.gateway.example.com），或把节点地址改成证书已覆盖的域名。
节点显示「运行的面与配置不一致」？ 通常是节点版本过旧，不支持新勾选的面。升级节点后会自动恢复。