使用 zenova 安装器与 .zpkg 离线包在单台 Linux 或 macOS 主机上安装、升级、恢复与清空重装 ZStack Zenova

ZStack Zenova 单机生产版安装手册

本手册说明 ZStack Zenova 在单台主机上的安装与维护，适用于以下场景：

• 安装在一台 Linux 服务器（systemd）或一台 macOS 主机（launchd）上。
• 客户现场可以没有外网，安装所需的全部内容都在安装器与离线包中。

多副本与 Kubernetes 形态请按对应的实施说明部署，不在本手册范围内。

1. 安装所需的两个文件

Linux x86_64（systemd）单机安装优先使用下载站「一体化安装包」页签的整包：一个 .tar 内含安装器、该产品版本可单机安装的全部能力的离线包与所需组件包，解包后执行页面给出的一条安装命令即可（命令形如 sudo ./zenova install --with <能力> ./<离线包>.zpkg）。

需要其他平台或只装部分能力时，在定制站选择平台、版本和需要的能力后，下载两个文件：

文件名中写明了版本与平台（如 linux-amd64、linux-arm64、macOS 对应的平台名）。安装器与离线包的版本和平台必须一致。

定制站不收集任何凭据和许可证。数据库密码、对象存储密钥等凭据只在现场安装时录入；许可证在安装完成后于控制台导入。

2. 安装前准备

2.1 主机要求

选择「托管智能体」能力时，主机还需要已安装容器运行时。

2.2 数据依赖

安装时，PostgreSQL、ClickHouse 和对象存储可以分别选择「由我们部署」或「使用现有」：

2.3 能力

离线包可以包含多项能力，安装时可以选择本次启用哪些：

未在本次启用的能力保留在本机，以后可以在控制台「系统更新」页直接启用，无需重新下载。

语义缓存不是单独安装的能力：它随核心提供，不在本机部署任何模型。安装完成后，租户管理员在「全局设置 › 默认模型」中设置「语义缓存向量模型」和「语义缓存重排模型」，再在路由规则中按规则开启。使用 OceanBase 作为平台数据库的部署不支持语义缓存。

2.4 访问地址与本机监听端口

访问地址是用户在浏览器里打开控制台、调用方访问模型接口所用的地址（如 http://10.0.0.5:12345）；本机监听端口是安装主机上访问入口实际监听的端口。两者的关系如下：

访问地址的端口与本机监听端口不同时，必须由前置代理、NAT 或 TLS 入口把访问地址的端口转发到本机监听端口，否则访问地址打不开。确认页同时列出「访问地址」与「本机监听端口」，两者不同时会给出提示。本机监听端口被占用时安装器报出占用进程，请停止该进程或改用其他端口。

管理入口（控制台）缺省与业务入口共用同一个本机监听端口；需要把控制台放到单独端口时，加 --admin-entry-port。

3. 上传安装文件

在服务器上选择独立的、允许执行程序的暂存目录；以下示例使用 /tmp，若其所在文件系统禁止执行，请改用其他可执行目录并替换示例路径。不要在安装根的父目录（如 /opt）直接解压：压缩包会解出名为 zenova 的文件，占用默认安装目录 /opt/zenova。

scp zenova-<版本>-linux-amd64.tar.gz zenova-<版本>-linux-amd64-xxxxxxxx.zpkg [email protected]:/tmp/

ssh [email protected]

cd /tmp

依次上传两个文件到服务器的同一目录、登录服务器并进入该目录；将示例中的账号与地址换成实际值。

无需手工校验文件：安装器启动后会先检查离线包大小上限，再按发布清单逐个校验组件的 sha256 与大小（只用于发现下载损坏）。

4. 交互式安装

tar xzf zenova-<版本>-linux-amd64.tar.gz

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg

先解压安装器，再执行安装命令。已有安装需要清空重装时，使用 11.7 节 的 --fresh 流程。

原生中心安装的主机检查按 2.1 节的建议容量检查安装目录所在卷。未显式传入 --install-dir 时，容量不足会阻断安装（诊断代码 HOST_DISK_LOW），提示安装到空间更大的卷；Linux 主机同时列出本机可用空间最大的三个可作为安装目录的挂载点，macOS 只给出提示。

显式传入 --install-dir <目录> 时，建议容量不足只告警并直接继续，无需额外确认；显式传入 --install-dir /opt/zenova 也适用。通过 ZENOVA_INSTALL_DIR、已安装 CLI 链接或默认值自动识别目录不属于显式指定。其他检查项仍按原有要求阻断；实际空间不足仍可能导致解包、安装或后续运行失败。

