weibo_signin/WEIBO_QRCODE_LOGIN.md

微博扫码登录功能说明

功能概述

实现了基于微博网页版扫码登录接口的账号添加功能，无需注册微博开放平台应用，直接使用微博官方的扫码登录 API。

实现原理

通过逆向微博网页版（weibo.com）的扫码登录流程，调用微博的内部 API：

1. 生成二维码：调用 https://login.sina.com.cn/sso/qrcode/image 获取二维码图片
2. 轮询状态：调用 https://login.sina.com.cn/sso/qrcode/check 检查扫码状态
3. 获取 Cookie：扫码成功后通过跳转 URL 获取登录 Cookie
4. 获取用户信息：使用 Cookie 调用微博 API 获取用户 UID 和昵称
5. 自动添加账号：将获取的信息自动添加到系统

使用流程

用户操作

1. 登录系统后，进入"添加账号"页面
2. 切换到"扫码添加"标签页
3. 点击"生成二维码"按钮
4. 使用手机微博 APP 扫描二维码
5. 在手机上点击"确认登录"
6. 等待页面自动完成账号添加
7. 自动跳转到 Dashboard

技术流程

用户点击生成二维码
    ↓
调用 /api/weibo/qrcode/generate
    ↓
请求微博 API 获取二维码
    ↓
显示二维码图片
    ↓
前端开始轮询 /api/weibo/qrcode/check/<qrid>
    ↓
后端轮询微博 API 检查状态
    ↓
状态变化：waiting → scanned → success
    ↓
获取跳转 URL 和 Cookie
    ↓
调用微博 API 获取用户信息
    ↓
前端调用 /api/weibo/qrcode/add-account
    ↓
添加账号到系统
    ↓
跳转到 Dashboard

API 接口

1. 生成二维码

POST /api/weibo/qrcode/generate

返回：

{
  "success": true,
  "qrid": "qr_id_string",
  "qr_image": "data:image/png;base64,...",
  "expires_in": 180
}

2. 检查扫码状态

GET /api/weibo/qrcode/check/<qrid>

返回：

{
  "status": "waiting|scanned|success|expired|cancelled|error",
  "weibo_uid": "123456789",  // 仅在 success 时返回
  "screen_name": "用户昵称"   // 仅在 success 时返回
}

状态说明：

• waiting: 等待扫码
• scanned: 已扫码，等待确认
• success: 确认成功
• expired: 二维码过期
• cancelled: 取消登录
• error: 发生错误

3. 添加账号

POST /api/weibo/qrcode/add-account
Content-Type: application/json

{
  "qrid": "qr_id_string",
  "remark": "备注（可选）"
}

返回：

{
  "success": true,
  "message": "Account added successfully",
  "account": {...}
}

微博 API 说明

生成二维码接口

GET https://login.sina.com.cn/sso/qrcode/image?entry=weibo&size=180&callback=STK_xxx

返回 JSONP 格式：

STK_xxx({
  "retcode": 20000000,
  "qrid": "xxx",
  "image": "data:image/png;base64,..."
})

检查扫码状态接口

GET https://login.sina.com.cn/sso/qrcode/check?entry=weibo&qrid=xxx&callback=STK_xxx

返回 JSONP 格式：

STK_xxx({
  "retcode": 20000000,  // 或其他状态码
  "alt": "跳转URL"       // 仅在登录成功时返回
})

状态码说明：

• 20000000: 等待扫码
• 50050001: 已扫码，等待确认
• 20000001: 确认成功
• 50050002: 二维码过期
• 50050004: 取消授权

获取用户信息接口

GET https://weibo.com/ajax/profile/info
Cookie: xxx

返回：

{
  "ok": 1,
  "data": {
    "user": {
      "idstr": "123456789",
      "screen_name": "用户昵称",
      ...
    }
  }
}

优势

1. 无需注册应用：不需要在微博开放平台注册应用
2. 无需配置：不需要配置 APP_KEY 和 APP_SECRET
3. 真实 Cookie：获取的是真实的登录 Cookie，可用于签到
4. 用户体验好：扫码即可完成，无需手动复制 Cookie

注意事项

1. 接口稳定性：使用的是微博内部 API，可能会变化
2. Cookie 有效期：获取的 Cookie 有效期通常较长，但仍可能过期
3. 安全性：Cookie 会被加密存储在数据库中
4. 二维码有效期：默认 3 分钟，过期后需重新生成
5. 轮询频率：前端每 2 秒轮询一次状态

故障排查

问题1：生成二维码失败

• 检查网络连接
• 检查微博 API 是否可访问
• 查看后端日志

问题2：扫码后长时间无响应

• 检查轮询是否正常
• 查看浏览器控制台是否有错误
• 刷新页面重试

问题3：添加账号失败

• 检查后端 API 服务是否正常
• 查看后端日志排查错误
• 确认 Cookie 是否有效

问题4：二维码过期

• 默认有效期 3 分钟
• 重新生成二维码即可

与 OAuth2 方案对比

特性	扫码登录（当前方案）	OAuth2 授权
需要注册应用	❌ 不需要	✅ 需要
配置复杂度	低	高
获取的凭证	真实 Cookie	Access Token
接口稳定性	中（内部 API）	高（官方 API）
用户体验	好	好
适用场景	个人项目	商业项目

未来改进

1. 添加错误重试机制
2. 优化轮询策略（WebSocket）
3. 添加二维码刷新功能
4. 支持多账号批量添加
5. 添加扫码记录和统计

参考资料

• 微博网页版：https://weibo.com
• 微博登录页面：https://login.sina.com.cn