base-cn-registry-mirror-strategy

国内镜像源与代理分层策略(Docker / Debian / Alpine / Node / Python / Maven / Gradle / Go),用于 Dockerfile 与 CI 的可维护加速。

SKILL.md

GitHub

base-cn-registry-mirror-strategy

用途

在中国大陆网络或跨境不稳定场景下,为容器镜像与语言包拉取提供一套可维护的分层策略:先定「谁负责加速」(宿主机 Docker、CI 注入、Dockerfile 内显式换源),再按栈选用可替换的默认候选 URL,避免每次临时拼命令。

适用于:

  • 编写、审查或重构 Dockerfile、多阶段构建
  • 配置 CI(含 Kaniko、BuildKit、自托管 Runner)
  • 与团队内 Nexus / Harbor 策略对齐前的公共默认基线

输入

  • 基础镜像家族:Debian/Ubuntu 系、Alpine,或其它(需单独评估)
  • 语言与工具:Node/npm、Python/pip、Maven、Gradle、Go modules
  • 构建环境:本地、云 CI、是否允许访问外网公共镜像
  • 组织是否提供:Docker Registry 镜像、PyPI/npm/Maven 代理、HTTP(S)_PROXY

输出

  • 分层策略表:每一层配置什么、何时用、与安全的边界
  • 默认候选:阿里云、清华 TUNA、中科大等可互换的「默认占位」,团队应收敛为单一事实源
  • 可复制片段:见 references/REFERENCE-MIRROR-RECIPES.md

核心原则(必读)

  1. 单一事实源:对外发布的 Dockerfile 里用 ARG 暴露镜像 URL,默认值可以指向公共镜像;团队内部在 CI 或 docker build --build-arg 中注入组织制品库地址,避免在仓库里硬编码易失效的第三方 URL 且无出口替换。
  2. 公共镜像 ≠ 长期承诺:域名、路径、同步延迟会变;本 skill 提供维护节奏(建议每季度巡检 + 出问题时切换 ARG),不保证某一第三方站点永久可用。
  3. 合规优先:若公司有「仅允许内网源」或审计要求,以安全与合规为准,本 skill 中的公共地址仅作开发/组织内部集群 基线参考。
  4. Docker Hub 与语言源解耦:docker pull / FROM 慢,与 apt、npm、pip 慢是不同链路;不要只配一种就以为全覆盖。
  5. 大依赖优先 Nexus 预热,而非仅 CN 公网镜像:凡 Nexus 能承接的生态(pip、npm、Maven、Gradle、Go 等),若存在大体积或 CI 关键路径依赖,应建议 Nexus group 统一入口 + hosted/manifest 预热;仅把 ARG 改成 npmmirror / 阿里云 / goproxy.cn 仍可能很慢(公网 CDN、代理、镜像站滞后)。决策表与分生态清单见 references/REFERENCE-NEXUS-ECOSYSTEM-PRELOAD.md。

分层策略

层级 解决什么问题 典型手段 备注
L0 宿主机 / Runner docker pull、FROM 拉取慢 /etc/docker/daemon.json 的 registry-mirrors;或企业内 Harbor 前置缓存 影响构建机拉基础镜像,不写入 Dockerfile
L1 CI 环境变量 构建阶段内的网络工具与 CLI HTTP_PROXY/HTTPS_PROXY/NO_PROXY;DOCKER_BUILDKIT=1 组织内部集群 宿主机默认代理见 组织内部集群-组织内部集群-ops/references/REFERENCE-组织内部集群-OUTBOUND-HTTP-PROXY.md
L2 Dockerfile ARG 可重复、可审计的换源 各语言 *_MIRROR / *_URL 默认 + build-arg 覆盖 推荐作为团队统一模式
L3 仅内网发布 出网受限 FROM 与包源全部改为内网 registry / Nexus group 与 infra-source-image-pipeline-ops 等流水线 skill 配合
L3b Nexus 预热 大 wheel/jar、钉死版本、镜像站缺包 hosted 上传 + group 消费;manifest + Ansible(PyPI 已示范) 组织内部集群 deploy-apps / Woodpecker 标准路径;见 REFERENCE-NEXUS-ECOSYSTEM-PRELOAD.md

默认候选(占位,可被 ARG 覆盖)

