10. 备份、恢复与升级

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

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

本章内容：本章说明平台备份覆盖哪些数据、如何创建与转存备份、如何从备份恢复，以及升级前要准备什么、如何在控制台或命令行升级、升级后出现问题时如何处理。恢复会改变当前运行的数据，执行前务必读完对应小节的「注意」。读者是客户方系统管理员与实施工程师。

10.1 备份范围

zenova backup 与控制台「备份与恢复」页使用同一套备份，只备份由安装器部署和管理的内容。

备份保存在 /opt/zenova/data/backups/<备份标识>/。所需空间估算：

所需空间 ≈ 本机 PG 数据目录 + 本机对象数据目录 + 1 GiB

操作步骤

1. 估算一次备份所需空间。

# 安装主机 · root · 只读（估算备份所需空间）
du -sh /opt/zenova/data/*
df -h /opt/zenova/data

1. 对照 du 输出中本机 PostgreSQL 与本机对象存储的数据目录大小（目录名以实际输出为准），加 1 GiB，与 df 的剩余空间比较。

注意：两类「不纳入」的数据必须在交付前与客户书面约定由谁负责、多久备份一次，并约定恢复时与平台备份恢复到同一时间点。只恢复平台备份而现有 PG 或 S3 不同步恢复，会出现数据不一致。

注意：密钥服务材料不在平台备份内。在另一台主机上恢复时，没有原主机 /etc/zenova/secret-service/ 的离机备份，平台保存的全部凭据无法解密。

10.2 创建、导出与转存

操作步骤

1. 创建一次备份，记录屏幕输出的备份标识（形如 zb-20261020T020000Z-1a2b3c4d）。

# 安装主机 · root · 写入（创建备份）
sudo zenova backup

1. 列出本机备份，核对刚才的标识。

# 安装主机 · root · 只读
sudo zenova backup list

1. 导出为 .zbackup 归档。

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

1. 把归档与摘要转存到与安装主机不同故障域的受控位置（不同主机、不同机房或离线介质），登记保管位置、保管人、摘要与日期；确认复制成功后删除本机导出文件。
2. 不再需要的本机备份按标识删除。

# 安装主机 · root · 删除（删除一个本机备份，不可找回）
sudo zenova backup delete <备份标识>

命令行与控制台对照（控制台为平台管理控制台「系统维护」的「备份与恢复」页签）：

你会看到

• 命令行备份完成后打印备份标识。
• 控制台点「立即备份」后提示「备份已开始，完成后会出现在列表中。」，任务依次经过「准备」「安装状态」「平台数据库」「分析数据库」「对象存储」「校验」。
• 「备份列表」显示「创建时间」「版本」「发起人」「大小」「包含内容」；未纳入的组件显示为「（未纳入）」及原因。
• 导出文件权限为 0600。

注意：导出文件未压缩、不另加密、含主密钥。拿到它的人可以解开平台保存的凭据。按最高密级保管，不得通过即时通讯、邮件或工单传递。

注意：只保存在安装主机上的备份不算备份。主机磁盘损坏或执行清空重装（会删除全部本机备份）时，本机备份随之丢失。

注意：备份由页面或命令行手动触发，平台不提供定期自动备份与过期清理；定期备份、异地转存和清理由客户按运维流程安排。已有备份、恢复或升级在进行时，新的备份会被阻止。

10.3 恢复

适用场景：数据被误删或损坏，需要把平台回到某次备份时的状态；或在演练主机上验证备份可用。

前提：同时满足以下条件，否则恢复被拒绝。

注意：恢复会用备份覆盖当前数据，备份之后写入的全部数据（配置变更、调用记录、用量、审计等）将永久丢失，无法撤销。 恢复前必须先对当前环境再做一次备份并导出转存，作为恢复失败或选错备份时的退路。

注意：现有 PostgreSQL 与现有 S3 不在恢复范围内。使用它们时，由对应管理员按其备份机制把数据恢复到与平台备份相同的时间点，否则平台数据前后不一致。

操作步骤

1. 先为当前环境再做一次备份，并导出转存（见 10.2 节）。

# 安装主机 · root · 写入（恢复前的保护性备份）
sudo zenova backup
sudo zenova backup list
sudo zenova backup export <当前备份标识> --output /root/zenova-install/<当前备份标识>.zbackup

1. 停止控制面组服务。先用 zenova status 查看服务名，未启用的组件跳过。

# 安装主机 · root · 写入（停止控制面组，控制台与管理接口不可用）
sudo zenova status
sudo zenova stop zenova-worker
sudo zenova stop zenova-runtime-store
sudo zenova stop zenova-control-plane

1. 执行恢复。参数可以是备份标识，也可以是 .zbackup 归档文件（先导入再恢复）。提示时输入确认词 RESTORE。

# 安装主机 · root · 写入（用备份覆盖当前数据，不可撤销）
sudo zenova restore <备份标识或 .zbackup 文件>

1. 恢复完成后、启动控制面组之前，重启密钥服务、权限服务与自带对象存储，使它们加载恢复后的数据。未使用自带对象存储时去掉 rustfs。

# 安装主机 · root · 写入（重启依赖服务，加载恢复后的数据）
systemctl restart spicedb secret-service rustfs
systemctl status spicedb secret-service rustfs --no-pager

1. 启动控制面组。

# 安装主机 · root · 写入（启动控制面组）
sudo zenova start zenova-control-plane
sudo zenova start zenova-runtime-store
sudo zenova start zenova-worker
sudo zenova status

1. 核对：登录控制台；确认网关节点在线；在「部署配置 › 最近一次验收」执行一次验收；按第 7.3 节完成一次真实调用，并核对模型、路由、权限、审计与告警配置与备份时一致。
2. 记录可恢复到的时间点、恢复耗时、缺失内容与需要重建的外部依赖数据。

你会看到

• zenova restore 先要求输入 RESTORE，输入其他内容时不执行；完成时的输出以实际输出为准。
• 控制台发起恢复时（备份行「恢复」→「从备份恢复」→ 输入 RESTORE →「开始恢复」），页面显示「正在恢复」，依次经过「停止控制台服务」、各组件恢复和「启动控制台服务」，完成后提示「恢复已完成。」。
• 控制面仍在运行，或有升级、备份任务进行时，恢复被拒绝。

注意：恢复过程中旧数据在新数据完整就位前保留；但一旦恢复完成，被覆盖的数据只能靠步骤 1 的保护性备份找回。

注意：恢复到另一台主机时，先按相同版本、相同产品与形态完成安装，再把原主机 /etc/zenova/secret-service/ 的离机备份放回原位，然后执行上述步骤。覆盖生产环境前，先在隔离的演练主机上完成一次恢复演练。

10.4 升级前准备

操作步骤

1. 阅读目标版本的发布说明，确认变更内容、已知问题与是否涉及数据库变更。
2. 确认可以从当前版本直接升级到目标版本。当前版本早于目标版本要求的「可直接升级的最低版本」时，先升级到中间版本，再升级到目标版本。
3. 确认当前已启用的全部能力。目标版本离线包必须包含当前已启用的全部能力，缺任何一项的组件，升级前检查不通过。

# 安装主机 · root · 只读（查看当前版本与服务）
sudo zenova status

也可在控制台「系统维护 › 系统更新」的「当前版本」核对版本与各能力状态。

1. 按当前产品、平台与已启用的全部能力，从下载站下载目标版本的安装器与离线包，按第 2 章核对 SHA-256，拷入可移动介质带到现场。平台不提供在线获取升级包，升级包一律在「系统更新」页现场上传或用命令行执行。
2. 有远端网关节点时，确认目标版本离线包包含这些节点所在系统的节点包：包含时，控制面升级会在控制台切换前自动逐台升级在线节点（见 10.5 节）；不包含时（例如节点与控制面平台不同），升级前检查「网关节点」一项不通过，须先按第 9 章「升级节点」逐台手工升级，已升到目标版本的节点会被跳过。节点升级时会被排空，排空不改 DNS 或负载均衡：入口池只有一个节点时，它升级期间公开入口不可用。
3. 完成一次备份，导出并转存到不同故障域，记录备份标识（见 10.2 节）。
4. 与客户约定维护窗口，通知控制台使用者。

注意：升级前检查会判定本次走「快速切换」还是「停机升级」，并在「系统更新」页写明影响。快速切换时控制台切换约数秒，期间操作稍慢或短暂不可用，网关调用不受影响；需要停机升级时（大表变更超出切换窗口预算、有待执行的分析数据库停机迁移等），升级器停止旧服务完成迁移，期间控制台与中心节点的网关调用都不可用；远端网关节点此前已升到目标版本，停机期间按已下发的配置照常服务（有节点离线或未升到目标版本时停机迁移不开始），预检显示的「约 600 秒」是固定提示值，实际时长随数据量而定。停机升级只支持单机部署。维护窗口按检查给出的影响安排。

注意：平台不提供回退命令，升级完成后要回到旧版本只能恢复升级前的备份（见 10.6 节），这份备份不能省略。

注意：当前版本启用了「运维观测」时，升级到不再提供该能力的版本前，须先在当前版本的「系统维护 › 系统更新」停用「运维观测」，否则升级前检查会拒绝升级：「部署配置」一项判为未通过，展开「查看技术详情」（命令行 zenova upgrade 为「详情：」一行）可见提示「能力『运维观测』已在新版本中退役，请先在当前版本的『系统更新』页停用该能力，再升级」；「能力包齐全」一项同时提示升级包缺少已启用的能力，二者是同一原因，按提示停用即可，不需要另找升级包。升级完成后，可手工删除 <安装目录>/data/ 下的 prometheus、alertmanager、grafana、loki、tempo 目录以回收磁盘空间。

10.5 升级

前提：已完成 10.4 节全部准备，且没有其他升级在进行。

在控制台升级

操作步骤

1. 以 root 打开「系统维护 › 系统更新」。
2. 上传 10.4 节准备好的 .zpkg。上传中断后可「继续上传」。
3. 上传完成后系统自动执行升级前检查。逐项核对结果；未通过时按提示处理，处理后点「重新检查」。

控制台上显示的检查项名称与数量以实际界面为准，可能还包括基础设施版本、数据库变更耗时、版本顺序等项。由安装器部署的 PostgreSQL 或 ClickHouse 版本不满足要求时，在维护窗口执行 sudo zenova infra upgrade <基础设施包> 后重新检查；使用现有数据库时由数据库管理员升级。

1. 全部通过后点「升级」，在弹窗中输入 root 密码确认。
2. 观察进度，直到升级结束。不要关闭服务器。
3. 升级完成后：在「升级历史」核对版本、结果、用时与操作人；在「部署配置 › 最近一次验收」点「立即验收」；按第 7.3 节完成一次真实调用。

你会看到

• 升级依次经过九个阶段，不适用的阶段跳过：

• 有远端网关节点时，「网关节点」阶段在控制台切换之前逐台升级在线节点：每台先排空、换包、通过入口自检后回到入口池，进度显示如「网关节点 gw-sh 换包中」。任一节点升级失败时控制台不切换，结果为「未成功，已恢复到原版本」，并列出失败节点与原因；失败节点自动切回旧版本继续服务，已升级的节点保持新版本。
• 检查结果里写明本次影响：快速切换时控制台切换约数秒、网关调用不受影响；停机升级时控制台与中心节点的网关调用在升级期间不可用、远端网关节点照常服务（见 10.4 节）。
• 结果为「已完成」「已完成，部分项需处理」「未成功，已恢复到原版本」或「需要人工处理」之一（以实际界面为准）。

在命令行升级

操作步骤

1. 在安装主机暂存目录解压目标版本的安装器，用新版本安装器执行升级。

# 安装主机 · root · 写入（升级到目标版本）
cd /root/zenova-install
tar xzf <目标版本安装器>.tar.gz
sudo ./zenova upgrade <目标版本离线包>.zpkg
echo $?

1. 按退出码判断结果；完成后同控制台第 6 步核对。

你会看到

• 命令依次完成上传、升级前检查与切换，持续显示进度。与控制台升级是同一个流程、同一条升级记录。
• 退出码：

注意：必须使用新版本的安装器执行 zenova upgrade。已安装的旧版本程序可能无法识别新版本的升级包。

注意：同一时间只能有一个升级在进行。控制台与命令行发起的升级互相可见，不要在一处升级进行中从另一处再次发起。

10.6 升级后出现问题

适用场景：升级失败，或升级完成后新版本出现无法接受的问题。

平台不提供回退命令，处理方式取决于升级结果：

注意：恢复升级前的备份会丢失备份之后写入的全部数据。 恢复要求本机版本与备份所在版本一致，先按第 11 章把本机安装到原版本，再按 10.3 节恢复。这也是 10.4 节要求升级前必须完成备份并转存的原因。

操作步骤

1. 查看当前版本与最近一次升级的结果。

# 安装主机 · root · 只读
sudo zenova status
sudo zenova upgrade status

1. 按上表选择处理方式。处理完成后，按第 7.3 节完成一次真实调用，并在「部署配置 › 最近一次验收」执行一次验收。

注意：有远端网关节点时，处理后在节点列表核对各节点状态与版本，以实际输出为准。

能力说明

---

上一章：9. 增加远端网关节点 · 下一章：11. 清空重装与更换产品