故障排查

Docker pull 正常，容器里却无法联网：代理到底配在哪一层？

镜像能拉取，不代表构建步骤和容器应用走同一个代理。按请求发生的位置定位配置，用有限对照验证，再恢复临时设置。

2026/10/26 · 3 项官方来源

先看重点pull 成功只证明对应拉取路径可用。构建步骤与运行中的应用可能使用另一套代理；先找请求发生的位置，再改那一层。

先定位：失败的是哪一个请求

终端显示镜像拉取成功，随后容器中的下载命令却超时，这两件事可以同时成立。先记下失败命令、目标域名和完整错误类型；不要直接把电脑上所有代理开关重置。镜像仓库和软件源往往也不是同一个目标，连通前者不能证明后者可达。

拉取镜像：独立 Docker Engine 的 daemon 负责访问仓库；Docker Desktop 还要按自身代理设置判断路径。
构建镜像：先区分获取基础镜像失败，还是 Dockerfile 的 RUN 步骤内下载失败。后者发生在构建环境。
运行容器：已经启动的应用访问网站或接口，要看该进程实际读取什么配置。环境变量存在，也不代表所有应用都会采用。

如果使用远程 Docker context 或独立 builder，网络请求可能发生在另一台机器。先确认正在操作哪个环境，不能把本机代理地址当成远端可用的地址。单纯宿主机终端不通，可先看浏览器与终端的代理区别；WSL 本身失败则看WSL 的网络入口。

Engine 与 Desktop：入口不能照抄

Docker 官方说明，独立 Engine 可以给 dockerd 配置代理；daemon.json 的代理字段和服务启动环境是这一层的选项。只在当前终端 export 变量，不等于已经运行的系统服务读到了新值。修改 daemon 配置通常涉及重启，应先评估现有容器和工作负载，不要为修一个应用随手重启服务。

Docker Desktop 不采用 daemon.json 中的代理设置。在 Desktop 的代理设置中核对系统代理或手动代理，并按当前版本区分 Docker Desktop proxy 与 Containers proxy；官方网络文档也区分了镜像拉取和容器流量的代理路径。不要把 Linux 的 systemd 操作直接套到 Mac 或 Windows Desktop。

既然 pull 已成功，就先保留它的有效设置。接下来查失败的构建步骤或应用，比重复修改镜像拉取代理更有针对性。

客户端配置如何传给构建和新容器

~/.docker/config.json 中的 proxies 可为新容器注入代理环境变量，并为构建提供代理参数；它不是给 Docker CLI 或 daemon 本身配置出站代理。保存后也不会追溯改变已存在的容器。

需要临时区分范围时，构建侧使用官方支持的 --build-arg 代理参数，运行侧使用 --env 或应用自己的设置。只选失败的一层做对照，不要同时修改三处。代理入口必须是对应环境实际可达、且你有权使用的 HTTP/HTTPS 代理，不是机场订阅链接。

不要把代理地址或密码写进 Dockerfile 的 ENV：这会把设置带进镜像。容器环境变量也可能被 inspect 或远程 API 读取；排查时不要直接贴出整份 config、环境变量或构建日志。需要认证时遵循组织认可的凭据方案，不把密码拼在可保存的示例命令里。

127.0.0.1 指向谁，比端口更重要

在通常使用独立网络命名空间的容器里，127.0.0.1 指向容器自身。把宿主机的 127.0.0.1:7890 原样传进去，可能是在连接一个根本没有代理进程的地方；但 host 网络等模式另有行为，不能脱离网络模式判断。

先核对代理所在机器、监听地址、容器网络模式与实际端口。即使知道宿主机地址，也不等于代理监听允许该路径访问。不要为试通而开放所有网卡、关闭防火墙或扩大局域网权限；需要调整边界时，让维护者确认允许的路径。端口协议混淆可查HTTP、SOCKS5 与 mixed 端口。

只做一次有界对照，读清失败阶段

先记录原应用错误与当前配置来源，保留原值。检查目标是否命中 NO_PROXY；不同工具对变量大小写和排除语法可能不同。
选一个已有、获准使用且已经包含 curl 的诊断容器，在其内部测试你有权访问的小页面。不要为了诊断临时安装软件、挂载宿主机目录或给容器提权。
下例仅演示在该容器内进行一次显式 HTTP 代理请求；将 proxy.example.com:3128 换成已确认可达的入口。它不是可直接使用的代理，也不含认证。

curl --proxy http://proxy.example.com:3128 --noproxy example.invalid --connect-timeout 5 --max-time 15 --output /dev/null --write-out "HTTP=%{http_code}; CONNECT=%{http_connect}\n" https://example.com/

--noproxy example.invalid 只使这次目标不命中排除列表；命令不会修改系统代理。请先确认这个目标允许通过所选代理访问。这里用 GET 获取小页面，而不是用 HEAD 结果代替内容访问结果。

解析代理地址失败或连接被拒绝：先查入口与监听，尚不能推断镜像源或目标网站故障。
CONNECT=407：停在代理认证层，核对授权与认证方式；不要连续试密码。
CONNECT=200 后仍失败：隧道建立不等于目标内容返回，继续区分 TLS 与 HTTP 响应。
401、403 或明确的访问限制：停止请求，交由目标服务或组织处理；不换出口绕过。

若显式请求成功而原应用失败，下一步是核对应用配置和同一目标的请求差异，不能据此宣布整个容器网络恢复。不要用关闭证书校验来掩盖 TLS 错误。本文没有声称在你的 Docker、代理或账户上实测。

验证原任务，再撤销临时配置

只修已定位的配置来源，然后在原构建步骤或原应用中复验相同目标。构建参数仅用于相应构建，不能代替运行时设置；修改新容器默认代理也不能指望旧容器自动更新。涉及重建时先保存业务数据与启动参数，避免把删除容器当成修复网络的第一步。

结果不符合预期时，恢复本次改动前的应用设置、配置片段或启动参数，结束临时诊断会话；单次 curl 参数随进程结束失效。不要清空整份 Docker 配置，它还可能包含登录信息和其他上下文。

求助时提供 Engine/Desktop 类型与版本、context/builder 所在位置、失败阶段、网络模式和脱敏错误；不要附上完整 inspect、订阅地址、认证头或 config.json。按日志脱敏清单处理后再发送。

官方参考

2026/10/26 复核；界面与支持范围以后续官方说明为准。