以下仅为常见公共加速(L2 应急或小依赖);组织内部集群 CI 与大依赖场景默认应改为 Nexus group,勿把本段当作 deploy-apps 终态。团队应在内网文档固定一套;多选一即可,不必同时使用。

  • Debian apt:https://mirrors.aliyun.com/debian(主)/ https://mirrors.tuna.tsinghua.edu.cn/debian(备)
  • Alpine apk:https://mirrors.aliyun.com/alpine/(注意版本目录 v3.xx/main 等)
  • npm:https://registry.npmmirror.com
  • pip:https://pypi.tuna.tsinghua.edu.cn/simple 或 https://mirrors.aliyun.com/pypi/simple/
  • Maven Central 聚合:https://maven.aliyun.com/repository/public
  • Gradle 插件与依赖:优先通过 settings.gradle / init.gradle 指到组织 Nexus;公共可用阿里云 Maven 聚合作临时替代(见参考文档)
  • Go:GOPROXY=https://goproxy.cn,direct

工作流(助手执行顺序)

  1. 确认栈与基镜像;若属 组织内部集群 deploy-apps、Woodpecker/Kaniko 或复用构建:先读 REFERENCE-NEXUS-ECOSYSTEM-PRELOAD.md,标出大依赖是否需 manifest 预热。
  2. 选择 L0~L3b 中最小必要集(能内网 Nexus group 则优先 L3/L3b,L2 仅作无 Nexus 时的默认)。
  3. 在 Dockerfile 顶部声明 ARG(带合理默认值),RUN 中只引用变量,避免魔法字符串散落;group URL 默认值优先于公网镜像站。
  4. 在 CI 中注入 build-arg 或环境变量,与 NO_PROXY(含 nexus.{base_domain}、.{base_domain})一并核对。
  5. 产出变更说明:group/manifest 名、preflight/预热命令、构建示例、回退方式。

推荐输出格式

执行完毕后输出极简回执:状态(✅ 成功 / ⚠️ 部分成功 / ❌ 失败)+ 关键结果(1-2 行,如操作对象、产出位置、下一步)。无需强制套用大表格。

约束

  • 不在 skill 中嵌入任何密钥、token、私有内网 URL(由项目或 CI secret 注入)。
  • 环境适配:主机名 <host>/<host> 为逻辑名示例;IP/域名使用占位符({hs_host}/{base_domain}/{root_domain} 等),解析自 ~/.harness-ai-kit/config.yaml 顶层字段,规范见 docs/config-governance.md。
  • 修改官方基础镜像内源文件前,确认许可证与镜像维护方约定;多阶段构建中构建阶段换源、运行阶段尽量不再保留构建机上的敏感配置。
  • 若与 infra-woodpecker-pipeline-ops 等技能同时出现:FROM 指向 Harbor 基座镜像时,语言包源仍可按本 skill 单独配置。

专题引用

  • Nexus 全生态私服与预热(大依赖必看):references/REFERENCE-NEXUS-ECOSYSTEM-PRELOAD.md
  • 组织内部集群 执行编排(manifest、波次 B、Harbor warm、Woodpecker inspect):infra-artifact-readiness-ops
  • 长篇可复制片段与命令:references/REFERENCE-MIRROR-RECIPES.md(在 harness-ai-kit 仓库内路径为 skills/base-cn-registry-mirror-strategy/references/REFERENCE-MIRROR-RECIPES.md;若以「02-工程工作空间」为根,则为 {checkout_dir}/skills/base-cn-registry-mirror-strategy/references/REFERENCE-MIRROR-RECIPES.md)
  • 组织内部集群 宿主机出站 HTTP 代理(GitHub / Google 等 GFW 站点):组织内部集群-组织内部集群-ops/references/REFERENCE-组织内部集群-OUTBOUND-HTTP-PROXY.md
  • Docker daemon 代理验收:references/REFERENCE-DOCKER-DAEMON-PROXY-CHECKS.md(大小写变量、重复 drop-in、NO_PROXY 和 daemon/容器层级)

维护建议

  • 每季度:任选一条最小构建(如 docker build --pull)验证各 ARG 默认仍可用。
  • 故障时:先切备用镜像域名,再评估是否改为组织 Nexus 单一入口。

参考文档:

  • references/REFERENCE-README.md