butubb/wxauto_api

Fork 0

Files

T

butubb c412e4de5f 初始化提交

2026-04-07 14:11:45 +08:00

14 KiB

Raw Blame History

///

CONFIG.md

描述：配置文件说明

作者：AI Generated

创建日期：2026-04-06

最后更新：2026-04-06

///

WXAuto Center 配置文件说明

概述

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

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

配置文件结构

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 环境变量配置文件。

# ///
# .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	已废弃，不再支持

节点数据模型

{
    "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 管理节点配置：

# 添加节点
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"

节点分组

节点分组功能允许将节点按业务线或用途进行分类管理：

# 查询特定分组的节点
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 数据模型

{
    "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")

{
    "msgtype": "text",
    "text": {
        "content": "【WXAuto Center 告警】\n事件类型: 微信掉线\n节点: wx1\n状态: offline\n时间: 2026-04-05 10:00:00"
    }
}

Bark 格式 (format: "bark")

{
    "title": "WXAuto告警 - 微信掉线",
    "body": "wx1\n状态: offline\n时间: 2026-04-05 10:00:00"
}

API 管理 Webhook

# 添加 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)

监控服务负责定时检测节点和微信状态。

{
    "monitor": {
        "enabled": true,
        "check_interval": 30
    }
}

配置项说明

配置项	类型	必填	默认值	说明
enabled	bool	否	true	是否启用监控服务
check_interval	int	否	30	检测间隔（秒）

检测逻辑

API 检测：定期调用节点 /health 接口检查节点是否在线
微信检测：定期调用 /api/wechat/initialize 检测微信连接状态
状态变化：当检测到状态变化时，触发 Webhook 通知

数据库配置

数据库配置通过环境变量设置：

环境变量	说明	默认值
DATABASE_URL	PostgreSQL 连接 URL	postgresql://wxauto:wxauto_password@postgres:5432/wxauto

Docker 环境

DATABASE_URL=postgresql://wxauto:wxauto_password@postgres:5432/wxauto

本地环境

DATABASE_URL=postgresql://wxauto:wxauto_password@localhost:5432/wxauto

Redis 配置

Redis 用于消息队列和缓存支持。

环境变量	说明	默认值
REDIS_URL	Redis 连接 URL	redis://redis:6379/0

Docker 环境

REDIS_URL=redis://redis:6379/0

本地环境

REDIS_URL=redis://localhost:6379/0

Workers 配置

Workers 用于多进程部署，提高并发处理能力。

{
    "workers": 1
}

配置项说明

配置项	类型	必填	默认值	说明
workers	int	否	1	工作进程数，1 表示单进程模式

启动方式

模式	workers	说明
单进程	1	默认模式，不启用多进程
多进程	>1	启用多进程模式，需要 Redis 支持

注意：多进程模式需要 Redis 支持，队列服务依赖 Redis 进行进程间通信。

启动命令

# 单进程
python main.py

# 多进程
python main.py --workers 4

完整配置示例

config.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

# 数据库配置
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。

14 KiB Raw Blame History Unescape Escape

///

CONFIG.md

描述：配置文件说明

作者：AI Generated

创建日期：2026-04-06

最后更新：2026-04-06

///

WXAuto Center 配置文件说明

概述

配置文件结构

config.json

.env 环境变量文件

配置项详细说明

应用配置

app_name

host

port

debug

secret_key

API 配置

api_prefix

external_api_key

cors_origins

节点配置 (NodeConfig)

配置存储

节点数据模型

节点标识说明

配置项说明

API 管理节点

节点分组

Webhook 配置 (WebhookConfig)

配置存储

Webhook 数据模型

配置项说明

支持的事件类型

消息格式

企业微信格式 (format: "wechat")

Bark 格式 (format: "bark")

API 管理 Webhook

监控配置 (MonitorConfig)

配置项说明

检测逻辑

数据库配置

Docker 环境

本地环境

Redis 配置

Docker 环境

本地环境

Workers 配置

配置项说明

启动方式

启动命令

完整配置示例

config.json

.env

环境变量配置优先级

配置加载与保存流程

数据库表结构

nodes 表

webhook_urls 表

logs 表

14 KiB

Raw Blame History