14. CI/CD 流水线中集成 Docker：GitHub Actions 自动构建部署

14. CI/CD 流水线中集成 Docker：GitHub Actions 自动构建部署

每次改完代码，你都要经历这套"手动三连"：本地 docker build → docker push → SSH 到服务器 docker pull + docker compose up -d。改一行代码，操作五分钟。要是哪天忘了推镜像、忘了重启容器，线上跑的还是老版本，排查半天才发现"哦，我没部署"。这种日子，该结束了。CI/CD 就是来帮你把这些重复操作全自动化的——代码一推，镜像自动构建、自动推送、自动部署，你只管写代码就行。

▲ 把"手动三连"交给流水线：代码一推，构建、测试、部署一条龙自动跑完。

一、什么是 CI/CD？Docker 在里面扮演什么角色？

1.1 一分钟搞懂 CI/CD

CI（持续集成） 和 CD（持续部署/交付） 听起来高大上，但核心思想很朴素：

串起来就是：代码提交 → 自动测试 → 自动构建镜像 → 自动推送 → 自动部署。整条链路无人值守，跑完线上就是最新的。

1.2 Docker 在 CI/CD 中的角色

Docker 是这条流水线里的"标准化打包环节"：

代码提交 → [自动测试] → [Docker 构建镜像] → [推送镜像到仓库] → [服务器拉取并部署]
                          ↑                   ↑                 ↑
                    你的 Dockerfile     Docker Hub / ACR     docker compose up

▲ 每一步都由流水线自动接力，你只需要把代码推上去。

为什么用 Docker 做 CI/CD 特别合适？ 因为镜像天然就是"不可变产物"——同一个 Dockerfile + 同一份代码，在任何机器上构建出来的镜像都一模一样。这保证了"开发能跑，生产也能跑"。

1.3 常见的 CI/CD 工具

本文以 GitHub Actions 为例，因为它免费、配置简单、跟 GitHub 仓库无缝集成，上手最快。文章末尾也会简要介绍 Jenkins 和 GitLab CI 的等效方案。

二、GitHub Actions 基础概念

在动手写配置之前，先搞清楚几个核心概念：

用一个流程图理解它们的关系：

Event（push 到 main）
  │
  ▼
Workflow（docker-build.yml）
  │
  ├── Job 1: build-and-push
  │     ├── Step 1: checkout 代码
  │     ├── Step 2: 登录 Docker Hub
  │     ├── Step 3: 构建镜像
  │     └── Step 4: 推送镜像
  │
  └── Job 2: deploy（依赖 Job 1 完成）
        ├── Step 1: SSH 到服务器
        └── Step 2: docker compose up -d

三、实战：编写完整的 GitHub Actions 工作流

3.1 项目结构

假设你有一个简单的 Node.js 项目（换成 Python、Java 都一样，改 Dockerfile 就行）：

my-app/
├── .github/
│   └── workflows/
│       └── docker-build.yml     ← 工作流文件
├── src/
│   └── index.js
├── docker-compose.yml
├── Dockerfile
├── package.json
└── .dockerignore

3.2 Dockerfile（构建目标）

FROM node:20-alpine
​
WORKDIR /app
​
# 先复制依赖文件，利用 Docker 缓存层
COPY package.json package-lock.json ./
RUN npm ci –production
​
# 再复制源码
COPY src/ ./src/
​
EXPOSE 3000
​
CMD ["node", "src/index.js"]

3.3 完整的工作流文件

这是本文的核心产出——一个可以直接拿去用的 GitHub Actions 配置：

# .github/workflows/docker-build.yml
​
name: Docker Build and Deploy
​
on:
 # 推送到 main 分支时触发
push:
  branches: [main]
   # 打 tag 时也触发（用于发布正式版本）
  tags: ['v*']
 # 允许手动触发
workflow_dispatch:
​
# 定义环境变量
env:
DOCKER_IMAGE: your-dockerhub-username/my-app
 # GitHub 自带的容器镜像仓库（可选方案）
GHCR_IMAGE: ghcr.io/${{ github.repository }}
​
jobs:
 # ========== Job 1：构建并推送镜像 ==========
build-and-push:
  runs-on: ubuntu-latest
  steps:
     # Step 1: 拉取代码
    – name: Checkout code
      uses: actions/checkout@v4
​
     # Step 2: 设置 Docker Buildx（支持高级构建特性）
    – name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3
​
     # Step 3: 登录 Docker Hub
    – name: Login to Docker Hub
      uses: docker/login-action@v3
      with:
        username: ${{ secrets.DOCKERHUB_USERNAME }}
        password: ${{ secrets.DOCKERHUB_TOKEN }}
​
     # Step 4: 登录 GitHub Container Registry（可选，双推）
    – name: Login to GHCR
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
​
     # Step 5: 生成镜像标签
    – name: Generate image tags
      id: meta
      run: |
        # 获取 Git 短哈希（用于唯一标识每次构建）
        SHORT_SHA=$(echo ${{ github.sha }} | cut -c1-7)
        echo "sha_tag=${SHORT_SHA}" >> $GITHUB_OUTPUT
