跳到主要内容
Ed. notes

06 部署(二):ACR、VPC 与回滚

长文 · 2026-11-11 · 合集第 7 / 12 篇

  • 构建日志
  • Docker
  • ACR
  • 部署
  • 回滚
第 7 / 12 篇 · 查看全部章节 → 当前:06 部署(二):ACR、VPC 与回滚

一句话结论:发布链路要短到一条命令,回滚要短到改一个 tag;在国内网络里,让 GitHub Actions 跨境推镜像、或让 ACR 自动构建去克隆私有仓库,都会把简单问题变成网络问题,所以我把构建放在本地,把拉取放在同地域的 VPC。

它解决什么问题

镜像构建只是第一步。接下来要回答三个问题:镜像放在哪里、服务器怎么拿到它、出错后怎么退回去。

最直觉的方案是让 GitHub Actions 构建并推送镜像,服务器再从镜像仓库拉取。但这条链路要跨两次网络:Actions 从 GitHub 拉代码、再把镜像推到国内的 ACR;服务器再从 ACR 拉回来。镜像层动辄几十 MB,跨境链路的稳定性和速度都不由我控制。另一种方案是 ACR 的自动构建:代码推到 GitHub,ACR 自己克隆仓库并构建。听起来更短,实际却卡在 Cloning into '/workspace'...,因为构建机访问 GitHub 同样不稳定。

最后我选了一条更笨但更可控的路:在本地或境内机器上用 buildx 构建 linux/amd64 镜像,推送到 ACR 的公网端点;服务器通过同地域的 VPC 端点拉取。构建位置和运行位置分开,跨境只发生在代码同步,不发生在镜像分发。

我怎么试的

1. 先把发布链路画出来

本地 / 境内构建机
  └─ docker buildx --platform linux/amd64
       └─ push → ACR public endpoint
                    └─ 服务器 pull → ACR VPC endpoint
                         └─ docker compose up -d --no-build

两条 endpoint 指向同一个镜像仓库,但网络路径不同:

用途 endpoint 形态 谁用 特点
推送 <acr-registry>.cn-beijing.personal.cr.aliyuncs.com/... 本地构建机 走公网,需要登录
拉取 <acr-registry>-vpc.cn-beijing.personal.cr.aliyuncs.com/... 同地域服务器 走 VPC 内网,不占公网带宽

这里最容易犯的错,是在服务器上继续用公网 endpoint。镜像能拉下来,但流量走公网,速度慢,也会产生不必要的出网费用。VPC endpoint 只在同地域可用;服务器和 ACR 不在一个地域时,这条路径不成立。

两条路径都需要一次 docker login,但凭证的用途不同:构建机需要推送权限,服务器只需要拉取权限。如果 ACR 支持读写分离的账号,最好给服务器单独一个只读凭证。密码不应该写进 compose、.env 或脚本,而是通过 docker login 存到 Docker 的凭证存储里。

2. 一条脚本,两个必须关掉的开关

发布脚本做三件事:确定 tag、构建 linux/amd64、推送两个 tag。

IMAGE_TAG="${IMAGE_TAG:-$(git rev-parse --short HEAD)}"

docker buildx build \
  --platform linux/amd64 \
  --build-arg "NODE_IMAGE=${NODE_IMAGE}" \
  --tag "${IMAGE_REPO}:${IMAGE_TAG}" \
  --tag "${IMAGE_REPO}:latest" \
  --provenance=false \
  --sbom=false \
  --push \
  .

--platform linux/amd64 是因为服务器是 x86_64,而本地开发机可能是 arm64。--provenance=false --sbom=false 不是可选项:ACR 个人版不接受 buildx 默认附加的证明清单,第一次推送会报:

denied: unknown manifest class for application/vnd.oci.empty.v1+json

这个错误看起来像镜像坏了,其实只是多推了一个 ACR 不认识的 manifest。关掉这两个开关后,推送就正常了。

脚本同时推 :<commit> 和 :latest。latest 只是方便手动查看,真正用于部署和回滚的是 commit tag。每次发布都对应一个 Git 提交,看到 tag 就知道线上跑的是哪版代码。

3. 服务器只拉不构建

服务器上的 docker-compose.yml 只引用镜像,不在服务器上执行 build:

services:
  app:
    image: ${IMAGE_REPO}:${IMAGE_TAG}
    environment:
      NUXT_CONTENT_DIR: /app/content
      NUXT_PUBLIC_SITE_URL: ${SITE_URL}
      NUXT_PUBLIC_ICP_NUMBER: ${ICP_NUMBER:-}
    expose:
      - '3000'
    healthcheck:
      test: ['CMD', 'wget', '-qO-', 'http://127.0.0.1:3000/api/health']
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 15s

