4. 交互式安装

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

本章内容：本章按安装器在终端里的实际顺序，从预检、启动、逐屏问答，到安装执行、装后验收和完成输出，一步步说明每一屏看到什么、该填什么、出了例外怎么处理，最后说明中途中断后怎样继续。读者是在安装主机上操作的实施工程师；涉及数据库、存储与网络的屏，需要对应的客户管理员在场或提前按第 3 章准备好。

4.1 安装流程总览

安装器的全部步骤如下。确认安装之前不写任何文件、不创建任何服务；任一步输入 q 退出，本机不留任何内容（退出码 130）。问答没有「返回上一步」，填错了只能输入 q 退出后重来，或在确认页之前对相应问题按提示修改。

注意：第 11 步以后，安装器在 /opt/zenova/state/ 下记录进度。此后中断或失败，重新执行同一条命令即可从断点继续（4.8 节），不要手工删除任何文件。

4.2 先跑预检

适用场景：正式安装前，在安装主机上确认主机条件与问答内容。预检可以反复执行，不留任何内容。

前提：已按第 3.6 节把物料放到 /root/zenova-install 并核对。

操作步骤

1. 进入暂存目录，设置离线包变量，执行预检。

# 安装主机 · root · 只读（预检，不写任何内容）
cd /root/zenova-install
ZPKG=/root/zenova-install/<离线包>.zpkg
sudo ./zenova install "$ZPKG" --check-only

2. 按 4.4 节回答能力选择、预填确认与补充配置各屏的问题。预检里填的内容不会保存，正式安装时还要再答一次，可以借预检把答案先理顺并记下来。
3. 主机检查有 ✗ 项时，按屏幕提示与第 3 章处理，按回车重新检查。
4. 需要把安装目录放到其他数据盘时，预检也要带上同样的参数，例如 --install-dir <目录>，否则检查的是默认的 /opt/zenova。

你会看到

• 最后一行输出「预检通过：未写入任何内容」，命令退出。

注意：预检不包含以下检查，预检通过不代表正式安装一定通过：

4.3 启动安装

前提：预检已通过；客户方管理员已就位（使用现有依赖时需要数据库管理员、存储管理员到场录入密码，或已准备好凭据文件）。

操作步骤

1. 建议在 tmux 或 screen 会话中执行（主机上已有时），避免 SSH 断开打断安装。
2. 执行安装命令。

# 安装主机 · root · 写入（确认后开始安装）
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

3. 核对屏幕第一行「将安装：<产品> <版本>」，不对就输入 q 退出。

主要参数（交互式安装通常一个都不用加，按需选用）：

你会看到

• 第一行形如「将安装：Zentrix 网关 0.7.0-nightly.20261020034227.f51c370a」。

注意：第一行的产品名由安装器决定，版本号来自离线包。核对两点：产品是否是本次要交付的产品（安装后不能更换产品，只能清空重装）；版本号是否与交付记录一致。安装器与离线包版本或产品不一致时，安装器在这一行之前就会拒绝并说明原因。

4.4 逐屏说明

下面按出现顺序说明每一屏。定制站已经预填的项不会再问，而是在「确认预填配置」屏统一确认。

4.4.1 能力选择

你会看到

• 标题「本次要安装的能力（核心必装；未勾选的会保留在本机，之后可在控制台直接启用）」，下面是离线包中包含的能力列表，带编号与勾选状态。
• 提示「输入编号切换，回车完成」。
• Zentrix 网关首次安装默认只勾选「核心」；完整版默认勾选离线包中的全部能力。

操作步骤

1. 输入编号切换某项的勾选状态，可以多次输入。
2. 核对勾选结果后直接回车。

注意：「核心」始终安装，不能取消。依赖关系自动联动：勾选「文档解析」会一并勾选「知识库」。离线包里有但本次没勾的能力保留在本机，装完后在控制台「系统更新」页直接启用，不需要重新下载。勾选会影响磁盘需求（第 3.1 节），磁盘紧张时只勾本次真要验证的能力。

4.4.2 确认预填配置

适用场景：下载站第四步填了预填配置。整页留空时没有这一屏。

你会看到

