619 lines
14 KiB
Markdown
619 lines
14 KiB
Markdown
# ///
|
||
# CONFIG.md
|
||
# 描述：配置文件说明
|
||
# 作者：AI Generated
|
||
# 创建日期：2026-04-06
|
||
# 最后更新：2026-04-06
|
||
# ///
|
||
|
||
# WXAuto Center 配置文件说明
|
||
|
||
## 概述
|
||
|
||
系统配置支持多种配置源，按优先级从高到低依次为：
|
||
1. 环境变量（`.env` 文件）
|
||
2. 配置文件（`config.json`）
|
||
3. 代码默认值
|
||
|
||
## 配置文件结构
|
||
|
||
### config.json
|
||
|
||
主配置文件，仅包含应用配置。**节点配置和 Webhook 配置已迁移到数据库**。
|
||
|
||
```json
|
||
{
|
||
"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 环境变量配置文件。
|
||
|
||
```
|
||
# ///
|
||
# .env
|
||
# 描述：环境变量配置（用于 Docker 环境）
|
||
# ///
|
||
|
||
# 数据库配置
|
||
DATABASE_URL=postgresql://wxauto:wxauto_password@postgres:5432/wxauto
|
||
|
||
# Redis 配置
|
||
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 配置
|
||
API_PREFIX=/api/v1
|
||
EXTERNAL_API_KEY=your-external-api-key
|
||
CORS_ORIGINS=["*"]
|
||
|
||
# 监控配置
|
||
MONITOR_ENABLED=true
|
||
MONITOR_CHECK_INTERVAL=30
|
||
```
|
||
|
||
---
|
||
|
||
## 配置项详细说明
|
||
|
||
### 应用配置
|
||
|
||
#### app_name
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | string |
|
||
| 默认值 | "WXAuto Center" |
|
||
| 环境变量 | APP_NAME |
|
||
| 说明 | 应用名称，显示在页面标题和日志中 |
|
||
|
||
#### host
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | string |
|
||
| 默认值 | "0.0.0.0" |
|
||
| 环境变量 | HOST |
|
||
| 说明 | 服务监听地址，0.0.0.0 表示监听所有网络接口 |
|
||
|
||
#### port
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | int |
|
||
| 默认值 | 8080 |
|
||
| 环境变量 | PORT |
|
||
| 说明 | 服务监听端口 |
|
||
|
||
#### debug
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | bool |
|
||
| 默认值 | false |
|
||
| 环境变量 | DEBUG |
|
||
| 说明 | 调试模式，启用时支持热重载 |
|
||
|
||
#### secret_key
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | string |
|
||
| 默认值 | "wxauto-center-secret-key-change-in-production" |
|
||
| 环境变量 | SECRET_KEY |
|
||
| 说明 | 应用密钥，用于会话加密等安全用途，生产环境必须修改 |
|
||
|
||
---
|
||
|
||
### API 配置
|
||
|
||
#### api_prefix
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | string |
|
||
| 默认值 | "/api/v1" |
|
||
| 环境变量 | API_PREFIX |
|
||
| 说明 | API 路由前缀，所有 API 路径都会此前缀开头 |
|
||
|
||
#### external_api_key
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | string |
|
||
| 默认值 | "your-external-api-key" |
|
||
| 环境变量 | EXTERNAL_API_KEY |
|
||
| 说明 | 外部 API 密钥，用于外部系统调用时的认证 |
|
||
|
||
#### cors_origins
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 类型 | array[string] |
|
||
| 默认值 | ["*"] |
|
||
| 环境变量 | CORS_ORIGINS |
|
||
| 说明 | 允许的 CORS 来源，* 表示允许所有来源（仅限开发环境使用） |
|
||
|
||
---
|
||
|
||
## 节点配置 (NodeConfig)
|
||
|
||
**重要更新**：节点配置已从 config.json 迁移到 PostgreSQL 数据库的 `nodes` 表。
|
||
|
||
### 配置存储
|
||
|
||
| 存储位置 | 说明 |
|
||
|----------|------|
|
||
| PostgreSQL | nodes 表（生产环境推荐） |
|
||
| config.json | 已废弃，不再支持 |
|
||
|
||
### 节点数据模型
|
||
|
||
```json
|
||
{
|
||
"node_id": "wx1",
|
||
"name": "微信1",
|
||
"api_url": "http://192.168.1.100:5000",
|
||
"api_key": "your-node-api-key",
|
||
"enabled": true,
|
||
"description": "主节点",
|
||
"group": "default",
|
||
"status": "active",
|
||
"wechat_status": "online",
|
||
"is_healthy": true
|
||
}
|
||
```
|
||
|
||
### 节点标识说明
|
||
|
||
每个节点有两个标识：
|
||
|
||
| 字段 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| node_id | 节点唯一标识，用于 API 调用 | "wx1", "node_001" |
|
||
| name | 节点显示名称，用于界面展示 | "微信1", "测试节点" |
|
||
|
||
### 配置项说明
|
||
|
||
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| node_id | string | 是 | - | 节点唯一标识（不可重复） |
|
||
| name | string | 否 | 等于 node_id | 节点显示名称 |
|
||
| api_url | string | 是 | - | 节点 API 服务地址 |
|
||
| api_key | string | 是 | - | 节点 API 密钥 |
|
||
| enabled | bool | 否 | true | 是否启用该节点 |
|
||
| description | string | 否 | "" | 节点描述信息 |
|
||
| group | string | 否 | "default" | 节点分组，用于分类管理 |
|
||
|
||
### API 管理节点
|
||
|
||
通过 API 管理节点配置：
|
||
|
||
```bash
|
||
# 添加节点
|
||
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.1.100:5000",
|
||
"api_key": "your-node-api-key",
|
||
"description": "主节点",
|
||
"group": "production"
|
||
}'
|
||
|
||
# 获取所有节点
|
||
curl http://localhost:8080/api/v1/nodes \
|
||
-H "X-API-Key: your-external-api-key"
|
||
|
||
# 更新节点
|
||
curl -X PUT http://localhost:8080/api/v1/nodes/wx1 \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: your-external-api-key" \
|
||
-d '{"enabled": false}'
|
||
|
||
# 删除节点
|
||
curl -X DELETE http://localhost:8080/api/v1/nodes/wx1 \
|
||
-H "X-API-Key: your-external-api-key"
|
||
```
|
||
|
||
### 节点分组
|
||
|
||
节点分组功能允许将节点按业务线或用途进行分类管理：
|
||
|
||
```bash
|
||
# 查询特定分组的节点
|
||
curl "http://localhost:8080/api/v1/nodes?group=production" \
|
||
-H "X-API-Key: your-external-api-key"
|
||
```
|
||
|
||
---
|
||
|
||
## Webhook 配置 (WebhookConfig)
|
||
|
||
**重要更新**：Webhook 配置已从 config.json 迁移到 PostgreSQL 数据库的 `webhook_urls` 表。
|
||
|
||
### 配置存储
|
||
|
||
| 存储位置 | 说明 |
|
||
|----------|------|
|
||
| PostgreSQL | webhook_urls 表（推荐） |
|
||
| config.json | 已废弃，不再支持 |
|
||
|
||
### Webhook 数据模型
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "企业微信告警",
|
||
"url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx",
|
||
"format": "wechat",
|
||
"enabled": true,
|
||
"event_types": "wechat_offline,wechat_online,node_offline,node_online",
|
||
"created_at": "2026-04-06T10:00:00",
|
||
"updated_at": "2026-04-06T10:00:00"
|
||
}
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| name | string | 是 | - | Webhook 名称 |
|
||
| url | string | 是 | - | Webhook URL 地址 |
|
||
| format | string | 否 | "bark" | 消息格式：bark 或 wechat |
|
||
| enabled | bool | 否 | true | 是否启用 |
|
||
| event_types | string | 否 | 全部事件 | 需要触发 Webhook 的事件类型 |
|
||
|
||
### 支持的事件类型
|
||
|
||
| 事件类型 | 说明 | 触发时机 |
|
||
|----------|------|----------|
|
||
| api_error | API 错误 | 调用节点 API 失败 |
|
||
| wechat_offline | 微信掉线 | 微信状态变为 offline |
|
||
| wechat_online | 微信上线 | 微信状态变为 online/connected |
|
||
| node_offline | 节点离线 | 节点 API 不可达 |
|
||
| node_online | 节点在线 | 节点 API 恢复可用 |
|
||
|
||
### 消息格式
|
||
|
||
#### 企业微信格式 (format: "wechat")
|
||
|
||
```json
|
||
{
|
||
"msgtype": "text",
|
||
"text": {
|
||
"content": "【WXAuto Center 告警】\n事件类型: 微信掉线\n节点: wx1\n状态: offline\n时间: 2026-04-05 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Bark 格式 (format: "bark")
|
||
|
||
```json
|
||
{
|
||
"title": "WXAuto告警 - 微信掉线",
|
||
"body": "wx1\n状态: offline\n时间: 2026-04-05 10:00:00"
|
||
}
|
||
```
|
||
|
||
### API 管理 Webhook
|
||
|
||
```bash
|
||
# 添加 Webhook
|
||
curl -X POST http://localhost:8080/api/v1/webhook \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: your-external-api-key" \
|
||
-d '{
|
||
"name": "企业微信告警",
|
||
"url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx",
|
||
"format": "wechat",
|
||
"enabled": true,
|
||
"event_types": "wechat_offline,wechat_online,node_offline,node_online"
|
||
}'
|
||
|
||
# 获取所有 Webhook
|
||
curl http://localhost:8080/api/v1/webhook \
|
||
-H "X-API-Key: your-external-api-key"
|
||
|
||
# 更新 Webhook
|
||
curl -X PUT http://localhost:8080/api/v1/webhook/1 \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: your-external-api-key" \
|
||
-d '{"enabled": false}'
|
||
|
||
# 删除 Webhook
|
||
curl -X DELETE http://localhost:8080/api/v1/webhook/1 \
|
||
-H "X-API-Key: your-external-api-key"
|
||
|
||
# 启用/禁用 Webhook
|
||
curl -X POST http://localhost:8080/api/v1/webhook/1/enable \
|
||
-H "X-API-Key: your-external-api-key"
|
||
|
||
curl -X POST http://localhost:8080/api/v1/webhook/1/disable \
|
||
-H "X-API-Key: your-external-api-key"
|
||
```
|
||
|
||
---
|
||
|
||
## 监控配置 (MonitorConfig)
|
||
|
||
监控服务负责定时检测节点和微信状态。
|
||
|
||
```json
|
||
{
|
||
"monitor": {
|
||
"enabled": true,
|
||
"check_interval": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| enabled | bool | 否 | true | 是否启用监控服务 |
|
||
| check_interval | int | 否 | 30 | 检测间隔（秒） |
|
||
|
||
### 检测逻辑
|
||
|
||
1. **API 检测**：定期调用节点 `/health` 接口检查节点是否在线
|
||
2. **微信检测**：定期调用 `/api/wechat/initialize` 检测微信连接状态
|
||
3. **状态变化**：当检测到状态变化时，触发 Webhook 通知
|
||
|
||
---
|
||
|
||
## 数据库配置
|
||
|
||
数据库配置通过环境变量设置：
|
||
|
||
| 环境变量 | 说明 | 默认值 |
|
||
|----------|------|--------|
|
||
| DATABASE_URL | PostgreSQL 连接 URL | postgresql://wxauto:wxauto_password@postgres:5432/wxauto |
|
||
|
||
### Docker 环境
|
||
|
||
```bash
|
||
DATABASE_URL=postgresql://wxauto:wxauto_password@postgres:5432/wxauto
|
||
```
|
||
|
||
### 本地环境
|
||
|
||
```bash
|
||
DATABASE_URL=postgresql://wxauto:wxauto_password@localhost:5432/wxauto
|
||
```
|
||
|
||
---
|
||
|
||
## Redis 配置
|
||
|
||
Redis 用于消息队列和缓存支持。
|
||
|
||
| 环境变量 | 说明 | 默认值 |
|
||
|----------|------|--------|
|
||
| REDIS_URL | Redis 连接 URL | redis://redis:6379/0 |
|
||
|
||
### Docker 环境
|
||
|
||
```bash
|
||
REDIS_URL=redis://redis:6379/0
|
||
```
|
||
|
||
### 本地环境
|
||
|
||
```bash
|
||
REDIS_URL=redis://localhost:6379/0
|
||
```
|
||
|
||
---
|
||
|
||
## Workers 配置
|
||
|
||
Workers 用于多进程部署，提高并发处理能力。
|
||
|
||
```json
|
||
{
|
||
"workers": 1
|
||
}
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| workers | int | 否 | 1 | 工作进程数，1 表示单进程模式 |
|
||
|
||
### 启动方式
|
||
|
||
| 模式 | workers | 说明 |
|
||
|------|---------|------|
|
||
| 单进程 | 1 | 默认模式，不启用多进程 |
|
||
| 多进程 | >1 | 启用多进程模式，需要 Redis 支持 |
|
||
|
||
**注意**：多进程模式需要 Redis 支持，队列服务依赖 Redis 进行进程间通信。
|
||
|
||
### 启动命令
|
||
|
||
```bash
|
||
# 单进程
|
||
python main.py
|
||
|
||
# 多进程
|
||
python main.py --workers 4
|
||
```
|
||
|
||
---
|
||
|
||
## 完整配置示例
|
||
|
||
### config.json
|
||
|
||
```json
|
||
{
|
||
"app_name": "WXAuto Center",
|
||
"host": "0.0.0.0",
|
||
"port": 8080,
|
||
"debug": false,
|
||
"secret_key": "your-production-secret-key",
|
||
"api_prefix": "/api/v1",
|
||
"external_api_key": "your-external-api-key",
|
||
"cors_origins": ["http://localhost:3000"],
|
||
"workers": 1,
|
||
"monitor": {
|
||
"enabled": true,
|
||
"check_interval": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
### .env
|
||
|
||
```bash
|
||
# 数据库配置
|
||
DATABASE_URL=postgresql://wxauto:wxauto_password@postgres:5432/wxauto
|
||
|
||
# Redis 配置
|
||
REDIS_URL=redis://redis:6379/0
|
||
|
||
# 应用配置
|
||
APP_NAME=WXAuto Center
|
||
HOST=0.0.0.0
|
||
PORT=8080
|
||
DEBUG=false
|
||
SECRET_KEY=your-production-secret-key
|
||
WORKERS=1
|
||
|
||
# API 配置
|
||
API_PREFIX=/api/v1
|
||
EXTERNAL_API_KEY=your-external-api-key
|
||
CORS_ORIGINS=["http://localhost:3000"]
|
||
|
||
# 监控配置
|
||
MONITOR_ENABLED=true
|
||
MONITOR_CHECK_INTERVAL=30
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量配置优先级
|
||
|
||
某些敏感配置项可以通过环境变量覆盖配置文件：
|
||
|
||
| 环境变量 | 对应配置项 |
|
||
|----------|------------|
|
||
| APP_NAME | app_name |
|
||
| HOST | host |
|
||
| PORT | port |
|
||
| DEBUG | debug |
|
||
| SECRET_KEY | secret_key |
|
||
| API_PREFIX | api_prefix |
|
||
| EXTERNAL_API_KEY | external_api_key |
|
||
| CORS_ORIGINS | cors_origins |
|
||
| WORKERS | workers |
|
||
| DATABASE_URL | database.url |
|
||
| REDIS_URL | redis.url |
|
||
| MONITOR_ENABLED | monitor.enabled |
|
||
| MONITOR_CHECK_INTERVAL | monitor.check_interval |
|
||
|
||
---
|
||
|
||
## 配置加载与保存流程
|
||
|
||
```
|
||
启动时 (startup_event)
|
||
│
|
||
├──► load_config_from_file("config.json")
|
||
│ │
|
||
│ ▼
|
||
│ 解析 JSON 配置
|
||
│ │
|
||
│ ▼
|
||
│ 设置 Settings 各属性
|
||
│ │
|
||
│ ▼
|
||
│ 初始化数据库连接
|
||
│ │
|
||
│ ▼
|
||
│ 从数据库加载节点配置 (nodes 表)
|
||
│ │
|
||
│ ▼
|
||
│ NodeManager.add_node() 注册节点
|
||
│
|
||
└──► register_builtin_plugins()
|
||
|
||
关闭时 (shutdown_event)
|
||
│
|
||
├──► monitor_service.stop()
|
||
│
|
||
└──► 保存配置到文件 (如需要)
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库表结构
|
||
|
||
### nodes 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| node_id | VARCHAR(50) | 节点唯一标识符 |
|
||
| name | VARCHAR(100) | 节点显示名称 |
|
||
| api_url | VARCHAR(255) | 节点 API 地址 |
|
||
| api_key | VARCHAR(255) | 节点 API 密钥 |
|
||
| enabled | BOOLEAN | 是否启用 |
|
||
| description | TEXT | 节点描述 |
|
||
| group | VARCHAR(50) | 节点分组 |
|
||
| status | VARCHAR(20) | API 状态 |
|
||
| wechat_status | VARCHAR(20) | 微信状态 |
|
||
| is_healthy | BOOLEAN | 健康状态 |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
| updated_at | TIMESTAMP | 更新时间 |
|
||
|
||
### webhook_urls 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | SERIAL | Webhook ID |
|
||
| name | VARCHAR(100) | Webhook 名称 |
|
||
| url | VARCHAR(500) | Webhook URL 地址 |
|
||
| format | VARCHAR(20) | 消息格式 (bark/wechat) |
|
||
| enabled | BOOLEAN | 是否启用 |
|
||
| event_types | TEXT | 支持的事件类型 |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
| updated_at | TIMESTAMP | 更新时间 |
|
||
|
||
### logs 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | SERIAL | 日志 ID |
|
||
| timestamp | TIMESTAMP | 日志时间 |
|
||
| level | VARCHAR(20) | 日志级别 |
|
||
| source | VARCHAR(50) | 日志来源 |
|
||
| message | TEXT | 日志消息 |
|
||
|
||
详细表结构请参阅 [DATABASE.md](./DATABASE.md)。
|