常见问题

安装与启动

docker compose up 报 required variable … is missing

.env 缺少必填项。deploy.sh 生成全部必填项。手动安装时对照配置项参考补齐，常缺的是 RST_USER_DB_PASSWORD、CADDY_SITE_ADDRESS 和 QRADAR_SEC_TOKEN。

deploy.sh 报「缺少镜像，中止」

compose 文件用到的镜像不在本机。交付包内含网关、Caddy 和 PostgreSQL 镜像，缺少时重新下载交付包并校验 SHA-256。SSO 部署另需 oauth2-proxy 镜像，见 SSO。

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

执行 docker compose -f docker-compose.prod.yml logs caddy gateway 查看原因。常见的有两种：443 端口未放通，云主机需在安全组中放行；CADDY_SITE_ADDRESS 填了裸 IP 导致 HTTPS 握手失败，改为域名并配置 hosts。

写入 .env 的配置项没有生效

1.0.1 及更早版本的标准安装只把 docker-compose.prod.yml 中列出的配置项传入网关，例如 RST_OUTPUT_LANG、RST_PLATFORM_* 不生效。升级到 1.0.2 或更高版本。其他版本修改 .env 后，执行 docker compose -f docker-compose.prod.yml up -d 重建容器。

网关日志出现 /app/state is not writable by uid 10001

状态卷的属主不是 uid 10001，入口脚本也没能修正。执行 docker run --rm -v <卷名>:/s alpine chown -R 10001:10001 /s，然后重启网关。

QRadar 连接

readyz 返回 503

qradar 字段给出原因。not_configured 表示没有填写 Console。其他值是连接 Console 的错误：检查 QRADAR_URL、网关主机到 Console 443 的连通性和 SEC Token 是否过期。开启了证书校验而 Console 使用私有 CA 时，把 CA 放入 ./certs/ 并设置 RST_QRADAR_CA_CERT。

「QRadar 认证失败。请检查 SEC Token 是否有效、是否过期。」

Token 无效、过期，或授权服务被停用。在 Console 的 Admin > Authorized Services 中重新生成 Token，在系统设置中更换。

测试连接通过，但提示 Token 访问不了某些接口

Token 的用户角色缺少对应权限（Ariel、Offenses、规则或日志源）。按 QRadar Token 权限修改用户角色，执行 Deploy Changes 后重新测试。

「当前 Token 的安全配置没有权限访问该接口：…」

错误码为 qradar_forbidden。多数是用户角色缺少 Ariel 权限，也可能是安全配置文件没有覆盖目标日志源。处理方法同上。

登录

「该部署仍在使用出厂密码，已拒绝远程登录。」

未设置 RST_ADMIN_PASSWORD_HASH。deploy.sh 自动设置，手动安装见交付包安装。隔离的试验环境可以设置 RST_ALLOW_DEFAULT_PASSWORD=1。

已设置 RST_ADMIN_PASSWORD_HASH，登录仍被拒绝

哈希中的 $ 被 compose 当作变量展开。在 .env 中把每个 $ 写成 $$。

用户页提示没有配独立用户表

未配置 RST_USER_DB_URL。deploy.sh 默认配置并启动账号库，手动安装见用户。

修改角色后，对方仍按原角色操作

角色变更立即生效，但不结束对方的会话，对方刷新页面后界面随之更新。需要立即让对方下线时，选择 停用。

智能查询

查询结果为 0 条

Ariel 对 Token 看不到的日志源不返回数据，也不报错，因此 0 条无法区分没有数据和没有权限。先选择 把时间放宽到最近 7 天再问一次，再展开 AQL 核对 LOGSOURCENAME() 与 QIDNAME() 中的名称是否与 Console 一致，最后检查安全配置文件和日志源白名单。

「日志源 X 不在白名单内（RST_LOG_SOURCE_WHITELIST = …）」