​
        # 根据触发方式生成不同的标签
        if [[ "${{ github.ref_type }}" == "tag" ]]; then
          # 打 tag 触发：用版本号 + latest
          VERSION=${GITHUB_REF_NAME#v}
          echo "tags=${{ env.DOCKER_IMAGE }}:${VERSION},${{ env.DOCKER_IMAGE }}:latest" >> $GITHUB_OUTPUT
          echo "env_name=production" >> $GITHUB_OUTPUT
        elif [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
          # push 到 main：用 dev + sha
          echo "tags=${{ env.DOCKER_IMAGE }}:dev,${{ env.DOCKER_IMAGE }}:${SHORT_SHA}" >> $GITHUB_OUTPUT
          echo "env_name=dev" >> $GITHUB_OUTPUT
        fi
​
     # Step 6: 构建并推送镜像（带缓存优化）
    – name: Build and push
      uses: docker/build-push-action@v5
      with:
        context: .
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: |
          org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
          org.opencontainers.image.revision=${{ github.sha }}
         # 缓存优化：利用 GitHub Actions 缓存
        cache-from: type=gha
        cache-to: type=gha,mode=max
​
 # ========== Job 2：部署到服务器 ==========
deploy:
  needs: build-and-push   # 必须等 Job 1 完成
  runs-on: ubuntu-latest
   # 仅在推送到 main 或打 tag 时部署
  if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
  steps:
    – name: Deploy to server via SSH
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.SERVER_HOST }}
        username: ${{ secrets.SERVER_USER }}
        key: ${{ secrets.SERVER_SSH_KEY }}
        port: 22
        script: |
          cd /opt/my-app
​
          # 拉取最新镜像
          docker compose pull
​
          # 重新创建容器（只替换有变化的服务）
          docker compose up -d –remove-orphans
​
          # 清理悬空镜像，释放磁盘空间
          docker image prune -f
​
          # 打印当前运行的容器状态
          docker compose ps
​
          echo "✅ 部署完成！镜像版本：${{ needs.build-and-push.outputs.image_tag }}"

3.4 镜像标签策略详解

上面用了一段 Shell 脚本来生成标签，这里用表格总结一下策略：

为什么要同时打两个标签？

• dev / 1.2.3：可追踪的固定版本，出问题可以回滚

• a1b2c3d（Git SHA）：精确到"哪次提交构建的"，排查问题利器

• latest：方便本地开发时 docker pull 拿最新版

四、配置 GitHub Secrets（关键步骤）

工作流里用到了好几个敏感信息，绝对不能硬编码在 YAML 文件里（推到公开仓库就泄露了）。需要用 GitHub Secrets：

4.1 需要配置的 Secrets

4.2 配置步骤

重要提醒：Docker Hub 的 Token 权限选择 Read/Write，否则推送镜像时会报 denied: requested access to the resource is denied。

4.3 服务器端准备

在你的云服务器上，确保以下环境已就绪：

# 1. 安装 Docker 和 Docker Compose（参考本系列第 2 篇）
docker –version
docker compose version
​
# 2. 登录 Docker Hub（让服务器有拉取私有镜像的权限）
docker login
​
# 3. 创建应用目录，放好 docker-compose.yml
mkdir -p /opt/my-app
cd /opt/my-app
​
# 4. 创建 docker-compose.yml（服务器版本）
cat > docker-compose.yml << 'EOF'
version: "3.8"
​
services:
app:
  image: your-dockerhub-username/my-app:dev
  container_name: my-app
  ports:
     – "3000:3000"
  environment:
     – NODE_ENV=production
     – DB_HOST=${DB_HOST}
   restart: always
  healthcheck:
    test: ["CMD", "wget", "–spider", "-q", "http://localhost:3000/health"]
    interval: 30s
    timeout: 5s
    retries: 3
EOF

五、缓存优化：让构建速度翻倍

5.1 为什么需要缓存？

每次 CI 构建都是在一台全新的虚拟机上跑，没有之前的构建层缓存。一个 Node.js 项目光 npm install 就要 1-2 分钟，Java Maven 项目更夸张——首次构建可能 5-10 分钟。

5.2 GitHub Actions 缓存方案

上面的工作流已经用上了：

cache-from: type=gha
cache-to: type=gha,mode=max

这两行的含义：

实测效果：

进阶：如果你用 GitHub Container Registry，还可以用 registry 类型缓存，把缓存层直接推到镜像仓库里：

cache-from: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache
cache-to: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache,mode=max

六、多环境部署策略

真实项目通常有 dev / staging / prod 三套环境。下面展示如何用一套工作流覆盖多环境：

# 在工作流顶部添加环境判断
jobs:
build-and-push:
# …（同上面的构建 Job）

