12 KiB
12 KiB
///
ARCHITECTURE.md
描述：WXAuto Center 系统架构文档
作者：AI Generated
创建日期：2026-04-05
更新日期：2026-04-06
///
WXAuto Center 系统架构文档
概述
WXAuto Center 是一个模块化的微信多节点中控系统，采用前后端分离架构，支持多节点管理、消息发送、插件扩展、定时任务等功能。
系统架构图
┌─────────────────────────────────────────────────────────────────────────────┐
│ WXAuto Center │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Frontend (Static) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │Dashboard │ │ Nodes │ │ Messages │ │ Plugins │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Backend │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
│ │ │nodes router │ │messages router│ │plugins router│ │webhook router│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
│ │ │callback router│ │external router│ │webhook service│ │queue service│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────┼────────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Redis │ │ PostgreSQL │ │ Nodes │ │
│ │ (Queue) │ │ (Storage) │ │ (External) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
核心组件
1. 前端 (Frontend)
静态文件服务，基于原生 JavaScript 开发。
页面模块：
| 页面 | 文件 | 说明 |
|---|---|---|
| 首页/仪表盘 | app.js | 系统概览 |
| 节点管理 | app.js | 节点 CRUD |
| 快捷消息 | app.js | 快速发送消息 |
| 监控告警 | app.js | Webhook 配置 |
| 日志查看 | app.js | 系统日志 |
| 外部接入 | app.js | 外部 API 文档 |
| 插件管理 | app.js | 插件配置 |
2. 后端 (Backend)
基于 FastAPI 的 RESTful API 服务。
API 模块：
| 模块 | 路径 | 说明 |
|---|---|---|
| nodes | /api/v1/nodes | 节点管理 |
| messages | /api/v1/messages | 消息发送 |
| plugins | /api/v1/plugins | 插件管理 |
| webhook | /api/v1/webhook | Webhook 管理 |
| callback | /api/v1/callback | 回调接口 |
| external | /api/v1/external | 外部接口 |
3. 服务层 (Services)
| 服务 | 说明 |
|---|---|
| node_manager | 节点管理器，内存缓存 |
| monitor_service | 节点健康监控服务 |
| scheduler_service | 定时任务调度服务 |
| log_service | 日志服务 |
| queue_service | 消息队列服务 |
| webhook_service | Webhook 通知服务 |
4. 插件系统 (Plugins)
| 插件 | 类型 | 说明 |
|---|---|---|
| http_data_source | DATA_SOURCE | HTTP 数据源 |
| database_query | DATA_SOURCE | 数据库查询 |
| webhook_trigger | ACTION_TRIGGER | Webhook 触发 |
| simple_ai_agent | AI_AGENT | AI 智能体 |
| http_scheduled_sender | SCHEDULED_TASK | 定时 HTTP 推送 |
5. 数据层 (Data)
| 组件 | 说明 |
|---|---|
| PostgreSQL | 主数据库，存储节点、Webhook、日志、插件配置 |
| Redis | 消息队列、缓存 |
目录结构
wxauto_api/
├── main.py # 应用入口
├── config.py # 配置管理
├── models.py # 数据模型
├── database_service.py # 数据库服务
├── requirements.txt # Python 依赖
├── Dockerfile # Docker 镜像
├── docker-compose.yml # Docker 编排
│
├── api/ # API 路由
│ ├── __init__.py
│ ├── nodes.py # 节点管理
│ ├── messages.py # 消息发送
│ ├── plugins.py # 插件管理
│ ├── webhook.py # Webhook 管理
│ ├── callback.py # 回调接口
│ └── external.py # 外部接口
│
├── services/ # 业务服务
│ ├── __init__.py
│ ├── node_manager.py # 节点管理
│ ├── monitor_service.py # 健康监控
│ ├── scheduler_service.py # 定时调度
│ ├── log_service.py # 日志服务
│ ├── queue_service.py # 队列服务
│ └── webhook_service.py # Webhook 服务
│
├── plugins/ # 插件系统
│ ├── __init__.py
│ ├── base.py # 插件基类
│ ├── builtin.py # 内置插件
│ └── http_scheduled_sender.py # 定时推送插件
│
├── utils/ # 工具函数
│ └── auth.py # 认证中间件
│
├── static/ # 静态文件
│ ├── index.html # 主页面
│ └── js/ # JavaScript
│ ├── api.js # API 封装
│ ├── app.js # 主应用
│ └── pages/
│ └── templates.js # 页面模板
│
└── doc/ # 文档
└── wxauto_center/
├── ARCHITECTURE.md # 架构文档
├── API.md # API 文档
├── DATABASE.md # 数据库文档
├── FLOWS.md # 流程文档
└── PLUGIN.md # 插件文档
技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端 | HTML/CSS/JavaScript | 原生开发，无框架依赖 |
| 后端 | Python 3.11 + FastAPI | 高性能异步框架 |
| 数据库 | PostgreSQL | 关系型数据库 |
| 缓存/队列 | Redis | 内存数据库、消息队列 |
| 容器 | Docker + Docker Compose | 容器化部署 |
| ORM | SQLAlchemy | Python ORM |
| HTTP 客户端 | httpx | 异步 HTTP 客户端 |
部署架构
┌─────────────────────────────────────────────────────────────┐
│ Docker Network │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ wxauto-center│ │ wxauto-redis │ │wxauto-postgres│ │
│ │ :8080 │ │ :6379 │ │ :5432 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ External Nodes │ │ External │
│ (wxauto nodes) │ │ Webhook URLs │
│ :5000 │ │ │
└──────────────────┘ └──────────────────┘
环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
POSTGRES_USER |
PostgreSQL 用户 | wxauto |
POSTGRES_PASSWORD |
PostgreSQL 密码 | wxauto_password |
POSTGRES_DB |
数据库名 | wxauto |
REDIS_PASSWORD |
Redis 密码 | wxauto_redis |
API_KEY |
API 认证密钥 | your-external-api-key |
EXTERNAL_KEY |
外部接口密钥 | your-external-api-key |
安全机制
1. API 认证
- 内部 API：Header
X-API-Key - 外部 API：Header
X-ExternalKey
2. 异常处理
- 全局异常处理器
- 所有 API 调用包裹 try/except
- 10 秒 HTTP 超时
3. 数据一致性
- 数据库优先原则
- 启动时从数据库加载配置
- 操作时同时更新内存和数据库