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 运维管理文档体系系统讲解如何将应用从开发环境安全地发布到生产环境。你将掌握发布管理的五类核心能力版本控制、变量与密钥、多应用、备份管理、迁移管理的职责划分与配合方式学会通过迁移规则覆盖/仅结构/跳过精确控制发布内容并掌握发布前备份、维护窗口、回滚恢复等生产级发布流程最终形成一套可重复、可验证、可回退的发布机制。发布管理概述发布管理用于规范应用从开发到生产的交付过程。它关注的不是单次操作而是一套可重复、可验证、可回退的发布机制。生产环境应保持稳定配置变更先在开发环境完成再进入预发布环境验证验证通过后才发布到生产环境。发布过程中产生的迁移文件、备份、执行日志和验证结果都应妥善保存作为后续排查和回滚的依据。推荐的环境链路如下开发环境 - 预发布环境 - 生产环境开发环境用于配置和调整允许频繁变更预发布环境用于还原生产约束并验证发布结果尽量贴近生产生产环境用于承载真实业务保持稳定优先。三类环境职责清晰后发布过程才容易管理。发布模型五类能力的分工与配合NocoBase 的发布管理通常由五类能力配合完成它们的职责划分决定了发布链路的可靠性能力解决的问题使用阶段版本控制保存开发过程中的关键节点为配置调整提供回退点开发阶段变量与密钥隔离不同环境的配置和敏感信息开发、预发布与生产发布多应用按业务模块拆分系统边界降低模块之间的发布影响架构规划与团队协作备份管理保存生产可恢复状态为发布失败和日常故障提供恢复依据发布前与日常容灾迁移管理将配置和结构变更发布到目标环境预发布与生产发布需要特别区分两类易混淆的能力迁移管理侧重于迁移特定的应用配置、数据表结构或部分数据备份管理对应nocobase/plugin-backups侧重于全量数据的备份与还原。前者解决变更怎么过去后者解决状态怎么回来。环境配置使用变量与密钥隔离环境变量与密钥用于隔离不同环境的配置和敏感信息。开发、预发布和生产环境应使用各自的变量和密钥。详细说明见 变量与密钥。开发阶段就应提前识别环境相关配置。数据库连接、第三方服务地址、测试账号、访问令牌、API Key、Webhook 地址等不应直接写死在页面、工作流或插件配置中应尽量通过变量与密钥引用。这样迁移到预发布或生产环境时只需要根据提示补充目标环境缺失的配置避免把生产密钥写入迁移内容。变量与密钥的两种存储方式动态配置的变量与密钥与项目根目录的.env文件是两套机制使用场景不同特性.env文件动态配置的变量和密钥存储位置项目根目录的.env文件数据库environmentVariables表加载方式dotenv等工具在应用启动时加载到process.env动态读取应用启动时加载到app.environment修改方式编辑文件修改后需重启应用运行时修改修改后直接重载应用配置环境隔离每个环境单独维护.env文件每个环境单独维护environmentVariables表数据适用场景固定静态配置如主数据库信息频繁调整或与业务逻辑绑定的动态配置如外部数据库、文件存储例如文件存储服务在开发与生产环境可以配置不同的值# 开发环境 FILE_STORAGE_OSS_BASE_URLdev-storage.nocobase.com FILE_STORAGE_OSS_BUCKETdev-storage # 生产环境 FILE_STORAGE_OSS_BASE_URLprod-storage.nocobase.com FILE_STORAGE_OSS_BUCKETprod-storage环境变量管理界面支持单个和批量添加支持明文和加密两种存储方式。两点注意事项重启应用修改或删除环境变量后顶部会出现重启应用的提示重启之后变更才会生效加密存储加密数据使用 AES 对称加密加解密密钥存放在./storage/environment-variables/app-name/aes_key.dat请妥善保管丢失或重写后加密数据将无法解密。从迁移管理的内置表清单见 应用和主要插件内置表可以看出environmentVariables表在迁移管理中的默认策略是仅结构即只迁移变量名这类结构信息不迁移具体密钥值——这正是避免把生产密钥写入迁移内容的底层设计保证。开发阶段用版本控制记录可恢复节点开发阶段变化频繁适合使用版本控制保存关键节点对应nocobase/plugin-version-control。一次较大的配置调整开始前可以先创建版本数据模型、页面、权限、工作流或插件配置调整完成后再创建一个新版本。详细说明见 版本控制。版本描述应写清楚本次变更的业务含义例如调整客户跟进页面和字段权限新增工单升级工作流优化资产领用审批流程描述越明确后续验证、对比和恢复越容易。版本控制的实操要点AI 自动保存版本启用版本控制插件后AI 搭建AI Builder在处理需求时会检查可用的 NocoBase Skills识别到nocobase-revisionskill 后会在完成一段可独立确认的成果搭好一个页面、创建一组数据表、配置完一条工作流时通过 NocoBase CLI 执行nb revision create自动创建版本入口顶部导航栏版本控制菜单或系统设置 / 版本控制默认快捷键Ctrl K可在设置页修改创建版本点击创建版本输入描述最多 2000 字符后保存。版本名由系统自动生成保存时列表先出现保存中记录完成后显示版本名、描述、文件大小、创建时间、创建人管理与恢复支持刷新、删除单个或批量、恢复。恢复会覆盖当前应用配置状态及版本中包含的数据内容恢复前建议先创建当前版本以便随时回退恢复期间应用短暂进入维护状态不要重复提交恢复操作设置版本策略Versions to keep保留版本数量上限超出自动删除较早版本、Shortcut: create version快捷键按Ctrl 字母键设置Backspace清除、User collections选择哪些用户创建的数据表纳入版本。默认情况下版本不包含用户自定义数据表内容选中某表后系统会把与之存在关系的数据表一并纳入恢复更完整。版本控制主要服务于开发过程适合撤销一次配置调整或保留阶段性成果。进入发布阶段后配置变更应通过迁移管理同步到目标环境生产环境需要恢复时应使用备份管理。注意社区版和标准版不包含版本控制插件。如需保存可回退的应用状态可以在关键变更前手动创建备份需要回退时再还原对应备份。模块拆分用多应用控制发布边界系统规模较小时可以从单应用开始——部署简单适合原型验证、小型内部系统和早期项目。当业务复杂度上升后单个应用会承载越来越多页面、数据表、权限和工作流一次配置变更可能影响多个团队一次发布也可能牵动多个模块此时应考虑使用多应用拆分业务边界。详细说明见 多应用管理。多应用适合按业务职责拆分例如 CRM、工单、资产、HR、报表、运营后台。每个应用可以独立开发、测试、发布和回滚。高频变更模块、高风险模块、面向不同用户群体的模块通常更适合独立出来。拆分前需要先规划公共能力。用户、组织、认证、权限和跨应用共享数据都会影响后续发布方式。边界越清晰发布影响范围越容易控制。拆分后的发布链路通常如下CRM 应用开发环境 - 预发布环境 - 生产环境 工单应用开发环境 - 预发布环境 - 生产环境 资产应用开发环境 - 预发布环境 - 生产环境发布前准备确认恢复能力备份是生产发布的安全底线。生产环境发布前应创建发布前备份重要发布还应先在独立环境验证备份可还原。详细说明见 备份管理。两类备份用途不同都应纳入生产运维策略日常定时备份应对误操作、数据损坏和基础设施故障发布前备份用于发布失败后的快速恢复。发布前需要确认备份任务已完成备份文件可下载或可访问重要发布在独立环境中做一次恢复验证确认备份可以正常还原。备份应覆盖数据库、用户上传文件以及应用运行所需的存储内容——只记录数据库不足以覆盖完整恢复场景。备份管理的使用基础备份管理插件nocobase/plugin-backups依赖对应主数据库的数据库客户端使用 Docker 安装 NocoBase 时推荐使用对应版本的full镜像如latest-full、beta-full、alpha-full已内置常用数据库客户端如环境缺少客户端可在./storage/scripts目录编写安装脚本如install-database-client.sh分别安装 PostgreSQLpostgresql-client-16或 MySQLmysqldump、mysql然后执行docker compose restart app并查看日志确认版本验证命令PostgreSQL 用docker compose exec app bash -c pg_dump -VMySQL 用docker compose exec app bash -c mysql -V客户端版本必须与数据库服务端版本一致。核心功能包括新建备份根据备份配置创建列表中显示备份状态还原备份支持从备份列表还原、上传本地备份文件还原。以下场景不允许还原当前 NocoBase 版本低于备份文件中的版本数据库类型dialect、underscored 字段配置、表前缀table prefix、schema 表结构不一致未开启容错模式且创建备份时数据库版本高于当前应用数据库版本下载 / 删除备份列表内一键操作。备份设置项设置项说明自动备份开启根据 Cron 运行自动备份后按指定时间自动备份最大备份数本地最大保存数量超出后自动删除最早的备份文件同步备份文件至云存储备份成功后自动上传到指定云存储备份本地存储文件是否把用户上传到storage/uploads的文件包含在备份中还原密码设置后恢复备份需输入该密码请妥善保管遗忘将无法还原备份还原均为数据库全量操作推荐在备份还原前先备份一份当前数据库。未加密备份文件还原时无需输入密码需要将备份还原至低版本数据库时需开启容错模式。发布执行用迁移管理将配置迁移到目标环境迁移管理插件对应nocobase/plugin-migration-manager用于将应用配置从一个环境如 Staging迁移到另一个环境如 PROD处理的是主数据库的数据表及数据。详细说明见 迁移管理。常见迁移内容包括应用配置、数据表结构、插件配置以及部分需要迁移的数据。推荐先发布到预发布环境迁移文件在预发布环境验证通过后再用于生产发布。发布到预发布环境从开发环境生成迁移文件后先在预发布环境执行。预发布环境应尽量接近生产环境包括内核版本、插件版本、变量、密钥、权限配置和外部系统连接方式。执行后验证核心页面、权限规则、工作流和外部系统集成。预发布验证通过后应保留同一份迁移文件用于生产发布。不要在发布到生产前临时修改迁移文件。需要调整时回到开发环境重新生成并重新经过预发布验证。发布到生产环境生产发布应安排维护窗口开始前通知用户维护时间并停止用户访问或切换维护页避免迁移期间产生新的业务数据集群或多节点部署场景下迁移前应先将应用缩容为一个节点确认发布前备份完成后再执行已在预发布环境验证过的迁移文件迁移完成后先验证核心业务流程再恢复用户访问多节点部署场景下验证通过后再恢复节点数量。迁移文件、备份和执行日志会分别保存在对应功能中。团队内部的发布记录可补充发布时间、执行人、验证结果和备份信息方便后续排查和回滚。迁移规则覆盖、仅结构、跳过迁移规则决定目标环境中数据表和记录如何处理目前内置三种规则仅结构只同步数据表结构不涉及数据的插入或更新覆盖清空并重新插入清空现有表记录然后插入新数据覆盖也会同步表结构的变化跳过对该表不做任何处理。配置规则时应先区分应用和插件内置表与用户自定义表再选择处理方式应用和插件内置表通常按默认策略处理选择覆盖优先。例如页面、菜单、区块、权限、工作流等应用配置发布时通常以开发环境中的配置为准同步到预发布和生产环境。默认策略对应的数据表清单见 应用和主要插件内置表用户自定义表需要按业务用途判断承载真实业务数据的表客户、订单、工单、审批记录、消息、日志等通常只迁移表结构选择仅结构避免覆盖生产环境中持续产生的数据部分用于承载配置、分类、模板、规则等元数据的表可以根据实际业务场景选择覆盖。迁移管理主要处理主数据库中的应用配置和数据。外部数据源、子应用数据和部分存储目录内容如storage目录中的日志、备份历史、请求日志等不会自动迁移应根据实际情况单独处理——如需在新环境保留需要手动拷贝storage目录下的相关文件夹。执行迁移时的检测机制执行迁移时系统会做两类自动检测环境变量检测若.env中的DB_UNDERSCORED、USE_DB_SCHEMA_IN_SUBAPP、DB_TABLE_PREFIX、DB_SCHEMA、COLLECTION_MANAGER_SCHEMA不一致则会弹窗提示不能继续迁移若缺失动态配置的环境变量或密钥会提示在弹窗中填写新增的环境变量或密钥后再继续插件检测如果目标环境缺少迁移文件涉及的插件会弹窗提示此时也可以选择继续迁移。迁移日志与命令行执行完迁移后服务器上会保存执行日志文件支持在线查看或下载在线查看时还可以下载迁移数据结构时执行的 SQL点击过程按钮可查看已完成迁移的执行过程。迁移管理还提供命令行能力便于脚本化或 CI 集成# 生成迁移文件 yarn nocobase migration generate [options] # Options: # --title [title] migration title # --ruleId ruleId migration rule id # 示例 yarn nocobase migration generate --ruleId1# 执行迁移文件 yarn nocobase migration run [options] filePath # Arguments: # filePath migration file path # Options: # --skip-backup skip backup # --var [var] variable (default: []) # --secret [secret] secret (default: []) # 示例 yarn nocobase migration run /your/path/migration_1775658568158.nbdata \ --var Aa --var Bb \ --secret Cc --secret Dd注意migration run默认会先自动创建备份--skip-backup可跳过这为回滚提供了自动兜底。回滚与恢复发布失败时优先通过备份管理插件使用发布前备份恢复。执行还原前先确认备份文件可用并根据界面提示完成还原操作。根据失败场景选择恢复路径场景 A迁移任务执行失败内核版本未变如果当前生产环境仍可正常进入备份管理且只是迁移执行失败可以直接在当前环境中还原迁移前自动创建的备份执行迁移前系统会自动创建备份。恢复完成后应记录失败原因和处理结果避免后续发布重复触发同类问题场景 B系统损坏或内核升级失败如果升级或迁移导致系统无法运行或希望降低在故障环境中反复修复的风险应准备独立环境并还原发布前备份停止应用停止当前的容器服务防止新的数据写入准备全新环境准备一个新的空库和空存储环境部署目标版本将 Docker 镜像标签改回备份生成时的版本——NocoBase 内核版本Docker 镜像必须与备份文件生成时的版本一致还原备份在这个干净的环境中通过备份管理执行还原验证与切换先验证核心业务流程再更新网关/负载均衡将流量切换到恢复后的实例。最佳实践蓝绿切换发布流程为获得最高安全性并尽量缩短停机时间迁移管理文档推荐双环境切换蓝绿方案准备阶段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。数据一致性与停机维护目前 NocoBase不支持零停机迁移。为了避免备份或迁移过程中产生数据不一致关闭网关/入口强烈建议在开始备份或迁移前停止用户访问可通过 Nginx 或网关配置503 维护页面提示系统正在维护中并防止新的数据写入手动数据同步如果在迁移期间用户继续在旧版本中产生数据这些数据需要后续手动同步。总结一份可落地的发布检查清单将以上内容收敛为发布执行前的检查清单环境配置数据库连接、API Key、Webhook 等均已通过变量与密钥引用未硬编码在页面或工作流中开发节点关键配置调整已通过版本控制记录版本描述写明业务含义模块边界多应用场景下已确认各应用的独立发布链路与公共能力规划恢复能力发布前备份已完成且可访问重要发布已在独立环境验证备份可还原备份覆盖数据库、上传文件与运行所需存储迁移验证同一份迁移文件已在预发布环境验证通过迁移规则已区分内置表覆盖优先与业务数据表仅结构生产执行已安排维护窗口、通知用户、停止写入多节点已缩容发布后验证核心流程再恢复访问回滚预案明确迁移失败场景 A与系统损坏场景 B两种回滚路径内核版本与备份版本一致。相关文档变量与密钥版本控制多应用管理备份管理迁移管理应用和主要插件内置表【免费下载链接】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），仅供参考