3. 环境准备

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

本章内容：安装器在确认安装之前会做一轮主机检查，但有几类问题只有到写盘之后才会暴露，到那时再找客户的主机、安全、数据库和网络管理员，往往要等很久。本章把这些准备工作提前到安装日之前：先用只读命令自查主机，再分别与主机安全管理员、数据库管理员、存储管理员、网络管理员确认各自负责的事项，最后把物料传上去并核对。读者是实施工程师和客户方的各类管理员。

3.1 主机检查项与安装前自查

适用场景：拿到安装主机的登录权限后、正式安装前一天或更早。

安装器的主机检查项如下。「何时检查」一栏说明这一项在哪个环节暴露，用来判断第 4 章的预检（--check-only）能不能替你提前发现它。

磁盘需求按本次部署的组件累加（GiB）：

典型组合：

操作步骤

1. 以 root 登录安装主机，逐条执行下面的只读命令，把输出记入交付记录。

# 安装主机 · root · 只读（系统、架构、内存、磁盘）
uname -m
free -g
df -h /opt

# 安装主机 · root · 只读（安装目录的挂载选项与上级目录权限）
findmnt -T /opt -o TARGET,OPTIONS
ls -ld / /opt

# 安装主机 · root · 只读（是否已有同名服务用户）
id zenova

# 安装主机 · root · 只读（CPU 指令集，仅 x86_64 且本机部署 ClickHouse 时需要）
grep -o -w -E 'avx|avx2|bmi1|bmi2|fma|f16c|movbe|abm' /proc/cpuinfo | sort -u

# 安装主机 · root · 只读（是否以 systemd 启动、是否有非回环地址）
ps -p 1 -o comm=
ip -br addr

2. 对照下面的预期逐项判断；不符合的项，按对应小节处理后再执行一次。

你会看到

• uname -m 输出 x86_64 或 aarch64，且与下载站选的平台一致（linux-amd64 对应 x86_64，linux-arm64 对应 aarch64）。
• free -g 的 Mem: 一行 total 不小于 8。注意 free -g 向下取整，物理内存恰为 8 GiB 的主机可能显示 7，以 free -m 的数值（不小于 8192）为准。
• df -h /opt 的 Avail 不小于上表算出的合计。不够时，选一个空间更大、可执行的持久数据盘，安装时用 --install-dir <目录> 指定（第 4 章）。
• findmnt 的 OPTIONS 一列里没有 noexec。
• ls -ld / /opt 两行权限的最后一位都是 x（例如 drwxr-xr-x）。
• id zenova 输出 no such user 表示不存在，安装器会自己创建，这是最常见的情况；如果已存在，输出里 gid= 后面括号中的组名必须是 zenova。
• 指令集命令输出 8 行：abm、avx、avx2、bmi1、bmi2、f16c、fma、movbe（abm 即 LZCNT）。少任何一项，本机都不能部署 ClickHouse。
• ps -p 1 -o comm= 输出 systemd。
• ip -br addr 至少有一行不是 lo 且带 IP 地址。

注意：以下两类问题，预检（--check-only）发现不了，必须在安装日之前单独确认：

• 执行权限：SELinux、fapolicyd、麒麟 KYSEC 对程序的拦截，只有在确认安装、离线包解开之后，安装器以服务用户身份实际执行一次随包程序时才能发现。启用了这类强制访问控制的主机，提前按 3.3 节与主机安全管理员约定放行方式。
• 业务入口端口：访问地址依赖的本机监听端口是否被占用，在主机检查之后才检查，预检不包含。提前用 3.7 节的 ss 命令确认端口空闲。

注意：虚拟机上指令集不全，多半是虚拟化平台给虚拟机配的 CPU 型号偏低。处理办法是把 CPU 型号改为 host 直通，或 Haswell 及以上型号；做不到时，把分析数据库改为「使用现有的」ClickHouse（3.5 节）。

3.2 时间同步

适用场景：所有安装。未同步或无法确认同步状态时，安装器只告警，允许继续安装；不会把它显示为时间已同步。

建议：安装主机使用客户内网的 NTP 服务器或客户指定的时间源。没有可用时间源时，请自行核对主机时间；安装告警不会关闭登录、二次验证、令牌或证书的时间校验。

安装器按以下情况提示或阻断：

操作步骤

1. 先看当前状态。

# 安装主机 · root · 只读
chronyc tracking
chronyc sources -v
timedatectl

