一、全景图：五个环节各自干什么#

先把整条链路在脑子里过一遍，后面每一节都是在填其中一个环节的细节。

有几个关键点先说清楚：

• 构建不在你的服务器上做。构建吃 CPU 和内存，小配置 VPS 构建一次能卡到服务无响应。GitHub Actions 的公共仓库免费额度足够个人项目用，构建在云端跑完，服务器只负责拉现成镜像，又快又稳。
• 服务器不存代码、不存密钥。服务器上只有一个 Compose 文件和一个 Watchtower，它甚至不需要知道 GitHub 上发生了什么，只盯着镜像仓库看标签有没有变。
• 整条链路是单向的。代码从本地流向 GitHub，再流向镜像仓库，最后流向服务器。任何一环出问题，都不会把脏东西带回上一环。

这套结构还有一个隐形好处：部署过程全部留痕。哪次上线对应哪个 commit、哪个镜像标签，在 GitHub 的 Actions 页面和镜像仓库里都查得到，出了问题甩不了锅，也赖不掉账。

二、镜像推哪：GHCR、Docker Hub 与自建 Registry#

构建出来的镜像得有个地方存。三个主流选择，先给结论再给对比：

怎么选，一句话原则：项目代码在 GitHub 上，优先用 GHCR；镜像要公开给所有人拉，Docker Hub 更有知名度；镜像不想出内网、或者拉取速度是硬要求，再上自建 Registry。

自建 Registry 的搭建方法在私有镜像仓库篇里完整写过（见 私有镜像仓库：Registry 与 Harbor 部署实战），包括认证、HTTPS 与垃圾回收，这一节不重复。本篇的实战以 GHCR 为主线，因为它和 GitHub Actions 是同一套账号体系，Secrets 都可以省掉大半，第一次搭流水线最不容易卡壳。

三、完整 Workflow 实战：逐段拆解#

在项目仓库根目录建 .github/workflows/docker.yml，下面是全文。先整体看一遍，后面逐段拆。

1
name: Build and Push Image
2

3
on:
4
  push:
5
    branches:
6
      - main
7
    paths:
8
      - "src/**"
9
      - "Dockerfile"
10
      - ".github/workflows/docker.yml"
11

12
permissions:
13
  contents: read
14
  packages: write
15

16
jobs:
17
  build:
18
    runs-on: ubuntu-latest
19
    steps:
20
      - name: Checkout
21
        uses: actions/checkout@v4
22

23
      - name: Set up Buildx
24
        uses: docker/setup-buildx-action@v3
25

26
      - name: Login to GHCR
27
        uses: docker/login-action@v3
28
        with:
29
          registry: ghcr.io
30
          username: ${{ github.actor }}
31
          password: ${{ secrets.GITHUB_TOKEN }}
32

33
      - name: Extract metadata
34
        id: meta
35
        uses: docker/metadata-action@v5
36
        with:
37
          images: ghcr.io/${{ github.repository }}
38
          tags: |
39
            type=semver,pattern={{version}}
40
            type=sha,format=short
41
            type=raw,value=latest,enable={{is_default_branch}}
42

43
      - name: Build and push
44
        uses: docker/build-push-action@v6
45
        with:
46
          context: .
47
          push: true
48
          tags: ${{ steps.meta.outputs.tags }}
49
          labels: ${{ steps.meta.outputs.labels }}
50
          cache-from: type=gha
51
          cache-to: type=gha,mode=max

1
on:
2
  push:
3
    branches:
4
      - main

1
    paths:
2
      - "src/**"
3
      - "Dockerfile"
4
      - ".github/workflows/docker.yml"

1
on:
2
  push:
3
    tags:
4
      - "v*"

1
      - name: Checkout
2
        uses: actions/checkout@v4

1
      - name: Set up Buildx
2
        uses: docker/setup-buildx-action@v3

1
      - name: Login to GHCR
2
        uses: docker/login-action@v3
3
        with:
4
          registry: ghcr.io
5
          username: ${{ github.actor }}
6
          password: ${{ secrets.GITHUB_TOKEN }}

1
permissions:
2
  contents: read
3
  packages: write

1
      - name: Login to Docker Hub
2
        uses: docker/login-action@v3
3
        with:
4
          username: ${{ secrets.DOCKERHUB_USERNAME }}
5
          password: ${{ secrets.DOCKERHUB_TOKEN }}

1
      - name: Build and push
2
        uses: docker/build-push-action@v6
3
        with:
4
          context: .
5
          push: true
6
          tags: ${{ steps.meta.outputs.tags }}
7
          labels: ${{ steps.meta.outputs.labels }}
8
          cache-from: type=gha
9
          cache-to: type=gha,mode=max

四、标签策略：版本号、latest 与 commit sha#

