排障与常见问题
这页写给管理员和部署运维，按员工报上来的症状组织。每条按「先看哪里 → 可能原因 → 处理」排。
员工自己能查的部分（登录状态、本机配置）写在企业登录和企业 policy 与安全边界，这页只写需要管理台或服务端才能查的。
第一步：让员工跑自检
几乎所有「某个功能没生效」的问题，先让员工执行：
sid-code auth status --verify它先列本机记录的登录信息，再逐条探测七条企业通道，结果类似：
服务端核验: ✓ 凭据有效
企业通道（backend.url = https://agent.example.com/traj，来源 settings）:
登录 ✓ /api/v1/ctl/whoami 200
策略 ✓ /api/v1/ctl/policy 200
预算 ✓ /api/v1/ctl/budget 204
账本 ✓ /api/v1/usage/ledger 400（鉴权已通过，空 body 被拒，未写库） · 待重放 0 条
事件 ✓ /api/v1/events 202（空批次，未写库） · 磁盘缓存 0 批
flag ✓ /api/v1/ctl/flags 200
轨迹 ✗ 未配置 backend.url几点说明：
- 不加
--verify时不发任何网络请求，只读本机记录。 - 账本和事件两条用空请求探测：账本收到 400、事件收到 202 都说明鉴权已经通过，不会写库。
- 预算、策略返回 204 是正常的，表示服务端没有给这台设备配置。
- 「待重放」「磁盘缓存」不为 0 且一直在涨，说明这台设备之前上报失败过，正在等重放。
- 轨迹一行看的是
trace.upload，和backend.url是两套配置，见轨迹采集与可观测。
员工说「策略没生效」
| 先看哪里 | 看到什么 | 处理 |
|---|---|---|
员工有没有重启或执行 /login | 没有，会话是策略改之前开的 | 交互会话最迟约 33 分钟内会拉到；-p 无头调用不轮询，要等下次启动。急的话让员工 /login |
| 「设备」页这台设备的「生效配置」 | 命中的不是你改的那一层 | 下层有一份策略把它遮住了。策略只取一层、不合并，见策略 |
| 「策略」页「预览命中」 | 三层都没有 | 设备不在你以为的团队里。飞书登录的新设备默认不在任何团队，见组织与团队 |
| 「审计」页「策略与护栏是不是在拦东西」 | policy applied 为 0，policy none/error 不为 0 | 客户端拉不到策略。让员工跑自检，看「策略」一行 |
| 员工的 sid-code 版本 | 低于支持策略轮询的版本 | 升级客户端 |
策略拉取失败时客户端是 fail-open：有 10 分钟内的缓存就用缓存，否则按没有远程策略运行。所以「拉不到」的表现就是「没生效」，不会报错拦住员工。
系统提示词里那段「哪些操作被禁止」的说明在会话中途不会刷新，但权限检查本身已经生效。员工看到模型「不知道」某个操作被禁，不代表策略没生效。
员工说「被预算停了，但我没花那么多」
按顺序核对：
- 命中的是哪一层。「成本」页预算区「预览命中」输入他的设备 ID。命中团队层或组织层时，算的是整个团队或组织的花费，不是他一个人的。
- 周期按 UTC 划分。北京时间早上 8 点前的花费算在前一天。月预算在每月 1 日 08:00（北京时间）才清零。
used_usd含辅助调用。标题生成、子代理、分类器的花费都算在内。- 超限动作。只有「硬拦」才会结束会话；「告警放行」只提示不停。
员工本地的 costLimit 也会停会话，提示文字不同：远程预算的提示以「远程预算」开头，本地的不是。见配额与成本控制。
飞书登录失败
看浏览器地址栏的 ?error=，对照表见用户与登录。部署侧最常见的三种：
| 症状 | 原因 | 处理 |
|---|---|---|
invalid_state，反复出现 | 用户从一个域名发起登录，回调到了另一个域名（典型是带 www 和不带 www），state 带不回来 | 让 PUBLIC_BASE_URL、飞书后台登记的回调地址、员工实际访问的地址三者一致 |
| 飞书页面提示重定向地址不合法，或回调 404 | PUBLIC_BASE_URL 少了路径前缀，或飞书后台登记的地址和它不一致 | 回调地址必须是 <PUBLIC_BASE_URL>/api/v1/auth/feishu/callback，逐字一致 |
tenant_mismatch | 不是本企业的飞书账号，或 FEISHU_TENANT_KEY 填错 | 核对租户 key，见部署与配置 |
feishu_failed | App Secret 错，或应用改了配置没发布新版本 | 查后端日志；在飞书开放平台创建并发布版本 |
管理台显示「没有管理台权限」
此人是 member。在「用户」页把他设成 admin，对方刷新页面即可。见用户与登录。
员工端 sid-code login 报 409
这台设备已经绑给另一个人。让原用户在这台电脑上 sid-code logout；原用户已经离职、无法操作时，吊销原用户。见用户与登录。
员工端所有企业功能都是 401
| 先看哪里 | 原因 |
|---|---|
| 「设备」页这台设备的状态和「变更记录」 | 设备被吊销 |
| 「用户」页此人的状态 | 此人被吊销，名下所有设备一起失效 |
| 员工端自检的「服务端核验」 | 凭据过期（连续 90 天没用） |
设备或凭据的问题，员工重新 sid-code login 即可。此人被吊销时登录会被拒，要先在「用户」页恢复。
插件装不上
| 现象 | 原因 | 处理 |
|---|---|---|
| 员工端说插件不存在（404） | 条目对他不可见（可见团队不包括他的设备），或版本还是草稿。两者服务端不区分 | 核对条目的「可见范围」和设备的团队；确认版本已发布 |
| 410 | 这个版本已下架 | 发布新版本 |
| 被策略拦下，提示来源不在白名单 | 策略里开了「限制插件来源」，白名单没有企业市场 | 在策略里加上企业市场的 index URL，见策略 |
| 下载后校验失败，拒绝安装 | 包内容和登记的哈希不一致 | 不要让员工绕过。联系部署运维检查存储，必要时重新上传新版本 |
| 装上了但没有新版本提示 | 企业市场默认只提示、不自动升级；hooks 或 MCP 有变化的版本不会静默升级 | 让员工 /plugin update，见插件市场 |
飞书文档工具报错
员工在 Agent 输出里看到的提示原文：
| 提示 | outcome | 处理 |
|---|---|---|
这台设备还没有用飞书身份登录，请先执行 sid-code login。 | not_logged_in | 设备是注册码设备或没登录。员工用飞书 sid-code login |
还没有飞书文档授权，请执行 sid-code login 完成飞书授权。 | reauth_required | 员工登录时后端没保存 token，常见于 TOKEN_ENC_KEY 是后来才配的。重新登录 |
飞书授权已失效，请重新执行 sid-code login。 | reauth_required | refresh token 过期或被撤销。重新登录 |
需要补充飞书授权：执行 sid-code login 重新授权。缺少的权限：… | scope_missing | 先确认 FEISHU_LOGIN_SCOPE 和飞书后台都开了缺少的权限，再让员工重新登录 |
| 飞书暂时不可用，请稍后再试。 | unavailable | 飞书侧故障或限流 |
整个 MCP 返回 503 时，是服务端没配 TOKEN_ENC_KEY 或飞书登录没配齐。完整枚举见飞书文档授权。
审计页、成本页看不到某台设备
| 先看哪里 | 原因 |
|---|---|
| 员工的隐私级别 | no-telemetry 或 essential-traffic 会停掉事件和账本上报 |
| 员工端自检 | 没登录、凭据失效，或 backend.url 配错了 |
| 自检里「待重放」「磁盘缓存」 | 一直在涨：网络到不了后端，或后端 5xx |
| 「设备」页「最近活跃」 | 很久没有活跃：这台设备根本没在用 |
只在轨迹页能看到、审计页看不到的设备，通常是员工开了 no-telemetry：它停掉事件和账本，但不停轨迹上传（essential-traffic 才停）。反过来，轨迹上传走的是 trace.upload 和共享口令，和 backend.url、登录无关，两边的覆盖范围本来就不同。各隐私级别停掉什么，见隐私与数据流向。
服务端问题
| 症状 | 原因 | 处理 |
|---|---|---|
| 进程启动即退出 | 缺 AUTH_PASSWORD 或 UPLOAD_TOKEN；LOG_LEVEL / LOG_FORMAT 取值不认识 | 补齐，见部署与配置 |
| 启动日志提示 schema 版本不一致 | 升级后没跑迁移 | 备份后 alembic upgrade head。后端不会自动迁移 |
| 改了应急口令，所有人都被踢下线 | 没单独配 SESSION_SECRET，会话密钥由口令推出 | 单独配置 SESSION_SECRET |
| 签发遥控会话返回 500 | 没配 BRIDGE_WS_PUBLIC_URL | 见遥控 |