本文档详细说明 Coordinate 系统的云端插件存储架构、数据库表设计(MySQL 8.x)、HTTP 管理与分发 API,以及与 Coordinate 节点端(main.py、plugin_updater.py)热重载升级机制的联动方案。
整个插件管理与发布系统的拓扑与时序流如下:
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 显示已安装最新版本
采用清晰实用的轻量双表结构:
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='插件版本发布历史表';
application/json(发布文件时支持 multipart/form-data)统一响应报文:
{
"code": 0, // 0 表示成功,非0为具体业务错误码
"msg": "success", // 状态提示信息
"data": {} // 业务数据(对象或数组)
}
POST /plugins/publishmultipart/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..."
}
}
GET /plugins/list_allpage: 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
}
}
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"
}
]
}
}
PUT /plugins/update?plugin_id={id}请求体:
{
"display_name": "TLSContact欧洲签证插件(更新版)",
"description": "更新后的功能描述说明",
"status": 1
}
POST /plugins/switch-version请求体:
{
"plugin_id": 1,
"version": "1.0.0"
}
服务端将
plugins.latest_version改为指定历史版本号。
DELETE /plugins/delete?plugin_id={id}
DELETE /plugins/delete_version?plugin_id={id}&version={version}
POST /plugins/upgrade/dispatch请求体:
{
"target_node": "all", // "all" 表示全量广播,或指定特定节点 node_id 如 "node01"
"plugins": ["tls_plugin"] // 指定升级的插件英文名列表;传空数组 [] 表示对所有启用的插件下发最新版
}
服务端处理与广播:
target_node 确定 Redis 频道(vs:channel:upgrade 或 vs:channel:upgrade:{node_id});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..."
}
]
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验证码重试卡死问题"
}
]
}
| 业务动作 | 节点对应代码位置 |
|---|---|
| 升级消息监听 | 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 |