CI/CD 持续集成与部署实战

1.1 三个概念的区别#

三个词都带 CD，含义完全不同，是最容易答错的面试题之一。

1
开发提交 push
2
  -> CI：代码检查 -> 单元测试 -> 构建
3
  -> 产出制品（artifact / 镜像）
4
  -> 自动部署测试环境 -> 自动化验收测试
5

6
持续交付：... -> 等待人工批准 -> 生产
7
持续部署：... -> 门禁全绿 -> 直接进生产

一句话概括：CI 关注“代码合进去能不能用”，持续交付关注“随时可发布”，持续部署关注“已经发出去了”。持续部署的前提是自动化测试足够可靠、监控和回滚足够快，否则就是裸奔。

1.2 流水线解决什么问题#

• 人为失误。手工部署是 SSH 登录、git pull、装依赖、构建、重启进程，中间任何一步打错字、走错目录、忘清缓存都会变成事故。人类在重复劳动面前的错误率是稳定的，交给机器即可。
• 环境差异。“在我机器上是好的”本质是构建环境不可复现：Node 版本、系统库、本地全局包、.env 里别人没有的一行配置。流水线把构建固定在干净的、声明式的机器上。
• 反馈太慢。一次提交等一整天才发现编译不过，修复成本指数上升。CI 把发现问题的时间从小时级压到分钟级。

顺带解决的还有：交付过程可审计（谁、何时、把哪个 commit 发上了线）、部署可重复（同一个 commit 结果一致）、新人上手成本低（部署方式写在 YAML 里，而不是老员工脑子里）。

2.1 阶段划分与耗时预算#

理想状态下，从 push 到“知道有没有问题”应在 10 分钟以内。超过这个阈值，开发者就会切去做别的事，反馈循环断裂。

2.2 设计原则#

• 快速反馈优先：最快、最容易失败的检查放最前。lint 挂了没必要跑 5 分钟单测。
• 失败即停 fail fast：默认行为即如此；除非检查彼此独立且并行成本低，不要用 continue-on-error 吞掉失败。
• 可重复 reproducible：同一 commit 任何时候跑出的制品应一致。锁文件必须提交，基础镜像用精确 tag 而不是 latest。
• 幂等 idempotent：部署脚本跑一次和跑三次结果一样。“先删目录再建”这种半途失败会留下残骸的写法要避免。
• 一切代码化 pipeline as code：流水线定义进仓库、跟着分支走，能 review、能回滚。网页上点出来的 Jenkins Job 是反面教材。
• 最小权限：流水线默认只拿它能拿到的权限，多余的显式关掉。

4.1 常用事件#

1
on:
2
  push:
3
    branches: [master, "release/**"]
4
  pull_request:
5
    branches: [master]
6
    types: [opened, synchronize, reopened]
7
  schedule:
8
    - cron: "0 2 * * *"
9
  workflow_dispatch:
10
    inputs:
11
      environment: { type: choice, options: [staging, production] }
12
  release:
13
    types: [published]

push 最常用，往往配合 branches 限定主干或发布分支。pull_request 用于质量门禁，注意来自 fork 的 PR 拿不到仓库 secrets（这是安全设计，不是 bug）。schedule 用 cron 跑定时任务，比如每天凌晨的依赖漏洞扫描，GitHub 用的是 UTC，写 0 2 * * * 实际是北京时间上午 10 点。workflow_dispatch 提供手动按钮，适合“一键回滚”“手动发布生产”这类需要人决策的场景。release 与 push: tags 用于版本发布。

4.2 分支与路径过滤#

1
on:
2
  push:
3
    branches-ignore: ["dependabot/**"]
4
    paths: ["src/**", "package.json", "pnpm-lock.yaml"]
5
    paths-ignore: ["**.md", "docs/**"]

paths 是白名单、paths-ignore 是黑名单，二者不能在同一事件下同时使用。一个坑：一次提交同时包含代码和文档改动时，paths-ignore 不会拦下这次运行——只要有任何一条改动命中 paths 就触发。路径过滤是省成本的第一手段，文档、图片的改动不该烧构建时长。

