快速开始

单机安装只需要一台 Linux 主机、Docker、已有的 Zabbix 和一个 Zabbix API token，执行一次安装命令或 deploy.sh。SSO 和离线激活见安装。

前提条件

支持 Docker 的 Linux（Ubuntu 22.04 及以上、麒麟、统信等），推荐 2 vCPU、4 GB 内存、20 GB 磁盘。
Docker Engine 24 及以上，Docker Compose v2。
Zabbix 6.0、6.4、7.0、7.2 或 7.4，网关主机可以访问 Zabbix 前端的 api_jsonrpc.php。
一个 Zabbix API token，最好属于一个只读账号。权限要求见下文。
一个 OpenAI 兼容的大模型端点，以及 API key 和模型名。
一个访问域名，例如 copilot.corp.local。没有内网 DNS 时，在使用者的电脑上添加 hosts 记录。

入站只需放通 443，80 用于跳转，可选。出站需要访问大模型端点和 Zabbix。在线激活商业许可时，还需要访问 license.reallysec.com 443。使用在线更新时，还需要访问 github.com 443，版本清单和内容包从 GitHub Releases 读取。

安装

安装 Docker

主机已有 Docker 24 及以上时跳过。

curl -fsSL https://get.docker.com | sudo sh
docker compose version

下载交付包并执行 deploy.sh

一条命令完成下载、签名校验、解压和部署。在交互式终端中以 root 执行：

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

脚本先核对 Reallysec 签名的版本清单，交付包的 SHA-256 与清单一致才会安装。交付包解压到 /opt/rst-ai-copilot-for-zabbix，然后执行其中的 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

交付包内含网关和 Caddy 的镜像，安装时不访问镜像仓库。其他选项和离线安装见交付包安装。

填写部署选项

按提示填写大模型端点、API key 和模型名，Zabbix JSON-RPC 地址（以 /api_jsonrpc.php 结尾）和 API token，访问域名，以及管理员账号 admin 的密码（至少 8 位，输入两次）。其他账号登录后在设置 > 用户中创建。脚本生成内部密钥和密码哈希，写入 .env（权限 600），启动容器并打印访问地址。

脚本同时生成 state/machine-id。这个文件是许可的硬件指纹，生成后不可重建。

验证

curl -k https://copilot.corp.local/healthz   # {"status":"ok"}
curl -k https://copilot.corp.local/readyz    # {"status":"ready","zabbix":"ok","zabbix_major":"7.0"}

readyz 返回 503 时，zabbix 字段给出原因，通常是地址、token 或网络不对。

Zabbix 权限

网关能看到的数据由 API token 所属账号的用户组和用户角色决定。

项目	要求
用户组	对要查询的主机组有读权限。范围之外的主机和问题不显示
用户角色	开启 API 访问。确认、关闭问题和执行脚本需要角色中对应的动作权限；创建触发器和维护窗口需要 Admin 类型，并对目标主机组有读写权限

单独创建一个账号给网关使用，不复用 Super admin。完整说明见 Zabbix 权限。

后续操作

使用付费功能时，在设置 > 产品激活 中导入许可，不需要重装。未激活时以社区版运行，各版本区别见版本对比，步骤见产品激活。
在设置中配置主机组白名单、脱敏模式和审计。
用交付包中的 scripts/backup.sh 定期备份，它同时备份 gateway_state 卷和 state/machine-id。

升级

再次执行安装命令，或把新交付包解到同一目录后执行 sudo ./deploy.sh，询问是否保留现有 .env 时输入 y。2.0.1 及更早版本在线更新到 2.0.2 会失败，需要这样手动升级一次，安装脚本会沿用老目录 /opt/rst-zabbix-ai-copilot。见升级、回滚与备份。

不要重建 state/machine-id，不要执行 docker compose down -v。这个文件或 gateway_state 卷变化都会被许可视为更换硬件，需要重新激活。

排障

/v2/ 无法打开

执行 docker compose -f docker-compose.prod.yml logs caddy gateway 查看日志。在防火墙或安全组放通 443，确认 CADDY_SITE_ADDRESS 正确。

浏览器登录 admin 返回 403

.env 中没有 RST_ADMIN_PASSWORD_HASH，出厂密码只允许从网关主机本机登录。生成哈希写入 .env（每个 $ 写成 $$），再执行 docker compose -f docker-compose.prod.yml up -d：

docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<密码>'

忘记密码时，由其他管理员在用户页重置。

readyz 返回 503

ZABBIX_URL 要带 /api_jsonrpc.php。再检查 token 是否有效，以及网关主机到 Zabbix 的网络。Zabbix 低于 6.0 时 code 为 zabbix_version_unsupported。

许可突然失效

state/machine-id 被重建，或 gateway_state 卷丢失。从备份恢复。

其他症状见常见问题。

本页内容