283 lines
8.0 KiB
Markdown
283 lines
8.0 KiB
Markdown
# ///
|
||
# DATABASE.md
|
||
# 描述：WXAuto Center 数据库设计文档
|
||
# 作者：AI Generated
|
||
# 创建日期：2026-04-05
|
||
# 更新日期：2026-04-06
|
||
# ///
|
||
|
||
# WXAuto Center 数据库设计文档
|
||
|
||
## 概述
|
||
|
||
本系统使用 PostgreSQL 数据库，通过 SQLAlchemy ORM 进行数据访问。数据库包含以下表：
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `nodes` | 节点配置表 |
|
||
| `webhook_urls` | Webhook URL 表 |
|
||
| `logs` | 日志表 |
|
||
| `plugin_configs` | 插件配置表 |
|
||
|
||
## ER 图
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ nodes │ │ webhook_urls │
|
||
├─────────────────┤ ├─────────────────┤
|
||
│ node_id (PK) │ │ id (PK) │
|
||
│ name │ │ name │
|
||
│ api_url │ │ url │
|
||
│ api_key │ │ format │
|
||
│ enabled │ │ enabled │
|
||
│ description │ │ event_types │
|
||
│ group │ │ created_at │
|
||
│ status │ │ updated_at │
|
||
│ wechat_status │ └─────────────────┘
|
||
│ is_healthy │
|
||
│ health_message │
|
||
│ created_at │
|
||
│ updated_at │
|
||
└─────────────────┘
|
||
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ logs │ │ plugin_configs │
|
||
├─────────────────┤ ├─────────────────┤
|
||
│ id (PK) │ │ id (PK) │
|
||
│ timestamp │ │ plugin_name │
|
||
│ level │ │ config_json │
|
||
│ source │ │ enabled │
|
||
│ message │ │ created_at │
|
||
└─────────────────┘ │ updated_at │
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 表结构详解
|
||
|
||
### 1. nodes - 节点配置表
|
||
|
||
存储所有微信节点的信息。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| `node_id` | VARCHAR(50) | **PK** | 节点唯一标识 |
|
||
| `name` | VARCHAR(100) | NOT NULL | 节点显示名称 |
|
||
| `api_url` | VARCHAR(255) | NOT NULL | 节点 API 地址 |
|
||
| `api_key` | VARCHAR(255) | NOT NULL | 节点 API 密钥 |
|
||
| `enabled` | BOOLEAN | DEFAULT true | 是否启用 |
|
||
| `description` | TEXT | DEFAULT '' | 节点描述 |
|
||
| `group` | VARCHAR(50) | DEFAULT 'default' | 节点分组 |
|
||
| `status` | VARCHAR(20) | DEFAULT 'inactive' | API 状态 |
|
||
| `wechat_status` | VARCHAR(20) | DEFAULT 'online' | 微信状态 |
|
||
| `is_healthy` | BOOLEAN | DEFAULT false | 健康检查状态 |
|
||
| `health_message` | VARCHAR(255) | DEFAULT '' | 健康检查消息 |
|
||
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |
|
||
|
||
**状态值说明：**
|
||
|
||
| status 值 | 说明 |
|
||
|------------|------|
|
||
| `active` | API 正常响应 |
|
||
| `inactive` | API 未响应 |
|
||
| `error` | API 返回错误 |
|
||
|
||
| wechat_status 值 | 说明 |
|
||
|------------------|------|
|
||
| `online` | 微信已登录 |
|
||
| `offline` | 微信未登录 |
|
||
|
||
**SQL：**
|
||
```sql
|
||
CREATE TABLE nodes (
|
||
node_id VARCHAR(50) PRIMARY KEY,
|
||
name VARCHAR(100) NOT NULL,
|
||
api_url VARCHAR(255) NOT NULL,
|
||
api_key VARCHAR(255) NOT NULL,
|
||
enabled BOOLEAN DEFAULT true,
|
||
description TEXT DEFAULT '',
|
||
group VARCHAR(50) DEFAULT 'default',
|
||
status VARCHAR(20) DEFAULT 'inactive',
|
||
wechat_status VARCHAR(20) DEFAULT 'online',
|
||
is_healthy BOOLEAN DEFAULT false,
|
||
health_message VARCHAR(255) DEFAULT '',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 2. webhook_urls - Webhook URL 表
|
||
|
||
存储告警 webhook 配置。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | INTEGER | **PK**, AUTO | 主键 |
|
||
| `name` | VARCHAR(100) | NOT NULL | Webhook 名称 |
|
||
| `url` | VARCHAR(500) | NOT NULL | Webhook URL |
|
||
| `format` | VARCHAR(20) | DEFAULT 'bark' | 消息格式 |
|
||
| `enabled` | BOOLEAN | DEFAULT true | 是否启用 |
|
||
| `event_types` | TEXT | DEFAULT '' | 触发事件类型（逗号分隔） |
|
||
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |
|
||
|
||
**format 支持的格式：**
|
||
- `bark` - Bark 推送格式
|
||
- `wecom` - 企业微信
|
||
- `dingtalk` - 钉钉
|
||
- `feishu` - 飞书
|
||
- `telegram` - Telegram
|
||
- `serverchan` - Server酱
|
||
|
||
**event_types 支持的类型：**
|
||
- `node_offline` - 节点离线
|
||
- `node_error` - 节点错误
|
||
- `wechat_offline` - 微信离线
|
||
- `all` - 所有事件
|
||
|
||
---
|
||
|
||
### 3. logs - 日志表
|
||
|
||
存储系统运行日志。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | INTEGER | **PK**, AUTO | 主键 |
|
||
| `timestamp` | TIMESTAMP | DEFAULT now | 日志时间 |
|
||
| `level` | VARCHAR(20) | NOT NULL | 日志级别 |
|
||
| `source` | VARCHAR(50) | NOT NULL | 日志来源 |
|
||
| `message` | TEXT | NOT NULL | 日志消息 |
|
||
|
||
**level 值：**
|
||
- `INFO` - 信息
|
||
- `WARNING` - 警告
|
||
- `ERROR` - 错误
|
||
- `SUCCESS` - 成功
|
||
- `DEBUG` - 调试
|
||
|
||
---
|
||
|
||
### 4. plugin_configs - 插件配置表
|
||
|
||
存储插件的配置和启用状态。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | INTEGER | **PK**, AUTO | 主键 |
|
||
| `plugin_name` | VARCHAR(100) | **UNIQUE**, NOT NULL | 插件名称 |
|
||
| `config_json` | TEXT | DEFAULT '{}' | 插件配置（JSON格式） |
|
||
| `enabled` | BOOLEAN | DEFAULT false | 是否启用 |
|
||
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |
|
||
|
||
**config_json 示例：**
|
||
```json
|
||
{
|
||
"node_id": "wx1",
|
||
"receiver": "文件传输助手",
|
||
"cron": "0 8 * * *",
|
||
"http_url": "https://api.example.com/news",
|
||
"message_template": "📰 {title}\n{url}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库操作
|
||
|
||
### DatabaseService 主要方法
|
||
|
||
#### 节点操作
|
||
```python
|
||
# 获取所有节点
|
||
db_service.get_all_nodes() -> List[Node]
|
||
|
||
# 获取指定节点
|
||
db_service.get_node(node_id: str) -> Optional[Node]
|
||
|
||
# 添加节点
|
||
db_service.add_node(node_id, name, api_url, api_key, description, group)
|
||
|
||
# 更新节点
|
||
db_service.update_node(node_id, **kwargs) -> bool
|
||
|
||
# 删除节点
|
||
db_service.delete_node(node_id) -> bool
|
||
|
||
# 获取启用的节点
|
||
db_service.get_enabled_nodes() -> List[Node]
|
||
```
|
||
|
||
#### Webhook 操作
|
||
```python
|
||
# 获取所有 Webhook
|
||
db_service.get_all_webhooks() -> List[WebhookUrl]
|
||
|
||
# 获取启用的 Webhook
|
||
db_service.get_enabled_webhooks() -> List[WebhookUrl]
|
||
|
||
# 添加 Webhook
|
||
db_service.add_webhook(name, url, format, event_types) -> bool
|
||
|
||
# 更新 Webhook
|
||
db_service.update_webhook(webhook_id, **kwargs) -> bool
|
||
|
||
# 删除 Webhook
|
||
db_service.delete_webhook(webhook_id) -> bool
|
||
```
|
||
|
||
#### 插件配置操作
|
||
```python
|
||
# 获取插件配置
|
||
db_service.get_plugin_config(plugin_name: str) -> Optional[PluginConfig]
|
||
|
||
# 获取所有插件配置
|
||
db_service.get_all_plugin_configs() -> List[PluginConfig]
|
||
|
||
# 保存插件配置
|
||
db_service.save_plugin_config(plugin_name, config, enabled) -> bool
|
||
|
||
# 更新插件启用状态
|
||
db_service.update_plugin_enabled(plugin_name, enabled) -> bool
|
||
```
|
||
|
||
---
|
||
|
||
## 索引
|
||
|
||
```sql
|
||
-- nodes 表索引
|
||
CREATE INDEX idx_nodes_enabled ON nodes(enabled);
|
||
CREATE INDEX idx_nodes_group ON nodes(group);
|
||
CREATE INDEX idx_nodes_status ON nodes(status);
|
||
|
||
-- webhook_urls 表索引
|
||
CREATE INDEX idx_webhook_enabled ON webhook_urls(enabled);
|
||
|
||
-- logs 表索引
|
||
CREATE INDEX idx_logs_timestamp ON logs(timestamp);
|
||
CREATE INDEX idx_logs_level ON logs(level);
|
||
```
|
||
|
||
---
|
||
|
||
## 迁移注意
|
||
|
||
如果数据库已存在，新增 `plugin_configs` 表：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS plugin_configs (
|
||
id SERIAL PRIMARY KEY,
|
||
plugin_name VARCHAR(100) UNIQUE NOT NULL,
|
||
config_json TEXT DEFAULT '{}',
|
||
enabled BOOLEAN DEFAULT false,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|