标签不是随手打的，它是你日后回滚和排障的唯一线索。本系列的立场很明确，一次构建同时打三种标签：

为什么生产环境不能只靠 latest？因为 latest 是个会动的指针。今天它指向好版本，明天一次坏构建推上去，它就指向坏版本了。更要命的是出了问题你想退回去，却发现旧镜像没有独立标签，没有版本号标签的镜像，等于没有存档点的游戏，坏了只能从头来过。

版本号标签负责稳定，sha 标签负责精确，latest 负责方便，三者分工明确。服务器上线时，重要服务建议在 Compose 里写死版本号标签，比如 image: ghcr.io/你的用户名/项目名:v1.2.0；个人小项目图省事可以跟 latest，但前提是仓库里每个版本都有独立标签存着，随时能退。

还有一个细节：标签一旦发布就不要覆盖重推。同一个 v1.2.0 今天是这份代码、明天换成另一份代码，这个版本号就废了。真要修，版本号往上加，发 v1.2.1。

五、Secrets 管理：密钥只进保险箱#

凡是 workflow 里要用到的密码、Token，一律放进仓库的 Secrets，路径是仓库页面 Settings → Secrets and variables → Actions → New repository secret。引用时写 ${{ secrets.名字 }}，GitHub 在日志里还会自动把这些值打码。

纪律只有三条，但条条要命：

WARNING

绝不把任何密码、Token、私钥直接写进 workflow 文件或提交进仓库。仓库历史是永久的，写进去删掉也还在 git 记录里，等于公开广播。真发生了，第一时间去吊销那个凭证换新的，光删文件没有任何用。

• 能用自动 Token 就不用手动凭证。推 GHCR 用 GITHUB_TOKEN 就是最优解，它随任务生、随任务死，泄漏面最小。
• 手动凭证要限权、限期。Docker Hub 用 Access Token 而不是主密码，Token 只给读写镜像的权限；自建 Registry 的账号也应该是专用账号，不要拿管理员账号到处填。
• 定期轮换。Secrets 不是配一次管一辈子，隔几个月换一轮，尤其是多人协作的仓库，有人退出就立刻换。

再补一句容易被忽略的：fork 来的 PR 默认拿不到 Secrets，这是 GitHub 的保护机制，不是配置错了。给外部 PR 跑构建检查时，设计成只构建不推送（push: false），别为了让它跑通去拆这道防线。

六、服务器侧衔接：Watchtower 自动上线#

镜像推上去了，最后一段路是服务器自己把新镜像换上。这正是自动更新篇的主角 Watchtower（见 如何在 Linux 自动更新 Docker 容器），这里只讲它在流水线里怎么对接，部署细节不重复。

核心就一件事：只让 Watchtower 更新本项目的容器，千万别让它把整台机器的容器全卷进来。做法是靠 label 精确圈定范围。被流水线管理的服务，在 Compose 里加上启用标签：

1
services:
2
  app:
3
    image: ghcr.io/你的用户名/项目名:latest
4
    labels:
5
      - "com.centurylinklabs.watchtower.enable=true"

Watchtower 这一侧则开启 label 模式，只盯带标签的容器：

1
services:
2
  watchtower:
3
    image: nickfedor/watchtower:latest
4
    volumes:
5
      - /var/run/docker.sock:/var/run/docker.sock
6
    environment:
7
      - WATCHTOWER_LABEL_ENABLE=true
8
      - WATCHTOWER_POLL_INTERVAL=300
9
      - WATCHTOWER_CLEANUP=true

这样对接完成后，链路是全自动的：你 push 代码，Actions 构建推送，Watchtower 在轮询周期内（上面配的是 300 秒）发现 latest 变了，拉新镜像、用原参数重建容器、清掉旧镜像。整个过程你只需要打开网站看一眼新版本在不在。

私有镜像 Watchtower 也拉得到，前提是服务器上先 docker login ghcr.io 登录一次，凭证会存在服务器的 Docker 配置里，Watchtower 挂载 docker.sock 时会沿用。登录用的 Token 在 GitHub 里生成一个只带 read:packages 权限的就够了，服务器侧只拉不推，权限给多了都是风险。

1
ssh deploy@你的服务器 "cd /opt/app && docker compose pull && docker compose up -d"

七、上线后验证、失败处理与回滚#

自动化不等于甩手不管，链路的最后一环是确认新版本真的活着。

1
#!/bin/bash
2
URL="http://127.0.0.1:8080/health"
3
for i in $(seq 1 30); do
4
  code=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
5
  if [ "$code" = "200" ]; then
6
    echo "OK: 服务已就绪"
7
    exit 0
8
  fi
9
  echo "第 $i 次检查，状态码 $code，继续等……"
10
  sleep 5
11
done
12
echo "超时：服务未在 150 秒内就绪"
13
exit 1