• 标题「以下配置来自定制站」，分两级列出：
  • 一般项（访问地址、依赖的部署方式、对象存储模式、通知渠道类型）合并列出，提示「请直接回车确认，或输入 n 修改」。
  • 地址类项（现有 PostgreSQL、ClickHouse、对象存储的地址，通知渠道地址）逐项显示并标注「来自定制站」，提示「这一项需要输入 y 才能确认」。

操作步骤

1. 一般项核对无误直接回车；需要改时输入 n，安装器随后重新询问。
2. 地址类项逐项输入 y 确认；不对时拒绝，安装器当场要求改填。

注意：预填内容在离线包里标记为未签名，地址类项必须逐项输入 y，直接回车不算确认。这是为了防止离线包在传递途中被改了地址。

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

你会看到

• 「访问地址（回车使用本机 <本机地址>；也可填写 http://… 或 https://…；地址里写的端口即本机监听端口，不写端口为 80）」。

操作步骤

1. 按下表填写访问地址。直接回车使用本机地址 http://<本机地址>。
2. 访问地址是 http:// 且带非 80 端口时，安装器再问「访问地址前面是否有代理或 NAT 转发」：
   • 选「没有，本机直接监听访问地址里的端口」，本机就监听访问地址里的端口；
   • 选「有，由代理或 NAT 转发到本机的另一个端口」，再填写「本机监听端口（代理、NAT 或 TLS 入口转发到的端口，回车为 80）」。
3. 访问地址是 https:// 时，安装器直接询问 TLS 入口转发到的本机监听端口，回车为 80。

注意：

• 访问地址是用户和调用方最终使用的地址，填 https:// 不会让本机提供 HTTPS，证书由客户的负载均衡或反向代理终结。
• 访问地址的端口与本机监听端口不同时，必须由前置代理、NAT 或 TLS 入口把访问地址的端口转发到本机监听端口，否则访问地址打不开。
• http:// 访问地址下，登录页不提供通行密钥，两步验证只能用验证器应用。客户要用通行密钥时，访问地址必须是 https://。
• 地址格式不对时提示「访问地址必须是 http:// 或 https:// 开头的完整地址」，当场重填。填了不带点的单段主机名且解析不到时，安装器会说明风险并要求输入 y 才继续使用。

4.4.4 平台数据库（PostgreSQL）

你会看到

• 「平台数据库（PostgreSQL）」，两个选项：「由我们部署」「使用现有的」。

操作步骤

1. 无特殊要求选「由我们部署」：安装器在本机初始化 PostgreSQL，只监听回环地址，后续不再提问。
2. 选「使用现有的」时，依次填写：
   • 「平台数据库访问地址（主机:端口）」，例如 <数据库地址>:5432；
   • 「平台数据库管理员账号（须为超级用户，安装器用它创建平台的角色与库）」；
   • 「平台数据库加密方式」：「明文（不加密）」「加密（校验交给系统信任库）」「加密并用指定 CA 证书校验」，缺省为明文；选第三项时再填「CA 证书文件路径」，必须是安装主机上已存在的文件。

注意：不问库名，平台的库由安装器创建、库名固定。管理员账号的密码在后面的「凭据」一屏录入。各项要求与数据库管理员自查方法见第 3.5 节。

4.4.5 分析数据库（ClickHouse）

你会看到

• 「分析数据库（ClickHouse，必装）」，两个选项：「由我们部署」「使用现有的」。

操作步骤

1. 无特殊要求选「由我们部署」。
2. 选「使用现有的」时，依次填写：
   • 「分析数据库访问地址（主机:端口）」，填 HTTP 或 HTTPS 接口端口（常见 8123 / 8443），不是 9000；
   • 「分析数据库库名（回车使用 zenova）」；
   • 「分析数据库登录账号」，按第 3.5 节为 default；
   • 「分析数据库加密方式」，三个选项同 PostgreSQL；
   • 「分析数据库的库类型」：「单机库（普通 MergeTree）」或「复制库（库引擎 Replicated，建表带 ON CLUSTER）」，缺省为单机库，按数据库管理员告知的选择。

注意：ClickHouse 是必装组件，没有「不安装」选项。本机 CPU 指令集不满足要求时，主机检查会提供「重新选择分析数据库」，回到这一屏改为「使用现有的」（4.4.8 节）。

