NocoBase 迁移管理插件（Migration Manager）实战指南：跨环境应用配置迁移-平芜编程栈

NocoBase 迁移管理插件（Migration Manager）实战指南：跨环境应用配置迁移

【免费下载链接】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 的迁移管理插件（@nocobase/plugin-migration-manager）用于将应用配置从一个环境（例如 Staging）迁移到另一个环境（例如 PROD），是运维管理中衔接开发、预发布与生产环境的关键工具。通过本指南，你将掌握迁移管理与备份管理的区别、三种内置迁移规则（仅结构/覆盖/跳过）的取舍、迁移文件的生成与执行、执行前的环境变量与插件检测，以及基于蓝绿切换的推荐部署流程和完整的回滚方案。

迁移管理是什么

迁移管理插件用于将应用配置从一个环境（例如 Staging）迁移到另一个环境（例如 PROD）。它的核心处理对象是主数据库中的数据表与数据，根据预设的迁移规则，从一个应用迁移至另一个应用。

与备份管理的核心区别

NocoBase 将"备份还原"与"迁移"设计为两套互补的机制，切勿混淆：

机制	侧重点
迁移管理	侧重于迁移特定的应用配置、数据表结构或部分数据，用于跨环境发布
备份管理器	侧重于全量数据的备份与还原，用于灾难恢复与状态回退

从仓库实现看，两者分别由不同的插件承载：迁移管理依赖备份管理插件（备份管理文档），因为执行迁移前系统会自动创建备份，迁移失败时可借助备份还原快速回退（详见下文"回滚"章节）。备份管理器插件（@nocobase/plugin-backups）提供了数据库及用户上传文件的全量备份、定时备份、下载、删除及还原等功能。

安装与依赖

迁移管理插件依赖备份管理插件（@nocobase/plugin-backups），使用前请确保备份管理插件已经安装并激活。

另外，备份管理器依赖对应主数据库的数据库客户端（如pg_dump、mysqldump），使用 Docker 安装 NocoBase 时，推荐使用对应版本的full镜像（例如latest-full、beta-full、alpha-full），这类镜像已内置常用数据库客户端。如果当前环境缺少数据库客户端，可在storage/scripts目录下编写安装脚本（具体安装脚本示例见备份管理文档）。

流程与原理

迁移的核心流程是：

在源环境（如 Staging）中新建迁移，选择迁移规则并生成迁移文件；
将迁移文件带到目标环境（如 PROD）；
在目标环境中执行迁移，按规则同步数据表结构与数据；
查看迁移日志与执行过程，必要时进行回滚。

重要的范围限制：迁移管理只处理主数据库的数据表及数据，不迁移外部数据库和子应用的数据。如果你的应用配置了外部数据源（如外部 MySQL/PostgreSQL）或使用了多应用（子应用）能力，这部分数据不会被迁移，需要另行规划同步方案。

迁移规则

迁移规则决定了某个数据表在迁移时的处理方式，是迁移管理最核心的配置项。

三种内置规则

规则	行为
仅结构	只同步数据表结构，不涉及数据的插入或更新
覆盖（清空并重新插入）	清空现有表记录，然后插入新数据；同时也会同步表结构的变化
跳过	对该表不做任何处理

规则选择的实践建议

用户自定义业务数据表通常选择"仅结构"：客户、订单、工单、审批记录、消息、日志等运行数据应避免覆盖生产环境中的记录，只把表结构带过去，数据留待生产环境自行积累；
承载业务配置、分类、模板、规则等元数据的自定义表，如果这些记录需要随发布从开发环境同步到预发布或生产环境，可以根据业务场景选择"覆盖"；
内置的系统表大多按默认策略处理即可，多数情况下用户不需要逐表调整。详细的默认策略清单见应用和主要插件内置表。

配置界面

在迁移管理的配置界面中，可以为每个数据表指定迁移规则：

配置迁移规则：为表设置默认的迁移策略（仅结构 / 覆盖 / 跳过），如需了解默认策略对应的数据表，参考应用和主要插件内置表；
启用独立规则：在默认策略之外，为特定表启用独立的迁移规则；
选择独立规则以及按当前独立规则处理的数据表：可以精确指定哪些表使用哪种独立规则，实现"大部分表仅结构、个别配置表覆盖"的精细化控制。

迁移文件

迁移文件是迁移的载体，通常以.nbdata为扩展名（例如命令行示例中的migration_1775658568158.nbdata），它记录了迁移规则与相关数据。

新建迁移

在迁移管理界面中点击"新建迁移"，选择需要包含的数据表与迁移规则，系统将生成对应的迁移文件。

执行迁移

选择迁移文件后执行迁移，执行过程中系统会做两项关键的前置检测：

环境变量检测

执行迁移前会进行应用环境变量检测（关于环境变量的说明参见变量与密钥）。如果.env中的以下变量在源环境与目标环境之间不一致，系统会弹窗提示无法继续迁移：

DB_UNDERSCORED
USE_DB_SCHEMA_IN_SUBAPP
DB_TABLE_PREFIX
DB_SCHEMA
COLLECTION_MANAGER_SCHEMA

这与备份管理器的还原限制逻辑相互印证——备份管理文档明确规定，当数据库类型（dialect）、字段配置（underscored）、表前缀（table prefix）、表结构（schema）不一致时不允许执行还原。这些参数直接决定表名、字段名和 schema 的物理形态，跨环境不一致会导致迁移出的表结构与目标环境无法对应。

如果缺失动态配置的环境变量或密钥，系统同样会弹窗提示，此时需要在弹窗中填写需要新增的环境变量或密钥，然后继续迁移。

