常见问题

安装与启动

install.sh 报 Docker Engine 24+ is required 或 Docker Compose v2 is required

主机没有 Docker，或只有旧版 docker-compose。先装 Docker Engine 24 及以上和 Compose v2 插件（docker compose version 能输出版本号），再重新执行安装命令。要求见环境要求。

install.sh 报 openssl is required、run as root 或 run this from an interactive terminal

安装脚本用 openssl 验证发布签名，缺少时按提示安装。脚本需要 root，用 curl … | sudo bash 执行。脚本最后会运行 deploy.sh 逐项提问，必须在交互式终端中执行，不能放进 CI 或无终端的远程命令。

install.sh 输出「China mirror not configured yet (set RST_COS_BASE); skipping it」

这是正常情况。国内镜像（--mirror cn）暂未开通，脚本跳过它，直接走 GitHub。如果 GitHub 也连不上，脚本报 could not download a signed release，稍后重试即可。GitHub 下载太慢时，在能访问 GitHub 的机器上执行 install.sh --download-only，把校验过的安装包拷到目标主机，解压后运行 ./deploy.sh。

install.sh 报 release signature check FAILED 或 is not the signed release

下载到的清单或安装包与 Reallysec 的签名不符，脚本已删除文件，没有安装任何东西。不要绕过校验，换一个网络重试。仍然失败时联系支持。

install.sh 输出 is not signed yet

最新版本刚发布，签名清单还没上传。脚本会自动安装最近一个已签名的版本。几分钟后重新执行可以装上最新版。

https://<域名>/v2/ 无法打开

执行 docker compose -f docker-compose.prod.yml logs caddy gateway 查看原因。常见的是 443 端口没有放通，云主机需要在安全组中放行，或 CADDY_SITE_ADDRESS 填错。

密码正确，登录仍提示「用户名或密码错误。」

.env 中 RST_ADMIN_PASSWORD_HASH 的 $ 没有写成 $$，compose 把哈希当成了变量。改好后执行 docker compose -f docker-compose.prod.yml up -d。deploy.sh 生成的 .env 已经处理过。

Zabbix 连接

readyz 返回 503

/readyz 每次都会实时连一次 Zabbix，返回体中的 zabbix 字段写明原因。检查 ZABBIX_URL、网关主机到 Zabbix 的网络，以及 API token 或账号。在设置的 Zabbix 连接 中选择 测试连接，可以看到具体错误。

「无法连接 Zabbix API。请检查 Zabbix 是否在线、ZABBIX_URL 配置是否正确。」

错误码 zabbix_unreachable。网关连不上 Zabbix：地址或端口不对、防火墙拦截，或 Zabbix 前端没有运行。ZABBIX_URL 用 https:// 时网关默认校验证书，证书不受信任也会连不上。

「该地址不是 Zabbix API（应以 /api_jsonrpc.php 结尾）。」

地址能访问，但返回的不是 Zabbix JSON-RPC。把 ZABBIX_URL 改成 https://<Zabbix 前端>/api_jsonrpc.php。

「Zabbix API 认证失败。请检查 API token 或用户名 / 密码。」

token 已过期、被删除或被停用，或者用户名、密码错误。在 Zabbix 的 用户设置 > API tokens 中重新生成 token，在 设置 中更换。账号权限要求见 Zabbix 账号权限。

「Zabbix X 不受支持：需要 6.0 或更高版本」

错误码 zabbix_version_unsupported。网关只支持 Zabbix 6.0 及以上版本，已验证 6.0、6.4、7.0、7.2 和 7.4。5.x 及更早版本需要先升级 Zabbix。

「连接地址已改，请重新填写密码 / API key」

在 设置 中修改了 Zabbix 地址。已保存的凭据只发往原来的地址，换地址后需要重新填写 token 或密码。

查询结果为空

先确认 Zabbix 里这段时间确实有数据。再检查设置中的 主机组白名单：白名单外的主机组不会被查询。最后检查 Zabbix API 账号的用户组是否有这些主机组的读权限，Zabbix 对没有权限的主机直接不返回数据，不会报错。

「主机组 X 不在白名单内」

错误码 index_not_whitelisted。问题涉及的主机组不在主机组白名单中。由管理员在 设置 的 主机组白名单 中添加。

模型调用

「模型调用超时」

错误码 llm_timeout。模型端拥塞或响应过慢。稍后重试，或在 AI 配置中调大该 provider 的超时时间。

「模型服务暂不可用：所有已启用的 provider 都未成功。」

错误码 llm_unavailable。检查 AI 配置中的 API key、模型名和 base url，以及网关主机到模型端点的出站网络。完全离线的环境需要使用内网自建的 OpenAI 兼容模型服务。

配了多个 provider，第一个出错时没有切到备用

多模型故障转移是企业版功能。社区版和专业版只使用列表中第一个启用的 provider，AI 配置页显示「企业版才切换」。

「AI 请求失败，请稍后重试。」或「模型返回的内容无法解析。」

错误码 llm_request_failed、llm_unparseable。provider 返回的原始错误只写入服务端日志。执行 docker compose -f docker-compose.prod.yml logs --since 30m gateway，搜索 llm_call_failed 查看原因。

「请求过于频繁，请约 N 秒后重试。」

错误码 rate_limited。生成查询等 AI 接口默认每个来源 IP 每分钟 30 次。多人共用一个出口 IP 时更容易触发。

