企业官网建设流程全解析

受限网络下 PentAGI 拉取 Docker Hub 镜像失败怎么排查与配置 registry mirror？

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi

如果你的部署主机无法直连 Docker Hub（docker.io），在安装 PentAGI 或执行docker compose up时就会卡在镜像拉取上：安装器的网络检查会验证 Docker Hub 可达性，Compose 主栈的多个服务也依赖 Docker Hub 托管的镜像。本文基于 PentAGI 的 README 与安装器 checker 文档，给出这条受限网络故障的排查顺序、Docker 守护进程 registry mirror 的配置方式、以及配置后的验证方法。

为什么改 PentAGI 环境变量解决不了

PentAGI 的文档首先点破一个常见误区：如果环境无法直连docker.io，只改 PentAGI 的环境变量通常不足以修复镜像下载失败。PentAGI 的 Compose 服务仍然依赖 Docker 自身的 registry 访问，安装器的网络检查也会验证 Docker Hub 可达性（见 README 的 Restricted Networks, Docker Mirrors, and Proxies 与 checker 文档）。

具体来说，以下 PentAGI 变量都不能替代 Docker daemon 的 registry 配置，它们只影响 PentAGI 应用镜像或 worker 镜像的选型，前提是 Docker 本身已经能拉到镜像：

• PENTAGI_IMAGE（主服务镜像，默认vxcontrol/pentagi:latest）；
• DOCKER_DEFAULT_IMAGE（通用任务默认镜像，debian:latest）；
• DOCKER_DEFAULT_IMAGE_FOR_PENTEST（渗透测试任务镜像，vxcontrol/kali-linux）。

先定位：安装器网络检查在验证什么

checker 文档说明了安装器网络检查的三层验证流程，失败时会给出对应的详细失败信息（来源：checker.md 及 helpers.go）：

1. DNS 解析：测试能否解析docker.io；失败时提示• DNS resolution failed for docker.io；
2. HTTPS 连通性：发起 proxy-aware 的 HTTPS 访问；失败时提示• Cannot reach external services via HTTPS；
3. Docker 拉取测试：当本地与 worker 两个 Docker client 均可用时，实际尝试拉取debian:latest（默认 worker 镜像）；失败时提示• Cannot pull Docker images from registry。

据此，排查应从第一层开始确认：主机能否解析并访问docker.io。

按文档顺序排查与修复

checker 文档给出了推荐的修复顺序（recommended remediation order）：

第 1 步：确认docker.io的解析与连通性。确认主机具备通用互联网访问，且能解析docker.io。这一层不通过，后面的 proxy/mirror 配置都没有意义。

第 2 步：区分代理配置的作用范围。如果你的环境需要出站代理承载 PentAGI 或安装器的 HTTP 流量，设置PROXY_URL环境变量即可；但要注意文档的明确边界——Docker 拉取镜像不走PROXY_URL，Docker 的 registry 访问需要在 Docker daemon 或 Docker Desktop 层面单独配置代理（daemon proxy）。也就是说：

• 安装器/应用 HTTP 流量受阻 → 用PROXY_URL；
• Docker 镜像拉取受阻 → 改 Docker daemon 或 Docker Desktop 的 proxy 设置。

第 3 步：配置 registry mirror。当 Docker Hub 被封锁或遭遇严重限流时，在运行安装器或docker compose up之前，在 Docker daemon / Docker Desktop 层面配置组织批准的 registry mirror 或 registry proxy。

第 4 步：重启 Docker 并重跑检查。修改 daemon 配置后必须重启 Docker，然后重新运行安装器检查或 Compose 启动。

配置 daemon 的 registry-mirrors

README 给出的 Docker daemon 镜像配置示例如下，其中https://mirror.example.com为文档占位地址，需要替换为你所在组织实际批准的镜像端点：

{ "registry-mirrors": ["https://mirror.example.com"] }

• 在 Linux 上，该配置通常写入/etc/docker/daemon.json。修改该文件会影响整机的 Docker daemon 行为，操作前请确认你有相应权限，且保留原有配置项。
• 在 Docker Desktop 上，使用等价的 Docker Engine 或 proxy 设置。

验证是否生效

文档给出的验证方式是：重启 Docker 后，重新运行安装器网络检查（installer checks）或docker compose up。对应上文三层检查，成功信号依次是：

• DNS 能解析docker.io；
• HTTPS 连通性检查通过；
• debian:latest试拉取成功，不再出现Cannot pull Docker images from registry。

如果安装器网络检查通过且 Compose 服务全部拉起，则 registry mirror 配置已对当前任务生效。

限制：Docker Hub mirror 覆盖不到的镜像

这是最容易踩的坑：一个 Docker Hub mirror只能覆盖 Docker Hub 托管的镜像（例如vxcontrol/*）。而 PentAGI 的 Compose 文件里还有来自其他 registry 的镜像，它们不受 Docker Hub mirror 影响，仍需直连或各自批准的 proxy/mirror 路径（来源：README.md 与 checker.md）：

• 主 Compose 栈包含quay.io/prometheuscommunity/postgres-exporter（docker-compose.yml）；
• 可选的 observability 栈包含gcr.io/cadvisor/cadvisor:v0.51.0（docker-compose-observability.yml）。

checker 文档对此的结论是：仅配 Docker Hub mirror 不足以支撑完整部署（a full deployment），quay.io与gcr.io也必须具备可达性或单独的镜像/代理路径。如果你没有部署 observability 组件，则gcr.io这条限制不涉及你，但quay.io的postgres-exporter在主栈中始终存在。

注意区分另一种"选镜像失败"

如果你的流程不是拉镜像失败，而是启动后立即报failed to select primary docker image via llm call（旧版本报告为failed to get primary docker image），那通常是 LLM 后端配置问题，而不是 Docker 或 registry 问题——镜像选型这一步调用的是simple类型的 agent，失败指向该 agent 对应的模型配置，与 registry 是否健康无关（README：Troubleshooting: "failed to select primary docker image via llm call"）。判断边界：如果 Docker 拉取成功、Compose 栈正常启动，只是 flow 创建卡在镜像选择，应去查 LLM 后端的 base URL、API key、模型名与 tool calling 支持，而不是继续调 Docker。

下一步

完成 registry mirror 与可达性验证后，按 README 的正常路径继续即可：运行安装器检查或docker compose up启动主栈。若拉取仍失败，回到本文的三层检查逐层定位——DNS、HTTPS 连通、Docker 拉取测试，并确认quay.io/gcr.io是否在你的网络策略覆盖范围内。

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi