23. 平台运行与日常维护

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

运维范围：本章标注为平台管理员专属的页面只在平台管理台显示，由私有部署的平台管理员（root，或被授予“平台管理员”的平台账号）操作；SaaS 方式下由服务运营方执行，普通租户看不到这些入口。标注为租户管理员的页面在各租户的管理控制台中操作，只影响本租户。命令行操作需要在安装主机上以 root 执行。

本章说明系统升级、备份恢复、日常巡检、运行参数、部署配置、网关节点、租户以及授权许可等维护工作。升级、恢复和入口变更前，应按组织流程确认影响范围、维护窗口和回退方案，并保留操作记录。

维护入口分布如下：

升级、回滚、备份和恢复只由 zenova 程序及其常驻的升级服务执行：控制台页面与命令行调用同一个执行器，产生同一份记录。

23.1 执行系统升级

平台管理员专属。从“管理控制台 → 系统设置 → 系统更新”进入，页面包含“当前版本”“升级包”“升级”和“升级历史”四个区域。

1. 在“当前版本”核对“版本”“部署方式”和各能力状态。能力状态包括“已启用”“本机已有，未启用”“需要获取”和“许可证未包含此能力”。
2. 获取升级包：在“升级包”选择“复制获取链接”（安装介质声明了获取地址时显示），在可访问互联网的电脑上打开链接下载升级包，或由交付方提供升级包，再回到本页选择“选择升级包”上传。页面只接受 .zpkg 升级包；上传中断后可选择“继续上传”。
3. 上传完成后系统自动执行升级前检查。检查项包括“许可证”“磁盘空间”“平台匹配”“部署配置”“基础设施版本”“数据库变更耗时”“能力包齐全”“网关节点兼容性”“智能体目标版本”“可直接升级的最低版本”和“版本顺序”，结果为“通过”“未通过”或“不适用”。未通过时按提示处理，例如“前往部署配置”“前往许可证”“重新选择升级包”，处理后选择“重新检查”。
4. 核对页面给出的影响说明。快速切换时控制台切换约数秒，期间操作稍慢、不会报错；不支持快速切换的部署在切换期间控制台暂不可用。两种情况下网关调用均不受影响。
5. 开始升级前，按第 23.2 节完成一次备份并记录备份标识。
6. 选择“升级到 {版本}”，在弹窗中输入当前账号的密码，再选择“开始升级”。升级开始后由系统自动完成，期间不要关闭服务器。
7. 在进度中依次查看各阶段：“准备”“控制台切换”“界面更新”“中心网关更新”“能力更新”“智能体滚动更新”“网关节点滚动更新”“数据整理”“收尾”。数据库变更在“准备”与“控制台切换”阶段内完成，不单独列为一个阶段。不适用的阶段会被跳过。
8. 完成后在“升级历史”核对“版本”“结果”“用时”“切换用时”和“操作人”，再验证登录、模型调用和常用管理操作。然后在“部署配置 → 最近一次验收”中选择“立即验收”。

升级结果的含义与处理：

同一时间只能有一个升级在进行；已有升级时页面提示“已有升级正在进行”。

使用命令行升级与回滚

在安装主机上执行：

sudo zenova upgrade ./<升级包>.zpkg

命令把升级包交给本机升级服务，依次完成上传、升级前检查和切换，并持续显示进度。它与控制台升级是同一个流程、同一条升级记录。

本机升级服务的版本早于升级包时（例如控制台上传后提示“发布清单版本不受支持”或“升级包的目标版本 zenova 二进制无效”），请解压与升级包同一版本、同一产品版本的安装包，用其中的程序执行 sudo ./zenova upgrade ./<升级包>.zpkg。命令先核对升级包与安装程序、本机已安装的产品版本一致，再由新程序接管本机升级服务，随后照常升级；接管任一步失败时恢复原升级服务，本机不发生变化。这一次升级完成后，以后的升级恢复在控制台进行。

需要退回上一次升级之前的版本时执行：

sudo zenova rollback

新版本的数据库变更已经落库时，回滚会被拒绝；此时只能升级到修复版本，或按第 23.3 节恢复升级前的备份。

