272 lines
5.0 KiB
Markdown
272 lines
5.0 KiB
Markdown
# WXAuto Relogin - API 接口文档
|
|
|
|
## 1. 概述
|
|
|
|
本文档定义 WXAuto Relogin 功能所需的 API 接口。
|
|
|
|
## 2. 回调接口
|
|
|
|
### 2.1 接收二维码
|
|
|
|
客户端上传二维码到中控。
|
|
|
|
```
|
|
POST /api/v1/callback/relogin/qrcode
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
X-API-Key: your-api-key
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**请求体:**
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"qrcode_base64": "data:image/png;base64,iVBORw0KGgo...",
|
|
"expires_in": 120
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| node_id | string | 是 | 节点ID |
|
|
| qrcode_base64 | string | 是 | Base64编码的PNG图片，带data URI前缀 |
|
|
| expires_in | integer | 否 | 过期时间（秒），默认120 |
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "二维码已接收",
|
|
"data": {
|
|
"status": "qrcode_ready",
|
|
"expires_at": "2026-04-07T15:30:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.2 更新重登录状态
|
|
|
|
```
|
|
POST /api/v1/callback/relogin/status
|
|
```
|
|
|
|
**请求体:**
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"status": "scanned",
|
|
"message": "用户已扫码"
|
|
}
|
|
```
|
|
|
|
| 状态 | 说明 |
|
|
|------|------|
|
|
| waiting_qrcode | 等待获取二维码 |
|
|
| qrcode_ready | 二维码已就绪 |
|
|
| scanned | 已扫码，待确认 |
|
|
| confirmed | 已确认，登录中 |
|
|
| completed | 登录完成 |
|
|
| failed | 登录失败 |
|
|
|
|
## 3. 节点接口
|
|
|
|
### 3.1 获取重登录状态
|
|
|
|
```
|
|
GET /api/v1/nodes/{node_id}/relogin/status
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"node_id": "wx1",
|
|
"status": "qrcode_ready",
|
|
"qrcode_base64": "data:image/png;base64,...",
|
|
"qrcode_expires_at": "2026-04-07T15:30:00",
|
|
"created_at": "2026-04-07T15:00:00",
|
|
"updated_at": "2026-04-07T15:05:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.2 清除重登录状态
|
|
|
|
```
|
|
DELETE /api/v1/nodes/{node_id}/relogin/status
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "状态已清除"
|
|
}
|
|
```
|
|
|
|
## 4. 客户端管理接口
|
|
|
|
### 4.1 注册客户端
|
|
|
|
```
|
|
POST /api/v1/relogin/clients
|
|
```
|
|
|
|
**请求体:**
|
|
```json
|
|
{
|
|
"client_name": "服务器1",
|
|
"webhook_url": "http://192.168.1.100:8081/webhook/relogin",
|
|
"secret_key": "optional_secret_for_signing"
|
|
}
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"id": 1,
|
|
"client_name": "服务器1",
|
|
"webhook_url": "http://192.168.1.100:8081/webhook/relogin",
|
|
"enabled": true,
|
|
"created_at": "2026-04-07T15:00:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 获取客户端列表
|
|
|
|
```
|
|
GET /api/v1/relogin/clients
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"client_name": "服务器1",
|
|
"webhook_url": "http://192.168.1.100:8081/webhook/relogin",
|
|
"enabled": true,
|
|
"created_at": "2026-04-07T15:00:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 4.3 更新客户端
|
|
|
|
```
|
|
PUT /api/v1/relogin/clients/{client_id}
|
|
```
|
|
|
|
**请求体:**
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
### 4.4 删除客户端
|
|
|
|
```
|
|
DELETE /api/v1/relogin/clients/{client_id}
|
|
```
|
|
|
|
## 5. Webhook 告警格式
|
|
|
|
中控向客户端发送的告警格式：
|
|
|
|
```json
|
|
{
|
|
"event": "wechat_offline",
|
|
"node_id": "wx1",
|
|
"node_name": "微信1",
|
|
"wechat_status": "offline",
|
|
"timestamp": "2026-04-07T15:00:00",
|
|
"message": "节点 wx1 微信掉线"
|
|
}
|
|
```
|
|
|
|
**event 类型:**
|
|
| 事件 | 说明 |
|
|
|------|------|
|
|
| wechat_offline | 微信掉线 |
|
|
| wechat_online | 微信上线 |
|
|
| node_offline | 节点离线 |
|
|
| node_online | 节点上线 |
|
|
|
|
## 6. 签名验证（可选）
|
|
|
|
如果配置了 secret_key，客户端应验证请求签名：
|
|
|
|
```
|
|
X-Signature: sha256=xxxxxxxxxxxxxx
|
|
```
|
|
|
|
**验证算法:**
|
|
```python
|
|
import hmac
|
|
import hashlib
|
|
|
|
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
|
|
expected = hmac.new(
|
|
secret.encode(),
|
|
payload,
|
|
hashlib.sha256
|
|
).hexdigest()
|
|
return hmac.compare_digest(f"sha256={expected}", signature)
|
|
```
|
|
|
|
## 7. 错误码
|
|
|
|
| 错误码 | 说明 |
|
|
|--------|------|
|
|
| 404 | 节点不存在 |
|
|
| 400 | 参数错误 |
|
|
| 401 | API Key无效 |
|
|
| 403 | 无权限 |
|
|
| 500 | 服务器内部错误 |
|
|
|
|
## 8. 使用示例
|
|
|
|
### 8.1 完整重登录流程
|
|
|
|
```bash
|
|
# 1. 微信掉线，中控发送告警到客户端
|
|
# 客户端接收: POST /webhook/relogin
|
|
|
|
# 2. 客户端从节点获取二维码
|
|
curl -o qrcode.png http://node-api:5000/api/wechat/qrcode \
|
|
-H "X-API-Key: node-api-key"
|
|
|
|
# 3. 客户端上传二维码到中控
|
|
curl -X POST http://center:8080/api/v1/callback/relogin/qrcode \
|
|
-H "X-API-Key: your-api-key" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"node_id": "wx1",
|
|
"qrcode_base64": "data:image/png;base64,...",
|
|
"expires_in": 120
|
|
}'
|
|
|
|
# 4. 前端轮询获取状态
|
|
curl http://center:8080/api/v1/nodes/wx1/relogin/status \
|
|
-H "X-API-Key: your-api-key"
|
|
|
|
# 5. 用户扫码确认后，节点回调通知中控
|
|
curl -X POST http://center:8080/api/v1/callback/node/check \
|
|
-d '{"node_id": "wx1", "status": "online"}'
|
|
|
|
# 6. 客户端轮询发现 completed
|
|
curl http://center:8080/api/v1/nodes/wx1/relogin/status
|
|
# 返回: {"status": "completed"}
|
|
```
|