企业官网建设流程全解析

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文件是两套机制，使用场景不同：

例如文件存储服务在开发与生产环境可以配置不同的值：

# 开发环境 FILE_STORAGE_OSS_BASE_URL=dev-storage.nocobase.com FILE_STORAGE_OSS_BUCKET=dev-storage # 生产环境 FILE_STORAGE_OSS_BASE_URL=prod-storage.nocobase.com FILE_STORAGE_OSS_BUCKET=prod-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），分别安装 PostgreSQL（postgresql-client-16）或 MySQL（mysqldump、mysql），然后执行docker compose restart app并查看日志确认版本；
• 验证命令：PostgreSQL 用docker compose exec app bash -c "pg_dump -V"，MySQL 用docker compose exec app bash -c "mysql -V"，客户端版本必须与数据库服务端版本一致。

核心功能包括：

• 新建备份：根据备份配置创建，列表中显示备份状态；
• 还原备份：支持从备份列表还原、上传本地备份文件还原。以下场景不允许还原：当前 NocoBase 版本低于备份文件中的版本；数据库类型（dialect）、underscored 字段配置、表前缀（table prefix）、schema 表结构不一致；未开启容错模式且创建备份时数据库版本高于当前应用数据库版本；
• 下载 / 删除备份：列表内一键操作。

备份设置项：

备份还原均为数据库全量操作，推荐在备份还原前先备份一份当前数据库。未加密备份文件还原时无需输入密码；需要将备份还原至低版本数据库时需开启容错模式。

发布执行：用迁移管理将配置迁移到目标环境

迁移管理插件（对应@nocobase/plugin-migration-manager）用于将应用配置从一个环境（如 Staging）迁移到另一个环境（如 PROD），处理的是主数据库的数据表及数据。详细说明见 迁移管理。

常见迁移内容包括：应用配置、数据表结构、插件配置，以及部分需要迁移的数据。推荐先发布到预发布环境：迁移文件在预发布环境验证通过后，再用于生产发布。

发布到预发布环境

从开发环境生成迁移文件后，先在预发布环境执行。预发布环境应尽量接近生产环境，包括内核版本、插件版本、变量、密钥、权限配置和外部系统连接方式。执行后验证核心页面、权限规则、工作流和外部系统集成。

预发布验证通过后，应保留同一份迁移文件用于生产发布。不要在发布到生产前临时修改迁移文件。需要调整时，回到开发环境重新生成，并重新经过预发布验证。

发布到生产环境

生产发布应安排维护窗口：

1. 开始前通知用户维护时间，并停止用户访问或切换维护页，避免迁移期间产生新的业务数据；
2. 集群或多节点部署场景下，迁移前应先将应用缩容为一个节点；
3. 确认发布前备份完成后，再执行已在预发布环境验证过的迁移文件；
4. 迁移完成后，先验证核心业务流程，再恢复用户访问；多节点部署场景下，验证通过后再恢复节点数量。

迁移文件、备份和执行日志会分别保存在对应功能中。团队内部的发布记录可补充发布时间、执行人、验证结果和备份信息，方便后续排查和回滚。

迁移规则：覆盖、仅结构、跳过

迁移规则决定目标环境中数据表和记录如何处理，目前内置三种规则：

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

配置规则时，应先区分应用和插件内置表与用户自定义表，再选择处理方式：

• 应用和插件内置表通常按默认策略处理，选择覆盖优先。例如页面、菜单、区块、权限、工作流等应用配置，发布时通常以开发环境中的配置为准，同步到预发布和生产环境。默认策略对应的数据表清单见 应用和主要插件内置表；
• 用户自定义表需要按业务用途判断：承载真实业务数据的表（客户、订单、工单、审批记录、消息、日志等）通常只迁移表结构，选择仅结构，避免覆盖生产环境中持续产生的数据；部分用于承载配置、分类、模板、规则等元数据的表，可以根据实际业务场景选择覆盖。

迁移管理主要处理主数据库中的应用配置和数据。外部数据源、子应用数据和部分存储目录内容（如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 --ruleId=1

# 执行迁移文件 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 A=a --var B=b \ --secret C=c --secret D=d

注意migration run默认会先自动创建备份（--skip-backup可跳过），这为回滚提供了自动兜底。

回滚与恢复

发布失败时，优先通过备份管理插件使用发布前备份恢复。执行还原前，先确认备份文件可用，并根据界面提示完成还原操作。

根据失败场景选择恢复路径：

• 场景 A：迁移任务执行失败（内核版本未变）：如果当前生产环境仍可正常进入备份管理，且只是迁移执行失败，可以直接在当前环境中还原迁移前自动创建的备份（执行迁移前，系统会自动创建备份）。恢复完成后，应记录失败原因和处理结果，避免后续发布重复触发同类问题；
• 场景 B：系统损坏或内核升级失败：如果升级或迁移导致系统无法运行，或希望降低在故障环境中反复修复的风险，应准备独立环境并还原发布前备份：
  1. 停止应用：停止当前的容器服务，防止新的数据写入；
  2. 准备全新环境：准备一个新的空库和空存储环境；
  3. 部署目标版本：将 Docker 镜像标签改回备份生成时的版本——NocoBase 内核版本（Docker 镜像）必须与备份文件生成时的版本一致；
  4. 还原备份：在这个干净的环境中通过备份管理执行还原；
  5. 验证与切换：先验证核心业务流程，再更新网关/负载均衡，将流量切换到恢复后的实例。

最佳实践：蓝绿切换发布流程

为获得最高安全性并尽量缩短停机时间，迁移管理文档推荐双环境切换（蓝绿）方案：

1. 准备阶段（Staging）：在 Staging 环境中创建迁移文件；
2. 安全备份（PROD-A）：为当前生产环境（PROD-A）创建全量备份；
3. 并行部署（PROD-B）：部署一个全新的、空库的生产实例（PROD-B），使用目标内核版本；
4. 还原与迁移：将 PROD-A 的备份还原到 PROD-B，再在 PROD-B 中执行来自 Staging 的迁移文件；
5. 验证：在 PROD-A 仍在服务的过程中，对 PROD-B 进行详尽测试；
6. 切换流量：更新 Nginx/网关，将流量从 PROD-A 指向 PROD-B；如遇问题，可瞬间切回 PROD-A。

数据一致性与停机维护

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

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

总结：一份可落地的发布检查清单

将以上内容收敛为发布执行前的检查清单：

1. 环境配置：数据库连接、API Key、Webhook 等均已通过变量与密钥引用，未硬编码在页面或工作流中；
2. 开发节点：关键配置调整已通过版本控制记录，版本描述写明业务含义；
3. 模块边界：多应用场景下已确认各应用的独立发布链路与公共能力规划；
4. 恢复能力：发布前备份已完成且可访问，重要发布已在独立环境验证备份可还原，备份覆盖数据库、上传文件与运行所需存储；
5. 迁移验证：同一份迁移文件已在预发布环境验证通过，迁移规则已区分内置表（覆盖优先）与业务数据表（仅结构）；
6. 生产执行：已安排维护窗口、通知用户、停止写入，多节点已缩容，发布后验证核心流程再恢复访问；
7. 回滚预案：明确迁移失败（场景 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