seed-forge 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
核心原则（必读）
- 单一事实源：对外发布的
Dockerfile里用ARG暴露镜像 URL，默认值可以指向公共镜像；团队内部在 CI 或docker build --build-arg中注入组织制品库地址，避免在仓库里硬编码易失效的第三方 URL 且无出口替换。 - 公共镜像 ≠ 长期承诺：域名、路径、同步延迟会变；本 skill 提供维护节奏（建议每季度巡检 + 出问题时切换
ARG），不保证某一第三方站点永久可用。 - 合规优先：若公司有「仅允许内网源」或审计要求，以安全与合规为准，本 skill 中的公共地址仅作开发/组织内部集群 基线参考。
- Docker Hub 与语言源解耦：
docker pull/FROM慢，与apt、npm、pip慢是不同链路；不要只配一种就以为全覆盖。 - 大依赖优先 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
工作流（助手执行顺序）
- 确认栈与基镜像；若属 组织内部集群
deploy-apps、Woodpecker/Kaniko 或复用构建：先读REFERENCE-NEXUS-ECOSYSTEM-PRELOAD.md，标出大依赖是否需 manifest 预热。 - 选择 L0～L3b 中最小必要集（能内网 Nexus group 则优先 L3/L3b，L2 仅作无 Nexus 时的默认）。
- 在
Dockerfile顶部声明ARG（带合理默认值），RUN中只引用变量，避免魔法字符串散落；group URL 默认值优先于公网镜像站。 - 在 CI 中注入
build-arg或环境变量，与NO_PROXY（含nexus.{base_domain}、.{base_domain}）一并核对。 - 产出变更说明：group/manifest 名、preflight/预热命令、构建示例、回退方式。
推荐输出格式
执行完毕后输出极简回执：状态（✅ 成功 / ⚠️ 部分成功 / ❌ 失败）+ 关键结果（1-2 行，如操作对象、产出位置、下一步）。无需强制套用大表格。
约束
- 不在 skill 中嵌入任何密钥、token、私有内网 URL（由项目或 CI secret 注入）。
- 环境适配：主机名 / 为逻辑名示例；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