215 lines
4.8 KiB
Markdown
215 lines
4.8 KiB
Markdown
# 微博 OAuth2 扫码授权配置指南
|
||
|
||
## 功能说明
|
||
|
||
实现了微博 OAuth2 扫码授权功能，用户可以通过手机微博 APP 扫码快速添加账号，无需手动复制 Cookie。
|
||
|
||
## 配置步骤
|
||
|
||
### 1. 注册微博开放平台应用
|
||
|
||
1. 访问 [微博开放平台](https://open.weibo.com/)
|
||
2. 登录你的微博账号
|
||
3. 进入"微连接" > "网站接入"
|
||
4. 创建新应用，填写应用信息：
|
||
- 应用名称：Weibo-HotSign（或自定义）
|
||
- 应用简介：微博自动签到系统
|
||
- 应用类型：网站
|
||
- 应用地址：http://localhost:5000（开发环境）
|
||
|
||
5. 提交审核（测试阶段可以使用未审核的应用）
|
||
|
||
### 2. 配置回调地址
|
||
|
||
在应用管理页面：
|
||
1. 进入"应用信息" > "高级信息"
|
||
2. 设置"授权回调页"为：`http://localhost:5000/auth/weibo/callback`
|
||
3. 保存设置
|
||
|
||
### 3. 获取 APP KEY 和 APP SECRET
|
||
|
||
在应用管理页面：
|
||
1. 进入"应用信息" > "基本信息"
|
||
2. 复制 `App Key` 和 `App Secret`
|
||
|
||
### 4. 配置环境变量
|
||
|
||
编辑 `backend/.env` 和 `frontend/.env` 文件：
|
||
|
||
```env
|
||
# 微博 OAuth2 配置
|
||
WEIBO_APP_KEY=你的_App_Key
|
||
WEIBO_APP_SECRET=你的_App_Secret
|
||
WEIBO_REDIRECT_URI=http://localhost:5000/auth/weibo/callback
|
||
```
|
||
|
||
### 5. 重启服务
|
||
|
||
```bash
|
||
# 停止所有服务
|
||
stop_all.bat
|
||
|
||
# 启动所有服务
|
||
start_all.bat
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
### 用户端操作
|
||
|
||
1. 登录系统后，进入"添加账号"页面
|
||
2. 切换到"微博授权"标签页
|
||
3. 点击"生成授权二维码"按钮
|
||
4. 使用手机微博 APP 扫描二维码
|
||
5. 在手机上点击"同意授权"
|
||
6. 等待页面自动完成账号添加
|
||
7. 自动跳转到 Dashboard
|
||
|
||
### 技术流程
|
||
|
||
1. **生成授权 URL**
|
||
- 前端调用 `/auth/weibo/authorize` 接口
|
||
- 后端生成包含 `state` 参数的授权 URL
|
||
- 前端使用 QRCode.js 生成二维码
|
||
|
||
2. **用户扫码授权**
|
||
- 用户用手机微博扫码
|
||
- 跳转到微博授权页面（移动端适配）
|
||
- 用户点击"同意授权"
|
||
|
||
3. **微博回调**
|
||
- 微博跳转到 `/auth/weibo/callback?code=xxx&state=xxx`
|
||
- 后端用 `code` 换取 `access_token`
|
||
- 调用微博 API 获取用户信息
|
||
- 更新授权状态为成功
|
||
|
||
4. **前端轮询**
|
||
- 前端每 2 秒轮询 `/auth/weibo/check/<state>`
|
||
- 检测到授权成功后，调用 `/api/weibo/add-account`
|
||
- 自动添加账号到系统
|
||
|
||
5. **完成添加**
|
||
- 账号添加成功
|
||
- 跳转到 Dashboard
|
||
|
||
## API 接口说明
|
||
|
||
### 1. 生成授权 URL
|
||
|
||
```
|
||
GET /auth/weibo/authorize
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"auth_url": "https://api.weibo.com/oauth2/authorize?...",
|
||
"state": "random_state_string",
|
||
"expires_in": 180
|
||
}
|
||
```
|
||
|
||
### 2. 检查授权状态
|
||
|
||
```
|
||
GET /auth/weibo/check/<state>
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"status": "pending|success|error|expired",
|
||
"account_info": {...} // 仅在 success 时返回
|
||
}
|
||
```
|
||
|
||
### 3. 微博回调
|
||
|
||
```
|
||
GET /auth/weibo/callback?code=xxx&state=xxx
|
||
```
|
||
|
||
返回 HTML 页面，显示授权结果
|
||
|
||
### 4. 添加账号
|
||
|
||
```
|
||
POST /api/weibo/add-account
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"state": "state_string",
|
||
"remark": "备注（可选）"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Account added successfully",
|
||
"account": {...}
|
||
}
|
||
```
|
||
|
||
## 安全说明
|
||
|
||
1. **State 参数**：用于防止 CSRF 攻击，每次授权生成唯一的 state
|
||
2. **Session 存储**：授权状态临时存储在 session 中（生产环境建议使用 Redis）
|
||
3. **Token 加密**：access_token 会被加密存储在数据库中
|
||
4. **HTTPS**：生产环境必须使用 HTTPS
|
||
|
||
## 生产环境配置
|
||
|
||
### 1. 更新回调地址
|
||
|
||
```env
|
||
WEIBO_REDIRECT_URI=https://yourdomain.com/auth/weibo/callback
|
||
```
|
||
|
||
### 2. 在微博开放平台更新回调地址
|
||
|
||
进入应用管理 > 高级信息 > 授权回调页：
|
||
```
|
||
https://yourdomain.com/auth/weibo/callback
|
||
```
|
||
|
||
### 3. 使用 Redis 存储授权状态
|
||
|
||
修改 `frontend/app.py`，将 session 存储改为 Redis 存储。
|
||
|
||
## 故障排查
|
||
|
||
### 问题1：二维码生成失败
|
||
|
||
- 检查 `WEIBO_APP_KEY` 是否配置正确
|
||
- 检查网络连接
|
||
|
||
### 问题2：扫码后提示"回调地址不匹配"
|
||
|
||
- 检查 `WEIBO_REDIRECT_URI` 是否与微博开放平台配置一致
|
||
- 确保包含协议（http:// 或 https://）
|
||
|
||
### 问题3：授权成功但添加账号失败
|
||
|
||
- 检查后端 API 服务是否正常运行
|
||
- 查看后端日志排查错误
|
||
|
||
### 问题4：二维码过期
|
||
|
||
- 默认有效期 3 分钟
|
||
- 重新生成二维码即可
|
||
|
||
## 注意事项
|
||
|
||
1. 微博开放平台应用需要审核，测试阶段可以使用未审核的应用
|
||
2. 未审核的应用只能授权给应用创建者和测试账号
|
||
3. 建议使用小号或测试账号进行测试
|
||
4. access_token 有效期通常为 30 天，过期后需要重新授权
|
||
5. 生产环境必须使用 HTTPS
|
||
|
||
## 参考文档
|
||
|
||
- [微博 OAuth2 文档](https://open.weibo.com/wiki/Oauth2)
|
||
- [微博 API 文档](https://open.weibo.com/wiki/API)
|