wxauto_api/doc/wxauto_center

WXAuto Center 中控系统

项目简介

WXAuto Center 是一款基于 FastAPI + PostgreSQL + Redis 构建的多节点微信管理中控系统，为企业级微信自动化运营提供集中管理平台。该系统能够同时管理多个 WXAuto-HTTP-API 节点，实现消息统一发送、节点状态监控、实时日志查看和外部程序接入等功能。

主要功能

• 多节点微信管理：支持同时接入多个微信节点，按组分类管理
• 节点标识系统：每个节点拥有唯一的 node_id（如 "wx1", "node_001"）和显示用的 name（如 "微信1", "测试节点"）
• 消息发送：支持单发、群发、批量发送、模板消息等多种发送模式
• 健康检测机制：通过 /api/wechat/initialize 接口检测微信状态，确保消息发送前微信正常运行
• Webhook 告警：支持企业微信(wechat)和 Bark 两种格式，节点/微信状态变化时自动通知
• 实时日志：通过 SSE（Server-Sent Events）技术实现日志实时推送，默认保留最近500条
• Redis 消息队列：支持 Redis 后端的消息队列，用于异步消息处理
• 多进程支持：支持多 worker 部署，适应高并发场景
• 外部程序接入：提供标准 RESTful API，支持外部系统调用
• 插件系统：支持扩展插件，包括数据源、AI 智能体、Webhook触发器等

快速开始

环境要求

• Python 3.8+
• Redis (用于消息队列和多进程场景)
• FastAPI
• httpx（异步 HTTP 客户端）
• uvicorn（ASGI 服务器）
• pydantic
• pydantic-settings

安装步骤

# 进入项目目录
cd wxauto_center

# 安装依赖
pip install -r requirements.txt

# 复制配置示例文件
cp .env.example .env

# 编辑 .env 文件，修改必要的配置项

启动服务

# 单进程启动（默认）
python run.py

# 多进程启动（需要 Redis）
python run.py --workers 4

# 带参数启动
python run.py --host 0.0.0.0 --port 8080 --workers 4

# 开发模式（支持热重载，单进程）
python run.py --reload

# 调试模式
python run.py --debug

替代启动方式：

# 使用 uvicorn 直接启动
uvicorn main:app --host 0.0.0.0 --port 8080 --reload

访问地址

• 主界面：http://localhost:8080/static/index.html
• API 文档：http://localhost:8080/docs
• ReDoc 文档：http://localhost:8080/redoc

快速使用示例

1. 添加节点

curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-external-api-key" \
  -d '{
    "node_id": "wx1",
    "name": "微信1",
    "api_url": "http://192.168.20.18:5000",
    "api_key": "your-node-api-key",
    "description": "生产节点",
    "group": "wechat"
  }'

节点标识说明：

• node_id：节点唯一标识，如 "wx1", "node_001"，用于 API 调用
• name：节点显示名称，如 "微信1", "测试节点"，用于界面展示

2. 发送消息

curl -X POST http://localhost:8080/api/v1/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-external-api-key" \
  -d '{
    "node_id": "wx1",
    "who": "wxid_friend",
    "msg": "您好，这是一条测试消息",
    "msg_type": "text"
  }'

3. 查询节点状态

curl http://localhost:8080/api/v1/nodes/wx1/status \
  -H "X-API-Key: your-external-api-key"

4. 重置微信状态（当微信掉线时）

curl -X POST http://localhost:8080/api/v1/callback/node/reset \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-external-api-key" \
  -d '{
    "node_id": "wx1"
  }'

项目结构

wxauto_api/
├── main.py                 # FastAPI 主入口
├── run.py                  # 启动脚本
├── config.py              # 配置管理
├── config.json           # 应用配置（不含节点和 Webhook）
├── .env                  # Docker 环境变量配置
├── models.py             # 数据模型（Node, LogEntry, WebhookUrl）
├── database_service.py   # 数据库服务
├── api/                   # API 路由模块
│   ├── __init__.py
│   ├── nodes.py          # 节点管理 API
│   ├── messages.py       # 消息发送 API
│   ├── external.py       # 外部扩展接口
│   ├── callback.py       # 回调接口
│   ├── plugins.py        # 插件管理 API
│   └── webhook.py        # Webhook 管理 API
├── services/             # 业务逻辑服务
│   ├── node_manager.py   # 节点管理器
│   ├── monitor_service.py # 监控服务
│   └── log_service.py    # 日志服务
├── plugins/              # 插件系统
│   ├── base.py          # 插件基类
│   └── builtin.py       # 内置插件
├── static/              # Web 静态资源
│   ├── index.html       # 主页面
│   ├── css/style.css    # 样式表
│   └── js/              # JavaScript 模块
├── scripts/             # 脚本目录
│   ├── start_amd64.sh   # amd64 启动脚本
│   ├── start_arm64.sh   # arm64 启动脚本
│   └── database/        # 数据库脚本
├── doc/                 # 文档目录
│   └── wxauto_center/  # 项目文档
├── data/                # 数据目录
│   ├── db/             # PostgreSQL 数据
│   ├── redis/          # Redis 数据
│   └── logs/           # 应用日志
├── docker-compose.yml   # Docker Compose 配置
└── Dockerfile           # Docker 构建文件

