Forráskód Böngészése

feat: adapt cloud config polling and loading to new role-based endpoints

jerry 2 hónapja
szülő
commit
8156aba53d

+ 277 - 0
docs/config_entries_database_schema.md

@@ -0,0 +1,277 @@
+# Coordinate 节点任务配置数据库 Schema 设计文档
+
+本文档定义了 Coordinate 系统中三大角色(`booker`、`sentinel`、`standalone`)的 JSON 任务配置持久化到 MySQL (8.x+) 数据库的表结构(DDL)、字段映射规范、设计原则与示例数据。
+
+---
+
+## 1. 设计规范与原则
+
+1. **顶级字段直接列化**:
+   - 基础标量类型(`string`、`bool`、`int`)映射为对应的 SQL 数据类型(`VARCHAR`、`TINYINT(1)`、`INT UNSIGNED` 等)。
+   - 嵌套对象类型(`object`、`array`,如 `plugin_config`、`appointment_types`、`free_config` 等)统一存储为 MySQL 原生 `JSON` 列。
+2. **多节点分发支持**:
+   - 包含 `node_id` 列(如 `node01`, `node02`),用于支持不同节点独立拉取和维护各自的任务组配置。
+   - 联合唯一约束采用 `UNIQUE KEY (node_id, identifier)`,既保证单节点内标识唯一,又支持跨节点部署同名任务。
+3. **运维与并发审计字段**:
+   - 统一提供 `version`(乐观锁版本号)、`updated_by`(变更操作人)、`created_at`、`updated_at`。
+4. **JSON 字段默认值**:
+   - 针对 MySQL 8.0+ 使用表达式默认值 `DEFAULT (json_object())` 或 `DEFAULT (json_array())`,防止非空写入报错。
+
+---
+
+## 2. 数据库 DDL 定义
+
+```sql
+-- =============================================================================
+-- 1. Booker 角色任务配置表 (booker_entries)
+-- =============================================================================
+DROP TABLE IF EXISTS `booker_entries`;
+CREATE TABLE `booker_entries` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+  `node_id` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '绑定的节点唯一标识(如 node01)',
+  `identifier` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '任务组标识(如 vfs.ie.nl)',
+  `enable` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否启用: 1-启用, 0-禁用',
+  `debug` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否开启调试日志: 1-开启, 0-关闭',
+  `need_account` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否需要账号池支持: 1-需要, 0-不需要',
+  `need_proxy` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否需要代理池支持: 1-需要, 0-不需要',
+  `proxy_pool` JSON NOT NULL DEFAULT (json_array()) COMMENT '指定代理池名称列表(JSON 字符串数组)',
+  `proxy_cd` INT UNSIGNED NOT NULL DEFAULT 300 COMMENT '代理冷却时间(秒)',
+  `session_max_life` INT UNSIGNED NOT NULL DEFAULT 1800 COMMENT '会话最大存活时间(秒)',
+  `active_time_start` VARCHAR(5) NOT NULL DEFAULT '00:00' COMMENT '任务每日生效起始时间(HH:MM)',
+  `active_time_end` VARCHAR(5) NOT NULL DEFAULT '23:59' COMMENT '任务每日生效结束时间(HH:MM)',
+  `website` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '目标签证网站/登录页面 URL',
+  `booker` JSON NOT NULL DEFAULT (json_object()) COMMENT 'Booker 专属配置对象(account_source, pool_id, target_instances 等)',
+  `plugin_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '插件加载配置对象(lib_path, plugin_name, plugin_bin 等)',
+  `appointment_types` JSON NOT NULL DEFAULT (json_array()) COMMENT '预约类型与路由权重配置列表',
+  `free_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '目标使馆/国家专属业务扩展配置',
+  `version` INT UNSIGNED NOT NULL DEFAULT 0 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_booker_node_identifier` (`node_id`, `identifier`),
+  KEY `idx_booker_identifier` (`identifier`),
+  KEY `idx_booker_updated_at` (`updated_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Booker 角色任务配置表';
+
+-- =============================================================================
+-- 2. Sentinel 角色任务配置表 (sentinel_entries)
+-- =============================================================================
+DROP TABLE IF EXISTS `sentinel_entries`;
+CREATE TABLE `sentinel_entries` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+  `node_id` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '绑定的节点唯一标识(如 node01)',
+  `identifier` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '任务组标识(如 vfs.ie.nl)',
+  `enable` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否启用: 1-启用, 0-禁用',
+  `debug` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否开启调试日志: 1-开启, 0-关闭',
+  `need_account` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否需要账号池支持: 1-需要, 0-不需要',
+  `need_proxy` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否需要代理池支持: 1-需要, 0-不需要',
+  `proxy_pool` JSON NOT NULL DEFAULT (json_array()) COMMENT '指定代理池名称列表(JSON 字符串数组)',
+  `proxy_cd` INT UNSIGNED NOT NULL DEFAULT 300 COMMENT '代理冷却时间(秒)',
+  `session_max_life` INT UNSIGNED NOT NULL DEFAULT 1800 COMMENT '会话最大存活时间(秒)',
+  `active_time_start` VARCHAR(5) NOT NULL DEFAULT '00:00' COMMENT '任务每日生效起始时间(HH:MM)',
+  `active_time_end` VARCHAR(5) NOT NULL DEFAULT '23:59' COMMENT '任务每日生效结束时间(HH:MM)',
+  `website` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '目标签证网站/登录页面 URL',
+  `sentinel` JSON NOT NULL DEFAULT (json_object()) COMMENT 'Sentinel 专属配置对象(account_source, signal_ttl, query_wait 等)',
+  `plugin_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '插件加载配置对象(lib_path, plugin_name, plugin_bin 等)',
+  `appointment_types` JSON NOT NULL DEFAULT (json_array()) COMMENT '预约类型与路由权重配置列表',
+  `free_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '目标使馆/国家专属业务扩展配置',
+  `version` INT UNSIGNED NOT NULL DEFAULT 0 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_sentinel_node_identifier` (`node_id`, `identifier`),
+  KEY `idx_sentinel_identifier` (`identifier`),
+  KEY `idx_sentinel_updated_at` (`updated_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Sentinel 角色任务配置表';
+
+-- =============================================================================
+-- 3. Standalone 独立任务配置表 (standalone_entries)
+-- =============================================================================
+DROP TABLE IF EXISTS `standalone_entries`;
+CREATE TABLE `standalone_entries` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+  `node_id` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '绑定的节点唯一标识(如 node01)',
+  `order_id` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL COMMENT '绑定的外部订单 ID(可选)',
+  `identifier` VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '任务唯一标识(如 tls, vfs, usa)',
+  `enable` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用: 1-启用, 0-禁用',
+  `debug` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否开启调试日志: 1-开启, 0-关闭',
+  `plugin_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '插件加载配置对象(lib_path, plugin_name, plugin_bin 等)',
+  `account` JSON NOT NULL DEFAULT (json_object()) COMMENT '独立账号登录凭据对象(username, password)',
+  `proxy_pool` JSON NOT NULL DEFAULT (json_array()) COMMENT '指定代理池名称列表(JSON 字符串数组)',
+  `query_wait` JSON NOT NULL DEFAULT (json_object()) COMMENT '查询等待与退避策略(mode, fixed_wait, random_min, random_max)',
+  `login_interval` INT UNSIGNED NOT NULL DEFAULT 1800 COMMENT '登录轮询/重试间隔(秒)',
+  `session_max_life` INT UNSIGNED NOT NULL DEFAULT 1800 COMMENT '会话最大存活时间(秒)',
+  `active_time_start` VARCHAR(5) NOT NULL DEFAULT '00:00' COMMENT '任务每日生效起始时间(HH:MM)',
+  `active_time_end` VARCHAR(5) NOT NULL DEFAULT '23:59' COMMENT '任务每日生效结束时间(HH:MM)',
+  `appointment_types` JSON NOT NULL DEFAULT (json_array()) COMMENT '目标预约类型与路由权重配置列表',
+  `user_preferences` JSON NOT NULL DEFAULT (json_object()) COMMENT '抢签用户个人资料与预订偏好信息',
+  `free_config` JSON NOT NULL DEFAULT (json_object()) COMMENT '目标使馆/国家专属业务扩展配置',
+  `version` INT UNSIGNED NOT NULL DEFAULT 0 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_standalone_node_identifier` (`node_id`, `identifier`),
+  KEY `idx_standalone_identifier` (`identifier`),
+  KEY `idx_standalone_order_id` (`order_id`),
+  KEY `idx_standalone_updated_at` (`updated_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Standalone 独立抢签任务配置表';
+```
+
+---
+
+## 3. JSON 与表字段映射对照表
+
+### 3.1 `booker_entries` 字段映射
+
+| JSON 字段 | SQL 列名 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| *(系统配置)* | `node_id` | `VARCHAR(64)` | 节点标识(如 `node01`) |
+| `identifier` | `identifier` | `VARCHAR(64)` | 组标识(如 `vfs.ie.nl`) |
+| `enable` | `enable` | `TINYINT(1)` | 布尔值 (0/1) |
+| `debug` | `debug` | `TINYINT(1)` | 布尔值 (0/1) |
+| `need_account` | `need_account` | `TINYINT(1)` | 布尔值 (0/1) |
+| `need_proxy` | `need_proxy` | `TINYINT(1)` | 布尔值 (0/1) |
+| `proxy_pool` | `proxy_pool` | `JSON` | 数组(如 `["proxy-cheap"]`) |
+| `proxy_cd` | `proxy_cd` | `INT UNSIGNED` | 代理冷却秒数 |
+| `session_max_life` | `session_max_life` | `INT UNSIGNED` | 会话存活秒数 |
+| `active_time_start`| `active_time_start`| `VARCHAR(5)` | 起始时间(`HH:MM`) |
+| `active_time_end` | `active_time_end` | `VARCHAR(5)` | 结束时间(`HH:MM`) |
+| `website` | `website` | `VARCHAR(512)`| 官网登录/主页链接 |
+| `booker` | `booker` | `JSON` | 包含 `account_source`, `account_pool_id`, `target_instances`, `keep_alive`, `account_cd`, `booking_cooldown`, `max_bookings_per_account` |
+| `plugin_config` | `plugin_config` | `JSON` | 包含 `lib_path`, `plugin_name`, `plugin_bin`, `plugin_proto` |
+| `appointment_types`| `appointment_types`| `JSON` | 包含 `weight`, `routing_key`, `city`, `visa_type`, `country` 数组 |
+| `free_config` | `free_config` | `JSON` | 包含 `mission_code`, `apt_configs` 等扩展字典 |
+
+---
+
+### 3.2 `sentinel_entries` 字段映射
+
+| JSON 字段 | SQL 列名 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| *(系统配置)* | `node_id` | `VARCHAR(64)` | 节点标识(如 `node01`) |
+| `identifier` | `identifier` | `VARCHAR(64)` | 组标识(如 `vfs.ie.nl`) |
+| `enable` | `enable` | `TINYINT(1)` | 布尔值 (0/1) |
+| `debug` | `debug` | `TINYINT(1)` | 布尔值 (0/1) |
+| `need_account` | `need_account` | `TINYINT(1)` | 布尔值 (0/1) |
+| `need_proxy` | `need_proxy` | `TINYINT(1)` | 布尔值 (0/1) |
+| `proxy_pool` | `proxy_pool` | `JSON` | 数组(如 `["proxy-cheap"]`) |
+| `proxy_cd` | `proxy_cd` | `INT UNSIGNED` | 代理冷却秒数 |
+| `session_max_life` | `session_max_life` | `INT UNSIGNED` | 会话存活秒数 |
+| `active_time_start`| `active_time_start`| `VARCHAR(5)` | 起始时间(`HH:MM`) |
+| `active_time_end` | `active_time_end` | `VARCHAR(5)` | 结束时间(`HH:MM`) |
+| `website` | `website` | `VARCHAR(512)`| 官网登录/主页链接 |
+| `sentinel` | `sentinel` | `JSON` | 包含 `account_source`, `account_pool_id`, `target_instances`, `account_cd`, `signal_ttl`, `query_wait` |
+| `plugin_config` | `plugin_config` | `JSON` | 包含 `lib_path`, `plugin_name`, `plugin_bin`, `plugin_proto` |
+| `appointment_types`| `appointment_types`| `JSON` | 包含 `weight`, `routing_key`, `city`, `visa_type`, `country` 数组 |
+| `free_config` | `free_config` | `JSON` | 包含 `mission_code`, `apt_configs` 等扩展字典 |
+
+---
+
+### 3.3 `standalone_entries` 字段映射
+
+| JSON 字段 | SQL 列名 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| *(系统配置)* | `node_id` | `VARCHAR(64)` | 节点标识(如 `node01`) |
+| *(系统配置)* | `order_id` | `VARCHAR(64)` | 订单标识(可选) |
+| `identifier` | `identifier` | `VARCHAR(64)` | 任务标识(如 `tls`, `usa`, `vfs`) |
+| `enable` | `enable` | `TINYINT(1)` | 布尔值 (0/1) |
+| `debug` | `debug` | `TINYINT(1)` | 布尔值 (0/1) |
+| `plugin_config` | `plugin_config` | `JSON` | 包含 `lib_path`, `plugin_name`, `plugin_bin`, `plugin_proto` |
+| `account` | `account` | `JSON` | 包含 `username`, `password` |
+| `proxy_pool` | `proxy_pool` | `JSON` | 数组(如 `["proxy-cheap"]`) |
+| `query_wait` | `query_wait` | `JSON` | 包含 `mode`, `fixed_wait`, `random_min`, `random_max` |
+| `login_interval` | `login_interval` | `INT UNSIGNED` | 登录重试/轮询秒数 |
+| `session_max_life` | `session_max_life` | `INT UNSIGNED` | 会话最大存活秒数 |
+| `active_time_start`| `active_time_start`| `VARCHAR(5)` | 起始时间(`HH:MM`) |
+| `active_time_end` | `active_time_end` | `VARCHAR(5)` | 结束时间(`HH:MM`) |
+| `appointment_types`| `appointment_types`| `JSON` | 包含 `weight`, `routing_key`, `city`, `visa_type`, `country` 数组 |
+| `user_preferences` | `user_preferences` | `JSON` | 申请人姓名、护照号、偏好时间等表单对象 |
+| `free_config` | `free_config` | `JSON` | 包含 `tls_url`, `capsolver_key`, `apt_configs` 等特定平台扩展配置 |
+
+---
+
+## 4. 插入与查询 SQL 示例
+
+### 4.1 Booker 插入示例
+```sql
+INSERT INTO `booker_entries` (
+  `node_id`, `identifier`, `enable`, `debug`, `need_account`, `need_proxy`,
+  `proxy_pool`, `proxy_cd`, `session_max_life`, `active_time_start`, `active_time_end`,
+  `website`, `booker`, `plugin_config`, `appointment_types`, `free_config`, `updated_by`
+) VALUES (
+  'node01',
+  'vfs.ie.nl',
+  0,
+  0,
+  1,
+  1,
+  '["proxy-cheap"]',
+  300,
+  1800,
+  '00:00',
+  '23:59',
+  'https://visa.vfsglobal.com/irl/en/nld/login',
+  '{"account_source": "built-in", "account_pool_id": "ie.nl.booker", "target_instances": 1, "keep_alive": 120, "account_cd": 10800, "booking_cooldown": 300, "max_bookings_per_account": 8}',
+  '{"lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg"}',
+  '[{"weight": 10, "routing_key": "slot.dub.nl.tourist", "city": "Dublin", "visa_type": "Tourist", "country": "Netherlands"}]',
+  '{"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"}}}',
+  'admin'
+);
+```
+
+### 4.2 Sentinel 插入示例
+```sql
+INSERT INTO `sentinel_entries` (
+  `node_id`, `identifier`, `enable`, `debug`, `need_account`, `need_proxy`,
+  `proxy_pool`, `proxy_cd`, `session_max_life`, `active_time_start`, `active_time_end`,
+  `website`, `sentinel`, `plugin_config`, `appointment_types`, `free_config`, `updated_by`
+) VALUES (
+  'node01',
+  'vfs.ie.nl',
+  0,
+  0,
+  1,
+  1,
+  '["proxy-cheap"]',
+  300,
+  1800,
+  '00:00',
+  '23:59',
+  'https://visa.vfsglobal.com/irl/en/nld/login',
+  '{"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}}',
+  '{"lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg"}',
+  '[{"weight": 10, "routing_key": "slot.dub.nl.tourist", "city": "Dublin", "visa_type": "Tourist", "country": "Netherlands"}]',
+  '{"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"}}}',
+  'admin'
+);
+```
+
+### 4.3 Standalone 插入示例
+```sql
+INSERT INTO `standalone_entries` (
+  `node_id`, `identifier`, `enable`, `debug`,
+  `plugin_config`, `account`, `proxy_pool`, `query_wait`,
+  `login_interval`, `session_max_life`, `active_time_start`, `active_time_end`,
+  `appointment_types`, `user_preferences`, `free_config`, `updated_by`
+) VALUES (
+  'node01',
+  'tls',
+  0,
+  1,
+  '{"lib_path": "plugins", "plugin_name": "tls_plugin", "plugin_bin": "tls_plugin.py", "plugin_proto": "IVSPlg"}',
+  '{"username": "18305503085@163.com", "password": "Zhangww@201207"}',
+  '["proxy-cheap"]',
+  '{"mode": "Random", "fixed_wait": 10, "random_min": 55, "random_max": 65}',
+  1800,
+  3600,
+  '00:00',
+  '23:30',
+  '[{"weight": 10, "routing_key": "slot.sha.fr.tourist", "city": "Shanghai", "visa_type": "Tourist", "country": "France"}]',
+  '{"support_pta": false, "expected_end_date": "2024-07-01", "expected_start_date": "2024-07-20"}',
+  '{"tls_url": "https://visas-fr.tlscontact.com/en-us/country/cn/vac/cnSHA2fr", "location": "Shanghai", "capsolver_key": "CAP-5441DD341DD3CC2FAEF0BE6FE493EE9A", "login_captcha": {"solve_advance": false, "site_key": "6LcDpXcfAAAAAM7wOEsF_38DNsL20tTvPTKxpyn0", "page_url": "https://i2-auth.visas-fr.tlscontact.com", "task": "ReCaptchaV2TaskProxyLess"}}',
+  'admin'
+);
+```

+ 103 - 258
docs/node_config_cloud_storage_and_api.md

@@ -1,37 +1,32 @@
 # 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`)周期轮询与热重载机制的联动方案。
+本文档详细说明 Coordinate 系统的节点配置(`config_booker.json`、`config_sentinel.json`、`config_standalone.json`)收归云端数据库的集中管理方案、HTTP 查询与下发 API,以及与 Coordinate 节点端(`main.py`、`utils/cloud_config.py`、`toolkit/vs_cloud_api.py`)周期轮询与热重载机制的联动方案。
 
 ---
 
 ## 1. 架构总览
 
-整个节点配置管理与同步系统的时序与拓扑流如下:
+Coordinate 节点配置同步系统的时序与拓扑流如下:
 
 ```mermaid
 sequenceDiagram
     autonumber
     actor Admin as 管理员/Web前端
     participant API as 云端配置管理服务 (API Server)
-    participant DB as MySQL 数据库 (node_configurations)
+    participant DB as MySQL 数据库 (sentinel_entries / booker_entries / standalone_entries)
     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: 【阶段二:节点定期轮询与平滑热重载】
+    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->>API: GET /api/node-configurations/{entry_type}?node_id=node01&pageSize=100
+        API->>DB: 查询满足条件的配置项列表
+        API-->>Node: 返回 items 列表 (code: 0)
+        Node->>Node: 计算 items 序列化后的 MD5 Hash
+        alt MD5 Hash 发生变更
+            Node->>Node: 写入本地磁盘缓存 config/config_{role}.json
             Node->>Node: 执行 sync_groups() 差异化启动/停止/更新 GCO 实例
             Node->>Node: 热重载完成,更新当前 current_hash
-        else config_hash 一致
+        else MD5 Hash 一致
             Node->>Node: 无需变动,跳过
         end
     end
@@ -39,56 +34,9 @@ sequenceDiagram
 
 ---
 
-## 2. 数据库表结构设计 (MySQL 8.x / MariaDB)
-
-采用**轻量单表 + 审计日志**结构:
-- `node_configurations`:存储各角色与各节点的配置主体(完整 JSON 格式)及自动计算的 MD5 哈希;
-- `node_config_audit_logs`:记录配置的修改历史、变更人与变更前后 Hash。
+## 2. HTTP RESTful API 设计
 
-```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 统一规范
+### 2.1 统一规范
 
 - **鉴权方式**: `Authorization: Bearer <token>`
 - **Content-Type**: `application/json`
@@ -103,59 +51,54 @@ CREATE TABLE IF NOT EXISTS `node_config_audit_logs` (
 
 ---
 
-### 3.2 接口详细定义
-
-#### 1. 节点拉取配置详情(Worker 轮询专用核心接口)
+### 2.2 分页查询配置列表
 
-- **接口地址**: `GET /api/node_configurations/detail`
+- **接口路径**: `GET /api/node-configurations/{entry_type}`
+- **Path 参数**:
+  - `entry_type` (*string*, 必填): 角色入口类型,可选值为 `sentinel` / `booker` / `standalone`。
 - **Query 参数**:
-  | 参数名 | 类型 | 必填 | 说明 |
-  | :--- | :--- | :--- | :--- |
-  | `node_id` | string | 是 | 节点标识,如 `node01` |
-  | `role` | string | 是 | 角色类型,可选值: `sentinel` / `booker` / `standalone` |
+  - `page` (*integer*, 可选, 默认 `1`): 页码。
+  - `pageSize` (*integer*, 可选, 默认 `20`): 每页条数(最大 100)。
+  - `identifier` (*string*, 可选): 任务标识模糊搜索(如 `vfs`)。
+  - `node_id` (*string*, 可选): 节点唯一标识精确搜索(如 `node01`)。
+  - `order_id` (*string*, 可选, 仅 `standalone` 有效): 关联订单 ID 精确搜索。
 
 - **请求示例**:
   ```http
-  GET /api/node_configurations/detail?node_id=node01&role=sentinel HTTP/1.1
+  GET /api/node-configurations/booker?node_id=node01&pageSize=100 HTTP/1.1
   Host: api.text.skin
   Authorization: Bearer tok_e946329a60ff45ba807f3f41b0e8b7fc
   ```
 
-- **响应示例**:
+- **响应示例 (`code: 0`)**:
   ```json
   {
     "code": 0,
     "message": "success",
     "data": {
-      "id": 1,
-      "role": "sentinel",
-      "node_id": "node01",
-      "is_enabled": 1,
-      "config_hash": "e2fc714c4727ee9395f324cd2e7f331f",
-      "config_content": [
+      "total": 1,
+      "page": 1,
+      "page_size": 20,
+      "items": [
         {
+          "id": 101,
+          "node_id": "node01",
           "identifier": "vfs.ie.nl",
-          "debug": false,
-          "enable": true,
-          "need_account": true,
-          "need_proxy": true,
+          "enable": 0,
+          "debug": 0,
+          "need_account": 1,
+          "need_proxy": 1,
           "proxy_pool": ["proxy-cheap"],
           "proxy_cd": 300,
           "session_max_life": 1800,
           "active_time_start": "00:00",
           "active_time_end": "23:59",
-          "sentinel": {
+          "website": "https://visa.vfsglobal.com/irl/en/nld/login",
+          "booker": {
             "account_source": "built-in",
-            "account_pool_id": "ie.nl.sentinel",
-            "target_instances": 1,
+            "account_pool_id": "ie.nl.booker",
             "account_cd": 10800,
-            "signal_ttl": 30,
-            "query_wait": {
-              "mode": "Random",
-              "fixed_wait": 10,
-              "random_min": 60,
-              "random_max": 300
-            }
+            "target_instances": 1
           },
           "plugin_config": {
             "lib_path": "plugins",
@@ -172,63 +115,14 @@ CREATE TABLE IF NOT EXISTS `node_config_audit_logs` (
               "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 哨兵轮询配置",
+            "country_code": "irl"
+          },
+          "version": 1,
           "updated_by": "admin",
-          "updated_at": "2026-08-23 00:30:00"
+          "created_at": "2026-08-23T20:10:00",
+          "updated_at": "2026-08-23T20:10:00"
         }
       ]
     }
@@ -237,138 +131,89 @@ CREATE TABLE IF NOT EXISTS `node_config_audit_logs` (
 
 ---
 
-#### 3. 管理后台新增/更新节点配置 (Save / Upsert)
+## 3. Coordinate 客户端集成
 
-- **接口地址**: `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` 新增方法
+### 3.1 `toolkit/vs_cloud_api.py`
 
 ```python
-def get_node_configuration(self, role: str, node_id: str) -> Optional[Dict[str, Any]]:
+def get_node_configurations(
+    self,
+    entry_type: str,
+    node_id: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 100,
+    identifier: Optional[str] = None,
+    order_id: Optional[str] = None,
+) -> Dict[str, Any]:
     """
-    从云端获取指定节点与角色的配置详情
-    GET /api/node_configurations/detail?node_id={node_id}&role={role}
+    分页查询指定 entry_type (sentinel/booker/standalone) 的节点配置列表
+    GET /api/node-configurations/{entry_type}
     """
-    url = f"{self.base_url}/api/node_configurations/detail"
-    params = {
-        "node_id": node_id,
-        "role": role
+    url = f"{self.base_url}/api/node-configurations/{quote(entry_type)}"
+    params: Dict[str, Any] = {
+        "page": page,
+        "pageSize": page_size,
     }
+    if node_id:
+        params["node_id"] = node_id
+    if identifier:
+        params["identifier"] = identifier
+    if order_id:
+        params["order_id"] = order_id
+
     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')}")
+        raise BizLogicError(message=f"Get node configurations biz error: {result.get('message')}")
 ```
 
-### 4.2 `utils/cloud_config.py` 改造
+### 3.2 `utils/cloud_config.py`
 
 ```python
-def fetch_cloud_config(role: str, node_id: str) -> Any:
+def fetch_cloud_config(role: str, node_id: str) -> Optional[Any]:
     """
-    拉取云端节点配置并返回 config_content
+    使用内置 VSCloudApi 从云端读取指定 role (entry_type) 及 node_id 的节点配置列表。
+    接口: GET /api/node-configurations/{entry_type}?node_id={node_id}&pageSize=100
+    返回 items 数组。
     """
     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:
+        data = VSCloudApi.Instance().get_node_configurations(entry_type=role, node_id=node_id, page_size=100)
+        if data and "items" in data:
+            return data["items"]
+    except Exception:
         pass
+    
     return None
 ```
 
----
-
-## 5. 数据初始化迁移脚本
-
-在实施迁移时,运行以下脚本将本地文件灌入数据库:
+### 3.3 `main.py` 周期热重载轮询
 
 ```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()
+# 初始化加载与缓存 Fallback
+groups_conf, current_hash, _ = load_remote_or_cache(
+    role=role,
+    node_id=node_id,
+    local_cache_path=config_path,
+    use_cloud=use_cloud,
+    logger=logger.info,
+)
+
+# 主轮询循环中
+if use_cloud and (now - last_poll_time >= args.poll_interval):
+    last_poll_time = now
+    try:
+        new_conf = fetch_cloud_config(role=role, node_id=node_id)
+        if new_conf is not None:
+            new_hash = compute_config_hash(new_conf)
+            if new_hash != current_hash:
+                logger.info(f"Cloud config change detected ({current_hash[:8]} -> {new_hash[:8]}). Auto-reloading...")
+                save_local_cache(config_path, new_conf)
+                sync_groups(role, new_conf, wrappers, gco_classes, logger)
+                current_hash = new_hash
+                logger.info(f"Auto-reload completed. Currently {len(wrappers)} group(s) running.")
+    except Exception as e:
+        logger.warning(f"Error polling cloud config for role '{role}' (node_id: '{node_id}'): {e}")
 ```

+ 5 - 5
main.py

@@ -256,7 +256,6 @@ def main():
     use_cloud = args.config is None
     config_path = args.config or f"config/config_{role}.json"
     node_id = os.getenv("NODE_ID", "node01")
-    config_key = f"{role}_config:{node_id}"
     status_key = f"vs:status:{role}:{node_id}"
 
     logger = setup_app_logger(role.title())
@@ -268,7 +267,8 @@ def main():
     start_upgrade_listener(REDIS_CFG, node_id, logger)
 
     groups_conf, current_hash, _ = load_remote_or_cache(
-        config_key=config_key,
+        role=role,
+        node_id=node_id,
         local_cache_path=config_path,
         use_cloud=use_cloud,
         logger=logger.info,
@@ -292,7 +292,7 @@ def main():
         logger.warning(f"Error reporting initial RoleStatus to Redis: {e}")
 
     if use_cloud:
-        logger.info(f"Cloud config active for key '{config_key}'. Polling every {args.poll_interval}s.")
+        logger.info(f"Cloud config active for role '{role}' (node_id: '{node_id}'). Polling every {args.poll_interval}s.")
 
     last_poll_time = time.time()
     last_status_report_time = time.time()
@@ -341,7 +341,7 @@ def main():
             if use_cloud and (now - last_poll_time >= args.poll_interval):
                 last_poll_time = now
                 try:
-                    new_conf = fetch_cloud_config(config_key)
+                    new_conf = fetch_cloud_config(role=role, node_id=node_id)
                     if new_conf is not None:
                         new_hash = compute_config_hash(new_conf)
                         if new_hash != current_hash:
@@ -351,7 +351,7 @@ def main():
                             current_hash = new_hash
                             logger.info(f"Auto-reload completed. Currently {len(wrappers)} group(s) running.")
                 except Exception as e:
-                    logger.warning(f"Error polling cloud config key '{config_key}': {e}")
+                    logger.warning(f"Error polling cloud config for role '{role}' (node_id: '{node_id}'): {e}")
 
     except KeyboardInterrupt:
         logger.info(f"Shutting down {role}...")

+ 33 - 0
toolkit/vs_cloud_api.py

@@ -63,6 +63,39 @@ class VSCloudApi:
         else:
             raise BizLogicError(message=f"Get dynamic config biz error: {result.get('message')}")
 
+    def get_node_configurations(
+        self,
+        entry_type: str,
+        node_id: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 100,
+        identifier: Optional[str] = None,
+        order_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        分页查询指定 entry_type (sentinel/booker/standalone) 的节点配置列表
+        GET /api/node-configurations/{entry_type}
+        """
+        url = f"{self.base_url}/api/node-configurations/{quote(entry_type)}"
+        params: Dict[str, Any] = {
+            "page": page,
+            "pageSize": page_size,
+        }
+        if node_id:
+            params["node_id"] = node_id
+        if identifier:
+            params["identifier"] = identifier
+        if order_id:
+            params["order_id"] = order_id
+
+        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 configurations biz error: {result.get('message')}")
+
     def get_vas_task_pop(self, routing_key: str) -> Dict:
         if configure.TEST_TASK:
             return configure.TEST_TASK

+ 15 - 18
utils/cloud_config.py

@@ -14,22 +14,18 @@ def compute_config_hash(config_data: Any) -> str:
     return hashlib.md5(serialized.encode('utf-8')).hexdigest()
 
 
-def fetch_cloud_config(config_key: str) -> Any:
+def fetch_cloud_config(role: str, node_id: str) -> Optional[Any]:
     """
-    使用内置 VSCloudApi 从云端读取指定 config_key 的动态配置。
-    支持节点专有 key (如 sentinel_config:node01),若无专有配置则自动回退至全局 key (如 sentinel_config)。
+    使用内置 VSCloudApi 从云端读取指定 role (entry_type) 及 node_id 的节点配置列表。
+    接口: GET /api/node-configurations/{entry_type}?node_id={node_id}&pageSize=100
+    返回 items 数组。
     """
     try:
-        data = VSCloudApi.Instance().get_dynamic_config(config_key)
-        if data is not None:
-            return data
+        data = VSCloudApi.Instance().get_node_configurations(entry_type=role, node_id=node_id, page_size=100)
+        if data and "items" in data:
+            return data["items"]
     except Exception:
         pass
-
-    # 若针对节点的特定 Key 未配置或获取失败,自动回退到全局 Key
-    if ":" in config_key:
-        base_key = config_key.split(":")[0]
-        return VSCloudApi.Instance().get_dynamic_config(base_key)
     
     return None
 
@@ -60,14 +56,15 @@ def load_local_config(path: str) -> Any:
 
 
 def load_remote_or_cache(
-    config_key: str,
+    role: str,
+    node_id: str,
     local_cache_path: str,
     use_cloud: bool = True,
     logger: Optional[Callable[[str], None]] = None
 ) -> Tuple[Any, str, bool]:
     """
     核心拉取与 Fallback 逻辑:
-    - 若开启了 use_cloud(默认):尝试调用 VSCloudApi 获取,成功则写入本地缓存文件;失败则 Fallback 读取本地缓存。
+    - 若开启了 use_cloud(默认):尝试调用 VSCloudApi 获取指定 role + node_id 的配置列表,成功则写入本地缓存文件;失败则 Fallback 读取本地缓存。
     - 若未开启 use_cloud(显式传了 -c/--config):直接读取本地配置文件。
     """
     def log_info(msg: str):
@@ -84,17 +81,17 @@ def load_remote_or_cache(
 
     if use_cloud:
         try:
-            log_info(f"Fetching cloud configuration key '{config_key}' via VSCloudApi...")
-            data = fetch_cloud_config(config_key)
+            log_info(f"Fetching cloud configuration for role '{role}' (node_id: '{node_id}') via VSCloudApi...")
+            data = fetch_cloud_config(role=role, node_id=node_id)
             if data is not None:
                 config_hash = compute_config_hash(data)
-                log_info(f"Successfully fetched cloud config '{config_key}' (hash: {config_hash[:8]})")
+                log_info(f"Successfully fetched cloud config for role '{role}' (hash: {config_hash[:8]}, count: {len(data)})")
                 save_local_cache(local_cache_path, data)
                 return data, config_hash, True
             else:
-                log_warn(f"Cloud config key '{config_key}' returned empty/null data.")
+                log_warn(f"Cloud config for role '{role}' (node_id: '{node_id}') returned empty/null data.")
         except Exception as e:
-            log_warn(f"Failed to fetch cloud config '{config_key}' via VSCloudApi: {e}")
+            log_warn(f"Failed to fetch cloud config for role '{role}' (node_id: '{node_id}') via VSCloudApi: {e}")
             log_warn(f"Fallback to local cache file: {local_cache_path}")
             
     local_data = load_local_config(local_cache_path)