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