默认安装目录是 /opt/zenova。该分区空间不足时，可将程序、数据、版本与解包暂存放到持久数据盘，并按需为规范日志选择独立目录：

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg --install-dir /data/zenova --log-dir /logs/zenova

目录必须是绝对路径；安装根只支持字母、数字、点、下划线、短横线和斜杠，不支持空格、引号及展开字符。独立日志目录必须位于安装根外，首次使用时为空；日志文件、归档和归属账本一起保存在该目录。Linux 不支持把安装根或持久日志根放到 /tmp、/var/tmp、/home、/root、/run/user、/usr、/etc、/boot，这些位置会被服务沙箱隔离或设为只读。安装目录需要允许执行程序，日志目录所在文件系统可以禁用执行。

后续 zenova status、doctor、logs、upgrade 和备份恢复命令会识别安装器注册的目录；使用独立下载的安装器时也可显式传 --install-dir。续装、重新配置和升级保留日志目录，不能通过换参数自动搬迁既有安装或日志。一台主机仍只允许一套中心安装。

未指定 --log-dir 时，首次安装的规范日志写入安装根下的 <服务名>/logs/；续装沿用已保存的配置。默认按天或 500 MiB 分片、保留 30 天。macOS 的有界原始捕获缓冲仍位于安装根；系统 journal、服务注册文件和密钥服务的系统目录遵循原生系统约定。

macOS 主机使用对应平台的安装器与离线包，命令相同。

在开始安装（4.9 节）之前，安装器不写入任何文件、不创建任何服务；任一步骤输入 q 退出时，本机不会留下任何内容。

4.1 验证安装包

安装器检查离线包大小上限，并按发布清单校验全部组件的 sha256 与大小（只用于发现下载损坏，不是信任机制）。验证失败时提示「安装包校验失败，请确认是 Zenova 官方安装包」并退出。离线包与本机平台不符时，提示重新获取对应的离线包。

4.2 主机检查

安装器一次性执行全部装前检查（CPU 架构、内存、磁盘空间、系统服务托管、可执行权限与安全模块、系统时间、待绑定端口等），按「阻断项」和「提示项」汇总展示结果与诊断代码（如 I-PORT-IN-USE、I-EXEC-DENIED）。所有未通过项目会同时列出原因与下一步处理办法，不会因第一项失败就中断其余检查；有阻断项时，处理后按回车重新检查，输入 q 退出；只有提示项时直接继续。代码含义可查阅安装与运维诊断代码。

4.3 选择能力

列出离线包中的全部能力，默认全选。输入编号切换选择，回车完成。核心能力始终安装。

4.4 确认预填配置

在定制站预填的配置分两级确认：

• 一般项（访问地址、依赖的部署方式、对象存储模式、通知渠道类型）合并列出，回车一次确认，输入 n 修改。
• 访问地址类（现有 PostgreSQL、ClickHouse、对象存储的地址，通知渠道地址）逐项显示并标注「来自定制站，未签名」，每项必须输入 y 才能确认；拒绝后当场改填。

4.5 补充未预填的配置

定制站未预填的项目（访问地址、各依赖的部署方式、对象存储、通知渠道）由安装器逐项询问，格式错误时当场重问。访问地址带非 80 端口时，安装器再问「访问地址前面是否有代理或 NAT 转发」：选「没有」，本机监听该端口；选「有」，再填写代理或 NAT 转发到的本机监听端口。访问地址为 https:// 时直接询问 TLS 入口转发到的本机监听端口（回车为 80）。规则见 2.4 节。

4.6 录入凭据并检测依赖

选择使用现有 PostgreSQL 时，安装器询问实例的访问地址、管理员账号与加密方式（缺省明文），再询问该管理员账号的密码（输入内容不显示）。管理员账号须为超级用户：安装器在安装过程中用它创建平台所需的角色、lobsterpool、spicedb、zenova_secret 三个库以及扩展，无需数据库管理员另行执行脚本。管理员密码只在安装过程中使用，不写入任何文件与日志；安装完成后，平台只使用自己的角色访问数据库。使用现有 ClickHouse、对象存储时，同样录入账号与密钥。

录入后安装器立即检测，检测过程不做任何写入：PostgreSQL 的管理员账号能否登录、是否为超级用户、服务器是否提供所需扩展（vector 0.7.0 及以上、pg_trgm、uuid-ossp、pgcrypto、btree_gist）；ClickHouse 的版本、宏和建库权限；对象存储的读、写、删。未通过的项目逐条说明缺少什么、由谁处理；修正后按回车重新检测，输入 q 退出。

