plugin_cloud_storage_and_api.md 11 KB

云端插件管理系统与 HTTP API 设计文档

本文档详细说明 Coordinate 系统的云端插件存储架构、数据库表设计(MySQL 8.x)、HTTP 管理与分发 API,以及与 Coordinate 节点端(main.py、plugin_updater.py)热重载升级机制的联动方案。


1. 架构总览

整个插件管理与发布系统的拓扑与时序流如下:

sequenceDiagram
    autonumber
    actor Admin as 管理员/网页前端
    participant API as 云端管理服务 (API Server)
    participant DB as MySQL 数据库
    participant OSS as 对象存储 (OSS/S3)
    participant Redis as Redis (PubSub 消息中继)
    participant Node as Coordinate 节点 (main.py)

    Note over Admin,OSS: 【阶段一:插件发布与版本管理】
    Admin->>API: POST /plugins/publish (上传代码/URL、指定版本)
    API->>OSS: 上传 Python 代码并计算 SHA256 校验和
    API->>DB: 写入 plugin_versions 表并更新 plugins.latest_version
    API-->>Admin: 返回发布成功

    Note over Admin,Node: 【阶段二:命令下发与即时热重载】
    Admin->>API: POST /plugins/upgrade/dispatch (点击下发升级)
    API->>DB: 查询当前需要更新的插件及最新版本下载地址
    API->>Redis: PUBLISH vs:channel:upgrade [payload]
    Redis-->>Node: 广播推送升级消息给 Upgrade-Listener
    Node->>OSS: 下载目标插件代码
    Node->>Node: 语法预检 (py_compile) 与原子文件覆盖
    Node->>Node: 热重载当前插件实例 (reload_wrappers_for_plugin)
    Node-->>Admin: 定时心跳上报 RoleStatus 显示已安装最新版本

2. 数据库表结构设计 (MySQL 8.x / MariaDB)

