企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 工作流
• RPA
• 后端
• 前端
• 工具调用

本文基于 astron-agent 仓库中console/backend/hub模块的数据库迁移指南（db/migration/README.md），系统讲解该控制台后端使用 Flyway 管理 MySQL 数据库版本控制的完整方案：迁移脚本的命名规范、按功能拆分的脚本目录结构、Spring Boot 中 Flyway 的关键配置项及其环境变量开关，以及“新增一个迁移”的标准操作流程。读完本文，你可以直接参与 astron-agent 的表结构或初始化数据变更，并理解脚本在应用启动时如何被自动检测与执行。

1. 迁移体系总览：Flyway + Spring Boot 启动时自动执行

astron-agent 的控制台后端（Hub 服务）使用Flyway进行数据库版本控制和迁移，所有迁移脚本统一放在console/backend/hub/src/main/resources/db/migration/目录下。

从源码依赖看，该能力由两部分构成：

• 依赖声明：Hub 模块引入flyway-core与flyway-mysql（hub/pom.xml），版本号由父工程统一管理，当前为10.21.0（console/backend/pom.xml）。flyway-mysql说明迁移的目标数据库是 MySQL，与数据源配置一致——Hub 默认连接astron_console库，字符集utf8mb4、时区Asia/Shanghai（application.yml）。
• 触发机制：配置位于 Spring Boot 的spring.flyway命名空间下（application.yml）。由于启用的是 Spring Boot 的 Flyway 自动配置，应用启动时Flyway 会自动扫描迁移目录、比对历史表、并按版本号顺序执行尚未应用的脚本，无需人工跑 SQL。

完整的 Flyway 配置片段如下（摘自 application.yml）：

# Flyway database migration configuration flyway: enabled: ${FLYWAY_ENABLED:true} # Migration scripts location locations: classpath:db/migration # Baseline on migrate (for existing databases) baseline-on-migrate: true # Baseline version baseline-version: 1.0 # Encoding of SQL migration files encoding: UTF-8 # Validate migrations on startup validate-on-migrate: ${FLYWAY_VALIDATE_ON_MIGRATE:false} # Table name for tracking migrations table: flyway_schema_history # Allow out of order migrations out-of-order: false

逐项解读这些配置的含义：

这里有两个工程细节值得注意：

1. validate-on-migrate默认关闭。Flyway 会把已应用脚本的校验和写入flyway_schema_history，一旦校验开启且发现某个已应用脚本的内容被改动，启动即失败。该配置默认关闭正是对“不可变性原则”（见第 4 节）的容忍设计，但在生产排障时打开它有助于及时发现脚本被误改的问题。
2. baseline-version: 1.0与脚本版本号衔接。仓库中最早的脚本是V1.1__init_core.sql，正好是基线之后的第一个版本，两者是刻意配合的：新库从V1.1开始全量建表，旧库打1.0基线后同样从V1.1起补迁移。

2. 命名规范：V<Version>__<Description>.sql

Flyway 对迁移文件遵循严格的命名规范：

V<Version>__<Description>.sql

• V：前缀，表示版本化迁移（versioned migration），区别于可重复执行的R__脚本；
• Version：唯一版本号，如1.1、20230101，可用点或下划线作分隔符；
• __：双下划线分隔符（必须，单下划线会被 Flyway 拒绝）;
• Description：对变更的有意义描述，如init_core、add_user_table；
• .sql：文件扩展名。

指南给出的示例：

• V1.1__init_core.sql
• V1.12__insert_other_data.sql

在 astron-agent 的实际目录中，这套规范被严格贯彻，且描述部分采用小驼峰风格表达变更意图，前缀约定清晰：init_*表示建表、insert_*表示初始化数据、add_*表示新增表/字段/模板、update_*/fix_*/normalize_*/expand_*/repair_*表示修正类变更。例如 migration 目录 中的真实脚本（节选）：

• V1.27__add_skill_file_system.sql —— 新增 Skill 文件系统表skill_file；
• V1.30__add_workflow_automation.sql —— 工作流自动化相关表；
• V1.35__add_publish_approval.sql —— 发布审批相关表；
• V1.48__remove_legacy_tenant_credentials_from_workflows.sql —— 清理遗留数据。

从脚本命名可以直观读出每次变更的业务语义，这是该规范在团队协作中的主要价值：版本号决定执行顺序，描述决定可追溯性。

3. 当前目录结构：Schema 定义与数据初始化分层

指南指出，初始的schema.sql已按功能拆分为多个文件，分为两大组：