4.4.6 对象存储

你会看到

• 「对象存储」，三个选项：「自带对象存储（推荐，生产）」「使用本机目录（单机试用）」「使用现有的 S3 兼容存储」，缺省为第一项。

操作步骤

1. 单机安装推荐选「自带对象存储（推荐，生产）」，安装器在本机部署并自动建桶。
2. 只做短期试用时可以选「使用本机目录（单机试用）」。
3. 选「使用现有的 S3 兼容存储」时，依次填写「对象存储访问地址（http://… 或 https://…）」「区域」「存储桶」「对象存储寻址方式」（「路径寻址」或「虚拟主机寻址」，缺省路径寻址）。访问密钥在「凭据」一屏录入。

注意：对象存储方式安装后不能在线更换，需要更换时只能备份后按新的选择重新安装，再恢复数据。POC 之后要转生产的环境，这里直接按生产的选择填。

4.4.7 运维通知渠道

你会看到

• 「运维通知渠道」，选项：「钉钉」「飞书」「企业微信」「Webhook」「暂不配置」。

操作步骤

1. 选择类型，再填「渠道地址」（机器人或回调的完整地址，必须以 http:// 或 https:// 开头）。
2. 钉钉机器人启用加签时，在「加签密钥」中填写机器人「安全设置 › 加签」中的密钥；输入内容不显示。没有启用加签时留空。Webhook 的密钥同样可选。
3. 安装器在确认页之前会发一条测试消息（4.4.11 节）。也可选择「暂不配置」继续安装，安装后再到「通知渠道」页面补配。无通知配置时，通知绑定与通知出站验收显示「已跳过」，不阻断安装；告警引擎等其它检查照常执行。已有通知配置但未验证或发送失败时仍会报错。安装时填写的渠道接收全部平台告警；紧急通知需要安装后在平台控制台「通知渠道」中另建一个独立接收方的渠道并设为「紧急通知」（6.5 节）。

4.4.8 主机检查

你会看到

• 标题「主机检查」，逐项列出检查结果：✓ 通过、⚠ 提示、✗ 阻断。检查项包括 CPU 架构、内存、磁盘空间、系统服务托管、系统时间，以及按本次选择适用的处理器指令集、容器运行时、目录遍历权限、挂载执行权限、服务用户属性等。
• 「系统时间」通过时，下面一行显示「已同步，时间偏差 N 秒（安装前上限 30 秒）」。
• 未通过的项逐条列出原因与处理办法，不会因第一项失败就停止其余检查。

操作步骤

1. 全部为 ✓，或只有 ⚠：自动继续。
2. 有 ✗：另开一个终端按屏幕提示与第 3 章处理，回到安装器按回车重新检查；输入 q 退出。
3. 只有「处理器指令集」阻断时，可以选「重新选择分析数据库」，把分析数据库改为「使用现有的」。

注意：显式传了 --install-dir（包括显式写 /opt/zenova）时，磁盘不足显示为 ⚠ 并直接继续。这只是不阻断，空间实际不足时仍可能在解包、安装或运行时失败。

4.4.9 端口

你会看到

• 平台内部服务的端口被占用时，安装器自动改用下一个空闲端口，并逐条说明改用了哪个端口，不需要处理。
• 业务入口端口被占用时，显示「本机监听端口 <端口> 已被进程 <进程名>（PID <进程号>）占用。访问地址依赖这个端口，安装不会自动更换；…」，并提示「释放端口后按回车重新检查，输入 n 重新填写访问地址与本机监听端口，输入 q 退出」。
• 业务入口端口与平台内部端口相同时，提示该端口是平台内部服务使用的端口，不能作为访问入口。

操作步骤

1. 业务入口端口被占用时，与客户确认后停止占用进程，回到安装器按回车重新检查。
2. 不能停止占用进程时，输入 n 重新填写访问地址与本机监听端口。命令行带了 --business-entry-port 时不能在问答里改，输入 q 退出后换端口重新执行。
3. 管理入口分离时，其端口被占用会自动顺延到下一个空闲端口，完成输出中的「本机直接访问」按实际端口给出。

注意：这一屏在预检中不出现。改了本机监听端口后，访问地址的端口与本机监听端口可能不再一致，此时必须有前置转发（4.4.3 节）。