发布时只需要:

docker compose pull
docker compose up -d --no-build
docker compose ps

--no-build 是一个保护:即使 compose 文件里还留着 build 段,也不会在服务器上临时构建。服务器的内存只有 2GB,另外配了 2GB swap;构建 Nuxt 时很容易把内存打满,所以这台机器只负责拉取和运行。

compose 里的 caddy 用 depends_on 等 app 变成 healthy 再启动,避免容器刚起来、内容还没加载完时先返回 502。健康检查本身也会加载内容,所以它不只是「进程活着」,而是「服务真的能读内容」。

.env 里需要关注的变量不多:

变量 作用 预检时的值
SITE_DOMAIN Caddy 的站点域名 localhost
SITE_URL canonical、RSS、sitemap 的绝对地址 http://localhost:13000
IMAGE_REPO 镜像仓库地址 VPC endpoint
IMAGE_TAG 要运行的版本 某个 commit 短哈希
NODE_IMAGE 构建时的 Node 基础镜像 ACR 内的 Node 镜像
ICP_NUMBER 页脚备案号,为空时不渲染 空

4. 备案前的预检

域名还在备案时,站点不能对公网开放 80/443。但代码是否真的能跑,还是要验证。我的做法是让 app 只绑定在服务器本机的 127.0.0.1:3000,再从本地建立 SSH 隧道:

ssh -N -i ~/.ssh/<deploy-key> -L 13000:127.0.0.1:3000 <user>@<server-ip>

-N 表示只转发端口、不执行远程命令,所以终端看起来「没有反应」是正常的。另开一个终端访问 http://localhost:13000,能看到页面就说明容器、内容路径和运行时都正常。此时服务器安全组只开放 22,80/443 保持关闭,公网无法通过 IP 加端口访问站点。

Caddy 和 HTTPS 的配置已经写好,但要等域名解析和备案通过后再启用。预检阶段可以先在本地用 Caddy 的内部 CA 验证反代和 308 跳转,不要把它当成正式上线。

5. 回滚演练

回滚不是「把 latest 拉一下」,而是明确回到某个 commit。我实际做了一轮:

# 当前版本 a7a3df0
# 1. 把 .env 里的 IMAGE_TAG 改成 6aea71b
docker compose pull
docker compose up -d --no-build

# 2. 验证健康检查和页面
curl -s http://127.0.0.1:3000/api/health
# {"status":"ok","notes":9}

# 3. 再改回 a7a3df0,重复 pull/up

两次切换后,健康接口都返回 ok,首页、笔记详情、RSS 和 sitemap 都能打开。回滚的关键不是命令,而是发布时就保证每个版本都有唯一的 commit tag,并且镜像没有被覆盖。latest 会随着新推送移动,不能作为回滚锚点。

坑和限制

1. ACR 自动构建不是理所当然可用的。 它依赖构建机访问 GitHub。仓库是私有的,构建日志停在 Cloning into '/workspace'...,既没有报错也没有进展。把自动构建当备用可以,但不要把它设计成唯一发布路径。

2. GitHub Actions 全绿不等于镜像已经发布。 当前 CI 里的 image job 只验证 Dockerfile 能构建,不登录 ACR,也不推送。真正的发布由本地脚本完成。这是有意分开的:质量门和发布动作有不同的失败代价。

3. VPC endpoint 有地域限制。 服务器和 ACR 必须在同一地域,否则 VPC 域名解析不到。跨地域时只能走公网,或者考虑其他复制方案。

4. ACR 个人版有能力边界。 仓库数量、构建并发和网络访问都有限制。个人站够用,但不要把自动构建、跨地域同步和复杂权限都压在一个个人版实例上。

5. 服务器磁盘和日志要留余量。 每次 pull 都会留下新镜像层,旧镜像不会自动删除。定期 docker image prune,并给容器日志设置轮转,否则磁盘会被历史版本和日志慢慢吃掉。

6. 不要把「预检可访问」说成「已上线」。 预检是通过 SSH 隧道访问本机端口,公网并没有开放站点。备案通过前,这个区别很重要。

适合谁

这篇适合需要把 Docker 镜像部署到国内云服务器的个人开发者,尤其是遇到「GitHub Actions 推镜像慢」「ACR 自动构建卡住」「服务器内存太小」这几类问题的人。它不涉及多节点编排、蓝绿发布或镜像签名;目标是用一条能复现的链路,把版本送上去,再安全地退回来。

继续探索