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_UNDERSCOREDUSE_DB_SCHEMA_IN_SUBAPPDB_TABLE_PREFIXDB_SCHEMACOLLECTION_MANAGER_SCHEMA这与备份管理器的还原限制逻辑相互印证——备份管理文档明确规定当数据库类型dialect、字段配置underscored、表前缀table prefix、表结构schema不一致时不允许执行还原。这些参数直接决定表名、字段名和 schema 的物理形态跨环境不一致会导致迁移出的表结构与目标环境无法对应。如果缺失动态配置的环境变量或密钥系统同样会弹窗提示此时需要在弹窗中填写需要新增的环境变量或密钥然后继续迁移。插件检测执行迁移前会进行应用插件检测如果当前环境缺少迁移文件涉及到的插件系统会弹窗提示。与环境变量检测不同插件缺失时可以选择继续迁移但需要注意后续功能可能不完整。迁移日志与存储执行完迁移后服务器上会保存执行日志文件可以在线查看或下载在线查看执行日志查看迁移的完整执行过程下载 SQL在线查看执行日志时还可以下载迁移数据结构时执行的 SQL便于审计或在目标环境手动复核查看执行过程点击过程按钮可以查看已完成迁移的执行过程详情。关于storage目录迁移管理主要处理数据库记录。storage目录中的部分数据如日志、备份历史、请求日志等不会被自动迁移。如果需要在新环境保留这些文件你需要手动拷贝storage目录下的相关文件夹。回滚迁移管理内置了回滚保障执行迁移前系统会自动创建备份这是回滚的前提。回滚原则停止服务在开始回滚前停止应用防止新的数据写入版本匹配NocoBase 内核版本Docker 镜像必须与备份文件生成时的版本一致全新环境还原如果当前数据库或存储已损坏仅还原镜像版本可能不够最稳妥的做法是在全新的应用实例新数据库和存储中使用正确的内核镜像还原备份。回滚流程场景 A迁移任务执行失败如果仅是迁移任务执行出错但内核版本未变请直接使用备份管理器还原迁移前自动创建的备份即可。场景 B系统损坏或内核升级失败如果升级或迁移导致系统无法运行需要回滚到稳定状态停止应用停止当前的容器服务准备全新环境准备一个新的空库和空存储环境部署目标版本将 Docker 镜像标签改回备份生成时的版本还原备份在这个干净的环境中通过备份管理器执行还原切换流量更新网关/负载均衡将流量指向这个恢复后的全新实例。命令行迁移管理提供两个 CLI 命令用于在无界面环境下生成与执行迁移。这两个命令通过 NocoBase CLInocobase调用仓库中的命令定义可参见 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 --ruleId1yarn 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 Aa --var Bb \ --secret Cc --secret Dd内置表参考迁移管理、版本控制、备份还原三类机制关注点不同内置表的默认策略也已预置。核心规律是系统基础数据如collections、fields、uiSchemas、roles、workflows等迁移默认策略为覆盖参与版本控制参与备份业务运行数据如users、attachments、auditTrails、executions等迁移默认策略为仅结构不参与版本控制参与备份运行态临时数据如 AI 对话检查点lcCheckpoints等迁移默认策略为仅结构不参与版本控制不备份。以下是几个典型内置表的默认策略示例完整清单见应用和主要插件内置表数据表说明迁移管理默认策略collections/fields业务集合及字段的元配置覆盖uiSchemas页面与区块的 JSON 布局描述覆盖roles/rolesResources权限角色及资源授权覆盖workflows/flow_nodes工作流定义与节点覆盖users登录账号与资料仅结构attachments文件附件元数据仅结构auditTrails审计日志仅结构migrationRules迁移管理自身的规则配置仅结构用户自定义表默认按业务数据处理多数情况下只需要迁移表结构选择仅结构即可。最佳实践推荐部署流程蓝绿切换为了确保零停机或极短停机时间并获得最高安全性建议使用双环境切换方案准备阶段Staging在 Staging 环境中创建迁移文件安全备份PROD-A为当前生产环境PROD-A创建全量备份并行部署PROD-B部署一个全新的、空库的生产实例PROD-B使用目标内核版本还原与迁移将 PROD-A 的备份还原到 PROD-B在 PROD-B 中执行来自 Staging 的迁移文件验证在 PROD-A 仍在服务的过程中对 PROD-B 进行详尽测试切换流量更新 Nginx/网关将流量从 PROD-A 指向 PROD-B如遇问题可瞬间切回 PROD-A。这种方案的核心价值在于迁移全程在全新实例 PROD-B 上进行生产环境 PROD-A 始终在线迁移失败时只需将流量切回 PROD-A 即可风险可控。数据一致性与停机维护目前 NocoBase不支持零停机迁移。为了避免备份或迁移过程中产生数据不一致关闭网关/入口强烈建议在开始备份或迁移前停止用户访问。你可以通过 Nginx 或网关配置503 维护页面向用户提示系统正在维护中并防止新的数据写入手动数据同步如果在迁移期间用户继续在旧版本中产生数据这些数据需要后续手动同步。小结迁移管理插件将跨环境发布配置这一高频运维需求产品化通过仅结构/覆盖/跳过三种规则精确控制每个数据表的迁移行为通过环境变量与插件检测在迁移前拦截配置不一致通过自动备份与版本匹配原则保障回滚安全并通过蓝绿切换实现近乎无损的发布流程。结合内置表参考理解默认策略、结合备份管理文档理解备份还原机制即可构建一套完整的应用配置发布与回退体系。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考