2. 如果没有配置时间源，或只配了本地时钟，编辑 chrony 配置文件（RHEL、麒麟、openEuler 一般为 /etc/chrony.conf，Ubuntu、Debian 为 /etc/chrony/chrony.conf），写入客户提供的 NTP 服务器，删除或注释掉 local stratum 一类以本地时钟为源的配置行。

server <NTP服务器地址> iburst

3. 重启时间服务并等待同步。

# 安装主机 · root · 写入（重启时间服务）
systemctl restart chronyd      # Ubuntu 上服务名为 chrony
chronyc waitsync 30
chronyc tracking

4. 偏差已经很大时（例如几分钟），可以让 chrony 立即跳变校准，再执行一次 chronyc tracking。

# 安装主机 · root · 写入（立即校准系统时间）
chronyc makestep

5. 主机没有 chrony、使用 systemd-timesyncd 时：在 /etc/systemd/timesyncd.conf 的 [Time] 段写入 NTP=<NTP服务器地址>，然后执行：

# 安装主机 · root · 写入（启用 systemd-timesyncd 同步）
timedatectl set-ntp true
systemctl restart systemd-timesyncd
timedatectl show -p NTPSynchronized

你会看到

• chronyc tracking 中 Leap status 为 Normal，System time 的偏差远小于 30 秒，Stratum 在 1～15 之间。
• chronyc sources -v 中至少有一个源行首为 ^*（当前选用的源）。
• 使用 systemd-timesyncd 时，最后一条命令输出 NTPSynchronized=yes。
• 安装时主机检查的「系统时间」一项显示 ✓，下面一行写明「已同步，时间偏差 N 秒（安装前上限 30 秒）」。

注意：仅未同步或无法确认状态时，安装器不会等待校时完成。若已测得偏差超限，可另开终端校时，再回到安装器重新检查；此时会等待校时服务收敛。

注意：准确时间仍是正常使用的条件。登录的两步验证码、证书校验、调用记录的时间顺序都依赖准确的时间，安装后也应保持校时机制可用。

3.3 目录权限与安全模块

适用场景：/opt 权限被收紧、/opt 挂在带 noexec 的分区、主机上已有 zenova 用户，或主机启用了 SELinux（Enforcing）、fapolicyd、麒麟 KYSEC。

平台服务以系统用户 zenova 身份运行（安装器创建，不可登录）。它需要能进入安装目录的每一级上级目录，并能执行安装目录下的程序。

操作步骤

1. 上级目录不可遍历时，二选一执行：

# 安装主机 · root · 写入（只给服务用户增加进入权限）
setfacl -m u:zenova:--x /opt

# 安装主机 · root · 写入（把 /opt 设为常规权限）
chmod 0755 /opt

setfacl 要求服务用户已经存在。用户还没创建时（首次安装前的常见情况），用 chmod，或先与主机管理员约定在安装器报出 HOST_ROOT_TRAVERSE 后再执行 setfacl。

2. 挂载点带 noexec 时，由主机管理员去掉该挂载选项并同步修改 /etc/fstab；或另挂一块允许执行的数据盘，安装时用 --install-dir 指向它。

# 安装主机 · root · 写入（重新挂载为允许执行，需同步修改 /etc/fstab）
mount -o remount,exec <挂载点>

3. 已有同名用户但主组不对时：

# 安装主机 · root · 写入（把 zenova 用户的主组改为同名组）
usermod -g zenova zenova

4. 启用了强制访问控制的主机，安装前与主机安全管理员确认放行方式。安装器报出拦截时，屏幕会直接给出针对本机路径的处理命令，形式如下（<安装根> 默认为 /opt/zenova），由安全管理员审核后执行：

5. 放行后，重新执行同一条安装命令。

你会看到

• 目录与挂载问题在主机检查页以 ✗ 标出，处理后按回车重新检查即可变为 ✓。
• 执行权限问题出现在确认安装之后，屏幕逐条列出 ✗ [<代码>] <原因> <处理办法>，安装停止。此时安装器已写入部分内容，按第 4.8 节续装，不要手工清理。

注意：安全模块的拦截在解包之后才能发现，预检通过不代表不会被拦截。启用了强制访问控制的主机，最稳妥的做法是安装前就把放行方式与主机安全管理员谈定，并约好安装当天的联系人。

注意：chcon 设置的标签在系统执行全盘重新标记后可能丢失；需要长期保留时，由主机安全管理员按客户自己的 SELinux 策略管理规范处理。升级会在 releases/ 下新增版本目录，放行策略要覆盖整个 releases/ 目录而不是某一个版本目录。

