Docker 构建网络问题排查

构建时出现类似错误：

text 复制代码

failed to resolve reference "docker.io/oven/bun:1@sha256:..."
Head "https://registry-1.docker.io/v2/oven/bun/manifests/sha256:...": dial tcp ...:443: i/o timeout

表示 服务器无法访问 Docker Hub （registry-1.docker.io）。国内云主机（如腾讯云 Ubuntu）上很常见。

1. 快速确认

bash 复制代码

# 测试能否访问 Docker Hub
curl -m 10 -I https://registry-1.docker.io/v2/

# 测试拉取（任选一个基础镜像）
sudo docker pull hello-world

若超时，需要先解决 镜像加速 ，再执行 ./bin/docker.sh rebuild。

2. 方案 A：配置 Docker 镜像加速（推荐，腾讯云）

编辑 /etc/docker/daemon.json（不存在则新建）：

bash 复制代码

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

腾讯云内网机器优先使用 mirror.ccs.tencentyun.com。

验证（必须能看到镜像地址，否则说明配置未生效，见第 3 节）：

bash 复制代码

sudo docker info 2>&1 | grep -i mirror
# 或（Docker 29+）
sudo docker info --format '{{json .RegistryConfig.Mirrors}}'

sudo docker pull oven/bun:1

3. 镜像加速已写 daemon.json 但仍直连 docker.io

3.1 现象

docker info | grep mirror 无输出
docker pull 仍访问 https://registry-1.docker.io/... 并超时
registry-1.docker.io 解析到 31.13.88.26 等明显错误的 IP（非 Docker 官方地址）

3.2 排查：安装方式与配置路径

Ubuntu 上若通过 snap 安装 Docker，配置文件路径是：

text 复制代码

/var/snap/docker/current/config/daemon.json

而不是 /etc/docker/daemon.json。

排查：

bash 复制代码

which docker
docker --version
dpkg -l | grep -E 'docker.io|docker-ce'
snap list 2>/dev/null | grep docker
sudo journalctl -u docker -n 5 --no-pager | grep commit

journalctl 若出现 commit="29.1.3-0ubuntu3~24.04.2" 这类格式，说明是 Ubuntu apt 自带的 docker.io ，不是 Docker 官网的 docker-ce。

snap 版写入配置：

bash 复制代码

sudo mkdir -p /var/snap/docker/current/config
sudo tee /var/snap/docker/current/config/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}
EOF
sudo snap restart docker

sudo docker info --format '{{json .RegistryConfig.Mirrors}}'

apt 版 使用 /etc/docker/daemon.json。若 restart 后 Mirrors 仍为空，可试 stop + start：

bash 复制代码

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}
EOF
sudo chmod 644 /etc/docker/daemon.json
sudo systemctl stop docker
sudo systemctl start docker
sudo docker info --format '{{json .RegistryConfig.Mirrors}}'

输出应类似 ["https://mirror.ccs.tencentyun.com/"]，不能为空。

注意：Docker 29 已无 RegistryConfig.MirrorQueue 字段，勿用旧文档里的 --format '{``{json .RegistryConfig.MirrorQueue}}'，会报模板错误。

3.3 换装 Docker 官方 docker-ce（mirror 仍为空时）

Ubuntu 自带的 docker.io 在部分环境下不加载 /etc/docker/daemon.json 中的 registry-mirrors。可改用官方 docker-ce。

卸载会停止现有容器，请先备份 ./data 等业务数据。

卸载 docker.io：

bash 复制代码

sudo apt-get remove -y docker.io docker-doc containerd runc 2>/dev/null

安装 docker-ce（Ubuntu 24.04 示例）：

bash 复制代码

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

重新配置腾讯云镜像加速：

bash 复制代码

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}
EOF

sudo systemctl restart docker
sudo docker info --format '{{json .RegistryConfig.Mirrors}}'

验证基础镜像拉取：

bash 复制代码

sudo docker pull oven/bun:1
sudo docker pull golang:1.26.1-alpine
sudo docker pull debian:bookworm-slim

三条均成功后，再执行 ./bin/docker.sh rebuild。

4. 关于 Dockerfile 中的 `@sha256:` 固定 digest

当前 Dockerfile 基础镜像带 digest pin，例如：

dockerfile 复制代码

FROM oven/bun:1@sha256:0733e50325078969732ebe3b15ce4c4be5082f18c4ac1a0f0ca4839c2e4e42a7

若配置 mirror 后仍失败，可在构建前预拉所有基础镜像：

bash 复制代码

sudo docker pull oven/bun:1
sudo docker pull golang:1.26.1-alpine
sudo docker pull debian:bookworm-slim

再执行 rebuild。

5. 与 `DOCKER_BUILDKIT=0` 的关系

日志中的 DEPRECATED: The legacy builder 只是提示旧版 builder 将被弃用，不是失败原因 。

Hub 拉取超时发生在 Step 1 拉取基础镜像，与 BuildKit 开闭无关。

低内存机器仍建议：

bash 复制代码

sudo DOCKER_BUILDKIT=0 ./bin/docker.sh rebuild

但 必须先能拉到 mirror 上的基础镜像。

6. 检查清单

sudo docker info --format '{``{json .RegistryConfig.Mirrors}}' 非空
sudo docker pull oven/bun:1 成功
sudo docker pull golang:1.26.1-alpine 成功
sudo docker pull debian:bookworm-slim 成功
构建前 ./bin/docker.sh stop 释放内存（4G 机器）
再执行 sudo DOCKER_BUILDKIT=0 ./bin/docker.sh rebuild

7. 相关文档

规模化部署与稳定性 --- 小内存构建、不要在生产机长时间 build
CSDN 踩坑实录 --- 腾讯云 2U4G 实际操作记录
bin/docker.sh --- rebuild / update 命令说明

Docker 构建网络问题排查

构建时出现类似错误：

1. 快速确认

2. 方案 A：配置 Docker 镜像加速（推荐，腾讯云）

3. 镜像加速已写 daemon.json 但仍直连 docker.io

3.1 现象

3.2 排查：安装方式与配置路径

3.3 换装 Docker 官方 docker-ce（mirror 仍为空时）

4. 关于 Dockerfile 中的 @sha256: 固定 digest

5. 与 DOCKER_BUILDKIT=0 的关系

6. 检查清单

7. 相关文档

4. 关于 Dockerfile 中的 `@sha256:` 固定 digest

5. 与 `DOCKER_BUILDKIT=0` 的关系