5. 非交互安装

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

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

本章内容：非交互安装用一份答案文件（--answers）和一份凭据文件（--secret-file）代替问答，安装器全程不提问，适合批量部署、远程执行和无人值守。本章给出两份文件的全部字段、写错时的后果，以及两套可以直接改值使用的完整示例。读者是需要用脚本或远程会话完成安装的实施工程师；只装一台、现场有人值守时，用第 4 章的交互安装即可。

5.1 什么时候用非交互安装

适用场景：同一套参数要装多台主机；只能通过远程会话或自动化工具执行；安装过程中无人在终端前回答问题。

非交互安装与交互安装走的是同一个安装流程、同样的主机检查、依赖检测、四个安装阶段和装后验收，区别只在「答案从哪里来」和「遇到问题时怎么处理」。交互安装遇到问题会停下来让你当场修正；非交互安装遇到问题直接报错退出，修正文件后重跑同一条命令。

规则一览

操作步骤

1. 按 5.2 节写好答案文件 answers.toml。
2. 有任何一项依赖使用现有服务时，按 5.3 节写好凭据文件 secrets.toml 并设为 0600。三项依赖都由安装器部署时不需要凭据文件。
3. 先加 --check-only 跑一次预检，通过后去掉 --check-only 正式执行。完整命令见 5.4、5.5 节。

你会看到

• 预检通过时输出「预检通过：未写入任何内容」。
• 正式执行时屏幕依次打印主机检查结果、依赖检测结果、通知测试结果（如配置）、四个安装阶段与装后验收，最后打印登录账号与初始密码（见第 4 章 4.7 节）。

注意：安装中断或失败后，修正原因并重跑同一条命令，安装器从断点继续。续装时答案文件内容必须与第一次一致，否则报「答案与上次安装不一致；如需修改配置，请加 --reconfigure 重新执行」；--with 与上次不同也会被拒绝并列出差异。--reconfigure 会进入问答，需要有人在终端前操作。

5.2 答案文件字段说明

答案文件是 TOML 格式。顶层字段必须写在所有 [段] 之前——写在某个段之后的顶层字段会被当作该段的成员，随即报「不认识的字段」。

顶层字段

另有两个顶层可选字段，POC 一般不用：admin_public_url（管理访问地址，只在控制台单独走反向代理或独立域名时填写，留空时由访问地址的主机与管理入口端口推导）、otlp_endpoint（链路导出地址）。两者都必须是合法的 http:// 或 https:// 地址。

[postgres] 平台数据库

只能写下面两种之一。

external 内的字段：

[clickhouse] 分析数据库（必装）

external 内的字段：

[object_store] 对象存储

只能写下面三种之一。安装后不能在线更换。

external_s3 内的字段（四项全部必填）：

[notify] 运维通知渠道

暂不配置时，省略本段，在答案文件顶层写 notify_skipped = true。加签密钥写入凭据文件的 notify_secret，不要写进答案文件。

[[hosts]] 主机清单

单机安装不要写这一段。写了 [[hosts]] 即进入多机安装，每一行包含 address（地址）、role（control_plane 控制面、gateway 网关节点、postgres 平台数据库、clickhouse 分析数据库、arbiter 仲裁）与 site（站点）。多机安装只能使用现有 S3 兼容存储，写 bundled 或 local_dir 会报「多副本部署必须使用现有的 S3 兼容存储，不能使用自带对象存储或本机目录」。多机安装不在本手册范围。

注意：答案文件不含任何口令、密钥和许可证，可以随交接材料归档。安装完成后，本次实际使用的答案保存在 /opt/zenova/state/answers.toml。

5.3 凭据文件

凭据文件也是 TOML 格式，按所选依赖和通知渠道填写需要的键。

操作步骤

1. 在安装暂存目录创建只有 root 可读写的空文件。不要用 echo 写入口令，避免口令进入命令历史。

# 安装主机 · root · 写入（创建空的凭据文件，权限 0600）
cd /root/zenova-install
umask 077
touch secrets.toml
chmod 600 secrets.toml

1. 用文本编辑器打开 secrets.toml，按需要写入，例如：

pg_admin_password = "<PostgreSQL 超级用户密码>"
ch_password = "<ClickHouse 账号密码>"
s3_access_key_id = "<访问密钥 ID>"
s3_access_key_secret = "<访问密钥>"

1. 核对权限与属主。

# 安装主机 · root · 只读
ls -l /root/zenova-install/secrets.toml

你会看到

• 权限列为 -rw-------，属主为 root。

注意：缺少某项依赖所需的凭据时，安装器提示「使用现有服务时，非交互安装必须用 --secret-file 提供凭据」并以依赖检测未通过停止，不会改为在终端询问。权限不对时报「凭据文件权限必须是 0600：<路径>」。安装完成后按第 8 章 8.3 节删除该文件，或按客户凭据管理要求移交。

5.4 示例一：三项依赖全部由安装器部署

适用场景：POC 推荐组合。平台数据库、分析数据库、对象存储全部由安装器在本机部署，不需要凭据文件。

操作步骤

1. 在安装暂存目录写入答案文件 answers.toml：

# 顶层字段写在所有段之前
public_url = "http://<主机地址>"
[notify]
kind = "webhook"
target = "https://hooks.example.com/zentrix"

[postgres]
managed = {}

[clickhouse]
managed = {}

[object_store]
bundled = {}

1. 预检（不写入任何内容）：

# 安装主机 · root · 只读（预检，不写任何内容）
cd /root/zenova-install
sudo ./zenova install ./<离线包>.zpkg --answers answers.toml --with core --check-only </dev/null

1. 预检通过后正式安装：

