简介这是一套彩虹聚合登录系统的二次开发源码主要面向需要为多个网站统一接入第三方快捷登录的开发者。聚合中转API支持微信、支付宝、微博、百度及QQ等平台解决了每次都要向各平台单独申请、逐个接入的麻烦。包内共312个文件以JS、CSS、PHP、JSON等类型为主JS与CSS构建了前台界面和后台样式PHP负责登录中转与各应用管理JSON存放配置数据整体仅4.08MB部署轻量。资源已有751人学习适合具备一定PHP基础的站点管理员或二次开发人员。相比原版新增了前台页面、开发文档及配套SDK接口文件后台采用光年模板美化支持站点配置与前台内容自定义同时集成多应用管理、域名限制、账号记录、登录记录等功能。压缩包内附安装说明及QQ互联申请注意事项强调需先备案域名并借助Discuz等论坛程序完成申请可有效帮助读者避开常见坑点快速搭建起可运行的聚合登录平台。1. 彩虹登录聚合系统先想明白它是给谁解决问题的彩虹登录聚合系统第一反应容易联想到前端炫彩主题。实际上做登录网关的人看到这个名字都明白它解决的是接入方最头疼的一类问题微信、QQ、钉钉、GitHub、Gitee 每家的 OAuth 文档都各写各的回调地址格式不一样用户字段命名不一样scope 权限说法更不一样。彩虹的思路是把这些第三方登录收编为一个统一适配层业务系统只对接一个入口就能同时具备多平台登录能力用户绑定、会话管理、后台配置也一并收口。适合正在做统一认证平台、SaaS 多租户登录、内部系统聚合登录的团队参考。2. 聚合登录背后的四个抽象从 Provider 适配到会话选型2.1 Provider 适配器屏蔽平台差异的那层壳所有第三方登录平台在流程上都遵循 OAuth 2.0 授权码模式跳转授权页、用户同意、回调带 code、拿 code 换 access_token、再拿 token 拉用户信息。真正的差异不在流程而在细节。第一个差异是授权端点参数。微信的 OAuth 用appid和secretGitHub 用client_id和client_secret字段名不同钉钉的授权还多一个redirect_uri编码要求。第二个差异是 scope 的语义微信要拿用户头像昵称得开snsapi_userinfoGitHub 要拿邮箱得额外申请user:email否则返回的 email 字段直接是null。第三个差异是用户信息字段GitHub 的id是数字微信的openid是带前缀的字符串钉钉的unionid和openid是两个值得自己决定用哪个做主键。所以适配器层要做的事情就三件把应用配置翻译成各平台的请求参数把各平台的响应翻译成统一结构把各平台的鉴权方式header 带 token 还是 query 带 token包掉。下面是一个统一适配接口的定义实践中我会把它作为整个系统的地基所有第三方登录都实现这套接口。// adapter.ts — 统一适配器接口 export interface OAuthAdapter { // 平台标识如 github / wechat / dingtalk providerName: string; // 生成跳转授权页的完整 URL buildAuthorizeUrl(state: string, redirectUri: string): string; // 用 code 换取 access_token返回 token 原始响应 exchangeCodeForToken(code: string, redirectUri: string): PromiseTokenResponse; // 用 access_token 拉取用户信息返回归一化后的用户档案 fetchUserInfo(accessToken: string): PromiseNormalizedUser; } // 归一化后的用户结构业务侧只认这份数据 export interface NormalizedUser { uid: string; // 平台内唯一 ID如 GitHub 的 id、微信的 openid unionid?: string; // 平台级统一 ID微信系账号常用 name: string; email?: string; avatar?: string; }这套接口的巧妙之处在于业务代码只依赖NormalizedUser不关心底层是哪个平台。后面对接新平台时加一个适配器类、注册进去即可业务侧和数据库都不用改动。回调地址、scope 配置、字段映射全部由各适配器内部消化这是聚合登录系统能长期维护而不腐烂的关键。2.2 state 校验为什么每次授权都要带一张“临时票”OAuth 2.0 协议本身要求客户端在发起授权时生成一个随机 state 参数授权完成后回调会原样带回。很多人图省事把 state 写成固定字符串或者干脆不传实战里这正是账号被恶意绑定的入口。攻击手法很直接攻击者先用自己的账号完成授权拿到一个合法的回调链接然后诱导受害者点击这个链接。如果系统不校验 state 或者 state 可预测回调到达后系统会拿着攻击者的 code 去换 token然后把这个第三方账号绑定到受害者本地账号上。受害者没做任何操作第三方账号就被绑到了自己的名下后续攻击者就能通过该第三方渠道直接登录受害者账号。所以 state 必须满足三个条件每次授权请求重新生成、不可预测、有有效期。实践中我会用随机串加时间戳生成 state存到 Redis 里设置 5 分钟过期回调时取出比对比对完立即删除。// stateService.ts — state 生成与校验 import crypto from crypto; export function generateState(providerName: string): string { // 随机 32 字节 hex携带 provider 信息便于回调时快速定位 const raw ${providerName}:${crypto.randomBytes(32).toString(hex)}; return Buffer.from(raw).toString(base64url); } export async function saveState(redis: any, state: string, ttl: number) { // 以 state 本身为 keyvalue 存平台名5 分钟过期 await redis.setex(oauth:state:${state}, ttl, state); } export async function consumeState(redis: any, state: string) { // 取出即删防止 state 二次使用 const stored await redis.getdel(oauth:state:${state}); return stored state; }注意getdel这个操作它在读取的同时删除 key天然防止了“同一个 state 在并发请求下被校验两次”的问题。如果 Redis 版本不支持getdel可以用get加del包一层事务或者用 Lua 脚本保证原子性。2.3 会话选型Redis 有状态与 JWT 无状态我选哪个授权回调处理完用户身份确定了接下来要解决“后续请求怎么认出这个用户”。聚合登录系统里有两种主流方案选型直接影响后续的踢人下线、多端登录、用户封禁能力。JWT 无状态方案登录成功后签发一个 JWT客户端存起来后续请求带上即可。服务端不保存会话天然支持分布式。但问题是无法主动吊销用户被封禁后 JWT 在有效期内仍然可用多端登录管理困难想踢掉某一端得维护 token 黑名单。黑名单方案本身就回到了有状态那 JWT 的价值就打折了。Redis 有状态方案登录成功后创建一条 session 记录把 sessionId 写入 httpOnly Cookie。服务端每次请求查一次 Redis会话存在且未过期则放行。封禁用户只需删除对应 session踢人只需要删掉指定 sessionId多端管理就是给每个设备发不同的 sessionId记录同一用户 ID 下的多份会话。聚合登录这种场景我倾向于 Redis 有状态方案。原因有三个一是多平台绑定关系天然需要服务端维护有状态更顺手二是用户可能同时在 PC、小程序、App 登录需要区分会话三是后台管理系统经常有“强制下线”需求无状态方案很难优雅实现。配合 Redis 集群性能也足够。对比项Redis 有状态JWT 无状态强制下线删 session 即可需要维护黑名单多端管理天然支持不借助额外存储很难服务端存储需要 Redis不需要回调逻辑复杂度低中推荐场景聚合登录后台、管理端纯 API 服务、移动端3. 搭一个最小可运行的彩虹登录网关回调入口到用户落库3.1 目录结构把“回调处理”“适配器”“用户映射”分三层要给读者一份能直接落地的最小工程骨架。常见做法是分三层路由层只做参数解析和重定向适配器层处理各平台的请求用户服务层负责查库、建号、绑关系。下面这份目录结构是我习惯用的和你看到的大多数开源聚合登录项目结构类似胜在每层职责单一。src/ ├── adapters/ # 各平台适配器实现 │ ├── github.adapter.ts │ ├── wechat.adapter.ts │ └── dingtalk.adapter.ts ├── routes/ # 路由层 │ ├── login.ts # /login/:provider 发起授权 │ ├── callback.ts # /auth/:provider/callback 回调终点 │ └── logout.ts # 退出登录 ├── services/ │ ├── auth.service.ts # 会话创建、销毁 │ ├── user.service.ts # 用户查找、创建、绑定 │ └── adapter.registry.ts # 适配器注册中心 ├── middlewares/ # 会话校验、错误处理 ├── config/ # provider 配置加载路由层不直接调用各平台 SDK而是通过adapter.registry拿适配器实例。这样做的好处是新增平台只动adapters/目录和config/配置路由层代码永远不会因为接新平台而改动。3.2 核心回调授权码换令牌与用户信息拉取的完整流程回调是整个聚合登录系统的心脏。这里贴一段核心的回调 handler它涵盖查适配器、校验 state、换 token、拉用户、查库/建号、建会话。每个步骤都会做详细说明。// callback.ts — 统一回调终点 import { Router } from express; import { getAdapter } from ../services/adapter.registry; import { consumeState } from ../services/state.service; import { findOrCreateUser } from ../services/user.service; import { createSession } from ../services/auth.service; export const callbackRouter Router(); // GET /auth/:provider/callback?codexxxstateyyy callbackRouter.get(/:provider/callback, async (req, res) { const { provider } req.params; const { code, state } req.query; if (!code || !state) { return res.status(400).send(缺少 code 或 state 参数); } // 1. 拿到该平台的适配器 const adapter getAdapter(provider); if (!adapter) { return res.status(400).send(不支持的登录平台); } // 2. 校验并消费 state防止 CSRF const stateOk await consumeState(req.redis, state as string); if (!stateOk) { return res.status(400).send(state 校验失败请重新发起登录); } try { // 3. 用 code 换 access_token const token await adapter.exchangeCodeForToken(code as string, buildRedirectUri(req, provider)); // 4. 用 token 拉取用户信息 const profile await adapter.fetchUserInfo(token.access_token); // 5. 查库或创建用户绑定第三方账号 const localUser await findOrCreateUser(provider, profile); // 6. 创建会话并写 Cookie const sessionId await createSession(req.redis, localUser.id); res.cookie(session_id, sessionId, { httpOnly: true, sameSite: lax, maxAge: 7 * 24 * 3600 * 1000, // 7 天 }); // 7. 跳回业务首页 res.redirect(/); } catch (err) { // 统一错误兜底避免把平台原始报错暴露给用户 res.status(500).send(登录失败请稍后重试); } });这段代码里几个关键点值得展开第三步exchangeCodeForToken内部会做三件事组装 token 请求参数、发起 HTTP 请求、解析响应。不同平台的参数差异在这里被屏蔽。比如微信要求appid和secretGitHub 要求client_id和client_secret适配器内部翻译好回调层不用感知。第五步findOrCreateUser是绑定逻辑的核心输入是平台名和归一化用户信息输出是本地用户记录。这里有一个重要设计同一个第三方账号重复登录不会创建新用户而是复用已有用户并更新资料。同一本地用户绑多个平台是允许的后面我会讲表结构。第六步会话过期时间我设为 7 天聚合登录后台通常不需要像支付系统那样 30 分钟强制过期但也不建议太长。过期后用户重新走第三方登录即可体验无损。buildRedirectUri这个函数动态拼接回调地址原理是读请求的 host 头和协议头但要注意反代场景下的协议识别问题这一点在第 4 章单独展开。3.3 用户映射表openid、unionid 与本地账号怎么关联用户表设计直接决定了多平台绑定关系能不能成立。经典做法是两张表users存本地用户主档案user_bindings存每个第三方平台的关联关系。-- users本地用户主表 CREATE TABLE users ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, username VARCHAR(64) DEFAULT NULL, avatar_url VARCHAR(512) DEFAULT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- user_bindings第三方账号绑定关系表 CREATE TABLE user_bindings ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, user_id BIGINT UNSIGNED NOT NULL COMMENT users.id, provider VARCHAR(32) NOT NULL COMMENT 平台标识 github/wechat/dingtalk, provider_uid VARCHAR(128) NOT NULL COMMENT 平台用户唯一ID, unionid VARCHAR(128) DEFAULT NULL COMMENT 微信 unionid可选, raw_profile JSON DEFAULT NULL COMMENT 平台原始用户信息快照, last_login_at DATETIME DEFAULT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_provider_uid (provider, provider_uid), KEY idx_user_id (user_id), CONSTRAINT fk_binding_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有两个务实的决策第一provider_uid存的是适配器归一化后的uidGitHub 场景下就是它的数字 ID微信场景下就是 openid。unionid单独列出来因为微信生态里同一个用户在公众号、小程序、开放平台下的 openid 不同但 unionid 一致。如果未来要把微信开放平台登录、公众号登录、小程序登录都接入unionid 就能把这几个入口识别为同一个人。第二raw_profile存 JSON 快照。这个字段的价值在于排查问题当用户反馈“第三方头像没同步过来”查这个字段就能确认平台到底返回了什么。不用为每种平台的字段建列存储成本也比想象中低。findOrCreateUser的逻辑用一句话概括先在user_bindings里按provider provider_uid查查到就更新快照并取关联的user_id查不到就新建users记录再回插user_bindings。这一步的并发问题在避坑章节单独讲。4. 让 Provider 变成外部配置JSON 驱动的适配器注册4.1 Provider 配置的正则校验与热加载把每个第三方平台的参数抽成外部 JSON 配置是聚合登录系统从“能跑”走向“可维护”的关键一步。配置项包括client_id、client_secret、授权端点、token 端点、userinfo 端点、scope、字段映射等。下面是一份完整的 provider 配置示例{ github: { label: GitHub, type: oauth2, client_id: Iv1.xxxxxxxxxxxx, client_secret: 替换成真实密钥, authorize_url: https://github.com/login/oauth/authorize, token_url: https://github.com/login/oauth/access_token, userinfo_url: https://api.github.com/user, scope: read:user user:email, field_map: { uid: id, name: name, email: email, avatar: avatar_url } }, wechat: { label: 微信, type: oauth2, client_id: wx1234567890abcdef, client_secret: 替换成真实密钥, authorize_url: https://open.weixin.qq.com/connect/qrconnect, token_url: https://api.weixin.qq.com/sns/oauth2/access_token, userinfo_url: https://api.weixin.qq.com/sns/userinfo, scope: snsapi_login, field_map: { uid: openid, unionid: unionid, name: nickname, avatar: headimgurl } } }配置加载时有几个校验不能省。client_secret不允许为空authorize_url必须走 httpsfield_map里uid必须有值否则无法唯一标识用户。校验不过就直接报错停服不要让系统带病运行。我在生产环境见过最隐蔽的问题是把 GitHub 的field_map配成了uid: loginGitHub 的login是用户名而不是唯一 ID用户改用户名后就会变成“另一个用户”导致原绑定关系失效、用户被识别为新账号。热加载的实现常见的做法是启动时读一次配置放入内存本地文件监听变化或者配置中心推送更新文件变更后重新解析并校验通过则替换内存配置。热更新的前提下后台改配置不用重启进程联调成本低很多。4.2 回调地址动态拼接反代与 https 回跳的坑每个第三方平台需要配置一个回调地址。如果只有一个环境写死即可。但开发、测试、预发、线上四套环境回调地址各不相同写死会让联调非常痛苦。所以一般做法是动态拼接但这里有个隐蔽的坑。// redirectUri.ts — 动态拼接回调地址 import { Request } from express; export function buildRedirectUri(req: Request, provider: string): string { // 优先读 X-Forwarded-Proto兼容反向代理后的 https 识别 const proto req.headers[x-forwarded-proto]?.split(,)[0] || req.protocol; const host req.headers[x-forwarded-host]?.split(,)[0] || req.headers.host; return ${proto}://${host}/auth/${provider}/callback; }代码里的split(,)[0]是处理多个反代节点串行传递的场景。nginx 转发时如果没有正确配置proxy_set_header X-Forwarded-Proto $scheme;后端的req.protocol仍然会是 http拼接出来的回调地址就不是 https第三方平台回调时就会报“redirect_uri 不匹配”。所以遇到“本地能登录、线上登录失败”时第一件事就是看线上回调地址的协议头。写成https://的第三方平台配置绝对不会容忍回调地址变成http://。更稳妥的做法是前端的 nginx 层直接强制跳 https后端就少一类问题。回调地址校验还有个细节很多第三方平台要求回调地址与配置的域名完全一致包括端口。本地开发端口是 3000平台配置的回调地址就必须带:3000。这是我联调时最常遇到的一个“配了但不对”的情况。4.3 多环境配置隔离测试 provider 与线上 provider 分开聚合登录系统对接的平台通常有“正式应用”和“测试应用”之分。GitHub 可以创建多个 OAuth App微信开放平台也可以配置多个网站应用。我见过因为配置混淆导致的线上事故测试环境的 client_id 配到了线上配置里用户跳过去看到的是“应用未审核”或者直接报错。隔离手段很简单按环境拆分配置文件config/ ├── default.json # 公共默认配置 ├── development.json # 本地环境测试应用 ├── test.json # 测试环境测试应用 └── production.json # 生产环境正式应用加载顺序是 default 为底、环境配置覆盖。不要小看这种朴素做法它省掉的排查时间非常可观。我自己遇到过的翻车场景就是测试环境把微信回调地址指向了线上域名导致真实用户在线上完成了测试应用的授权回调回来后 code 全部无效用户群里一片“登录一直失败”的反馈。5. 彩虹登录聚合系统的五个高频翻车点回调、联调与关联避坑5.1 state 反复校验不过多标签页与授权会话复用现象用户反馈“登录时说 state 无效”但自己操作步骤完全正常多刷新几次又好了。 原因同一浏览器开了多个标签页同时发起多次第三方登录。浏览器对同一域名的授权弹窗做了会话复用后一次授权请求覆盖了前一次的 state 存储。回到回调时发现 state 对应的 key 已被消费于是校验失败。 解决发起授权前为每次跳转生成独立 state并限制每用户同时只能有一个活跃登录流程。如果用户再次发起授权主动把前一个 state 提前作废。前端侧在点击“登录”按钮后做 loading 拦截避免重复点击。后端再加一道保险state 被消费后如果再次使用直接拒绝。5.2 本地联调回调地址不是 https回调被平台拒在门外现象本地开发时配置了内网映射的公网域名平台回调总是提示地址不合法。 原因微信、GitHub 等平台要求回调地址必须是可公网访问的 https 地址。本地http://localhost:3000这种地址是没法配置到平台后台的内网映射的域名没配好证书的话协议头仍然是 http。 解决统一做法是把回调地址拆成两级先由网关层校验域名再按环境传不同的redirect_uri给平台。本地开发时使用带证书的公网映射域名指向本地端口同时保证 nginx 正确传递X-Forwarded-Proto。若平台支持配置“开发用回调域名”优先使用与线上回调地址彻底分开避免误操作影响线上。注意所有基于公网映射的联调方式仅限测试环境使用。生产环境回调地址必须写死控制风险。5.3 邮箱当主键导致用户关联错乱GitHub 隐私邮箱与微信手机号现象同一个用户先通过 GitHub 登录建立了账号之后改用微信登录系统里出现两个账号资料各不同步。或者 GitHub 用户不公开邮箱系统把 email 为 null 的用户识别成了新用户。 原因用邮箱作为用户唯一标识而第三方平台的邮箱往往不是稳定字段。GitHub 用户可以不公开邮箱微信用户信息拉取根本不含邮箱只有手机号场景才有。拿一个“可能为 null 的字段”做唯一识别必然出错。 解决把唯一性完全压在provider provider_uid上邮箱只作为资料展示。绑定逻辑在 3.3 已经给出核心是绑定关系表索引唯一不要试图用邮箱全局去重。如果业务确实需要邮箱合并账号单独做“账号合并”功能而不是在登录回调里隐式合并因为隐式合并会在无意识中把两个真实用户的数据搅到一起。5.4 scope 漏配能跳过去但拉不回用户信息现象用户能跳转到授权页同意后回调也正常但拉取用户信息时报“接口无权限”或返回字段为空。 原因scope 定义决定了授权范围。GitHub 未申请user:email则 email 为 null微信未开snsapi_userinfo则 userinfo 接口返回的昵称头像为空钉钉的通讯录权限未申请则手机号字段缺失。 解决在 provider 配置里显式声明 scope适配器层在拉用户信息时检查关键字段是否返回完整。比如 GitHub 适配器可以在fetchUserInfo结束后检查id是否存在不存在则抛错“用户信息缺失请检查 scope 配置”。这样一个模糊的第三方报错就变成了一个明确的本系统错误联调时能节省大量时间。5.5 回调路径大小写与尾斜杠平台严格匹配导致 404现象从第三方平台跳回时提示“redirect_uri 不匹配”但肉眼比对后台配置和代码里的回调地址完全一致。 原因多个平台对回调地址做了精确匹配大小写敏感、尾部斜杠也不能多不能少。GitHub 的 OAuth 回调必须精确等于注册值。如果注册为/auth/GitHub/callback代码里写成/auth/github/callback就会不匹配。 解决回调地址统一用小写字母路径配置和代码保持一致且不发尾斜杠。如果为了兼容历史地址而不得不接受两种形式可以在回调路由上做一次“路径归一化”中间件将带尾斜杠的请求 301 到不带斜杠的路径。不要试图让平台都接受一种模糊匹配因为有的平台就是不支持。注意5.5 的问题一旦发生排查优先级最高的就是回调路径本身。先看请求日志里实际落在后端的 path再看平台后台配置的 callback 地址往往一眼就能发现问题。6. 上线前最后一道工序用一张检查清单把“能登录”升级成“敢上线”本地跑通第三方登录只能说明流程通了离上线还差几步验证。我每次上聚合登录系统前都按下面这张检查清单过一遍它能暴露绝大多数隐藏问题。检查项验证方法预期结果state 防重放首次登录成功后用历史授权 URL 手动触发一次回调系统拒绝不创建会话重复绑定同一第三方账号连续登录两次用户 ID 不变绑定表不重复插入多端会话隔离同一用户 PC 和手机分别登录产生两个不同 session可独立下线强制下线管理后台踢掉某个会话该会话后续请求返回未登录回调路径大小写大小写混写访问回调地址直接 404 或 400不被误处理用户绑定跨平台同一个人 GitHub 登录后再用微信登录可手动绑定为同一本地账号会话过期修改 Redis TTL 为 10 秒等过期后请求接口返回未登录需重新授权验证环节还可以写一个小脚本模拟客户端发起登录并断言关键响应。下面这张代码示意了完整的回归链路# check_login_flow.sh — 最小回归脚本 curl -c cookies.txt -L http://localhost:3000/login/github -o /dev/null -w %{http_code} %{redirect_url}\n echo step1: authorize redirect 通过 curl -b cookies.txt -c cookies.txt http://localhost:3000/auth/github/callback?codedummystatedummy -o /dev/null -w %{http_code}\n echo step2: 无效回调被拒绝这段命令验证两个点登录入口能正确返回 302 跳转第三方带假 code 的回调被系统拒绝而不是 500。上线前的回归不追求全面只求关键路径没退化。最后说一个我个人的习惯把所有平台的原始响应和回调错误统一记录到一张日志表里字段包含平台名、错误码、原始消息、时间。这张日志表在平时是废的一旦线上出问题它就是唯一能还原现场的后悔药。每次接新平台或者改配置之前先跑一遍日志里的历史请求对比改动前后行为差异能挡住不少低级失误。聚合登录系统的价值不在于代码多炫而在于把“接入第三方登录”这件事从每次都要看的黑匣子变成可控的配置行为。希望这套拆解和踩坑记录能帮你在自己的项目里少走几个弯路。本文还有配套的精品资源点击获取