merge: 合并 dev 到 main (基础镜像源可配置 BASE_REGISTRY)

2026-10-12 16:33:54 +08:00
parent 7a6a2350b0 56ca479c6b
commit 26780c9a4b
8 changed files with 92 additions and 16 deletions
@@ -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
@@ -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
@@ -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

@@ -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

@@ -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
@@ -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
@@ -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:
@@ -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}