代码能跑之后，工程才刚开始：从MVP开始的规范化交付

TL;DR

个人项目走向生产，分水岭并非单纯取决于是否使用了 Docker、CI 或云服务器，而在于一次变更能否开始拥有明确的来历、稳定的制品、可验证的前置条件、面向用户的验收和真实可执行的恢复路径。

我最初把部署理解为“把最新代码放到服务器并启动”；后来才意识到，生产交付的本质是一组受约束的状态迁移：问题先被描述，改动在分支中隔离，本地与 CI 共同反证候选版本，主分支只负责确认集成，Release 固化不可变制品，部署只运行已经存在的东西，验收从用户入口判断可用性，失败则恢复到上一份已知状态。

生产化是把一次不可控的远程操作，改造成一连串可识别、可验证、可拒绝、可恢复的状态迁移

flowchart LR
    Q["问题：描述失败与期望"] --> B["分支：隔离改动"]
    B --> L["本地验证：快速反馈"]
    L --> P["变更评审：解释决策与边界"]
    P --> C["CI：反证候选版本"]
    C --> M["主分支：确认集成"]
    M --> R["Release：固化不可变制品"]
    R --> D["部署：执行受控状态迁移"]
    D --> A["验收：从用户入口验证"]
    A -->|成功| O["持续运行"]
    A -->|失败| X["恢复上一已知状态"]
    X --> O

一、幻觉来了：部署成功 == 上线成功

2026 年 5 月，某个项目第一次拥有生产工作流简单粗暴，非常符合个人项目的“特色”：

flowchart LR
    A["main CI 通过"] --> B["SSH 登录服务器"]
    B --> C["git pull 源码"]
    C --> D["重写环境变量"]
    D --> E["执行 SQL 迁移"]
    E --> F["docker compose up"]
    F --> G["请求 /readyz"]
    G --> H["清理无用镜像"]
    H --> I["宣布部署成功"]

部署动作从终端搬进了 GitHub Actions，环境变量不再散落在聊天记录里，服务也有了健康检查，但这条链路没有回答任何稍微麻烦一点的问题：

• 所谓“最新代码”究竟是哪一个完整版本，多个运行组件是否来自同一次构建；
• 同名镜像被覆盖后，上一版本是否还能准确找回；
• 数据库脚本哪些已经执行，历史文件是否被悄悄改过；
• 健康接口正常，是否代表公网入口和关键用户路径正常；
• 更新进行到一半失败时，系统处于什么状态；
• 应用可以退回旧版本时，数据库是否仍与旧版本兼容

这些问题平时不出现，是因为变化还不够频繁、故障还没有恰好撞中边界，个人开发者既写代码、又部署、又排障，脑中保存着大量未记录的上下文，所以系统看起来比实际更可靠

从结果看，“代码能跑”只证明某一刻有进程启动了；“系统可持续运行”则要求团队——哪怕这个团队只有未来的我，能够解释现在运行的版本、这次变更的来历、系统为什么被判定为健康，以及失败后如何恢复，也因此必须对现有生产链路作出修改

1.1 生产化是工具，状态和证据升级

shell 命令搬进 GitHub Actions，并不会自动得到持续交付¹，如果工作流仍然进入服务器拉源码、安装依赖、现场构建，那么只是把手工操作换成了远程bot，版本、环境漂移和恢复困难依旧存在，工程真正发生变化，是每个阶段开始有清楚的事实来源：

重要原则：后面的绿灯不能只继承前面的结论。源码测试通过，不代表镜像构建正确；镜像正确，不代表生产配置完整；容器存活，不代表用户路径可用；应用制品可以回退，也不代表数据状态可以跟着倒退，靠多个边界清楚的检查分别回答不同问题，才不至于一用就崩

1.2 从问题到分支：先让“为什么改”可恢复

我在为期半年的各类MVP项目开发~~（各种造垃圾与推倒重来）~~中发现，个人开发最容易跳过问题记录这一必要环节：看到故障就直接改，改完能跑就提交。短期看很快，时间一久却无法解释某段防御代码为什么存在，也无法判断删掉它会不会让旧故障重现 还会让聪明AI给你加无数防御性回退掩盖真实问题所在，违背第一性原则，因此，一份有价值的问题描述至少应保存：

• 用户观察到的现象，预期行为与实际行为，稳定的复现条件，已知证据与尚未证实的猜测；
• 本次改动允许触碰和禁止触碰的边界，修复完成后如何重新验证

这使问题从“作者记得的一次异常”变成“未来仍能重放的一组条件”。随后创建独立分支，保持主分支整洁，给一次假设建立有限的实验空间：这批改动解决哪类失败，修改了哪些边界，又通过什么证据证明没有扩大风险

