9. 增加远端网关节点

POC 部署手册章节。按 2026.10 主线代码核对；命令输出以当次交付的安装器为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：业务调用方位于另一个网络区域、控制面不在那里时，可以在该区域增加一台远端网关节点，让模型与工具调用在当地完成鉴权、路由与转发，不必绕回控制面。本章说明何时需要独立节点、开通前要准备什么、如何在控制台创建节点并在节点主机上安装、如何核对上线，以及重装、更换控制面与升级的做法。读者是实施工程师与客户方系统管理员。

9.1 什么时候需要独立节点

适用场景：业务调用需要在另一个网络区域就近接入，而控制面不在那里。

控制面所在的主机本身就是第一个网关节点，名为 office-primary（中心节点）。它随控制面一起安装、一起启动，单机部署时不需要再单独安装节点。只有当调用方与控制面不在同一网络区域、跨区域访问代价高或不被允许时，才需要增加远端节点。

远端节点的工作方式：

• 节点自己完成鉴权、路由、限流、护栏检测与计费预授权，请求不绕回控制面。
• 节点主动连接控制面拉取配置、上报心跳；控制面从不主动连接节点。
• 节点与控制面断开时，按最近一次拿到的配置继续服务；请求记录先暂存在节点本地，恢复连接后自动补传。

注意：节点上线后不会自动承接公开流量。需要让公开访问地址解析到该节点时，还要在节点详情中「加入入口池」并调整 DNS 或负载均衡，这一步通过入口自检后才生效。POC 阶段只验证就近调用时，业务方直接使用节点地址即可。

9.2 前提

前提：控制面已按第 4～7 章安装完成并通过验收，中心节点 office-primary 在线。

节点安装器在写入任何文件前，会一次性执行完整的主机检查：CPU 架构、内存、磁盘、服务托管器、可执行权限与安全模块、时钟偏差、监听端口，以及到控制面的连通性。有阻断项时汇总打印诊断代码与处理建议，不写入任何内容。诊断代码中 NODE 组为节点相关代码，含义查产品文档站的「安装与运维诊断代码」页。

节点安装目录规则

注意：安装目录首次安装后不能通过升级更换。 创建节点前按节点主机的磁盘规划好目录。

9.3 在控制台创建节点

前提：以 root 登录平台管理控制台。

操作步骤

1. 打开「网关 › 节点」，点「添加节点」。
2. 按四步弹窗填写：

1. 点「创建并生成安装命令」，立即复制整条命令，保存到受控位置。

你会看到

• 弹窗显示完整的安装命令，其中包含一次性令牌。
• 弹窗进入「上线进度」，状态为等待节点首次上线；节点安装完成后无需刷新页面即可更新。

注意：安装命令只显示一次。关闭弹窗后无法再次查看。令牌过期（24 小时）、丢失或已使用后，在节点详情点「重新签发安装命令」获取新命令。

注意：令牌等同于节点接入凭据。不要通过即时通讯、邮件或工单明文传递，不要截图外传。

9.4 在节点主机安装

前提：节点主机满足 9.2 节要求；已从下载站取得与控制面同产品、同版本、匹配节点主机平台的安装器与离线包，并按第 2 章核对过 SHA-256。

操作步骤

1. 把安装器与离线包放到节点主机同一个暂存目录，解压安装器，并把离线包改名为 zenova-node.zpkg（控制台生成的命令使用这个固定文件名）。

# 节点主机 · root · 写入（解压安装器、离线包改名）
mkdir -p /root/zenova-install
cd /root/zenova-install
tar xzf <安装器>.tar.gz
mv <离线包>.zpkg zenova-node.zpkg

1. 先预检。预检执行主机检查与到控制面的连通性检查，不消耗令牌，不写入任何内容。

# 节点主机 · root · 只读（预检，不消耗令牌）
cd /root/zenova-install
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --check-only

1. 预检通过后，执行控制台给出的安装命令。控制面 CA 相关参数以控制台生成的命令为准，完整复制、不要删改：控制面使用自建 CA 或填写了安装目录时，生成的命令会自动带上对应参数。命令形如：

# 节点主机 · root · 写入（安装节点并消耗令牌）
cd /root/zenova-install
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token <令牌>

1. 推荐改用 --token-file：把令牌写入一个仅 root 可读的文件，在控制台生成的命令中把 --token <令牌> 换成 --token-file <文件>，其余参数原样保留。--token-file 与 --token 二选一。

# 节点主机 · root · 写入（令牌写入文件后安装节点，消耗令牌）
cd /root/zenova-install
umask 077
printf '%s' '<令牌>' > /root/zenova-install/node.token
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token-file /root/zenova-install/node.token

1. 安装成功后删除令牌文件。

# 节点主机 · root · 删除（清理令牌文件）
rm -f /root/zenova-install/node.token

你会看到

• 预检通过时，屏幕给出通过提示且不写入任何内容；有阻断项时列出诊断代码与处理建议（以实际输出为准）。
• 安装成功时，安装器打印结果；失败时打印原因（例如令牌已过期或已使用、节点包校验失败、系统服务启动失败）并以非零状态退出。