4.7 运维通知测试

向所填通知渠道发送一条测试消息，请确认已收到。未收到时可修正渠道后重新发送。

4.8 确认安装内容

确认页列出本次要安装的能力、全部配置（含「访问地址」与「本机监听端口」）与磁盘空间。访问地址的端口与本机监听端口不同时，确认页提示需要前置代理或 NAT 转发。确认后开始安装。

4.9 安装

安装器依次完成：数据层（如由我们部署）、控制面（本机的中心网关节点随控制面一并启动）、已选能力，最后执行装后验收。

• 安装中断或某一步失败时，屏幕会停在失败的步骤并给出原因与下一步。处理后重新执行同一条 sudo ./zenova install … 命令，将从断点继续。

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg --reconfigure

配置填写有误时执行此命令，安装器会回到「选择能力」一步，并带入上次的答案。--reconfigure 保留已有数据，不会清空安装。

4.10 安装完成

安装器打印验收结果、用户名 root 与初始密码，随后打印：

• 本机直接访问：按本机监听端口拼出的地址，不经任何前置转发，用于在内网直接打开控制台或排查访问地址问题；
• 访问地址：安装时填写的地址，日常使用与对外提供服务的地址；
• 下一步：登录控制台，按提示修改初始密码；平台安全策略要求两步验证时，还需绑定两步验证（见第 6 节）。

请立即保存初始密码。 首次登录修改密码之前，可在安装主机上执行 sudo zenova root-password show 再次查看；修改之后无法再查看。

5. 非交互安装

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg --answers answers.toml --secret-file secrets.toml --with core,doc_parse

批量或自动化安装时，用答案文件代替问答，效果与交互安装一致。

使用现有服务时，非交互安装必须通过 --secret-file 提供凭据。使用现有 PostgreSQL 时，答案文件写访问地址与管理员账号，凭据文件写该账号的密码：

# answers.toml
[postgres]
external = { host = "10.0.0.5", port = 5432, user = "postgres" }

# secrets.toml（权限 0600）
pg_admin_password = "…"

6. 首次登录

1. 用浏览器打开安装完成时打印的访问地址；访问地址打不开时，先用「本机直接访问」地址确认服务正常，再检查前置代理或 NAT 的转发（见 2.4 节）。
2. 以 root 和初始密码登录，按页面列出的口令规则修改初始密码。新装部署的平台范围默认不强制两步验证，改密后直接进入平台管理控制台；平台安全策略开启了「强制两步验证」时，登录页随后要求绑定两步验证（验证器应用或通行密钥），使用验证器应用时保存页面给出的恢复码。修改密码与绑定两步验证各有 10 分钟时限，超时后重新登录即可。客户要求平台账号必须使用两步验证时，root 先在个人设置「账号安全」中绑定两步验证并以两步验证重新登录，再在「平台账号与登录 › 登录会话 › 安全策略」中开启「强制两步验证」（见「身份源与登录安全」专题第 4 节）。
3. 如需启用受许可证控制的能力，由租户管理员在「管理控制台 → 系统设置 → 全局设置 →「授权许可」页签」导入许可证（许可证按租户导入，平台管理员不管理许可证）；未被许可证覆盖的能力显示为「许可证未包含」，导入后自动可用。
4. 打开「平台 → 网关」，确认中心节点（office-primary）在线。
5. 打开「系统更新」，确认当前版本、本机形态与各能力状态。
6. 添加模型供应商、创建租户，开始使用。

忘记初始密码时，在安装主机上执行 sudo zenova root-password show 查看（仅在首次修改密码之前有效）。root 忘记密码，或 root 的验证器与恢复码同时丢失时，在安装主机上重置：

sudo zenova root-password set

该命令生成新的初始密码并直接打印，同时清除 root 的两步验证并让 root 的全部会话失效；再次登录时同样需要修改密码，平台安全策略要求两步验证时还需重新绑定两步验证。详见「身份源与登录安全」专题。

7. 安装目录

程序与数据默认位于 /opt/zenova，版本程序按版本存放在安装根的 releases/ 下。指定 --install-dir 后，下文以 /opt/zenova 举例的产品路径应使用实际安装根。本机服务名均以 zenova- 开头，例如 zenova-control-plane、zenova-edge；以 zenova status 列出的名称为准。

凭据由平台的密钥服务保管，不以明文写入安装目录。请将安装目录纳入主机备份范围，并按第 10 节定期执行 zenova backup。

8. 日常运维命令

以下命令均在安装主机上以 root 执行，不依赖控制台是否可用。

<服务> 为完整服务名，例如：

sudo zenova restart zenova-control-plane

查看服务日志：Linux 主机使用 journalctl -u <服务名>；macOS 主机查看 /opt/zenova 下的日志目录。

9. 升级

9.1 在控制台升级

平台 root 打开「系统更新」页，上传与本机同产品版本、同平台的升级包（平台不提供在线获取，升级包由交付人员现场上传）。

上传后系统自动执行升级前检查，全部通过后点击「升级」并输入 root 密码确认。升级进度、结果与历史都在本页显示。检查结果写明本次影响，有两种：

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

有远端网关节点时，升级在控制台切换之前逐台升级在线节点（先排空、换包、入口自检通过后回到入口池）。升级包不含某个在线节点所在系统的节点包时，升级前检查「网关节点」一项不通过，须先按网关节点 › 升级手工升级该节点。节点排空不改 DNS 或负载均衡。

升级只能前滚，升级前请按第 10 节备份并把归档转存到本机以外。

9.2 在命令行升级

sudo zenova upgrade ./zenova-<目标版本>-linux-amd64-xxxxxxxx.zpkg

命令将升级包交给本机升级服务，依次完成上传、升级前检查和切换，并持续显示进度。与控制台升级是同一个流程、同一条升级记录；已有升级在进行时，命令会提示发起人与发起时间后退出。

本机升级服务的版本早于升级包时（例如控制台上传后提示“发布清单版本不受支持”或“升级包的目标版本 zenova 二进制无效”），请解压与升级包同一版本、同一产品版本的安装包，用其中的程序执行：

sudo ./zenova upgrade ./zenova-<目标版本>-linux-amd64-xxxxxxxx.zpkg

命令先核对升级包与安装程序、本机已安装的产品版本一致，再由新程序接管本机升级服务，随后照常升级；接管任一步失败时恢复原升级服务，本机不发生变化。这一次升级完成后，以后的升级恢复在控制台进行。

9.3 升级失败与回退

没有回退命令。升级在数据库变更提交之前失败的，系统自动恢复到原版本（结果「未成功，已恢复到原版本」），无需处理。升级完成之后要回到旧版本，只能升级到修复版本，或在原版本上用 zenova restore 恢复升级前的备份（见第 10 节），因此升级前必须备份并把归档转存到本机以外。

9.4 基础设施升级

升级前检查提示由我们部署的 PostgreSQL 或 ClickHouse 版本不满足要求时，请在维护窗口执行：

sudo zenova infra upgrade <基础设施包>

完成后回到「系统更新」页点击「重新检查」。使用现有数据库时，请联系数据库管理员升级。

9.5 已退役的能力

本版本不再提供「运维观测」能力（随包的指标、链路、日志与告警观测组件）。平台运行状况在「运行监控」页查看，告警由平台内置的告警引擎判定，指标、链路与日志的对外导出通过「集成与导出」页按需提供。

当前版本启用了「运维观测」时，升级前检查会拒绝升级：「部署配置」一项判为未通过，展开「查看技术详情」（命令行 zenova upgrade 为「详情：」一行）可见提示「能力『运维观测』已在新版本中退役，请先在当前版本的『系统更新』页停用该能力，再升级」；「能力包齐全」一项同时提示升级包缺少已启用的能力，二者是同一原因，按提示停用即可，不需要另找升级包。请按以下顺序处理：

1. 在当前版本的「系统更新」页停用「运维观测」。
2. 重新上传升级包或执行 zenova upgrade，升级前检查即可通过。
3. 升级完成后，可手工删除原观测组件的数据目录，以回收磁盘空间：<安装目录>/data/prometheus、<安装目录>/data/alertmanager、<安装目录>/data/grafana、<安装目录>/data/loki、<安装目录>/data/tempo。

10. 备份与恢复

10.1 备份

sudo zenova backup

完成后打印备份标识，例如 备份完成：zb-20261009t020000z-1a2b3c4d。备份写入 /opt/zenova/data/backups/<备份标识>/，内容包括：

• 安装状态与部署配置（含主密钥，请妥善保管备份文件）；
• 由我们部署的 PostgreSQL 与 ClickHouse 数据；
• 本机目录形式的对象存储。

