预热命令 preheat 返回 FAILED 主因是调度器找不到可用 seed-peer 或源站不可达；seed-peer 需配置 dfget 回源能力并正确注册，URL 必须为带 digest 的 HTTPS 地址且可直连。
预热命令 preheat 为什么总返回 FAILED？
预热失败不是因为镜像 URL 写错了，而是调度器找不到可用的 seed-peer 或者源站不可达。Dragonfly 的 preheat 实际上是向 scheduler 提交一个任务，再由 scheduler 指派给某个 seed-peer 回源下载；如果所有 seed-peer 都未就绪（比如没启动、没注册、健康检查失败），任务就会卡在 WAITING 后超时变 FAILED。
-
seed-peer必须配置dfget回源能力，并在启动时通过--scheduler显式指向调度器地址 - 检查
scheduler日志里是否有类似no available seed peer for preheat task的报错 - 确保预热 URL 是完整可访问的 HTTPS 地址，且
seed-peer能直连该 registry（比如 Harbor、Docker Hub），不能依赖 client 端的代理或私有 DNS - 预热 image 类型时，URL 必须带 digest（如
https://harbor.example.com/v2/library/nginx/manifests/sha256:abc...），tag 不行——OCI 规范要求预热以不可变层为单位
dfget 下载镜像时卡在 waiting for parent
这是 P2P 协议里典型的“父节点发现失败”现象。Dragonfly 不是直接从 registry 拉，而是先找 peer 要分片，找不到才回源。但若本地 peer 列表为空、scheduler 未响应、或网络策略阻断了 peer 间 gRPC 连接（默认端口 8002），dfget 就会一直等不到 parent。
- 确认
client配置中scheduler.addr正确，且能telnet <scheduler-ip> 8002</scheduler-ip> -
peer启动后需几秒注册到scheduler，刚启动就拉镜像容易失败，加--retry=3更稳妥 - 若用 Docker，务必挂载
/etc/dragonfly/dfget.yml并设置dfdaemon作为 proxy（否则docker pull流量不走 Dragonfly） - 注意 v2.3+ 默认启用
piece download timeout（scheduler/config/constants.go中DefaultPieceDownloadTimeout），超时后不会 fallback 到 registry，而是报错——需手动配--fallback-to-registry=true
镜像分层预热后，docker pull 仍慢？
预热只把 blob 层存进 seed-peer 的本地存储（通常是 /var/lib/dragonfly/peer/tasks），但 docker pull 默认仍走 registry HTTP API 获取 manifest 和 config，这些元数据没被预热。所以首次拉取仍要花时间解析和校验，只是 layer 下载快了。
- 要真正提速，得配合
dfdaemon+proxy模式：让dockerd的 registry 请求全部经由dfdaemon代理，它会拦截 manifest 请求并重写 layer URL 为 Dragonfly 内部地址 - 预热时必须指定
type=image，且 URL 是 manifest digest；若误用type=file，只会下载原始 JSON，无法被容器运行时识别 - Harbor v2.13+ 支持
dragonfly-preheat插件，可自动触发镜像 push 后的预热，避免手动维护预热列表 - 注意 OCI image 的
config层虽小，但必须存在且校验通过，否则containerd会拒绝组装镜像——预热失败常因 config 层缺失而非 layer 层
scheduler 配置里 DefaultPeerConcurrentUploadLimit 设太高会怎样？
这个参数控制每个 peer 最大并发上传数，默认是 3。设成 10 看似能加速分发，实则容易触发内核 ephemeral port exhaustion 或打满 peer 机器的出向带宽，导致其他服务丢包、HTTP 超时、甚至 scheduler 自身 gRPC 连接中断。
- 生产环境建议按 peer 机器网卡带宽估算：千兆网卡上限 ≈
5~7，万兆可到15~20，但必须同步调高net.ipv4.ip_local_port_range - 该值不影响下载速度，只影响 peer 能同时给多少个下游传数据；上传瓶颈通常不在 scheduler，而在 peer 的磁盘 I/O 或网络出口
- 动态调整无需重启：通过
manager的 APIPUT /api/v1/schedulers/config修改，scheduler会在 30 秒内生效 - 若发现大量 peer 上报
upload failed: context deadline exceeded，大概率就是这个值设高了，伴随netstat -s | grep "failed to allocate"显著上升
最常被忽略的一点：预热任务状态只能通过 manager API 查，scheduler 和 seed-peer 都不暴露预热详情；而 manager 默认不开启 metrics 端点，查不到日志就以为任务丢了——其实它可能正卡在调度队列里。