3.4 容器运行时

适用场景：本次要启用「托管智能体」「文档解析」，或多机方案中由安装器部署高可用 PostgreSQL。Zentrix 网关不包含以容器运行的能力，单机安装 Zentrix 网关不需要容器运行时，可以跳过本节。

前提：主机已安装 Docker 并处于运行状态。

操作步骤

1. 确认 Docker 可用。

# 安装主机 · root · 只读
docker info --format '{{.ServerVersion}}'

2. Docker 未启动时：

# 安装主机 · root · 写入（启动 Docker 并设为开机自启）
systemctl enable --now docker

3. 启用托管智能体时，取得客户安全负责人的书面同意，见下方「注意」。
4. 正式安装时，只有启用托管智能体才把服务用户 zenova 加入 docker 组并验证其访问。只启用文档解析时，服务单元由 root 管理，平台经 HTTP 访问，安装器只核对 root 能使用 Docker。

你会看到

• 第 1 步输出一个版本号。输出报错表示 Docker 未安装或未运行。
• 安装器主机检查页的「容器运行时」一项显示 ✓；不可用时为 ✗ 并提示「所选能力需要容器运行时，但本机 Docker 不可用」。

注意：加入 docker 组等同于授予宿主机 root 权限。 启用托管智能体前，取得客户安全负责人的书面同意，并把同意记录归入交付材料。仅文档解析不会改变服务用户的 Docker 权限。

注意：安装时没选这类能力、装完后在控制台「系统更新」页再启用时，控制台会重新检查容器运行时。检查失败时提示「所选能力需要容器运行时，但平台服务用户无法访问本机的 Docker」，按本节准备好 Docker 后重试。

3.5 准备现有数据库与对象存储

适用场景：平台数据库（PostgreSQL）、分析数据库（ClickHouse）或对象存储中有任何一项要「使用现有的」。三项都由安装器部署时跳过本节。

三项依赖在安装时逐项选择：

注意：选择「使用现有的」会改变后续运维边界，事先与客户讲清楚：

• zenova backup 不备份现有 PostgreSQL 与现有 S3，这两部分由客户数据库管理员、存储管理员按其备份机制保护。ClickHouse 无论自建还是现有，都经 HTTP 接口纳入平台备份。
• 三项依赖都由安装器部署时才能使用清空重装（--fresh）；只要有一项使用现有服务，就不能清空重装。
• 对象存储方式安装后不能在线更换。

PostgreSQL

要求

操作步骤（由客户数据库管理员执行）

1. 用准备交给安装器的那个管理员账号登录。下面的命令可以在任何装有 psql 且能访问数据库的主机上执行。

# 数据库管理员主机 · 数据库管理员 · 只读
psql "host=<数据库地址> port=<端口> user=<管理员账号> dbname=postgres"

2. 在 psql 中逐条执行：

-- 只读：版本应为 16
SHOW server_version;

-- 只读：当前账号是否超级用户，应返回 t
SELECT rolsuper FROM pg_roles WHERE rolname = current_user;

-- 只读：所需扩展是否可用，应返回 5 行，vector 的版本不低于 0.7
SELECT name, default_version
  FROM pg_available_extensions
 WHERE name IN ('vector', 'pg_trgm', 'uuid-ossp', 'pgcrypto', 'btree_gist')
 ORDER BY name;

-- 只读：连接数上限，应不低于 400
SHOW max_connections;

3. 把以下信息交给实施工程师：访问地址（主机:端口）、管理员账号、加密方式（见下文「加密方式与 CA」）、CA 证书文件（如需要）。密码在安装现场由数据库管理员本人录入，或经凭据文件提供（第 5 章），不经即时通讯或邮件传递。

你会看到

• 四条查询分别返回 16.x、t、5 行扩展、不小于 400 的数字。

注意：云数据库提供的「高权限账号」通常不是超级用户，rolsuper 返回 f，安装器的依赖检测会拒绝。此时需要客户换用自建 PostgreSQL，或请云厂商开通超级用户；做不到时改为由安装器部署。

注意：扩展少一项时，由数据库管理员在数据库服务器上安装对应的扩展包（vector 即 pgvector）。pg_available_extensions 里能查到即可，不需要预先 CREATE EXTENSION，安装器会自己创建。

ClickHouse

要求

操作步骤（由客户数据库管理员执行）

