应首先检查Docker守护进程状态与网络连通性，再通过sudo journalctl -u docker.service --since "2026-04-19 00:00:00" -n 100 --no-pager查看系统级日志，重点搜索pull、registry、unauthorized、timeout等关键词定位镜像拉取失败根因。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动WorkBuddy容器化服务但部署失败，常见根源之一是镜像拉取阶段中断，而该环节的异常往往被日志沉默掩盖。Docker守护进程在拉取失败时可能仅返回简短错误码，需深入查看其运行时日志才能定位真实诱因。以下是定位镜像拉取问题的具体路径：
一、检查Docker守护进程状态与基础连通性
Docker服务未运行或处于异常状态时，所有镜像操作均无法执行，此时docker pull命令会直接报“Cannot connect to the Docker daemon”类错误。必须先确认守护进程健康，再验证其对外部镜像仓库的基础网络可达性。
1、执行sudo systemctl status docker，确认服务状态为active (running)且无红色failed标记。
2、若服务未运行，执行sudo systemctl start docker启动服务。
3、运行docker version，核对Client与Server两栏均输出版本信息，且Server端API版本不低于1.44（对应Docker Engine 24.0.0）。
4、测试与镜像源的底层连通性：curl -I https://registry-1.docker.io/v2/，响应应含HTTP/2 401或403，而非timeout或Connection refused。
二、读取Docker守护进程系统级日志
Docker守护进程自身日志记录了镜像拉取全过程的底层行为，包括DNS解析、TLS握手、认证流程及HTTP响应码，比客户端命令输出更详尽。这些日志由systemd托管，需通过journalctl提取原始上下文。
1、执行sudo journalctl -u docker.service --since "2026-04-19 00:00:00" -n 100 --no-pager，限定今日范围并显示最新100行。
2、在输出中搜索关键词pull、registry、unauthorized、timeout或certificate。
3、若发现Get \"https://registry-1.docker.io/v2/...\": dial tcp: lookup registry-1.docker.io on [::1]:53: read udp [::1]:53: i/o timeout，表明宿主机DNS解析失败，需检查/etc/resolv.conf中配置的DNS服务器是否可达。
4、若出现error parsing HTTP 401 response body: invalid character '，说明镜像仓库返回了HTML页面（如Nginx默认页或防火墙拦截页），而非标准JSON响应，<strong><font color="green">表明网络路径中存在中间代理或WAF设备劫持了HTTPS请求</font></strong>。
三、验证镜像地址与加速器配置一致性
Docker客户端配置的镜像加速器若与实际拉取的镜像仓库不匹配，会导致重定向失败或证书校验异常。WorkBuddy官方镜像默认托管于私有registry（如ghcr.io/workbuddy/core），若daemon.json中仅配置了Docker Hub加速器，则对该registry的请求仍走原始慢速链路，极易超时。
1、运行docker info | grep -A 10 "Registry Mirrors"，确认输出中包含针对ghcr.io或registry-1.docker.io的加速地址。
2、检查/etc/docker/daemon.json文件，确保registry-mirrors数组内至少有一项为国内可用的GitHub Container Registry镜像源，例如"https://ghcr.m.daocloud.io"。
3、若文件中存在多个镜像源，必须确保所有源均支持HTTPS且证书有效，任一无效源会导致整个registry-mirrors列表被Docker守护进程忽略。
4、修改daemon.json后，执行sudo systemctl restart docker并等待10秒，再运行docker info确认新配置已加载。
四、分析容器启动日志中的拉取上下文
当使用docker-compose启动WorkBuddy时，即使镜像已存在本地，docker-compose仍会在启动前校验镜像完整性并触发隐式pull。该过程的日志嵌套在容器初始化流中，需结合容器ID与时间戳交叉定位。
1、执行docker-compose up -d后立即运行docker ps -a，找到workbuddy-service容器的ID（如abc123def456）。
2、运行docker logs abc123def456 --tail 50 --timestamps，观察最早几行是否含pulling from、waiting for image或manifest unknown字样。
3、若日志首行即为standard_init_linux.go:228: exec user process caused: exec format error，说明拉取的镜像是arm64架构，而宿主机为amd64，表明docker-compose.yml中未声明platform字段，导致Docker Engine自动选择错误架构镜像。
4、若日志含failed to register layer: re-exec error: exit status 1: output: time=\"...\" level=error msg=\"open /var/lib/docker/overlay2/.../diff/...: permission denied\"，则指向宿主机文件系统挂载选项问题，需检查mount | grep docker输出中overlay2所在分区是否启用user_xattr。
五、复现拉取过程并捕获完整HTTP事务
当上述步骤未能明确归因时，需绕过docker-compose抽象层，以最简方式复现拉取动作，并启用调试模式获取全量网络交互细节，从而暴露证书链断裂、HTTP重定向循环或认证头缺失等深层问题。
1、执行docker pull --platform linux/amd64 ghcr.io/workbuddy/core:v0.9.0，显式指定平台避免多架构混淆。
2、若失败，在同一终端前置环境变量export DOCKER_CLI_DEBUG=1，再执行相同pull命令。
3、在输出中定位以DEBU[开头的行，查找HEAD或GET请求行，确认目标URL是否为预期registry地址。
4、若请求URL被重写为http://而非https://，或Host头为localhost，说明宿主机/etc/hosts中存在对registry域名的错误静态映射，需立即删除对应行。