使用现有 PostgreSQL 或 S3 对象存储时，这两部分不纳入本机备份，请纳入数据库管理员与存储管理员的备份体系。控制台「备份与恢复」页与本命令使用同一套备份。

sudo zenova backup list

sudo zenova backup export zb-20261009t020000z-1a2b3c4d --output /data/zenova-backup.zbackup

需要把备份拷到别处或重装后恢复时，先列出备份，再用实际的备份标识导出为归档文件。

10.2 恢复

恢复会覆盖当前数据，备份之后写入的数据将丢失。只能恢复同一版本、同一部署形态与平台的备份；版本不同时，先把本机安装或升级到备份所在的版本再恢复。

1. 用 zenova status 查看服务名，并用 zenova stop <服务> 停止控制面服务。控制面仍在运行、或有升级与备份任务正在进行时，恢复会被拒绝。
2. 执行恢复，并在提示时输入确认词 RESTORE。参数可以是备份标识，也可以是 .zbackup 归档文件（先导入再恢复）：

   sudo zenova restore zb-20261009t020000z-1a2b3c4d

1. 恢复完成后，用 zenova start <服务> 启动服务。

11. 常见问题

11.1 提示「安装包校验失败」

安装器或离线包不完整、下载损坏，或安装器与离线包的版本、平台不一致。请从定制站重新下载对应文件。

11.2 主机检查提示端口被占用

检查结果会写明占用端口的进程。

• 本机监听端口（访问入口）被占用：访问地址依赖这个端口，安装器不会自动更换。停止占用进程后按回车重新检查；或输入 n 重新填写访问地址与本机监听端口。非交互安装直接报错退出，处理后重新执行，或用 --business-entry-port 改用其他本机端口（此时需前置转发，见 2.4 节）。
• 平台内部服务的端口被占用：安装器自动改用下一个空闲端口并逐条说明，无需处理。

11.3 依赖检测未通过

按提示逐项处理：使用现有 PostgreSQL 时，确认管理员账号与密码正确、该账号为超级用户，且服务器已安装所需扩展并满足版本要求；使用现有 ClickHouse 时，确认版本与宏定义；使用现有对象存储时，确认密钥对存储桶具有读、写、删权限。

11.4 安装中途失败或需要远程排查

屏幕会输出完整报告，每条失败均带有稳定的诊断代码（如 I-EXEC-DENIED、D-PG-AUTH）和下一步处理建议。普通安装失败时，处理后重新执行原安装命令，已完成的步骤会跳过。如需向远程支持反馈，请执行 sudo zenova doctor（或复制当前检查报告中的代码与摘要）发给支持人员，无需截取整屏终端图片。清空重装的失败处理见 11.7 节，不能将清理中断当作普通安装断点重跑。

11.5 提示「本机已完成安装」

本机已安装完毕。如需修改安装时的配置，加 --reconfigure 重新执行安装命令并保留数据；日常配置变更请在控制台「部署配置」页完成。确需删除旧数据并重新首装时，使用 11.7 节的 --fresh 流程。

11.6 控制台无法访问

1. 在安装主机上执行 sudo zenova status，确认各服务状态。
2. 对未运行的服务执行 sudo zenova restart <服务>，并查看该服务日志。
3. 本机正常但外部无法访问时，检查主机防火墙、云安全组和域名解析。

控制面不可用期间，网关节点仍按最近一次配置继续服务。

11.7 清空重装

每个版本声明可直接升级的最低版本；本机版本低于该下限时，升级前检查提示需要先升到中间版本或重装，后者需要安排停服窗口。需要在原主机删除旧数据并重新首装时，使用 zenova install <包.zpkg> --fresh；普通安装命令不会覆盖旧安装。

--fresh 与 --reconfigure 互斥。重装会删除旧部署的业务数据、配置与身份，不自动备份；如需保留旧数据，请先按第 10 节备份并将归档移到清理范围之外。重装后按第 6 节完成首次登录与初始化。

请使用与新离线包同版本的独立 ./zenova，将安装器、.zpkg、--answers 答案文件与 --secret-file 凭据文件放在旧安装根和业务目录之外（如单独的可执行暂存目录），不要使用待删除安装根中的 zenova。

支持范围

