插件使用指南

本页面向平台运营者和租户管理员，说明插件从平台安装到租户使用的完整流程。

平台安装插件

平台后台进入「插件管理」，可以选择两种来源：

来源	场景	操作
上传插件包	第三方或外部交付插件	上传 zip，系统校验后安装
登记内置插件	插件已随源码放入 server/plugins/{code}	输入插件 code，登记并安装

安装时系统会执行：

1. 校验 plugin.json、插件 code、依赖和兼容版本。
2. 检查 zip 路径安全，拒绝绝对路径和 ../。
3. 写入插件记录，备份插件包。
4. 执行插件迁移。
5. 执行生命周期 install()。
6. 同步租户侧菜单和权限。
7. 创建平台端或租户端前端构建任务。

插件市场

如果配置了官方插件市场，平台可以：

• 发起 OAuth 连接。
• 同步插件目录、版本、兼容性和授权状态。
• 创建安装意图。
• 下载并校验插件包。
• 安装或升级兼容版本。

插件市场安装仍然会进入同一套本地安装流程，最终由本系统校验 manifest、执行迁移和同步菜单权限。

套餐授权

插件安装后，不代表所有租户都能使用。平台需要进入「套餐管理」，把插件授权到套餐。

配置	说明
授权插件	当前套餐可使用的插件列表
自动启用	租户订阅套餐后自动拥有该插件权益
单独购买	租户可在套餐外购买插件并获得独立有效期

插件授权不替代 RBAC。即使租户已启用插件，租户管理员仍需要给角色分配对应菜单和按钮权限。

租户启用插件

租户后台进入「插件应用」，可以看到当前套餐授权或历史启用过的插件。

插件状态通常包括：

• 未启用：套餐已授权，但租户尚未启用。
• 已启用：租户可以访问插件能力。
• 已禁用：租户主动关闭，配置和数据默认保留。
• 已过期：单独购买插件到期或套餐不再授权。

启用 kind=app 插件后，插件菜单会进入租户侧边栏。启用 kind=plugin 后，通常会出现配置面板，或被其他业务模块调用。

升级与卸载

平台升级插件时会按版本执行迁移和生命周期逻辑。升级前建议先备份数据库和插件目录。

卸载默认是软卸载：

• 插件全局状态失效。
• 租户不再能访问插件入口。
• 插件业务数据默认保留。
• 迁移文件和 manifest 会保留快照，便于后续彻底清理。

需要删除业务数据时，再执行插件清理流程。

使用检查

插件安装后租户仍看不到时，按顺序检查：

1. 插件是否处于已安装、已启用状态。
2. 租户当前套餐是否授权该插件。
3. 插件授权是否自动启用，或租户是否已手动启用。
4. 租户生命周期是否为 trial 或 active。
5. 租户角色是否分配了插件菜单和按钮权限。
6. 前端插件源码是否已同步并完成构建。