DittoFS 配置参数详解

目标：完整梳理 DittoFS v0.34.1 的配置体系——config.yaml 全部配置键、DITTOFS_ 环境变量覆盖、两层配置模型（进程级配置 + 控制面数据库）、SQLite/PostgreSQL 控制面、JWT、TLS 与安全默认值。全部参数基于 dfs init 生成的真实配置与实测回显整理。

DittoFS 的配置系统非常灵活：支持 YAML/TOML 配置文件与 DITTOFS_ 前缀环境变量覆盖，并把「进程级配置」与「控制面数据库」分离开——用户、存储、共享、权限等动态对象存数据库，dfsctl 可在线管理，无需重启服务。

⚠️ 注意：DittoFS 处于 pre-1.0 实验阶段，配置键与磁盘格式可能在不通知的情况下变化；升级前阅读 Release Notes。

一、环境信息

• 测试环境：CentOS 8.4 / Ubuntu 22.04（x86_64），DittoFS v0.34.1
• 配置文件默认位置：$XDG_CONFIG_HOME/dittofs/config.yaml（典型 ~/.config/dittofs/config.yaml）
• 状态目录：$XDG_STATE_HOME/dittofs（典型 ~/.local/state/dittofs，存放日志与 PID 文件）
• 配置查看命令：dfs config show --config <path>
• 配置校验命令：dfs config validate --config <path>
• 支持格式：YAML（.yaml/.yml）与 TOML（.toml）

二、前置条件

1. 已按安装指南完成 DittoFS 安装（dfs/dfsctl 位于 PATH）。
2. 已执行 dfs init 生成配置文件。
3. 以具备配置文件读写权限的账号操作。

三、配置查看与修改方式

3.1 生成默认配置

dfs init
# 或指定路径
dfs init --config /etc/dittofs/config.yaml
# 覆盖已存在的配置
dfs init --force

3.2 查看当前配置

dfs config show
# 指定配置文件 / JSON 输出 / 查看自动推导的块存储默认值
dfs config show --config /etc/dittofs/config.yaml
dfs config show --output json
dfs config show --deduced

💡 说明：dfs config show 中 JWT secret 显示为 '********'（不会明文回显）。

3.3 校验配置

dfs config validate --config /etc/dittofs/config.yaml
# Configuration file: /etc/dittofs/config.yaml
# Validation: OK
#
# Configuration summary:
#   Database type:   sqlite
#   API host:        127.0.0.1
#   API port:        8080
#   API TLS:         false
#   Log level:       INFO

3.4 修改方式

• 直接编辑配置文件后重启服务（systemctl restart dfs）。
• 通过环境变量覆盖（适合 Kubernetes/systemd 等托管场景注入），优先级高于配置文件。
• 动态对象（用户/存储/共享/权限）通过 dfsctl 在线管理，存控制面数据库，无需重启。

四、两层配置模型

配置文件默认位置与格式（dfs init 生成，实测真实内容关键字段）：

# Logging configuration
logging:
  level: "INFO"                    # DEBUG, INFO, WARN, ERROR
  format: "text"                   # text, json
  output: "~/.local/state/dittofs/dittofs.log"   # stdout/stderr/文件路径
  rotation:
    max_size: 100                  # MB
    max_backups: 5
    max_age: 30                    # 天
    compress: false
shutdown_timeout: 30s
database:
  type: sqlite                     # sqlite | postgres
  sqlite:
    path: ""                       # 默认 $XDG_CONFIG_HOME/dittofs/controlplane.db
controlplane:
  host: "127.0.0.1"                # 默认仅回环；多主机部署改 0.0.0.0
  port: 8080
  read_timeout: 10s
  write_timeout: 10s
  idle_timeout: 60s
  # require_initial_password_change: false
  # tls: { cert_file, key_file, client_ca, min_version }
  jwt:
    secret: "<自动生成，生产用 DITTOFS_CONTROLPLANE_SECRET>"
    access_token_duration: 15m
    refresh_token_duration: 168h   # 7 天
