# 节点配置管理服务 (Node Configuration) HTTP API 接口文档 本文档为 Coordinate 节点配置管理服务(`node_configurations`)的后端 HTTP RESTful API 接口规范。 --- ## 1. 接口通用规范 - **协议规范**: `HTTP/1.1` 或 `HTTP/2` - **基础路径 (Base URL)**: `/api` - **数据交互格式**: `application/json` - **字符编码**: `UTF-8` - **认证方式**: Bearer Token 鉴权(管理员权限): ```http Authorization: Bearer ``` ### 统一响应结构 所有接口均返回标准 JSON 结构: ```json { "code": 0, // 0 为成功,非 0 为错误码 "message": "success", "data": {} // 响应数据对象 } ``` --- ## 2. API 接口列表 | 方法 | 接口路径 | 说明 | | :--- | :--- | :--- | | `GET` | `/api/node_configurations/list` | 分页查询节点配置列表 | | `GET` | `/api/node_configurations/detail` | 获取指定节点配置详情 | | `POST` | `/api/node_configurations/save` | 新增或更新节点配置 (Save/Upsert) | | `POST` | `/api/node_configurations/toggle` | 快速启用 / 禁用节点配置 | | `POST` | `/api/node_configurations/clone` | 节点配置克隆复制 | | `DELETE` | `/api/node_configurations/delete` | 删除指定节点配置 | | `GET` | `/api/node_configurations/audit-logs` | 查询配置修改审计日志 | --- ## 3. 接口详细说明 ### 3.1 查询节点配置列表 - **接口地址**: `GET /api/node_configurations/list` - **Query 参数**: | 参数名 | 类型 | 必填 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | :--- | | `role` | string | 否 | `null` | 过滤角色: `sentinel` / `booker` / `standalone` | | `node_id` | string | 否 | `null` | 过滤节点标识 (支持模糊搜索) | | `is_enabled` | int | 否 | `null` | 过滤启用状态: `1` (启用), `0` (禁用) | | `page` | int | 否 | `1` | 当前页码 (>= 1) | | `page_size` | int | 否 | `20` | 每页数量 (1 ~ 100) | - **响应报文 (Response)**: ```json { "code": 0, "message": "success", "data": { "total": 2, "items": [ { "id": 1, "role": "sentinel", "node_id": "node01", "is_enabled": 1, "config_hash": "6cbc001d68b050867db78f262a884ca6", "description": "节点01 哨兵监控配置", "created_by": "admin", "updated_by": "admin", "created_at": "2026-08-23T00:30:00", "updated_at": "2026-08-23T00:45:00" } ] } } ``` --- ### 3.2 获取指定节点配置详情 - **接口地址**: `GET /api/node_configurations/detail` - **Query 参数**: | 参数名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | | `role` | string | 是 | 角色类型: `sentinel` / `booker` / `standalone` | | `node_id` | string | 是 | 节点唯一标识,如 `node01` | - **响应报文 (Response)**: ```json { "code": 0, "message": "success", "data": { "id": 1, "role": "sentinel", "node_id": "node01", "is_enabled": 1, "config_hash": "6cbc001d68b050867db78f262a884ca6", "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" } } ], "description": "节点01 哨兵监控配置", "created_by": "admin", "updated_by": "admin", "created_at": "2026-08-23T00:30:00", "updated_at": "2026-08-23T00:45:00" } } ``` --- ### 3.3 保存 / 更新节点配置 (Save / Upsert) - **接口地址**: `POST /api/node_configurations/save` - **请求头**: `Content-Type: application/json` - **请求体 (Body)**: | 字段名 | 类型 | 必填 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | :--- | | `role` | string | 是 | - | 角色类型: `sentinel` / `booker` / `standalone` | | `node_id` | string | 是 | - | 节点标识,如 `node01` | | `config_content` | array / object | 是 | - | 完整的配置 JSON 内容 | | `is_enabled` | int | 否 | `1` | 启用状态: `1` (启用), `0` (禁用) | | `description` | string | 否 | `""` | 配置描述/用途说明 | | `remark` | string | 否 | `""` | 修改原因/变更备注(记录到审计日志) | - **请求示例**: ```json { "role": "sentinel", "node_id": "node01", "config_content": [ { "identifier": "vfs.ie.nl", "debug": true, "enable": true } ], "is_enabled": 1, "description": "更新为调试模式", "remark": "排查爱尔兰荷兰节点抓取问题" } ``` - **响应报文 (Response)**: ```json { "code": 0, "message": "Configuration saved successfully", "data": { "id": 1, "role": "sentinel", "node_id": "node01", "is_enabled": 1, "config_hash": "779854f7892e9bacc6e73f32e4fa830a", "config_content": [ ... ], "description": "更新为调试模式", "created_by": "admin", "updated_by": "admin", "created_at": "2026-08-23T00:30:00", "updated_at": "2026-08-23T01:00:00" } } ``` --- ### 3.4 快速启用 / 禁用节点配置 - **接口地址**: `POST /api/node_configurations/toggle` - **请求头**: `Content-Type: application/json` - **请求体 (Body)**: | 字段名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | | `role` | string | 是 | 角色类型: `sentinel` / `booker` / `standalone` | | `node_id` | string | 是 | 节点标识,如 `node01` | | `is_enabled` | int | 是 | 状态: `1` (启用), `0` (禁用) | | `remark` | string | 否 | 操作备注说明 | - **请求示例**: ```json { "role": "sentinel", "node_id": "node01", "is_enabled": 0, "remark": "临时下线维护" } ``` - **响应报文 (Response)**: ```json { "code": 0, "message": "Configuration status updated successfully", "data": { "id": 1, "role": "sentinel", "node_id": "node01", "is_enabled": 0, "config_hash": "779854f7892e9bacc6e73f32e4fa830a", "description": "节点01 哨兵监控配置", "updated_by": "admin", "updated_at": "2026-08-23T01:05:00" } } ``` --- ### 3.5 跨节点克隆 / 复制配置 - **接口地址**: `POST /api/node_configurations/clone` - **请求头**: `Content-Type: application/json` - **请求体 (Body)**: | 字段名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | | `source_role` | string | 是 | 源角色类型 | | `source_node_id` | string | 是 | 源节点标识 | | `target_role` | string | 是 | 目标角色类型 | | `target_node_id` | string | 是 | 目标节点标识 | | `remark` | string | 否 | 克隆操作备注 | - **请求示例**: ```json { "source_role": "sentinel", "source_node_id": "node01", "target_role": "sentinel", "target_node_id": "node02", "remark": "扩容新节点" } ``` - **响应报文 (Response)**: ```json { "code": 0, "message": "Configuration cloned successfully", "data": { "id": 2, "role": "sentinel", "node_id": "node02", "is_enabled": 1, "config_hash": "779854f7892e9bacc6e73f32e4fa830a", "config_content": [ ... ], "description": "Cloned from sentinel:node01. 节点01 哨兵监控配置", "created_by": "admin", "updated_by": "admin", "created_at": "2026-08-23T01:10:00", "updated_at": "2026-08-23T01:10:00" } } ``` --- ### 3.6 删除节点配置 - **接口地址**: `DELETE /api/node_configurations/delete` - **Query 参数**: | 参数名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | | `role` | string | 是 | 角色类型: `sentinel` / `booker` / `standalone` | | `node_id` | string | 是 | 节点标识 | | `remark` | string | 否 | 删除原因说明 | - **响应报文 (Response)**: ```json { "code": 0, "message": "Configuration deleted successfully", "data": { "role": "sentinel", "node_id": "node02", "deleted": true } } ``` --- ### 3.7 查询配置修改审计日志 - **接口地址**: `GET /api/node_configurations/audit-logs` - **Query 参数**: | 参数名 | 类型 | 必填 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | :--- | | `role` | string | 否 | `null` | 过滤角色类型 | | `node_id` | string | 否 | `null` | 过滤节点标识 | | `page` | int | 否 | `1` | 页码 (>= 1) | | `page_size` | int | 否 | `20` | 每页数量 (1 ~ 100) | - **响应报文 (Response)**: ```json { "code": 0, "message": "success", "data": { "total": 3, "items": [ { "id": 3, "role": "sentinel", "node_id": "node01", "action": "UPDATE", "before_hash": "6cbc001d68b050867db78f262a884ca6", "after_hash": "779854f7892e9bacc6e73f32e4fa830a", "operator": "admin@example.com", "remark": "排查爱尔兰荷兰节点抓取问题", "created_at": "2026-08-23T01:00:00" }, { "id": 2, "role": "sentinel", "node_id": "node01", "action": "TOGGLE", "before_hash": "6cbc001d68b050867db78f262a884ca6", "after_hash": "6cbc001d68b050867db78f262a884ca6", "operator": "admin@example.com", "remark": "临时下线维护", "created_at": "2026-08-23T00:50:00" }, { "id": 1, "role": "sentinel", "node_id": "node01", "action": "CREATE", "before_hash": null, "after_hash": "6cbc001d68b050867db78f262a884ca6", "operator": "system", "remark": "Initial import from config_sentinel.json", "created_at": "2026-08-23T00:30:00" } ] } } ```