4.3 并发控制与防重复触发#

concurrency.group 是并发锁的键，写法是 concurrency: { group: deploy-blog, cancel-in-progress: false }。同一 group 内默认排队等待前一个结束；加上 cancel-in-progress: true 则直接取消正在跑的那个。

两种情况要分开处理：CI 类（lint / test）用 cancel-in-progress: true，连续 push 三次只跑最后一次，前两次已无人关心；部署类必须用 false，部署跑到一半被取消很可能留下半新半旧的状态，同时用固定的 group: deploy-production 保证同一环境串行部署。其他防重复手段：if: github.actor != 'dependabot[bot]' 跳过机器人，github.event.pull_request.draft == false 跳过草稿 PR。

5.1 runs-on 选型#

• ubuntu-latest：最便宜、启动最快（通常 10 秒内）、生态最全，绝大多数场景首选。
• windows-latest：构建 .NET、MSI、原生 Windows 应用时用，启动慢，计费是 Linux 的 2 倍。
• macos-latest：构建 iOS / macOS 必需，计费是 Linux 的 10 倍，能不用就不用。
• 自托管 runner：需要访问内网、需要更强硬件、或想省成本时用。代价是自己维护（系统更新、磁盘清理），以及最要命的一条：fork 来的 PR 能在你的机器上执行任意代码，除非配了环境与审批。

5.2 needs 依赖与并行执行#

1
jobs:
2
  deploy:
3
    needs: [lint, test]       # lint / test 两个 job 并行跑，都成功才轮到 deploy
4
    runs-on: ubuntu-latest
5
    steps: [{ run: echo deploy }]

没有 needs 关系的 job 默认并行；加上 needs 就形成 DAG，deploy 会等 lint 与 test 都成功才开始。也能用 needs.lint.outputs.xxx 在 job 间传数据。

5.3 条件执行#

常用条件：github.ref、github.event_name、success() / failure() / always()、needs.job.result。failure() 常用来做“失败了才发通知”“失败了才上传日志”，形如 if: failure()；只在主干部署用 if: github.ref == 'refs/heads/master' && github.event_name == 'push'。

5.4 matrix 矩阵构建#

1
jobs:
2
  test:
3
    runs-on: ${{ matrix.os }}
4
    strategy:
5
      fail-fast: false
6
      matrix:
7
        os: [ubuntu-latest, windows-latest]
8
        node: [20, 22]
9
        exclude: [{ os: windows-latest, node: 20 }]
10
        include: [{ os: ubuntu-latest, node: 22, coverage: true }]

matrix 把组合自动展开成多个并行 job，用一份 YAML 覆盖“多 Node 版本 x 多操作系统”。exclude 剔除不需要的组合，include 追加额外变量。fail-fast 默认 true（任一组合失败就取消其余），跑兼容性验证时设为 false，一次性看到全部平台的失败情况。

6.1 checkout 与 setup-node#

1
      - uses: actions/checkout@v4
2
        with: { fetch-depth: 0 }        # 需要 git 历史（如生成 changelog）时设为 0
3
      - uses: actions/setup-node@v4
4
        with: { node-version: 22, cache: pnpm }

checkout 默认 fetch-depth: 1 浅克隆，速度快；需要 git describe、生成 changelog 或做差异分析时要显式设 0。setup-node 的 cache 支持 npm / yarn / pnpm，缓存包管理器全局 store，key 默认基于锁文件哈希，这一行通常能省掉 30% 到 70% 的安装时间。

6.2 actions/cache 自定义缓存#

1
      - uses: actions/cache@v4
2
        with:
3
          path: |
4
            node_modules/.vite
5
            ~/.local/share/pnpm/store
6
          key: ${{ runner.os }}-build-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
7
          restore-keys: ${{ runner.os }}-build-

