🔄 CI/CD：从代码提交到生产上线

CI/CD 是什么

CI (Continuous Integration)：开发者频繁将代码合并到主分支，每次合并自动触发构建和测试，尽早发现集成问题。

CD (Continuous Delivery/Deployment)：代码通过所有测试后，自动部署到预发布/生产环境。Delivery 需要人工确认，Deployment 全自动。

为什么你必须有 CI/CD

Pipeline 基础架构

一个成熟的 CI/CD Pipeline 通常包含以下阶段，每个阶段失败都会阻断后续阶段：

Pipeline 设计原则

GitHub Actions — 事实标准

GitHub Actions 已经成为 CI/CD 的事实标准。原因：与 GitHub 深度集成、生态丰富、免费额度充足、YAML 配置简单。

基础 Workflow 结构

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# 同一 PR 只保留最新一次运行
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check

  test:
    runs-on: ubuntu-latest
    needs: lint  # lint 通过后才跑测试
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test:coverage
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

矩阵构建 — 多版本并行

jobs:
  test:
    strategy:
      fail-fast: false  # 一个失败不影响其他
      matrix:
        node-version: [18, 20, 22]
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

缓存最佳实践

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 方式1: 使用 setup-node 内置缓存
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'  # 自动缓存 pnpm store

      # 方式2: 手动缓存 (更灵活)
      - uses: actions/cache@v4
        with:
          path: |
            ~/.pnpm-store
            .next/cache
            node_modules
          key: ${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

Docker 构建与推送

jobs:
  docker:
    runs-on: ubuntu-latest
    needs: [test, build]
    permissions:
      contents: read
      packages: write  # 推送到 GHCR
    steps:
      - uses: actions/checkout@v4

      # Docker Buildx — 多平台构建 + 缓存
      - uses: docker/setup-buildx-action@v3

      # QEMU — ARM64 等异构构建
      - uses: docker/setup-qemu-action@v3

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

部署到 VPS (SSH Deploy)

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: [docker]
    if: github.ref == 'refs/heads/main'
    environment: production  # 需要 GitHub Environment 审批
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: deploy
          key: ${{ secrets.DEPLOY_SSH_KEY }}
          script: |
            docker pull ghcr.io/myorg/myapp:latest
            docker compose up -d
            sleep 5
            curl -f http://localhost:3000/health || exit 1

GitHub Actions 优劣势

GitLab CI — 自托管首选

如果你的代码托管在 GitLab（尤其自托管 GitLab），GitLab CI/CD 是自然选择。它比 GitHub Actions 更早成熟，Pipeline 概念更清晰。

# .gitlab-ci.yml
stages:
  - lint
  - test
  - build
  - deploy

variables:
  DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
  # 全局缓存 key
  CACHE_KEY: pnpm-${CI_COMMIT_BRANCH}

# 默认配置
default:
  image: node:22
  before_script:
    - pnpm install --frozen-lockfile
  cache:
    key: $CACHE_KEY
    paths:
      - .pnpm-store
      - node_modules

lint:
  stage: lint
  script:
    - pnpm lint
    - pnpm type-check

test:
  stage: test
  script:
    - pnpm test:coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/'  # 自动提取覆盖率
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

build:
  stage: build
  script:
    - pnpm build
  artifacts:
    paths:
      - dist/

docker:
  stage: build
  needs: [build]
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
  script:
    - docker build -t $DOCKER_IMAGE .
    - docker push $DOCKER_IMAGE

deploy:staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.myapp.com
  script:
    - ssh deploy@staging "docker pull $DOCKER_IMAGE && docker compose up -d"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:production:
  stage: deploy
  environment:
    name: production
    url: https://myapp.com
  when: manual  # 需手动触发
  script:
    - ssh deploy@prod "docker pull $DOCKER_IMAGE && docker compose up -d"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

GitLab CI 独有能力

其他 CI/CD 平台

新兴趋势：CI/CD 即代码的下一代

// Dagger: 用 Go 写 CI (不是 YAML!)
package main

import (
    "context"
    "os"
    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()
    client, _ := dagger.Connect(ctx, dagger.WithLogOutput(os.Stdout))
    defer client.Close()

    src := client.Host().Directory()

    // 构建
    builder := client.Container().From("node:22").
        WithMountedDirectory("/app", src).
        WithWorkdir("/app").
        WithExec([]string{"npm", "ci"}).
        WithExec([]string{"npm", "run", "build"})

    // 测试
    builder.WithExec([]string{"npm", "test"})

    // 导出
    builder.Directory("dist").Export(ctx, "./dist")
}

# Earthfile
VERSION 0.8

build:
    FROM node:22
    COPY package.json pnpm-lock.yaml ./
    RUN pnpm install --frozen-lockfile
    COPY . .
    RUN pnpm build
    SAVE ARTIFACT dist /dist

test:
    FROM +build
    RUN pnpm test

docker:
    FROM +build
    SAVE IMAGE --push myapp:latest

部署策略详解

部署是 CI/CD 中风险最高的环节。选择正确的策略，决定了上线事故的影响范围。

1. 直接部署 (Recreate)

2. 滚动部署 (Rolling Update)

# Kubernetes 滚动部署配置
spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1        # 最多多起 1 个 Pod
      maxUnavailable: 0   # 不允许任何 Pod 不可用

3. 蓝绿部署 (Blue-Green)

# Nginx 蓝绿切换
upstream backend {
    server blue:3000;   # 当前活跃
    # server green:3000;  # 切换时注释蓝，取消注释绿
}

# 自动化脚本
# sed -i 's/server blue/server green/' /etc/nginx/conf.d/app.conf
# nginx -s reload

4. 金丝雀部署 (Canary)

# Argo Rollouts 金丝雀配置
apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
      - setWeight: 5
      - pause: {duration: 5m}    # 观察 5 分钟
      - setWeight: 25
      - pause: {duration: 5m}
      - setWeight: 50
      - pause: {duration: 10m}
      - setWeight: 100
      canaryService: myapp-canary
      stableService: myapp-stable

5. 功能开关部署 (Feature Flag)

// 代码中检查功能开关
if (featureFlags.isEnabled('new-dashboard', { userId: user.id })) {
  renderNewDashboard();
} else {
  renderOldDashboard();
}

策略选择矩阵

高级模式

Monorepo CI/CD

# .github/workflows/ci.yml — 使用 Turborepo
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需要完整 git 历史计算 diff

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # Turborepo 自动检测变更的包，只构建/测试受影响的
      - run: pnpm turbo build --filter=...[HEAD^1]
      - run: pnpm turbo test --filter=...[HEAD^1]

      # Nx 的等价写法
      # - run: npx nx affected --target=build
      # - run: npx nx affected --target=test

Preview Deployments

# Vercel Preview 自动完成，零配置
# Cloudflare Pages 也原生支持

# 自托管方案：Docker + 子域名
jobs:
  preview:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - run: |
          PREVIEW_DOMAIN="pr-${{ github.event.number }}.preview.myapp.com"
          docker build -t myapp:pr-${{ github.event.number }} .
          # 部署到预览集群
          ssh deploy@preview "docker run -d --name pr-${{ github.event.number }} \
            -e VIRTUAL_HOST=$PREVIEW_DOMAIN myapp:pr-${{ github.event.number }}"
          echo "Preview: https://$PREVIEW_DOMAIN"

  # PR 关闭时清理
  cleanup:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - run: ssh deploy@preview "docker rm -f pr-${{ github.event.number }}"

数据库迁移在 CI/CD 中

# 两阶段迁移策略
# Phase 1: 添加新列（不删旧列）
jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - run: |
          # 1. 先跑迁移
          npx prisma migrate deploy
          # 2. 验证迁移成功
          npx prisma migrate status

  deploy:
    needs: migrate
    steps:
      - run: |
          # 3. 部署新代码（兼容新旧 schema）
          docker compose up -d

# Phase 2: 下一个部署周期删除旧列
# 删除列的迁移要在新代码运行稳定至少一个周期后才做

自动回滚

# 健康检查 + 自动回滚
deploy:
  steps:
    - name: Deploy
      run: docker compose up -d

    - name: Health Check (60s grace)
      run: |
        for i in $(seq 1 12); do
          if curl -f http://localhost:3000/health; then
            echo "✅ Healthy"
            exit 0
          fi
          sleep 5
        done
        echo "❌ Health check failed"
        exit 1

    - name: Rollback on Failure
      if: failure()
      run: |
        docker compose down
        docker compose up -d --build  # 重新用上一个镜像
        echo "⚠️ Rolled back due to health check failure"

CI/CD 安全

CI/CD Pipeline 是攻击者的黄金目标——拿到 Pipeline 权限 = 拿到生产环境。

# 安全的 GitHub Actions 配置示例
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read       # 最小权限
      packages: write      # 只写包注册表
      id-token: write      # OIDC 需要
    environment:
      name: production
      # 保护规则：需要 1 人审批 + 等待 5 分钟
    steps:
      # ✅ 用 commit SHA 而非 tag
      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4

      # ✅ 用 OIDC 而非 Access Key
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/deploy-role
          aws-region: ap-northeast-1

      # ✅ 避免注入：使用环境变量而非直接插值
      - name: Deploy
        env:
          BRANCH: ${{ github.head_ref }}
        run: |
          # 不要: echo "Deploying ${{ github.head_ref }}"
          # 要用: 
          echo "Deploying $BRANCH"

成本优化

# 只在相关文件变更时运行
on:
  push:
    paths:
      - 'src/**'
      - 'package.json'
      - 'pnpm-lock.yaml'
    paths-ignore:
      - '**.md'
      - 'docs/**'

# 或者用 path-filtering Action
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      backend: ${{ steps.filter.outputs.backend }}
      frontend: ${{ steps.filter.outputs.frontend }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            backend:
              - 'backend/**'
            frontend:
              - 'frontend/**'

常见反模式

# 🚫 Bad
- run: |
    npm ci
    npm run lint
    npm run test
    npm run build
    docker build .
    docker push ...

# ✅ Good
- name: Install dependencies
  run: npm ci
- name: Lint
  run: npm run lint
- name: Test
  run: npm run test
- name: Build
  run: npm run build

# 失败通知
- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "❌ Pipeline failed: ${{ github.workflow }}",
        "blocks": [{"type": "section", "text": {"type": "mrkdwn",
          "text": "*Failed:* ${{ github.workflow }}\n*Branch:* ${{ github.ref }}\n*Commit:* ${{ github.sha }}"
        }}]
      }

决策树：选哪个 CI/CD？

实战模板合集

模板 1: Next.js + Vercel 全自动

# 零配置！Vercel 原生集成 GitHub
# Push to main → 自动部署
# PR → 自动 Preview
# 只需在 Vercel Dashboard 连接仓库

# 如果需要额外检查：
name: CI
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check
      - run: pnpm test

模板 2: Docker + VPS 部署

name: Build & Deploy
on:
  push:
    branches: [main]

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

  docker:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:${{ github.sha }}
            ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: docker
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Deploy
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: deploy
          key: ${{ secrets.DEPLOY_SSH_KEY }}
          script: |
            docker compose pull
            docker compose up -d --remove-orphans
            sleep 10
            curl -f http://localhost:3000/health || (docker compose rollback && exit 1)

      - name: Notify Success
        if: success()
        run: echo "✅ Deployed ${{ github.sha }} to production"

      - name: Notify Failure
        if: failure()
        run: echo "❌ Deploy failed, rolled back"

模板 3: Python FastAPI + Celery

name: Python CI/CD
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install ruff mypy
      - run: ruff check .
      - run: mypy src/

  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_DB: test, POSTGRES_USER: test, POSTGRES_PASSWORD: test }
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      redis:
        image: redis:7
        ports: ['6379:6379']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -e ".[dev]"
      - run: pytest --cov=src -v
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test
          REDIS_URL: redis://localhost:6379/0

模板 4: 语义化版本自动发布

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Conventional Commits → 自动计算版本号
      - uses: python-semantic-release/python-semantic-release@v9
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

      # 或者用 release-please (Google 出品)
      # - uses: google-github-actions/release-please-action@v4
      #   with:
      #     release-type: node

模板 5: 多环境部署 (Dev → Staging → Prod)

name: Deploy Pipeline

on:
  push:
    branches: [main, develop]

jobs:
  deploy-dev:
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: development
    steps:
      - run: echo "Deploy to dev"

  deploy-staging:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: echo "Deploy to staging"

  deploy-prod:
    needs: deploy-staging
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: production
      # 需要 1 人审批 + 等待 5 分钟
    steps:
      - run: echo "Deploy to production"

  # Tag 触发直接部署生产 (热修复)
  deploy-hotfix:
    if: startsWith(github.ref, 'refs/tags/hotfix-')
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: echo "Hotfix deploy to production"

🔗 Agent 架构关联