1. 在能访问 ClickHouse HTTP 接口的主机上执行。用 HTTPS 接口时把 http:// 换成 https://、端口换成对应端口。

# 数据库管理员主机 · 数据库管理员 · 只读（版本与宏）
CH='http://<ClickHouse地址>:8123/'
curl -sS -u 'default:<密码>' "$CH" --data-binary 'SELECT version()'
curl -sS -u 'default:<密码>' "$CH" --data-binary 'SELECT macro, substitution FROM system.macros'

# 数据库管理员主机 · 数据库管理员 · 写入（建一个临时库再删除，验证建库权限）
curl -sS -u 'default:<密码>' "$CH" --data-binary 'CREATE DATABASE zenova_selfcheck'
curl -sS -u 'default:<密码>' "$CH" --data-binary 'DROP DATABASE zenova_selfcheck'

2. 告诉实施工程师本次使用单机库还是复制库，以及访问地址、端口、加密方式与 CA 证书（如需要）。

你会看到

• 第一条返回不低于 26.7 的版本号。
• 第二条至少返回 cluster、shard、replica 三行。
• 建库、删库两条无输出、无报错。

注意：用 9000 端口填写访问地址，依赖检测无法通过。ClickHouse 是所有部署形态的必装组件，调用明细、用量统计与策略命中都存放在这里；不能跳过，只能在「由我们部署」与「使用现有的」之间选。

S3 兼容对象存储

要求

操作步骤（由客户存储管理员执行）

1. 建好存储桶，生成访问密钥并授予读、写、删权限。
2. 用存储管理员熟悉的 S3 客户端验证三种权限。以 AWS CLI 为例：

# 存储管理员主机 · 存储管理员 · 写入（上传、读取、删除一个临时对象）
export AWS_ACCESS_KEY_ID='<访问密钥 ID>'
export AWS_SECRET_ACCESS_KEY='<访问密钥>'
echo selfcheck > /tmp/zenova-selfcheck.txt
aws --endpoint-url <访问地址> --region <区域> s3 cp /tmp/zenova-selfcheck.txt s3://<存储桶>/zenova-selfcheck.txt
aws --endpoint-url <访问地址> --region <区域> s3 cp s3://<存储桶>/zenova-selfcheck.txt -
aws --endpoint-url <访问地址> --region <区域> s3 rm s3://<存储桶>/zenova-selfcheck.txt

3. 把访问地址、区域、存储桶、寻址方式交给实施工程师。访问密钥 ID 与访问密钥在安装现场录入或经凭据文件提供。

你会看到

• 三条命令依次显示上传成功、打印 selfcheck、显示删除成功。

注意：对象存储没有单独的加密选项。访问地址以 https:// 开头即为加密连接，此时证书须能被安装主机的系统信任库校验。

加密方式与 CA

使用现有 PostgreSQL 或 ClickHouse 时，安装器询问加密方式，三选一，缺省为明文：

注意：后两种都会校验证书与主机名，区别只在 CA 从哪里来。用 IP 访问而证书里只有域名时，校验会失败，要么改用证书里的域名作为访问地址，要么由数据库管理员重签证书。生产环境建议加密。

注意：安装器的依赖检测会创建并删除临时库（zenova_probe_<随机串>）或临时对象（zenova-probe/<随机串>），不写入业务数据。如果客户的数据库审计会对建库操作告警，提前告知数据库管理员。

3.6 上传物料与校验

前提：已按第 2 章取得安装器归档与离线包，并在联网机器上核对过。

暂存目录的选择规则：

本手册统一使用 /root/zenova-install 作为暂存目录。

操作步骤

1. 在安装主机上建暂存目录。

# 安装主机 · root · 写入（创建暂存目录）
install -d -m 0700 /root/zenova-install

2. 在存放物料的机器上，把两个文件传到安装主机的暂存目录。登录账号无权写 /root 时，先传到该账号的家目录，再在安装主机上以 root 移入。

# 物料所在机器 · 普通用户 · 写入（上传到安装主机）
scp zenova-<版本>-linux-amd64.tar.gz <离线包>.zpkg <账号>@<安装主机地址>:/root/zenova-install/

3. 在安装主机上核对安装器摘要。<安装器摘要> 取自下载站「安装器摘要（SHA-256）」一栏，两个空格分隔摘要与文件名。

# 安装主机 · root · 只读（核对安装器摘要）
cd /root/zenova-install
echo '<安装器摘要>  zenova-<版本>-linux-amd64.tar.gz' | sha256sum -c -

