xianyan/docs/toolsapi/docs/API_OAUTH_DOC.md

闲言APP — OAuth社交登录 API 接口文档

基础URL: https://tools.wktyl.com 版本: v1.0.0 | 创建时间: 2026-06-05 支持平台: Apple / Google / GitHub 关联文档: API_USER_SECURITY_DOC.md

---

一、概述

OAuth社交登录允许用户通过 Apple、Google、GitHub 账号快速登录闲言APP，无需手动注册。

核心流程：

1. 客户端调用 /api/oauth/config 获取授权URL
2. 用户在第三方平台完成授权，获取授权码(id_token)
3. 客户端调用 /api/oauth/login 提交授权码
4. 服务端验证授权码，创建/关联用户，返回Token

与闲言自有注册的关系：

• OAuth登录是独立通道，不影响现有用户名+密码注册
• OAuth登录后自动创建闲言账号，邮箱相同的会自动关联
• 已登录用户可通过 /api/oauth/bind 绑定社交账号

---

二、接口概览

接口	方法	路径	需登录	说明
获取OAuth配置	GET	/api/oauth/config	❌	获取授权URL和client_id
社交登录	POST	/api/oauth/login	❌	授权码登录
绑定社交账号	POST	/api/oauth/bind	✅	已登录用户绑定
解绑社交账号	POST	/api/oauth/unbind	✅	已登录用户解绑
已绑定列表	GET	/api/oauth/bound	✅	查询已绑定平台
安装数据表	GET	/api/oauth/install	❌	初始化

---

三、接口详情

3.1 获取OAuth配置

GET /api/oauth/config?platform=apple

参数	类型	必填	说明
platform	string	✅	平台: apple/google/github

响应示例：

{
    "code": 1,
    "msg": "",
    "data": {
        "platform": "github",
        "configured": true,
        "client_id": "Ov23li...",
        "redirect_uri": "https://tools.wktyl.com/oauth/callback",
        "authorize_url": "https://github.com/login/oauth/authorize?client_id=Ov23li...&redirect_uri=...&scope=user:email&state=..."
    }
}

3.2 社交登录

POST /api/oauth/login

参数	类型	必填	说明
platform	string	✅	平台: apple/google/github
code	string	条件	授权码（google/github必填）
id_token	string	条件	Apple ID Token（apple必填）
device_name	string	❌	设备名称
device_model	string	❌	设备型号
platform_type	string	❌	登录平台(ios/android/web)
device_id	string	❌	设备唯一标识
ip_city	string	❌	IP归属地
ip_range	string	❌	IP段范围

Apple登录流程：

1. 客户端使用 sign_in_with_apple SDK 获取 id_token 和 authorization_code
2. POST /api/oauth/login 提交 platform=apple&id_token=xxx&code=xxx

Google登录流程：

1. 客户端使用 google_sign_in SDK 获取 serverAuthCode
2. POST /api/oauth/login 提交 platform=google&code=xxx

GitHub登录流程：

1. 客户端打开浏览器授权页面
2. 用户授权后回调获取 code
3. POST /api/oauth/login 提交 platform=github&code=xxx

成功响应：

{
    "code": 1,
    "msg": "登录成功",
    "data": {
        "userinfo": {
            "id": 42,
            "username": "github_abc12345",
            "nickname": "octocat",
            "email": "user@example.com",
            "avatar": "https://avatars.githubusercontent.com/u/..."
        },
        "token": "xxxxxxxxxxxx",
        "is_new_user": true,
        "bind_platform": "github"
    }
}

3.3 绑定社交账号

POST /api/oauth/bind

需登录。

参数	类型	必填	说明
platform	string	✅	平台: apple/google/github
code	string	条件	授权码
id_token	string	条件	Apple ID Token

3.4 解绑社交账号

POST /api/oauth/unbind

需登录。

参数	类型	必填	说明
platform	string	✅	平台: apple/google/github

3.5 已绑定列表

GET /api/oauth/bound

需登录。

响应示例：

{
    "code": 1,
    "msg": "",
    "data": {
        "bindings": [
            {
                "platform": "github",
                "openid": "github_12345",
                "nickname": "octocat",
                "avatar": "https://...",
                "createtime": 1717200000
            }
        ]
    }
}

3.6 安装数据表

GET /api/oauth/install

无需登录。创建 tool_user_oauth 表。

---

四、数据表设计

tool_user_oauth

字段	类型	说明
id	int(11) unsigned	主键自增
user_id	int(11) unsigned	用户ID
platform	varchar(30)	平台(apple/google/github)
openid	varchar(128)	平台用户ID
unionid	varchar(128)	联合ID
nickname	varchar(100)	昵称
avatar	varchar(500)	头像
access_token	text	访问令牌
refresh_token	text	刷新令牌
expires_at	int(11) unsigned	令牌过期时间
createtime	int(11) unsigned	创建时间
updatetime	int(11) unsigned	更新时间

索引： uk_platform_openid(platform, openid), idx_user_id(user_id)

---

五、错误码

code	msg	说明
0	不支持的平台	platform参数无效
0	平台未配置	OAuth配置缺失
0	OAuth验证失败	授权码/id_token无效
0	该账号已被其他用户绑定	绑定冲突
0	已绑定该平台	重复绑定
0	请求过于频繁	频率限制(30次/5分钟)

---

六、频率限制

接口	上限	时间窗口(秒)
login	30次	300
bind	20次	3600
unbind	20次	3600

---

七、安全说明

• Apple: 验证JWT的issuer和签名，不依赖客户端解析
• Google: 服务端用授权码换取access_token，客户端无法伪造
• GitHub: 服务端用授权码换取access_token，安全可靠
• 同一openid只能绑定一个闲言账号
• 邮箱相同的OAuth用户会自动关联已有账号