node_configuration.md 11 KB

节点配置管理服务 (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 鉴权(管理员权限):

    Authorization: Bearer <token>
    

统一响应结构

所有接口均返回标准 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):

    {
    "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):

    {
    "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 | 否 | "" | 修改原因/变更备注(记录到审计日志) |

  • 请求示例:

    {
    "role": "sentinel",
    "node_id": "node01",
    "config_content": [
      {
        "identifier": "vfs.ie.nl",
        "debug": true,
        "enable": true
      }
    ],
    "is_enabled": 1,
    "description": "更新为调试模式",
    "remark": "排查爱尔兰荷兰节点抓取问题"
    }
    
  • 响应报文 (Response):

    {
    "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 | 否 | 操作备注说明 |

  • 请求示例:

    {
    "role": "sentinel",
    "node_id": "node01",
    "is_enabled": 0,
    "remark": "临时下线维护"
    }
    
  • 响应报文 (Response):

    {
    "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 | 否 | 克隆操作备注 |

  • 请求示例:

    {
    "source_role": "sentinel",
    "source_node_id": "node01",
    "target_role": "sentinel",
    "target_node_id": "node02",
    "remark": "扩容新节点"
    }
    
  • 响应报文 (Response):

    {
    "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):

    {
    "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):

    {
    "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"
        }
      ]
    }
    }