deploy-dev:
needs: build-and-push
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
– name: Deploy to DEV
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.DEV_SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SERVER_SSH_KEY }}
script: |
cd /opt/my-app
# dev 环境用 dev 标签
sed -i 's|image:.*|image: your-dockerhub-username/my-app:dev|' docker-compose.yml
docker compose pull && docker compose up -d

deploy-prod:
needs: build-and-push
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ubuntu-latest
environment: production # ← GitHub 环境保护：可以配置审批人
steps:
– name: Deploy to PRODUCTION
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.PROD_SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SERVER_SSH_KEY }}
script: |
cd /opt/my-app
VERSION=${GITHUB_REF_NAME#v}
sed -i "s|image:.*|image: your-dockerhub-username/my-app:${VERSION}|" docker-compose.yml
docker compose pull && docker compose up -d

关键设计：

• deploy-dev：push 到 main 自动部署，用 dev 标签

• deploy-prod：只有打 tag（如 v1.0.0）才触发，用版本号标签

• environment: production：可以在 GitHub 上配置审批人，防止误操作

七、工作流运行效果

配置完成后，每次推代码到 main 分支，GitHub Actions 会自动触发。在仓库的 Actions 标签页可以看到运行记录：

✅ Docker Build and Deploy #87 pushed 2 minutes ago
├── ✅ build-and-push completed in 1m 23s
│ ├── ✅ Checkout code 5s
│ ├── ✅ Set up Docker Buildx 8s
│ ├── ✅ Login to Docker Hub 2s
│ ├── ✅ Login to GHCR 2s
│ ├── ✅ Generate image tags 1s
│ └── ✅ Build and push 1m 05s
│
└── ✅ deploy completed in 32s
└── ✅ Deploy to server via SSH 30s

推送镜像到 Docker Hub 后的效果：

your-dockerhub-username/my-app
├── latest ← 最新正式版（打 tag 时更新）
├── 1.2.3 ← 版本号标签
├── dev ← 开发版（push 到 main 时更新）
├── a1b2c3d ← Git 短哈希标签（精确到提交）
└── buildcache ← 构建缓存（不用于运行，仅加速构建）

八、其他 CI/CD 工具等效方案

如果你不用 GitHub Actions，下面是 Jenkins 和 GitLab CI 的等效配置概要。

8.1 GitLab CI

GitLab CI 的配置文件是项目根目录的 .gitlab-ci.yml：

# .gitlab-ci.yml

stages:
– build
– deploy

build:
stage: build
image: docker:24
services:
– docker:24-dind # Docker in Docker
script:
– docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
– docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
– docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
only:
– main

deploy:
stage: deploy
image: alpine:latest
before_script:
– apk add openssh-client
– eval $(ssh-agent -s)
– echo "$SSH_PRIVATE_KEY" | ssh-add –
script:
– ssh -o StrictHostKeyChecking=no $DEPLOY_USER@$DEPLOY_HOST "cd /opt/my-app && docker compose pull && docker compose up -d"
only:
– main
needs: ["build"]

8.2 Jenkins Pipeline

Jenkins 用 Jenkinsfile 定义流水线：

// Jenkinsfile

pipeline {
agent any

environment {
DOCKER_IMAGE = 'your-dockerhub-username/my-app'
DOCKERHUB_CREDENTIALS = credentials('dockerhub-credentials')
}

stages {
stage('Build') {
steps {
sh "docker build -t ${DOCKER_IMAGE}:${env.BUILD_NUMBER} ."
}
}
stage('Push') {
steps {
withCredentials([usernamePassword(credentialsId: 'dockerhub-credentials',
usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS')]) {
sh "echo ${DOCKER_PASS} | docker login -u ${DOCKER_USER} –password-stdin"
sh "docker push ${DOCKER_IMAGE}:${env.BUILD_NUMBER}"
}
}
}
stage('Deploy') {
steps {
sshagent(['server-ssh-key']) {
sh """
ssh -o StrictHostKeyChecking=no root@your-server \\
'cd /opt/my-app && docker compose pull && docker compose up -d'
"""
}
}
}
}
}

三者对比：

九、常见问题与避坑

十、本文要点回顾

CI/CD 的本质是"把人的操作变成机器的流程"。 Docker 在其中扮演"标准化打包"的角色——同一份 Dockerfile 构建出的镜像，在任何环境都一模一样，这就是 CI/CD 能可靠运行的基石。

下集预告

到这里，Docker 的日常使用和自动化部署都讲完了。下一篇我们进入底层原理篇——Docker 到底是怎么做到"隔离"的？Namespace、Cgroup、UnionFS 这三大核心技术，将揭开容器"看起来像虚拟机，其实不是"的秘密。理解这些原理，你在排查容器问题时就不再是"黑盒调试"了。

参考资料

• GitHub Actions 官方文档

• docker/build-push-action 仓库

• docker/login-action 仓库

• appleboy/ssh-action 仓库

• GitHub Actions 缓存文档