配置说明

系统配置支持多种配置源，按优先级从高到低依次为：

1. 环境变量（.env 文件）
2. 配置文件（config.json）
3. 代码默认值

配置文件

config.json - 应用配置（不含节点和 Webhook）：

{
    "app_name": "WXAuto Center",
    "host": "0.0.0.0",
    "port": 8080,
    "debug": true,
    "secret_key": "wxauto-center-secret-key-change-in-production",
    "workers": 1,
    "cors_origins": ["*"],
    "api_prefix": "/api/v1",
    "external_api_key": "your-external-api-key",
    "monitor": {
        "enabled": true,
        "check_interval": 30
    }
}

.env - Docker 环境变量配置：

DATABASE_URL=postgresql://wxauto:wxauto_password@postgres:5432/wxauto
REDIS_URL=redis://redis:6379/0
APP_NAME=WXAuto Center
HOST=0.0.0.0
PORT=8080
DEBUG=true
SECRET_KEY=wxauto-center-secret-key-change-in-production
WORKERS=1
API_PREFIX=/api/v1
EXTERNAL_API_KEY=your-external-api-key
CORS_ORIGINS=["*"]
MONITOR_ENABLED=true
MONITOR_CHECK_INTERVAL=30

节点配置

节点配置存储在 PostgreSQL 的 nodes 表中，运行时从数据库加载。详细说明请参阅 CONFIG.md。

Webhook 配置

Webhook 配置存储在 PostgreSQL 的 webhook_urls 表中，支持企业微信和 Bark 两种格式。详细说明请参阅 CONFIG.md。

API 文档

系统提供完整的 RESTful API，包括：

• 节点管理：/api/v1/nodes - 节点的添加、删除、启用/禁用、状态检测
• 消息发送：/api/v1/messages - 单发、群发、批量发送、模板消息
• 外部接口：/api/v1/external - 供外部程序调用的接口
• 回调接口：/api/v1/callback - 节点状态重置、状态检测
• 插件管理：/api/v1/plugins - 插件的注册和调用
• 配置管理：/api/v1/config/webhook, /api/v1/config/monitor - Webhook和监控配置
• 监控状态：/api/v1/monitor/status - 实时监控状态
• 日志服务：/api/v1/logs/* - 日志查询和实时推送(SSE)

详细 API 说明请参阅 API.md

业务流程

系统主要业务流程包括消息发送流程、回调重置流程和监控告警流程。详细说明请参阅 FLOWS.md。

开发指南

如需进行二次开发或扩展功能，请参阅 DEVELOPMENT.md，其中包含：

• 开发环境搭建
• 代码结构说明
• 插件开发指南
• API 调用示例

常见问题

如遇到问题，请参阅 TROUBLESHOOTING.md

核心设计理念

1. 节点标识系统

每个节点有两个标识：

• node_id：节点唯一标识符，用于 API 调用和系统内部引用，示例："wx1", "node_001"
• name：节点显示名称，用于界面展示和用户友好提示，示例："微信1", "测试节点"

2. 健康检测机制

每次发送消息前，系统会自动调用 /api/wechat/initialize 接口初始化微信，确保微信处于可发送消息的状态。这是官方推荐的正确流程。

3. 监控告警

监控服务定时检测所有节点和微信状态，当状态发生变化时自动触发Webhook通知。支持的事件类型包括：api_error、wechat_offline、wechat_online、node_offline、node_online。

4. 日志服务

采用内存存储+发布订阅模式，支持SSE实时推送。默认保留最近500条日志，足够应对日常调试和监控需求。

许可证

本项目仅供学习交流使用，请勿用于违规用途。