好的评审说明应把“为什么改”和“改了什么”连接起来，并明确数据库、配置、部署和恢复是否受到影响，Issue 与 PR 的结构化关联可以帮助工具维护这种关系²

1.3 本地验证：消灭“我的电脑能跑啊，你那怎么不行？”

分支只隔离了改动，没有消除环境差异，下一道陷阱又来了：本地机器装着作者自己也记不清的运行时、系统库和数据库状态，所有测试都通过，但换一台机器就开始补依赖、改端口、重建数据，这时候就涉及到容器化，把隐式环境改成版本化输入，构建：

• 运行时与基础设施版本由镜像定义，服务通过受控网络发现彼此，而非依赖某台电脑的端口习惯；
• 数据库初始化、迁移与测试数据有固定入口，应用、网关与依赖以接近生产的拓扑共同启动，本地与 CI 调用同一组命令

本地验证追求快速反馈，因此不必每次都执行最昂贵的全链路演练，按故障半径分层：

• 单元与契约测试证明局部逻辑和接口边界；
• 数据库集成测试证明真实事务、迁移和查询行为；
• 浏览器测试证明页面与后端能够协作；
• 外部验收从网关入口进入，再核对系统状态；
• 发布测试专门验证制品身份、清单、排除规则和回滚条件；
• 隔离演练验证交付机制本身能否完成部署与恢复

1.4 CI 的职责是寻找反例

早期 CI 敏捷开发时，只运行 lint、类型检查和单元测试，这对代码质量有帮助，但检查全绿，候选版本就已经适合生产吗？不一定,让 CI 主动覆盖那些“代码正确但交付仍会失败”的路径会更好：

• 使用真实数据库执行迁移，从统一入口运行浏览器与 API 验收；
• 构建实际要发布的镜像，验证多个镜像来自同一源码身份；
• 检查部署包没有带入源码、测试数据和开发工具。在临时环境中执行部署、验收和恢复

这类 CI 更容易在建设初期暴露“看起来与业务无关”的失败：临时网络没有按预期暴露、隔离环境选择了错误的项目状态、恢复后探针仍指向旧入口…若 CI 只检查业务函数，它们会原封不动地进入生产

1.5 主分支别当 Release 看待

主分支只确认源码完成了集成，真正的 Release 还需要把源码、运行制品和验证证据绑定成一个稳定对象，古法手工发布，会在服务器执行 git pull 和 docker compose up --build，让生产环境同时承担源码同步、依赖解析、镜像构建和服务更新，任何一步都可能受网络、缓存、工具版本和服务器残留状态影响有一次全盘扫描服务器空间大文件给我ECS搞OOM了更麻烦的是，所谓“部署上一版”往往意味着重新执行一次旧代码的构建，而非取回当时真正运行过的东西

演进后的流程在 CI 中一次性构建全部运行镜像，为它们写入同一个源码 revision，并记录 Registry 返回的 digest。tag 是可以移动的名称，digest 则是内容寻址的不可变身份³。生产环境只按 digest 拉取，不再现场构建。

Release manifest⁴ 把一次发布需要回答的问题收口到机器可读清单中：

• 源码来自哪个完整 revision，每个运行组件对应哪个镜像 digest，数据库迁移集合与校验和是什么；
• 哪些检查已经通过，哪些文件明确不属于生产部署包，上一份稳定 Release 是什么。

部署主机收到了最小运行包：编排文件、Release manifest、兼容性计划和必要的验证脚本。源码、测试数据、评测产物、开发工具与历史记录都被过滤掉，现在，main CI 通过后，会从完整 main SHA 构建除数据库外的完整镜像，每个镜像都写入同一个 OCI revision label[^note_oci_revision]，推送后记录 Registry 返回的 digest

构建只发生一次，测试、部署和恢复围绕同一份制品展开，发布原子化为一个可识别、保存、比较的对象

1.6 数据库迁移必须拥有自己的生命周期

应用镜像可以快速切回旧版本，数据库变化却可能已经改写结构或事实数据，把 migration 顺手放进应用部署，看似省事，实际把两种可逆性完全不同的状态绑在了一起。

我早期的做法直接依赖假设：只要每个 SQL 文件尽量幂等，就可以在每次发布时全部执行，然后就寄了，因为根本不知道：

• 这个文件是否已经在生产执行，执行过的历史文件是否被修改，变更只影响结构，还是会触碰事实数据；
• 允许在哪些环境运行，失败后的恢复方案是什么，高风险操作是否经过独立评审。

更可靠的迁移入口，应该要求每个变更声明范围、数据风险、允许环境、回滚计划和评审要求，并在数据库中登记文件名、checksum、源码身份、执行者与结果。已执行的历史 migration 只允许校验，不允许通过修改原文件来“历史修正主义”；内容漂移必须直接拒绝

