跳到主要内容
Ed. notes

08 CI(二):CI 构建还是本地发布

长文 · 2026-11-11 · 合集第 9 / 12 篇

  • 构建日志
  • CI
  • GitHub Actions
  • ACR
  • 发布
第 9 / 12 篇 · 查看全部章节 → 当前: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;把需要凭证、跨网络、失败代价高的发布留在本地。等团队和发布频率真的需要时,再考虑更复杂的流水线。

继续探索