Coolify 中 383 个 Laravel 迁移文件的治理规范：以大规模迁移体系印证七条数据库迁移最佳实践

Coolify 中 383 个 Laravel 迁移文件的治理规范以大规模迁移体系印证七条数据库迁移最佳实践【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本篇以 Laravel 迁移最佳实践规则为骨架结合 Coolify一个可自托管、对标 Vercel/Heroku/Netlify 的开源 PaaS仓库中 383 个真实迁移文件的写法逐条展开「Artisan 生成迁移、外键 constrained、不可修改已部署迁移、建表即建索引、模型镜像默认值、可回滚 down() 方法、单一职责迁移」七项规范的具体含义与落地方式。读完本文你将掌握在大型 Laravel 项目中编写、演进和回滚数据库迁移的完整方法论并能在 Coolify 迁移目录 中找到每条规则的源码级实证。Coolify 的迁移体系规范从何而来Coolify 是典型的「长周期演进」Laravel 项目从 database/migrations 目录看当前仓库累计沉淀了383 个迁移文件时间跨度从 2014 年的框架基础表用户、密码重置、会话一直延续到 2025 年的云服务商令牌等新增表。这种量级意味着迁移本身已经成为项目最重要的「数据架构文档」——任何一个在 CI 或生产环境中被执行过的迁移都牵动着所有已部署实例的数据库状态。因此Coolify 将迁移实践规范沉淀为独立规则文档 migrations.md作为团队协作与代码审查的依据。下文按该文档的七条规则逐一展开并用仓库中的真实迁移文件佐证每条规则的执行情况。一、统一用 Artisan 生成迁移命名即契约规则文档的第一条要求永远使用php artisan make:migration生成迁移文件以获得一致的命名与时间戳禁止手工创建无时间戳的文件。# 正确做法Artisan 生成 php artisan make:migration create_posts_table php artisan make:migration add_slug_to_posts_table对比手工创建的posts_migration.php无时间戳、命名随意Artisan 生成的文件名遵循Y_m_d_His_action_description.php格式。时间戳前缀直接决定了php artisan migrate的执行顺序是迁移幂等性与可重放性的基础。Coolify 仓库的命名风格可以完整印证这一点例如建表2023_03_27_075351_create_projects_table.php、2024_02_01_111228_create_tags_table.php加列/改表2023_08_06_142951_add_description_field_to_applications_table.php、2025_10_09_095905_add_cloud_provider_token_id_to_servers_table.php。动词前缀create_*与add_*让文件按时间排序后表结构演进脉络一目了然——这正是时间戳命名带来的「可审计性」。二、外键统一使用 constrained()自动命名 引用完整性规则要求所有外键列使用foreignId(...)-constrained()让 Laravel 自动推导约束名称{表}_外键列_foreign并真正创建数据库级外键非标准表名时可显式指定$table-foreignId(user_id)-constrained()-cascadeOnDelete(); // 外键指向非约定命名的表 $table-foreignId(author_id)-constrained(users);Coolify 的迁移中constrained()几乎是外键列的标准写法且清晰展示了三种级联策略的选择cascadeOnDelete()/onDelete(cascade)——子记录随父记录删除。通知配置类表全部采用此策略如 team_invitations 迁移 中的$table-foreignId(team_id)-constrained()-cascadeOnDelete();以及 Slack 通知配置迁移、邮件、Discord、Telegram、Pushover 等同类表。团队删除后其通知配置随之级联清理避免孤儿配置行onDelete(set null)——父记录删除时置空外键用于「可选关联」。例如 服务器表追加 cloud_provider_token_id 列的迁移$table-foreignId(cloud_provider_token_id)-nullable()-after(private_key_id)-constrained()-onDelete(set null);。云令牌被删除时服务器记录保留、仅解除关联这是典型的「软解除引用」场景可空外键 可空级联——共享环境变量迁移 展示了变量可绑定到 team/project/environment 中任意一层的灵活建模$table-foreignId(project_id)-nullable()-constrained()-onDelete(cascade);。值得注意的是并非所有foreignId都带constrained()。例如 applications 建表迁移 中$table-foreignId(environment_id);未加约束——从源码结构看这是早期迁移的遗留写法可能为规避迁移顺序或大表加外键的锁表开销。对新迁移而言规则文档的立场是明确的能用constrained()就应当用把引用完整性交给数据库而非应用层校验。三、已部署的迁移视为不可变只新增、不修改这是迁移规范中最关键的一条一旦迁移在生产环境执行过就把它当作只读文件要改表就新建一个迁移。文档中的反例是编辑已上线的2024_01_01_create_posts_table.php追加slug列正确做法是新增add_slug_to_posts_table迁移在down()中dropColumn实现回滚。这条规则在 Coolify 的演进史中被反复验证applications表自 2023 年 3 月创建后从未被「就地修改」其后续所有字段变更都以新迁移追加例如2023_08_06_142951_add_description_field_to_applications_table、2024_05_15_091757_add_commit_message_to_app_deployment_queue等一系列add_*文件。383 个迁移文件本质上就是一份「只追加append-only」的表结构变更日志——如果允许编辑旧文件任何新实例执行migrate得到的 schema 都会与存量实例分叉而「不可变 新迁移」保证了任意时点全新拉起的数据库与存量数据库的终态一致。四、建表时就把索引建好WHERE / ORDER BY / JOIN 的列规则要求凡用于WHERE、ORDER BY、JOIN的列应在Schema::create阶段直接加索引而不是事后补迁移。文档给出的标准示例Schema::create(orders, function (Blueprint $table) { $table-id(); $table-foreignId(user_id)-constrained()-index(); $table-string(status)-index(); $table-timestamp(shipped_at)-nullable()-index(); $table-timestamps(); });Coolify 仓库中同类写法同样存在如 会话表迁移$table-foreignId(user_id)-nullable()-index();与$table-integer(last_activity)-index();——会话查询几乎总是按user_id过滤、按last_activity排序索引在表结构诞生之初就与列同时落地省去了后续「加索引 大表锁/重建」的成本。此外unique()约束如 team_invitations 中的$table-unique([team_id, email]);在多数数据库中也由索引支撑属于同一类「建表即完成」的决策。五、数据库默认值与模型 $attributes 双写镜像当列定义了数据库默认值时规则要求在模型的$attributes中镜像同样的默认值使未持久化的新实例在保存前就持有正确值// Migration $table-string(status)-default(pending); // Model protected $attributes [ status pending, ];Coolify 模型中这一模式真实存在Team 模型 声明了protected $attributes [is_mcp_server_enabled true];其默认值与建表迁移中的列默认值语义一致——这样new Team后未显式赋值时序列化、API 响应、表单回填都拿到与数据库一致的初始值而不是null。仓库中 EnvironmentVariable、InstanceSettings、ServiceApplication 等模型也采用了相同的$attributes镜像写法。对照 applications 建表迁移 可以看到大量-default(...)列health_check_method默认GET、git_commit_sha默认HEAD等。这些默认值对「数据库侧直接插入」是兜底而模型侧的镜像默认值则覆盖了「应用侧构造对象再落库」的路径两处默认值保持一致是这条规则成立的前提。六、默认编写可回滚的 down()让 migrate:rollback 在 CI 与事故现场可用规则要求凡是能安全逆操作的 schema 变更都应实现down()使php artisan migrate:rollback可用于 CI 环境重置与部署失败回退。Coolify 的建表迁移普遍遵循此约定例如 projects 建表迁移public function up(): void { Schema::create(projects, function (Blueprint $table) { $table-id(); $table-string(uuid)-unique(); $table-string(name); $table-string(description)-nullable(); $table-foreignId(team_id); $table-timestamps(); }); } public function down(): void { Schema::dropIfExists(projects); }Coolify 的测试体系依赖可重放的迁移链phpunit.xml 强制DB_CONNECTIONtesting配合 config/testing.php 的测试库配置功能测试tests/Feature 下 500 个测试文件需要在隔离数据库中干净地重跑整套迁移。down()方法的可执行性直接决定了migrate:fresh/rollback能否在 CI 中稳定工作。规则同时给出一条务实的边界对于故意不可逆的迁移如破坏性数据回填不要假装支持回滚——留一条清晰的注释说明不可逆原因并以「向前修复forward fix」新迁移代替回滚。这与「不可变迁移」原则一致回滚能力是设计出来的不是事后补救出来的。七、一个迁移只解决一件事DDL 与 DML 分离规则的最后一条每个迁移聚焦单一关注点绝不混用 DDL改结构和 DML动数据。文档给出的反例是在up()里既Schema::create(settings, ...)又DB::table(settings)-insert([...])——一旦前半成功、后半失败数据库将停留在「表已建、种子数据缺失」的不可恢复中间态正确做法是拆成create_settings_table与seed_default_settings两个迁移。这里值得对照 Coolify 仓库中的真实案例做一点深入讨论。Slack 通知配置迁移 的up()确实同时包含了 DDL 与 DML建表之后遍历所有存量团队为每个 team 插入一行默认通知配置并用try/catch Log::error包裹单条插入以保证批量循环的幂等与容错foreach ($teams as $team) { try { DB::table(slack_notification_settings)-insert([team_id $team-id]); } catch (\Throwable $e) { Log::error(Error creating slack notification settings for existing teams: .$e-getMessage()); } }从源码结构看这是对「存量数据升级」场景的务实妥协新表带team_id唯一约束每个团队必须立刻拥有一行配置后续 Team 模型的 booted 钩子 已改为在新建团队时自动创建各行通知配置。严格遵循「单一职责」时应当拆分为建表迁移 数据回填迁移两个文件而把两者合并在同一文件内、辅以逐条容错则换来了「建表与回填原子生效」的运维便利。理解这一取舍比机械背诵规则更有价值规范定义的是默认姿势而存量数据升级是需要显式权衡的例外场景。实践清单提交迁移前逐项核对综合以上七条规则可以在代码审查中使用如下检查清单检查项依据文件由php artisan make:migration生成文件名含时间戳与create_/add_语义前缀命名规范参见 tags 建表迁移所有外键列使用foreignId(...)-constrained()并显式选择cascadeOnDelete/set null等策略team_invitations、cloud_provider_token 列未修改任何已部署迁移表结构变更一律新增add_*迁移Coolify 迁移目录 的 append-only 演进模式WHERE/ORDER BY/JOIN列在Schema::create阶段即加index()/unique()sessions 表数据库列默认值在模型protected $attributes中镜像Team 模型、applications 建表迁移down()实现可回滚确不可逆处留注释并改用向前修复projects 建表迁移一个迁移只做一件事DDL 与 DML 分离存量回填例外需显式说明并容错Slack 配置迁移案例对自托管 PaaS 这类「用户各自持有数据库」的项目迁移的可重放性就是产品承诺的一部分新安装、旧库升级、CI 重置三条路径最终必须收敛到同一份 schema。以上七条规则覆盖了从命名、外键、索引到回滚的完整生命周期而 Coolify 仓库中 383 个迁移文件则提供了每一条规则在大体量、长周期项目中的真实落点。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考