先留住错误，不要先改一圈设置
本文由 AI 按 Docker 官方文档整理，核对日期为 2026-09-08，未在 Mac、Linux 或群晖设备上亲测。read 为查询；write 包括文件修改、拉取镜像和启动容器；danger 包括停机、替换运行容器以及可能破坏数据的操作。
示例镜像为 docker.io/library/nginx:1.28.0-alpine，项目目录仍为 bloglab，但本文的镜像命令不依赖 Compose 文件。需要可用 Docker CLI、可连接的引擎，以及进行联网探测的授权；curl、nslookup 和 buildx 并不保证在每台 NAS 上预装，缺失时先记录能力，不为一条诊断命令临时安装不明工具。所有域名要么是 Docker 官方入口，要么是明确的 example.com 占位符，不涉及私人服务地址。
先保存最小错误信息：镜像完整引用、时间、错误阶段、当前引擎版本和平台。不要把带 token 的 URL、完整代理配置或认证文件粘到公开求助中。连接 daemon 失败和访问 registry 失败是不同层次；如果 docker version 只有客户端信息，问题还没到镜像仓库。context 可能指向远程 Linux，所以笔记本浏览器能访问 Docker Hub 并不能证明真正执行拉取的引擎网络正常。
docker context show
docker version
docker info --format 'os={{.OSType}} arch={{.Architecture}}'只读取版本、目标和架构字段，避免全量 info 暴露代理等配置。Server 无法连接时先修复引擎连接。
docker pull docker.io/library/nginx:1.28.0-alpine联网下载，可能写入大量镜像层；记录第一次明确报错并分类。历史示例标签不代表最新版本，不要无限循环重试。
DNS 与连接超时要检查哪一层
出现 no such host、lookup 失败或 temporary failure 时，优先区分宿主机解析、代理域名解析和 Docker 引擎自身出网路径。宿主机 DNS 查询成功只是一条局部证据，Desktop 虚拟化网络、VPN、远程 context 或代理服务仍可能处在另一条路径。容器配置里的 dns 主要影响容器的名称解析，不能简单等同于修复引擎拉镜像使用的解析环境。不要把任意公共 DNS 地址写进去当成普遍有效答案。
连接超时可能发生在仓库入口、认证入口或镜像层分发端。只探测 registry 的 /v2/ 成功不代表所有下载域名都畅通；应结合错误里出现的目标域名和失败阶段继续定位。代理部署者需要核对自己的允许列表和路由策略，但共享排错记录时只保留必要主机名，删除签名参数。若同一网络上其他服务也超时，应先缩小故障范围，不能靠重启全部容器来修复上游网络。
nslookup registry-1.docker.io
nslookup auth.docker.io需要系统已有 nslookup。这是只读联网查询，会产生访问流量；看是否返回地址或明确解析错误，不把成功结果当作引擎网络正常的证明。
curl --connect-timeout 10 --max-time 20 -sS -D - -o /dev/null https://registry-1.docker.io/v2/联网请求，不附带凭据、不禁用 TLS 验证；常见 401 与认证挑战说明入口可达且要求认证，不是证明账号登录失败。
证书错误应修复信任链
x509 unknown authority、证书过期和主机名不匹配分别指向不同证书问题。先确认系统时间、访问域名是否正确，再查是否有组织代理对 HTTPS 做受控检查。如果确有受信任的组织 CA，应从正式渠道取得并按 Docker 对宿主机和引擎的说明安装；不要从报错页面或陌生镜像站随意下载根证书。容器内程序访问 HTTPS 所需的信任链又可能不同，镜像拉取成功不能证明容器应用也信任同一证书。
macOS Docker Desktop 与 Linux Engine 的证书和代理配置入口不同，修改后可能需要重启 Desktop 或引擎，安排维护窗口并验证影响范围。不要使用 curl -k、关闭证书验证或增加不安全仓库来掩盖错误，因为这样会移除验证服务身份的关键保护。本资料不提供一键安装根证书脚本，原因是必须先验证证书来源和实际引擎类型，通用脚本无法代替这些事实。
date -u仅显示 UTC 时间，与可信时间源人工比对；不要用修改系统时间作为猜测性修复。
认证失败、路径不存在与限流要分开
unauthorized、denied 或 pull access denied 需要同时核对仓库主机、命名空间、仓库名、标签和权限。私有仓库可能把不存在与无权限表现为类似错误；登录成功也不代表账号有目标仓库权限。先确认自己登录的是正确主机，再按最小需要使用可信凭据存储。Docker Hub 的默认登录流程可能使用设备码；企业环境采用其他认证流程时应遵守其管理方式，而不是把 token 直接放在命令参数或脚本历史中。
429 可能涉及拉取配额或滥用保护，错误正文和响应信息比一个状态码更有用。配额与产品策略可能变动，本资料不写死免费额度数值；减少并发、停止重试风暴、复用已经下载的镜像，再核对当前账号与官方限制说明。登录有时影响拉取配额归属，但不能保证解决所有 429。重命名镜像标签或重启 daemon 都不会凭空增加服务端配额。
不要为了下载速度给陌生镜像站登录 Docker Hub 凭据。镜像引用中的 registry 主机决定了你向哪里请求镜像，认证服务也应核对来源；修改为第三方路径可能改变发布者、内容、标签同步延迟与信任关系。若必须使用组织批准的缓存或镜像仓库，应验证内容摘要及认证边界，不把换源视为无需验证的网络修复。
docker login会联网并改变本机认证状态，按 write 标注。只对可信 Docker Hub 登录页面操作，不把设备码、口令或 token 贴进笔记。
架构不匹配不是网络超时
Apple Silicon 的常见目标是 linux/arm64，许多 x86 Linux 与 NAS 使用 linux/amd64，但应以实际引擎输出为准，不能从品牌推断。no matching manifest 通常意味着该标签没有提供所请求的平台；先查询镜像清单，再选择确实支持本机平台的标签。manifest unknown 则还可能是标签或路径不存在，不应把这两类错误都归到 DNS。
显式 --platform 可以选择某个平台镜像，不能凭空为宿主机增加可靠执行能力。跨架构运行可能依赖模拟器，性能和兼容性都要验证；NAS 尤其不能假定拥有 Desktop 的同等模拟环境。成功 pull 仅证明内容能下载，不证明能启动；启动后的 exec format error 要回到入口程序和架构检查。imagetools 输出中的未知平台也可能是附属证明记录，注意辨认实际运行镜像条目。
docker buildx imagetools inspect docker.io/library/nginx:1.28.0-alpine需要已安装 Buildx；会访问仓库，只查询元数据，不修改服务。看 Platforms 中是否有目标 linux/arm64 或 linux/amd64。缺少插件不代表镜像不存在。
docker pull --platform linux/arm64 docker.io/library/nginx:1.28.0-alpine仅当引擎目标确认为 ARM64 或已验证模拟方案时使用；x86 目标应替换为 linux/amd64。联网写入镜像存储，不会启动服务。
代理要配置给真正出网的进程
终端里设置 HTTP_PROXY 不等于 Docker daemon 也使用该代理。引擎负责拉取镜像，Docker Desktop 应在自身设置中的代理入口配置；官方明确说明 Desktop 忽略 daemon.json 中的代理配置。独立 Linux Engine 则可按实际启动方式配置 daemon 代理，rootless 与系统级服务又有不同管理入口。群晖是厂商包装环境，本文不能仅凭 Docker 官方文档断言其配置文件位置或服务重启命令。
代理地址的 localhost 属于执行请求的环境：宿主机、Desktop 内部环境和远程 NAS 不一定共享同一个回环接口。先确认代理监听地址、访问权限及引擎能到达的端点，再按平台配置。NO_PROXY 范围过大可能让本应走代理的仓库直连失败，过小也可能把内部仓库错误送往外部代理。修改代理或重启引擎都会影响更多服务，因此先核对再安排维护，不提供无条件重启命令。
网络之外还要看本地磁盘和镜像存储。如果下载后解压失败或出现 no space left on device，先用磁盘用量查询确定问题对象，再制定保留和清理策略；日志、构建缓存和卷数据不是同一类内容。不要把 prune --volumes 当作拉取失败的万能修复。最终以一次受控拉取成功、正确平台镜像可用和后续服务独立验证作为闭环，避免把某条探测通过夸大成问题彻底解决。
docker system df查询 Docker 分类用量；可回收值不代表可以无损删除，也不等于宿主机文件系统剩余空间。
把一次拉取失败收敛成一张证据链
假设自己准备为本地静态站点下载镜像，终端返回连接超时。这里的假设只是写作案例，没有对应真实设备故障。先把完整镜像引用、引擎上下文、平台和错误阶段记下来，再确认错误来自连接引擎还是引擎连接仓库。如果引擎查询失败，仓库探测即使成功也无法推进任务；应先恢复正确引擎连接。若引擎查询正常，再观察超时发生在认证、清单获取还是层下载，后续测试始终围绕同一次拉取目标。
第一轮只做有限查询：名称解析是否返回、仓库接口是否回应、系统时间是否合理。仓库接口要求认证时返回未认证响应，反而说明这一次请求已到达接口；它不证明目标仓库权限已满足，也不证明层下载地址可达。若接口响应而拉取仍在下载层阶段失败，下一步查看错误中具体失败主机和代理路径。不能以“浏览器能打开官网”代替这个定位，因为官网、认证接口和内容分发链路承担不同任务。
接着只改变已经有证据指向的一项，例如在个人网络设置中修复确实不可达的代理端点，再用相同引用进行一次受控拉取。把改变前后的错误阶段并排记录：从解析失败变成权限失败，说明前一层可能已推进，但任务还没完成；从超时变成平台不匹配，也不能写成网络修复无效。这样的记录能避免在多个错误之间来回切换时重复修改已经正确的设置，也能让最终结论保持与证据相符。
如果没有明确变化，只保留当前结果并回到失败阶段，不持续高频重试。重复拉取会产生网络请求、镜像存储变化和可能的配额消耗，属于 write；远程清单查询只读取仓库元数据，按 read 标注，但仍会联网并可能留下访问记录。这个区分有助于安排诊断顺序，也避免把所有网络命令都混为一类。
docker image inspect --format 'id={{.Id}} os={{.Os}} arch={{.Architecture}} digests={{json .RepoDigests}}' docker.io/library/nginx:1.28.0-alpineread：只有该引用已存在才有结果；摘要、镜像编号和平台分别记录。
拉取成功后的验收与配置收尾
拉取完成的直接证据是命令正常结束且本地能够查到所需镜像，而不是某一层显示完成。随后核对操作系统与架构、记录仓库摘要，并确认目标服务配置引用同一内容。清单摘要可能描述多平台索引，本地镜像编号描述选中内容，二者不能要求字面相等。要固定部署内容时使用正确仓库引用与摘要，再在目标平台确认能够取得匹配镜像；固定内容并不会自动获得后续修复，所以仍需要有计划的更新流程。
下载验收和运行验收分开记录。下面使用独立静态实例验证该镜像能够启动，端口不与前面练习冲突；它不挂载原站点卷，适合只确认镜像自身入口与默认页面。实际服务还需要自己的配置和数据验收，尤其是跨架构模拟场景，启动成功不能证明性能可接受。如果创建失败，先保留返回错误并确认是否已有同名实例，不能删除用途不明的容器来抢名字。运行日志和单次首页请求通过后，才把“可下载、可启动、默认页面可读取”分别打勾。
如果曾调整个人代理设置，记录最终采用的入口和必要条件，移除已经证实无效的临时改动前先保留原值，以免下次网络切换时失去依据。Linux 系统级引擎、无根引擎和 Mac Desktop 的设置入口不同，DSM 还必须使用厂商支持方式；本篇没有给出或验证厂商配置路径。遇到版本不支持某个选项时，先查帮助并记录限制，不能通过忽略错误让维护脚本继续。
最后停止独立验证容器，把仍未验证的内容写清楚：真实业务挂载、候选升级兼容性、长时间稳定性和离线恢复不属于本轮下载诊断的完成条件。若后续服务失败，就带着已经确认的镜像身份进入对应运行排错，不重新把问题统称为下载慢。个人诊断记录保留必要错误字段即可，不保存认证文件或令牌；这不是额外步骤，而是让记录能被自己长期使用且不会与凭据生命周期绑定。
示意诊断报告：引擎查询通过，最初错误停在仓库连接阶段；名称解析有回应，接口探测得到认证挑战；随后把调查范围缩到引擎代理路径。修正经过确认的个人代理设置后，才重试同一镜像引用，接着核对平台并建立独立默认页面实例。报告将“接口可达”“镜像可用”“默认页面可读”分成三个验收项，避免把一条局部证据放大。它是已填写的诊断路线示例，不是本次设备运行结果。
docker run -d --pull=never --name bloglab-imagecheck -p 127.0.0.1:18083:80 docker.io/library/nginx:1.28.0-alpinewrite：创建运行实例；要求镜像已在本地、名称和端口未占用。
curl --noproxy '*' --fail --show-error --connect-timeout 3 --max-time 10 http://127.0.0.1:18083/read：只验证默认静态页面，未实机执行。
docker stop -t 30 bloglab-imagecheckdanger：中断该测试入口；保留镜像供后续使用。
错误阶段 已有证据 下一步
daemon 连接 只有 Client 核对 context 与引擎
registry 连接 DNS 返回、连接超时 查引擎出网和代理
auth unauthorized 核对引用与账号许可
manifest no matching manifest 查平台清单
层解压 no space left 查引擎存储容量阅读用示意材料；不是命令输出或实测记录，复制保存为记录文件属于 write。