node_configuration.md 14 KB

前端开发 API 接口文档:Provider 模板与 Node Configuration

本文档为 Coordinate 管理系统的前端接口规范,包含 服务商模板管理(Provider) 与 节点任务配置管理(Node Configuration: booker / sentinel / standalone) 的所有接口定义、字段说明及 JSON 示例。


0. 通用约定

  • Base URL: /api (例如 http://127.0.0.1:8888/api)
  • 请求头: 除公共登录接口外,所有请求均须携带 Bearer Token:

    Authorization: Bearer <token>
    Content-Type: application/json
    
  • 统一响应格式:

    {
    "code": 0,
    "message": "success",
    "data": {}
    }
    
    • code === 0 表示请求成功;
    • code !== 0 表示业务异常,此时 message 包含人类可读的错误提示信息。

业务错误码

code HTTP 状态 说明
0 200 成功
40000 400 参数校验失败 / 掩码占位符拦截 / 删除最后一条未确认
40101 401 未登录或 Token 无效/已过期
40301 403 权限不足 (非管理员)
40400 404 目标资源不存在
40900 409 Provider 名称已被占用
40902 409 标识符冲突 (同节点下 node_id + identifier 已存在)
42200 422 请求 Body 结构或数据类型非法

1. Provider 服务商模板接口

1.1 获取服务商目录列表

  • 接口路径: GET /api/providers
  • Query 参数:
    • enabled_only (boolean, 可选, 默认 false): 设为 true 时仅返回已启用的服务商(适用于向导新建下拉框)。

响应示例 (code: 0):

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "vfs",
      "enabled": 1,
      "plugin_config": {
        "lib_path": "plugins",
        "plugin_name": "vfs_plugin",
        "plugin_bin": "vfs_plugin.py",
        "plugin_proto": "IVSPlg"
      },
      "role_templates": {
        "booker": {
          "proxy_cd": 300,
          "session_max_life": 1800,
          "booker.account_cd": 10800,
          "booker.target_instances": 1
        },
        "sentinel": {
          "sentinel.signal_ttl": 30,
          "sentinel.query_wait.mode": "Random"
        }
      },
      "version": 1,
      "updated_by": "admin",
      "created_at": "2026-08-23T20:00:00",
      "updated_at": "2026-08-23T20:00:00"
    }
  ]
}

1.2 获取服务商详情

  • 接口路径: GET /api/providers/{name}
  • Path 参数:
    • name (string, 必填): 服务商唯一标识/名称(如 vfs, tls, bls)。

响应示例 (code: 0):

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "vfs",
    "enabled": 1,
    "plugin_config": {
      "lib_path": "plugins",
      "plugin_name": "vfs_plugin",
      "plugin_bin": "vfs_plugin.py",
      "plugin_proto": "IVSPlg"
    },
    "role_templates": {
      "booker": {
        "proxy_cd": 300,
        "session_max_life": 1800,
        "booker.account_cd": 10800
      },
      "sentinel": {
        "sentinel.signal_ttl": 30
      }
    },
    "version": 1,
    "updated_by": "admin",
    "created_at": "2026-08-23T20:00:00",
    "updated_at": "2026-08-23T20:00:00"
  }
}

1.3 新建服务商模板

  • 接口路径: POST /api/providers
  • Body 参数:
    • name (string, 必填): 服务商唯一标识/名称(如 vfs, tls, bls 等)。
    • enabled (boolean, 可选, 默认 true): 是否启用。
    • plugin_config (object, 可选): 默认插件加载配置。
    • role_templates (object, 可选): 角色配置模板(键仅允许 sentinel / booker / standalone,值为点路径平铺字典)。

请求示例:

{
  "name": "tls",
  "enabled": true,
  "plugin_config": {
    "lib_path": "plugins",
    "plugin_name": "tls_plugin",
    "plugin_bin": "tls_plugin.py",
    "plugin_proto": "IVSPlg"
  },
  "role_templates": {
    "standalone": {
      "login_interval": 1800,
      "session_max_life": 3600
    }
  }
}

响应示例 (code: 0):

{
  "code": 0,
  "message": "Provider created successfully",
  "data": {
    "id": 2,
    "name": "tls",
    "enabled": 1,
    "plugin_config": { ... },
    "role_templates": { ... },
    "version": 1,
    "updated_by": "admin",
    "created_at": "2026-08-23T20:05:00",
    "updated_at": "2026-08-23T20:05:00"
  }
}