缓存 key 的设计核心是分层降级：第一级带 github.sha，精确命中“这个 commit 曾构建过”（重跑场景）；第二级 restore-keys 去掉 sha，命中“同一锁文件的任意一次构建”；第三级只带操作系统兜底。提升命中率的关键：把稳定的因子放前面（runner.os -> 语言版本 -> 锁文件哈希 -> sha）；锁文件是缓存的锚点，它一变依赖缓存必然失效，这是正确行为，不要绕过；缓存路径要精确，跨平台缓存整个 node_modules 经常因二进制平台相关而出错，更稳妥的是缓存包管理器 store 或构建工具自己的缓存目录。缓存有 10GB 上限，且 7 天不访问会被清理。

6.3 artifact 上传与下载#

1
      - uses: actions/upload-artifact@v4
2
        with:
3
          name: dist-${{ github.sha }}
4
          path: dist/
5
          retention-days: 30
6
      # 另一个 job 中
7
      - uses: actions/download-artifact@v4
8
        with: { name: "dist-${{ github.sha }}", path: dist }

artifact 是跨 job 传递文件的唯一官方方式（同一 job 内的 step 共享文件系统，不需要它）。retention-days 可以用来保存“上一版制品”以实现回滚，是最省事的方案。

6.4 发布与镜像构建#

1
      - uses: softprops/action-gh-release@v2
2
        if: startsWith(github.ref, 'refs/tags/v')
3
      - uses: docker/build-push-action@v6
4
        with:
5
          context: .
6
          push: true
7
          platforms: linux/amd64,linux/arm64
8
          tags: ${{ steps.meta.outputs.tags }}
9
          cache-from: type=gha
10
          cache-to: type=gha,mode=max

cache-from: type=gha 用的是 Actions 自带的缓存后端，专为 Docker 层缓存设计，比手工管 actions/cache 更贴合。

7.1 env、vars、secrets 的区别与优先级#

作用域覆盖顺序由窄到宽生效：step 级 env > job 级 env > workflow 级 env。secrets 与 vars 需要用 ${{ }} 表达式取值注入。

1
env: { NODE_ENV: production }      # workflow 级，被下面 job 级覆盖
2
jobs:
3
  deploy:
4
    env: { TARGET: production }   # job 级，覆盖同名 workflow 变量
5
    steps:
6
      - run: echo "部署到 $TARGET"
7
        env: { DEPLOY_HOST: "${{ secrets.DEPLOY_HOST }}" }   # step 级

7.2 GITHUB_TOKEN、权限与审批门禁#

每次运行都会自动获得 GITHUB_TOKEN，默认权限在仓库设置里可配（历史默认读写全开，现在新仓库默认只读）。显式声明权限是最佳实践，也是安全审计最容易挑出来的问题。

1
permissions: { contents: read }   # workflow 顶层：保守基线
2
jobs:
3
  publish:
4
    permissions: { contents: read, packages: write, id-token: write }

在 Settings -> Environments 里创建 staging、production，可配置必需审批人（人工点击才继续）、允许部署的分支、以及该环境专属 secrets。这是用 GitHub 原生能力实现“持续交付”的那道人工闸门。

部署 job 上声明环境即接入这道门禁：

1
  deploy-prod:
