交付包安装

用一条命令或手动下载交付包安装网关，离线主机安装，deploy.sh 的提问，安装后的验证，以及不使用 deploy.sh 的安装方法。

网关以交付包 RST-AI-Copilot-for-Zabbix-<版本>.tar.gz 发布在 GitHub Releases，同名 .sha256 文件用于校验，release-manifest.token 是 Reallysec 签名的版本清单。交付包内含镜像和部署文件，由其中的 deploy.sh 完成安装：加载镜像，收集配置，写入 .env，启动容器。install.sh 把下载、签名校验、解压和执行 deploy.sh 合为一条命令。

交付包内容

RST-AI-Copilot-for-Zabbix-<版本>/
├── RST-AI-Copilot-for-Zabbix-images-<版本>.tar   # 网关和 Caddy 镜像
├── deploy.sh                                 # 交互式安装脚本
├── docker-compose.prod.yml                   # 标准部署
├── docker-compose.sso.yml                    # SSO
├── Caddyfile、Caddyfile.sso
├── .env.example                              # 配置项及说明
├── deploy/rst-update.sh                      # 在线更新安装器
├── keycloak/                                 # SSO 演示环境的 Keycloak 配置
├── scripts/backup.sh、scripts/restore.sh
├── docs/                                     # INSTALL.md、LICENSING.md、BACKUP.md、SSO.md、EULA.md 等
└── THIRD-PARTY-NOTICES.md、CHANGELOG.md

用一条命令安装

前提条件

主机已安装 Docker Engine 24 及以上和 Docker Compose v2，以及 curl、tar、sha256sum、base64、openssl。
主机可以访问 github.com。
以 root 在交互式终端中执行，deploy.sh 需要读取输入。

步骤

执行安装命令：
```
curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Zabbix/releases/latest/download/install.sh | sudo bash
```
所有版本使用同一个交付包：未激活许可时以社区版运行，在设置 > 产品激活 中激活许可后，原地解锁对应版本的功能，不需要重装。
按 deploy.sh 的提示填写配置，见下文 deploy.sh 的提问。

脚本先下载签名的版本清单 release-manifest.token，用内置的 Reallysec 公钥验签，再下载交付包，SHA-256 与清单一致才继续，否则删除下载的文件并退出，不做任何安装。最新版本刚发布、清单还没上传时，脚本跳过它，安装最新的已签名版本。

校验通过后，交付包解压到 /opt/rst-ai-copilot-for-zabbix，再执行 deploy.sh。在同一台主机再次执行时，该目录中的 .env 和 state/ 保留，许可的主机指纹不变。因此同一条命令也用于升级。

选项	说明
`--version <x.y.z>`	安装指定版本，默认最新的已签名版本。指定的版本没有签名清单时不安装
`--dir <路径>`	安装目录，默认 `/opt/rst-ai-copilot-for-zabbix`
`--mirror github`、`--mirror cn`	选择下载来源。国内镜像暂未开通，`--mirror cn` 目前提示后直接从 GitHub 下载
`--download-only`	只下载并校验交付包，保存到当前目录，不安装

选项要放在 bash -s -- 后面：

curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Zabbix/releases/latest/download/install.sh | sudo bash -s -- --version 2.0.2

GitHub 下载速度连续 30 秒低于 10 KB/s 时，脚本按下载失败处理并退出。网络慢时可以在其他机器上用 --download-only 下载，再拷到目标主机，见下文。

在离线主机上安装

步骤

在可以访问 GitHub 的 Linux 机器上下载并校验交付包。这一步不需要 root 和 Docker：

curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Zabbix/releases/latest/download/install.sh | bash -s -- --download-only

把当前目录中的 RST-AI-Copilot-for-Zabbix-<版本>.tar.gz 拷到离线主机。

在离线主机上解压并执行 deploy.sh：

tar xzf RST-AI-Copilot-for-Zabbix-<版本>.tar.gz
cd RST-AI-Copilot-for-Zabbix-<版本>
sudo ./deploy.sh

离线主机上的许可需要离线激活（企业版），见产品激活。

手动安装交付包

步骤

从 GitHub Releases 下载 RST-AI-Copilot-for-Zabbix-<版本>.tar.gz 和同名 .sha256 文件。所有版本使用同一个交付包，由激活的许可决定开放的功能。

校验并解压：

sha256sum -c RST-AI-Copilot-for-Zabbix-<版本>.tar.gz.sha256
tar xzf RST-AI-Copilot-for-Zabbix-<版本>.tar.gz
cd RST-AI-Copilot-for-Zabbix-<版本>

执行 sudo ./deploy.sh，按提示填写配置。