4.4.10 凭据与依赖检测

适用场景：至少一项依赖选了「使用现有的」。三项都由安装器部署时没有这一屏。

你会看到

• 依次询问（输入内容不显示）：「平台数据库管理员账号 <账号> 的密码」「分析数据库的登录密码」「对象存储访问密钥 ID」「对象存储访问密钥」，只问本次选了「使用现有的」那几项。
• 录入后立即检测。全部通过时直接进入下一屏；有未通过项时显示标题「依赖检测」，逐条列出「<依赖>：<原因>，请联系<负责人>」，并提示「修正后按回车重新检测，输入 q 退出」。

操作步骤

1. 由数据库管理员、存储管理员本人在终端录入密码与密钥；不要把口令写在聊天记录或纸面上转交。
2. 检测未通过时，按屏幕列出的原因与负责人处理（对照第 3.5 节自查），修正后按回车重新检测。

检测内容：

注意：检测会创建并删除临时库（zenova_probe_<随机串>）或临时对象（zenova-probe/<随机串>），不写入业务数据。PostgreSQL 管理员密码只在安装过程中使用，不写入任何文件与日志；安装完成后平台只用自己的角色访问数据库。

注意：如果现有 PostgreSQL 的平台库中已经有平台数据，普通安装会在这里停止并提示改用接管安装（--adopt-existing）。接管不在本章范围，联系技术支持确认后再操作。

4.4.11 运维通知测试

适用场景：4.4.7 节配置了通知渠道。

你会看到

• 发送成功：「测试消息已发送，请确认已收到」。
• 发送失败：「运维通知测试：<失败原因>」，可修正渠道地址或加签密钥后重发，也可输入 s 跳过通知、输入 q 退出。

操作步骤

1. 到对应的群或接收端确认收到测试消息。
2. 发送失败时，核对渠道地址、机器人安全设置与安装主机的出网，按提示修正地址或加签密钥后重发；暂时无法配置时输入 s 跳过通知，安装后补配。

注意：安装器会检查渠道返回的业务错误码；签名、令牌或关键词校验被拒绝时不会显示发送成功。显示「已发送」后仍需到群里确认接收人已收到。

4.4.12 确认页

你会看到

• 标题「即将开始安装，请确认以下内容」，逐项列出：
  • 访问地址，紧跟「本机监听端口」。两者不同时提示「访问地址的端口与本机监听端口不同，需由前置代理或 NAT 把访问地址的端口转发到本机监听端口」；访问地址为 https:// 时提示「访问地址使用 https，需由前置 TLS 入口终结加密后转发到本机监听端口」。
  • 平台数据库、分析数据库、对象存储、运维通知渠道的选择与地址。
  • 「能力：…」。
  • 「安装目录：/opt/zenova（需要 N GB 磁盘空间）」；显式传了 --install-dir 时显示「建议」。
  • 「服务账户 zenova：安装根外的祖先目录须可遍历，系统目录权限由系统管理员管理」。
• 最后一行「确认开始安装」。

操作步骤

1. 逐项与交付记录核对，特别是访问地址、本机监听端口和对象存储方式。
2. 无误后回车确认；有误则输入 q 退出，重新执行安装命令。

注意：这是最后一个不写盘的点。回车之后安装器开始写入部署配置、解开离线包，之后再退出就会留下部分安装，只能按 4.8 节续装或按清空重装流程处理。

4.5 安装执行

你会看到

• 先解开离线包，并以服务用户身份检查随包程序能否执行。被安全模块拦截时，逐条显示「✗ [<代码>] <原因> <处理办法>」并停止（处理见第 3.3 节，之后按 4.8 节续装）。
• 随后依次执行四个阶段，每个阶段开始时显示「正在安装：<阶段>」，结束时显示「<阶段> 已完成」。

• 四个阶段结束后显示「各阶段耗时」表，以及「逐项计时与迁移分步耗时已写入安装日志」。

操作步骤

1. 等待安装执行，不要中断。三项依赖都由安装器部署的干净主机上，全程约 4 分钟，其中数据库迁移约占一半，控制面阶段停留较久属于正常现象。
2. 需要观察细节时，另开一个终端查看安装日志：