插件检测

执行迁移前会进行应用插件检测：如果当前环境缺少迁移文件涉及到的插件，系统会弹窗提示。与环境变量检测不同，插件缺失时可以选择继续迁移，但需要注意后续功能可能不完整。

迁移日志与存储

执行完迁移后，服务器上会保存执行日志文件，可以在线查看或下载：

在线查看执行日志：查看迁移的完整执行过程；
下载 SQL：在线查看执行日志时，还可以下载迁移数据结构时执行的 SQL，便于审计或在目标环境手动复核；
查看执行过程：点击"过程"按钮可以查看已完成迁移的执行过程详情。

关于`storage`目录

迁移管理主要处理数据库记录。storage目录中的部分数据（如日志、备份历史、请求日志等）不会被自动迁移。如果需要在新环境保留这些文件，你需要手动拷贝storage目录下的相关文件夹。

回滚

迁移管理内置了回滚保障：执行迁移前，系统会自动创建备份，这是回滚的前提。

回滚原则

停止服务：在开始回滚前停止应用，防止新的数据写入；
版本匹配：NocoBase 内核版本（Docker 镜像）必须与备份文件生成时的版本一致；
全新环境还原：如果当前数据库或存储已损坏，仅还原镜像版本可能不够，最稳妥的做法是在全新的应用实例（新数据库和存储）中使用正确的内核镜像还原备份。

回滚流程

场景 A：迁移任务执行失败

如果仅是迁移任务执行出错，但内核版本未变，请直接使用备份管理器还原迁移前自动创建的备份即可。

场景 B：系统损坏或内核升级失败

如果升级或迁移导致系统无法运行，需要回滚到稳定状态：

停止应用：停止当前的容器服务；
准备全新环境：准备一个新的空库和空存储环境；
部署目标版本：将 Docker 镜像标签改回备份生成时的版本；
还原备份：在这个干净的环境中通过备份管理器执行还原；
切换流量：更新网关/负载均衡，将流量指向这个恢复后的全新实例。

命令行

迁移管理提供两个 CLI 命令，用于在无界面环境下生成与执行迁移。这两个命令通过 NocoBase CLI（nocobase）调用，仓库中的命令定义可参见 CLI 命令实现。

`yarn nocobase migration generate`

生成迁移文件：

Usage: nocobase migration generate [options] Options: --title [title] migration title --ruleId <ruleId> migration rule id

参数说明：

--title：迁移标题，便于识别迁移文件用途；
--ruleId：迁移规则 ID（必填），对应配置界面中的迁移规则编号。

示例：

yarn nocobase migration generate --ruleId=1

`yarn nocobase migration run`

执行迁移文件：

Usage: nocobase migration run [options] <filePath> Arguments: filePath migration file path Options: --skip-backup skip backup --var [var] variable (default: []) --secret [secret] secret (default: [])

参数说明：

filePath：迁移文件的路径（必填）；
--skip-backup：跳过迁移前的自动备份（默认情况下执行迁移前会自动创建备份）；
--var：以--var 键=值的形式传入普通变量，可重复传入多个；
--secret：以--secret 键=值的形式传入密钥，可重复传入多个。

示例：

yarn nocobase migration run /your/path/migration_1775658568158.nbdata \ && --var A=a --var B=b \ && --secret C=c --secret D=d

内置表参考

迁移管理、版本控制、备份还原三类机制关注点不同，内置表的默认策略也已预置。核心规律是：

系统基础数据（如collections、fields、uiSchemas、roles、workflows等）：迁移默认策略为覆盖，参与版本控制，参与备份；
业务运行数据（如users、attachments、auditTrails、executions等）：迁移默认策略为仅结构，不参与版本控制，参与备份；
运行态临时数据（如 AI 对话检查点lcCheckpoints等）：迁移默认策略为仅结构，不参与版本控制，不备份。

以下是几个典型内置表的默认策略示例（完整清单见应用和主要插件内置表）：

数据表	说明	迁移管理默认策略
`collections`/`fields`	业务集合及字段的元配置	覆盖
`uiSchemas`	页面与区块的 JSON 布局描述	覆盖
`roles`/`rolesResources`	权限角色及资源授权	覆盖
`workflows`/`flow_nodes`	工作流定义与节点	覆盖
`users`	登录账号与资料	仅结构
`attachments`	文件附件元数据	仅结构
`auditTrails`	审计日志	仅结构
`migrationRules`	迁移管理自身的规则配置	仅结构

用户自定义表默认按业务数据处理，多数情况下只需要迁移表结构，选择仅结构即可。

最佳实践

数据一致性与停机维护

目前 NocoBase不支持零停机迁移。为了避免备份或迁移过程中产生数据不一致：

关闭网关/入口：强烈建议在开始备份或迁移前停止用户访问。你可以通过 Nginx 或网关配置503 维护页面，向用户提示系统正在维护中，并防止新的数据写入；
手动数据同步：如果在迁移期间用户继续在旧版本中产生数据，这些数据需要后续手动同步。

小结

迁移管理插件将"跨环境发布配置"这一高频运维需求产品化：通过仅结构/覆盖/跳过三种规则精确控制每个数据表的迁移行为，通过环境变量与插件检测在迁移前拦截配置不一致，通过自动备份与版本匹配原则保障回滚安全，并通过蓝绿切换实现近乎无损的发布流程。结合内置表参考理解默认策略、结合备份管理文档理解备份还原机制，即可构建一套完整的应用配置发布与回退体系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

NocoBase 迁移管理插件（Migration Manager）实战指南：跨环境应用配置迁移