11. 清空重装与更换产品

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

本章内容：本章说明什么时候需要删除已有部署重新安装、什么时候不需要，以及确需清空时怎样先预览、再确认、出错后从哪里继续。更换产品（完整版与 Zentrix 网关互换）也只能走这条路，放在本章最后一节。读者是实施工程师与客户方系统管理员；执行本章任何写入命令前，须取得客户书面同意并安排停服窗口。

11.1 三个入口的区别

适用场景：已有一套安装，准备「重新装一下」之前，先判断要的到底是哪一种。

绝大多数情况你要的是前两个：换新版本用升级，改安装时填错的配置用重新填写配置。这两个入口都保留数据。只有确定要丢弃全部数据、从零开始时，才使用删除重装。

操作步骤

1. 只是要换版本：用新版本的安装器执行 sudo zenova upgrade <包.zpkg>，或在控制台「系统维护 › 系统更新」上传升级包。
2. 只是要改访问地址、通知渠道、资源容量等：先看控制台「系统维护 › 部署配置」或 zenova config set 能否在线修改；不能在线修改的，再用 --reconfigure。
3. 以上都不能解决、且客户同意丢弃全部数据：继续阅读 11.2 节。

你会看到

• 已完成安装的主机上直接再跑一次普通安装命令时，安装器停止并提示本机已完成安装（诊断代码 SVC_ALREADY_INSTALLED），同时给出三条去向：升级用 sudo zenova upgrade <包.zpkg>，修改配置用 sudo zenova install --reconfigure，清空重装加 --fresh。普通安装命令不会覆盖已有安装。

注意：--fresh 与 --reconfigure 互斥，不能同用。--adopt-existing（在已有平台数据上接管安装）也不能与这两者同用。

11.2 适用条件

前提：以下三条须同时满足，缺一条安装器都会拒绝清空。

以下环境不支持清空重装：

• 平台数据库或分析数据库使用现有服务；
• 对象存储使用现有 S3 兼容存储；
• 多机部署；
• Kubernetes Helm 部署；
• 远端网关节点主机（zenova install node 不使用 --fresh，节点换控制面或换令牌用 --reenroll，见第 9 章）。

注意：使用现有数据库或现有 S3 的环境确需重装时，需要客户的数据库管理员与存储管理员先自行处理原有库与桶，再按首装流程安装；这部分不由安装器执行，也不在本手册范围内。本机上的网关节点（含与控制面同机的 office-primary）会随清空一并清理；如果本机节点曾注册到另一个远端控制面，该控制面上节点会变为离线，需在其控制台退役。

11.3 先预览再确认

适用场景：任何一次清空重装的第一步。

前提：安装器、离线包、答案文件与凭据文件已放在旧安装根与业务目录之外的独立目录（如 /root/zenova-install），见 11.4 节。

操作步骤

1. 执行只读预览。

# 安装主机 · root · 只读（预览清理范围，不停服务、不删数据、不开始安装）
cd /root/zenova-install
sudo ./zenova install "$ZPKG" --fresh --dry-run

2. 逐行核对预览输出，确认列出的就是这台主机上要删除的那套部署。
3. 预览中出现「归属不明」或带风险提示的残留项时，按下面三种方式之一处理，不要手工清理：

# 安装主机 · root · 只读（导出清理计划文件，供审核）
sudo ./zenova install "$ZPKG" --fresh --dry-run --plan ./reinstall-plan.toml

# 安装主机 · root · 删除（按审核后的计划清空旧部署并重新安装）
sudo ./zenova install "$ZPKG" --fresh --plan ./reinstall-plan.toml --confirm-data-loss DELETE_EXISTING_DATA

你会看到

• 预览一次性汇总全部待清理项与拒绝项：旧部署的身份、版本与部署形态，以及服务、业务路径、独占容器、卷和网络的清理范围。
• 遇到以下情况时，预览说明具体对象并停止，处理所列对象后重新预览：

注意：严禁手写 rm -rf、docker rm、systemctl 等命令清理旧安装残留。 现场运维与远程支持一律通过 --fresh --dry-run、交互确认或计划文件处理。手工删除会让安装器无法再证明资源归属，后续预览会被拒绝，问题只会更难处理。

注意：计划文件只对生成它时的现场有效。停服后安装器会再次核对旧部署身份，若与计划不一致会以 FRESH_STATE_CHANGED 停止，此时重新执行 --fresh --dry-run 生成新的计划文件。