# 安装主机 · root · 只读（跟踪安装日志）
tail -f /opt/zenova/state/install.log

使用 --install-dir 时，把 /opt/zenova 换成实际安装根。

注意：某一阶段失败时，屏幕停在失败的步骤并给出原因与下一步。处理原因后重新执行同一条安装命令，已完成的阶段会跳过（4.8 节）。安装期间控制台不可用；首次安装尚无网关业务流量，不影响任何现有业务。

4.6 装后验收

装后验收是安装的最后一个阶段，自动执行，不需要输入。全部阻断级验收项通过，安装才记为完成。

你会看到

• 验收通过：进入 4.7 节的完成输出，其中包含验收结果。
• 验收失败：屏幕显示「装后验收失败：未通过的检查：<验收项>（<依据>）」，安装不记为完成。
• 警告级项未通过只提示，不阻止安装完成。

操作步骤（验收失败时）

1. 按「依据」中的原因处理。常见情形：

2. 处理后重新执行同一条安装命令，安装器从装后验收继续，不重做前面的阶段。

# 安装主机 · root · 写入（从装后验收继续）
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

3. 需要远程支持时，采集信息：

# 安装主机 · root · 只读
sudo zenova status --json > /root/zenova-install/status.json
sudo zenova doctor --all --save /root/zenova-install/doctor
sudo cp /opt/zenova/state/install.log /root/zenova-install/

注意：装后验收通过只证明平台基础服务可用。模型与工具的配置、真实调用、拒绝路径等，按第 7 章逐项完成。

4.7 完成输出

你会看到

安装完成后，屏幕依次打印：

• 「各阶段耗时」表与验收结果；
• 「安装完成」；
• 「管理台登录账号（初始密码只保存在本机，日志中不记录）」，下面是登录账号 root 与 32 位随机字符的初始密码（具体行格式以实际输出为准）；
• 「本机直接访问：http://<本机地址>[:<端口>]」；
• 「访问地址：<访问地址>」；
• 「下一步：用上面的账号登录控制台，按提示修改初始密码；平台安全策略要求两步验证时，还需绑定两步验证」。

两个地址的区别：

操作步骤

1. 立即按客户的口令管理规范保管初始密码。
2. 首次修改密码前需要再次查看时，在安装主机上执行：

# 安装主机 · root · 只读（查看初始密码）
sudo zenova root-password show

3. 用浏览器打开「访问地址」登录，按第 6 章完成首次登录与初始化。打不开时先试「本机直接访问」。

注意：初始密码不得通过即时通讯、邮件或工单传递，不要录屏或截图外传。 初始密码同时保存在 /opt/zenova/.env.runtime/root-password-initial（权限 0600），首次修改密码后失效，root-password show 也随之不再可用。root 忘记密码或两步验证全部丢失时，用 sudo zenova root-password set 重置（第 8.7 节）。

注意：完成输出之后，务必按第 8.1、8.2 节完成密钥材料离机备份与首次平台备份，这两项不做，平台出故障时无法恢复。

4.8 中断与续装

确认安装之后，安装器把每个已完成的阶段记录在 /opt/zenova/state/ 下。重新执行同一条安装命令，已完成的阶段会跳过，从断点继续。

操作步骤

1. 查看失败原因：屏幕上的提示，或安装日志。

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

2. 按原因处理。
3. 重新执行与上次完全相同的命令（参数不变）。

# 安装主机 · root · 写入（从断点继续安装）
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

你会看到

• 已完成的阶段不再显示「正在安装」，安装器直接从未完成的阶段开始。

注意：不要删除 /opt/zenova/state/ 下的进度文件（install.json 等），也不要手工删除 /opt/zenova 下的任何目录或停用服务来「重来」。进度文件被删后，安装器无法判断哪些已完成，现场会处于无法续装、也无法安全清理的状态。确实需要推倒重来时，只能在满足条件的环境中用清空重装流程（--fresh --dry-run 预览后再执行），严禁手写 rm -rf、docker rm、systemctl 等手工清理命令。

注意：续装时参数要与首次一致，特别是 --install-dir、--log-dir、--business-entry-port。换了参数，安装器会认为是另一套安装或拒绝继续。

能力说明

上一章：3. 环境准备 · 下一章：5. 非交互安装