CNCF Dragonfly P2P文件分发系统入门：部署、配置与Harbor预热

2026年1月14日，云原生计算基金会（CNCF）宣布，开源镜像与文件分发系统 Dragonfly 正式毕业。

Dragonfly 专注于解决基于 Kubernetes 的云原生环境下大规模镜像与文件分发难题。该项目利用点对点（P2P）技术，提供高效、稳定且安全的数据分发与加速能力，旨在成为云原生架构中的标准解决方案，支持文件、容器镜像、OCI制品、AI模型权重、缓存、日志及依赖项的大规模分发。

Dragonfly 最初由阿里巴巴集团于2017年11月开源，并于2018年10月以Sandbox项目身份加入CNCF。2019年11月 Dragonfly 1.0 达到生产就绪状态；2020年1月，其子项目 Nydus 正式开源。2020年4月，项目进入 CNCF 孵化阶段，随后于 2021 年发布 Dragonfly 2.0。

Dragonfly 的官方网站在国内的镜像站： https://dragonfly.website.cncfstack.com

本文主要包含的章节内容：

• Dragonfly架构组成
• Dragonfly部署
• Dragonfly使用限制
• Dragonfly加速与预热
• Dragonfly的配置文件详解

本文涉及的资源：

• 在线的 Dragonfly Web 体验环境

Dragonfly架构组成

Dragonfly 模块为四类：管理器、调度器、种子对等节点和对等节点。

• 管理器（Manager）：维护各 P2P 集群之间的关系，主要提供动态配置管理和数据采集等功能。此外，还配备了一个前端控制台，方便用户以可视化方式操作和管理集群。
• 调度器（Scheduler）：为下载节点选择最佳的下载父节点。在适当的时间，触发 Seed Peer 执行回源下载，或 Peer 执行回源下载。
• 种子节点（Seed Peer）：提供上传和下载功能，可在 P2P 网络中作为根节点，使调度器能够主动发起回源。
• 节点（Peer）：提供上传和下载功能。

Dragonfly部署

Dragonfly 官方提供了推荐的 Kubernetes Helm Chart 部署方案[1]。

分析其 Helm Chart 部署方案，搭建一套 Dragonfly 环境主要是部署 manager、scheduler、client 3个镜像，其中 seed-peer 和 peer 使用的是同一个 client 镜像，只是配置文件存在差异。

本文方案注意事项：

1. 由于目前规模不大，没有 Kubernetes 集群，因此采用基于 docker-compose 的部署方式。
2. Dragonfly 运行依赖 MySQL（或 PostgreSQL），以及 Redis 数据库。本次部署使用外部独立部署的数据库。
3. docker-compose.yml 中的镜像是 v2.3.4 版本，已迁移到国内镜像源，可以正常拉取使用。
4. seed-client 和 client 本质是同一个镜像，如果在同一台机器上运行，需要修改端口以避免冲突。

基于 docker-compose.yml 搭建服务端

挂载的配置文件详情在文章结尾提供参考，使用 docker compose up -d 启动服务。

services:
  manager:
    image: registry.cncfstack.com/docker.io/dragonflyoss/manager:v2.3.4
    container_name: manager
    restart: always
    volumes:
      - /data/logs/dragonfly/manager:/var/log/dragonfly
      - ./config/manager.yaml:/etc/dragonfly/manager.yaml:ro
    healthcheck:
      test: [ "CMD-SHELL", "/bin/grpc_health_probe -addr=:65003 || exit 1" ]
      interval: 1s
      timeout: 2s
      retries: 30
    ports:
      - 65003:65003
      - 8080:8080

  scheduler:
    image: registry.cncfstack.com/docker.io/dragonflyoss/scheduler:v2.3.4
    depends_on:
      - manager
    container_name: scheduler
    restart: always
    healthcheck:
      test: [ "CMD-SHELL", "/bin/grpc_health_probe -addr=:8002 || exit 1" ]
      interval: 1s
      timeout: 2s
      retries: 30
    volumes:
      - /data/logs/dragonfly/scheduler:/var/log/dragonfly
      - ./config/scheduler.yaml:/etc/dragonfly/scheduler.yaml:ro
    ports:
      - 8002:8002

  seed-client:
    image: registry.cncfstack.com/docker.io/dragonflyoss/client:v1.1.7
    network_mode: “host“
    depends_on:
      - manager
      - scheduler
    container_name: seed-client
    restart: always
    healthcheck:
      test: [ "CMD-SHELL", "/bin/grpc_health_probe -addr=unix:///var/run/dragonfly/dfdaemon.sock || exit 1" ]
      interval: 1s
      timeout: 2s
      retries: 30
    volumes:
      - /data/logs/dragonfly/seed-client:/var/log/dragonfly
      - ./config/seed-client.yaml:/etc/dragonfly/dfdaemon.yaml:ro
    ports:
      - 4010:4010
      - 4011:4011
      - 4012:4012