升级前检查提示“基础设施版本不满足要求”且平台数据库、分析数据库由本平台部署时，在维护窗口执行 sudo zenova infra upgrade <基础设施包>，完成后回到“系统更新”选择“重新检查”。使用现有数据库时，由数据库管理员负责升级。

当前版本早于升级包要求的“可直接升级的最低版本”时，页面提示“需要先升级到中间版本，请复制获取链接获取”；按提示先升级到中间版本，再升级到目标版本。早期以容器方式部署的安装不能升级，需按《Zentrix Gateway 部署与服务选型指南》的清空重装说明重新安装。

启用或停用可选能力

在“当前版本”的能力列表中，“本机已有，未启用”的能力可直接选择“启用”；已启用的能力可选择“停用”；“需要获取”的能力选择“复制获取链接”取得能力包。Zentrix 网关版本可选的能力包括“知识库”“语义缓存”“运维观测”和“数据高可用”，能否使用同时受许可约束。Kubernetes 集群部署的能力由集群配置管理，本页不受理启停。

23.2 备份平台数据

平台管理员专属。从“管理控制台 → 系统设置 → 备份与恢复”进入。页面顶部显示当前版本和备份目录可用空间。

1. 选择“立即备份”。页面提示“备份已开始，完成后会出现在列表中。”
2. 在任务信息中查看“当前步骤”，依次为“准备”“安装状态”“平台数据库”“分析数据库”“对象存储”“校验”。
3. 完成后在“备份列表”核对“创建时间”“版本”“发起人”“大小”和“包含内容”。未纳入的组件显示为“（未纳入）”及原因。
4. 需要把备份保存到安装主机以外时，选择“下载”取得 .zbackup 归档，转存到独立的存储位置。

备份内容与未纳入的情况：

密钥服务的密钥目录 /etc/zenova/secret-service/keys 纳入主机级备份，并与备份归档分开保管；换主机恢复时需要该目录。

备份由页面或命令行手动触发。定期备份、异地转存和过期备份清理由部署管理员按组织流程安排。

命令行使用同一套备份：

不再需要的备份在列表中选择“删除”，删除后不可找回。已有备份、恢复或升级在进行时，备份操作会被阻止。

Kubernetes 集群部署时，本页提示数据层备份由集群侧负责，不提供本机备份。

23.3 恢复和演练

平台管理员专属。恢复会用备份覆盖本机数据，备份之后写入的数据将丢失。只能恢复同一版本、同一部署形态与平台的备份；版本不一致时页面提示需先安装为同一版本再恢复。

1. 恢复优先在隔离环境演练：在演练主机安装与备份相同的版本，选择“上传备份”导入 .zbackup 归档。
2. 在“备份列表”找到目标备份，选择“恢复”。
3. 在“从备份恢复”中核对备份标识与时间，按提示输入 RESTORE，选择“开始恢复”。
4. 恢复期间控制台服务会停止，页面显示“正在恢复”；不要关闭页面。任务依次经过“停止控制台服务”、各组件恢复和“启动控制台服务”。
5. 页面提示“恢复已完成。”后，验证登录、模型调用、MCP、路由、权限、审计和告警。
6. 记录可恢复到的时间点、恢复耗时、缺失内容和需要重建的外部依赖数据。

命令行恢复时，先停止控制台服务组，再执行恢复：

sudo zenova stop zenova-worker
sudo zenova stop zenova-runtime-store
sudo zenova stop zenova-control-plane
sudo zenova restore <备份标识或 .zbackup 文件>

命令要求输入确认词 RESTORE。参数为 .zbackup 文件时先导入再恢复。完成后依次执行 sudo zenova start zenova-control-plane、sudo zenova start zenova-runtime-store、sudo zenova start zenova-worker。

恢复过程中旧数据在新数据完整就位前保留。在另一台主机恢复时，还需具备原主机 /etc/zenova/secret-service/keys 目录的主机级备份，见第 23.2 节。使用现有 PostgreSQL 或 S3 兼容存储时，这些数据不在备份中，需由对应管理员按其备份机制同步恢复到同一时间点。覆盖生产环境前，应确认完整备份、近期恢复演练、业务暂停安排和恢复后验证方案均已就绪。

23.4 日常巡检与服务日志

日常巡检建议按以下顺序进行：

“系统运行监控”中，“控制面”包括“控制面”“运行时存储”“后台任务”；“数据面”列出各网关节点；“依赖”包括“系统数据库”“ClickHouse”“对象存储”“权限服务”“密钥服务”“身份提供方”和“语义缓存”，并标明“平台托管”或“外部提供”。打开某一项可查看实例的“版本”“运行态”“最后上报”和影响范围。外部提供的依赖出现异常时，应联系其维护方并检查网络。

“出口网络”按探测目标展示平台访问公网的延迟与丢包趋势，用于定位变慢或断开的层次。可选择“添加探测目标”（只能添加公网地址），并对目标执行逐跳诊断。关闭探测后停止发送探测包，历史数据保留。

控制台不可用时，在安装主机上执行：

sudo zenova status

该命令不依赖控制台，列出各服务运行状态、当前版本、各实例以及进行中与最近一次升级；加 --json 输出机器可读结果。对未运行的服务执行 sudo zenova restart <服务名>，服务名以 zenova status 的输出为准。Linux 主机使用 journalctl -u <服务名> 查看服务日志。控制面不可用期间，网关节点按最近一次下发的配置继续处理调用。

23.5 运行参数边界

平台管理员专属。网关过载保护在“管理控制台 → 平台扩展 → 网关”的“过载保护”页签设置，控制面数据库连接上限在“平台扩展 → 部署配置”的“资源容量”中设置：

在“网关 → 节点”的节点详情中，每个实例显示“本机负载”（处理器与内存占用）和“过载保护”状态（“正常”“过载中”“恢复中”“负载数据不可用”）。节点健康原因显示“本机负载过高，正在拒绝新请求”时，表示占用已超过高水位；显示“本机负载数据不可用，过载保护未生效”时，应检查该节点实例是否在线上报。

其他限制分别在对应页面设置，不能用某一处配额代替其他层级的限制：

调整步骤：

1. 记录原值、目标值、调整原因、影响范围和计划恢复时间。
2. 保存后查看页面给出的生效状态，例如“当前生效值”或发布结果。
3. 使用受控请求验证正常范围和超限范围，并在调用记录中确认拒绝来源。
4. 观察同一时间范围内的请求量、错误率和耗时；出现异常时恢复原值。
5. 具备“全链路审计”许可模块时，在“操作审计”中核对调整与恢复记录。

23.6 维护部署配置与入口监听

平台管理员专属。从“管理控制台 → 平台扩展 → 部署配置”进入。页面列出可由管理员修改的部署配置、入口监听、数据依赖和最近一次验收结果。

修改配置项：

1. 在目标项选择“修改”，填写“新值”并保存。敏感项只显示“已设置”或“未设置”，不回显原值。
2. 页面提示“已保存，正在让新值生效”，相关服务在后台重新加载或重启。生效完成后显示已重启的服务数量；控制台需要切换时会无中断切换到新配置。
3. 显示“有服务未能重启”或“控制台未能切换到新配置”时，在安装主机执行 sudo zenova status 检查。

“对象存储方式”不支持在线修改，页面提示“不支持在线修改：请备份后按新的选择重新安装，再恢复数据”。升级进行中或上一次修改仍在生效时，所有修改按钮不可用。使用现有服务的数据依赖由客户自行维护，本页不提供其凭据轮换。

在安装主机上可以用命令修改同一组配置项，例如：

sudo zenova config set PUBLIC_URL https://gateway.example.com

敏感项不接受写在命令行上，需加 --value-stdin 从标准输入读取，或在终端提示时输入。

修改入口端口与绑定网卡

“业务入口”提供模型、MCP、A2A 等对外服务，“管理入口”提供控制台。两个入口默认均为 80 端口，端口相同时合并为一个入口，改为不同端口后拆分监听。

1. 在“入口监听”选择对应入口的“修改”，填写端口并选择绑定网卡（“全部网卡”或某个本机地址）。
2. 保存前确认影响：修改业务入口后，外部调用方与网关节点需改用新端口；修改管理入口后，当前页面所在地址失效，页面给出新的管理访问地址并提供“前往新地址”。
3. 两个入口使用相同端口时绑定网卡必须相同；端口已被本机其他程序或平台其他服务占用时保存会被拒绝。
4. 生效后从新地址访问控制台，并使用外部客户端验证业务入口。