# 安装主机 · root · 写入（开始安装，不再提问）
cd /root/zenova-install
sudo ./zenova install ./<离线包>.zpkg --answers answers.toml --with core </dev/null

</dev/null 把标准输入接到空设备。非交互安装正常情况下不会提问；万一某一步仍需要输入，安装器立即读到输入结束，按输入 q 处理并退出（退出码 130），而不会在无人值守的会话里一直卡住等待。远程会话或自动化工具调用时建议始终加上。

你会看到

• 预检输出「预检通过：未写入任何内容」。
• 正式安装依次完成数据层、控制面、已选能力、装后验收，干净主机上约 4 分钟。
• 最后打印各阶段耗时、验收结果、root 账号与初始密码、「本机直接访问」与「访问地址」。

注意：--with 要与本次离线包所属产品匹配。Zentrix 网关不提供托管智能体与文档解析，写了会报「…不含「…」能力，请从 --with 中去掉」。能力标识为 core、knowledge_base、agent_runtime、doc_parse、ha_data。

5.5 示例二：使用现有数据库与对象存储

适用场景：客户要求平台数据库、分析数据库与对象存储都使用现有服务，且数据库连接需要加密。

前提：现有服务已满足第 1 章 1.5 节的全部要求（PostgreSQL 超级用户与扩展、ClickHouse 版本与宏、预先建好的存储桶与读写删权限）；如使用内部 CA 签发的证书，已把 CA 文件放到安装主机上。

操作步骤

1. 把客户提供的 CA 证书放到安装暂存目录，例如 /root/zenova-install/customer-ca.pem（必须用绝对路径引用）。
2. 写入答案文件 answers.toml：

public_url = "https://<访问域名>"
business_listen_port = 80

[postgres]
# 证书由公共 CA 签发时可写 tls = "required"
external = { host = "<PostgreSQL 地址>", port = 5432, user = "<超级用户账号>", tls = { verify_full = { ca_file = "/root/zenova-install/customer-ca.pem" } } }

[clickhouse]
external = { host = "<ClickHouse 地址>", port = 8443, database = "zenova", user = "default", tls = { verify_full = { ca_file = "/root/zenova-install/customer-ca.pem" } } }

[object_store]
external_s3 = { endpoint = "https://<对象存储地址>", region = "<区域>", bucket = "<桶名>", addressing = "path" }

[notify]
kind = "wecom"
target = "<企业微信机器人地址>"

[postgres] 中不写 database。现有 ClickHouse 为复制库时，在 external 内加 replicated = true。

1. 按 5.3 节创建凭据文件 secrets.toml（0600），写入：

pg_admin_password = "<PostgreSQL 超级用户密码>"
ch_password = "<ClickHouse 账号密码>"
s3_access_key_id = "<访问密钥 ID>"
s3_access_key_secret = "<访问密钥>"

1. 预检，再正式安装：

# 安装主机 · root · 只读（预检，不写任何内容）
cd /root/zenova-install
sudo ./zenova install ./<离线包>.zpkg --answers answers.toml --secret-file secrets.toml --with core --check-only </dev/null

# 安装主机 · root · 写入（开始安装，不再提问）
cd /root/zenova-install
sudo ./zenova install ./<离线包>.zpkg --answers answers.toml --secret-file secrets.toml --with core </dev/null

加密方式写法对照

你会看到

• 依赖检测逐项通过：PostgreSQL 账号可登录、为超级用户、扩展齐全；ClickHouse 版本、宏与建库权限满足；对象存储读、写、删正常。检测会创建并删除临时库或临时对象，不写入业务数据。
• 通知测试显示「测试消息已发送，请确认已收到」，到企业微信群确认已收到。
• 其后与示例一相同。

注意：

• 依赖检测不通过时，屏幕显示「依赖检测未通过：<原因>，请联系<负责人>」，例如需要数据库管理员或存储管理员处理。修正后重跑同一条命令。
• 现有 PostgreSQL 中已有本平台数据时，普通安装会停止并提示改用接管方式（不在本手册范围）。
• 本例的访问地址为 https://，证书由客户前置的负载均衡或反向代理终结，business_listen_port 写的是 TLS 入口转发到本机的端口。本机不提供 HTTPS。
• 使用现有 PostgreSQL 与现有 S3 时，zenova backup 不包含这两部分数据，由对应管理员负责；该环境也不支持清空重装。

5.6 从下载站预填答案改为非交互

适用场景：离线包是在下载站填写了「预填配置」后下载的，包内已带一份答案，现在要改为非交互执行。

下载站的预填配置会随离线包带到现场。交互安装时，安装器把这些预填项列出来请你确认：一般项回车确认，访问地址类（现有服务地址、通知渠道地址）标注「来自定制站，未签名」，逐项输入 y 才算确认。

改为非交互时：

操作步骤

1. 按 5.2 节写一份完整的 answers.toml。可以参照下载页「配置链接」中的同一份预填内容（以实际页面为准），但必须补齐全部必填段——--answers 是整份替换，离线包里预填过、而答案文件里没写的项目不会被沿用，会报「缺少 <项目>」。
2. 需要凭据时按 5.3 节准备凭据文件。下载站不收集凭据，这一步不能省。
3. 按 5.4 或 5.5 节的命令执行，带上 --answers。

你会看到

• 安装器不再显示「确认预填配置」这一步，也不要求逐项输入 y，直接进入主机检查。

注意：--answers 的优先级最高，给出后离线包内的预填配置不再参与本次安装。答案文件由实施工程师提供，视为已确认，因此地址类字段务必在写入前与客户核对一遍（可对照第 1 章 1.6 节的确认表）。

能力说明

---

上一章：4. 交互式安装 · 下一章：6. 首次登录与初始化