4. 核对离线包大小与下载站显示的「离线包大小」一致。

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

5. 解开安装器，查看安装器版本与产品。

# 安装主机 · root · 写入（在暂存目录解出 zenova 程序）
cd /root/zenova-install
tar -xzf zenova-<版本>-linux-amd64.tar.gz
./zenova --version

6. 查看离线包的产品、版本与通道。

# 安装主机 · root · 只读
tar -xOf <离线包>.zpkg release.json | grep -oE '"(edition|version|channel)": ?"[^"]*"'

7. 为后面的命令设置离线包变量。

# 安装主机 · root · 只读（仅设置当前会话的变量）
ZPKG=/root/zenova-install/<离线包>.zpkg

你会看到

• 第 3 步输出 zenova-<版本>-linux-amd64.tar.gz: OK。输出 FAILED 表示文件损坏或拿错，重新下载。
• 第 5 步输出一行，以版本号开头，后跟产品名（应为 Zentrix 网关）与括号内的构建提交。
• 第 6 步输出三行：产品（zentrix_gateway 或 zenova）、版本号、通道（stable 或 test）。

注意：以下三处必须一致，任何一处不符就不要继续，换用正确的文件：

1. ./zenova --version 的版本号与产品名；
2. release.json 中的 version 与 edition；
3. 下载站上选择的版本与产品。

安装器与离线包版本不一致时，安装器会直接拒绝（「安装器版本 … 与离线包版本 … 不一致」）；产品不一致时提示「安装包与安装程序不属于同一版本」。提前核对可以省下一次失败。

注意：离线包没有单独的校验文件。安装器启动后会按 release.json 记录的摘要逐个校验组件，摘要校验只用于发现下载损坏，不是签名校验。

3.7 网络与防火墙准备

适用场景：所有安装。与客户网络管理员一起完成，网络策略变更通常需要提前走审批。

入站放行项

不得对外开放的端口

以下端口监听在全部网卡上，供本机智能体容器回连宿主服务使用，不得在主机防火墙、云安全组或网络边界上对外放行：

其余内部服务只监听回环地址，不需要也不应从主机外访问。

出站需要放行的目标

安装过程本身不需要外网，安装所需内容都在安装器与离线包里。出站需求来自安装后要连接的对象，按交付范围逐项列出并请网络管理员放行：

远端网关节点主机还需要能访问控制面回连地址；该地址以 https:// 开头，放行的端口以回连地址中的端口为准。

操作步骤

1. 确认业务入口端口在安装主机上空闲（以 80 为例，换成你的本机监听端口）。

# 安装主机 · root · 只读
ss -lntp | grep -w ':80'

2. 确认主机使用哪种防火墙。

# 安装主机 · root · 只读
systemctl is-active firewalld
systemctl is-active ufw
systemctl is-active nftables

3. 主机使用 ufw 或 nftables 时，安装器不会处理，由主机管理员在安装后手工放行业务入口端口（及 443、分离后的管理入口端口）。
4. 把上面的出站清单交给网络管理员，确认现有依赖的地址在安装前已经可达。

# 安装主机 · root · 只读（检查到现有依赖的 TCP 连通性，以 PostgreSQL 为例）
timeout 5 bash -c '</dev/tcp/<数据库地址>/<端口>' && echo reachable

5. 安装完成后，核对防火墙与监听情况（第 4.6 节的「监听边界」验收也会检查本产品进程的监听范围）。

# 安装主机 · root · 只读
firewall-cmd --list-ports
ss -lntp

你会看到

• 第 1 步无输出，表示端口空闲；有输出时，最后一列是占用的进程，安装前先与客户确认能否停止它，或改用其他端口。
• 第 2 步中处于 active 的那一项就是本机使用的防火墙。
• 第 4 步输出 reachable。
• 安装完成后，firewall-cmd --list-ports 中出现业务入口端口与 443。

注意：安装器只在 Linux 首次安装时，把业务入口端口与 443 写入 firewalld 或 iptables。它不放行分离后的管理入口端口，不放行安装后在控制台修改过的入口端口，不处理 ufw 与 nftables。云主机还要另外在云安全组中放行。

注意：业务入口端口被占用时，安装会停在端口检查，不会自动更换；平台内部服务的端口被占用时，安装器自动顺延到下一个空闲端口并逐条说明，不需要处理。

能力说明

上一章：2. 从下载站取得安装物料 · 下一章：4. 交互式安装