1.4 编辑服务商模板

  • 接口路径: PUT /api/providers/{name}
  • Body 参数(支持稀疏更新,Body 中不传 name):
    • enabled (boolean, 可选): 启用状态。
    • plugin_config (object, 可选): 插件配置对象。
    • role_templates (object, 可选): 角色配置模板(覆盖更新)。

请求示例:

{
  "enabled": true,
  "plugin_config": {
    "lib_path": "plugins",
    "plugin_name": "tls_plugin_v2",
    "plugin_bin": "tls_plugin.py",
    "plugin_proto": "IVSPlg"
  }
}

响应示例 (code: 0): 返回更新后的 Provider 完整对象。


1.5 删除服务商模板

  • 接口路径: DELETE /api/providers/{name}

响应示例 (code: 0):

{
  "code": 0,
  "message": "Provider deleted successfully",
  "data": true
}

2. Node Configuration 节点任务配置接口

entry_type 说明: 所有端点中的 {entry_type} 统一取值为:

  • booker (Booker 占位/出票角色)
  • sentinel (Sentinel 监控/扫位角色)
  • standalone (Standalone 独立一体化抢签任务)

2.1 分页查询配置列表

  • 接口路径: GET /api/node-configurations/{entry_type}
  • Query 参数:
    • page (integer, 可选, 默认 1): 页码。
    • pageSize (integer, 可选, 默认 20): 每页条数(最大 100)。
    • identifier (string, 可选): 任务标识模糊搜索(如 vfs)。
    • node_id (string, 可选): 节点唯一标识精确搜索(如 node01)。
    • order_id (string, 可选, 仅 standalone 有效): 关联订单 ID 精确搜索。

响应示例 (code: 0):

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "id": 101,
        "node_id": "node01",
        "identifier": "vfs.ie.nl",
        "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",
        "website": "https://visa.vfsglobal.com/irl/en/nld/login",
        "booker": {
          "account_source": "built-in",
          "account_pool_id": "ie.nl.booker",
          "account_cd": 10800,
          "target_instances": 1
        },
        "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"
          }
        ],
        "free_config": {
          "mission_code": "nld",
          "country_code": "irl"
        },
        "version": 1,
        "updated_by": "admin",
        "created_at": "2026-08-23T20:10:00",
        "updated_at": "2026-08-23T20:10:00"
      }
    ]
  }
}

2.2 获取配置详情

  • 接口路径: GET /api/node-configurations/{entry_type}/{entry_id}
  • Path 参数:
    • entry_type (string, 必填): booker | sentinel | standalone
    • entry_id (integer, 必填): 配置条目主键 ID

响应示例 (code: 0): 返回该配置条目的全字段对象。


2.3 新建配置条目

  • 接口路径: POST /api/node-configurations/{entry_type}
  • 重要规则: 新建条目一律以停用状态落库 (enable = 0);同一节点下 (node_id, identifier) 冲突时返回 40902。

A. Booker 角色请求 Body 示例:

{
  "node_id": "node01",
  "identifier": "vfs.ie.nl",
  "website": "https://visa.vfsglobal.com/irl/en/nld/login",
  "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",
  "booker": {
    "account_source": "built-in",
    "account_pool_id": "ie.nl.booker",
    "target_instances": 1,
    "account_cd": 10800,
    "booking_cooldown": 300,
    "max_bookings_per_account": 8
  },
  "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"
    }
  ],
  "free_config": {
    "mission_code": "nld",
    "country_code": "irl"
  }
}

B. Sentinel 角色请求 Body 示例:

{
  "node_id": "node01",
  "identifier": "vfs.ie.nl",
  "website": "https://visa.vfsglobal.com/irl/en/nld/login",
  "sentinel": {
    "account_source": "built-in",
    "account_pool_id": "ie.nl.sentinel",
    "target_instances": 1,
    "signal_ttl": 30,
    "query_wait": {
      "mode": "Random",
      "fixed_wait": 10,
      "random_min": 60,
      "random_max": 300
    }
  },
  "plugin_config": { ... },
  "appointment_types": [ ... ],
  "free_config": { ... }
}

C. Standalone 角色请求 Body 示例:

