java-template/PROXY_CONFIG.md

Docker 代理配置指南

问题说明

在国内网络环境下，直接拉取 Docker Hub 镜像可能遇到以下问题：

• ❌ 连接超时 (i/o timeout)
• ❌ 拉取速度慢
• ❌ TLS handshake timeout

解决方案

使用本地代理（ClashX、V2rayU 等）来加速 Docker 镜像拉取。

🚀 快速开始

1. 确认代理服务运行

# 检查代理端口是否可用（默认 7890）
curl --proxy http://127.0.0.1:7890 https://www.google.com

# 如果成功，说明代理正常工作

2. 测试代理配置

# 运行测试脚本
./test-proxy.sh

# 输出示例：
# 🔍 测试 Docker 代理配置
# 🔧 代理配置:
#    HTTP_PROXY: http://127.0.0.1:7890
#    HTTPS_PROXY: http://127.0.0.1:7890
# 🌐 测试代理连接 Docker Hub...
# ✅ 代理连接正常
# 📥 测试拉取基础镜像 (mysql:8.0)...
# ✅ 镜像拉取成功

3. 构建镜像

# 使用默认代理配置（7890 端口）
./build-and-push.sh mysql

# 或者自定义代理端口
PROXY_PORT=7891 ./build-and-push.sh mysql

📋 配置说明

方式一：环境变量（临时）

# 设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,*.local

# 构建镜像
./build-and-push.sh mysql

方式二：修改配置文件（永久）

编辑 monitoring-versions.env：

# 代理配置 (用于拉取 Docker Hub 镜像)
PROXY_PORT=7890
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890
NO_PROXY=localhost,127.0.0.1,*.local

方式三：命令行参数（一次性）

# 自定义代理端口
PROXY_PORT=7891 ./build-and-push.sh mysql

# 完全自定义代理地址
HTTP_PROXY=http://proxy.example.com:8080 \
HTTPS_PROXY=http://proxy.example.com:8080 \
./build-and-push.sh mysql

🔧 代理原理

构建时代理配置

脚本会自动将代理配置传递给 Docker 构建过程：

docker buildx build \
  --build-arg HTTP_PROXY=http://127.0.0.1:7890 \
  --build-arg HTTPS_PROXY=http://127.0.0.1:7890 \
  --build-arg NO_PROXY=localhost,127.0.0.1,*.local \
  ...

代理生效范围

代理配置在以下场景生效：

1. Docker 拉取基础镜像

   FROM mysql:8.0  # 通过代理从 Docker Hub 拉取
   

2. Dockerfile 中的网络请求

   RUN apt-get update  # 通过代理访问软件源
   RUN pip install -r requirements.txt  # 通过代理下载 Python 包
   

3. 构建过程中的网络操作

   • Maven 依赖下载
   • NPM 包下载
   • Go modules 下载

🌐 常见代理端口

代理工具	默认端口
ClashX	7890
ClashX Pro	7890
V2rayU	1087
Surge	6152
Shadowsocks	1080

🔍 验证代理生效

方法 1: 查看构建日志

./build-and-push.sh mysql 2>&1 | grep -i proxy

# 应该看到：
# 🔧 代理配置:
#    HTTP_PROXY: http://127.0.0.1:7890
#    HTTPS_PROXY: http://127.0.0.1:7890

方法 2: 手动拉取镜像

# 设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 拉取镜像
docker pull mysql:8.0

# 如果速度很快，说明代理生效

方法 3: 检查网络流量

在代理工具（如 ClashX）的日志中查看是否有 Docker 相关的连接记录。

🛠️ 故障排查

问题 1: 代理连接失败

症状:

⚠️  代理连接可能有问题，将尝试继续...

解决方案:

# 1. 检查代理服务是否运行
lsof -i :7890

# 2. 测试代理连接
curl --proxy http://127.0.0.1:7890 https://www.google.com

# 3. 检查代理配置
cat ~/.config/clash/config.yaml  # ClashX 配置

问题 2: 镜像拉取仍然超时

症状:

ERROR: failed to do request: Head "https://registry-1.docker.io/...": dial tcp: i/o timeout

解决方案:

# 1. 确认代理规则包含 Docker Hub
# 在 ClashX 中确保 docker.io 走代理

# 2. 尝试使用 SOCKS5 代理
export HTTP_PROXY=socks5://127.0.0.1:7891
export HTTPS_PROXY=socks5://127.0.0.1:7891

# 3. 增加超时时间
export DOCKER_CLIENT_TIMEOUT=120
export COMPOSE_HTTP_TIMEOUT=120

问题 3: 部分下载仍然失败

症状:

apt-get update 超时
pip install 超时

解决方案:

在 Dockerfile 中显式使用代理：

# APT 使用代理
RUN apt-get update -o Acquire::http::Proxy="http://host.docker.internal:7890"

# pip 使用代理
RUN pip install --proxy http://host.docker.internal:7890 -r requirements.txt

# Maven 使用代理
ENV MAVEN_OPTS="-DproxySet=true -DproxyHost=host.docker.internal -DproxyPort=7890"

问题 4: NO_PROXY 配置错误

症状:

无法连接到 localhost:8080 (Harbor)

解决方案:

# 确保 NO_PROXY 包含本地地址
export NO_PROXY=localhost,127.0.0.1,*.local,host.docker.internal

💡 最佳实践

1. 混合使用代理和镜像源

# 使用代理拉取基础镜像
export HTTP_PROXY=http://127.0.0.1:7890

# 在 Dockerfile 中使用国内镜像源
RUN sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

2. 分层代理配置

# Docker 守护进程代理（全局）
# 编辑 ~/.docker/config.json
{
  "proxies": {
    "default": {
      "httpProxy": "http://127.0.0.1:7890",
      "httpsProxy": "http://127.0.0.1:7890",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

# 构建时代理（临时）
./build-and-push.sh mysql

3. 自动代理检测

脚本已内置代理检测功能：

# 脚本会自动检测代理是否可用
🔧 代理配置:
   HTTP_PROXY: http://127.0.0.1:7890
   HTTPS_PROXY: http://127.0.0.1:7890
   NO_PROXY: localhost,127.0.0.1,*.local
✅ 代理连接正常

📚 相关资源

• Docker 代理配置文档
• Docker Buildx 代理配置
• ClashX 使用指南

🔗 相关文档

• BUILD_WITH_HARBOR.md - Harbor 构建指南
• DOCKER_README.md - Docker Compose 使用指南
• monitoring-versions.env - 版本和配置文件

---

最后更新: 2025-11-25 版本: 1.0.0