安装时可通过 --business-entry-port、--admin-entry-port、--business-entry-bind、--admin-entry-bind 预置这些值。Kubernetes 集群部署的入口由集群配置管理，本页不受理修改。修改入口后，同步检查防火墙、负载均衡和“网关 → 入口与证书”中的公开访问地址，见第 24.8 节。

23.7 管理网关节点

平台管理员专属。从“管理控制台 → 平台扩展 → 网关”进入，页面包括“概览”“入口与证书”“节点”“过载保护”“出口判定”“出口代理”六个页签。控制面所在主机本身就是中心网关节点，随安装一并启动；远端网关节点用于在其他主机上就近处理请求。

添加远端节点：

1. 在“节点”页签选择“添加节点”，在“添加网关节点”中填写“节点名”（小写字母、数字和连字符，2–31 个字符，创建后不可修改）、“节点地址”（客户端访问该节点用的域名或 IP，入口证书需要覆盖它）、“地域（可选）”、“控制面回连地址”（节点主动连接控制面的地址，页面要求 https:// 开头）和“安装方式”（“Linux（systemd）”或“macOS（launchd）”）。控制面使用自签或内部 CA 时粘贴“控制面 CA 证书”。
2. 按需设置“启用的面”（模型服务为必选）、“副本数”、“本地暂存配额（GB）”和“暂存满时”的处理方式。与控制面断连期间，请求记录先暂存在节点本地，恢复后补传。
3. 选择“创建并生成安装命令”。安装命令只显示一次，有效期 24 小时；过期后在节点详情选择“重新签发安装命令”。
4. 把安装器 zenova 和节点离线包 zenova-node.zpkg 放到目标主机的同一目录，在该目录以 root 运行页面给出的命令。命令形如 sudo ./zenova install node --package zenova-node.zpkg --control-plane <控制面回连地址> --token <一次性令牌>，令牌只能使用一次。
5. 页面显示“上线进度”，节点首次上线后显示“节点已上线”。超过时限仍未上线时，按页面列出的顺序排查。

日常维护：

• 在节点列表核对“状态”“版本”“配置落后版本数”“最近心跳”“5 分钟请求数”“5 分钟错误率”“回传积压”和“本地暂存”。
• 在节点详情的实例信息中核对“入库状态”（“正常”“明细积压”“控制面不可达”“已暂停接收”“已按自报用量结清”“未知”）、“待确认计费”“待写入明细”“最早一条已等待”和“本地剩余空间可支撑时长”。“明细积压”表示调用明细尚未写入分析数据库，节点继续转发并在本地保留，恢复后自动补齐；“已暂停接收”表示节点本地存储已满，新调用被暂缓。
• 系统升级的“网关节点滚动更新”阶段会逐台更新远端节点；节点更新失败时升级结果为“已完成，部分项需处理”。
• 节点已离线且确认不再恢复时，可在“更多操作”中选择“强制退役”，输入节点名确认。强制退役会立即吊销该节点的全部实例身份，并永久丢弃尚未回传的请求记录和本地暂存的报文，无法恢复。

“出口判定”和“出口代理”用于查看和配置节点访问外部服务的出口方式，变更前应与网络管理员确认允许的出口目标。

23.8 管理租户

平台管理员专属。从“管理控制台 → 平台扩展 → 租户管理”进入。列表可按“活跃”“已禁用”“已删除”筛选，并显示名称、状态、结算货币、管理员和本月 Token 等信息。

创建租户：

1. 选择“创建租户”，在“创建新租户”中填写“企业信息”（“租户名称”“标识”）和“默认管理员”（“管理员姓名”“管理员邮箱”“管理员密码”）。“标识”用作 IDP 组织标识，只能使用小写字母、数字和连字符。
2. 选择“结算货币”（人民币或美元）。该租户的售价、额度和账单都使用这个货币，创建后不能更改。
3. 选择“创建”，使用默认管理员账号登录该租户，完成后续成员与配置工作。

