CICD 入门:从提交到上线的全链路
本篇要点:读完你能说清持续集成、持续交付、持续部署的界线,并在自己机器上搭出一条从提交到部署的最小流水线。 前置文章:这是《CICD 入门:从提交到上线的全链路》。开始之前你只需要会用 Git 提交代码、能在 Linux 上敲命令、用 Docker 跑起过一个容器。
一、为什么需要它
2026 年 3 月,一家做社区团购的团队,6 个后端、2 个前端。发版固定在每周四晚上十点,流程写在 Notion 里,一共 17 步:本地跑测试、npm run build、压缩、scp 到跳板机、解压到带日期的目录、改软链、重启进程、看日志、发通知。
那天第 9 步漏了一个新加的环境变量 ORDER_TIMEOUT_MS,因为它只写在运维本机的 .env 里,没进仓库。上线后下单接口用了默认的 3 秒超时,晚高峰失败率爬到 12%,客服工单 200 多张。值班同学决定回滚,把上一个目录软链回来——那是三天前的版本,中间合了 14 个 commit,其中两个是当天下午刚修好的线上问题。回滚等于把它们一起撤掉了。
复盘写了两页,最后一条是「发布前双人核对清单」。三个月后同样的漏配又出过一次,因为新来的人不知道清单放在哪个页面。
这类事故的根因不在谁不小心。17 步流程全部依赖人的记忆,而人一定会忘,区别只是忘在第几步、多久被发现。流水线(pipeline)要解决的就是这件事:把那 17 步写成一段没人需要记住的机器指令,每一步的输入输出固定,失败了停在哪一步一目了然,回滚拿的是明确版本的制品而不是三天前的目录。
二、核心概念
2.1 三个 CD:集成、交付、部署
持续集成(continuous integration,CI)指开发者把代码频繁合入主干,每次合入都自动触发一次构建与测试,让「合坏了」在几分钟内暴露。
持续交付(continuous delivery)在 CI 之上再加一层:每次通过验证的构建都被自动送进「随时可以发布」的状态,按不按那个按钮由人决定。
持续部署(continuous deployment)把按钮也去掉,通过验证就自动上线。
用汽车总装线打比方。CI 是每装完一个零件就通一次电做检测;持续交付是车下线后停在交付区,钥匙插着、油加满,销售随时能开走;持续部署是车一下线就自己开到客户家门口。
反例:「我们 Jenkins 里有个 deploy job,能一键部署到生产」。这句话只说明你有自动化脚本,说明不了你能持续交付。判断标准是:任何一个通过验证的 commit,能不能在十分钟内变成生产上跑的版本,中间不用登服务器、不用手改配置。做不到的话,「一键」只是把 17 步压成 1 步,第 9 步那种漏配照样会漏。
落到工程上,持续交付要求「制品在通过测试时就已生成,部署阶段只分发不重建」;持续部署还多一条「部署后能自动判断健康,坏了自动退回」。
2.2 流水线阶段:按失败成本排序
阶段划分只有一条原则:越便宜的检查越靠前。
一次失败在不同阶段被发现的代价差很远。lint 报错在提交后 40 秒被发现,改一行就完;同一个空指针漏到生产,代价是失败率加值班电话。所以顺序基本固定:检出、依赖安装、静态检查、单元测试、构建、集成测试、部署预发、冒烟、部署生产。
「构建」这一步的位置值得单独说。不少团队把构建放在测试之后,理由是「先确认代码没问题再打包」。但单元测试跑的是源码,上线跑的是构建产物,两者之间隔着打包器、依赖解析、环境变量注入。测过的代码和上线的制品不是同一个东西,这是最隐蔽的一类事故来源。
图 1-1 从提交到上线的七个阶段,以及制品在其中的位置
如图 1-1 所示,阶段整体是一条从左到右的线,但有两处不是线性的。其一,制品在单元测试通过后就被固定下来,后面所有环境用的都是同一份;其二,部署生产前那个判断框,就是持续交付与持续部署的唯一差别。
2.3 制品与版本:不可变的那一份
制品(artifact)指流水线产出的、可以直接部署的东西:一个容器镜像、一个 jar 包、一份前端静态资源。它有两个硬要求。
一是不可变(immutable)。同一个版本号对应的内容永远不能变。听着像常识,但很多团队实际做的是「每次部署现场 build 一次」,于是预发验证过的和生产的不是同一份字节。
二是可追溯(traceable)。从生产上跑的镜像能一路倒推回某个 commit。做法是把 commit SHA 写进镜像标签和镜像内的 label。
常见的做法是一个制品打三个 tag:app:1.4.2、app:1.4.2-9f3c1ab、app:sha-9f3c1ab。语义化版本(semantic versioning)给人看,1.4.2 说明是第 2 个补丁;带 SHA 的给机器用,唯一且不会撞名;纯 SHA 的给回滚用。
版本号不要手写,从 git describe 或 CI 提供的 commit SHA 推出来。手写的版本号迟早会重复,而重复一次就毁掉了可追溯性。
2.4 环境分级:少一层通常更好
环境(environment)分级的目的只有一个:让生产配置在捅娄子之前先被验证一次,同时保证验证时用的配置和生产一致。
常见是开发(development)、预发(staging)、生产(production)三层。也有团队加第四层「测试环境」,结果是那层常年半死不活,谁都不信它的结论。
判断一层环境该不该存在,问两句话:它有独立的数据库和独立域名吗?有人定期看它的失败吗?两个答案都是否,这层环境就是负债,它让你误以为验证过了。
| 环境 | 用途 | 数据来源 | 谁能触发部署 | 挂了谁管 |
|---|---|---|---|---|
| 开发 dev | 单人自测 | 种子数据 | 开发者本人 | 自己 |
| 预发 staging | 上线前整体验证 | 生产脱敏快照 | 流水线自动 | 值班 |
| 生产 prod | 真实用户 | 真实数据 | 流水线 + 人工批准 | 全员 |
表 1-1 三层环境的边界,「谁能部署」写不清的那一层通常没人用
2.5 最小可用流水线
最小可用流水线(minimum viable pipeline)指能覆盖「提交即验证、通过即可部署」的最短路径,通常四步:检查、测试、打包、部署到一个环境。
重点在「可用」。一条跑 40 分钟、三天两头红着没人看的流水线,不如一条 6 分钟、红了必须停的。加阶段的顺序是先让它稳,再让它全,最后才让它快。
三、动手实践
拿一个两百行的 Node 服务演示,目录叫 demo-api,测试用 node --test(Node 18 起内置,Node 20 转正)。
3.1 一段 60 行的流水线脚本
先在本地用 shell 把四个阶段串起来,看清每一步的输入输出,再交给 CI 平台。这样做的好处是排错时能分清问题出在脚本还是平台。
#!/usr/bin/env bash
# ci.sh —— 最小流水线,任何 CI 平台都能跑
set -euo pipefail
APP=demo-api
TAG=$(git describe --tags --always --dirty)
echo "==> 制品版本: $TAG"
echo "==> [1/4] 安装依赖(严格按 lockfile)"
npm ci --no-audit --no-fund
echo "==> [2/4] 静态检查 + 单元测试"
npx eslint . --max-warnings=0
node --test
echo "==> [3/4] 构建镜像"
docker build \
--build-arg VERSION="$TAG" \
--build-arg GIT_SHA="$(git rev-parse --short HEAD)" \
-t "$APP:$TAG" -t "$APP:latest" .
echo "==> [4/4] 校验制品身份"
docker image inspect "$APP:$TAG" \
--format '{{.Id}} {{index .Config.Labels "org.opencontainers.image.version"}}'运行结果(chmod +x ci.sh && ./ci.sh,本地已打 tag v1.4.2,之后又提交了 3 次):
==> 制品版本: v1.4.2-3-g9f3c1ab
==> [1/4] 安装依赖(严格按 lockfile)
added 214 packages in 6s
==> [2/4] 静态检查 + 单元测试
✔ health endpoint returns 200 (12.4ms)
✔ order create rejects negative qty (8.1ms)
ℹ tests 2
ℹ pass 2
ℹ fail 0
==> [3/4] 构建镜像
#9 exporting to image DONE 0.4s
==> [4/4] 校验制品身份
sha256:6b1f0c2e... v1.4.2-3-g9f3c1abgit describe 的输出格式值得记住:v1.4.2-3-g9f3c1ab 表示最近的 tag 是 v1.4.2,之后又有 3 个 commit,当前 commit 缩写 9f3c1ab。末尾如果出现 -dirty,说明工作区有没提交的改动,这种版本号不该进生产。
3.2 把版本写进镜像内部
tag 打了还不够,制品本身要能自证身份。Dockerfile 里加两行 label:
FROM node:22-alpine AS runtime
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ARG VERSION=dev
ARG GIT_SHA=unknown
LABEL org.opencontainers.image.version="$VERSION" \
org.opencontainers.image.revision="$GIT_SHA" \
org.opencontainers.image.source="https://git.example.com/team/demo-api"
CMD ["node", "src/server.js"]运行结果(用 docker inspect 把 label 读出来):
$ docker inspect demo-api:v1.4.2-3-g9f3c1ab --format '{{json .Config.Labels}}'
{"org.opencontainers.image.version":"v1.4.2-3-g9f3c1ab",
"org.opencontainers.image.revision":"9f3c1ab",
"org.opencontainers.image.source":"https://git.example.com/team/demo-api"}有了这几条,出问题时不用问「生产上跑的是哪个版本」,一条 docker inspect 就有答案。这几个 label 名字来自 OCI 镜像规范(Open Container Initiative image spec)的 annotation 约定,主流镜像仓库会直接展示。
3.3 从脚本搬到平台
脚本能跑通,才轮到 CI 平台。等价的最小配置在 GitHub Actions 里不到 20 行,《GitHub Actions 工程化实践》会逐行拆开讲。
name: ci
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: npm ci
- run: npx eslint . --max-warnings=0
- run: node --test运行结果(Actions 页面上每个 step 的耗时):
ci / build (push) Success 1m 42s
✓ Set up job 3s
✓ actions/checkout@v4 2s
✓ actions/setup-node@v4 6s
✓ npm ci 38s
✓ npx eslint . 11s
✓ node --test 24s到这里流水线就立起来了:每次 push 自动验证,每次通过都留下一个带版本号的镜像。剩下的问题全是「怎么让它更快、更可信、更难被绕过」。
四、常见误解
很多人以为 CI 就是「有个能跑测试的服务器」。实际上自动触发才是 CI 的核心。一个要人手动点一下才跑的测试任务,本质上还是「想起来才跑」,而人一定会忘。
很多人以为流水线越长越专业。实际上阶段数量不等于覆盖度。一条 40 分钟、每周红三次的流水线,团队会养成「红着也合」的习惯;一条 6 分钟、红了必须停下来修的,才能当真。先砍到 10 分钟以内,比再加一个扫描阶段有用得多。
很多人以为部署到生产总得有人登服务器。实际上「人能上服务器改配置」本身就是风险源:改了什么没人知道,出事也没法复现。部署该由流水线执行,人的作用只在批准那一环。
五、小结
这一章给出的是整个类目的地基,后面十一章都在把它做得更快、更可复现、更安全。
- 持续集成管合入即验证,持续交付管随时可发,持续部署管自动发。三者的界线在于最后那个按钮由谁按。
- 阶段按失败成本排序,便宜的在前。构建要放在测试附近,保证测的和上的是同一份产物。
- 制品必须不可变、可追溯。版本号从
git describe或 commit SHA 推出来,不要手写。 - 环境层数不是越多越好,判断标准是「有独立数据源吗、有人看吗」。
- 最小可用流水线先求稳定,再求完整,最后才谈快。
六、相关文章
上面那段 20 行 YAML 能跑通,但它留着四个坑:依赖每次都重装,1 分 42 秒里有 38 秒在下载;多个 Node 版本只能复制粘贴;GITHUB_TOKEN 的权限大得像管理员;上了云以后还得在仓库里存一份长期密钥。相关文章把这四件事逐个拆开,讲清楚 workflow 的触发与复用怎么写、矩阵和缓存怎么配、权限怎么收到最小,以及用 OIDC(OpenID Connect)换掉长期密钥的做法。
继续阅读:[《GitHub Actions 工程化实践》 GitHub Actions 工程化实践](/guide/cicd/github-actions-engineering.html)