常见问题
装不起来、登不进去、查不到、激活不了、模型慢：按症状找原因和解法。
安装与启动
deploy.sh 起不来，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 里 es: ping 或 es_write: denied
前者连不上 ES（地址 / 证书 / 网络），后者账号缺 .rst_copilot_* 的建 / 写权限。见 ES 权限。
网关日志 /app/state is not writable by uid 10001
老部署的状态卷是 root 建的。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；手动安装见用户。
改了角色 / 停用了账号，对方还在操作 停用会立刻踢掉会话；改角色立即生效但不踢。对方刷新页面就能看到。
智能查询
查询报错或结果为空 先看卡片上的提示，多数情况已经给出原因：时间窗不对（有「改查」按钮）、条件卡住了（有「去掉某条件后有 N 条」）、索引选错了（有「在别处有命中」）。再看：索引在不在白名单里、模型 key / endpoint 对不对。
「索引 X 不在授权白名单内」 系统设置加索引模式，或让管理员加。
问「今天 / 昨天」查出来是空的或差一天
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 分钟内），产品激活页看「最后一次心跳」。离线许可：1.1.20 之前签的不带三个新引擎的密钥，重签。
状态「宽限期内」/「心跳丢失」
网关连不上 license.reallysec.com:443。检查出站；超过宽限期自动失效。
告警与分诊
实时告警页一直是 0
RST_ALERT_INGEST_INDEX 指向的索引没有新告警，或 ES_USER 没有 .alerts-security.alerts-* 的读权限。网关日志搜 alert_ingest。
批量分诊「AI 评分未完成」 模型超时。减少「送模型评分的聚类上限」（10 是个能用的值），或给 provider 加超时。
分诊只拉到很少几条 默认时间窗 60 分钟。改大（最多 7 天 = 10080）。
知识库
处置手册页提示「未启用」 没配向量模型。AI 配置 → 知识库向量模型测试并保存。
保存向量模型被拒绝，提示维度不一致
换了模型。删掉 .rst_copilot_kb 索引重建，再重新上传文档。
通知
邮件目标一直「待重试」/「已放弃」 投递记录里看最后错误。多半是没配发件服务器、密码错、或 SMTP 端口被拦。修好后「重投」。
飞书目标标「密钥失效」 网关重装后旧密文解不开。编辑目标重填 Webhook 和密钥。
升级
升级后报告显示「旧格式报告」 旧版结构，重新生成即可。
更新后异常
./deploy/rst-update.sh --rollback，或把 GATEWAY_IMAGE_TAG 改回上一版重启。
还是不行
docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log，连同 readyz 的输出发给 support@reallysec.com。日志里不含你的日志内容和密钥。