# 云端插件管理系统与 HTTP API 设计文档 本文档详细说明 Coordinate 系统的云端插件存储架构、数据库表设计(MySQL 8.x)、HTTP 管理与分发 API,以及与 Coordinate 节点端(`main.py`、`plugin_updater.py`)热重载升级机制的联动方案。 --- ## 1. 架构总览 整个插件管理与发布系统的拓扑与时序流如下: ```mermaid 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 校验和与更新日志(用于留痕、版本追溯与一键回滚)。 ```sql -- ---------------------------- -- 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`) - **统一响应报文**: ```json { "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`) | - **响应示例**: ```json { "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-停用, 可选) - **响应示例**: ```json { "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}` - **响应示例**: ```json { "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}` - **请求体**: ```json { "display_name": "TLSContact欧洲签证插件(更新版)", "description": "更新后的功能描述说明", "status": 1 } ``` --- #### 5. 切换生效版本 / 一键回滚 - **URL**: `POST /plugins/switch-version` - **请求体**: ```json { "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` - **请求体**: ```json { "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 结构示例**: ```json [ { "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` - **响应示例**: ```json { "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()](file:///Users/hujiarui/workspace/coordinate/main.py#L153-L180) | | **版本比对规则** | [utils/plugin_updater.py: is_newer_version()](file:///Users/hujiarui/workspace/coordinate/utils/plugin_updater.py#L25-L27) | | **安全下载与编译安装** | [utils/plugin_updater.py: download_and_install_plugin()](file:///Users/hujiarui/workspace/coordinate/utils/plugin_updater.py#L117-L154) | | **热重载运行中实例** | [main.py: reload_wrappers_for_plugin()](file:///Users/hujiarui/workspace/coordinate/main.py#L104-L123) | | **节点版本心跳上报** | [vs_types.py: RoleStatus.installed_plugins](file:///Users/hujiarui/workspace/coordinate/vs_types.py#L290-L300) |