1
docker compose logs --tail=100 app

1
cd /opt/app
2
# 把 compose 里的镜像标签改回上一个版本
3
sed -i 's|image: ghcr.io/你的用户名/项目名:.*|image: ghcr.io/你的用户名/项目名:v1.1.0|' docker-compose.yml
4
docker compose pull
5
docker compose up -d

八、进阶：一句带过的两个提速与扩展点#

多架构构建。想让镜像同时支持 x86 和 ARM（比如还要跑在树莓派或 ARM 云主机上），在 build-push-action 里加一行 platforms 即可：

1
        with:
2
          platforms: linux/amd64,linux/arm64

原理、QEMU 模拟构建的注意事项和 manifest 清单的验证方法，在多平台构建篇里完整讲过（见 多平台镜像构建实战：buildx 双架构），这里不展开。

构建缓存用 type=gha。第三节 workflow 里已经埋了这两行：

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

它把 Docker 的层缓存存进 GitHub Actions 自带的缓存空间，下次构建直接复用没变的层。依赖多、构建慢的项目，第一次构建五分钟、第二次可能只要几十秒。注意 Actions 缓存有容量上限（默认 10 GB，超了自动淘汰最旧的），缓存偶尔失效重跑一次全量构建属于正常现象，不用排查。

再往前一步，还可以给 workflow 加上 PR 触发的只构建不推送检查、镜像漏洞扫描等环节，但那都是锦上添花。主链先跑稳，再谈扩展。

九、排障小节#

1. login 失败：unauthorized 或 permission_denied

按顺序查三件事：一是 workflow 顶部有没有写 permissions: packages: write，没写的话 GITHUB_TOKEN 默认权限可能不给推包；二是镜像名是不是全小写，GHCR 对大小写很较真；三是如果用的是个人访问令牌（PAT），确认它勾了 write:packages 权限且没有过期。用 Docker Hub 或自建仓库的，则检查 Secrets 里的用户名和 Token 有没有复制串行、Token 有没有被吊销。

2. build-push-action 推不上去：构建成功但 push 报错

先分清是构建挂了还是推送挂了，日志里 ERROR: failed to push 才是推送问题。常见原因：登录步骤被跳过或失败但没中断（检查 login-action 那一步是不是绿的）；镜像名和仓库对不上，比如 metadata-action 生成的名字和 login 的 registry 不是同一家；网络抽风偶发失败，直接 Re-run 一次能过的大多是这类。

3. 服务器没更新：镜像推上去了，容器纹丝不动

这是 Watchtower 对接最经典的坑，逐项对：

• 服务的 Compose 里 label 写了吗？键名必须是 com.centurylinklabs.watchtower.enable=true，拼错一个字母都不认；
• Watchtower 自己有没有开 WATCHTOWER_LABEL_ENABLE=true，一边开一边没开等于没对接；
• 容器跟的标签对不对：Watchtower 只认你部署时用的那个标签有没有新版，Compose 里钉的是版本号标签，那推 latest 推一万次它也不会动；
• 私有镜像有没有在服务器上 docker login 过，没登录它拉不到，只会在日志里默默报错，去看 Watchtower 自己的日志：

1
docker logs watchtower --tail=50

4. 镜像拉下来了但容器反复重启

这不是流水线的问题，是新版本本身起不来。看应用日志定位，别回滚了事也别放着不管：确认是代码 bug 就修完发新版，是配置缺失（环境变量、数据卷没跟上）就补齐部署配置。实在顶不住先按第七节回滚保命，再慢慢查。

5. Actions 额度或缓存异常

公共仓库的 Actions 分钟数免费且宽裕，私有仓库有月度额度，跑超了流水线会被暂停，去 Settings → Billing 看用量。缓存突然全失效一般是缓存被容量淘汰，属正常现象。

小结#

这一篇把整个系列收了个尾，回顾一下链路：本地 git push 触发 GitHub Actions，checkout、Buildx、登录、打标签、构建推送一气呵成，镜像躺进 GHCR 并带着版本号、latest、commit sha 三种标签；服务器上的 Watchtower 盯着标签把新容器换上；健康检查确认服务活着，出事就改标签一分钟回滚。

真正要带走的其实是三条纪律：构建放云端、服务器只拉镜像；标签必须留存档、生产别只靠 latest；密钥只进 Secrets、权限只给刚好够用的。这三条守住，你的部署就从手艺活变成了流水线，改代码只管改，上线交给机器。

至此 Docker 系列从安装、更新、命令、数据、网络、Compose、Dockerfile、日志、安全、反代，一路写到自动化流水线，一条完整的路走通了。下一篇可以横向扩展到监控与编排，或者就停在这里，把这条流水线先在自己项目里跑上一个月，体感会比多看十篇教程都实在。