# 可选：metadata.badger.block_cache_mb / index_cache_mb
admin:
  username: "admin"
  email: ""
  password_hash: ""                # 留空则首启自动生成密码

五、环境变量覆盖

所有配置键均可通过环境变量覆盖，规则：DITTOFS_ + 大写键路径，嵌套点号转下划线。

示例：

DITTOFS_LOGGING_LEVEL=DEBUG dfs start --foreground
DITTOFS_ADAPTERS_NFS_PORT=2049 dfs start --foreground

💡 配置优先级：环境变量 > 配置文件 > 内置默认值。

六、日志配置（logging）

json 格式示例：

{"time":"2026-10-06T16:38:26Z","level":"INFO","msg":"Starting DittoFS server","component":"server","version":"0.34.1"}

七、控制面数据库（database）

SQLite 配置：

PostgreSQL 配置（database.postgres）：

💡 说明：控制面数据库启动时自动建表并执行迁移；含 schema 变更的版本升级后建议执行 dfs migrate（可重复执行，安全）。

八、控制面 API（controlplane）

8.1 JWT 配置（controlplane.jwt）

⚠️ 安全注意：生产环境不要把 JWT 密钥写进配置文件，用环境变量注入：export DITTOFS_CONTROLPLANE_SECRET=$(openssl rand -hex 32)（64 字符 hex，32 字节熵）。该变量仅在首次启动初始化时写入控制面数据库，后续改动需同时更新配置与数据库。

8.2 TLS 配置（controlplane.tls）

DittoFS 提供原生基于文件的 TLS：只加载证书文件，不做签发/续期/轮换（非 CA，无 ACME）；文件在磁盘更新后自动热加载，无需重启。

controlplane:
  host: 0.0.0.0
  port: 8080
  tls:
    cert_file: /etc/dittofs/tls/tls.crt
    key_file: /etc/dittofs/tls/tls.key
    client_ca: /etc/dittofs/tls/ca.crt   # 可选 → mTLS
    min_version: "1.2"

💡 部署建议：边缘层用 Nginx/Ingress/Service Mesh 终结 TLS，DittoFS 原生 TLS（或 mTLS）作为非 Kubernetes 主机与直连 dfsctl 的安全底线。

8.3 常用 API 端点

九、块存储与 journal（blockstore）

每个共享有恰好一个块存储（内容的持久归宿），前面还有一个落盘的 journal（写前日志）。块存储由 dfsctl store block 创建，类型只有 s3 与 memory；journal 是服务级自动预置的，无需创建，位置由 blockstore.journal.path 决定，每个共享一个子目录 <path>/shares/<共享名>/journal/。

blockstore:
  journal:
    path: /var/lib/dittofs/blocks   # journal 根目录；默认 <状态目录>/blocks
    chunk_size: 0                   # FastCDC 最小分块大小；0 = 内置配置
    chunk_max: 0                    # 覆盖推导的最大分块；0 = 由 chunk_size 推导
    dirty_expire: ...               # 脏块过期时间

写入路径：写入先追加到 journal（本地确认）→ 后台 flush 把脏区间打包成块搬运到块存储 → 已同步的段在空间压力或显式 drain 时回收。journal 不是第二副本：一旦段被回收，字节只存在于块存储。

⚠️ 重要：memory 块存储在服务重启后内容即失；s3 块存储必须指向真实 bucket 才是持久化方案。journal 承载所有「尚未到达块存储」的字节的唯一副本，所在目录必须持久化。

十、协议适配器（adapters）

适配器（NFS/SMB）通过 dfsctl adapter 管理，配置键与端口：

标准端口（生产）对照：

使用标准端口需要：(1) 释放宿主系统占用（systemctl disable --now nfs-server rpcbind smbd nmbd）；(2) 允许绑定低端口（root 运行，或 setcap 'cap_net_bind_service=+ep' /usr/local/bin/dfs，或 systemd 加 AmbientCapabilities=CAP_NET_BIND_SERVICE）。

十一、指标（Prometheus）