2
    environment: { name: production, url: https://sakura-hu.top }

7.3 OIDC 免密钥访问云厂商#

把云厂商 AccessKey 存成长期 secret 是常见反模式：一旦泄露，攻击者可以一直用。OIDC 让 GitHub 给 job 签发短期 token，云平台验证签发者与仓库身份后临时发放凭证，仓库里不再存任何云凭证。

用法是 aws-actions/configure-aws-credentials 传 role-to-assume（形如 arn:aws:iam::123456789012:role/github-actions-deploy）与 aws-region，并给 job 声明 permissions: { id-token: write }。

AWS、GCP、Azure、阿里云、腾讯云都已支持。

7.4 常见误用#

• 把密钥硬编码进 YAML。即使删掉，它也已躺在 git 历史里。密钥一旦入库，唯一正确的处理是立即轮换。
• 在 PR 里打印 secrets。echo ${{ secrets.X }} 会写进日志，虽然 GitHub 会打码，但打码可以被编码、切片绕过，不要依赖它。
• pull_request_target 的陷阱。这个触发器能在有 secrets 的上下文里运行。一旦你在这个 workflow 里 checkout 并执行 PR 的代码（比如装了对方改过的依赖），就等于把 secrets 交给任意陌生人。要用必须配环境审批，且绝不执行 PR 提供的代码。
• 把 secrets 传给第三方 action。第三方 action 能读走你上下文里的所有东西，用之前先看源码。

8.1 完整 workflow#

1
name: Deploy Blog
2
on:
3
  push: { branches: [master] }
4
  workflow_dispatch:
5

6
concurrency: { group: deploy-blog, cancel-in-progress: false }
7
permissions: { contents: read }
8

9
jobs:
10
  build-and-deploy:
11
    runs-on: ubuntu-latest
12
    steps:
13
      - uses: actions/checkout@v4
14
      - uses: pnpm/action-setup@v4
15
        with: { version: 9 }
16
      - uses: actions/setup-node@v4
17
        with: { node-version: 22, cache: pnpm }
18
      - run: pnpm install --frozen-lockfile
19
        env: { CI: "1" }
20
      - run: pnpm build
21
        env: { CI: "1" }
22
      - name: 校验产物
23
        run: |
24
          test -d dist || { echo "dist 不存在"; exit 1; }
25
          test -f dist/index.html || { echo "缺少 index.html"; exit 1; }
26
      - name: 通过 SFTP 上传到服务器
27
        uses: wlixcc/SFTP-Deploy-Action@v1.2.5
28
        with:
29
          server: ${{ secrets.DEPLOY_HOST }}
30
          username: ${{ secrets.DEPLOY_USER }}
31
          password: ${{ secrets.DEPLOY_PASS }}
32
          port: 22
33
          local_path: ./dist/*
34
          remote_path: /www/wwwroot/sakura-hu.top/
35
          sftp_only: true
36
          delete_remote_files: false

8.2 secrets 配置与增量同步#

在 Settings -> Secrets and variables -> Actions 新建三个 Repository secrets：

更稳妥的是用 SSH 密钥：公钥放服务器 ~/.ssh/authorized_keys，私钥存成 DEPLOY_KEY，action 里换成 key: ${{ secrets.DEPLOY_KEY }}；密码方案配置简单但没法轮换和精细授权。给部署单独建受限用户、只授予站点目录写权限，比用 root 安全得多。

delete_remote_files: false 表示只覆盖同名文件、不删服务器上多余文件：好处是本地产物缺了某文件时旧文件还在，不会硬性 404；坏处是删掉的文章会一直留在服务器上。对带 hash 文件名的静态站点（Astro 产出 index.a1b2c3.js 这类名字），全量上传代价可观——每次构建资源 hash 都可能变，几百个小文件逐个走 SFTP，单次部署要几分钟。要做增量同步，rsync 更合适，它按“大小 + 修改时间”判断差异：

1
      - name: 写入部署私钥并增量同步
2
        run: |
3
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
4
          printf '%s' "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/key && chmod 600 ~/.ssh/key
5
          ssh-keyscan ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts 2>/dev/null
6
          rsync -avz --delete --exclude='.well-known/' -e "ssh -i ~/.ssh/key" \
7
            ./dist/ ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}:/www/wwwroot/sakura-hu.top/

--delete 是开启的：用了 rsync 就该做完整镜像同步，保证“服务器状态 = 构建产物”，避免残留文件造成诡异问题（比如旧 service worker 缓存住旧页面）。--exclude 用来保护服务器上证书校验之类的目录；-z 开压缩，静态站点压缩率很高。

8.3 变体：同步到对象存储与 CDN#

托管在对象存储（COS / OSS / S3 / R2）时把最后一步换掉即可。要点是静态资源长缓存、HTML 短缓存。

1
rclone sync ./dist/_astro oss:my-bucket/_astro \
2
  --header-upload "Cache-Control: public, max-age=31536000, immutable"
3
rclone sync ./dist oss:my-bucket --exclude "_astro/**" \
4
  --header-upload "Cache-Control: public, max-age=300"

sync 会删除目标端多余文件（双向对齐，保证远端与构建产物一致），copy 只增不删，远端还存着别的东西时用 copy。

9.1 多阶段 Dockerfile#

1
FROM node:22-alpine AS builder
2
WORKDIR /app
3
RUN corepack enable
4
COPY package.json pnpm-lock.yaml ./
5
RUN pnpm install --frozen-lockfile
6
COPY . .
7
RUN pnpm build
8
FROM nginx:1.27-alpine AS runner
9
COPY --from=builder /app/dist /usr/share/nginx/html
10
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
11
  CMD wget -qO- http://127.0.0.1/ || exit 1
12
CMD ["nginx", "-g", "daemon off;"]

构建工具链只存在于构建阶段，运行镜像里完全没有，体积更小、攻击面更小。不变的层放前面（先 COPY 锁文件装依赖，最后才 COPY . .），改业务代码时依赖层能命中缓存。

9.2 构建并推送的 workflow#

1
name: Build and Push Image
2
on:
3
  push: { branches: [master], tags: ["v*"] }
4
permissions: { contents: read, packages: write }
5

6
jobs:
7
  docker:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v4
11
      - uses: docker/setup-buildx-action@v3
12
      - uses: docker/login-action@v3
13
        with:
14
          registry: ghcr.io
15
          username: ${{ github.actor }}
16
          password: ${{ secrets.GITHUB_TOKEN }}
17
      - id: meta
18
        uses: docker/metadata-action@v5
19
        with:
20
          images: ghcr.io/${{ github.repository }}
21
          tags: |
22
            type=semver,pattern={{version}}
23
            type=sha,prefix=sha-,format=short
24
            type=raw,value=latest,enable={{is_default_branch}}
25
      - uses: docker/build-push-action@v6
26
        with:
27
          context: .
28
          push: true
29
          platforms: linux/amd64,linux/arm64
30
          tags: ${{ steps.meta.outputs.tags }}
31
          cache-from: type=gha
32
          cache-to: type=gha,mode=max

推 Docker Hub 只需把 registry 换成 docker.io、images 换成 用户名/仓库名，密码用 DOCKERHUB_TOKEN。

9.3 标签策略#

生产部署永远不要用 latest，用 sha- 或语义化版本，回滚时把 tag 换回上一版即可。注意跨平台构建（linux/amd64,linux/arm64）走 QEMU 模拟，耗时是单平台的好几倍；只有 x86 服务器时去掉 platforms 能显著提速。

9.4 服务器拉取新镜像并重启#

最轻量的做法是服务器上放一个脚本，由流水线通过 SSH 触发：

1
#!/usr/bin/env bash
2
set -euo pipefail
3
IMAGE="ghcr.io/owner/blog:sha-${1:?usage: deploy.sh <sha>}"
4
echo "$GHCR_TOKEN" | docker login ghcr.io -u owner --password-stdin
5
docker pull "$IMAGE"
6
docker compose up -d --no-deps --force-recreate blog
7

8
for i in $(seq 1 15); do
9
  curl -fsS -m 3 http://127.0.0.1:8080/healthz >/dev/null && exit 0
10
  sleep 2
11
done
12

13
echo "健康检查失败，回滚"
14
PREV=$(cat /opt/blog/.previous-image)
15
sed -i "s|image:.*|image: ${PREV}|" docker-compose.yml
16
docker compose up -d --no-deps --force-recreate blog
17
exit 1

1
      - uses: appleboy/ssh-action@v1
2
        with:
3
          host: ${{ secrets.DEPLOY_HOST }}
4
          username: ${{ secrets.DEPLOY_USER }}
5
          key: ${{ secrets.DEPLOY_KEY }}
6
          script: /opt/blog/deploy.sh ${{ github.sha }}

脚本把成功部署的镜像名写进 .previous-image，回滚时读出来用——这就是最简单可靠的一键回滚。

11.1 四种策略对比#

蓝绿的核心是两套环境 + 一个流量开关：新版部署到绿色环境 -> 跑冒烟测试 -> 负载均衡把流量从蓝色切到绿色 -> 观察后保留蓝色作为回滚目标，回滚就是再切一次。

金丝雀的核心是按比例放量 + 指标自动决策：导入 1% 流量 -> 观察错误率、延迟、核心业务指标 -> 正常则 5% -> 25% -> 50% -> 100%，任一步恶化就自动回滚。相比蓝绿，它多了“在小流量下发现测试覆盖不到的问题”的能力，代价是需要完善的指标监控与流量切分。实践中两者组合：蓝绿做底层发布单元，金丝雀做流量层策略。

11.2 健康检查与就绪探针#

切换流量的前提是新版本真的能服务。存活探针（liveness）判断进程是否还在，失败就重启；就绪探针（readiness）判断能否接流量，失败就从负载均衡摘除但不重启。

1
    readinessProbe:
2
      httpGet: { path: /healthz, port: 8080 }
3
      initialDelaySeconds: 5
4
      periodSeconds: 5
5
    livenessProbe:
6
      httpGet: { path: /livez, port: 8080 }

/healthz 不应只检查进程存活，还应检查下游依赖（数据库、缓存）。流水线的部署脚本必须把健康检查当门禁：部署完成 -> 轮询健康端点最多 N 次 -> 全部失败就自动回滚并让 job 失败。没有这一步，所谓自动部署只是自动把故障推上线。

11.3 数据库迁移的处理原则#

数据库是 CI/CD 里最难原子化的部分——代码可以两套并存，schema 不能。三条原则：

1. 向前兼容。先上兼容新旧两版的 schema 变更，再上使用新结构的代码。
2. 先迁移后发布。迁移脚本独立执行，且要能在旧版本应用还在跑时执行而不出错（新增可空列、新增表、加索引都符合）。
3. 可回滚的迁移。删表、删列、改类型必须拆成多次发布。回滚应用代码时数据库不应该需要回滚，因为迁移本身向前兼容。

1
发布 1：新增 new_status 列（可空）-> 代码双写 status 和 new_status
2
发布 2：数据迁移脚本回填 new_status
3
发布 3：代码只读 new_status
4
发布 4：删除旧列 status

用了 ORM 自动建表的话，务必关掉生产环境的 synchronize / auto-migrate，迁移必须是一次性脚本且能被审批。

17.1 触发器与并发#

1
on:
2
  push:
3
    branches: [master, "release/**"]
4
    tags: ["v*"]
5
    paths: ["src/**", "package.json"]
6
  pull_request: { branches: [master] }
7
  schedule:
8
    - cron: "0 2 * * *"        # UTC，北京时间为 10:00
9
  workflow_dispatch:
10
    inputs:
11
      env: { type: choice, options: [staging, production] }
12

13
concurrency:
14
  group: ${{ github.workflow }}-${{ github.ref }}
15
  cancel-in-progress: true     # 部署类改 false

17.2 Job 骨架#

1
permissions: { contents: read }
2

3
jobs:
4
  build:
5
    runs-on: ubuntu-latest
6
    strategy: { matrix: { node: [20, 22] } }
7
    steps:
8
      - uses: actions/checkout@v4
9
      - uses: actions/setup-node@v4
10
        with: { node-version: "${{ matrix.node }}", cache: npm }
11
      - run: npm ci && npm run build
12
        env: { API_BASE: "${{ vars.API_BASE }}", TOKEN: "${{ secrets.TOKEN }}" }
13
      - uses: actions/upload-artifact@v4
14
        with: { name: "dist-${{ matrix.node }}", path: dist/ }
15
  deploy:
16
    needs: build
17
    if: github.ref == 'refs/heads/master'
18
    environment: production
19
    runs-on: ubuntu-latest
20
    steps:
21
      - uses: actions/download-artifact@v4
22
        with: { name: dist-22, path: dist }

17.3 常见坑一览#