241 lines
5.2 KiB
Markdown
241 lines
5.2 KiB
Markdown
# 微博扫码登录功能说明
|
||
|
||
## 功能概述
|
||
|
||
实现了基于微博网页版扫码登录接口的账号添加功能，无需注册微博开放平台应用，直接使用微博官方的扫码登录 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
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"qrid": "qr_id_string",
|
||
"qr_image": "data:image/png;base64,...",
|
||
"expires_in": 180
|
||
}
|
||
```
|
||
|
||
### 2. 检查扫码状态
|
||
|
||
```
|
||
GET /api/weibo/qrcode/check/<qrid>
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"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": "备注（可选）"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"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 格式：
|
||
```javascript
|
||
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 格式：
|
||
```javascript
|
||
STK_xxx({
|
||
"retcode": 20000000, // 或其他状态码
|
||
"alt": "跳转URL" // 仅在登录成功时返回
|
||
})
|
||
```
|
||
|
||
状态码说明：
|
||
- `20000000`: 等待扫码
|
||
- `50050001`: 已扫码，等待确认
|
||
- `20000001`: 确认成功
|
||
- `50050002`: 二维码过期
|
||
- `50050004`: 取消授权
|
||
|
||
### 获取用户信息接口
|
||
|
||
```
|
||
GET https://weibo.com/ajax/profile/info
|
||
Cookie: xxx
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"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
|