# /// # 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. 数据一致性 - 数据库优先原则 - 启动时从数据库加载配置 - 操作时同时更新内存和数据库