08 CI(二):CI 构建还是本地发布
一句话结论:CI 的职责是证明代码没有坏,发布的职责是把某个确定的版本送到服务器;这两件事的权限、网络和失败代价都不一样,应该分开设计,而不是让「CI 全绿」自动等于「线上已更新」。
它解决什么问题
一开始,我对自动化的想象是一条直线:push 代码,GitHub Actions 跑检查、构建镜像、推到 ACR,服务器拉取新镜像并重启。理想情况下,这条链路确实能工作;但在国内网络、私有仓库和个人版 ACR 的组合下,它会在几个具体位置断掉。
第一处是 GitHub Actions 推镜像到 ACR。镜像层不小,跨境链路的稳定性不由我控制,失败时往往只看到超时。第二处是 ACR 自动构建。它需要构建机从 GitHub 克隆私有仓库,日志停在 Cloning into '/workspace'...,没有明确错误。第三处是权限:如果 CI 要直接部署,它就需要 ACR 凭证、服务器访问能力,甚至 SSH key;这些凭证放在 GitHub Secrets 里不是不行,但一旦工作流配置出错,影响面比一个本地脚本大得多。
所以我停止追求「一条全自动直线」,改成两条明确的路径:CI 负责质量门,本地脚本负责发布,服务器只负责拉取和运行。
我怎么试的
1. 把三条路径放在一起比较
| 路径 | 链路 | 主要失败点 | 适合什么 |
|---|---|---|---|
| GitHub Actions 构建并推送 | GitHub → Actions → ACR → 服务器 | 跨境推送慢、镜像层大、凭证多 | 网络稳定、镜像较小的团队 |
| ACR 自动构建 | GitHub → ACR 构建机 → 服务器 | 克隆私有仓库卡住、构建日志不透明 | 代码托管在可稳定访问的仓库 |
| 本地 buildx 推送 | 本地/境内机器 → ACR → 服务器 | 构建机要装 Docker、发布是手动步骤 | 个人项目、国内网络、需要可控回滚 |
我三条都试过。GitHub Actions 的检查部分很稳,但推镜像不稳定;ACR 自动构建在克隆阶段卡住;本地 buildx 最笨,却每次都能在几分钟内完成,失败时也知道该看哪一行日志。
2. 为什么不让 CI 直接发布
除了网络,还有三个原因。
权限边界。 CI 如果直接发布,就需要写 ACR、访问服务器。工作流文件在仓库里,任何有写权限的人改一行 run,就能把凭证用在别处。个人仓库风险不大,但习惯应该从一开始就对:CI 只读代码,发布凭证留在本地。
版本可追溯。 本地脚本用 git rev-parse --short HEAD 作为 tag,发布哪个 commit 一目了然。如果 CI 在合并后自动发布,tag 和实际运行的代码之间多了一层「工作流是否成功」的状态;排查时还要去翻 Actions 记录。
失败代价。 质量门失败,最多是 PR 不能合并;发布失败,可能留下半更新状态。把发布做成一个需要人主动执行的命令,能强制我在按下回车前看一眼版本号和变更。
3. 最终分工
GitHub Actions(只读)
├─ lint / stylelint / format / typecheck
├─ vitest
├─ nuxt build
├─ Playwright e2e + axe
└─ docker build(只验证 Dockerfile)
本地发布
├─ scripts/publish-image.sh
├─ buildx --platform linux/amd64
├─ push ACR public endpoint
└─ 服务器 pull ACR VPC endpoint → compose up
CI 里的 image job 只执行 docker build,不登录 ACR,也不推送。它通过 needs: check 挂在质量门之后:测试没过,就不会浪费 runner 去构建镜像;但它证明的是 Dockerfile 没有坏,不是镜像已经可用。真正的发布仍然需要我在本地执行脚本,然后在服务器上 docker compose pull && docker compose up -d --no-build。
这不是「自动化不完整」,而是有意的分工。CI 擅长在干净环境里重复检查,不擅长处理跨境网络和长期凭证;本地脚本擅长在我盯着终端的时候完成一次可控的发布。
4. 用 commit tag 和 digest 钉住版本
发布脚本会同时推两个 tag:
IMAGE_TAG="$(git rev-parse --short HEAD)"
docker buildx build \
--platform linux/amd64 \
--tag "${IMAGE_REPO}:${IMAGE_TAG}" \
--tag "${IMAGE_REPO}:latest" \
--provenance=false --sbom=false \
--push .
部署时用 IMAGE_TAG,不要用 latest。latest 会随着每次推送移动,今天拉到的 latest 和昨天可能不是同一个镜像。commit tag 不会移动,回滚时把它改回旧值即可。
如果想进一步确认服务器上跑的到底是哪一层,可以看 digest:
docker inspect --format '{{index .RepoDigests 0}}' \
"$(docker compose images -q app)"
digest 是镜像内容的哈希,比 tag 更接近「不可变」。tag 可能被覆盖,digest 不会。个人项目不必每次都记录 digest,但在排查「明明发了新版本,页面却没变」时,它能区分是构建、推送还是拉取出了问题。
5. 发布后验证
每次发布后,我会按固定顺序检查:
curl -s http://127.0.0.1:3000/api/health
# {"status":"ok","notes":9}
curl -sI http://127.0.0.1:3000/ | head -1
curl -sI http://127.0.0.1:3000/notes/magpie | head -1
curl -s http://127.0.0.1:3000/rss.xml | head -5
curl -s http://127.0.0.1:3000/sitemap.xml | head -5
健康接口确认内容和运行时都加载成功;首页和详情页确认 SSR 正常;RSS 和 sitemap 确认内容聚合没有因为新版本断掉。最后再看一眼 docker compose logs --tail=50 app,确认没有启动时的异常堆栈。
发布前还有一张很短的清单:工作区没有未提交的改动、CI 对目标 commit 是绿的、脚本打出的 tag 和 git rev-parse --short HEAD 一致、.env 里的 IMAGE_TAG 已经更新。任何一项对不上,都先停下来,不要靠「应该没事」把版本推上去。
坑和限制
1. 自动构建不是越自动越好。 每增加一个自动步骤,就多一个需要维护的凭证、网络路径和失败模式。个人项目的发布频率不高,手动执行一次脚本的成本,往往低于排查一条不稳定的自动链路。
2. 私有仓库会放大网络问题。 ACR 自动构建需要克隆私有仓库;只要构建机访问 GitHub 不稳定,日志就会停在克隆阶段。把仓库公开能缓解,但这不是一个应该为了 CI 而做的决定。
3. 凭证不要进仓库。 ACR 密码、服务器 key、.env 都应该留在本地或服务器的受限文件里。CI 只保留只读权限;发布脚本也不要把密码写进命令行历史。
4. latest 会漂移。 它适合手动查看「最近一次推送」,不适合作为部署或回滚的依据。所有自动化和文档都应该以 commit tag 为准。
5. 手动发布仍然会忘。 脚本不会提醒你「代码已经合并但还没发布」。当前用一份发布检查清单补这个缺口;如果以后频率变高,可以加一个只读的部署状态检查,但不要因此把发布权限交给 CI。
6. 构建和部署是两件事。 镜像构建成功,不代表 compose 配置正确;compose 启动成功,也不代表 Caddy、DNS 和备案状态就绪。每一层都要单独验证。
适合谁
这篇适合正在纠结「要不要让 CI 直接部署」的个人开发者。它不提供一套通用的 CI/CD 模板,而是给出一条判断线:把只读、可重复、失败代价低的检查放在 CI;把需要凭证、跨网络、失败代价高的发布留在本地。等团队和发布频率真的需要时,再考虑更复杂的流水线。