{
  "node_id": "node01",
  "order_id": "ORD-20260823-001",
  "identifier": "tls.shanghai.fr",
  "account": {
    "username": "user@example.com",
    "password": "Password123"
  },
  "proxy_pool": ["proxy-cheap"],
  "query_wait": {
    "mode": "Random",
    "fixed_wait": 10,
    "random_min": 55,
    "random_max": 65
  },
  "login_interval": 1800,
  "session_max_life": 3600,
  "user_preferences": {
    "support_pta": false,
    "expected_start_date": "2026-09-01",
    "expected_end_date": "2026-09-20"
  },
  "plugin_config": { ... },
  "appointment_types": [ ... ],
  "free_config": { ... }
}

响应示例 (code: 0): 返回新生成的配置对象(初始 enable: 0, version: 1)。


2.4 稀疏更新配置 (Sparse Update)

  • 接口路径: PUT /api/node-configurations/{entry_type}/{entry_id}
  • 说明:
    • set:支持顶级字段(如 proxy_cd)与多层 JSON 点路径更新(如 booker.account_cd、sentinel.query_wait.random_min)。
    • clear:显式将字段清空重置为默认空值(如 website 重置为空串、account 重置为空对象)。
    • 成功更新后自动写入修订历史链,version 版本号自增 +1。

请求示例:

{
  "set": {
    "proxy_cd": 600,
    "booker.account_cd": 9000,
    "booker.target_instances": 2
  },
  "clear": [
    "website"
  ]
}

响应示例 (code: 0):

{
  "code": 0,
  "message": "Node configuration updated successfully",
  "data": {
    "id": 101,
    "node_id": "node01",
    "identifier": "vfs.ie.nl",
    "proxy_cd": 600,
    "website": "",
    "booker": {
      "account_source": "built-in",
      "account_pool_id": "ie.nl.booker",
      "account_cd": 9000,
      "target_instances": 2
    },
    "version": 2,
    "updated_by": "admin",
    "created_at": "2026-08-23T20:10:00",
    "updated_at": "2026-08-23T20:15:00"
  }
}

2.5 启用 / 停用配置 (Enable / Disable)

  • 接口路径: PUT /api/node-configurations/{entry_type}/{entry_id}/enable
  • Body 参数:
    • enable (boolean, 必填): true 为启用 (1),false 为停用 (0)。

请求示例:

{
  "enable": true
}

响应示例 (code: 0):

{
  "code": 0,
  "message": "Node configuration status toggled",
  "data": {
    "id": 101,
    "enable": 1,
    "version": 3,
    "updated_by": "admin",
    ...
  }
}

2.6 删除配置条目

  • 接口路径: DELETE /api/node-configurations/{entry_type}/{entry_id}
  • Query 参数:
    • confirm_purge (boolean, 可选, 默认 false): 删除保护守卫。当当前角色的配置在数据库中仅剩最后 1 条时,若不传 confirm_purge=true 会拦截并返回 40000(提示需二次确认);有多条数据时可直接删除。

请求示例:

DELETE /api/node-configurations/booker/101?confirm_purge=true

响应示例 (code: 0):

{
  "code": 0,
  "message": "Node configuration deleted successfully",
  "data": true
}

2.7 查询配置修订历史记录 (Revisions)

  • 接口路径: GET /api/node-configurations/{entry_type}/{entry_id}/revisions
  • 说明: 每次新建、修改、启停或回滚都会自动保留完整快照。按时间倒序排列。

响应示例 (code: 0):

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 15,
      "entry_type": "booker",
      "entry_id": 101,
      "version": 3,
      "action": "enable",
      "snapshot": { ... },
      "updated_by": "admin",
      "created_at": "2026-08-23T20:20:00"
    },
    {
      "id": 14,
      "entry_type": "booker",
      "entry_id": 101,
      "version": 2,
      "action": "update",
      "snapshot": { ... },
      "updated_by": "admin",
      "created_at": "2026-08-23T20:15:00"
    },
    {
      "id": 13,
      "entry_type": "booker",
      "entry_id": 101,
      "version": 1,
      "action": "create",
      "snapshot": { ... },
      "updated_by": "admin",
      "created_at": "2026-08-23T20:10:00"
    }
  ]
}

2.8 回滚配置至指定历史版本 (Rollback)

  • 接口路径: POST /api/node-configurations/{entry_type}/{entry_id}/rollback
  • Body 参数:
    • revision_id (integer, 必填): 目标历史快照的 ID(来自 2.7 节)。

请求示例:

{
  "revision_id": 13
}

响应示例 (code: 0):

{
  "code": 0,
  "message": "Node configuration rolled back successfully",
  "data": {
    "id": 101,
    "enable": 0,
    "version": 4,
    "updated_by": "admin",
    ...
  }
}