服务端搭建完成后，可以通过 manager 服务的 8080 端口访问其 Web 管理界面。

客户端搭建

客户端需要在所有需要加速的节点上部署，在 Kubernetes 上通常以 DaemonSet 形式运行。在本地环境可以基于 Docker 运行。

docker run -itd --name dfd \
    -v ./log/client:/var/log/dragonfly \
    -v ./p2p-client.conf:/etc/dragonfly/dfdaemon.yaml:ro  \
    -p 4100:4000 \
    -p 4101:4001 \
    -p 4202:4002 \
    registry.cncfstack.com/docker.io/dragonflyoss/client:v1.1.7

客户端使用

• Docker作为客户端拉取镜像
  参考下文的“不支持 docker 工具加速”章节。

• Containerd 运行时
  在 containerd 运行时的节点上，修改或添加一个配置：/etc/containerd/certs.d/docker.io/hosts.toml，其中 http://127.0.0.1:4001 就是本地运行的 peer 的代理端口。
  详细的配置如下说明[2]

  server = “https://registry.cncfstack.com“
  
  [host.“http://127.0.0.1:4001“]
  capabilities = [ “pull“, “resolve“ ]
  
  [host.“http://127.0.0.1:4001“.header]
  X-Dragonfly-Registry = “https://registry.cncfstack.com“

Dragonfly使用限制

经过体验和查阅官方文档，在使用 Dragonfly 加速镜像拉取时，会存在如下限制：

不支持 docker 工具加速

对 docker pull 拉取镜像并不友好，官方也明确说明不完全支持 Docker。

这主要是由于 Docker 的 HTTP_PROXY 配置机制问题。虽然添加代理后可以加速镜像拉取，但 Docker 的所有 HTTP/HTTPS 请求都会经过该代理，可能影响其他功能。加速操作完成后，需要移除代理并重启 Docker 服务，使用流程较为繁琐。相比之下，对于 containerd、podman 等工具，可以更精细地配置，不存在此问题。

如果必须为 Docker 提供镜像加速，需要修改 Docker 的 systemd 配置，添加代理环境变量并重启 Docker 服务。注意，在 Shell 终端使用 export 设置的环境变量对 Docker 服务端不生效。

给 dockerd 服务端添加配置示例：

root@iv-ydsh9xsohswuxjsht8f2:~# cat /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://1.2.3.4:4011/"
Environment="HTTPS_PROXY=http://1.2.3.4:4011/"
Environment="NO_PROXY=localhost,127.0.0.1,10.0.0.0/8"

将配置文件中的 1.2.3.4 修改为实际的 peer 节点地址即可。

不支持开放网络

Peer 节点需要在同一个可路由的网络中，否则可能导致其他 peer 节点无法访问该节点。

在一个 Kubernetes 集群内，节点通常位于同一个网络平面，不存在此问题。但如果是在开放的网络环境中，例如部分节点在公有云，部分节点在公司内网或个人电脑，当某个节点配置为 peer 后，该节点自身可以正常拉取镜像，但其他节点可能无法从该节点拉取数据。如果调度器恰好将下载任务调度到这个不可达的节点，就会导致下载失败。

Dragonfly加速与预热

默认情况下，第一次拉取镜像时，peer 节点会从种子节点（Seed Peer）获取数据，而种子节点则需要回源站（例如 Docker Hub）拉取镜像。整个过程涉及两次镜像传输。

为了提升初次下载的体验，或者提前分发文件，可以通过主动预热或与 Harbor 集成实现自动预热。

主动预热

主动预热是在 Dragonfly 管理界面中配置，添加需要预热的镜像或文件任务后，Dragonfly 的种子节点会自动从源站拉取文件并缓存到本地。

这种方式需要人工操作或调用 API 接口来创建任务，对于自动化流程来说可能不够便捷。

Harbor镜像预热

Harbor 镜像预热是在 Harbor 仓库中配置，当项目中有新的镜像推送时，Harbor 会自动触发预热任务，将镜像推送到指定的 Dragonfly 集群中。

这种方式实现了自动化，配置完成后，新推送的镜像会自动执行预热。详细配置步骤[3]。

Dragonfly的配置文件详解

需要特别注意，配置文件中出现的 __IP__ 占位符需要替换为机器网卡的实际 IP 地址。可以通过以下命令获取 IP：

ip=${IP:-$(ip a s eth0 |grep "inet\ "|awk -F'/' '{print $1}'|awk '{print $NF}')}
export ip=${ip}

manager.template.yaml

manager 服务的运行配置。注意配置中的 __IP__ 需要替换为机器的网卡 IP 地址。
详细的配置参数参考[4]

manager 配置涉及 MySQL (或 PostgreSQL) 和 Redis，请根据实际情况修改。

#################
# 日志配置
# console是否在控制台输出日志，可使用 logs 命令查看日志
# 日志级别：trace/debug/info/warn/error
console: true
log:
  level: info

server:
  grpc:
    # advertiseIP manager 访问的IP地址，用于 scheduler和seed的访问。
    # 如果本地eth0的 IP 地址和访问的 IP 地址不一致，请设置本字段为访问的 IP 地址
    advertiseIP: __IP__
    # 设置监听的起始和结束端口，如果前面的端口被占用则会自动使用后续的端口，相同时则为固定端口
    port:
      start: 65003
      end: 65003
    # Restful API接口监听的端口，业务Web页面的服务端口
  rest:
    addr: :8080

#安全建议：生产环境务必修改默认的 JWT key！
auth:
  jwt:
    realm: ‘Dragonfly‘ # 认证域名称
    key: ‘ZHJhZxxxuZmx5Cg==‘ # JWT签名密钥（base64编码）
    timeout: 48h # Token有效期
    maxRefresh: 48h # Token可刷新时间

# 可以配置为mysql，参考配置文件中格式
database:
  type: postgres
  postgres:
    user: pg-user
    password: pg-pwd
    host: pg-ip-or-doman
    port: 5432
    dbname: df_manager
    sslMode: disable
    timezone: UTC
  migrate: true

redis:
  addrs:
    - “redis-ip-or-domain:6379“
  masterName: ‘’
  username: ‘’
  password: redis-pwd
  db: 3
  brokerDB: 1
  backendDB: 2

# Job配置
job:
  rateLimit:
    fillInterval: 1m # 令牌桶填充间隔
    capacity: 5      # 令牌桶容量
    quantum: 5       # 每次填充的令牌数
  gc:
    # Interval is the interval for garbage collection.
    interval: 1m
    # TTL is the time to live for the job.
    ttl: 1m

  syncPeers:
    # 设置同步所有 peers 信息的间隔时间，从 scheduler 同步到 manager
    # 注意：代码限制必须 > 12h，否则无法启动
    interval: 13h
    # 从 scheduler 同步到 manager时的同步超时时间
    timeout: 10m

  preheat:
    # 请求 registry 获取 token 和 manifest 的超时时间
    registryTimeout: 1m
    tls:
      insecureSkipVerify: false # 是否跳过TLS验证

scheduler.template.yaml

scheduler 服务的运行配置。注意配置中的 __IP__ 需要替换为机器的网卡 IP 地址。
详细配置参考[5]

scheduler 配置文件涉及 Redis 配置，请根据实际情况修改。

server:
  advertiseIP: __IP__
  port: 8002

# Scheduler policy configuration.
scheduler:
  # 调度算法：
  # default：基于规则的调度算法（默认）
  # ml：机器学习调度算法（需要额外配置）
  # plugin：插件扩展算法（需要编译 d7y-scheduler-plugin-evaluator.so）
  algorithm: default

  # 回源设置：
  # 单个任务允许Peer回源的最大次数
  backToSourceCount: 200
  # Peer回源重试限制
  retryBackToSourceLimit: 3
  # 调度重试次数限制
  retryLimit: 5
  # 调度重试间隔
  retryInterval: 400ms

  # GC 参数调优建议：
  # 高负载环境：减少 peerGCInterval 和 taskGCInterval
  # 内存敏感环境：减少 peerTTL 和 hostTTL
  # 网络不稳定环境：增加 pieceDownloadTimeout
  gc:
    pieceDownloadTimeout: 30m # Piece下载超时时间
    peerGCInterval: 5m        # Peer垃圾回收间隔
    peerTTL: 24h              # Peer存活时间，如果 peer 被其他 peers 下载了，改值会重新刷新
    taskGCInterval: 30m       # 任务垃圾回收间隔
    hostGCInterval: 5m        # Host垃圾回收间隔
    hostTTL: 1h               # Host存活时间。如果 host 上报了状态，该值会重新刷新

database:
  redis:
    addrs:
      - “redis-ip-or-domain:6379“
    masterName: ‘’
    username: ‘’
    password: ‘’
    brokerDB: 1
    backendDB: 2

# 动态配置
# 支持从 Manager 动态拉取配置更新
# 无需重启 Scheduler 即可更新部分配置
# 用于集群策略的动态调整
dynConfig:
  # 动态配置刷新时间
  refreshInterval: 1m

# 调度器host信息
# 数据中心标识（如：us-east-1）
# 地理位置（如：NewYork）
# 设置 idc 和 location 可实现智能调度
# 优先调度同 IDC/同地域的 Peer
# 减少跨地域网络流量和延迟
host:
  idc: ‘’
  location: ‘’

# Manager服务的配置信息
manager:
  addr: “__IP__:65003“
  # 所属集群ID
  schedulerClusterID: 1
  keepAlive:
    interval: 5s

seedPeer:
  # Scheduler enable seed peer as P2P peer,
  # if the value is false, P2P network will not be back-to-source through
  # seed peer but by peer and preheat feature does not work.
  enable: true

# CPU核心数 < 16:   globalWorkerNum = 200-500
# CPU核心数 16-32:  globalWorkerNum = 500-1000
# CPU核心数 > 32:   globalWorkerNum = 1000-2000
job:
  enable: true          # 启用异步作业服务
  globalWorkerNum: 500  # 全局队列工作线程数
  schedulerWorkerNum: 500 # 调度器队列工作线程数
  localWorkerNum: 1000  # 本地队列工作线程数%

seed-client.template.yaml

种子节点（Seed Peer）的配置。需要将配置中的 __IP__ 替换为本节点的 IP 地址。
详细完整的配置参考[6]

#################
# 日志配置
# console是否在控制台输出日志，可使用 logs 命令查看日志
# 日志级别：trace/debug/info/warn/error
console: true
log:
  level: info

#################
# 当前运机器的基础信息配置， 设置 idc 和 location 可实现同地域优先调度
# host.idc 该机器所属的数据中心，如us-east-1
# host.location 该机器所属的地理位置（如：Beijing）
# host.hostname 主机名（可选）
# host.ip IP（NAT/多IP场景使用）， 注意：peer 节点需要基于该IP地址给其他peer提供下载功能，所以如果内网和外网IP，需要配置为外网IP
# host.schedulerClusterID 所属调度器集群ID。需要基于 scheduler 中的 ID 配置，该配置添加后，idc/location 会被忽略
host:
  ip: __IP__

#################
# 插件和缓存配置
# server.cacheDir 缓存文件存储的目录
# server.pluginDir 保存插件的目录
server:
  pluginDir: /var/lib/dragonfly/plugins/dfdaemon/
  cacheDir: /var/cache/dragonfly/dfdaemon/

#################
# 下载配置
# download.protocol 中 peers下载资源时支持的协议，如 tcp 或 quic：
# TCP：适用于高带宽、低延迟、局域网环境
# QUIC：适用于高延迟、高丢包率、移动网络环境
# socketPath：dfdaemon GRPC service的 socket 路径
# requestRateLimit：下载请求速率限制（请求/秒）default is 4000 req/s
# rateLimit： # 下载速率限制（默认50GiB/秒）
# pieceTimeout：从源站下载piece的超时时间
# collectedPieceTimeout：从父节点收集piece的超时时间
# concurrentPieceCount：并发下载的piece数量
download:
  protocol: tcp
  server:
    socketPath: /var/run/dragonfly/dfdaemon.sock
    requestRateLimit: 4000
    rateLimit: 1GiB
    pieceTimeout: 360s
    collectedPieceTimeout: 360s
    concurrentPieceCount: 10

#################
# 上传配置
# upload.server.port 上传的 dfdeamon grpc 服务端口
# upload.disableShared 是否禁止上传数据给其他节点
# rateLimit 上传速度配置，默认10GiB 每秒，支持单位 KiB/MiB/GiB
upload:
  server:
    port: 4010
    disableShared: false
    rateLimit: 10GiB

#################
# 访问 manager 的配置信息
manager:
  addr: http://__IP__:65003

#################
# 种子节点配置
# seedPeer.enable 是否启用种子节点功能
# seedPeer.type 节点类型，可选值：super/sub
# seedPeer.clusterID 节点所属的种子节点集群ID
# seedPeer.keepaliveInterval 节点向manager上报存活时间间隔
seedPeer:
  enable: true
  type: super
  clusterID: 1
  keepaliveInterval: 15s

#################
# 存储配置
# tcpPort tcp服务端口
# quicPort quic服务端口
# dir：存储tasks元数据和内容的目录
# keep： dfdaemon重启时是否保留任务数据
# writeBufferSize：数据写入磁盘缓冲区大小，默认128KB
# readBufferSize：读取缓冲区大小，默认128KB
storage:
  server:
    tcpPort: 4005
    quicPort: 4006
    dir: /var/lib/dragonfly/
    keep: true
    writeBufferSize: 131072
    readBufferSize: 131072

#################
# 资源GC回收配置
# gc.interval gc任务执行间隔
# gc.policy.taskTTL 任务TTL
# gc.policy.distThreshold 设置磁盘使用率阈值。 如果设置为0或者不设置，则会使用全部磁盘空间。可设置 distThreshold 限制dfdaemon使用的最大磁盘空间
# distHighThresholdPercent 磁盘使用率 > 该值：触发GC，删除旧任务
# distLowThresholdPercent 磁盘使用率 < 该值：停止GC
gc:
  interval: 900s
  policy:
    taskTTL: 21600s
    # distThreshold: 10TiB
    distHighThresholdPercent: 80
    distLowThresholdPercent: 60

#################
# 镜像代理配置
# proxy.server.port 镜像代理服务端口
# proxy.ip 镜像代理服务IP
# ... （其他proxy相关注释）
proxy:
  server:
    port: 4011
  rules:
    - regex: ‘blobs/sha256.*‘
  registryMirror:
    addr: https://registry.cncfstack.com
  disableBackToSource: false
  prefetch: false
  readBufferSize: 32768

#################
# Prometheus metrics
metrics:
  server:
    port: 4012

p2p-client.conf

客户端（Peer）运行的配置文件，与 seed-client.template.yaml 配置基本一致，但不需要配置 seedPeer 部分。

其他默认配置可以按需调整，完整的配置参考[7]。

host:
  ip: <上报的当前机器IP，用于其他peer节点连接>
manager:
  addr: http://<manager服务的访问地址>:65003
proxy:
  server:
    port: 4001
  rules:
    - regex: ‘blobs/sha256.*‘
  registryMirror:
    addr: https://registry.cncfstack.com
  disableBackToSource: false
  prefetch: false
  readBufferSize: 32768

引用链接
[1] Kubernetes Helm Chart 部署方案: https://dragonfly.website.cncfstack.com/docs/next/getting-started/quick-start/kubernetes/
[2] 详细的配置如下说明: https://dragonfly.website.cncfstack.com/docs/next/operations/integrations/container-runtime/containerd/
[3] 详细配置步骤: https://dragonfly.website.cncfstack.com/docs/next/advanced-guides/open-api/preheat/#harbor
[4] 详细的配置参数参考: https://dragonfly.website.cncfstack.com/docs/next/reference/configuration/manager/
[5] 详细配置参考: https://dragonfly.website.cncfstack.com/docs/next/reference/configuration/scheduler/
[6] 详细完整的配置参考: https://dragonfly.website.cncfstack.com/docs/next/reference/configuration/client/dfdaemon/
[7] 完整的配置参考: https://dragonfly.website.cncfstack.com/docs/next/reference/configuration/client/dfdaemon/