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 自动构建卡住」「服务器内存太小」这几类问题的人。它不涉及多节点编排、蓝绿发布或镜像签名;目标是用一条能复现的链路,把版本送上去,再安全地退回来。