wxauto_api/doc/wxautorelogin/API.md

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

请求体:

{
    "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

响应:

{
    "success": true,
    "message": "二维码已接收",
    "data": {
        "status": "qrcode_ready",
        "expires_at": "2026-04-07T15:30:00"
    }
}

2.2 更新重登录状态

POST /api/v1/callback/relogin/status

请求体:

{
    "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

响应:

{
    "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

响应:

{
    "success": true,
    "message": "状态已清除"
}

4. 客户端管理接口

4.1 注册客户端

POST /api/v1/relogin/clients

请求体:

{
    "client_name": "服务器1",
    "webhook_url": "http://192.168.1.100:8081/webhook/relogin",
    "secret_key": "optional_secret_for_signing"
}

响应:

{
    "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

响应:

{
    "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}

请求体:

{
    "enabled": false
}

4.4 删除客户端

DELETE /api/v1/relogin/clients/{client_id}

5. Webhook 告警格式

中控向客户端发送的告警格式：

{
    "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

验证算法:

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 完整重登录流程

# 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"}