.sha256 文件与交付包来自同一个地方，只能发现传输损坏。需要确认交付包确实由 Reallysec 发布时，使用 install.sh，它校验签名清单。

deploy.sh 的提问

脚本分七步执行：预检、加载镜像、检查现有 .env、部署形态、填写配置、写入 .env、启动。

预检检查 Docker、Docker Compose v2 和部署文件，并生成 state/machine-id。这个文件是许可的硬件指纹，已存在时复用。
已有 .env 时，脚本询问是否保留并直接启动，默认为否。升级时输入 y。选择否时，旧文件备份为 .env.<时间>.bak 后重新填写。
交付包只有标准部署形态，即连接客户已有的 Zabbix，这一步不需要选择。

提问	取值
LLM endpoint URL	默认 `https://ark.cn-beijing.volces.com/api/v3`
LLM API key	输入不回显
LLM model id	火山方舟填 endpoint id，例如 `ep-xxxxxxxxxxxxxx-xxxxx`；其他端点填模型名
Zabbix JSON-RPC URL	例如 `https://zabbix.corp.local/api_jsonrpc.php`
Zabbix API token	推荐填写。留空时改为询问 Zabbix 用户名（默认 `Admin`）和口令
Zabbix Web UI 地址	可选，「在 Zabbix 中打开」链接使用。留空时使用 JSON-RPC 地址的协议、主机和端口
Caddy 访问域名或 IP	使用者访问 `https://<域名>/v2/`，建议使用域名
管理员密码	管理员账号 `admin` 的密码，至少 8 位，输入两次。其他账号登录后在设置 > 用户中创建

脚本自动生成 RST_GATEWAY_SHARED_SECRET、RST_ADMIN_TOKEN 和管理员密码的哈希 RST_ADMIN_PASSWORD_HASH（用网关镜像计算），确认后写入 .env，权限 600。启动后最多等待 90 秒至全部容器 healthy，然后打印访问地址 https://<域名>/v2/、登录账号 admin 和 RST_ADMIN_TOKEN。RST_ADMIN_TOKEN 是运维 API 令牌，放在请求头 X-RST-Admin-Token 中供脚本使用，按密码保管。

deploy.sh 不配置 SSO。SSO 见 SSO。

验证安装

步骤

检查健康与就绪状态：

curl -k https://<域名>/healthz     # {"status":"ok"}
curl -k https://<域名>/readyz
docker compose -f docker-compose.prod.yml ps

打开 https://<域名>/v2/，确认跳转到登录页，以 admin 和安装时设置的密码登录。

readyz 正常时返回 {"status":"ready","zabbix":"ok","zabbix_major":"<主版本>"}。返回 503 时，zabbix 字段是原因：连接或认证错误的信息，或者 Zabbix 版本低于 6.0（code 为 zabbix_version_unsupported）。readyz 每次都实际调用一次 Zabbix，可以用作监控探针。

默认证书由 Caddy 内置 CA 签发，浏览器首次访问时提示不受信。生产环境修改 Caddyfile 中的 tls internal，换成自有证书。

不使用 deploy.sh 安装

步骤

加载镜像并准备 .env：

docker load -i RST-AI-Copilot-for-Zabbix-images-<版本>.tar
cp .env.example .env

在 .env 中填写 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL、ZABBIX_URL、ZABBIX_TOKEN、CADDY_SITE_ADDRESS，以及用 openssl rand -hex 32 生成的 RST_GATEWAY_SHARED_SECRET 和 RST_ADMIN_TOKEN。
生成管理员密码的哈希，写入 .env 的 RST_ADMIN_PASSWORD_HASH。哈希中的每个 $ 写成 $$：
```
docker run --rm rst-ai-copilot-for-zabbix-gateway:<版本> python -m backend.session_auth '<密码>'
# pbkdf2_sha256$600000$...  写成  pbkdf2_sha256$$600000$$...
```
不设置时使用出厂密码 admin / Admin@123，只允许从网关主机本机登录，浏览器远程登录返回 403。

生成主机指纹文件，只生成一次：

mkdir -p state
openssl rand -hex 16 > state/machine-id

执行 docker compose -f docker-compose.prod.yml up -d。交付包不含 Dockerfile，不要加 --build。

启动前 state/machine-id 必须存在。缺少时 Docker 在该位置创建一个目录，激活时报 no hardware identifier available。这个文件生成后不要重建，变化后许可需要重新激活。

后续操作

使用付费功能时，在产品激活中激活许可。
在设置中配置主机组白名单、脱敏模式和审计。
把 ./state/machine-id 和 gateway_state 卷纳入备份，见升级、回滚与备份。

本页内容