普通应用部署，因此不再自动执行数据库变更。数据库迁移先经过备份、隔离恢复验证、风险评审和独立执行；应用部署只用只读事务确认生产数据库已经处于 Release 所要求的兼容状态，PostgreSQL 的只读事务设置降低核验脚本误写生产的风险⁵。

备份文件需要校验完整性、权限与 checksum，并在隔离数据库中真正恢复，确认目标对象可用后才算形成恢复证据⁶，作为为完成标准

将数据库迁移从应用部署中拆出，承认可逆性不同是对的，毕竟应用回滚、数据库恢复和配置纠正是三种故障处置，各有各的操作逻辑和最佳实践

1.7 生产部署只运行已经存在的东西

成熟后的生产部署：选择一份已经在主分支构建、通过门禁并保存完备证据的 Release，然后由授权操作触发部署，替换容器之前，流水线先完成所有不需要修改生产的检查：

• Release 来源与源码身份是否合法，manifest 和部署包 checksum 是否一致，所有镜像 digest 是否仍可从 Registry 拉取；
• 数据库是否满足只读兼容性要求，必要配置是否存在且能够被确定性判断，当前需要保持不变的生产状态是否已快照。

只有这些前置条件全部成立，部署才进入第一个写动作：上传新的最小运行包，按 digest 拉取镜像，再用禁止现场构建的方式更新服务。部署后重新对账运行 digest、revision、配置快照、数据库兼容性和外部依赖

把所有可能失败、但不需要修改生产的检查，尽量放到第一个生产写动作之前，减少发布已经改动一半，随后还要人工理解并修复半成品现场的概率

二、生产部署了是吧，该真实环境抗压了

2.1 验收：流水线全绿，用户仍然不可用

容器全部存活，健康与就绪检查通过，数据库也可访问，但真实用户动作仍然失败。问题绝非某个检查“写错了”，而在于验证边界不完整。流水线只证明了：

flowchart LR
    A["制品可运行"] --> B["进程已启动"]
    B --> C["响应内部探针"]
    C --> D["基础依赖可访问"]

它没有证明：

flowchart LR
    A["公网入口发起"] --> B["网关按规则转发"]
    B --> C["加载完整运行配置"]
    C --> D["外部依赖真实可用"]
    D --> E["到达正确终态"]

类似地，应用在本地持续输出数据，不代表生产代理不会缓存；源站观察到连续响应，也不代表浏览器从公网看到同样的节奏。组件内部的白盒信息适合定位原因，却不能替代从用户入口发起的黑盒验收⁷，我的做法是增加一系列受限的关键路径探针：它从公网入口进入，使用最小合法输入，经过真实网关、运行配置与外部依赖，最后只记录协议、事件和终态

2.2 故障恢复：回滚并非重新部署“上一版代码”

可执行的应用回滚应以“上一份已知稳定 manifest”为目标：

flowchart LR
    A["验证上一 Release 属性"] --> B["检查数据库向下兼容"]
    B --> C["按 digest 拉取旧镜像"]
    C --> D["禁止构建更新服务"]
    D --> E["重新验证身份与入口"]
    E --> F["确认配置与数据边界"]

应用回滚不应顺带恢复数据库、修改租户状态或重写运行配置，若故障涉及这些状态，就应进入各自独立的恢复流程，并获得与风险匹配的授权：启动上一组制品，创建并恢复数据库备份，执行受治理的迁移，部署候选版本，完成验收

2.3 最危险的命令，可能看起来完全“只读”

还有一类故障很容易被忽略：某些没有修改业务数据的诊断命令，因为需要枚举大量运行时对象，在资源紧张的主机上耗尽内存，连带影响应用容器BOOM

上生产环境必须小心又小心，考虑最坏资源成本、是否有明确超时和输出上限、操作与业务是否共享故障域、失败时会拖垮哪个组件、是否存在更窄、更定向的观测方式，才能动手

发布路径中的诊断应该是有界的：读取必要的系统指标、定向检查目标容器、执行受控健康请求、使用数据库只读事务。全量枚举与重型排障应脱离发布关键路径，在独立窗口和授权下执行，操作的安全性要按副作用和故障域判断，切忌单纯按语义上的“只读”进行判断

三、小结：把一次发布变成可解释的状态迁移

在MVP阶段，代码能放到服务器并启动就是胜利，进入持续运行阶段后，需要回答的问题就完全不一样了

这就是“问题 → 分支 → 本地验证 → 变更评审 → CI → 主分支 → 不可变 Release → 生产部署 → 验收 → 故障恢复”这条链路的意义，Release Engineering⁸是为了给个人项目套上一层企业的规范化流程，为了把依赖作者记忆的操作，改造成未来仍有人敢修改、发布、在故障中执行的工程系统

代码能跑，是今天的成功；系统可持续运行，是让明天的变化仍然可控，并在未来的意外到来之时，能够最快恢复正常