跳到主要内容
Ed. notes

09 CI(三):个人发布与企业流水线

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

  • 构建日志
  • CI
  • 发布
  • 权限
  • 流程
第 10 / 12 篇 · 查看全部章节 → 当前:09 CI(三):个人发布与企业流水线

一句话结论:同一串发布动作,个人做是「三条命令加一次判断」,企业做要变成「受控、可审计、可复现」的流水线。差距不在工具多少,而在谁能发布、发布留不留痕、失败后能不能追。

它解决什么问题

这个站一直是本地构建、推 ACR、SSH 上服务器更新。有人问我:这样做符合国内工程规范吗?

这个问题没法用「符合」或「不符合」回答,因为它把两个场景混在了一起。对个人项目,发布频率低,发布者就是作者,停机成本接近零,手工发布不仅够用,通常还比维护一条流水线更稳。对公司生产环境,发布者不止一个人,出了问题要能回答「谁在什么时候把哪个版本发上去的」,镜像要能证明来源,权限要能收回。这时候手工发布的问题不是「不规范」,而是「不可控」。

所以我把它拆成四个可以逐项检查的问题:

  1. 谁能发布?
  2. 发布有没有记录?
  3. 同样的输入能不能得到同样的结果?
  4. 出错之后多久能恢复?

用这四个问题对照现状,比争论「要不要上 CI/CD」更有用。

我怎么试的

1. 先把现在的流程一步不落地写出来

不写清楚现有流程,就没法判断它缺什么。本站一次完整发布是这样的:

# 1. 确认发布版本
git status --short                  # 期望为空
git rev-parse --short HEAD          # 这个 commit 就是镜像 tag

# 2. 本地构建并推送(linux/amd64)
./scripts/publish-image.sh

# 3. 登录服务器,更新 compose 配置
ssh admin@<server>
cd /opt/ednotes
cp .env ".env.bak.$(date +%F-%H%M)"
sed -i "s/^IMAGE_TAG=.*/IMAGE_TAG=<commit>/" .env
docker compose pull
docker compose up -d --no-build

# 4. 验证
docker compose exec -T app wget -qO- http://127.0.0.1:3000/api/health
docker compose logs --tail=50 app

# 5. 失败时回滚
sed -i "s/^IMAGE_TAG=.*/IMAGE_TAG=<old-commit>/" .env
docker compose pull
docker compose up -d --no-build

有两个细节值得说明。

健康检查是在容器里执行的,不是从宿主机访问 127.0.0.1:3000。compose 里 app 服务只有 expose: 3000,端口没有映射到宿主机,直接 curl 宿主机端口会失败;用 docker compose exec 进入容器请求,才和 Caddy 看到的是同一个服务。

控制台在这里没有位置。本地脚本推送的已经是构建完成的镜像,不需要再去 ACR 控制台点「构建」;控制台那条路是从源码重新构建,而它既不会、也不该去重启我的服务器。所以「推完镜像还要去控制台操作」是一个常见误解,实际剩下的唯一人工步骤就是 SSH 上去更新 compose。

2. 四个维度的差距

把这些步骤逐条对照企业生产环境的常见要求:

维度 本站现在的做法 企业生产的典型要求 差距的本质
权限 一个人的 ACR 密码和 SSH key 角色分离、短期凭证、最小权限 人离开或误操作时,权限要能收回
审批 自己按下回车 变更单或环境审批 发布前需要第二双眼睛
审计 shell history 谁、何时、发布了哪个 tag 或 digest、结果如何 出事后能定位,而不是靠回忆
复现 本机 Docker 加手动命令 固定 runner、步骤固化在流水线里 换一个人也能得到同样结果
镜像安全 没有接入扫描 扫描、签名、准入控制 知道镜像里到底有什么
回滚 手工改 tag 一键回滚并留下记录 恢复时间可预期

表格里没有「自动化程度」这一行,因为自动化本身不是目的。上面六项里,只要有三项靠人记着,自动化也只是把同样的风险换个地方发生。

3. 真要做成流水线,关键设计是什么

如果哪天要把这套流程搬进 CI,重点不是把命令粘贴进 YAML,而是三个设计。

构建一次,处处引用。 镜像只在流水线里构建一次,推一个 commit tag,记录对应的 digest;部署环节只传 tag 或 digest,不在服务器上重新构建。否则「测试过的镜像」和「上线的镜像」可能不是同一个。

