8. 安装后必做事项与日常运维

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

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

本章内容：安装完成不等于交付完成。本章前三节是装完当天必须做完的三件事——离机备份密钥材料、做首次平台备份并转存、清理临时文件；后四节是日常运维要用到的命令、日志查看、部署配置修改，以及 root 密码与管理面网段的应急恢复。读者是实施工程师与接手运维的客户方系统管理员。本章所有命令都在安装主机上以 root 执行，不依赖控制台是否可用。

8.1 离机备份密钥材料

适用场景：安装完成当天必须做；此后更换主密钥或密钥服务材料发生变化时重做。

前提：安装已完成；已与客户确定一个与安装主机隔离的受控保管位置（不同主机、不同存储，最好不同机房），以及保管人。

平台备份（8.2 节）包含 /opt/zenova/.env（含主密钥），但不包含密钥服务材料 /etc/zenova/secret-service/。密钥服务的 keys/ 用于加密平台保存的全部凭据（模型供应商密钥、对象存储密钥等）。缺了它，即使有平台备份，也无法在新主机上恢复出可用的平台。

操作步骤

1. 打包密钥材料并计算摘要。

# 安装主机 · root · 写入（在 /root 下生成密钥材料归档）
umask 077
tar -C / -czf /root/zenova-keys-$(hostname)-$(date +%Y%m%d).tar.gz \
    etc/zenova/secret-service opt/zenova/.env
sha256sum /root/zenova-keys-*.tar.gz

1. 按客户规定的受控方式，把归档转存到与安装主机隔离的保管位置。
2. 在保管位置重新计算 SHA-256，与第 1 步的输出逐字核对一致。
3. 填写下面的登记表，随交接材料归档（登记表本身不含密钥内容）。
4. 确认复制成功、摘要一致后，删除本机上的归档（见 8.3 节）。

你会看到

• /root 下生成 zenova-keys-<主机名>-<日期>.tar.gz，权限只有 root 可读（由 umask 077 保证）。
• sha256sum 输出一行 64 位十六进制摘要加文件名。

注意：高危。该归档包含主密钥与密钥服务的全部加密密钥。泄露等同于泄露平台保存的全部凭据；丢失则无法从备份恢复平台。 按客户最高密级数据管理：不得通过即时通讯、邮件、工单或网盘分享链接传递；不得与平台备份文件（8.2 节）放在同一位置；保管人变更时在登记表上留痕。

注意：使用自定义安装根（--install-dir）时，命令中的 opt/zenova/.env 换成 <安装根>/.env（去掉开头的 /）。

8.2 首次平台备份与转存

适用场景：安装与第 7 章验收完成后立即做一次；此后每次升级前、每次重要配置变更前都做一次。

前提：安装主机上有足够的可用空间，见本节「注意」。

操作步骤

1. 立即备份，列出备份确认标识，再把它导出为单个归档文件。

# 安装主机 · root · 写入（生成本机备份与导出归档）
sudo zenova backup
sudo zenova backup list
sudo zenova backup export <备份标识> --output /root/zenova-install/first-install.zbackup

1. 计算导出文件摘要，转存到与安装主机不同故障域的受控位置（不同主机、不同存储设备，最好不同机房），在目标位置核对摘要一致。

# 安装主机 · root · 只读
ls -l /root/zenova-install/first-install.zbackup
sha256sum /root/zenova-install/first-install.zbackup

1. 在交接材料中记录：备份标识、导出文件名、摘要、转存位置、保管人、日期。

你会看到

• zenova backup list 列出本机备份，最新的在前。备份标识形如 zb-20261020T020000Z-1a2b3c4d（zb- + UTC 时间 + 8 位随机串）。
• 本机备份保存在 /opt/zenova/data/backups/<备份标识>/。
• 导出文件权限为 0600。

备份范围：

注意：导出文件未压缩、不另加密，且含主密钥。 按最高密级保管，与 8.1 节的密钥材料归档分开存放，不要放在同一台主机或同一个存储桶。

注意：所需空间约等于「本机 PG 数据目录 + 本机对象数据目录 + 1 GiB」。本机备份与导出文件各占一份，导出前确认 /opt/zenova 与 /root/zenova-install 所在磁盘都有余量。

注意：本机备份放在 /opt/zenova/data 下，与平台数据同盘。只留本机备份不算备份——主机或磁盘故障时会一起丢失；执行清空重装（第 11 章）时也会被一并删除。一定要转存。

注意：恢复要求版本、产品、部署形态、平台都相同，旧版本的备份不能恢复到新版本的安装。升级后要重新做一次备份并转存。

8.3 清理临时文件

适用场景：8.1、8.2 节完成之后；交付验收结束时再做最后一次。

前提：密钥材料归档与平台备份导出文件均已转存，并在目标位置核对摘要一致。

操作步骤

1. 按下表处置每一类文件。

1. 删除凭据文件与已转存的归档。

