IWish Auth开发者文档
V1 Alpha GitHub
迁移/故障排查

故障排查

稳定错误码、诊断顺序和常见问题

先按错误发生阶段定位，不要通过关闭 state、PKCE、权限检查或扩大 callback allowlist 来“修复”登录。

1. 快速诊断顺序

  1. 确认 Auth API /health 可访问。
  2. 确认 App 服务端环境变量完整，值来自当前环境。
  3. 检查 OAuth client 状态、App 状态和组织开通状态。
  4. 对比实际 callback 与登记 redirect URI，逐字符检查。
  5. 检查浏览器是否保存 state/verifier cookie。
  6. 检查 token exchange 的稳定错误码。
  7. 检查 App session introspection 和权限上下文。

不要在日志中打印 code、verifier、client secret 或 session token。

2. 登录跳转错误

sso_client_not_found / sso_client_disabled

检查 IWISH_AUTH_CLIENT_ID 是否属于当前环境，client 是否启用。不要复用其他 App 或生产环境 client。

sso_redirect_uri_not_allowed / invalid_redirect_uri

实际 redirectUri 必须与登记值完全一致。常见差异：localhost 与 127.0.0.1、端口、HTTP/HTTPS、路径和尾部斜杠。

sso_organization_not_allowed

用户不属于目标授权域，或组织没有开通当前 App。由管理员检查组织成员和 App 开通关系。

3. Callback 错误

sso_state_mismatch

确认 login 和 callback 使用同一域、cookie Path 为 /、反向代理没有改写 Host/协议、浏览器没有阻止 cookie。不要跳过 state 校验。

sso_callback_incomplete

缺少 code 或 PKCE verifier。检查短时 cookie、callback route 和中间代理查询参数。

sso_invalid_grant

Code 已过期、被重复消费、verifier 错误或 redirect URI 不一致。重新从登录入口开始，不要重试同一个 code。

sso_invalid_client

检查 client secret 是否当前版本。Secret 轮换后旧 secret 和现有 sessions 会失效。

4. Session 与权限错误

missing_app_session

没有 App cookie/Bearer token，或 cookie 名称不一致。返回登录入口。

sso_session_expired / sso_session_revoked

清理本 App cookie并重新登录。不要循环调用 introspection。

app_session_mismatch

当前 App 收到了其他 App 的 session。检查 cookie 域、名称和反向代理，不要放宽 appKey 校验。

permission_not_granted

用户已登录但没有权限。检查 Manifest 是否同步、组织是否开通 App、角色是否分配、角色是否包含该 permission。403 不应触发重复登录。

5. 飞书问题

业务 App 不直接排查飞书 API。平台管理员在 IWish Auth Admin 检查同步状态和历史。

feishu_directory_field_permission_missing 表示飞书应用字段权限或通讯录可见范围不足。修改权限后必须发布飞书应用版本，并把通讯录数据权限范围设为全部成员。

6. 客户项目问题

clientAssignments 为空不一定是错误。检查：员工是否 active、项目/职责是否 active、生效日期、成员是否来自飞书目录。不要通过给用户更高 App 权限来修复项目分工。

7. Dev 环境诊断

平台仓库本地开发可以运行：

npx pnpm@10.12.4 doctor:auth-dev
npx pnpm@10.12.4 doctor:auth-dev -- --strict

首次创建 dev 管理员时密码可自动生成。完整诊断规则见仓库 docs/AUTH_DEV_DOCTOR.md。需要由脚本判断当前下一步时运行 npx pnpm@10.12.4 next:auth；该命令不会绕过 SUPABASE_SERVICE_ROLE_KEY 或 E2E_INVITE_EMAIL。

业务 App 不应复制平台的 service role、数据库连接或飞书 secret。

Dev 管理员初始化

平台开发者需要真实管理员会话时，使用仓库引导命令创建或复用 admin@iwish.local：

npx pnpm@10.12.4 bootstrap:dev-admin

该流程依赖本地未提交的 SUPABASE_SERVICE_ROLE_KEY，并输出仅用于开发验收的 SUPABASE_ACCESS_TOKEN。任何 token 或 service role key 都不得写入文档示例值、源代码或 Git。

HTTP E2E 验证

准备真实可收信的测试邮箱 E2E_INVITE_EMAIL，启动 Auth API 后运行：

npx pnpm@10.12.4 e2e:auth-api

该命令验证真实 Supabase Auth token、本地 Worker、邀请流程和管理端 API。完整环境说明见仓库 docs/ENVIRONMENT_SETUP.md 与 docs/E2E_AUTH_API.md。