维护租户：

• “编辑租户”：修改租户名称与标识；标识变更会影响 IDP 组织映射。
• “编辑配额”：Zentrix 网关形态使用“每月 Token 上限”和“存储上限（GiB）”。留空表示不限制，填 0 表示本租户不能调用模型或不允许上传。Token 按自然月统计，保存后十几秒内在网关生效，可能少量超出。
• “查看用量”：查看租户在所选时段的用量详情。
• 打开租户详情，在“管理员”页签选择“添加管理员”，从企业已有成员中授予管理员权限；“移除管理员”不能移除最后一个管理员。需要时可为管理员“重置两步验证”。
• 在租户详情选择“导出数据”，确认“开始导出”后异步导出该租户的全部数据，就绪后选择“下载”。
• 删除租户后可在“已删除”中选择“恢复”。

23.9 授权许可、通知横幅、品牌与 SMTP 配置

授权许可

租户管理员。从“管理控制台 → 系统设置 → 授权许可”进入。许可按租户生效，导入和移除只影响当前租户。

1. 在“升级商业授权”中选择“导出授权请求 (.json)”，导出的请求文件包含租户与部署的绑定信息。
2. 将请求文件发给供应商，换取签名后的 .lic 文件。
3. 选择“导入 .lic 文件”。许可证在本地验签，校验通过后立即生效。
4. 核对“授权用户数”“授权天数”“到期时间”“高级模块”“License ID”“授权对象”和“导入时间”。

“高级模块”显示“模型护栏”“动态路由”“全链路审计”“用量与成本”的开通状态；“用量与成本”对应 FinOps 模块。未开通高级模块时显示“未开通高级模块（仅主许可）”。未导入许可证时，网关以评估模式运行，页面显示“当前为 Zentrix 评估模式（离线包预置）。不限期试用；导入正式 License 后立即覆盖评估状态。”，“高级模块”中的四个模块均显示为已开通。选择“移除 License”后回落到评估模式。

通知横幅

平台管理员发布对所有租户生效的平台公告；租户管理员发布只对本租户生效的公告。从“管理控制台 → 系统设置 → 通知横幅”进入。

1. 选择“发布新公告”，选择级别（“信息”“警告”“严重”“系统维护”），填写内容（最多 500 字）。
2. 选择“受众”：“全体成员”或“使用指定模型服务的用户”（需选择模型服务）。
3. 设置“开始时间”“结束时间”，开始时间留空表示立即生效。
4. 需要预告模型服务下线时，填写“事件时间”，将“到期动作”设为“停用模型服务”，并选择“提醒节点”。
5. 按需勾选“发送站内信”“发送通知渠道”，核对预计覆盖人数后选择“发布”。
6. 在列表核对“状态”（“待生效”“生效中”“已结束”“已撤回”）。不再需要时选择“撤回”，撤回后不能恢复启用。

品牌

租户管理员。从“管理控制台 → 系统设置 → 品牌”配置本租户的“产品显示名”“Logo”和“Favicon”。图片支持 PNG、SVG、WebP、JPEG，最大 2MB。选择“恢复默认”清除本租户的自定义品牌。

SMTP 配置

租户管理员。从“管理控制台 → 系统设置 → SMTP 配置”进入。SMTP 用于密码重置、邮箱验证等系统邮件，需客户自备 SMTP 服务。

1. 选择“添加 SMTP”，在“发件人”步骤填写“发件人名称”“发件人邮箱”和“站点 URL”。
2. 在“服务器”步骤填写“主机”“端口”“用户名”“密码”和“连接安全”，并保持“启用自定义 SMTP”开启。建议使用支持 TLS 的 587 端口。
3. 保存后在“测试”步骤选择“发送测试邮件”，测试邮件发送到当前账号的邮箱，到收件箱确认收到。
4. 在“连接状态”核对“上次测试状态”“上次测试时间”和“上次测试耗时”。

已保存的密码不回显，编辑时留空表示保持不变。选择“禁用”后，即使已保存凭据，平台也不会发送事务邮件。

上一章：22. 告警、通知、留存、导出与操作审计 · 下一章：24. 常用配置的维护与变更