许可

激活时报「无法连接 license 服务器」

网关主机到 license.reallysec.com:443 的出站没有放通。放通后重试。不能联网的环境用离线激活，见产品激活。

激活时报「license 服务器拒绝激活」

冒号后是许可服务器给出的原因。常见的是许可的主机名额已用完：在旧主机的 撤销激活 中选择 撤销当前 license，再在新主机激活。也可能是 state/machine-id 被重新生成，主机指纹变了，此时从备份恢复原文件，或联系我们核查。

激活时报「license 属于其它产品」

这个 license 是为其他产品签发的，例如 RST AI Copilot for Elastic 或 QRadar 的许可不能用于 Zabbix。联系销售获取本产品的许可。

离线激活提示需要企业版

离线激活使用企业版许可签发的离线令牌。专业版许可请用在线激活。

「无法读取本机硬件标识」

容器内读不到 /etc/machine-id。检查部署目录下 state/machine-id 是否存在，以及是否挂载进了网关容器。不要重新生成这个文件，重新生成等于换了一台机器，现有许可会失效。

已激活，付费功能仍然锁定，提示需要许可

错误码 feature_sealed。触发器与监控配置功能的核心代码加密随镜像交付，需要许可中的功能密钥才能解开。离线许可签发时漏了功能密钥，会出现这种情况，联系我们重新签发。其他功能锁定时，在产品激活页查看 已解锁功能，确认许可的版本。

许可状态为心跳丢失、已过期或已吊销

在线许可超过 7 天没有连上许可服务器，或许可过期超过 7 天宽限期，或被吊销，产品回退到社区版：免费功能照常使用，付费功能暂停，账号和数据都保留。心跳丢失时恢复到 license.reallysec.com:443 的网络即可自动恢复。过期或吊销需要联系销售，拿到新的 license key 后重新激活。

许可状态为无效

许可校验没有通过，签名、所属产品或主机绑定不匹配。此时除登录、许可协议和产品激活页外，其他接口都被拒绝。确认粘贴的是与本机绑定的 license key 后重新激活。

登录与席位

「启用的账号数超过了当前许可的 N 个用户席位……」

错误码 seats_exceeded_admin_only，只在开启多用户密码登录后出现。启用的账号数超过了当前许可的用户数：社区版 1 个，试用最多 10 个，专业版和企业版按许可的用户数。常见原因是许可过期或换成了用户数更少的许可。管理员登录后，在用户中停用多余账号，或续期、增购用户数。账号和数据不会被删除。

新建或启用账号时弹出升级提示

错误码 users_need_professional（社区版只能有 1 个用户）或 user_seats_exhausted（许可的席位已用完）。启用的账号已达到许可的用户数。停用一个账号，或激活用户数更多的许可。

「该账号仍在使用出厂默认密码，禁止远程登录。」

.env 中没有 RST_ADMIN_PASSWORD_HASH，管理员账号还是出厂密码，常见于从 2.0.0 升级的部署（deploy.sh 新装时会设置）。执行 docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<密码>'，把输出写进 .env 的 RST_ADMIN_PASSWORD_HASH=（每个 $ 写成 $$），再执行 docker compose -f docker-compose.prod.yml up -d。也可以在网关本机登录后修改密码。

「登录失败次数过多，请稍后再试。」

5 分钟内同一来源或同一账号输错 10 次，登录被暂时锁定。等 5 分钟后重试。

「使用前请先阅读并同意最终用户许可协议」

错误码 eula_not_accepted。当前账号还没有同意这一版许可协议。在弹出的协议页面阅读后选择同意。

内容包

内容包没有自动启用

按顺序检查：

1. .env 中是否设置了 RST_CONTENT_AUTO_APPLY=0。设为 0 时，新内容包验签后只保存在本机，不会自动生效。管理员在设置的 内容包 > 回滚 列表中找到该版本，选择 回滚到此版本 使其生效。
2. 是否检查过更新。新内容包随在线更新的检查获取：网关每天自动检查一次，管理员也可以在 在线更新 中选择 立即检查。
3. 是否是离线激活。离线激活的部署不会连接更新源，内容包需要在 内容包 > 导入内容包 中粘贴签名令牌导入。

验签失败、版本比当前旧的内容包会被拒绝，错误码为 content_pack_rejected。

在线更新

在线更新看不到新版本

按顺序检查：

1. 选择 立即检查。网关每天自动检查一次，刚发布的版本可能要等到下次检查。
2. 网关主机能否访问 github.com。连不上时检查静默失败，页面仍显示上一次的结果或「未检查」。网关日志中搜索 update_check_failed 查看原因。
3. 是否是离线激活。离线激活的部署不连接更新源，用新交付包离线升级，见升级与备份。
4. 新版本是否刚发布。签名清单上传前，这个版本不会出现在更新中，几分钟后再查。

已显示「已暂存」，版本还是旧的

网关只负责下载和校验，安装要在主机上完成。在部署目录执行 sudo ./deploy/rst-update.sh。健康检查失败时脚本自动回滚。

更新后出现异常

执行 sudo ./deploy/rst-update.sh --rollback 回到上一个版本，或把 .env 中的 GATEWAY_IMAGE_TAG 改回旧版本后执行 docker compose -f docker-compose.prod.yml up -d。

联系支持

执行 docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log，把 gateway.log 和 /readyz 的输出发送到 support@reallysec.com。