注意：--token-file 的好处是令牌不出现在进程列表和 shell 历史中。使用 --token 时，同机其他用户在安装期间可能通过进程列表看到令牌。

注意：预检不校验令牌。 令牌只在正式安装时兑换，令牌过期或已被使用的错误只会在这一步出现；预检通过也不代表正式安装一定通过。出现令牌错误时，在节点详情「重新签发安装命令」后用新命令重跑。预检失败时不要直接执行带令牌的命令。

9.5 核对上线

操作步骤

1. 回到控制台「添加节点」弹窗或节点详情，查看「上线进度」。
2. 在节点主机上查看节点状态。

# 节点主机 · root · 只读
sudo zenova status

1. 在节点列表与节点详情核对节点信息（见下）。
2. 让调用方把 Base URL 指向节点地址，按第 7.3 节的方法完成一次真实调用，并在控制台「网关请求」中按响应头 x-request-id 查到这次调用。
3. 上线异常时查看节点日志。

# 节点主机 · root · 只读（查看节点日志）
sudo zenova logs node-edge --since '30 min ago'
sudo zenova logs node-caddy --since '30 min ago'

你会看到

• 「上线进度」依次显示三个状态：

• zenova status 显示节点身份、所连控制面与就绪状态。
• 节点列表中可核对：「状态」「版本」「配置落后版本数」「最近心跳」「5 分钟请求数」「5 分钟错误率」「回传积压」「本地暂存」。
• 真实调用返回 HTTP 200 与模型回复，控制台「网关请求」中能按 x-request-id 查到这次调用。

注意：节点与控制面断开 2 分钟内，界面仍显示在线；超过 2 分钟标为「离线」，节点仍按最后一份配置继续服务。

注意：控制面使用自签证书而创建节点时没有粘贴 CA 证书时，节点无法连上控制面。处理办法是在节点详情「编辑网络」补上 CA 证书，再按需重新签发安装命令。

9.6 重装、更换控制面与升级

已有节点再安装

在已安装节点的主机上再次执行安装命令时，安装器提示「本机已存在网关节点安装」并停止，不会覆盖现有节点。

需要让该主机连接到另一个控制面时，先在目标控制面上为它创建节点；在同一控制面上重新接入（节点身份失效、签名公钥无法自动更新）时，在控制台节点详情签发「重新注册命令」（或在控制面主机执行 sudo zenova gateway-node reenroll-command --name <节点名>）。之后执行：

# 节点主机 · root · 写入（重新接入，消耗新令牌）
cd /root/zenova-install
sudo ./zenova install node --package zenova-node.zpkg --reenroll --control-plane <控制面回连地址> --token <新令牌>

注意：不要手工删除节点目录（如 /opt/zenova-node）或系统服务单元来"重装"。节点目录里保存着节点身份、本地暂存与尚未回传的请求记录，手工删除会使这些记录永久丢失，且后续安装与升级无法正确识别本机状态。重新接入一律用上面的 --reenroll。用新主机顶替失联实例时，在新主机上执行同一条重新注册命令并去掉 --reenroll。

升级节点

前提：已取得目标版本、与节点主机平台匹配的安装器与离线包。

操作步骤

1. 升级包含节点所在系统的节点包时，在线节点由控制面升级自动完成，一般无需在节点上操作。 控制面升级时（见第 10.5 节）会在控制台切换之前逐台升级在线节点。以下步骤用于：升级包不含节点所在系统的节点包（升级前检查「网关节点」一项不通过，须在控制面升级之前先完成）、升级时节点离线、或自动升级失败后需要单独补升的节点。
2. 在节点主机上放好新版本的安装器，并把新版本离线包改名为 zenova-node.zpkg。
3. 在控制台节点详情点「签发升级命令」，复制命令。
4. 用新版本安装器在暂存目录执行该命令，命令带 --upgrade，形如：

# 节点主机 · root · 写入（升级节点，保留节点身份与数据）
cd /root/zenova-install
sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token <新签发的令牌> --upgrade

1. 升级完成后按 9.5 节核对节点版本与上线状态，并通过该节点完成一次真实调用。

你会看到

• 节点切换到新版本；节点列表「版本」列与控制面目标版本一致。
• 节点切换到新版本后 60 秒内未就绪，会自动切回旧版本，节点继续以旧版本服务。此时查 node-edge 日志定位原因，处理后重新签发升级命令再执行，不要反复执行同一条命令。

注意：升级保留节点身份、暂存与账本数据；升级命令不带 --install-dir，沿用首次安装的目录。在升级命令上另指目录会被拒绝。

注意：控制面升级的离线包须包含在线节点所需平台的节点包，否则升级前检查「网关节点所需节点包齐全」不通过并列出缺包的节点与平台。

能力说明

---

上一章：8. 安装后必做事项与日常运维 · 下一章：10. 备份、恢复与升级