# 安装主机 · root · 删除（凭据文件与已转存的密钥材料归档、备份导出文件）
rm -f /root/zenova-install/secrets.toml
rm -f /root/zenova-keys-*.tar.gz
rm -f /root/zenova-install/first-install.zbackup
ls -la /root/zenova-install/ /root/

你会看到：ls 的输出中不再有 secrets.toml、zenova-keys-*.tar.gz 与 first-install.zbackup；安装器、离线包与 answers.toml 仍在。

注意：只删除上表列出的文件。不要删除 /opt/zenova/state/answers.toml（安装记录，升级与重新配置会用到）、/opt/zenova/.env.runtime/ 下的任何文件；初始密码文件 root-password-initial 在修改 root 密码后自动失效，不需要手工删除。

注意：不要在转存与摘要核对完成之前删除密钥材料归档。删除后如发现转存的副本损坏，回到 8.1 节重新打包。

8.4 日常运维命令速查

适用场景：日常巡检、故障处理、变更窗口。所有命令以 root 在安装主机执行，不依赖控制台。

操作步骤

按「什么时候用」选择命令。

你会看到：每条命令都在终端直接给出结果；zenova doctor 没有阻断项时退出码为 0，有阻断项时为 2。

注意：zenova start/stop/restart 只接受 zenova- 开头的服务名，例如 sudo zenova restart zenova-edge。postgres、clickhouse、caddy、secret-service、spicedb 用 systemctl 管理。

注意：恢复（zenova restore）前，先对当前环境再做一次备份；恢复条件是版本、产品、部署形态、平台都相同，没有升级在进行，控制面组服务已停止。恢复后、启动控制面组之前，先重启 spicedb、secret-service、rustfs（未用自带对象存储时去掉 rustfs）。

注意：严禁用手写的 rm -rf、docker rm、systemctl disable 等命令清理或"重装"平台。需要清空时只走第 11 章的清空重装流程。

8.5 日志怎么查

适用场景：zenova status 显示服务异常、安装或升级失败、需要向支持方提供日志。

操作步骤

1. 按组件查看日志。zenova logs 会解析出该组件当前对应的 systemd 单元（控制面会自动定位到当前接流槽位），再转调 journalctl。

# 安装主机 · root · 只读
sudo zenova logs control-plane --since '30 min ago'
sudo zenova logs edge --follow

1. 不在组件列表里的服务，直接用 journalctl 按单元名查看。

# 安装主机 · root · 只读
journalctl -u [email protected] --since '30 min ago' --no-pager
journalctl -u spicedb.service --since '30 min ago' --no-pager

1. 安装、续装、重新配置的过程日志看 install.log。

# 安装主机 · root · 只读
tail -n 200 /opt/zenova/state/install.log

1. 远端网关节点的日志在节点主机上查看。

# 节点主机 · root · 只读
sudo zenova logs node-edge --since '30 min ago'
sudo zenova logs node-caddy --since '30 min ago'

1. 向支持方反馈时，按下面的命令一次采集齐全。

# 安装主机 · root · 写入（仅在 /root/zenova-install 下生成文件）
sudo zenova status --json > /root/zenova-install/status.json
sudo zenova doctor --all --save /root/zenova-install/doctor
sudo zenova logs control-plane --since '30 min ago' > /root/zenova-install/control-plane.log
sudo cp /opt/zenova/state/install.log /root/zenova-install/

组件与单元名对照（Linux，zenova logs 可用的组件共 8 个）：

其他服务单元（用 journalctl -u <单元名> 查看）：zenova-worker@<槽位>、zenova-updater、spicedb、rustfs，以及能力组件如 qdrant、docling、zenova-runtime-store@<槽位>。实际存在哪些单元以本机安装的能力为准。

你会看到

• zenova logs 输出的就是 journalctl -u <单元> 的内容；不带 --follow 时一次输出完毕，带 --follow 时持续跟随，按 Ctrl+C 退出。
• 组件名写错时，提示「未知的日志组件 …」并列出全部可用组件。

注意：Linux 上的服务日志由 journald 保存，--since 原样传给 journalctl --since，可写 '30 min ago'、'2026-10-20 09:00' 等 journalctl 接受的格式。不存在 /opt/zenova/<服务>/logs/ 这类目录，不要按这种路径去找。

注意：日志里可能出现请求内容与内部地址。外发给支持方前，按客户数据管理要求审阅；不要外发 .env、密钥材料与初始密码文件。

8.6 修改部署配置

适用场景：访问地址变更、对象存储参数调整、运维通知渠道更换、调整资源容量、修改入口端口等安装后的配置变更。

前提：没有升级正在进行；上一次修改已生效完毕。变更前先按 8.2 节做一次备份。

操作步骤

1. 首选控制台。平台管理员进入「系统维护 › 部署配置」，在目标项选「修改」，填写新值并保存。页面分为七个分组：

1. 控制台不可用或需要脚本化时，用命令行。普通项直接写值：

