Docker Compose 镜像替换整体方案文档

docker compose 相关替换未完整验证，如有问题，可留言或自行处理。

一、方案背景

在跨地域或受网络限制的环境中，直接拉取 Docker 官方镜像仓库（如 ghcr.io、quay.io）可能面临速度缓慢或访问失败的问题。本方案通过镜像前缀替换机制，将官方镜像源自动重定向到国内镜像站（如南京大学镜像源），同时兼容 docker compose 全生命周期操作，实现无缝镜像加速。

二、核心功能

智能镜像替换
- 支持 k8s.gcr.io、gcr.io、ghcr.io 等常见仓库到国内镜像站的重定向
- 优先级匹配长前缀（如 k8s.gcr.io 优先于 gcr.io）
全命令兼容
- 覆盖 docker compose pull/build/up/run 等操作
- 透传原生 docker 命令参数，无侵入式替换
多场景适配
- 自动解析 docker-compose.yml 中的 image 和 build 指令
- 支持未指定 image 字段的构建服务生成默认镜像名称
调试增强
- 彩色日志标注操作阶段（DEBUG/WARN/ERROR）
- 显示最终镜像列表及替换路径

三、实现机制

1. 镜像替换规则

declare -A DOCKER_REPLACE_RULES=(
  ["k8s.gcr.io/"]="gcr.nju.edu.cn/google-containers/"
  ["gcr.io/"]="gcr.nju.edu.cn/"
  ["ghcr.io/"]="ghcr.nju.edu.cn/"
  ["nvcr.io/"]="ngc.nju.edu.cn/"
  ["quay.io/"]="quay.nju.edu.cn/"
)

注：规则按前缀长度优先匹配，用户可自定义扩展。

2. 关键流程

命令拦截
- 覆盖 docker compose 命令，拦截 pull/build/up/run 操作
- 解析 -f 参数或自动查找 docker-compose.yml
镜像解析
- 使用 yq 解析 Compose 文件中的 image 字段
- 未指定 image 时生成 local/<项目名>_<服务名>:latest 格式的默认镜像名
路径处理
- 自动修正 build.context 为空时的当前目录路径
- 检查 Dockerfile 是否存在，跳过无效构建
镜像拉取
- 按规则替换镜像前缀并执行 docker pull
- 拉取后重标签为原始镜像名，清理中间镜像

四、使用说明

1. 环境要求

操作系统: Linux/macOS（需 bash 4.0+）
依赖工具: docker、yq（v4.30.6+）
权限: Docker 需具有 sudo 或用户组权限

2. 部署步骤

# 1. 下载脚本
wget https://erbantou.com/upload/2025/03/docker-compose-helper-5f04f76a0d5648ed9b34cc54f3ee84b6.sh -O ~/.docker-compose-helper.sh

# 2. 加载脚本（建议加入 shell 配置文件）
echo "source ~/.docker-compose-helper.sh" >> ~/.bashrc
source ~/.bashrc

# 3. 验证安装
docker compose version
yq --version

3. 使用示例

# 拉取镜像并替换
docker compose pull

# 启动服务（自动处理构建镜像）
docker compose up -d

# 直接拉取单个镜像（触发替换）
docker pull quay.io/nginx:latest

五、注意事项

1. 必须项

yq 版本强制要求
必须使用 yq v4.30.6+，旧版（如 v3.x）会因语法不兼容导致解析失败。安装命令：

# Linux
sudo wget https://github.com/mikefarah/yq/releases/download/v4.30.6/yq_linux_amd64 -O /usr/local/bin/yq
sudo chmod +x /usr/local/bin/yq

# macOS
brew install yq

Compose 文件规范
- 使用 image 字段明确指定镜像名称（推荐）
- 若使用 build 指令，必须指定 context 和 dockerfile 的合法路径

2. 建议项

镜像加速器配置
在 /etc/docker/daemon.json 添加国内镜像源以加速非替换镜像：
```
{
  "registry-mirrors": ["https://docker.nju.edu.cn"]
}
```
路径规范
- 避免使用相对路径 ..（如 build: ../app）
- 若 build.context 为空，脚本将默认指向当前目录

3. 常见问题处理

镜像拉取超时
调整 Docker 客户端超时时间：
```
export DOCKER_CLIENT_TIMEOUT=120
```

Dockerfile 缺失警告
若服务不需要构建，在 Compose 文件中注释 build 指令：

services:
  web:
    image: ghcr.io/ready-to-use-image:latest
    # build: .  # 禁用构建

调试模式
通过 bash -x 跟踪执行流程：

bash -x ~/.docker-compose-helper.sh compose pull

六、附录

1. 日志颜色说明

蓝色 ([DEBUG]): 流程跟踪信息
黄色 ([WARN]): 非阻断性警告
红色 ([ERROR]): 需立即处理的错误

2. 镜像替换示例

原始镜像	替换后镜像
`ghcr.io/open-webui:main`	`ghcr.nju.edu.cn/open-webui:main`
`quay.io/nginx:latest`	`quay.nju.edu.cn/nginx:latest`

目录CONTENT