排障 runbook
部署/登录/域名/迁移/邮件/通知常见故障的定位顺序。
排障顺序：先看版本与健康 → 再看域名/会话 → 再看数据/迁移 → 最后看外部依赖。 不要一上来改代码。
0. 先收集现场
curl -sS https://<domain>/api/health
pnpm exec wrangler tail <worker> --env <env>记录：Version ID、migrationCount、latestMigration、错误码、请求时间、Host。
1. 页面 404 / 打不开
| 现象 | 常见原因 | 处理 |
|---|---|---|
www 或 console 上 /admin 404 | 域名职责分离：后台只在 CRM 域 | 改用 https://crm.<domain>/admin |
| 全站 404 | Custom Domain 未挂到 Worker | 查 deploy.sh <env> domain，必要时 --apply |
| 522/1016 | DNS 未生效或源站不可达 | 查 DNS/CNAME 与 Worker 路由 |
| 静态资源 404 | 部署产物不完整 | 重新 build + deploy，确认 .open-next/assets |
2. 登录失败
| 状态 | 原因 | 处理 |
|---|---|---|
| 401 | 账号不存在/密码错/会话过期 | 用 seed 账号核对；必要时重置密码 |
403 ACCOUNT_SUSPENDED | 平台账号被停用 | 运营在 CRM 恢复 |
403 EMAIL_UNVERIFIED | 注册后未验证 | 重发验证邮件或运营人工确认 |
| 423 | 登录失败次数触发锁定 | 等待锁定窗口或管理员解锁 |
/admin 登录 401 | 打错域名（用了 console/www） | 改用 CRM 域 |
3. 部署后 500
- 看
wrangler tail的首个堆栈，不要只看最后一行。 - 查
/api/health：migrationCount是否落后于代码。 - 跑
./deploy.sh <env> plan，确认「待应用 migration」为空。 - 缺 secret（
PAYLOAD_SECRET）会导致启动失败；首次部署后跑secret。 - 若仍 500，按回滚 runbook 回上一版本，保留日志。
4. 迁移漂移 / D1 报错
no such column：代码比 D1 新 → 先migrate，不要手工加列。UNIQUE constraint：看业务幂等键是否被绕过（订单/事件/通知）。SQLITE_BUSY：本地多进程抢同一 sqlite；确认只起一个 dev server。- 破坏性迁移（删表/删列）：先备份，再执行；不要依赖
down()。
5. 邮件/通知
- 邮件 outbox 一直
queued：检查MAILER_PROVIDER/RESEND_API_KEY/
MAILER_FROM；未配置时是 inert，不是故障。
notification-emails有行但没发：看attempts与last_error；3 次后failed。- 站内通知未读不消：
POST /api/console/notifications/read（org 级全部已读）。 - 到期提醒重复：看
event_key是否按notice_expiring:{instance_id}:{date}幂等。
6. 工单/附件
- 附件上传 415：只接受 PNG/JPEG/PDF，且 Content-Type 与 magic bytes 必须一致。
- 附件下载 403：签名 URL 10 分钟过期；重新上传/重新获取。
- 工单 404：跨 org 访问；确认当前账号的 org 与工单
org_id一致。
7. 何时升级给平台
以下情况不要自行处理，带现场信息联系平台：
- 需要恢复 D1 备份或修改表结构；
- 授权/订单状态不一致（已付款未签发）；
- 安全事件（Token 泄露、异常登录）；
- 连续两次回滚仍无法恢复。