4.8 KiB
4.8 KiB
App 第三方登录配置
代码支持 Android/iOS 的微信、QQ、Google 原生登录，以及 GitHub 系统浏览器授权。后台开关可以随时停用已接入渠道，但不能把 SDK 动态装入已经发布的 App。参数尚未配置、SDK 尚未打包的原生渠道不会显示。
部署顺序
- 先备份数据库，执行后端新增迁移
backend/migrations/027_app_oauth_login.sql，再发布新版后端。该迁移保留已有 H5 绑定，增加 App 登录平台、回调证明及身份应用范围。 - 发布新版管理端。在“平台配置 → 第三方登录”分别配置管理端、H5、App 开关。App 开关默认关闭，不会沿用 H5 开关。
- 在 HBuilderX 的
manifest.json → App SDK 配置 → 登录鉴权勾选所需 SDK，填写下面的平台信息，然后云打包或制作自定义调试基座。标准基座的示例 AppID 不能用于本项目正式登录。 - 在真实 Android/iOS 设备上逐个验证授权成功、取消授权、首次手机号绑定、再次登录，以及后台关闭渠道后拒绝登录。
npm run build:app-plus只生成 App 资源，并不生成已签名 APK/IPA。
各渠道参数
| 渠道 | 后台 | HBuilderX / 开放平台 |
|---|---|---|
| 微信 | App 微信 AppID、App 微信 AppSecret、App 启用微信登录 | 微信开放平台移动应用 AppID；登记 Android 包名及签名、iOS Bundle ID 与 Universal Links。AppSecret 只保存在后端，客户端使用 onlyAuthorize: true 获取 code。 |
| App QQ AppID、App 启用 QQ 登录 | QQ 移动应用 SDK 配置和实际包名、签名、Bundle ID；AppID 与后台一致。服务端验证令牌所属 AppID，忽略客户端自行提交的 OpenID。 | |
| App Google Client ID 白名单、App 启用 Google 登录 | 注册 Android（包名及签名）和 iOS OAuth Client ID；配置 Google 登录模块与 iOS Client ID；将实际签发令牌的 Android/iOS 客户端 ID 加入后台白名单，以英文逗号分隔。设备与服务端须能访问 Google 服务。 | |
| GitHub | 下方共用的 GitHub OAuth 应用参数、App 启用 GitHub 登录、App 回调地址 | GitHub OAuth App 填后端的 HTTPS 回调，例如 https://api.example.com/api/v1/auth/oauth/callback。不要填 App Scheme。Android/iOS 均已在 manifest 注册 xingyuim Scheme。 |
GitHub 的 App 返回地址固定为 xingyuim://oauth/callback。App 在打开系统浏览器之前保存本次请求 ID 和私有证明；后端回调携带短期一次性登录码，兑换和手机号绑定还必须提交该私有证明。证明不进入浏览器 URL，截获 Scheme 回调的其他 App 无法单独兑换登录态。支持 App 被系统结束后从回调冷启动。
微信、QQ 的网站应用与移动应用 OpenID 不一定相同。本次实现按移动 AppID 隔离绑定，首次 App 登录可能需要对已注册手机号做一次短信验证；不会只凭昵称、邮箱或未经验证的 OpenID 自动合并账号。Google、GitHub 使用同渠道的稳定身份，可复用已有绑定。
接口
GET /api/v1/auth/oauth/providers?platform=app：仅返回后端已启用、参数完整的 App 渠道。省略 platform 保持旧版 H5 行为。App 再与实际打包 SDK 取交集。POST /api/v1/auth/oauth/native：微信提交{provider:"wechat", code}；QQ/Google 提交{provider, accessToken}。后端向官方接口校验后返回oauthCode。所有请求必须使用 HTTPS。POST /api/v1/auth/oauth/start：GitHub App 提交{provider:"github", platform:"app"}，返回授权 URL、requestId、appProof 和 callbackUrl。POST /api/v1/auth/oauth/exchange：提交{code, deviceId, appProof?}，已绑定时返回登录态，未绑定时返回requiresLink。POST /api/v1/auth/oauth/link：提交{code, phone, smsCode, deviceId, appProof?}，验证已注册手机号并绑定。GitHub App 的appProof必填。
渠道在列表、授权发起、授权回调、登录码兑换及绑定处均校验开关。停用渠道阻止新的第三方登录，不会撤销已经签发的账户会话。回到登录页时刷新渠道列表。
本地检查
在 mobile 目录运行 npm run test:oauth、npm run test:native-config、npm run type-check、npm run build:h5 和 npm run build:app-plus。后端运行 go test ./...。
这些检查不代替第三方平台审核、真机 SDK 授权和 iOS/Android 回跳测试。不要把 AppSecret、访问令牌、回调证明或登录码粘贴到日志里。