mmsAdmin

简体中文

English

简体中文

English

主题

JAR 插件宿主 ​

在不修改管理端主工程源码的前提下，将符合约定的 插件 JAR 放到指定目录（或通过页面上传），由 插件宿主 在进程内加载并调用插件提供的 SPI（如启动初始化、健康检查）。管理端提供 状态、列表、安装、重载 等运维能力（需超级管理员权限）。

白话理解

可以把 插件宿主 想成：mms-admin 启动时去磁盘上「逛一圈」，按约定目录加载 JAR，在同一个 Java 进程里跑你的 SPI；需要运维时看 /system/pluginHost/* 接口或管理端插件市场。不会自动帮你把插件里的 @Controller 注册成 Spring MVC，详见下文「能力边界」。

新手从哪读起

建议顺序：① JAR 开发指南 — 第 0 节（闭环与排障） → ② 本文（配置、目录、HTTP） → ③ 再回到 JAR 开发指南 从第 1 节起写自己的插件。进阶前端配合见 JAR 插件路由协议。若后端还没跑起来，先看 项目导入与启动。

适合做什么

  • 独立交付能力包（算法、同步任务、监听、第三方 SDK 封装等），以 JAR 形式安装、升级。
  • 与 JAR 开发指南 配合：开发契约、打包与目录约定；第一次从 0 跑通示例（术语、install API、闭环排障）请直接看该文 0. 第一次写插件。

能做什么 ​

能力说明
按需加载mms.plugin.enabled=true 且配置好根目录后，应用就绪时扫描磁盘上的插件目录，按 plugin.json 校验并加载。
目录隔离每个插件每个版本独立目录：lib（JAR）、data（运行数据）、tmp（临时），宿主会创建 data / tmp。
HTTP 运维status / manifests / health 查看配置与已加载插件；install 上传单个 JAR 并触发重载；reload 全量重新扫描。
管理界面超级管理员菜单进入插件市场页，查看状态与健康、上传安装（具体路径以当前 mms-ui 为准）。
前端元数据已加载插件的 manifest 可包含 frontend 等字段，供前端展示协议约定见 JAR 插件路由协议。

能力边界 ​

请注意

  • 插件 不会 自动注册 Spring MVC 映射；@Controller、@Autowired 不会在插件 JAR 内按 Spring 方式生效。
  • 热重载受类加载器与 JVM 限制；安装或升级后重启应用仍是最稳妥方式。
  • 使用 Redis、数据库 等请见 JAR 开发指南 中 「与宿主 Redis、数据库」 小节。

开启与配置 ​

在 mms-admin 的配置（如 application.yml）中设置 mms.plugin，与仓库中实际片段合并即可：

yaml
mms:
  plugin:
    enabled: true
    root-dir: ${user.home}/mms/plugins
    host-mms-revision: ${revision}
配置项含义
enabled是否启用宿主；为 false 时不扫描、不加载。
root-dir插件根目录；若目录不存在，宿主会在启动或扫描前 自动创建（路径为文件等异常情况除外）。具体默认值以主仓 application*.yml 为准。
host-mms-revision与根 pom 的 revision 一致，用于校验插件内 plugin.json 的 requiresMms。

磁盘目录约定 ​

每个 插件 id、每个 版本 各占一层目录，其下 lib 中放置一个或多个 JAR（须至少有一个 JAR 内含 META-INF/mms/plugin.json）：

text
<root-dir>/
  <pluginId>/
    <version>/
      lib/
        your-plugin.jar      # 须含 META-INF/mms/plugin.json（或根目录 plugin.json）
        extra-dependency.jar # 可选，与主插件同属一个类加载器
      data/
      tmp/
  • pluginId / version 目录名与 plugin.json 中字段对应；特殊字符会经宿主安全化，详见 JAR 开发指南。
  • data、tmp 由宿主确保存在，供插件写入运行期数据。

HTTP 接口（超级管理员） ​

以下接口均需 super_admin（及主工程实际鉴权方式，如 Sa-Token 请求头）。

方法路径说明
GET/system/pluginHost/status当前配置与已加载插件列表
GET/system/pluginHost/manifests已加载插件 manifest（与 plugin.json 字段对齐，含 frontend 等）
GET/system/pluginHost/health聚合各插件健康检查 SPI 的返回
POST/system/pluginHost/installmultipart/form-data，表单字段 file，单个 .jar；写入约定目录后触发全量重载
POST/system/pluginHost/reload卸载后重新扫描并加载（生产环境请谨慎，重大变更建议 重启应用）
命令行调用示例（curl）

将 BASE 换成服务根地址，将鉴权头换成你环境中的 token（示例为 Bearer）：

bash
curl -sS "${BASE}/system/pluginHost/status" -H "Authorization: Bearer <token>"

curl -sS "${BASE}/system/pluginHost/health" -H "Authorization: Bearer <token>"
bash
curl -sS -X POST "${BASE}/system/pluginHost/install" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/your-plugin.jar"

curl -sS -X POST "${BASE}/system/pluginHost/reload" \
  -H "Authorization: Bearer <token>"

:::

示例 JAR 的构建 ​

主仓提供示例模块 mms-plugins/mms-plugin-sample-health，在仓库根目录执行：

bash
cd /path/to/mms
mvn -pl mms-plugins/mms-plugin-sample-health -am package -DskipTests

将生成的 JAR 放入对应版本的 lib/，或在管理端使用 安装 接口/页面上传。

管理端菜单（超级管理员） ​

若需在菜单中出现「插件市场」等入口，可执行主仓增量 SQL（若路径已存在则跳过）：

  • mms/script/db/increment_20260331_plugin_market_menu.sql（sys_function 与角色菜单关联，通常绑定 role_id='1'）

契约与 SPI（查阅） ​

  • 描述文件：META-INF/mms/plugin.json（示例见主仓 mms-plugin-api 内 META-INF/mms/plugin.example.json）。
  • 入口 SPI：META-INF/services/com.sxpcwlkj.plugin.MmsPlugin
  • 可选健康检查：META-INF/services/com.sxpcwlkj.plugin.PluginHealthContributor

开发、打包、与宿主 Redis/库的关系等，见 JAR 开发指南。

延伸阅读 ​

Released under the MIT License.

Copyright © 2021-present 品创网络 · XiJue