采用清晰实用的轻量双表结构:

  • plugins:维护插件基础元数据与当前生效的最新版本(供网页列表展示和快速判断最新版本)。
  • plugin_versions:维护每个版本的发布记录、下载地址、SHA256 校验和与更新日志(用于留痕、版本追溯与一键回滚)。

    -- ----------------------------
    -- 1. 插件基础信息表
    -- ----------------------------
    CREATE TABLE IF NOT EXISTS `plugins` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID (plugin_id)',
    `name` VARCHAR(64) NOT NULL COMMENT '插件唯一英文标识,如: tls_plugin',
    `display_name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '插件展示名称,如: TLSContact欧洲多国签证预约插件',
    `filename` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '本地落盘文件名,如: tls_plugin.py',
    `latest_version` VARCHAR(32) NOT NULL DEFAULT '1.0.0' COMMENT '当前推荐/最新生效版本号',
    `description` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '插件功能描述',
    `status` TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '状态: 1-启用, 0-停用',
    `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_name` (`name`),
    KEY `idx_status` (`status`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='插件基础元数据表';
    
    -- ----------------------------
    -- 2. 插件版本发布历史表
    -- ----------------------------
    CREATE TABLE IF NOT EXISTS `plugin_versions` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID (version_id)',
    `plugin_id` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '关联插件ID (对应 plugins.id)',
    `plugin_name` VARCHAR(64) NOT NULL COMMENT '关联插件英文标识 (对应 plugins.name)',
    `version` VARCHAR(32) NOT NULL COMMENT '版本号,如: 1.0.1',
    `download_url` VARCHAR(512) NOT NULL COMMENT '代码文件下载URL (S3/OSS/对象存储/静态HTTP地址)',
    `sha256` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '文件SHA256校验码 (用于节点下载后防篡改/完整性校验)',
    `changelog` TEXT COMMENT '本次版本更新说明',
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '版本发布时间',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_plugin_version` (`plugin_id`, `version`),
    KEY `idx_plugin_name` (`plugin_name`),
    KEY `idx_plugin_id` (`plugin_id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='插件版本发布历史表';
    

3. HTTP RESTful API 设计

3.1 统一规范

  • Content-Type: application/json(发布文件时支持 multipart/form-data)
  • 统一响应报文:

    {
    "code": 0,          // 0 表示成功,非0为具体业务错误码
    "msg": "success",   // 状态提示信息
    "data": {}          // 业务数据(对象或数组)
    }
    

3.2 接口详细列表

1. 发布插件 / 上传新版本

  • URL: POST /plugins/publish
  • Content-Type: multipart/form-data 或 application/json
  • 请求字段:
字段 类型 必填 说明
name string 是 插件唯一英文标识,如 tls_plugin
version string 是 版本号,如 1.0.1
display_name string 否 插件中文展示名,如 TLSContact欧洲多国签证预约插件
description string 否 插件功能描述
file file 二选一 直接上传 .py 代码文件(后端自动上传OSS并计算SHA256)
download_url string 二选一 已有文件下载地址
sha256 string 否 文件 SHA256 校验和(若直接填 URL 时可选提供)
changelog string 否 本次版本更新日志
set_as_latest bool 否 是否立即将该版本设为插件最新版本(默认 true)
  • 响应示例:

    {
    "code": 0,
    "msg": "Plugin published successfully",
    "data": {
    "plugin_id": 1,
    "name": "tls_plugin",
    "version": "1.0.1",
    "download_url": "https://oss.example.com/plugins/tls_plugin-1.0.1.py",
    "sha256": "5d41402abc4b2a76b9719d911017c592..."
    }
    }
    

2. 获取插件列表 (网页管理)

  • URL: GET /plugins/list_all
  • 请求参数:
    • page: int, 页码 (默认 1)
    • page_size: int, 每页数量 (默认 20)
    • status: int, 状态过滤 (1-启用, 0-停用, 可选)
  • 响应示例:

    {
    "code": 0,
    "msg": "success",
    "data": {
    "list": [
      {
        "id": 1,
        "name": "tls_plugin",
        "display_name": "TLSContact欧洲多国签证预约插件",
        "filename": "tls_plugin.py",
        "latest_version": "1.0.1",
        "description": "DrissionPage拟人化与CF挑战破解",
        "status": 1,
        "created_at": "2026-08-20 10:00:00",
        "updated_at": "2026-08-21 14:00:00"
      }
    ],
    "total": 1
    }
    }
    

3. 获取插件详情 (含历史所有版本)

  • URL: GET /plugins/detail?plugin_id={id}
  • 响应示例:

    {
    "code": 0,
    "msg": "success",
    "data": {
    "id": 1,
    "name": "tls_plugin",
    "display_name": "TLSContact欧洲多国签证预约插件",
    "filename": "tls_plugin.py",
    "latest_version": "1.0.1",
    "description": "DrissionPage拟人化与CF挑战破解",
    "status": 1,
    "versions": [
      {
        "id": 2,
        "version": "1.0.1",
        "download_url": "https://oss.example.com/plugins/tls_plugin-1.0.1.py",
        "sha256": "5d41402abc4b2a76b9719d911017c592...",
        "changelog": "修复CF验证码重试卡死问题",
        "created_at": "2026-08-21 14:00:00"
      },
      {
        "id": 1,
        "version": "1.0.0",
        "download_url": "https://oss.example.com/plugins/tls_plugin-1.0.0.py",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "changelog": "初始版本上线",
        "created_at": "2026-08-20 10:00:00"
      }
    ]
    }
    }
    

4. 编辑插件基础信息

  • URL: PUT /plugins/update?plugin_id={id}
  • 请求体:

    {
    "display_name": "TLSContact欧洲签证插件(更新版)",
    "description": "更新后的功能描述说明",
    "status": 1
    }
    

5. 切换生效版本 / 一键回滚

  • URL: POST /plugins/switch-version
  • 请求体:

    {
    "plugin_id": 1,
    "version": "1.0.0"
    }
    

    服务端将 plugins.latest_version 改为指定历史版本号。


6. 删除插件 / 删除指定历史版本

  • 删除整套插件: DELETE /plugins/delete?plugin_id={id}
    • 删除该插件及其所有关联版本记录。
  • 删除指定版本: DELETE /plugins/delete_version?plugin_id={id}&version={version}
    • 删除某个具体的历史版本记录。

7. 下发插件升级命令 (控制面与节点联动)

  • URL: POST /plugins/upgrade/dispatch
  • 请求体:

    {
    "target_node": "all",          // "all" 表示全量广播,或指定特定节点 node_id 如 "node01"
    "plugins": ["tls_plugin"]      // 指定升级的插件英文名列表;传空数组 [] 表示对所有启用的插件下发最新版
    }
    
  • 服务端处理与广播:

    1. 服务端查询 DB 组装目标插件的最新版本元数据数组;
    2. 根据 target_node 确定 Redis 频道(vs:channel:upgrade 或 vs:channel:upgrade:{node_id});
    3. 执行 redis_client.publish(channel, json.dumps(payload))。
  • 广播 Payload 结构示例:

    [
    {
    "name": "tls_plugin",
    "filename": "tls_plugin.py",
    "version": "1.0.1",
    "download_url": "https://oss.example.com/plugins/tls_plugin-1.0.1.py",
    "sha256": "5d41402abc4b2a76b9719d911017c592..."
    }
    ]
    

8. 获取当前全量最新可用插件清单 (节点主动拉取)

  • URL: GET /plugins/latest
  • 响应示例:

    {
    "code": 0,
    "msg": "success",
    "data": [
    {
      "name": "tls_plugin",
      "display_name": "TLSContact欧洲多国签证预约插件",
      "filename": "tls_plugin.py",
      "version": "1.0.1",
      "description": "DrissionPage拟人化与CF挑战破解",
      "download_url": "https://oss.example.com/plugins/tls_plugin-1.0.1.py",
      "sha256": "5d41402abc4b2a76b9719d911017c592...",
      "changelog": "修复CF验证码重试卡死问题"
    }
    ]
    }
    

4. 与 Coordinate 节点本地代码对应关系

业务动作 节点对应代码位置
升级消息监听 main.py: start_upgrade_listener()
版本比对规则 utils/plugin_updater.py: is_newer_version()
安全下载与编译安装 utils/plugin_updater.py: download_and_install_plugin()
热重载运行中实例 main.py: reload_wrappers_for_plugin()
节点版本心跳上报 vs_types.py: RoleStatus.installed_plugins