RainID 接入指南（任意项目通用）
RainID（
https://rainid.rainnya.asia）是 Rainnya 家族统一身份认证服务（OIDC Provider）。 本目录是任意项目接入 RainID 的完整资料包，基于 RainWeb 实战接入沉淀（含线上排障）。 RainID 官方协议文档：/home/miaomiao/Project/rainid/docs/OIDC对接文档.md
从哪份开始读
| 你的角色 | 读这份 |
|---|---|
| 项目负责人 / 架构师（先定方向再动手） | 01-onboarding-audit.md（审计视角：协议选型、账户整合模式 A/B/C、安全清单、验收） |
| 开发 / 实施（照着写代码） | 02-implementation-practice.md（实现视角：Step-by-step、可抄代码模式、配置、踩坑、排障） |
| 已接入但在排障 | 02-implementation-practice.md 第 5 章（踩坑实录）+ 第 6 章（快速排障 L1-L5） |
| 只想知道"注意什么" | 01-onboarding-audit.md 第 4 章（安全清单）+ 第 5 章（常见坑） |
核心结论（30 秒速览）
- RainID 只做标准 OIDC/OAuth2——你的项目只需要一个
discovery_url=https://rainid.rainnya.asia/oauth - 身份归 RainID，角色归你——
sub是跨应用稳定绑定键，admin/角色/数据归属永远本地维护 - 授权码 + PKCE 是默认正解（有浏览器）；ROPC 仅服务端代理登录用（2FA 用户会被拒）；client_credentials 供服务间
- 影子账号模式最推荐（用户表加
rainid_user_id一列），存量站可做混合绑定但必须过email_verified撞绑闸门 - 必须留本地 admin 逃生通道——RainID 故障时管理员仍能登录后台（break-glass）
- 务必登记：redirect_uris、post_logout_redirect_uris、grant_types、scope 白名单、ROPC 密码直连白名单——漏一个登出就卡死/登录静默失败
目录文件
01-onboarding-audit.md—— 架构审计视角通用指南（协议选型决策树、账户整合模式对比、安全清单、验收 checklist）02-implementation-practice.md—— 实现落地实操指南（Step-by-step、可复制代码模式、配置设计、admin 逃生通道、踩坑实录、L1-L5 快速排障）
RainWeb 参考实现（抄作业对照）
| 需求 | RainWeb 文件 |
|---|---|
| discovery 缓存 / secret 双通道 / 影子账号 / ROPC | lib/rainid.js |
| 授权码三路由 + ticket + 登出联动 | routes/oidc.js |
| ROPC 接线 + admin 逃生通道 | routes/auth.js |
| PUBLIC_KEYS / ALL_KEYS / ALLOWED_SET | routes/settings.js |
| 前端登录页（ticket/error 收尾） | frontend/src/pages/Login.jsx |
| 前端注册页（注册托管） | frontend/src/pages/Register.jsx |
| 登出联动按钮 | frontend/src/components/Layout.jsx |
| 后台设置表单（secret 置空不回显） | frontend/src/admin/pages/Settings.jsx |
| 唯一索引迁移 | db.js migrations |
整理：RainWeb 接入实战（orchestrator 编排 + oracle 审计视角 + fixer 实现视角三方沉淀）