给 Clara 加 OAuth 第三方登录：可行性路线分析

给 Clara 加 OAuth 第三方登录在技术上可行，但官方插件清单里目前没有现成的 OAuth 登录插件，所以不存在"后台点一下开关"的路径。

结论：唯一稳妥的落地方式是写一个挂在 `content/plugins` 下的运行时钩子插件，核心文件一行不改；任何"直接改登录逻辑源码"的方案都会在下一次覆盖升级时被打回。

先认清三个硬约束

第一，Clara 是无框架的轻量 PHP 系统，明确不依赖 Composer。这意味着你熟悉的 `composer require league/oauth2-client` 这条路走不通，得手写 OAuth2 授权码流程（拼 authorize URL、换 token、拉 userinfo 三步），或者把第三方 SDK 源码整个内联放进插件目录。

第二，系统没有命令行环节，安装靠访问 install 向导，插件保存即生效、不需要编译和清缓存。所以插件的"安装"动作必须做成访问某个页面即触发，不能指望跑一条 `php migrate.php`。

第三，核心升级会覆盖文件，新增字段和表靠后台「系统工具→数据库升级」执行增量 DDL（幂等，可重复执行）。插件如果自建了第三方账号绑定表，务必先备份数据库，并确保你的建表语句可以重复执行不报错。

路线一：纯插件钩子（推荐主线）

结论：这是唯一不破坏升级链路的方案，成本可控，但依赖你对钩子触发点的准确定位。

具体做法分四步：① 在 `content/plugins` 下新建插件目录，按官方插件的目录约定放入口文件；② 挂"登录页渲染"类钩子，在登录表单下方插入微信/QQ/GitHub 等按钮；③ 挂或新增一个回调入口，接收 `code` 与 `state`，完成换 token 和拉取用户信息；④ 按第三方 `openid` 查绑定表，命中就写登录态，未命中就走注册分支。

关键点是钩子名。系统有 156 个运行时钩子，但具体到"登录页渲染"和"登录提交处理"这两个叫什么，别凭猜——直接翻官方插件的源码或者查官方站 www.leleweb.cn 的文档，照着同类插件的写法抄结构最省事。

路线二：对接现有账号与安全体系（必做的适配）

结论：OAuth 只替换了"验证身份"这一步，身份验证之后的活 Clara 已经有一套现成机制，必须接上，不能绕开。

密码侧不用管——系统密码是 bcrypt 存储，第三方登录用户可以不设本地密码，但建议保留"设置密码"入口，否则哪天第三方平台封了应用，用户就进不来了。CSRF 侧要特别注意：OAuth 回调本质上是一次跨站跳转，`state` 参数就是防重放的核心，别图省事省掉。

登录安全闭环也要照顾到：系统默认连错 5 次锁 15 分钟、同 IP 高频失败会被拦截、每次登录都会进后台「用户体系→登录日志」。第三方登录失败同样应该落审计，否则你排查问题时看不到真实情况。

新用户注册分支还有几个坑：邮箱域名黑名单（内置近百临时邮箱域）和注册验证问答是为表单注册设计的，OAuth 拿到的邮箱要不要过黑名单、验证问答要不要跳过，得自己定规矩；用户名冲突要有兜底改名策略；用户落在哪个用户组、是否给新人礼包，都要在插件里显式指定。

路线三：外部反代/中间层（不推荐）

结论：用 Nginx 或独立中转服务在 Clara 前面做 OAuth，看着不用碰 PHP，实际是最容易翻车的方案。

原因是 Clara 的 URL 会自动识别 `.html` 后缀，服务器只需把非静态请求转发到 `index.php`；这意味着你的中间层必须完整透传 Cookie 和会话。而官方 FAQ 里已经点明：站点地址 www 与裸域混用会导致会话丢失。多一层代理，等于把这个坑放大一倍，回调后再跳回主站很容易变成"登录成功但没有登录态"。

真要走这条路，前提是后台「基本设置」里把站点地址填成带 `https://` 的主域名且全程不跳域，成本远高于路线一。

落地检查清单

回调地址必须与后台配置的站点地址完全一致，协议、域名、子目录一个字符都不能差；测试顺序是本地 → 测试站 → 生产，别直接在生产上调；上线后确认插件在系统工具里不影响原有升级流程；最后，各平台开放平台的接入资质、审核要求以对方规则为准，这不是 Clara 能替你解决的部分。

一句话收束：Clara 加 OAuth 的正解是"运行时钩子插件 + 复用现有安全与用户体系"，改核心、加反代都是给自己挖坑。