rainblogweb/docs/rainid-integration/README.md

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 实现视角三方沉淀）