AQL 引用了白名单之外的日志源。由管理员在系统设置的 日志源白名单 中添加。reason=unbounded 表示白名单展开超过 50 个日志源、语句带子查询，或日志源目录读取失败，网关无法自动限定，此时缩小白名单。

「AQL 被 QRadar 拒绝：…」

冒号后是 Console 返回的原文，常见原因是列名或函数用错。展开 AQL 选择 编辑 修改后执行，或换一种问法重新生成。

「QRadar 搜索超时（120s）…」

Ariel 搜索超过 RST_AQL_TIMEOUT_SECONDS 被取消。缩小时间范围，或在问题中限定日志源以减少扫描量。数据量大的站点可以调大该值。

问「今天」「昨天」时结果为空或差一天

RST_TIMEZONE 未设置，网关按 UTC 切分日界。国内部署设为 +08:00，重建网关容器。

「模型思考超过 45 秒仍未开始作答，已中止。」

模型端拥塞或思考模型推理过长。在 AI 配置中把该 provider 的推理强度设为关或低。上限由 RST_LLM_FIRST_TOKEN_TIMEOUT_S 调整。

Offense

Offenses 页一直为空

按顺序检查：系统设置中是否已连接 QRadar；同步设置 中是否打开了 启用轮询；RST_OFFENSE_INGEST_LOOKBACK（默认 7 天）内是否有 OPEN 状态的 Offense；最低 magnitude 是否设得过高；Token 的安全配置文件是否覆盖产生 Offense 的日志源和网络。网关日志中搜索 offense_ingest 查看同步记录。

Console 中已关闭的 Offense 在网关中仍为 OPEN

状态按 last_updated_time 刷新，在下一个同步周期（默认 30 秒）内更新。积压很大时网关日志出现 offense_ingest_page_cap_reached，需要等待几个周期。

「更新 Offense 失败：…」

关闭、备注或分配写回失败。常见原因是 Token 缺少 Offenses 的写权限，或该 Offense 已被其他人关闭。关闭原因列表来自 Console，重新打开详情刷新后再试。

批量分诊显示「AI 评分未完成」

模型评分超时或报错。把 送模型评分的聚类上限 调小，把 provider 的超时调到 300 秒以上，或把推理强度降到低。

批量分诊只拉到少量 Offense

默认时间窗为 1440 分钟，按 Offense 的开始时间计算。调大 时间窗（分钟），或检查同步的回看时长。

许可

激活失败，原因为主机名额已用完

该许可的主机名额已用完。在旧主机的 撤销激活 中选择 撤销当前 license，再在新主机激活。

离线激活失败，原因为主机不匹配

.lic 中的主机指纹与本机不符：state/machine-id 或 state/server_guid 被重建，或文件签发给了其他主机。从备份恢复原文件，或用本机指纹重新申请。

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

容器内读不到主机指纹文件。state/machine-id 或 state/server_guid 缺失（文件缺失时 Docker 挂载为目录），或权限不是 644。按交付包安装重新生成后重启。

已激活，付费引擎仍然锁定

在线许可在首次心跳成功后下发引擎密钥，在产品激活中查看最后一次心跳。离线许可确认 .lic 是为 RST AI Copilot for QRadar 签发的，RST AI Copilot for Elastic 的许可不通用。

许可状态为心跳丢失

在线许可超过 7 天没有连上许可服务器，付费引擎和查询都被锁定。检查网关主机到 license.reallysec.com:443 的出站网络，恢复后下一次心跳自动解除。

对外通道

邮件目标一直是待重试或已放弃

在 投递记录 中查看 最后错误。常见原因是没有配置邮件服务器、密码错误或 SMTP 端口被拦截。修复后选择 重投。

投递目标标记为密钥失效

网关重装后，旧的密文无法解开。编辑该目标，重新填写 Webhook 地址和密钥。

更新

更新后出现异常

执行 ./deploy/rst-update.sh --rollback 回到上一版本，或把 GATEWAY_IMAGE_TAG 改回上一版本后重启。

联系支持

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