From 56ca479c6bd03d2488850e52d5255ef2d14ea36c Mon Sep 17 00:00:00 2001 From: yml2213 Date: Mon, 12 Oct 2026 16:33:45 +0800 Subject: [PATCH] =?UTF-8?q?chore(deploy):=20=E5=9F=BA=E7=A1=80=E9=95=9C?= =?UTF-8?q?=E5=83=8F=E6=BA=90=E6=94=B9=E4=B8=BA=E5=8F=AF=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=20BASE=5FREGISTRY=EF=BC=8C=E5=B9=B6=E6=8F=90=E5=89=8D=E8=A1=A5?= =?UTF-8?q?=E9=BD=90=20FROM=20=E5=9F=BA=E7=A1=80=E9=95=9C=E5=83=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 修的是什么 线上部署卡死过一次：daocloud 加速源返回 502 Bad Gateway，整轮构建在 load metadata 阶段就失败，而服务器 daemon.json 里另外两个 registry-mirrors 完全帮不上忙。 原因是**显式写死的 registry 会绕过 daemon.json 的 registry-mirrors**： Dockerfile 里 `FROM docker.m.daocloud.io/library/node:...` 属于显式指定 registry， 镜像列表对它就失效了，于是这个源成了构建的单点故障。 ## 修法 1. 四个 Dockerfile（backend / frontend / backend-dev / dev-caddy）的 `FROM` 改用 `${BASE_REGISTRY}`（registry 前缀语义），默认值 docker.m.daocloud.io 保持不变； 2. docker-compose.yml / docker-compose.dev.yml 的 `build.args` 接上 `${BASE_REGISTRY:-docker.m.daocloud.io}`，并把 postgres / minio / node / caddy 这几处 `image:` 也改成同一变量，整套编排只有一个换源开关； 3. 部署脚本：新增 resolve_base_registry()（读 .env 的 BASE_REGISTRY，缺省同 compose）， --dry-run 的基础镜像 digest 预检沿用同一变量； 新增 ensure_dockerfile_base_images()，在 pull_base_images 阶段把 Dockerfile 里 `FROM` 用到的基础镜像提前补齐 —— 这类镜像不归 `docker compose pull` 管， 本地缺失要拖到构建阶段才报错，且报错信息晦涩，看不出来是"源挂了"还是"代码写错了"； 现在缺失时明确提示并给出换源/离线搬运两条排障路径； 4. .env.server.example 增加 BASE_REGISTRY 说明（推荐多源容灾时设 docker.io， 走 daemon 的 registry-mirrors 列表自动故障转移）。 ## 验证 - docker compose config：默认值下所有镜像引用与改动前逐字一致（不会触发重新下载）； BASE_REGISTRY=docker.1panel.live / docker.io 时全部引用正确替换； - docker buildx build --call=check -f deploy/docker/backend.Dockerfile：Check complete, no warnings； - deploy/ubuntu-deploy.sh bash -n 通过； - 生产实测：预拉三个基础镜像后，buildkit 解析基础镜像 1s 命中本地镜像、不再访问远端。 --- .env.server.example | 6 +++ deploy/docker/backend-dev.Dockerfile | 4 +- deploy/docker/backend.Dockerfile | 13 ++++++- deploy/docker/dev-caddy.Dockerfile | 4 +- deploy/docker/frontend.Dockerfile | 7 +++- deploy/ubuntu-deploy.sh | 56 +++++++++++++++++++++++++--- docker-compose.dev.yml | 10 +++-- docker-compose.yml | 8 +++- 8 files changed, 92 insertions(+), 16 deletions(-) diff --git a/.env.server.example b/.env.server.example index 719dbde2..e4110f1e 100644 --- a/.env.server.example +++ b/.env.server.example @@ -15,6 +15,12 @@ HTTP_TRUST_PROXY=1 # DEBIAN_MIRROR=mirrors.aliyun.com # ALPINE_MIRROR=mirrors.aliyun.com # NPM_REGISTRY=https://registry.npmmirror.com +# +# 基础镜像源（registry 前缀，node / caddy / postgres 都从这里拉）。 +# 默认 docker.m.daocloud.io。加速源会抽风（daocloud 出现过 502 Bad Gateway， +# 而显式写死的 registry 会绕过 daemon.json 的 registry-mirrors，其它源帮不上忙）。 +# 想要多源容灾就设为 docker.io：走 daemon.json 的 registry-mirrors 列表自动故障转移。 +# BASE_REGISTRY=docker.m.daocloud.io # Claim Links CLAIM_BASE_URL=https://order.khhao.com/#/claim diff --git a/deploy/docker/backend-dev.Dockerfile b/deploy/docker/backend-dev.Dockerfile index eaaafb3b..f0d5f491 100644 --- a/deploy/docker/backend-dev.Dockerfile +++ b/deploy/docker/backend-dev.Dockerfile @@ -1,5 +1,7 @@ # 快手轻量开发镜像：只保留 Node 运行时和基础工具。 -FROM docker.m.daocloud.io/library/node:22-bookworm +# 基础镜像源可整体替换（.env 的 BASE_REGISTRY），原因见 backend.Dockerfile 顶部注释。 +ARG BASE_REGISTRY=docker.m.daocloud.io +FROM ${BASE_REGISTRY}/library/node:22-bookworm # 阿里云公共源（全国可达）；也可构建时覆盖：--build-arg DEBIAN_MIRROR=mirrors.cloud.aliyuncs.com ARG DEBIAN_MIRROR=mirrors.aliyun.com diff --git a/deploy/docker/backend.Dockerfile b/deploy/docker/backend.Dockerfile index b4b61174..5175409d 100644 --- a/deploy/docker/backend.Dockerfile +++ b/deploy/docker/backend.Dockerfile @@ -1,5 +1,14 @@ # 快手轻量后端镜像 -FROM docker.m.daocloud.io/library/node:22-bookworm AS builder +# +# 基础镜像源可整体替换（.env 的 BASE_REGISTRY）。为什么必须可配： +# 显式写死的 registry 会**绕过** daemon.json 的 registry-mirrors —— 加速源一抽风 +# （daocloud 出现过 502 Bad Gateway），整轮构建在 load metadata 阶段就失败， +# 而 daemon 里其它可用镜像源完全帮不上忙，只能等它自己恢复。 +# 默认值保持历史值，避免已有本地镜像被重新下载；多源容灾可改 BASE_REGISTRY=docker.io +# （那样会走 daemon.json 的 registry-mirrors 列表自动故障转移）。 +ARG BASE_REGISTRY=docker.m.daocloud.io + +FROM ${BASE_REGISTRY}/library/node:22-bookworm AS builder # 阿里云公共源（全国可达）；也可构建时覆盖：--build-arg DEBIAN_MIRROR=mirrors.cloud.aliyuncs.com ARG DEBIAN_MIRROR=mirrors.aliyun.com @@ -29,7 +38,7 @@ COPY apps/backend/ ./ RUN npm run build \ && npm prune --omit=dev -FROM docker.m.daocloud.io/library/node:22-bookworm-slim AS runtime +FROM ${BASE_REGISTRY}/library/node:22-bookworm-slim AS runtime ARG DEBIAN_MIRROR=mirrors.aliyun.com diff --git a/deploy/docker/dev-caddy.Dockerfile b/deploy/docker/dev-caddy.Dockerfile index 08e6d2be..f5424f1d 100644 --- a/deploy/docker/dev-caddy.Dockerfile +++ b/deploy/docker/dev-caddy.Dockerfile @@ -1,4 +1,6 @@ -FROM docker.m.daocloud.io/library/caddy:2-alpine +# 基础镜像源可整体替换（.env 的 BASE_REGISTRY），原因见 backend.Dockerfile 顶部注释。 +ARG BASE_REGISTRY=docker.m.daocloud.io +FROM ${BASE_REGISTRY}/library/caddy:2-alpine ENV TZ=Asia/Shanghai diff --git a/deploy/docker/frontend.Dockerfile b/deploy/docker/frontend.Dockerfile index e18d4f44..b300833d 100644 --- a/deploy/docker/frontend.Dockerfile +++ b/deploy/docker/frontend.Dockerfile @@ -1,4 +1,7 @@ -FROM docker.m.daocloud.io/library/node:22-bookworm AS builder +# 基础镜像源可整体替换（.env 的 BASE_REGISTRY），原因见 backend.Dockerfile 顶部注释。 +ARG BASE_REGISTRY=docker.m.daocloud.io + +FROM ${BASE_REGISTRY}/library/node:22-bookworm AS builder ARG NPM_REGISTRY=https://registry.npmmirror.com ARG VITE_WORKER_SITE_URL=https://worker.khhao.com @@ -16,7 +19,7 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \ COPY apps/frontend/ ./ RUN npm run build -FROM docker.m.daocloud.io/library/caddy:2-alpine +FROM ${BASE_REGISTRY}/library/caddy:2-alpine # 阿里云公共源（全国可达）；也可构建时覆盖：--build-arg ALPINE_MIRROR=mirrors.cloud.aliyuncs.com ARG ALPINE_MIRROR=mirrors.aliyun.com diff --git a/deploy/ubuntu-deploy.sh b/deploy/ubuntu-deploy.sh index add74304..d4b0f97a 100755 --- a/deploy/ubuntu-deploy.sh +++ b/deploy/ubuntu-deploy.sh @@ -27,6 +27,8 @@ DRY_RUN=false RESET_PRE_BACKUP_DONE=false # 上次成功部署的 commit / .env 指纹；用来算"这次到底改了什么"。 DEPLOY_STATE_FILE="${DEPLOY_STATE_FILE:-${PROJECT_ROOT}/.deploy-state}" +# 基础镜像源（registry 前缀）默认值，必须与 docker-compose.yml / Dockerfile 的默认值一致。 +BASE_REGISTRY_DEFAULT="docker.m.daocloud.io" BUILD_BACKEND=false BUILD_WEB=false CHANGED_FILES="" @@ -146,6 +148,14 @@ read_env_value() { ' "${ENV_FILE}" } +# 基础镜像源（registry 前缀）：与 docker-compose.yml / Dockerfile 的 BASE_REGISTRY 同一套默认值。 +# 写进 .env 即可整体换源（例如加速源抽风时改成 docker.io，白拿 daemon 的多源故障转移）。 +resolve_base_registry() { + local value + value="$(read_env_value BASE_REGISTRY 2>/dev/null || true)" + printf '%s' "${value:-${BASE_REGISTRY_DEFAULT}}" +} + ensure_docker() { command -v docker >/dev/null 2>&1 || fail "未找到 docker，请先在 Ubuntu 上安装 Docker Engine。" docker compose version >/dev/null 2>&1 || fail "未找到 docker compose 插件，请安装 Docker Compose plugin。" @@ -494,10 +504,46 @@ pull_base_images() { # postgres 这类 tag，既多一次联网，也可能让数据库镜像在"随手一部署"时被静默升级。 log "检查基础镜像（仅缺失时拉取）" if docker compose pull --ignore-buildable --policy missing; then + : + else + warn "compose pull 不支持 --policy missing，回退为默认拉取策略。" + docker compose pull --ignore-buildable + fi + ensure_dockerfile_base_images +} + +# Dockerfile 里 `FROM` 的基础镜像**不归 `docker compose pull` 管**：本地缺失时要到构建阶段才报错， +# 而且报错很晦涩（`failed to resolve source metadata ... 502 Bad Gateway`）， +# 看不出是"镜像源挂了"还是"代码写错了"（生产就这么卡过一次）。 +# 这里提前补齐：已存在则跳过（构建命中本地镜像，完全不访问远端）； +# 缺失且拉不到时给出明确的排障指引。 +ensure_dockerfile_base_images() { + if [[ "${BUILD_BACKEND}" != "true" && "${BUILD_WEB}" != "true" ]]; then return fi - warn "compose pull 不支持 --policy missing，回退为默认拉取策略。" - docker compose pull --ignore-buildable + + local registry images=() image + registry="$(resolve_base_registry)" + if [[ "${BUILD_BACKEND}" == "true" ]]; then + images+=("${registry}/library/node:22-bookworm" "${registry}/library/node:22-bookworm-slim") + fi + if [[ "${BUILD_WEB}" == "true" ]]; then + images+=("${registry}/library/node:22-bookworm" "${registry}/library/caddy:2-alpine") + fi + + while IFS= read -r image; do + [[ -n "${image}" ]] || continue + if docker image inspect "${image}" >/dev/null 2>&1; then + continue + fi + log "基础镜像本地缺失，尝试拉取：${image}" + docker pull "${image}" || fail "基础镜像拉取失败：${image} + 当前镜像源 BASE_REGISTRY=${registry} 不可用。可选处理： + 1) 在 .env 换一个可用源后重跑，例如 BASE_REGISTRY=docker.io + （docker.io 会走 daemon.json 的 registry-mirrors 列表自动故障转移） + 2) 或在能联网的机器上 docker pull 同名镜像，再 docker save | docker load 搬到本机 + 注意：Dockerfile/compose 里显式写死的 registry 会绕过 daemon.json 的 registry-mirrors。" + done < <(printf '%s\n' "${images[@]}" | sort -u) } build_images() { @@ -846,9 +892,9 @@ main() { if [[ "${BUILD_BACKEND}" == "true" || "${BUILD_WEB}" == "true" ]]; then log "基础镜像当前 digest（用于事后判断是否上游 tag 漂移导致全量重建）：" print_base_image_digests \ - "docker.m.daocloud.io/library/node:22-bookworm" \ - "docker.m.daocloud.io/library/node:22-bookworm-slim" \ - "docker.m.daocloud.io/library/caddy:2-alpine" + "$(resolve_base_registry)/library/node:22-bookworm" \ + "$(resolve_base_registry)/library/node:22-bookworm-slim" \ + "$(resolve_base_registry)/library/caddy:2-alpine" fi log "（--dry-run）以上是计划，未做任何改动。" return 0 diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 7312d75d..382dd9e7 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -6,7 +6,7 @@ x-json-log-rotation: &json-log-rotation services: postgres: - image: docker.m.daocloud.io/library/postgres:16-bookworm + image: ${BASE_REGISTRY:-docker.m.daocloud.io}/library/postgres:16-bookworm command: [ "postgres", @@ -51,7 +51,7 @@ services: - postgres_dev_data:/var/lib/postgresql/data minio: - image: docker.m.daocloud.io/minio/minio:latest + image: ${BASE_REGISTRY:-docker.m.daocloud.io}/minio/minio:latest restart: unless-stopped logging: *json-log-rotation command: server /data --address ":9000" --console-address ":9001" @@ -70,6 +70,8 @@ services: context: . dockerfile: deploy/docker/backend-dev.Dockerfile args: + # 基础镜像源（registry 前缀），与生产 compose 同一套语义。 + BASE_REGISTRY: ${BASE_REGISTRY:-docker.m.daocloud.io} DEBIAN_MIRROR: ${DEBIAN_MIRROR:-mirrors.aliyun.com} NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmmirror.com} restart: unless-stopped @@ -129,7 +131,7 @@ services: - ./apps/backend/data:/app/data frontend: - image: docker.m.daocloud.io/library/node:22-bookworm-slim + image: ${BASE_REGISTRY:-docker.m.daocloud.io}/library/node:22-bookworm-slim working_dir: /app restart: unless-stopped logging: *json-log-rotation @@ -151,7 +153,7 @@ services: - frontend_node_modules:/app/node_modules web: - image: docker.m.daocloud.io/library/caddy:2-alpine + image: ${BASE_REGISTRY:-docker.m.daocloud.io}/library/caddy:2-alpine restart: unless-stopped logging: *json-log-rotation depends_on: diff --git a/docker-compose.yml b/docker-compose.yml index 3cf50b9c..fe7d4666 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,7 +6,7 @@ x-json-log-rotation: &json-log-rotation services: postgres: - image: docker.m.daocloud.io/library/postgres:16-bookworm + image: ${BASE_REGISTRY:-docker.m.daocloud.io}/library/postgres:16-bookworm # 开启 pg_stat_statements，便于定位生产环境累计最耗时的 SQL。 # 内存类参数默认按 4 核 8G 且与其他服务共用的服务器设置（见 .env.server.example）。 command: @@ -75,6 +75,11 @@ services: context: . dockerfile: deploy/docker/backend.Dockerfile args: + # 基础镜像源（registry 前缀，默认 docker.m.daocloud.io）。 + # 显式指定的 registry 会绕过 daemon.json 的 registry-mirrors —— 加速源一抽风 + # 整轮构建就在 load metadata 阶段失败，其它可用镜像源帮不上忙。 + # 想要多源容灾就改成 docker.io：走 daemon 的 registry-mirrors 列表自动故障转移。 + BASE_REGISTRY: ${BASE_REGISTRY:-docker.m.daocloud.io} # 默认阿里云公共源；阿里云 ECS 内网可设 DEBIAN_MIRROR=mirrors.cloud.aliyuncs.com DEBIAN_MIRROR: ${DEBIAN_MIRROR:-mirrors.aliyun.com} NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmmirror.com} @@ -142,6 +147,7 @@ services: dockerfile: deploy/docker/frontend.Dockerfile args: APP_DOMAIN: ${APP_DOMAIN:-localhost} + BASE_REGISTRY: ${BASE_REGISTRY:-docker.m.daocloud.io} VITE_WORKER_SITE_URL: ${WORKER_SITE_ADDR:-https://worker.khhao.com} ALPINE_MIRROR: ${ALPINE_MIRROR:-mirrors.aliyun.com} NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmmirror.com}