# ///
# 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)。