# 安装主机 · root · 写入（修改访问地址，相关服务会重新加载或重启）
sudo zenova config set PUBLIC_URL <新访问地址>
echo "退出码：$?"

1. 敏感项不能写在命令行上，按提示在终端输入（不回显），或用 --value-stdin 从标准输入读取：

# 安装主机 · root · 写入（修改对象存储访问密钥，按提示输入，不回显）
sudo zenova config set LP_OBJECT_STORE_ACCESS_KEY_SECRET

1. 修改完成后，sudo zenova status 核对服务状态，并按第 7.3 节做一次真实业务调用。

可用 zenova config set 修改的 18 个键：

键名以命令的实际提示为准：写了不在列表中的键时，命令提示「<键> 不是可修改的部署配置项」，并列出全部可修改的键。

你会看到

• 控制台：提示「已保存，正在让新值生效」，完成后显示已重启的服务数量；敏感项只显示「已设置」或「未设置」，不回显原值。
• 命令行：先输出「已保存，正在让新值生效…」，生效后可能输出「已重启：…」「已更新安装记录：…」，最后一行为「修改已生效」。
• 值为空表示清除该项。

注意：对象存储方式安装后不能在线更换。 控制台提示「不支持在线修改：请备份后按新的选择重新安装，再恢复数据」。需要更换时，安排维护窗口按「备份 → 重新安装 → 恢复」处理。

注意：入口端口与绑定网卡只能在控制台「入口监听」中修改，不能用 zenova config set 改。 修改业务入口后，外部调用方与远端网关节点要改用新端口；修改管理入口后，当前页面地址失效，按页面给出的新地址访问。安装器只在首次安装时放行防火墙端口，改端口后由运维方自行调整防火墙、负载均衡与「网关 → 入口与证书」中的公开访问地址。

注意：修改「资源容量」会让控制面重启，期间控制台暂时不可用，网关请求不受影响。

注意：不要手工编辑 /opt/zenova/.env.runtime/ 与 /opt/zenova/etc/ 下的文件。 它们由安装器与配置编译生成，手改的内容会在下一次修改、升级或重新配置时被覆盖，或导致服务无法启动。/opt/zenova/.env 含主密钥，同样不要手改。

注意：使用现有服务的数据库与对象存储，其凭据轮换由客户管理员负责，「部署配置」页不提供这些依赖的凭据轮换。

8.7 root 密码与两步验证恢复、管理面访问网段应急

适用场景：root 忘记密码、两步验证设备与恢复码全部丢失；或「管理面访问网段」白名单配错，导致无法从客户网络进入控制台。

操作步骤

一、首次改密前查看初始密码

1. 尚未修改初始密码时，可再次查看初始密码：

# 安装主机 · root · 只读
sudo zenova root-password show

二、重置 root

1. root 忘记密码，或两步验证与恢复码全部丢失时执行：

# 安装主机 · root · 写入（重置 root 密码，清除两步验证并使会话失效）
sudo zenova root-password set

1. 用终端打印的新密码登录，按页面要求修改密码。平台范围开启了「强制两步验证」时，页面随后要求重新绑定两步验证（验证器应用或通行密钥），保存新的恢复码；未开启时按 6.1 节第 5–6 步重新绑定。改密与绑定各有 10 分钟时限，超时重新登录。

三、管理面访问网段应急

1. 查看当前白名单配置：

# 安装主机 · root · 只读
sudo zenova admin-network show

1. 追加一个允许访问管理控制台的网段：

# 安装主机 · root · 写入（追加管理面允许网段）
sudo zenova admin-network allow --cidr <网段>

1. 或直接关闭白名单：

# 安装主机 · root · 写入（关闭管理面网段白名单）
sudo zenova admin-network disable

1. 恢复访问后，以 root 打开「平台账号与登录 › 登录方式」，在「仅允许以下网段访问管理控制台」开关下方按正确的网段重新配置。

你会看到

• root-password show：首次改密前打印初始密码；改密后初始密码失效。
• root-password set：打印新生成的随机密码；root 原有的两步验证与恢复码被清除，root 的全部会话失效，操作写入审计记录。
• admin-network：修改约 10 秒内在所有实例生效。从安装主机本机回环地址访问控制台始终放行。

注意：root-password set 打印的新密码与初始密码一样，不得通过即时通讯、邮件或工单传递，不要录屏或截图外传。执行前确认终端没有被录屏或共享。

注意：http:// 访问地址下登录页不提供通行密钥，两步验证只能用验证器应用。

注意：这两组命令只恢复平台 root。租户管理员丢失两步验证时，由平台管理员在「租户管理」打开该租户详情，在「管理员」页签为其「重置两步验证」。

注意：「仅允许以下网段访问管理控制台」开启前，先把实施方与客户运维所在网段都加入；admin-network disable 只用于应急，恢复后应重新开启并核对网段。

能力说明

---

上一章：7. 安装验收 · 下一章：9. 增加远端网关节点