配置、安装、升级与发布

本文介绍 BPMAX 插件从源码开发走向平台安装的完整生命周期，包括配置、打包、安装、升级、卸载和发布。

学习目标

理解插件配置文件的作用
理解平台安装、升级、卸载插件的执行流程
理解插件发布时需要关注的兼容性问题

插件配置文件

`config.json` 的职责

config.json 是插件的元信息入口，至少承担四个作用：

标识插件身份
提供展示信息
提供安装记录基础数据
作为打包产物的一部分随插件发布

一个可直接参考的最小示例如下：

{
  "name": "Task Integration",
  "en_name": "plugin_task_integration",
  "version": "1.2.0",
  "description": "外部任务集成插件"
}

基础字段建议

建议至少包含：

name
en_name
version
description

如果插件还存在依赖关系、适用范围或额外元信息，也应统一放在这里维护。

版本号与展示信息

版本号建议遵循稳定的递增规则。每次发布都应同步更新：

版本号
变更说明
与旧版本的兼容性说明

依赖插件与页面范围

如果插件依赖其他插件能力，或只在特定页面范围内生效，建议把这类限制写入配置，而不是散落在代码中。

安装流程

平台接收插件包

平台安装时接收的是插件打包产物，而不是开发中的源码目录。

解压与写入运行环境

安装后，平台会把插件产物中的前后端文件分别写入对应运行环境。

执行安装脚本

如果插件提供了安装脚本，平台会在安装阶段按约定执行。

安装脚本可以先保持极简：

export default class extends think.Service {
  async run() {
    think.logger.info('[plugin_task_integration] install');
    return true;
  }
}

写入插件记录

安装完成后，平台会记录插件的版本、描述和文件信息，用于后续展示、升级和卸载。

重载服务

安装完成并不等于立即生效。很多情况下仍需要通过平台重载机制使插件代码生效。

升级流程

与首次安装的区别

首次安装通常是新增插件记录；升级则是在已存在记录基础上更新文件和元数据。

已安装记录如何更新

升级时通常会更新：

插件版本
描述信息
文件内容
相关配置元数据

升级兼容性注意事项

升级最容易出问题的地方有三个：

新代码不兼容旧配置
新字段缺少默认值
历史数据缺少迁移

因此升级前要确认：

是否有配置结构变更
是否有数据库结构变更
是否需要补迁移脚本

如果有配置结构升级，可以明确给旧字段补默认值：

function normalizeConfig(config = {}) {
  return {
    enabled: Boolean(config.enabled),
    platform_id: config.platform_id || '',
    mapping_function: config.mapping_function || '',
    retry_limit: config.retry_limit ?? 3,
  };
}

涉及迁移脚本的创建、执行和开发阶段使用方式，统一见环境准备与开发模式中的 “migrations/ 怎么写”。

卸载流程

卸载脚本执行时机

如果插件提供了卸载脚本，平台通常会在卸载阶段先执行脚本，再移除文件和记录。

文件移除与记录处理

卸载时通常会处理两类内容：

插件写入的运行文件
插件在平台中的记录

是否保留历史数据

是否保留插件历史数据，应在设计阶段明确：

如果保留，需说明保留内容和恢复方式
如果删除，需说明删除范围和不可逆风险

发布流程

打包前检查项

发布前至少检查：

config.json 是否完整
版本号是否已更新
前后端是否能正常构建
安装脚本和卸载脚本是否可执行
迁移脚本是否齐全

产物结构建议

打包产物建议至少包含：

config.json
前端构建产物
后端构建产物
迁移脚本

一个常见的打包结构如下：

plugin_task_integration.zip
├── config.json
├── frontend/
│   └── dist/
├── server/
│   └── dist/
└── migrations/

版本发布建议

建议每次发布都保留以下信息：

插件版本号
变更摘要
兼容性说明
回滚建议

常见问题

安装成功但插件未生效

平台尚未完成重载
插件入口未正确注册
安装产物与当前平台版本不兼容

升级后功能异常

旧配置未兼容
默认值结构变更
迁移脚本缺失

卸载后仍残留配置或数据

卸载脚本未清理完整
数据本身设计为保留
插件外部资源未回收