Linux Dragonfly P2P 的镜像分发加速与预热机制

预热命令 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 的 API PUT /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 端点，查不到日志就以为任务丢了——其实它可能正卡在调度队列里。