常见问题

安装与启动

docker compose up 报 required variable … is missing

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

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

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

readyz 返回 not_ready，或 es_write 为 denied

es 字段不是 ok 时，网关无法连接 Elasticsearch，检查地址、证书和网络。es_write 为 denied 时，账号缺少 .rst_copilot_* 的建索引与写权限，按 Elasticsearch 权限 授权。

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

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

登录

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

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

已设置 RST_ADMIN_PASSWORD_HASH，登录仍被拒绝

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

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

未配置 RST_USER_DB_URL。deploy.sh 默认配置并启动 userdb，手动安装见 用户与角色。

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

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

智能查询

查询报错或结果为空

结果卡片上的提示通常已给出原因和下一步操作，见 结果为空时。卡片没有提示时，检查索引是否在白名单内，以及模型的 key 和 endpoint 是否正确。

「索引 … 不在白名单内」

目标索引不匹配 RST_INDEX_WHITELIST 中的任何模式。管理员在 系统设置 的 索引白名单 中添加模式。

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

未设置 RST_TIMEZONE，网关按 UTC 划分日界。设置为当地时区，例如 +08:00。

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

模型端拥塞，或思考模型推理时间过长。在 AI 配置 中把该 provider 的 推理强度 设为 关 或 低，或添加备用 provider。超时上限由 RST_LLM_FIRST_TOKEN_TIMEOUT_S 设置。

同一个问题再问一次，结果不同

同一会话中的追问带有上一轮的上下文，包括索引和指代。需要不受上文影响时，选择 新会话 后再问。

许可

activation limit reached

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

Offline license is bound to a different host

.lic 中的指纹与本机不符。原因是 state/machine-id 或 state/server_guid 被重建，或文件签发给了其他主机。

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

容器内读不到 /etc/machine-id。state/machine-id 未挂载（文件缺失时 docker 会挂载成目录），或文件权限不是 644。

已激活在线许可，付费功能仍然锁定

付费引擎在第一次成功心跳后解锁。等待心跳（失败时每 5 分钟重试一次），在 产品激活 页查看 最后一次心跳。

许可状态为「宽限期内」或「心跳丢失」

网关无法连接 license.reallysec.com:443，检查出站网络。失联超过离线宽限期后，许可自动失效。

告警与分诊

实时告警页一直为 0

RST_ALERT_INGEST_INDEX 指向的索引没有新告警，或 ES_USER 没有 .alerts-security.alerts-* 的读权限。在网关日志中搜索 alert_ingest。首次开启摄取时默认只回溯 1 小时，用 RST_ALERT_INGEST_LOOKBACK 扩大回溯窗口。

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

模型调用超时。调低 送模型评分的聚类上限（默认 30，10 通常可行），或提高 provider 的超时。

分诊只拉到少量告警

时间窗（分钟） 默认 60。调大该值，最大 10080（7 天）。

知识库

「处置手册未启用，请联系管理员在服务端开启向量模型」

未配置向量模型。在 AI 配置 中测试并保存一个向量模型。

保存向量模型时提示维度不一致

新模型的维度与已有 .rst_copilot_kb 索引不同。换回原模型，或删除 .rst_copilot_kb 索引后重新上传文档。

通知

邮件目标一直为「待重试」或「已放弃」

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

通知目标标记为「密钥失效」

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

更新

更新后出现异常

执行 sudo ./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。网关日志不含业务日志内容和密钥。