DittoFS 没有 OpenTelemetry/分布式追踪子系统。可观测性通过可选的 Prometheus /metrics 端点提供，在独立监听器上启用（observability/metrics 配置块）。默认不启用，端口 9090 默认不监听——需要指标时在配置中启用并重启服务，然后以 curl -s http://127.0.0.1:9090/metrics 验证。

十二、管理员账号（admin）

⚠️ 首次启动密码：DITTOFS_ADMIN_INITIAL_PASSWORD 未设置且后台模式（systemd）下，自动生成的密码不会显示、无法找回。务必首启前设置。

十三、生产配置模板

13.1 单机开发测试（默认 SQLite + 内存块存储）

dfs init --config /etc/dittofs/config.yaml
DITTOFS_ADMIN_INITIAL_PASSWORD=Your-Strong-Pass-123! dfs start --foreground --config /etc/dittofs/config.yaml

13.2 生产单机（SQLite + S3 块存储 + 标准端口）

logging:
  level: "INFO"
  format: "json"
  output: "/var/log/dittofs/dittofs.log"
shutdown_timeout: 30s
database:
  type: sqlite
  sqlite:
    path: /var/lib/dittofs/controlplane.db
controlplane:
  host: 127.0.0.1
  port: 8080
  tls:
    cert_file: /etc/dittofs/tls/tls.crt
    key_file: /etc/dittofs/tls/tls.key
    min_version: "1.3"
  jwt:
    secret: "${DITTOFS_CONTROLPLANE_SECRET}"
    access_token_duration: 15m
    refresh_token_duration: 168h
blockstore:
  journal:
    path: /var/lib/dittofs/blocks
adapters:
  nfs:
    port: 2049
    portmapper:
      enabled: true
      port: 111
  smb:
    port: 445

配合 setcap 'cap_net_bind_service=+ep' /usr/local/bin/dfs，块存储指向真实 S3 bucket：

dfsctl store block add --name s3main --type s3 --bucket my-bucket --region us-east-1 --prefix dittofs
dfsctl share edit /export --block-store s3main

13.3 高可用多节点（PostgreSQL 控制面）

database:
  type: postgres
  postgres:
    host: pg01.example.com
    port: 5432
    database: dfs
    user: dfs
    password: ${POSTGRES_PASSWORD}
    sslmode: verify-full
    ssl_root_cert: /etc/dittofs/tls/pg-ca.crt
controlplane:
  host: 0.0.0.0
  port: 8080
  tls:
    cert_file: /etc/dittofs/tls/tls.crt
    key_file: /etc/dittofs/tls/tls.key

⚠️ 多主机场景 controlplane.host 必须改为 0.0.0.0 并配 TLS，否则管理面只监听回环无法被其他主机访问。

十四、常见问题（FAQ）

Q1：dfs config show 里 JWT secret 是 ********？

正常，出于安全不回显明文。生产用 DITTOFS_CONTROLPLANE_SECRET 环境变量注入。

Q2：环境变量与配置文件哪个优先？

环境变量优先。DITTOFS_ + 大写键路径（点号转下划线）覆盖配置文件对应键。

Q3：改了 config.yaml 不生效？

进程级配置在启动时读取，需重启服务（systemctl restart dfs）。用户/共享/权限等控制面对象用 dfsctl 修改，即时生效。

Q4：启用 2049/445 标准端口失败？

先释放宿主占用（systemctl disable --now nfs-server rpcbind smbd nmbd），再授予绑定低端口能力（setcap 或 systemd AmbientCapabilities），最后确认无残留占用：ss -tulpn | grep -E ':(2049|445|111)\b'。

Q5：9090 端口没在监听？

Prometheus /metrics 默认不启用。需在配置中启用 observability/metrics 并重启服务，详见「十一、指标」。

十五、参考链接

• 官方仓库：https://github.com/marmos91/dittofs
• 官方配置文档：https://dittofs.io/
• 官方文档（GitHub docs）：https://github.com/marmos91/dittofs/tree/main/docs