排障
按初始化、登录、资源、支付、AI 和部署阶段定位问题，保留可复核证据。
先收集最小证据
记录当前 Git 提交、Node/pnpm 版本、操作 URL、执行命令、失败阶段和脱敏错误。区分本地 development、preview 与 production。不要发送真实 .env、Cookie、API Key、验证码、签名或订单个人信息。
初始化或类型检查失败
- 确认 Node 至少 22.12、pnpm 10.26.2，并在仓库根目录安装锁定依赖。
- 初始化命令是
pnpm muse:init；pnpm init是包管理器命令，不能替代应用初始化。 - 缺 routeTree 或 Paraglide：先 pnpm build 再 type-check，不手工创建替代文件。
- 本地缺表：检查 muse:init 的迁移输出和 Wrangler 本地状态目录。
- seed 密码不匹配：重复 init 保留已有密码，MUSE_SEED_PASSWORD 只影响首次创建。
登录、验证码和邮件
默认 /auth/login 发邮件验证码；密码登录位于 /auth/password。验证码请求成功后在本地 /dev/mail 查找消息；生产必须真实投递到邮箱。不要在验证码页寻找密码输入框。
- 验证码错误或过期：使用最新一封邮件，检查重发与验证流程，不重复使用旧码。
- 登录循环或 Origin 失败：对照 APP_URL 与浏览器 origin，包括 localhost 与 127.0.0.1 的区别。
- OAuth 按钮缺失：同一 provider 的 ID 和 Secret 必须都配置；检查公开 auth 配置。
- OAuth 回调失败：核对 /api/auth/callback/google 或 github 和最终 HTTPS 域名。
- Turnstile 失败：核对 TURNSTILE_SITE_KEY、TURNSTILE_SECRET 与允许域名。
- 生产邮件缺失：检查 EMAIL binding、验证发件域、MAIL_FROM 和服务响应，不能开放开发收件箱代替。
工作台与存储
401 先查会话或 Key 是否失效；403 再查角色、邮箱验证、资源归属及 Origin。文件 Key 仅开放文件接口，不能用于聊天或后台。
上传失败检查非零大小、1 MiB 上限、允许 MIME 与文件数量配额。文件列表存在但无法下载时，检查 R2_BUCKET 指向的目标 bucket 与对象，不直接给 bucket 开公共访问绕过权限。
后台表格只对已加载数据筛选分页。没有某条记录时先检查查询范围和目标环境，不把前端分页当全库结果。
AI 或任务没有结果
默认 remoteBindings 为 false，没有本地模型模拟器。先确认自己的 AI binding 可调用，再检查 prompt 长度、余额和模型响应。摘要只支持本人纯文本/Markdown，处理前 16,000 字符。
pending 任务查看 JOBS 队列、消费者、cron、outbox 与租约。重复重试不能重复扣费；未知结果先查状态，不能通过直接改余额解决。死信恢复保留后台权限与审计。
支付不可用或权益未到账
默认 billing.enabled 为空。启用网关后必须配置 defaultGateway、商品映射和完整 Secret。核对测试/正式环境一致，Webhook 为 /api/webhooks/<gateway>。
浏览器成功跳转不表示签名事件处理完毕。检查订单、Webhook 与账本，重复事件不重复发放积分。退款超时或未知结果先到网关确认；退款不自动等于取消续费，部分退款不自动按比例回退积分。
部署阻断、失败与 smoke
pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --json
pnpm muse:verify --target production --json- 缺变量：检查进程 > 根 .env > 目标 secrets JSON 的优先级。
- 错误账户：核对 Token、账户和本机 deployment 状态，不修改状态绕过保护。
- 意外 create：核对 target-resources 五个精确名称；升级不应无意创建空 D1/R2。
- 高风险 SQL：独立审查备份并处理，不删迁移检查。
- 构建规范失败：先修复具体诊断，再发布，不跳过 preflight。
- 自定义域 smoke 失败：检查 DNS、HTTPS 与 health 环境，等待生效后重新 verify。
- 回滚后数据库错误：Worker 回滚不撤销迁移，检查代码与 schema 兼容性。
退出码 2 是阻断，3 是 smoke 失败；命令 0 和 smokePassed 也不证明真实邮件、支付或 AI 已人工验收。需要完整流程时阅读 部署指南 与 测试指南。