用户安全接口（11 类 34 接口）

基础URL: https://tools.wktyl.com
维护: Xianyan 团队 | 更新时间: 2026-08-15
关联: OAuth 授权 · 任务/勋章

职责：账号生命周期（注册 / 登录 / 注销）+ 身份验证（密码 / 密保 / 回执 / 二维码）+ 安全凭证（Token / HMAC）。

1. 通用约定

1.1 请求 / 响应

所有接口均返回统一格式：

1.2 认证 Token

登录成功 → 响应 Header 含 __token__，同时 Set-Cookie: uid=<id>; token=<token>。后续请求三选一：

# Header（推荐）
token: eyJ0eXAiOiJKV1Q...
# Cookie
Cookie: uid=1; token=eyJ0eXAi...
# URL 参数
?token=eyJ0eXAi...

1.3 6 种登录方式

receiptLogin 支持 account 同时填用户名、邮箱、手机号之一，服务端自动识别。

2. 核心流程图

mermaid sequenceDiagram participant C as Client participant S as Server C->>S: POST /login {account, password, device_id, platform} S-->>C: 200 {code:1, data:{token, user_id}} C->>S: GET /api/some-api (Header: token) S->>S: verify token + 更新 last_active S-->>C: 业务响应

3. 接口清单（按功能分组）

3.1 注册 / 登录

• POST /api/user_security/register — 注册（用户名/邮箱/手机任选其一，可选密保）
• POST /api/user_security/login — 用户名/邮箱+密码登录
• POST /api/user_security/mobilelogin — 手机+短信验证码登录
• POST /api/user_security/tokenLogin — 用现有 Token 续期
• POST /api/user_security/receiptLogin — 账号+回执登录（v8.0+）
• POST /api/user_security/checkusername — 实时检测用户名占用（v10.2.2+）

3.2 登录凭证

• POST /api/user_security/sendEms — 发送邮箱验证码（保留兼容，新代码建议走 receipt）
• POST /api/user_security/checkEms — 校验邮箱验证码
• POST /api/user_security/sendMobileCaptcha — 发送短信验证码
• POST /api/user_security/checkMobileCaptcha — 校验短信验证码

3.3 密码管理

• POST /api/user_security/changepwd — 修改密码（需验证：旧密码 / 密保 / 回执 三选一）
• POST /api/user_security/resetpwd — 找回密码（密保 / 邮箱回执）
• POST /api/user_security/secQuestions — 获取预置密保问题列表（v10.1+）
• POST /api/user_security/changeSecQuestion — 设置 / 修改密保问题（v10.1+）

3.4 账号变更

• POST /api/user_security/changeemail — 修改邮箱（验证方式：邮箱回执 / 密保）
• POST /api/user_security/changemobile — 修改手机号（验证方式：短信回执 / 密保）
• POST /api/user_security/changeavatar — 修改头像

3.5 二维码登录（v9.0+）

• GET /api/user_security/qrcodeGenerate — 生成登录二维码（返回 code + qr_url）
• POST /api/user_security/qrcodeConfirm — APP 端确认登录（传 code + token）
• GET /api/user_security/qrcodePoll — Web 端轮询（返回 pending/confirmed/expired）
• POST /api/user_security/qrcodeCancel — 取消二维码登录

3.6 账号注销

• POST /api/user_security/applyDeactivate — 申请注销（进入 7 天冷静期）
• GET /api/user_security/deactivateStatus — 查询注销状态
• POST /api/user_security/cancelDeactivate — 撤回注销申请
• POST /api/user_security/confirmDeactivate — 二次确认（冷静期后）

3.7 设备与在线（登录时附加）

• 所有 login 接口均支持 POST 参数：device_name, device_model, platform, app_name, device_id, ip_city, ip_range
• device_id 用于去重（同一设备只保留一条在线记录）
• ip_city / ip_range 由客户端通过 IP 接口传入，服务端不查

3.8 第三方账号绑定

• 绑定类见 OAuth 文档 §绑定解绑

4. 关键示例

4.1 注册

POST /api/user_security/register
Content-Type: application/json

{
  "username": "alice",
  "password": "P@ssw0rd!",
  "mobile": "13800138000",
  "sec_question": 3,
  "sec_answer": "我的宠物"
}

# 响应
{
  "code": 1,
  "msg": "注册成功",
  "data": {
    "user_id": 12345,
    "token": "eyJ0eXAi..."
  }
}

4.2 二维码登录（Web 端）

mermaid sequenceDiagram participant W as Web participant S as Server participant A as App W->>S: GET /qrcodeGenerate S-->>W: {code: "abc123", qr_url: "..."} A->>S: POST /qrcodeConfirm {code, token} S-->>A: {confirmed: true} W->>S: GET /qrcodePoll?code=abc123 S-->>W: {status: "confirmed", login_token: "..."}

5. 回执（Receipt）机制

核心思想：客户端自行验证邮箱 / 手机 / 短信，服务端只验签回执，不再受验证码通道限制。

POST /api/user_security/receiptLogin
Content-Type: application/json

{
  "account": "alice",          # 用户名 / 邮箱 / 手机 任一
  "receipt": "<base64-json>",  # 客户端拼接：email + 时间戳 + 唯一值
  "sig": "HmacSHA256(...)"     # 用回执密钥对 receipt 签名
}

# 响应
{
  "code": 1,
  "data": {
    "user_id": 12345,
    "token": "eyJ0eXAi...",
    "new_user": false          # true 表示自动创建账号
  }
}

回执密钥：Xy7kP9mL2qR4wS8v（HMAC-SHA256），不公开传输，只用于客户端签名。

6. 频率限制

超限：

{
  "code": 0,
  "msg": "请求过于频繁，请稍后再试",
  "data": { "retry_after": 300 }
}

7. 常见错误码

8. 设计要点

• Receipt 优于验证码：避免短信通道限速、可离线校验、可在多设备复用
• 二维码登录统一为 60s 过期：防止"悬挂二维码"被攻击
• 注销 7 天冷静期：所有数据仍在，期内可撤回；过期后清理
• 设备去重靠 device_id：同设备登录不重复建条
• HMAC 密钥只下发到客户端：回执签名过程不可逆向，凭证不下发服务端

9. 关联文档

• OAuth 三方授权 — GitHub / Apple / Google 登录 / bind / unbind
• 用户中心 — 用户资料、偏好、个性化设置
• 用户运营 (任务/勋章/签到) — 游戏化运营体系（合并查阅）
• 统计与分析 — 注册/活跃度统计