Procházet zdrojové kódy

feat: 实现云端插件管理系统与HTTP API

jerry před 2 měsíci
rodič
revize
3fba699c28

+ 199 - 0
app/api/endpoints/plugin.py

@@ -0,0 +1,199 @@
+from typing import Optional, List, Dict, Any
+from fastapi import APIRouter, Depends, Query, Body, File, Form, UploadFile, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.utils.response import success
+from app.schemas.common import ApiResponse
+from app.schemas.plugin import (
+    PluginPublishOut,
+    PluginOut,
+    PluginListResponse,
+    PluginDetailOut,
+    PluginUpdate,
+    PluginSwitchVersion,
+    PluginUpgradeDispatch,
+    PluginLatestItemOut,
+)
+from app.services.plugin_service import PluginService
+
+public_router = APIRouter()
+protected_router = APIRouter()
+admin_required_router = APIRouter()
+
+
+@admin_required_router.post(
+    "/plugins/publish",
+    summary="发布插件 / 上传新版本",
+    tags=["插件管理"],
+    response_model=ApiResponse[PluginPublishOut],
+)
+async def publish_plugin(
+    request: Request,
+    name: Optional[str] = Form(None),
+    version: Optional[str] = Form(None),
+    display_name: Optional[str] = Form(""),
+    description: Optional[str] = Form(""),
+    download_url: Optional[str] = Form(None),
+    sha256: Optional[str] = Form(""),
+    changelog: Optional[str] = Form(None),
+    set_as_latest: bool = Form(True),
+    file: Optional[UploadFile] = File(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    发布插件或上传新版本:
+    - 支持 multipart/form-data(包含文件上传或表单字段)
+    - 支持 application/json(直接提供 download_url)
+    """
+    content_type = request.headers.get("content-type", "")
+    if "application/json" in content_type:
+        try:
+            body = await request.json()
+            name = body.get("name")
+            version = body.get("version")
+            display_name = body.get("display_name", "")
+            description = body.get("description", "")
+            download_url = body.get("download_url")
+            sha256 = body.get("sha256", "")
+            changelog = body.get("changelog")
+            set_as_latest = body.get("set_as_latest", True)
+        except Exception:
+            pass
+
+    res = await PluginService.publish_plugin(
+        db=db,
+        name=name,
+        version=version,
+        display_name=display_name,
+        description=description,
+        file=file,
+        download_url=download_url,
+        sha256=sha256,
+        changelog=changelog,
+        set_as_latest=set_as_latest,
+    )
+    return success(data=res, message="Plugin published successfully")
+
+
+@admin_required_router.get(
+    "/plugins/list_all",
+    summary="获取插件列表 (网页管理)",
+    tags=["插件管理"],
+    response_model=ApiResponse[PluginListResponse],
+)
+async def list_all_plugins(
+    page: int = Query(1, ge=1, description="页码"),
+    page_size: int = Query(20, ge=1, le=100, description="每页数量"),
+    status: Optional[int] = Query(None, description="状态过滤 (1-启用, 0-停用)"),
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.get_plugin_list(
+        db=db, page=page, page_size=page_size, status=status
+    )
+    return success(data=res)
+
+
+@admin_required_router.get(
+    "/plugins/detail",
+    summary="获取插件详情 (含历史所有版本)",
+    tags=["插件管理"],
+    response_model=ApiResponse[PluginDetailOut],
+)
+async def get_plugin_detail(
+    plugin_id: int = Query(..., description="插件ID"),
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.get_plugin_detail(db=db, plugin_id=plugin_id)
+    return success(data=res)
+
+
+@admin_required_router.put(
+    "/plugins/update",
+    summary="编辑插件基础信息",
+    tags=["插件管理"],
+    response_model=ApiResponse[PluginOut],
+)
+async def update_plugin(
+    plugin_id: int = Query(..., description="插件ID"),
+    plugin_in: PluginUpdate = Body(...),
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.update_plugin(
+        db=db, plugin_id=plugin_id, plugin_in=plugin_in
+    )
+    return success(data=res)
+
+
+@admin_required_router.post(
+    "/plugins/switch-version",
+    summary="切换生效版本 / 一键回滚",
+    tags=["插件管理"],
+    response_model=ApiResponse[PluginOut],
+)
+async def switch_plugin_version(
+    payload: PluginSwitchVersion = Body(...),
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.switch_version(
+        db=db, plugin_id=payload.plugin_id, version=payload.version
+    )
+    return success(data=res)
+
+
+@admin_required_router.delete(
+    "/plugins/delete",
+    summary="删除整套插件",
+    tags=["插件管理"],
+    response_model=ApiResponse[bool],
+)
+async def delete_plugin(
+    plugin_id: int = Query(..., description="插件ID"),
+    db: AsyncSession = Depends(get_db),
+):
+    await PluginService.delete_plugin(db=db, plugin_id=plugin_id)
+    return success(data=True, message="Plugin deleted successfully")
+
+
+@admin_required_router.delete(
+    "/plugins/delete_version",
+    summary="删除指定历史版本",
+    tags=["插件管理"],
+    response_model=ApiResponse[bool],
+)
+async def delete_plugin_version(
+    plugin_id: int = Query(..., description="插件ID"),
+    version: str = Query(..., description="版本号"),
+    db: AsyncSession = Depends(get_db),
+):
+    await PluginService.delete_version(db=db, plugin_id=plugin_id, version=version)
+    return success(data=True, message="Plugin version deleted successfully")
+
+
+@admin_required_router.post(
+    "/plugins/upgrade/dispatch",
+    summary="下发插件升级命令 (控制面与节点联动)",
+    tags=["插件管理"],
+    response_model=ApiResponse[List[Dict[str, Any]]],
+)
+async def dispatch_upgrade(
+    payload: PluginUpgradeDispatch = Body(...),
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.dispatch_upgrade(
+        db=db, target_node=payload.target_node, plugins=payload.plugins
+    )
+    return success(data=res)
+
+
+@admin_required_router.get(
+    "/plugins/latest",
+    summary="获取当前全量最新可用插件清单 (节点主动拉取)",
+    tags=["插件管理"],
+    response_model=ApiResponse[List[PluginLatestItemOut]],
+)
+async def get_latest_plugins(
+    db: AsyncSession = Depends(get_db),
+):
+    res = await PluginService.get_latest_plugins(db=db)
+    return success(data=res)

+ 2 - 0
app/api/router.py

@@ -9,6 +9,7 @@ from app.api.endpoints import (
     notification,
     notification,
     order,
     order,
     payment,
     payment,
+    plugin,
     product,
     product,
     proxy,
     proxy,
     slot,
     slot,
@@ -37,6 +38,7 @@ _modules = [
     notification,
     notification,
     order,
     order,
     payment,
     payment,
+    plugin,
     product,
     product,
     proxy,
     proxy,
     slot,
     slot,

+ 1 - 0
app/models/__init__.py

@@ -6,3 +6,4 @@ from .payment import VasPayment
 from .configuration import Configuration
 from .configuration import Configuration
 from .notification_outbox import NotificationOutbox
 from .notification_outbox import NotificationOutbox
 from .emails import VasEmail
 from .emails import VasEmail
+from .plugin import Plugin, PluginVersion

+ 34 - 0
app/models/plugin.py

@@ -0,0 +1,34 @@
+from datetime import datetime
+from sqlalchemy import Column, Integer, String, Text, SmallInteger, DateTime, UniqueConstraint, Index
+from app.core.database import Base
+
+
+class Plugin(Base):
+    __tablename__ = "plugins"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name = Column(String(64), unique=True, nullable=False, index=True)
+    display_name = Column(String(128), nullable=False, default="")
+    filename = Column(String(128), nullable=False, default="")
+    latest_version = Column(String(32), nullable=False, default="1.0.0")
+    description = Column(String(512), nullable=False, default="")
+    status = Column(SmallInteger, nullable=False, default=1, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+
+class PluginVersion(Base):
+    __tablename__ = "plugin_versions"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    plugin_id = Column(Integer, nullable=False, default=0, index=True)
+    plugin_name = Column(String(64), nullable=False, index=True)
+    version = Column(String(32), nullable=False)
+    download_url = Column(String(512), nullable=False)
+    sha256 = Column(String(64), nullable=False, default="")
+    changelog = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint("plugin_id", "version", name="uk_plugin_version"),
+    )

+ 95 - 0
app/schemas/plugin.py

@@ -0,0 +1,95 @@
+from typing import Optional, List
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class PluginPublishRequest(BaseModel):
+    name: str = Field(..., description="插件唯一英文标识,如: tls_plugin")
+    version: str = Field(..., description="版本号,如: 1.0.1")
+    display_name: Optional[str] = Field("", description="插件中文展示名")
+    description: Optional[str] = Field("", description="插件功能描述")
+    download_url: Optional[str] = Field(None, description="已有文件下载地址")
+    sha256: Optional[str] = Field("", description="文件 SHA256 校验和")
+    changelog: Optional[str] = Field(None, description="本次版本更新日志")
+    set_as_latest: bool = Field(True, description="是否立即将该版本设为插件最新版本")
+
+
+class PluginPublishOut(BaseModel):
+    plugin_id: int
+    name: str
+    version: str
+    download_url: str
+    sha256: str
+
+
+class PluginOut(BaseModel):
+    id: int
+    name: str
+    display_name: str
+    filename: str
+    latest_version: str
+    description: str
+    status: int
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+class PluginListResponse(BaseModel):
+    list: List[PluginOut]
+    total: int
+
+
+class PluginVersionOut(BaseModel):
+    id: int
+    version: str
+    download_url: str
+    sha256: str
+    changelog: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+class PluginDetailOut(BaseModel):
+    id: int
+    name: str
+    display_name: str
+    filename: str
+    latest_version: str
+    description: str
+    status: int
+    versions: List[PluginVersionOut] = []
+
+    class Config:
+        from_attributes = True
+
+
+class PluginUpdate(BaseModel):
+    display_name: Optional[str] = Field(None, description="插件展示名")
+    description: Optional[str] = Field(None, description="功能描述")
+    status: Optional[int] = Field(None, description="状态: 1-启用, 0-停用")
+
+
+class PluginSwitchVersion(BaseModel):
+    plugin_id: int = Field(..., description="插件ID")
+    version: str = Field(..., description="切换的目标版本号")
+
+
+class PluginUpgradeDispatch(BaseModel):
+    target_node: str = Field("all", description="'all' 表示全量广播,或指定特定节点 node_id 如 'node01'")
+    plugins: List[str] = Field(default_factory=list, description="指定升级的插件英文名列表;传空数组 [] 表示对所有启用的插件下发最新版")
+
+
+class PluginLatestItemOut(BaseModel):
+    name: str
+    display_name: str
+    filename: str
+    version: str
+    description: str
+    download_url: str
+    sha256: str
+    changelog: Optional[str] = None

+ 360 - 0
app/services/plugin_service.py

@@ -0,0 +1,360 @@
+import json
+import hashlib
+from typing import Optional, List, Dict, Any, Tuple
+from fastapi import UploadFile
+from sqlalchemy import select, func, delete
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.biz_exception import BizLogicError
+from app.core.redis import get_redis_client
+from app.core.logger import logger
+from app.models.plugin import Plugin, PluginVersion
+from app.schemas.plugin import PluginUpdate
+from app.services.seaweedfs_service import SeaweedFSService
+
+
+class PluginService:
+
+    @classmethod
+    async def publish_plugin(
+        cls,
+        db: AsyncSession,
+        name: str,
+        version: str,
+        display_name: Optional[str] = "",
+        description: Optional[str] = "",
+        file: Optional[UploadFile] = None,
+        download_url: Optional[str] = None,
+        sha256: Optional[str] = "",
+        changelog: Optional[str] = None,
+        set_as_latest: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        发布插件新版本:
+        1. 支持直接上传 .py 文件(通过 SeaweedFSService 存储并计算 sha256)或直接传入 download_url
+        2. 自动更新/创建 plugins 基础信息
+        3. 记录 plugin_versions 发布历史
+        """
+        if not name or not version:
+            raise BizLogicError("Plugin name and version are required")
+
+        final_download_url = download_url
+        final_sha256 = (sha256 or "").strip()
+
+        if file is not None and file.filename:
+            file_bytes = await file.read()
+            if not file_bytes:
+                raise BizLogicError("Uploaded file is empty")
+
+            final_sha256 = hashlib.sha256(file_bytes).hexdigest()
+            await file.seek(0)
+
+            # 上传至 SeaweedFS
+            upload_result = await SeaweedFSService.upload(file)
+            final_download_url = upload_result.get("url")
+            if not final_download_url:
+                raise BizLogicError("Failed to retrieve file download URL from storage")
+
+        if not final_download_url:
+            raise BizLogicError("Either file upload or download_url must be provided")
+
+        filename = f"{name}.py"
+
+        # 1. 查找或创建 Plugin 基础记录
+        stmt = select(Plugin).where(Plugin.name == name)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+
+        if plugin is None:
+            plugin = Plugin(
+                name=name,
+                display_name=display_name or name,
+                filename=filename,
+                latest_version=version,
+                description=description or "",
+                status=1,
+            )
+            db.add(plugin)
+            await db.flush()
+        else:
+            if display_name:
+                plugin.display_name = display_name
+            if description is not None and description != "":
+                plugin.description = description
+            plugin.filename = filename
+            if set_as_latest:
+                plugin.latest_version = version
+
+        # 2. 查找或创建 PluginVersion 历史版本记录
+        v_stmt = select(PluginVersion).where(
+            PluginVersion.plugin_id == plugin.id,
+            PluginVersion.version == version,
+        )
+        v_res = await db.execute(v_stmt)
+        pv = v_res.scalar_one_or_none()
+
+        if pv is None:
+            pv = PluginVersion(
+                plugin_id=plugin.id,
+                plugin_name=name,
+                version=version,
+                download_url=final_download_url,
+                sha256=final_sha256,
+                changelog=changelog,
+            )
+            db.add(pv)
+        else:
+            pv.download_url = final_download_url
+            pv.sha256 = final_sha256
+            if changelog is not None:
+                pv.changelog = changelog
+
+        if set_as_latest:
+            plugin.latest_version = version
+
+        await db.commit()
+        await db.refresh(plugin)
+        await db.refresh(pv)
+
+        return {
+            "plugin_id": plugin.id,
+            "name": plugin.name,
+            "version": pv.version,
+            "download_url": pv.download_url,
+            "sha256": pv.sha256,
+        }
+
+    @classmethod
+    async def get_plugin_list(
+        cls,
+        db: AsyncSession,
+        page: int = 1,
+        page_size: int = 20,
+        status: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """分页获取插件列表"""
+        query = select(Plugin)
+        count_query = select(func.count(Plugin.id))
+
+        if status is not None:
+            query = query.where(Plugin.status == status)
+            count_query = count_query.where(Plugin.status == status)
+
+        total_res = await db.execute(count_query)
+        total = total_res.scalar() or 0
+
+        query = query.order_by(Plugin.id.desc()).offset((page - 1) * page_size).limit(page_size)
+        res = await db.execute(query)
+        plugins = res.scalars().all()
+
+        return {
+            "list": plugins,
+            "total": total,
+        }
+
+    @classmethod
+    async def get_plugin_detail(cls, db: AsyncSession, plugin_id: int) -> Dict[str, Any]:
+        """获取单个插件详情(包含所有历史发布版本)"""
+        stmt = select(Plugin).where(Plugin.id == plugin_id)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+        if not plugin:
+            raise BizLogicError(f"Plugin with id {plugin_id} not found")
+
+        v_stmt = select(PluginVersion).where(
+            PluginVersion.plugin_id == plugin_id
+        ).order_by(PluginVersion.id.desc())
+        v_res = await db.execute(v_stmt)
+        versions = v_res.scalars().all()
+
+        return {
+            "id": plugin.id,
+            "name": plugin.name,
+            "display_name": plugin.display_name,
+            "filename": plugin.filename,
+            "latest_version": plugin.latest_version,
+            "description": plugin.description,
+            "status": plugin.status,
+            "versions": versions,
+        }
+
+    @classmethod
+    async def update_plugin(
+        cls,
+        db: AsyncSession,
+        plugin_id: int,
+        plugin_in: PluginUpdate,
+    ) -> Plugin:
+        """更新插件基础信息"""
+        stmt = select(Plugin).where(Plugin.id == plugin_id)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+        if not plugin:
+            raise BizLogicError(f"Plugin with id {plugin_id} not found")
+
+        if plugin_in.display_name is not None:
+            plugin.display_name = plugin_in.display_name
+        if plugin_in.description is not None:
+            plugin.description = plugin_in.description
+        if plugin_in.status is not None:
+            plugin.status = plugin_in.status
+
+        await db.commit()
+        await db.refresh(plugin)
+        return plugin
+
+    @classmethod
+    async def switch_version(
+        cls,
+        db: AsyncSession,
+        plugin_id: int,
+        version: str,
+    ) -> Plugin:
+        """切换插件的生效版本(一键回滚/切换推荐版本)"""
+        stmt = select(Plugin).where(Plugin.id == plugin_id)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+        if not plugin:
+            raise BizLogicError(f"Plugin with id {plugin_id} not found")
+
+        # 校验该版本是否存在
+        v_stmt = select(PluginVersion).where(
+            PluginVersion.plugin_id == plugin_id,
+            PluginVersion.version == version,
+        )
+        v_res = await db.execute(v_stmt)
+        pv = v_res.scalar_one_or_none()
+        if not pv:
+            raise BizLogicError(f"Version '{version}' does not exist for plugin '{plugin.name}'")
+
+        plugin.latest_version = version
+        await db.commit()
+        await db.refresh(plugin)
+        return plugin
+
+    @classmethod
+    async def delete_plugin(cls, db: AsyncSession, plugin_id: int) -> bool:
+        """删除整套插件及其所有版本记录"""
+        stmt = select(Plugin).where(Plugin.id == plugin_id)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+        if not plugin:
+            raise BizLogicError(f"Plugin with id {plugin_id} not found")
+
+        # 删除所有版本
+        await db.execute(
+            delete(PluginVersion).where(PluginVersion.plugin_id == plugin_id)
+        )
+        # 删除插件主体
+        await db.delete(plugin)
+        await db.commit()
+        return True
+
+    @classmethod
+    async def delete_version(cls, db: AsyncSession, plugin_id: int, version: str) -> bool:
+        """删除单个历史版本记录(禁止直接删除当前生效的 latest_version)"""
+        stmt = select(Plugin).where(Plugin.id == plugin_id)
+        res = await db.execute(stmt)
+        plugin = res.scalar_one_or_none()
+        if not plugin:
+            raise BizLogicError(f"Plugin with id {plugin_id} not found")
+
+        if plugin.latest_version == version:
+            raise BizLogicError(
+                f"Cannot delete active latest version '{version}'. Please switch to another version first."
+            )
+
+        v_stmt = select(PluginVersion).where(
+            PluginVersion.plugin_id == plugin_id,
+            PluginVersion.version == version,
+        )
+        v_res = await db.execute(v_stmt)
+        pv = v_res.scalar_one_or_none()
+        if not pv:
+            raise BizLogicError(f"Version '{version}' not found for plugin '{plugin.name}'")
+
+        await db.delete(pv)
+        await db.commit()
+        return True
+
+    @classmethod
+    async def dispatch_upgrade(
+        cls,
+        db: AsyncSession,
+        target_node: str = "all",
+        plugins: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        下发插件升级命令:
+        1. 组装指定插件(或所有已启用插件)的最新版本配置
+        2. 通过 Redis 发布到指定频道广播通知节点 Upgrade-Listener
+        """
+        query = select(Plugin).where(Plugin.status == 1)
+        if plugins and len(plugins) > 0:
+            query = query.where(Plugin.name.in_(plugins))
+
+        res = await db.execute(query)
+        target_plugins = res.scalars().all()
+
+        payload = []
+        for p in target_plugins:
+            # 获取对应的 latest_version 记录
+            v_stmt = select(PluginVersion).where(
+                PluginVersion.plugin_id == p.id,
+                PluginVersion.version == p.latest_version,
+            )
+            v_res = await db.execute(v_stmt)
+            pv = v_res.scalar_one_or_none()
+            if pv:
+                payload.append({
+                    "name": p.name,
+                    "filename": p.filename or f"{p.name}.py",
+                    "version": p.latest_version,
+                    "download_url": pv.download_url,
+                    "sha256": pv.sha256,
+                })
+
+        # 确定广播频道
+        if not target_node or target_node.strip() == "" or target_node == "all":
+            channel = "vs:channel:upgrade"
+        else:
+            channel = f"vs:channel:upgrade:{target_node.strip()}"
+
+        try:
+            redis_client = await get_redis_client()
+            await redis_client.publish(channel, json.dumps(payload))
+            logger.info(f"🚀 [Plugin Upgrade] Dispatched {len(payload)} plugins to Redis channel '{channel}'")
+        except Exception as e:
+            logger.error(f"❌ [Plugin Upgrade] Failed to publish upgrade to Redis: {e}", exc_info=True)
+            raise BizLogicError(f"Failed to publish upgrade notification to Redis: {str(e)}")
+
+        return payload
+
+    @classmethod
+    async def get_latest_plugins(cls, db: AsyncSession) -> List[Dict[str, Any]]:
+        """获取当前所有已启用的最新可用插件清单(供节点主动拉取)"""
+        stmt = select(Plugin).where(Plugin.status == 1).order_by(Plugin.id.asc())
+        res = await db.execute(stmt)
+        plugins = res.scalars().all()
+
+        result = []
+        for p in plugins:
+            v_stmt = select(PluginVersion).where(
+                PluginVersion.plugin_id == p.id,
+                PluginVersion.version == p.latest_version,
+            )
+            v_res = await db.execute(v_stmt)
+            pv = v_res.scalar_one_or_none()
+
+            result.append({
+                "name": p.name,
+                "display_name": p.display_name,
+                "filename": p.filename or f"{p.name}.py",
+                "version": p.latest_version,
+                "description": p.description,
+                "download_url": pv.download_url if pv else "",
+                "sha256": pv.sha256 if pv else "",
+                "changelog": pv.changelog if pv else "",
+            })
+
+        return result

+ 304 - 0
docs/plugin.md

@@ -0,0 +1,304 @@
+# 云端插件管理系统与 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) |

+ 222 - 0
tests/test_plugin_api.py

@@ -0,0 +1,222 @@
+# -*- coding: utf-8 -*-
+import pytest
+import pytest_asyncio
+from unittest.mock import AsyncMock, patch, MagicMock
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from fastapi.testclient import TestClient
+
+from app.core.database import Base, get_db
+from app.core.auth import get_current_user, require_min_role, RoleLevel
+from app.models.plugin import Plugin, PluginVersion
+from app.services.plugin_service import PluginService
+from app.schemas.plugin import PluginUpdate, PluginSwitchVersion, PluginUpgradeDispatch
+from app.core.biz_exception import BizLogicError
+from app.main import app
+
+# 使用 SQLite 内存数据库进行测试
+TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
+
+test_engine = create_async_engine(TEST_DATABASE_URL, echo=False)
+TestSessionLocal = async_sessionmaker(
+    bind=test_engine,
+    class_=AsyncSession,
+    autoflush=False,
+    expire_on_commit=False,
+)
+
+
+@pytest_asyncio.fixture(scope="function")
+async def async_db():
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async with TestSessionLocal() as session:
+        yield session
+
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+
+@pytest.mark.asyncio
+async def test_plugin_publish_and_versions(async_db: AsyncSession):
+    # 1. 发布 1.0.0 版本
+    res1 = await PluginService.publish_plugin(
+        db=async_db,
+        name="tls_plugin",
+        version="1.0.0",
+        display_name="TLSContact 插件",
+        description="TLS 签证自动预约",
+        download_url="https://oss.example.com/plugins/tls_plugin-1.0.0.py",
+        sha256="hash100",
+        changelog="初始版本",
+        set_as_latest=True,
+    )
+    assert res1["name"] == "tls_plugin"
+    assert res1["version"] == "1.0.0"
+    assert res1["download_url"] == "https://oss.example.com/plugins/tls_plugin-1.0.0.py"
+
+    # 2. 发布 1.0.1 版本
+    res2 = await PluginService.publish_plugin(
+        db=async_db,
+        name="tls_plugin",
+        version="1.0.1",
+        display_name="TLSContact 插件更新版",
+        description="TLS 签证更新",
+        download_url="https://oss.example.com/plugins/tls_plugin-1.0.1.py",
+        sha256="hash101",
+        changelog="修复问题",
+        set_as_latest=True,
+    )
+    assert res2["version"] == "1.0.1"
+
+    # 3. 获取详情并验证版本列表
+    detail = await PluginService.get_plugin_detail(db=async_db, plugin_id=res1["plugin_id"])
+    assert detail["name"] == "tls_plugin"
+    assert detail["latest_version"] == "1.0.1"
+    assert len(detail["versions"]) == 2
+
+    # 4. 获取列表
+    list_res = await PluginService.get_plugin_list(db=async_db, page=1, page_size=10)
+    assert list_res["total"] == 1
+    assert list_res["list"][0].latest_version == "1.0.1"
+
+
+@pytest.mark.asyncio
+async def test_plugin_switch_version_and_delete_protection(async_db: AsyncSession):
+    # 发布 1.0.0 和 1.0.1
+    p = await PluginService.publish_plugin(
+        db=async_db,
+        name="bls_plugin",
+        version="1.0.0",
+        download_url="https://oss.example.com/bls-1.0.0.py",
+        sha256="h1",
+    )
+    plugin_id = p["plugin_id"]
+
+    await PluginService.publish_plugin(
+        db=async_db,
+        name="bls_plugin",
+        version="1.0.1",
+        download_url="https://oss.example.com/bls-1.0.1.py",
+        sha256="h2",
+        set_as_latest=True,
+    )
+
+    # 尝试删除当前生效版本 1.0.1 -> 应该报错被阻止
+    with pytest.raises(BizLogicError) as exc_info:
+        await PluginService.delete_version(db=async_db, plugin_id=plugin_id, version="1.0.1")
+    assert "Cannot delete active latest version" in str(exc_info.value)
+
+    # 切换生效版本回退到 1.0.0
+    switched = await PluginService.switch_version(db=async_db, plugin_id=plugin_id, version="1.0.0")
+    assert switched.latest_version == "1.0.0"
+
+    # 此时允许删除 1.0.1
+    deleted = await PluginService.delete_version(db=async_db, plugin_id=plugin_id, version="1.0.1")
+    assert deleted is True
+
+    # 验证版本仅剩 1.0.0
+    detail = await PluginService.get_plugin_detail(db=async_db, plugin_id=plugin_id)
+    assert len(detail["versions"]) == 1
+    assert detail["versions"][0].version == "1.0.0"
+
+
+@pytest.mark.asyncio
+async def test_plugin_upgrade_dispatch_and_latest(async_db: AsyncSession):
+    await PluginService.publish_plugin(
+        db=async_db,
+        name="vfs_plugin",
+        version="2.0.0",
+        display_name="VFS 插件",
+        download_url="https://oss.example.com/vfs-2.0.0.py",
+        sha256="sha_vfs",
+    )
+
+    # 模拟 Redis Client
+    mock_redis = AsyncMock()
+    with patch("app.services.plugin_service.get_redis_client", return_value=mock_redis):
+        # 广播给全部节点
+        payload = await PluginService.dispatch_upgrade(db=async_db, target_node="all", plugins=["vfs_plugin"])
+        assert len(payload) == 1
+        assert payload[0]["name"] == "vfs_plugin"
+        assert payload[0]["version"] == "2.0.0"
+        mock_redis.publish.assert_called_once()
+        args, _ = mock_redis.publish.call_args
+        assert args[0] == "vs:channel:upgrade"
+
+    # 节点主动拉取最新插件
+    latest_list = await PluginService.get_latest_plugins(db=async_db)
+    assert len(latest_list) == 1
+    assert latest_list[0]["name"] == "vfs_plugin"
+    assert latest_list[0]["version"] == "2.0.0"
+
+
+class DummyAdminUser:
+    id = 1
+    role = "admin"
+
+
+@pytest.fixture
+def test_client():
+    async def override_get_db():
+        async with TestSessionLocal() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = override_get_db
+    app.dependency_overrides[get_current_user] = lambda: DummyAdminUser()
+    app.dependency_overrides[require_min_role(RoleLevel.admin)] = lambda: DummyAdminUser()
+
+    with TestClient(app) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+
+
+def test_plugin_api_http_endpoints(test_client):
+    import asyncio
+    async def setup_db():
+        async with test_engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+    asyncio.run(setup_db())
+
+    # 1. POST /api/plugins/publish (JSON 格式)
+    resp = test_client.post("/api/plugins/publish", json={
+        "name": "tls_plugin",
+        "version": "1.0.0",
+        "display_name": "TLS 签证插件",
+        "download_url": "https://oss.example.com/tls.py",
+        "sha256": "abc123sha",
+        "changelog": "init",
+        "set_as_latest": True
+    })
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["code"] == 0
+    plugin_id = data["data"]["plugin_id"]
+
+    # 2. GET /api/plugins/list_all
+    resp = test_client.get("/api/plugins/list_all")
+    assert resp.status_code == 200
+    assert resp.json()["data"]["total"] == 1
+
+    # 3. GET /api/plugins/detail
+    resp = test_client.get(f"/api/plugins/detail?plugin_id={plugin_id}")
+    assert resp.status_code == 200
+    assert resp.json()["data"]["name"] == "tls_plugin"
+
+    # 4. PUT /api/plugins/update
+    resp = test_client.put(f"/api/plugins/update?plugin_id={plugin_id}", json={
+        "display_name": "TLS 签证插件 (修改版)"
+    })
+    assert resp.status_code == 200
+    assert resp.json()["data"]["display_name"] == "TLS 签证插件 (修改版)"
+
+    # 5. GET /api/plugins/latest
+    resp = test_client.get("/api/plugins/latest")
+    assert resp.status_code == 200
+    assert len(resp.json()["data"]) == 1
+
+    # 6. DELETE /api/plugins/delete
+    resp = test_client.delete(f"/api/plugins/delete?plugin_id={plugin_id}")
+    assert resp.status_code == 200
+    assert resp.json()["data"] is True

+ 158 - 0
tests/test_plugin_manual.py

@@ -0,0 +1,158 @@
+import asyncio
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+from fastapi.testclient import TestClient
+
+from app.core.auth import get_current_user, require_min_role, RoleLevel
+from app.core.database import get_db
+from app.models.plugin import Plugin, PluginVersion
+from app.schemas.plugin import (
+    PluginPublishRequest,
+    PluginPublishOut,
+    PluginOut,
+    PluginListResponse,
+    PluginDetailOut,
+    PluginUpdate,
+    PluginSwitchVersion,
+    PluginUpgradeDispatch,
+    PluginLatestItemOut,
+)
+from app.services.plugin_service import PluginService
+from app.main import app
+
+
+class DummyAdminUser:
+    id = 1
+    role = "admin"
+
+
+async def test_plugin_service():
+    print("Testing PluginService logic...")
+
+    # Mock AsyncSession
+    mock_db = AsyncMock()
+
+    # 1. Test publish_plugin
+    mock_plugin = Plugin(
+        id=1,
+        name="tls_plugin",
+        display_name="TLSContact 插件",
+        filename="tls_plugin.py",
+        latest_version="1.0.0",
+        description="TLS 签证自动预约",
+        status=1,
+    )
+    mock_version = PluginVersion(
+        id=1,
+        plugin_id=1,
+        plugin_name="tls_plugin",
+        version="1.0.0",
+        download_url="https://oss.example.com/plugins/tls_plugin-1.0.0.py",
+        sha256="abcsha256",
+        changelog="初始版本",
+    )
+
+    mock_execute_plugin_res = MagicMock()
+    mock_execute_plugin_res.scalar_one_or_none.return_value = None
+
+    mock_execute_version_res = MagicMock()
+    mock_execute_version_res.scalar_one_or_none.return_value = None
+
+    mock_db.execute.side_effect = [mock_execute_plugin_res, mock_execute_version_res]
+
+    res = await PluginService.publish_plugin(
+        db=mock_db,
+        name="tls_plugin",
+        version="1.0.0",
+        display_name="TLSContact 插件",
+        description="TLS 签证自动预约",
+        download_url="https://oss.example.com/plugins/tls_plugin-1.0.0.py",
+        sha256="abcsha256",
+        changelog="初始版本",
+    )
+    assert res["name"] == "tls_plugin"
+    assert res["version"] == "1.0.0"
+    print("✓ publish_plugin passed")
+
+    # 2. Test switch_version
+    mock_db.execute.side_effect = None
+    mock_execute_p = MagicMock()
+    mock_execute_p.scalar_one_or_none.return_value = mock_plugin
+    mock_execute_v = MagicMock()
+    mock_execute_v.scalar_one_or_none.return_value = mock_version
+    mock_db.execute.side_effect = [mock_execute_p, mock_execute_v]
+
+    switched = await PluginService.switch_version(mock_db, plugin_id=1, version="1.0.0")
+    assert switched.latest_version == "1.0.0"
+    print("✓ switch_version passed")
+
+    # 3. Test delete_version protection for latest_version
+    mock_db.execute.side_effect = None
+    mock_execute_p = MagicMock()
+    mock_execute_p.scalar_one_or_none.return_value = mock_plugin
+    mock_db.execute.return_value = mock_execute_p
+
+    try:
+        await PluginService.delete_version(mock_db, plugin_id=1, version="1.0.0")
+        assert False, "Should have raised BizLogicError"
+    except Exception as e:
+        assert "Cannot delete active latest version" in str(e)
+        print("✓ delete_version latest version protection passed")
+
+    # 4. Test dispatch_upgrade with Redis
+    mock_redis = AsyncMock()
+    mock_plugin_list_res = MagicMock()
+    mock_plugin_list_res.scalars.return_value.all.return_value = [mock_plugin]
+    mock_v_res = MagicMock()
+    mock_v_res.scalar_one_or_none.return_value = mock_version
+    mock_db.execute.side_effect = [mock_plugin_list_res, mock_v_res]
+
+    with patch("app.services.plugin_service.get_redis_client", return_value=mock_redis):
+        payload = await PluginService.dispatch_upgrade(mock_db, target_node="all", plugins=["tls_plugin"])
+        assert len(payload) == 1
+        assert payload[0]["name"] == "tls_plugin"
+        mock_redis.publish.assert_called_once()
+        print("✓ dispatch_upgrade with Redis passed")
+
+    # 5. Test get_latest_plugins
+    mock_db.execute.side_effect = [mock_plugin_list_res, mock_v_res]
+    latest = await PluginService.get_latest_plugins(mock_db)
+    assert len(latest) == 1
+    assert latest[0]["name"] == "tls_plugin"
+    assert latest[0]["download_url"] == "https://oss.example.com/plugins/tls_plugin-1.0.0.py"
+    print("✓ get_latest_plugins passed")
+
+
+def test_http_routes():
+    print("Testing HTTP routes registration...")
+    app.dependency_overrides[require_min_role(RoleLevel.admin)] = lambda: DummyAdminUser()
+    app.dependency_overrides[get_current_user] = lambda: DummyAdminUser()
+
+    client = TestClient(app)
+    # Check openapi contains all plugin routes
+    openapi = app.openapi()
+    paths = openapi["paths"]
+    
+    expected_endpoints = [
+        "/api/plugins/publish",
+        "/api/plugins/list_all",
+        "/api/plugins/detail",
+        "/api/plugins/update",
+        "/api/plugins/switch-version",
+        "/api/plugins/delete",
+        "/api/plugins/delete_version",
+        "/api/plugins/upgrade/dispatch",
+        "/api/plugins/latest",
+    ]
+
+    for ep in expected_endpoints:
+        assert ep in paths, f"Missing endpoint in OpenAPI: {ep}"
+        print(f"✓ Found endpoint {ep}")
+
+    print("All HTTP routes properly registered in FastAPI router!")
+
+
+if __name__ == "__main__":
+    asyncio.run(test_plugin_service())
+    test_http_routes()
+    print("\n🎉 ALL TESTS PASSED!")