# 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 秒速览）

1. **RainID 只做标准 OIDC/OAuth2**——你的项目只需要一个 `discovery_url` = `https://rainid.rainnya.asia/oauth`
2. **身份归 RainID，角色归你**——`sub` 是跨应用稳定绑定键，admin/角色/数据归属永远本地维护
3. **授权码 + PKCE 是默认正解**（有浏览器）；ROPC 仅服务端代理登录用（2FA 用户会被拒）；client_credentials 供服务间
4. **影子账号模式最推荐**（用户表加 `rainid_user_id` 一列），存量站可做混合绑定但必须过 `email_verified` 撞绑闸门
5. **必须留本地 admin 逃生通道**——RainID 故障时管理员仍能登录后台（break-glass）
6. **务必登记**：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 实现视角三方沉淀）*