11.4 执行与中断处理

前提：已完成 11.3 节的预览与核对；客户已书面同意丢弃全部数据；已安排停服窗口。需要保留旧数据时，先执行 zenova backup 并用 zenova backup export 导出，并把导出的归档移到清理范围之外——清空重装不自动备份，且会删除本机全部备份。

操作步骤

1. 准备物料目录。使用与新离线包同版本的独立 ./zenova，不要使用待删除安装根里的 zenova（/usr/local/bin/zenova 指向的就是旧安装）。安装器、.zpkg、--answers 答案文件、--secret-file 凭据文件都必须放在旧安装根（默认 /opt/zenova）与业务目录之外；放在待清理目录内时，安装器会说明并停止。

# 安装主机 · root · 只读（确认物料位置与版本）
cd /root/zenova-install
ls -l ./zenova "$ZPKG"
sha256sum "$ZPKG"

2. 执行清空重装。确认词必须完整填写 DELETE_EXISTING_DATA。

# 安装主机 · root · 删除（清空旧部署后重新安装）
sudo ./zenova install "$ZPKG" --fresh --confirm-data-loss DELETE_EXISTING_DATA

3. 安装完成后按第 6 章重新完成首次登录与初始化、重新申请并导入许可证（6.4 节），再重新离机备份密钥材料并做首次平台备份——旧的密钥归档与备份对新部署无效。

你会看到

• 删除任何内容之前，安装器先核对：新包全部组件的 sha256 与大小、安装器与离线包的版本和平台、安装答案、所选能力是否齐全。任一项未通过，不会进入删除阶段，旧部署保持原样。组件摘要用于发现下载损坏，不代表签名校验。
• 通过后依次执行：停止旧服务和容器并再次核对旧部署身份 → 清理属于该安装的服务、数据路径、容器、独占卷和网络（保留 Docker 镜像与系统账户）→ 按首装流程安装新包并完成装后验收。
• 完成输出与首装相同：新的 root 初始密码、访问地址与「下一步」。

中断后从哪里继续

注意：在旧部署已清理、新安装未完成的状态下再次带 --fresh 并确认删除，表示重新清空本机数据，不是继续上次安装。

注意：清空重装会生成新的部署标识。原许可证、原 root 密码、原两步验证绑定、原密钥材料与备份全部失效；原有租户、成员、模型供应商、API 密钥都需要重新创建，调用方需要换用新的 API 密钥。

11.5 更换产品

适用场景：已安装 Zentrix 网关，要改装完整版；或反过来。

前提：两个产品使用同一套安装命令，但产品在安装时锁定，安装后不能原地更换。两者互换只能清空重装，11.2 节的适用条件同样适用。

操作步骤

1. 向客户说明后果并取得书面同意：原有数据全部删除；原许可证失效，需在新产品上重新导出授权请求、重新申请许可证。
2. 从下载站重新选择目标产品，下载目标产品的安装器与离线包（第 2 章）。离线包文件名里的产品字段应与目标产品一致。
3. 用目标产品的安装器按 11.3 节预览、11.4 节执行清空重装。
4. 按第 6 章重新完成初始化与许可证导入，按第 7 章重新验收。

你会看到

• 不做清空、直接用另一个产品的安装器执行普通安装时，安装器停止并提示「本机已安装<已装产品>，该安装程序为<另一产品>版，请使用<已装产品>版的安装包」。这表示产品已锁定：要么换回已装产品的安装包，要么按本节清空重装。
• 输出中带诊断代码 ANS_EDITION_LOCKED（版本形态已锁定）时含义相同，处理办法是执行 zenova install <安装包> --fresh 后重新选择。
• 安装器与离线包分属不同产品时，提示「安装包与安装程序不属于同一版本：安装程序为…版，安装包为…版」，须换用同一产品的安装器与离线包。

注意：只是想多启用或停用某项能力（如知识库）时，不需要换产品，也不需要清空重装：在控制台「系统更新」页启用已随离线包带来的能力，或用 --reconfigure 重新选择能力。目标能力不在本产品中（安装器提示「…不含「…」能力，请从 --with 中去掉」）时，才需要考虑更换产品。

能力说明

上一章：10. 备份、恢复与升级 · 下一章：12. 故障排查与提交支持