NocoBase 版本控制插件：为系统搭建过程保存可恢复的版本快照-平芜编程栈

NocoBase 版本控制插件：为系统搭建过程保存可恢复的版本快照

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

NocoBase 的搭建过程涉及集合、字段、界面、插件等大量配置，一次误操作或一次失败的结构变更就可能让迭代多日的工作回到原点。版本控制（Version Control）插件的作用正是在搭建过程中为当前系统状态保存一份"版本快照"（revision），并在需要时恢复到指定版本。读完本文，你将了解该插件的定位与启用条件、如何通过 NocoBase CLI 的revision create命令创建可恢复的版本快照，以及该命令底层与插件之间的事件通信机制。

插件定位与默认状态

版本控制插件对应包名为@nocobase/plugin-version-control，其官方描述为：为 NocoBase 搭建过程保存当前版本快照，并在需要时恢复到指定版本。

从插件文档页 docs/docs/cn/plugins/@nocobase/plugin-version-control/index.md 的元信息可以确认它的几个关键属性：

适用版本：supportedVersions 为 2.x，即该插件面向 NocoBase 2.x 系列；
非内置插件：builtIn: false，它不会随基础系统自动存在，需要单独安装；
默认不启用：defaultEnabled: false，安装后仍需手动启用才能使用；
付费插件：isFree: false且editionLevel: 2，属于商业授权体系中的插件，可用性与所在环境的授权级别相关。

一个值得注意的事实是：在整个开源仓库中，packages/plugins/@nocobase/目录下并不存在plugin-version-control的源码目录——从仓库结构看，插件的服务端实现并未随开源代码发布，仓库中保留的是它的文档页，以及一个直接对接该插件的 CLI 命令。这也与该插件"付费、非内置"的定位相吻合。

通过 CLI 创建版本快照

创建版本快照的入口是 NocoBase CLI 的revision create命令，实现位于 packages/core/cli/src/commands/revision/create.ts。其命令摘要为"Save the current NocoBase build as a restorable revision"（将当前 NocoBase 搭建状态保存为一个可恢复的 revision）。

基本用法：

nb revision create "描述文字" # 指定目标环境时 nb revision create --env app1 "描述文字"

命令的参数与选项如下（均取自命令源码中的 Args 与 Flags 定义）：

参数 / 选项	类型	说明
`description`（位置参数）	string，必填	revision 的描述，最长 2000 字符，超长会直接报错
`--api-base-url`	string	NocoBase API 基础地址，例如`http://localhost:13000/api`
`-e, --env`	string	目标环境名，用于多环境部署场景
`--role`	string	角色覆盖，请求中以`X-Role`头发送
`-t, --token`	string	API key 覆盖，用于鉴权
`-y, --yes`	boolean	当`--env`指向与当前不同的环境时，自动跳过确认
`-j, --json-output`	boolean	直接打印原始 JSON 响应，便于脚本消费

命令的底层执行流程

revision create并不直接操作数据库，而是通过 HTTP API 与运行中的 NocoBase 实例协作。从源码可以看出完整的调用链：

参数校验：先检查description长度是否超过 2000 字符，超过则报错终止。
跨环境确认：若通过ensureCrossEnvConfirmed检测到--env指向的环境与当前环境不一致，且未提供--yes，会要求用户确认后再继续。
插件启用检查：命令先发起GET /pm:list?mode=summary请求拉取插件列表，在结果中查找packageName为@nocobase/plugin-version-control的条目。若该插件不存在或未启用，命令会直接报错，并提示先执行nb plugin enable @nocobase/plugin-version-control。
发布插件事件：检查通过后，命令向POST /app:publishEvent发送事件，请求体为：

{ "plugin": "plugin-version-control", "command": "revision.create", "payload": { "description": "描述文字" } }

结果输出：请求失败时会打印状态码与响应体；成功时默认输出Revision created successfully，使用-j时则输出完整的原始 JSON 响应。

从源码结构看，publishEvent是 NocoBase 中 CLI、多应用等外部入口向已启用插件投递指令的通用机制：CLI 只负责"投递事件"，真正执行快照创建的是版本控制插件侧监听revision.create事件的处理逻辑。这种解耦使得创建快照这一动作同时可以由 CLI 和系统内部调用，而插件是否可用完全由其启用状态决定。

使用前提与注意事项

必须先启用插件：由于defaultEnabled: false，revision create执行前插件必须处于启用状态，否则命令会在插件检查阶段失败并给出nb plugin enable ...的提示。
面向 2.x 版本：文档元信息声明 supportedVersions 为 2.x，实际使用前应确认当前部署的 NocoBase 版本在支持范围内。
付费属性：该插件isFree: false且editionLevel: 2，其安装与可用性受商业授权约束，且插件本体源码不在本开源仓库中，本文所述的插件内部行为以文档描述与 CLI 侧实现为准。
多环境场景：--env指向跨环境目标时务必谨慎，命令内置了确认机制（--yes可跳过），避免误操作到生产环境。