|
@@ -0,0 +1,374 @@
|
|
|
|
|
+# Coordinate 节点配置云端管理系统与 HTTP API 设计文档
|
|
|
|
|
+
|
|
|
|
|
+本文档详细说明 Coordinate 系统的节点配置(`config_booker.json`、`config_sentinel.json`、`config_standalone.json`)收归云端数据库(MySQL 8.x)的集中管理方案、表结构设计、HTTP 管理与下发 API,以及与 Coordinate 节点端(`main.py`、`utils/cloud_config.py`)周期轮询与热重载机制的联动方案。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 1. 架构总览
|
|
|
|
|
+
|
|
|
|
|
+整个节点配置管理与同步系统的时序与拓扑流如下:
|
|
|
|
|
+
|
|
|
|
|
+```mermaid
|
|
|
|
|
+sequenceDiagram
|
|
|
|
|
+ autonumber
|
|
|
|
|
+ actor Admin as 管理员/Web前端
|
|
|
|
|
+ participant API as 云端配置管理服务 (API Server)
|
|
|
|
|
+ participant DB as MySQL 数据库 (node_configurations)
|
|
|
|
|
+ participant Node as Coordinate 节点 (main.py)
|
|
|
|
|
+
|
|
|
|
|
+ Note over Admin,DB: 【阶段一:配置初始化与可视化编辑】
|
|
|
|
|
+ Admin->>API: POST /api/node_configurations/save (保存 node01 的 sentinel 配置)
|
|
|
|
|
+ API->>API: 校验 JSON 语法合法性并计算 MD5 Hash
|
|
|
|
|
+ API->>DB: 写入/更新 node_configurations 表 & 记录审计日志
|
|
|
|
|
+ API-->>Admin: 返回保存成功
|
|
|
|
|
+
|
|
|
|
|
+ Note over Node,DB: 【阶段二:节点定期轮询与平滑热重载】
|
|
|
|
|
+ loop 每 30 秒轮询一次 (可配)
|
|
|
|
|
+ Node->>API: GET /api/node_configurations/detail?node_id=node01&role=sentinel
|
|
|
|
|
+ API->>DB: 查询 (role='sentinel', node_id='node01') 的配置与 Hash
|
|
|
|
|
+ API-->>Node: 返回配置内容与 config_hash
|
|
|
|
|
+ alt config_hash 发生变更
|
|
|
|
|
+ Node->>Node: 写入本地磁盘缓存 config/config_sentinel.json
|
|
|
|
|
+ Node->>Node: 执行 sync_groups() 差异化启动/停止/更新 GCO 实例
|
|
|
|
|
+ Node->>Node: 热重载完成,更新当前 current_hash
|
|
|
|
|
+ else config_hash 一致
|
|
|
|
|
+ Node->>Node: 无需变动,跳过
|
|
|
|
|
+ end
|
|
|
|
|
+ end
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 2. 数据库表结构设计 (MySQL 8.x / MariaDB)
|
|
|
|
|
+
|
|
|
|
|
+采用**轻量单表 + 审计日志**结构:
|
|
|
|
|
+- `node_configurations`:存储各角色与各节点的配置主体(完整 JSON 格式)及自动计算的 MD5 哈希;
|
|
|
|
|
+- `node_config_audit_logs`:记录配置的修改历史、变更人与变更前后 Hash。
|
|
|
|
|
+
|
|
|
|
|
+```sql
|
|
|
|
|
+-- ----------------------------
|
|
|
|
|
+-- 1. 节点配置主表
|
|
|
|
|
+-- ----------------------------
|
|
|
|
|
+CREATE TABLE IF NOT EXISTS `node_configurations` (
|
|
|
|
|
+ `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '自增主键',
|
|
|
|
|
+ `role` VARCHAR(32) NOT NULL COMMENT '角色类型: sentinel / booker / standalone',
|
|
|
|
|
+ `node_id` VARCHAR(64) NOT NULL COMMENT '节点唯一标识,如: node01, node02 等',
|
|
|
|
|
+ `config_content` JSON NOT NULL COMMENT '完整配置内容 (JSON 数组或 JSON 对象)',
|
|
|
|
|
+ `config_hash` CHAR(32) GENERATED ALWAYS AS (MD5(CAST(`config_content` AS CHAR))) STORED COMMENT '配置内容 MD5 哈希,用于节点秒级比对',
|
|
|
|
|
+ `is_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用: 1-启用, 0-禁用',
|
|
|
|
|
+ `description` VARCHAR(255) DEFAULT '' COMMENT '配置用途/备注说明',
|
|
|
|
|
+ `created_by` VARCHAR(64) DEFAULT 'system' COMMENT '创建人',
|
|
|
|
|
+ `updated_by` VARCHAR(64) DEFAULT 'system' COMMENT '最后更新人',
|
|
|
|
|
+ `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
|
|
|
|
+ `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
|
|
|
|
+ PRIMARY KEY (`id`),
|
|
|
|
|
+ UNIQUE KEY `uk_role_node` (`role`, `node_id`),
|
|
|
|
|
+ KEY `idx_updated_at` (`updated_at`)
|
|
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='节点角色配置主表';
|
|
|
|
|
+
|
|
|
|
|
+-- ----------------------------
|
|
|
|
|
+-- 2. 配置修改审计日志表
|
|
|
|
|
+-- ----------------------------
|
|
|
|
|
+CREATE TABLE IF NOT EXISTS `node_config_audit_logs` (
|
|
|
|
|
+ `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '自增主键',
|
|
|
|
|
+ `role` VARCHAR(32) NOT NULL COMMENT '角色类型',
|
|
|
|
|
+ `node_id` VARCHAR(64) NOT NULL COMMENT '节点标识',
|
|
|
|
|
+ `action` VARCHAR(32) NOT NULL COMMENT '操作类型: CREATE / UPDATE / TOGGLE / DELETE',
|
|
|
|
|
+ `before_hash` CHAR(32) DEFAULT NULL COMMENT '修改前配置 Hash',
|
|
|
|
|
+ `after_hash` CHAR(32) DEFAULT NULL COMMENT '修改后配置 Hash',
|
|
|
|
|
+ `operator` VARCHAR(64) NOT NULL DEFAULT 'system' COMMENT '操作人',
|
|
|
|
|
+ `remark` VARCHAR(500) DEFAULT '' COMMENT '修改原因或备注说明',
|
|
|
|
|
+ `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '操作时间',
|
|
|
|
|
+ PRIMARY KEY (`id`),
|
|
|
|
|
+ KEY `idx_role_node_time` (`role`, `node_id`, `created_at`)
|
|
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='配置修改审计日志表';
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 3. HTTP RESTful API 设计
|
|
|
|
|
+
|
|
|
|
|
+### 3.1 统一规范
|
|
|
|
|
+
|
|
|
|
|
+- **鉴权方式**: `Authorization: Bearer <token>`
|
|
|
|
|
+- **Content-Type**: `application/json`
|
|
|
|
|
+- **统一响应报文**:
|
|
|
|
|
+ ```json
|
|
|
|
|
+ {
|
|
|
|
|
+ "code": 0, // 0 表示成功,非 0 为具体错误码
|
|
|
|
|
+ "message": "success",
|
|
|
|
|
+ "data": {}
|
|
|
|
|
+ }
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 3.2 接口详细定义
|
|
|
|
|
+
|
|
|
|
|
+#### 1. 节点拉取配置详情(Worker 轮询专用核心接口)
|
|
|
|
|
+
|
|
|
|
|
+- **接口地址**: `GET /api/node_configurations/detail`
|
|
|
|
|
+- **Query 参数**:
|
|
|
|
|
+ | 参数名 | 类型 | 必填 | 说明 |
|
|
|
|
|
+ | :--- | :--- | :--- | :--- |
|
|
|
|
|
+ | `node_id` | string | 是 | 节点标识,如 `node01` |
|
|
|
|
|
+ | `role` | string | 是 | 角色类型,可选值: `sentinel` / `booker` / `standalone` |
|
|
|
|
|
+
|
|
|
|
|
+- **请求示例**:
|
|
|
|
|
+ ```http
|
|
|
|
|
+ GET /api/node_configurations/detail?node_id=node01&role=sentinel HTTP/1.1
|
|
|
|
|
+ Host: api.text.skin
|
|
|
|
|
+ Authorization: Bearer tok_e946329a60ff45ba807f3f41b0e8b7fc
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+- **响应示例**:
|
|
|
|
|
+ ```json
|
|
|
|
|
+ {
|
|
|
|
|
+ "code": 0,
|
|
|
|
|
+ "message": "success",
|
|
|
|
|
+ "data": {
|
|
|
|
|
+ "id": 1,
|
|
|
|
|
+ "role": "sentinel",
|
|
|
|
|
+ "node_id": "node01",
|
|
|
|
|
+ "is_enabled": 1,
|
|
|
|
|
+ "config_hash": "e2fc714c4727ee9395f324cd2e7f331f",
|
|
|
|
|
+ "config_content": [
|
|
|
|
|
+ {
|
|
|
|
|
+ "identifier": "vfs.ie.nl",
|
|
|
|
|
+ "debug": false,
|
|
|
|
|
+ "enable": true,
|
|
|
|
|
+ "need_account": true,
|
|
|
|
|
+ "need_proxy": true,
|
|
|
|
|
+ "proxy_pool": ["proxy-cheap"],
|
|
|
|
|
+ "proxy_cd": 300,
|
|
|
|
|
+ "session_max_life": 1800,
|
|
|
|
|
+ "active_time_start": "00:00",
|
|
|
|
|
+ "active_time_end": "23:59",
|
|
|
|
|
+ "sentinel": {
|
|
|
|
|
+ "account_source": "built-in",
|
|
|
|
|
+ "account_pool_id": "ie.nl.sentinel",
|
|
|
|
|
+ "target_instances": 1,
|
|
|
|
|
+ "account_cd": 10800,
|
|
|
|
|
+ "signal_ttl": 30,
|
|
|
|
|
+ "query_wait": {
|
|
|
|
|
+ "mode": "Random",
|
|
|
|
|
+ "fixed_wait": 10,
|
|
|
|
|
+ "random_min": 60,
|
|
|
|
|
+ "random_max": 300
|
|
|
|
|
+ }
|
|
|
|
|
+ },
|
|
|
|
|
+ "plugin_config": {
|
|
|
|
|
+ "lib_path": "plugins",
|
|
|
|
|
+ "plugin_name": "vfs_plugin",
|
|
|
|
|
+ "plugin_bin": "vfs_plugin.py",
|
|
|
|
|
+ "plugin_proto": "IVSPlg"
|
|
|
|
|
+ },
|
|
|
|
|
+ "appointment_types": [
|
|
|
|
|
+ {
|
|
|
|
|
+ "weight": 10,
|
|
|
|
|
+ "routing_key": "slot.dub.nl.tourist",
|
|
|
|
|
+ "city": "Dublin",
|
|
|
|
|
+ "visa_type": "Tourist",
|
|
|
|
|
+ "country": "Netherlands"
|
|
|
|
|
+ }
|
|
|
|
|
+ ],
|
|
|
|
|
+ "website": "https://visa.vfsglobal.com/irl/en/nld/login",
|
|
|
|
|
+ "free_config": {
|
|
|
|
|
+ "mission_code": "nld",
|
|
|
|
|
+ "mission_name": "Netherlands",
|
|
|
|
|
+ "country_code": "irl",
|
|
|
|
|
+ "country_name": "Ireland",
|
|
|
|
|
+ "culture_code": "en-US",
|
|
|
|
|
+ "language": "en",
|
|
|
|
|
+ "apt_configs": {
|
|
|
|
|
+ "slot.dub.nl.tourist": {
|
|
|
|
|
+ "center_name": "Netherlands Visa Application Center - Dublin",
|
|
|
|
|
+ "address": "Cunningham House, 130 Francis Street, Dublin 8 D08 H48R",
|
|
|
|
|
+ "vac_code": "NTDB",
|
|
|
|
|
+ "category_name": "All Short stay Categories",
|
|
|
|
|
+ "category_code": "TA",
|
|
|
|
|
+ "subcategory_name": "Tourist",
|
|
|
|
|
+ "subcategory_code": "To"
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ ],
|
|
|
|
|
+ "updated_at": "2026-08-23 00:30:00"
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+#### 2. 管理后台查询节点配置列表
|
|
|
|
|
+
|
|
|
|
|
+- **接口地址**: `GET /api/node_configurations/list`
|
|
|
|
|
+- **Query 参数**:
|
|
|
|
|
+ | 参数名 | 类型 | 必填 | 说明 |
|
|
|
|
|
+ | :--- | :--- | :--- | :--- |
|
|
|
|
|
+ | `role` | string | 否 | 过滤角色: `sentinel` / `booker` / `standalone` |
|
|
|
|
|
+ | `node_id` | string | 否 | 过滤节点标识 (支持模糊搜索) |
|
|
|
|
|
+ | `page` | int | 否 | 页码 (默认 1) |
|
|
|
|
|
+ | `page_size`| int | 否 | 每页条数 (默认 20) |
|
|
|
|
|
+
|
|
|
|
|
+- **响应示例**:
|
|
|
|
|
+ ```json
|
|
|
|
|
+ {
|
|
|
|
|
+ "code": 0,
|
|
|
|
|
+ "message": "success",
|
|
|
|
|
+ "data": {
|
|
|
|
|
+ "total": 3,
|
|
|
|
|
+ "items": [
|
|
|
|
|
+ {
|
|
|
|
|
+ "id": 1,
|
|
|
|
|
+ "role": "sentinel",
|
|
|
|
|
+ "node_id": "node01",
|
|
|
|
|
+ "is_enabled": 1,
|
|
|
|
|
+ "config_hash": "e2fc714c4727ee9395f324cd2e7f331f",
|
|
|
|
|
+ "description": "节点01 哨兵轮询配置",
|
|
|
|
|
+ "updated_by": "admin",
|
|
|
|
|
+ "updated_at": "2026-08-23 00:30:00"
|
|
|
|
|
+ }
|
|
|
|
|
+ ]
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+#### 3. 管理后台新增/更新节点配置 (Save / Upsert)
|
|
|
|
|
+
|
|
|
|
|
+- **接口地址**: `POST /api/node_configurations/save`
|
|
|
|
|
+- **请求体 (Body)**:
|
|
|
|
|
+ ```json
|
|
|
|
|
+ {
|
|
|
|
|
+ "role": "sentinel",
|
|
|
|
|
+ "node_id": "node01",
|
|
|
|
|
+ "is_enabled": 1,
|
|
|
|
|
+ "config_content": [ ... ],
|
|
|
|
|
+ "description": "节点01 哨兵监控配置",
|
|
|
|
|
+ "operator": "admin",
|
|
|
|
|
+ "remark": "开启英国意大利预约通道"
|
|
|
|
|
+ }
|
|
|
|
|
+ ```
|
|
|
|
|
+- **响应示例**:
|
|
|
|
|
+ ```json
|
|
|
|
|
+ {
|
|
|
|
|
+ "code": 0,
|
|
|
|
|
+ "message": "Configuration saved successfully",
|
|
|
|
|
+ "data": {
|
|
|
|
|
+ "id": 1,
|
|
|
|
|
+ "role": "sentinel",
|
|
|
|
|
+ "node_id": "node01",
|
|
|
|
|
+ "config_hash": "e2fc714c4727ee9395f324cd2e7f331f"
|
|
|
|
|
+ }
|
|
|
|
|
+ }
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 4. Coordinate 客户端集成改动
|
|
|
|
|
+
|
|
|
|
|
+### 4.1 `toolkit/vs_cloud_api.py` 新增方法
|
|
|
|
|
+
|
|
|
|
|
+```python
|
|
|
|
|
+def get_node_configuration(self, role: str, node_id: str) -> Optional[Dict[str, Any]]:
|
|
|
|
|
+ """
|
|
|
|
|
+ 从云端获取指定节点与角色的配置详情
|
|
|
|
|
+ GET /api/node_configurations/detail?node_id={node_id}&role={role}
|
|
|
|
|
+ """
|
|
|
|
|
+ url = f"{self.base_url}/api/node_configurations/detail"
|
|
|
|
|
+ params = {
|
|
|
|
|
+ "node_id": node_id,
|
|
|
|
|
+ "role": role
|
|
|
|
|
+ }
|
|
|
|
|
+ headers = self._get_headers()
|
|
|
|
|
+ resp = self._perform_request('GET', url, params=params, headers=headers, timeout=10)
|
|
|
|
|
+ result = resp.json()
|
|
|
|
|
+ if result.get("code") == 0:
|
|
|
|
|
+ return result.get("data") or {}
|
|
|
|
|
+ else:
|
|
|
|
|
+ raise BizLogicError(message=f"Get node configuration error: {result.get('message')}")
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 4.2 `utils/cloud_config.py` 改造
|
|
|
|
|
+
|
|
|
|
|
+```python
|
|
|
|
|
+def fetch_cloud_config(role: str, node_id: str) -> Any:
|
|
|
|
|
+ """
|
|
|
|
|
+ 拉取云端节点配置并返回 config_content
|
|
|
|
|
+ """
|
|
|
|
|
+ try:
|
|
|
|
|
+ data = VSCloudApi.Instance().get_node_configuration(role=role, node_id=node_id)
|
|
|
|
|
+ if data and "config_content" in data:
|
|
|
|
|
+ return data["config_content"]
|
|
|
|
|
+ except Exception as e:
|
|
|
|
|
+ pass
|
|
|
|
|
+ return None
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 5. 数据初始化迁移脚本
|
|
|
|
|
+
|
|
|
|
|
+在实施迁移时,运行以下脚本将本地文件灌入数据库:
|
|
|
|
|
+
|
|
|
|
|
+```python
|
|
|
|
|
+import os
|
|
|
|
|
+import json
|
|
|
|
|
+import hashlib
|
|
|
|
|
+import pymysql
|
|
|
|
|
+
|
|
|
|
|
+DB_CONFIG = {
|
|
|
|
|
+ "host": "localhost",
|
|
|
|
|
+ "user": "root",
|
|
|
|
|
+ "password": "your_password",
|
|
|
|
|
+ "database": "coordinate_db",
|
|
|
|
|
+ "charset": "utf8mb4"
|
|
|
|
|
+}
|
|
|
|
|
+
|
|
|
|
|
+CONFIG_FILES = {
|
|
|
|
|
+ "booker": "config/config_booker.json",
|
|
|
|
|
+ "sentinel": "config/config_sentinel.json",
|
|
|
|
|
+ "standalone": "config/config_standalone.json"
|
|
|
|
|
+}
|
|
|
|
|
+
|
|
|
|
|
+TARGET_NODES = ["node01"] # 初始化的目标节点 ID
|
|
|
|
|
+
|
|
|
|
|
+def migrate():
|
|
|
|
|
+ conn = pymysql.connect(**DB_CONFIG)
|
|
|
|
|
+ cursor = conn.cursor()
|
|
|
|
|
+
|
|
|
|
|
+ for role, file_path in CONFIG_FILES.items():
|
|
|
|
|
+ if not os.path.exists(file_path):
|
|
|
|
|
+ print(f"[SKIP] File not found: {file_path}")
|
|
|
|
|
+ continue
|
|
|
|
|
+
|
|
|
|
|
+ with open(file_path, "r", encoding="utf-8") as f:
|
|
|
|
|
+ content = json.load(f)
|
|
|
|
|
+
|
|
|
|
|
+ content_json_str = json.dumps(content, ensure_ascii=False)
|
|
|
|
|
+
|
|
|
|
|
+ for node_id in TARGET_NODES:
|
|
|
|
|
+ sql = """
|
|
|
|
|
+ INSERT INTO node_configurations
|
|
|
|
|
+ (role, node_id, config_content, description, created_by, updated_by)
|
|
|
|
|
+ VALUES
|
|
|
|
|
+ (%s, %s, %s, %s, 'migration_script', 'migration_script')
|
|
|
|
|
+ ON DUPLICATE KEY UPDATE
|
|
|
|
|
+ config_content = VALUES(config_content),
|
|
|
|
|
+ updated_by = 'migration_script',
|
|
|
|
|
+ updated_at = NOW();
|
|
|
|
|
+ """
|
|
|
|
|
+ cursor.execute(sql, (role, node_id, content_json_str, f"Migrated from {file_path}"))
|
|
|
|
|
+ print(f"[OK] Migrated {role} for node '{node_id}'")
|
|
|
|
|
+
|
|
|
|
|
+ conn.commit()
|
|
|
|
|
+ cursor.close()
|
|
|
|
|
+ conn.close()
|
|
|
|
|
+ print("All configurations migrated successfully.")
|
|
|
|
|
+
|
|
|
|
|
+if __name__ == "__main__":
|
|
|
|
|
+ migrate()
|
|
|
|
|
+```
|