用短期凭证,不用长期密钥。 把 ACR 密码和 SSH 私钥放进 GitHub Secrets 能用,但它们长期有效,一旦泄露窗口很大。更常见的做法是通过 OIDC 换取云厂商的临时凭证,并给部署身份单独授权。

审批和部署记录放在环境上。 GitHub Environments 的 required reviewers 是最小实现;部署 job 把 digest、操作者、时间和结果写进 release 记录或制品仓库。这样「谁发的」不再依赖某个人记得。

示意性的骨架如下,本站并没有落地这一段:

deploy:
  needs: check
  if: github.ref == 'refs/heads/main'
  environment: production # 审批挂在这里
  permissions:
    contents: read
    id-token: write # 用于换取短期凭证
  steps:
    - run: ./scripts/publish-image.sh
    - run: ssh "$DEPLOY_HOST" "cd /opt/ednotes && ./release.sh $GITHUB_SHA"

注意最后一行仍然调用仓库里的脚本。流水线应该复用和手工发布相同的步骤,而不是另写一套只在 CI 里成立的逻辑;否则手工回滚时又要重新对照两份实现。

4. 本站实际做到的边界

按个人项目的标准,这套流程是完整的:

  • CI 只读,permissions: contents: read,不持有发布凭证;
  • tag 来自 git rev-parse --short HEAD,tag 和代码一一对应;
  • 发布后检查 /api/health、首页、详情、RSS 和 sitemap;
  • 回滚演练做过一轮 a7a3df0 → 6aea71b → a7a3df0,确认改回旧 tag 就能恢复。

按公司生产标准,它缺的是治理,不是命令:

  • 没有审批,也没有第二个人能独立完成发布;
  • 没有部署记录,只有终端历史;
  • 没有镜像扫描、签名和准入;
  • 回滚是手工的,依赖我记得备份 .env。

这两份清单并不矛盾。它们回答的是不同场景下的同一个问题:这个流程的风险,是否与它承载的东西匹配。

5. 什么时候该升级

我给自己的判断线是四条,任意一条成立,就该把手工发布让位给受控流水线:

  1. 有第二个人需要发布。流程必须写进仓库,而不是留在某个人的终端历史里。
  2. 有对外承诺的可用性。需要审批、灰度或维护窗口,而不是「发完再看」。
  3. 有审计要求。客户、投标或等保一类的要求,最终都会落到发布记录和凭证分离上。
  4. 镜像来源需要被证明。需要扫描、签名和准入,而不只是「我知道它是从哪台机器推的」。

四条都不成立时,先把人工步骤降到最少、把回滚练熟,收益通常比搭一条流水线大。

坑和限制

1. 「我有脚本」不等于「流程可复现」。 脚本只在你的机器上跑通,依赖你的 Docker 版本、buildx 配置和 ACR 登录状态。换个人、换台机器,第一步就可能断。

2. 手工流程的隐性成本在记忆,不在操作。 备份 .env、在容器内 curl、看启动日志,每一步都靠记得。漏一步通常不会立刻报错,但会在回滚时暴露。

3. 企业流水线不是把命令搬进 YAML。 没有凭证模型、审批和审计,只是把手工操作自动化了,出错时反而更难查,因为中间多了一层不透明的执行环境。

4. 国内网络会改变方案形状。 跨境推镜像、构建机克隆私有仓库都可能卡住;流水线要么跑在境内 runner,要么依赖企业版能力。个人版 ACR 的组合下,本地发布不是退而求其次,而是当前网络条件下的正确选择。

5. 合规不是「上了 CI 就合规」。 备案、等保这类要求最终落在组织、流程和记录上,工具只是承载。反过来,工具再完整,没有记录和责任人也不成立。

6. 别照搬大厂。 发布频率低、只有一个人维护时,流水线的维护成本会高于它省下的时间。复杂度要和发布频率、团队规模一起增长。

适合谁

适合两类人:个人项目作者想判断「我这样算不算规范」;小团队准备从手工发布过渡到流水线,需要知道先补哪一块。判断标准不是「自不自动」,而是权限、审计、复现和回滚这四件事有没有答案。有答案,手工发布也是可控的;没有答案,全自动也只是把风险藏得更深。

继续探索