3.1 表结构定义（Schema Definition）

• V1.1__init_core.sql：核心系统表
• V1.2__init_enterprise.sql：企业相关表
• V1.3__init_space.sql：空间/群组相关表
• V1.4__init_bot.sql：机器人配置表
• V1.5__init_workflow.sql：工作流引擎表
• V1.6__init_model.sql：AI 模型相关表
• V1.7__init_knowledge.sql：知识库表
• V1.9__init_toolbox.sql：工具/插件表

可以看到初始化阶段按“核心 → 企业 → 空间 → 机器人 → 工作流 → 模型 → 知识库 → 工具箱”的领域顺序组织，这与 Hub 后端mybatis-plus类型别名覆盖entity包的组织方式相互呼应（application.yml 中type-aliases-package列出了 commons、hub、toolkit 三个实体包）。

以 V1.1__init_core.sql 为例，建表风格非常统一：

DROP TABLE IF EXISTS `agent_apply_record`; CREATE TABLE `agent_apply_record` ( `id` bigint NOT NULL AUTO_INCREMENT, `enterprise_id` bigint DEFAULT NULL COMMENT 'Enterprise team ID', `space_id` bigint DEFAULT NULL COMMENT 'Space ID', ... `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT 'Creation time', `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'Update time', PRIMARY KEY (`id`), KEY `enterprise_id_key` (`enterprise_id`) USING BTREE, ... ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Application records for joining space/enterprise';

从中可以提炼出 Hub 库的建表惯例：InnoDB +utf8mb4、每表自带create_time/update_time审计字段、常用外键关联列建KEY索引、表级与列级COMMENT齐全。这些约定保证了后续开发者写新迁移时能保持风格一致。

3.2 数据初始化（Data Initialization）

• V1.10__insert_permission_data.sql：权限数据
• V1.11__insert_template_data.sql：模板数据
• V1.12__insert_other_data.sql：其他初始化数据
• V1.13__insert_config_data.sql：配置数据
• V1.14__insert_config_data2.sql：额外配置数据

数据脚本集中在版本号 1.10 之后，与结构脚本（1.1～1.9）严格分离——这正是指南第 4 节“Schema 文件中不包含插入语句”原则的落地方式：CREATE TABLE一类 DDL 放init_*脚本，INSERT一类 DML 放insert_*脚本。

从实际内容看，数据脚本也遵循了可重复执行的设计。例如 V1.21__add_official_deepseek_models.sql 使用INSERT INTO model_common (...) SELECT ...形式做数据装配；而后期新增表脚本 V1.27__add_skill_file_system.sql 则采用CREATE TABLE IF NOT EXISTS。

需要说明的是，仓库当前实际脚本已超过指南列举的范围：目录中从V1.1一直编号到V1.46、V1.48（编号V1.47缺失，属于历史演进中保留的空隙），覆盖了 Skill 沙箱、Bot MCP 服务、Agent 记忆配置、知识库列扩容等后续特性。指南列出的 1.1～1.14 是“初始化期”结构，后续版本则持续按第 4 节的流程追加，本文的讲解以指南骨架为准、以仓库现状为佐证。

4. 如何新增一个迁移：四步操作

指南给出的标准流程如下，这里补充每步的注意事项：

第 1 步：在迁移目录创建新文件

文件必须创建在console/backend/hub/src/main/resources/db/migration/（即配置中locations: classpath:db/migration对应的包路径），否则 Spring Boot 启动时扫描不到。

第 2 步：使用下一个可用版本号命名

指南原文示例：如果最新的是V1.13，则新文件用V1.14。

按仓库当前状态执行该步骤：先列出 migration 目录，找到最大版本号（当前为V1.48），新文件应命名为V1.49__<描述>.sql。注意：

• 版本号必须严格递增，因为out-of-order: false决定了 Flyway 不会补跑低版本号的脚本；
• 双下划线__不能写错；
• 描述使用英文、小写、下划线分隔，语义上要能独立说明变更内容。

第 3 步：编写 SQL（DDL 或 DML）

按变更类型参考仓库中的既有范式：

• 新建表：参照 V1.27__add_skill_file_system.sql，用CREATE TABLE IF NOT EXISTS，保持 InnoDB/utf8mb4/审计字段/索引命名风格；

• 修改表/加列：参照 V1.15__fix_missing_alter.sql，该脚本即为典型的“修复遗漏的 ALTER”：

  ALTER TABLE rpa_user_assistant ADD user_name varchar(100) NULL COMMENT '用户名'; ALTER TABLE workflow ADD `type` INT NULL COMMENT '工作流类型'; ALTER TABLE workflow_version ADD advanced_config text NULL COMMENT '工作流高级配置';

  这类“补漏”脚本本身也印证了不可变性原则：发现旧脚本漏了字段，不改旧脚本，而是新开一个fix_*版本补齐；

• 初始化/装配数据：参照 V1.10__insert_permission_data.sql，权限数据按module+permission_key（形如SpaceController_createCorporateSpace_POST）逐条INSERT，与 Hub 端的权限注解体系对应。

第 4 步：重启应用

重启 Hub 服务后，Flyway 会自动检测并应用新迁移：它读取flyway_schema_history中已应用的最高版本，将高于该版本且未应用的新脚本按升序执行，执行成功后把版本号、描述、checksum 写入历史表。

由于FLYWAY_ENABLED默认为true，无需额外开启；只有显式设置FLYWAY_ENABLED=false的环境才会跳过迁移。

5. 注意事项：不可变性、幂等性与 Schema/数据分离

指南最后列出三条重要原则，结合仓库配置与脚本实况逐条说明：

5.1 不可变性（Immutability）

一旦迁移文件已应用到数据库（例如生产环境），切勿修改它；请创建一个新版本来进行更改或修复。

Flyway 以flyway_schema_history表中的 checksum 作为“脚本未被篡改”的证据（校验开关即validate-on-migrate）。修改已应用脚本会带来三类风险：checksum 不匹配导致校验失败、多人环境执行结果不一致、变更历史不可追溯。仓库中的 V1.15__fix_missing_alter.sql（修复遗漏字段）、V1.41__repair_memory_config_and_bot_type_defaults.sql（repair 类修正）都是“新增版本修复问题”原则的活例子。

5.2 幂等性（Idempotency）

指南建议编写幂等脚本，例如CREATE TABLE IF NOT EXISTS或存在性检查——虽然 Flyway 通过版本跟踪本身就不会重复执行已应用脚本，但幂等写法在以下场景仍有价值：

• 基线数据库（baseline-on-migrate: true）在打基线前可能存在部分表结构，防御性 DDL 能减少边界情况；
• 团队本地清库重跑、CI 环境重建等场景下，脚本自我约束能降低人为失误的影响。

仓库实践中两种风格并存：初始化期脚本V1.1使用DROP TABLE IF EXISTS + CREATE TABLE（面向全新库的全量重建），后续演进脚本普遍采用CREATE TABLE IF NOT EXISTS与增量ALTER。无论哪种写法，新增迁移时都应保持“脚本自洽、不依赖隐式执行顺序之外的假设”。

5.3 Schema 与数据分离

表结构定义（CREATE TABLE）与数据插入（INSERT）应分开存放，以获得更好的可维护性。

astron-agent 的目录结构正是这一原则的体现：V1.1～V1.9（init_*）只建表，V1.10～V1.14（insert_*）只灌数。好处在于：

• 建表脚本可以独立评审索引、字符集、约束等结构问题；
• 数据脚本可以独立控制种子数据体量与更新节奏（后续大量特性版本如V1.21（模型数据）、V1.23（节点模板）也都遵循“结构归结构、数据归数据”的追加方式）。

6. 小结：一条可复用的迁移工作流

把以上内容浓缩为 astron-agent Hub 后端的数据库变更工作流：

1. 变更需求确定后，在console/backend/hub/src/main/resources/db/migration/下新建V<下一版本号>__<snake_case 描述>.sql；
2. 按类型选择仓库中的既有范式：init_*/add_*建新表（CREATE TABLE IF NOT EXISTS，保持 utf8mb4 + 审计字段 + 索引命名风格），fix_*/repair_*/expand_*做修正（增量ALTER），insert_*做数据装配（显式INSERT或INSERT ... SELECT）；
3. 不修改任何已发布脚本，所有修正一律开新版本；
4. 重启 Hub 服务，Flyway 依spring.flyway配置自动按升序执行新脚本，并将执行记录写入flyway_schema_history；
5. 如需排查“脚本是否被改过”，可临时设置FLYWAY_VALIDATE_ON_MIGRATE=true打开 checksum 校验。

相关代码与配置的入口，便于继续深入：

• 迁移指南与全部脚本：db/migration/README.md
• Flyway 与数据源配置：application.yml
• Flyway 依赖与版本：hub/pom.xml、console/backend/pom.xml

• 人工智能
• AI Agent
• Agent 工作流
• RPA
• 后端
• 前端
• 工具调用