• 单机裸机安装：Linux systemd 或 macOS launchd，默认安装根目录 /opt/zenova。
• Linux 旧默认 Docker 安装：安装根目录 /opt/lobsterpool，清理后迁移到新的裸机安装；这是一次性迁移入口。
• 原生与旧 Docker 安装并存时，两套本机资源均纳入清理；没有安装根但存在正式业务目录或密钥残留时，也会列入预览。
• 本机网关节点（包括旧安装器创建的同机节点和独立安装的节点）一并清理：停止并移除 systemd/launchd 单元、历史单元、drop-in、启用链接，以及节点的程序、配置和数据目录；保留系统账户。

本流程由控制面完整安装命令执行；zenova install node、多机与 Helm 安装命令不使用 --fresh。节点注册到远端控制面也不阻止本机清理：远端控制面上该节点会变为离线，需在其控制台退役。

外部 PostgreSQL、ClickHouse 或对象存储不会被删除或复用，新安装会生成新身份。检测到外置数据依赖、清理范围外的共享资源、损坏或矛盾的归属证据、符号链接逃逸，或安装输入位于待清理目录内时，安装器会说明具体对象并停止；请处理所列对象后重新预览。

先预览，再确认（交互逐项确认或计划文件）

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg --fresh --dry-run

先执行只读预览。该命令一次性汇总全部待清理项与拒绝项，预览旧部署身份以及服务、业务路径、独占容器、卷和网络的清理范围；不停止服务、不删除数据，也不开始安装。

遇到归属不明或存在风险的残留项时：

• 交互模式：直接运行 sudo ./zenova install <包.zpkg> --fresh，安装器会列出每一项待确认资源并逐项询问 y/N，由现场管理员确认后继续。
• 非交互 / 远程支持模式：先运行 --fresh --dry-run --plan ./reinstall-plan.toml 导出清理计划文件，审核确认后执行 sudo ./zenova install <包.zpkg> --fresh --plan ./reinstall-plan.toml --confirm-data-loss DELETE_EXISTING_DATA。
• 外部数据库或对象存储：安装器始终硬拒绝清空外部 PostgreSQL、ClickHouse 与 S3，防止误删共享生产数据。
• 严禁手写清理命令：远程支持与现场运维一律通过 --fresh --dry-run、交互确认或 --plan 处理旧安装残留，不得手写 rm -rf、docker rm、systemctl 等手工清理命令。

sudo ./zenova install ./zenova-<版本>-linux-amd64-xxxxxxxx.zpkg --fresh --confirm-data-loss DELETE_EXISTING_DATA

核对预览并安排停服窗口后，执行第二条命令。确认词必须完整填写 DELETE_EXISTING_DATA。在删除旧数据前，安装器先验证新包全部组件的 sha256 与大小、安装器与包的版本和平台、安装答案以及所选能力是否齐全；未通过时不会进入删除阶段。组件摘要校验用于发现下载损坏，不代表签名校验。

安装器按以下顺序执行：

1. 停止旧服务和容器后，再次核对旧部署身份指纹。
2. 清理属于该安装的服务、数据路径、容器、独占卷和网络；保留 Docker 镜像与系统账户。
3. 调用现有首装流程安装新包，完成第 4 节的装后验收。

中断后从哪里继续

• 旧部署清理成功，后续安装失败：处理安装错误后，对同一个包执行普通安装命令，使用已有安装进度继续执行，不再加 --fresh。现有断点继续执行能力无需额外配置。
• 清理阶段失败或中断：执行 sudo ./zenova install <包.zpkg> --fresh --dry-run 并回传输出的清单与诊断代码，按提示的计划文件或交互确认继续处理；切勿手写清理命令。

再次使用 --fresh 并确认删除表示重新清空本机数据，不是继续上次安装。

waner reset --local

客户端也须与控制面配套升级，过旧的婉儿 CLI、ZenSwitch、桌面端可能无法连接新版控制面。需要删除客户端旧本地数据时，在对应客户端机器上执行此命令，之后重新登录；它不代替服务器的 --fresh 清空重装。

12. 安装完成检查清单

• [ ] 安装器输出的装后验收结果全部通过。
• [ ] 已保存初始 root 密码，并在首次登录时修改密码；已按客户的安全要求设置平台范围的「强制两步验证」。
• [ ] 浏览器可以打开控制台地址。
• [ ] sudo zenova status 显示各服务正常运行。
• [ ] 「平台 → 网关」中中心节点（office-primary）在线。
• [ ] 如需受许可证控制的能力，已导入许可证。
• [ ] 已添加模型供应商并完成一次测试调用。
• [ ] 已执行一次 sudo zenova backup 并记录备份标识。
• [ ] 公网使用时，防火墙或安全组已放行控制台入口端口。