配置参考

本页描述当前 main 分支的配置布局,内容依据 crates/common/curvine-config/src/*.rs 中的实际配置结构体与示例文件 etc/curvine-cluster.toml 整理。

运行时真正的配置来源是 conf/curvine-cluster.toml。本页是配置段落与关键字段的索引;完整字段列表请直接查看 crates/common/curvine-config/src/ 下对应的结构体。

配置来源

Curvine 常见的配置输入包括:

  • conf/curvine-cluster.toml:主配置文件
  • conf/curvine-env.sh:bin/ 脚本使用的环境初始化
  • conf/curvine-site.xml:Hadoop / Java 客户端配置

关键环境变量覆盖项:

变量作用
CURVINE_CONF_FILE覆盖 curvine-cluster.toml 路径
CURVINE_MASTER_HOSTNAME覆盖 Master 实际 hostname
CURVINE_MDS_HOSTNAME覆盖 MDS 实际 hostname
CURVINE_WORKER_HOSTNAME覆盖 Worker 实际 hostname
CURVINE_CLIENT_HOSTNAME覆盖客户端 hostname,用于本地性判断
CURVINE_TRANSFER_HOSTNAME覆盖 Transfer 服务 hostname

配置加载流程

文件(TOML)-> 环境变量白名单 -> 反序列化 -> 空白字符规范化
            -> 校验 -> discovery.init -> 推导 client.master_addrs
  • 未知配置键会由 validation::warn_unknown_keys 输出警告,但不会导致启动失败。拼错的键会静默保留默认值,因此请始终检查启动日志中的警告。
  • client.master_addrs 可以省略。为空时,Curvine 使用 master.rpc_port 从 journal.journal_addrs 推导;如果 journal_addrs 也为空,则使用 master.hostname:master.rpc_port。
  • 独立 Transfer 服务使用简化加载流程(ClusterConf::from_transfer),只校验 client 与 transfer 段落。

net_interface

当 net_interface 非空(例如 "eth0")时,Curvine 会解析该网卡的第一个 IPv4 地址,并将其应用到 master、mds、journal、worker、client 和 transfer 的 hostname。设置该字段后,CURVINE_*_HOSTNAME 环境变量会被忽略。

net_interface 只填充本节点自身的 hostname。集群成员列表(journal.journal_addrs 与 client.master_addrs)仍必须显式填写,且每个节点的条目必须使用其网卡实际解析出的 IPv4。否则节点无法在 Raft 组中定位自己,启动时会给出明确错误。

当前配置布局

当前 ClusterConf 的主要段落如下:

段落作用
顶层字段format_master、format_worker、testing、cluster_id、net_interface
[master]Master RPC / Web、元数据、TTL、配额、复制、锁
[mds]可选的独立元数据服务(FoundationDB 或内存 KV)
[journal]Raft / journal 配置
[worker]Worker RPC、数据目录、复制与数据路径执行参数
[client]客户端默认值、重试、读写缓冲区、统一文件系统行为
[fuse]FUSE 挂载与缓存参数
[log]client / fuse 共用日志
[job]旧版 Master 侧 load 任务生命周期与并发控制
[transfer]独立 Load / Export 服务、状态存储和客户端路由
[cli]CLI 日志配置
[discovery]基于 etcd 的服务发现(默认关闭)
[fault_injection]仅测试使用的故障 HTTP 控制面
[web]、[web.observability]独立 curvine-web 管理控制台及其可观测性组件
[s3_gateway]独立 curvine-s3-gateway 服务
[master.compatibility]、[worker.compatibility]版本兼容策略

顶层字段

字段默认值含义
format_mastertrue启动时格式化 Master 元数据存储
format_workertrue启动时格式化 Worker 数据存储
testingfalse仅测试模式;数据不会正常流动
cluster_idcurvine集群标识,用于存储路径与服务命名
net_interface空用于解析本节点 IPv4 的网卡名

format_master 会删除 RocksDB 元数据,format_worker 会删除 Worker 数据目录。已有生产集群必须将两者设为 false;仓库自带的 etc/curvine-cluster.toml 已经如此配置。

[master]

字段默认值含义
hostnamelocalhostMaster hostname;可被 net_interface 或 CURVINE_MASTER_HOSTNAME 覆盖
rpc_port8995Master RPC 端口
web_port9010Master 指标监听端口(仅 /metrics,无 UI)。管理控制台是独立的 curvine-web 进程,监听 [web].port
io_threads32Master RPC I/O 线程数
worker_threadsmax(32, 2 × CPU)Master RPC worker 线程数
actor_threads4Actor 运行时线程数
io_timeout10m网络读写超时
io_close_idletrue关闭空闲的 Master RPC 连接
meta_request_concurrenttrue在单个连接上并发处理元数据请求
meta_dir<cwd>/fs-metaRocksDB 元数据目录
min_block_size1MB最小 block 大小
max_block_size100GB最大 block 大小
min_replication1最小副本数
max_replication100最大副本数
max_path_len8000最大路径长度
max_path_depth1000最大路径深度
retry_cache_enabletrue启用文件系统请求重试缓存
retry_cache_size100000重试缓存容量
retry_cache_ttl10m重试缓存 TTL
block_report_limit100000单次 block report 的最大 block 数
worker_policylocalWorker 选择策略:local、robin、random、load_based、weighted
executor_threads10Master 执行器线程数
executor_channel_size1000Master 执行器队列大小
heartbeat_interval3sWorker 心跳间隔
worker_check_interval10sWorker 状态检查间隔
worker_blacklist_interval30s不健康 Worker 被拉黑前的等待时间
worker_lost_interval10mWorker 判定丢失时间
audit_logging_enabledtrue启用审计日志
block_replication_enabledfalse启用 block 复制管理
block_replication_concurrency_limit1000复制任务并发上限
block_replication_retry_interval5s复制重试间隔
block_replication_submit_timeout30s源 Worker 接受复制任务的截止时间
block_replication_job_timeout30m已提交复制任务上报结果的截止时间
ttl_checker_retry_attempts3TTL 检查重试次数
ttl_checker_interval1hTTL 扫描周期
ttl_bucket_interval1hTTL 分桶周期
ttl_max_retry_duration10mTTL 最大重试时长
ttl_retry_interval1sTTL 重试间隔
enable_quota_evictionfalse启用 quota 驱动逐出
quota_eviction_modefree逐出模式
quota_eviction_policylru逐出策略
quota_eviction_high_rate0.8高水位
quota_eviction_low_rate0.6低水位
quota_eviction_scan_page2扫描页数
quota_eviction_dry_runfalse只报告可逐出对象,不实际删除
quota_eviction_capacity5000000逐出扫描容量(条目数)
quota_eviction_max_scan10000每次触发最多检查的逐出候选数;0 表示扫描全部候选
lock_expire_time5m过期文件锁回收时间
client_session_lock_leasetrue会话持有的锁只由持有者或会话回收器释放,不按 lock_expire_time 过期;设为 false 时恢复该 TTL
client_session_timeout60s客户端会话超过该时长没有心跳即视为过期;应为客户端心跳间隔(默认 12s)的数倍
buffer_size128KB内部缓冲区大小
conn_limit8单连接在途请求上限,必须 > 0
global_limit4096全局在途请求上限,必须 > 0
trash_enabledfalse删除的条目移入回收站 /.Trash,而不是直接删除
trash_retention7d条目在 /.Trash 中保留多久后被清理;0 表示保留到手动清理
trash_check_interval1h扫描 /.Trash 中过期条目的间隔
trash_purge_interval1s清理异步删除暂存条目(/.Trash/.pending)的间隔;即使 trash_enabled 为 false 也会运行
trash_purge_batch_inodes4096单个清理批次在释放命名空间锁之前最多删除的 inode 数
trash_purge_yield_ms5清理批次之间的停顿(毫秒),让其他元数据操作获得锁
delete_stage_min_children4096直接子项数不少于该值的目录在永久递归删除时先暂存到 /.Trash/.purging,再分批清理;0 表示不暂存
s3_allow_env_credentialsfalse允许 S3 挂载使用 s3.credentials.type = role 或 auto,即使用节点自身的云身份。挂载 RPC 没有认证,只应在 Master RPC 仅对管理员开放时启用
read_cache_reservation_enabledfalseWorker 确认最新容量报告后,释放已完成缓存文件的空间预留;仅用于专用读缓存集群,写缓存或混合用途请保持关闭

worker_policy = "local" 会为第一个副本优先选择本地 Worker,其余副本通过 weighted 策略分配;weighted 按 worker.weight 分配。

[master.rocksdb] 控制元数据 RocksDB 行为,默认值来自 MasterConf::rocksdb_default()(4 KB block、关闭 WAL、启用 bloom filter、缓存并 pin index/filter block)。

[master.compatibility] 见下文“版本兼容策略”。

[mds]

MDS 是可选的独立元数据服务,通过 curvine-server --service mds 启动,默认关闭。

字段默认值含义
enabledfalse启用 MDS 服务
hostnamelocalhostMDS hostname
rpc_port8998MDS RPC 端口
web_port9004MDS Web / 健康检查端口
io_threads4MDS RPC I/O 线程数
worker_threads8MDS RPC worker 线程数
kv_backendfdbKV 后端:fdb 或 memory
fdb_cluster_file/etc/foundationdb/fdb.clusterFoundationDB cluster file;kv_backend = "fdb" 时必填
fdb_txn_timeout_ms5000FoundationDB 单事务超时
logmds.logMDS 日志配置

kv_backend = "memory" 仅用于测试,进程退出后会丢失全部元数据。fdb_txn_timeout_ms 决定操作在 FoundationDB 不可达时等待多久后快速失败;除非有明确原因,否则保持默认值。

[journal]

字段默认值含义
enabletrue启用 Raft journal
group_nameraft-groupRaft 组名
hostnamelocalhost本地 Raft hostname
rpc_port8996Raft RPC 端口
io_threads8Raft RPC I/O 线程数
worker_threads8Raft RPC worker 线程数
message_size200Raft RPC message size
journal_addrs[{id=1, hostname="localhost", port=8996}]Raft 节点列表
journal_dirtesting/journal-<random>Journal / Raft 日志目录
writer_channel_size0Journal writer 队列大小;0 表示无界
writer_flush_batch_size1000Journal flush batch 大小
writer_flush_batch_ms10Journal flush 周期
snapshot_interval6hFollower 触发 snapshot 的周期
snapshot_min_interval10m两次 snapshot 的最小间隔;0 关闭限制
leader_create_snapshot未设置Leader 是否创建 snapshot;未设置表示仅单节点组创建
snapshot_entries1000000两次 snapshot 之间的 entry 数
snapshot_read_chunk_size1MBSnapshot 读取 chunk 大小
snapshot_download_parallel8本节点下载快照时同时传输的快照文件数(每个文件一个连接);1 表示串行
conn_retry_max_duration_ms0连接重试最大时长
conn_retry_min_sleep_ms10000连接重试最小休眠
conn_retry_max_sleep_ms10000连接重试最大休眠
rpc_close_idlefalse关闭空闲 Raft RPC 连接
rpc_retry_max_duration_ms60000RPC 重试最大时长
rpc_retry_min_sleep_ms20000RPC 重试最小休眠
rpc_retry_max_sleep_ms20000RPC 重试最大休眠
conn_timeout_ms30000连接超时
io_timeout_ms60000RPC 读写超时
conn_size1每个 peer 的共享连接数
raft_tick_interval_ms1000Raft tick 周期
raft_election_tick10选举超时(tick 数)
raft_heartbeat_tick3心跳间隔(tick 数)
raft_min_election_ticks10Raft 随机选举下界
raft_max_election_ticks30Raft 随机选举上界
raft_check_quorumtrue启用 quorum 检查
raft_max_size_per_msg1MB单条消息最大大小
raft_max_inflight_msgs256最大在途消息数
raft_max_committed_size_per_ready16MB单次 ready 的最大已提交大小
raft_batch_size8Batch append 大小
raft_retry_cache_size100000Raft 重试缓存容量
raft_retry_cache_ttl10mRaft 重试缓存 TTL
retain_checkpoint_num3保留 checkpoint 数;0 会被拒绝
ignore_reply_errorfalse跳过无法重放的 journal batch,而不是失败
max_retry_num1000最大重放重试次数
skip_failed_ufs_replay_after_retrytrue重试后推进 UFS 重放水位;元数据重放永不跳过
scan_batch_size1000Journal 扫描 batch 大小
retry_interval_secs10重放重试间隔
ufs_copy_timeout20m数据复制到 UFS 的超时
recover_from_peers未设置显式指定需要从健康 peer 重建的单个丢失 HA 成员的 Raft ID

要点:

  • journal_addrs 必须列出 Raft 节点,且本地实际 hostname 必须匹配其中一项(或 net_interface 解析出的 IPv4 必须匹配)。否则启动失败。
  • retain_checkpoint_num 同时决定保留的日志窗口(retain_checkpoint_num × snapshot_entries 条 entry)。调大会增加 journal 磁盘占用。
  • leader_create_snapshot 默认只为单节点组创建 snapshot。多节点组未设置该键时,Leader 侧没有日志压缩路径,并且每隔几分钟输出一次错误日志;生产 HA 集群应显式设置 leader_create_snapshot = true。
  • ignore_reply_error = true 可能使 Master 与其余节点永久分叉,只应在灾难恢复时使用,不能作为常规配置。
  • recover_from_peers 通常只用于运维人员主动重建“日志非空但已陈旧”的成员。被清空的成员在集群健康时会自动进入隔离恢复流程。

[worker]

字段默认值含义
hostnamelocalhostWorker hostname;可被 net_interface 或 CURVINE_WORKER_HOSTNAME 覆盖
weight1weighted 策略下的相对分配权重;0 表示不再接收新分配
rpc_port8997Worker RPC 端口
web_port9002Worker Web / 指标端口
dir_reserved0每个数据目录固定预留的空闲空间
free_ratio0.0按设备比例设置的严格空闲下限([0.0, 1.0));0 关闭
data_dir[]Worker 数据目录列表
io_slow_threshold300ms慢 I/O 阈值
io_threads32Worker RPC I/O 线程数
worker_threadsmax(32, 2 × CPU)Worker RPC worker 线程数
io_timeout10mWorker 网络超时
io_close_idlefalse关闭空闲 Worker RPC 连接
scheduler_threads2调度线程数
executor_threads10后台执行线程数
executor_channel_size1000后台执行队列大小
transfer_io_threads0加载、导出和副本复制任务使用的独立运行时线程数,避免其块 I/O 阻塞 RPC 处理;0 表示与 RPC 运行时共用。运行大量传输任务的 Worker 建议设为 8 到 32
transfer_blocking_threadsmax(64, 2 × CPU)该运行时并发的本地块 I/O 调用上限(仅在 transfer_io_threads 非零时生效);0 表示 tokio 默认值 512
enable_splicefalse启用 splice 优化
enable_send_filetrue启用 sendfile 优化
pipe_buf_size64KBPipe buffer 大小
pipe_pool_init_cap0Pipe pool 初始容量
pipe_pool_max_cap2000Pipe pool 最大容量
pipe_pool_idle_time0Pipe 空闲回收时间
block_replication_concurrency_limit100复制任务并发上限
block_replication_chunk_size1MB复制 chunk 大小
block_checksumfalse在每个完成的本地块旁写入按 chunk 计算的 CRC32C 校验文件
block_checksum_verifyfalse读取本地块时逐 chunk 与校验文件比对,不一致则读取失败;启用后不使用 sendfile 和短路读
block_checksum_allow_missingtrue启用 block_checksum_verify 时,没有校验文件的块不校验直接读取,而不是拒绝
block_checksum_scan_on_starttrue启用 block_checksum_verify 时,Worker 启动后在后台重新校验所有已完成的块,并删除校验失败的块
block_checksum_scan_rate100MB启动扫描每秒读取速率上限;0 表示不限速
spdk_disk关闭SPDK NVMe-oF/RDMA 磁盘配置
compatibilitydiagnose数据面 peer 的版本兼容策略

data_dir 支持三种写法:

data_dir = [
  "[SSD]/data/data1",          # 指定存储类型,容量不设限
  "[HDD:500GB]/data/data2",    # 指定存储类型与容量
  "/data/data3"                # 默认为 DISK,容量不设限
]

存储类型包括 SSD、HDD、DISK、MEM。Worker 会在每个路径下追加 cluster_id,因此实际数据目录为 <path>/<cluster_id>。

dir_reserved 是固定字节预留;free_ratio 按物理设备比例预留,并且会考虑同盘其他应用占用的空间。两者都会在写入准入时作用于新 block 和 FileLayout 重写 staging 副本。

[worker.spdk_disk] 仅在启用 SPDK 的服务端构建中有效(build.sh --spdk 或 --spdk-rdma),包含 enabled、app_name、reactor_mask、qpair_acquire_timeout,以及 targets 数组(trtype、adrfam、traddr、trsvcid、subnqn)。

[client]

字段默认值含义
master_addrs[]Master RPC 地址;为空时自动推导
hostnamelocalhost客户端 hostname;可被 net_interface 或 CURVINE_CLIENT_HOSTNAME 覆盖
io_threads16客户端 RPC I/O 线程数
worker_threadsmax(16, 2 × CPU)客户端 RPC worker 线程数
replicas1默认副本数
block_size128MB默认 block 大小
alloc_first_block_on_createtrue创建或打开文件时请求 Master 同时分配第一个块,小文件可少一次 RPC;不支持的 Master 会忽略
write_chunk_size128KB写 chunk 大小
write_chunk_num8单 pipeline 写 chunk 数
write_buffer_size256MB本客户端所有带缓冲的写入器可排队的总字节数,超过后新的写入等待;0 表示只受每个文件的 chunk 数限制
write_limit0写带宽上限(Mbps),由客户端所有块写入器共享,按写入字节计一次而不是按副本计;0 表示不限制
read_chunk_size128KB读 chunk 大小
read_chunk_num8单 pipeline 读 chunk 数
read_parallel1基础读并发
read_pipeline_depth1每个远程块读取同时在途的 chunk 请求数;大于 1 时下一个请求与当前 chunk 的传输重叠
read_slice_size0读切片大小;0 表示 read_chunk_size × read_chunk_num
max_cache_block_handles10block handle 缓存上限
short_circuittrue启用 short-circuit 读
storage_typedisk默认存储类型
ttl_ms0默认 TTL
ttl_actionnone默认 TTL 动作
auto_cache_enabledfalse对 UFS 读取自动提交缓存请求
auto_cache_ttl7d自动缓存条目的 TTL
conn_retry_max_duration_ms60000连接重试最大时长
conn_retry_min_sleep_ms100连接重试最小休眠
conn_retry_max_sleep_ms2000连接重试最大休眠
rpc_retry_max_duration_ms60000RPC 重试最大时长
rpc_retry_min_sleep_ms100RPC 重试最小休眠
rpc_retry_max_sleep_ms3000RPC 重试最大休眠
rpc_close_idletrue关闭空闲 RPC 连接
conn_timeout_ms30000连接超时
rpc_timeout_ms120000RPC 超时
data_timeout_ms300000数据传输超时
pipeline_timeout_ms120000Pipeline 超时
master_conn_pool_size1每个 Master 的连接数
enable_read_aheadtrue启用预读
read_ahead_len0预读长度;0 表示 read_chunk_size × read_chunk_num
drop_cache_len1MB读后丢弃 page cache 的数据长度阈值
failed_worker_ttl_ms600000失败 Worker 的拉黑时长
enable_unified_fstrue启用统一文件系统视图
enable_rust_read_ufstruecache miss 时允许直接读 UFS
audit_logging_enabledtrue输出客户端审计日志
mount_update_ttl_ms60000Mount 元数据刷新周期
umask022文件创建 umask(八进制)
metric_report_enabletrue上报客户端指标
clean_task_interval_ms60000清理任务周期
close_timeout_secs5关闭超时
sync_check_interval_min_ms100UFS 同步轮询最小间隔
sync_check_interval_max_ms1000UFS 同步轮询最大间隔
max_sync_wait_timeout_ms300000同步任务最大等待时间
sync_check_log_tick3同步进度日志的轮询间隔(tick)
enable_block_conn_pooltrue启用 block 连接池
block_conn_idle_size128空闲 block 连接保留数量
block_conn_idle_time_ms60000Block 连接空闲时间
small_file_size4MB小文件阈值
enable_smart_prefetchtrue启用 smart prefetch
large_file_size10GB大文件阈值
max_read_parallel8最大动态读并发
sequential_read_threshold7顺序读判定阈值
seek_absorb_window0前向 seek 吸收窗口:落在预读缓冲区该距离内的前向 seek 直接由缓冲区提供。需要 enable_smart_prefetch = true 且 read_chunk_num > 1;0 表示关闭

大小字段使用字符串,例如 "128MB"、"4MB"、"10GB";以 _ms 结尾的时长字段使用整数毫秒。旧的无后缀别名(mount_update_ttl、sync_check_interval_min 等)仍被接受。

[fuse]

字段默认值含义
debugfalse输出 FUSE 请求/响应日志
audit_logging_enabledfalse输出 FUSE 审计日志
metrics_enabledtrue输出 FUSE 请求/错误/延迟指标
io_threads32FUSE I/O 线程数
mnt_path/curvine-fuse挂载点路径
fs_path/挂载点内可见的 Curvine 根路径
mnt_number1挂载点数量(在 mnt_path 下创建 mnt-0、mnt-1…)
tasks_per_mnt0每个挂载点的 I/O 任务数;0 跟随 io_threads
clone_fdtrue启用 clone-fd 优化
fuse_channel_size0FUSE 请求队列大小;0 使用后端默认值
stream_channel_size0读写请求队列大小;0 使用后端默认值
fuse_opts[]额外挂载选项(见下文)
readonlyfalse在内核层以只读方式挂载
async_deletefalseunlink 和 rmdir 走 Master 的异步删除通道:条目立即从命名空间移除,空间在后台回收
umask022为 ./.. 合成权限位时使用的 umask
uid / gid当前进程挂载条目的默认属主
web_port9003FUSE Web / 指标端口
read_dir_fill_inotrue列目录时填充 node ID
entry_timeout1s内核 dentry 缓存超时
negative_timeout0内核负查找缓存超时;0 表示关闭
attr_timeout1s内核属性缓存超时
rememberfalse记住已打开的文件与目录
max_background256最大后台请求数
congestion_threshold192拥塞阈值;必须 ≤ max_background
enable_meta_cache未设置启用用户态元数据缓存;未设置时,只要 meta_cache_timeout 窗口非零即启用,默认即为非零
meta_cache_timeout未设置用户态元数据缓存窗口;未设置时跟随 attr_timeout
node_cache_timeout1hinode/node map 逐出 TTL
direct_iofalse所有打开操作绕过内核 page cache
open_direct_on_stalefalse本地元数据陈旧时对该次打开使用 direct I/O
write_back_cachefalse允许内核缓冲写
cache_readdirfalse缓存目录列表
non_seekablefalse将文件标记为不可 seek
check_permissiontrue执行权限检查
state_dir系统临时目录持久化 FUSE 状态的目录
max_readahead_kb未设置覆盖 BDI read_ahead_kb;未设置时保持内核默认
list_limit1000目录列举数量限制
enable_splicefalseFUSE 数据传输使用 splice/vmsplice
path_lock_stripes1024路径锁分片数

说明:

  • meta_cache_capacity 与 node_cache_size 已被移除,请改用 meta_cache_timeout 与 node_cache_timeout。
  • negative_timeout = 0 表示关闭负查找缓存,而不是“永久缓存”。
  • direct_io 与 write_back_cache 不能同时启用,启动时会被拒绝。
  • fuse_opts 支持 VFS 选项对 ro/rw、nodev/dev、nosuid/suid、noexec/exec、noatime/atime、sync/async,以及 dirsync、allow_other、default_permissions、big_write。旧版 libfuse 选项 auto_unmount、allow_root、max_write 不受直接挂载后端支持。
  • 时长值支持字符串("1s"、"500ms"、"1h")或按毫秒解释的裸整数。旧的 *_ms 键仍作为别名接受。

[web]

curvine-web 是一个独立进程(二进制 curvine-web,通过 bin/curvine-web.sh start 启动),提供管理控制台:集群总览、文件浏览、Worker 列表、配置与监控大盘。它不由 curvine-server 启动,也不在本地集群辅助脚本的启动列表中;需要 UI 时请单独启动。

字段默认值含义
hostnamelocalhost管理控制台监听主机名
port9000管理控制台 HTTP 端口

[master].web_port(9010)只是一个指标监听端口,用浏览器打开它只会得到 Prometheus 文本输出,不是管理界面。UI 请访问 [web].port(9000)。

[web.observability]

管理控制台内嵌了自己的采集器和时序库,因此不依赖 Prometheus 也能看大盘。把 mode 改成 prometheus 或 auto 可改为查询已有的 Prometheus。

字段默认值含义
enabledtrue是否启用可观测性组件
modebuiltinbuiltin、prometheus 或 auto
scrape_interval60s内置采集器的抓取间隔
scrape_timeout3s单目标抓取超时
retention24h内存时序库保留窗口
max_concurrent_scrapes32并发抓取上限
max_concurrent_dashboard_queries8单次大盘刷新的并发范围查询上限
max_series100000序列基数上限
max_samples_per_series10000每个序列保留的样本数

[web.observability.fuse]

FUSE 指标抓取默认关闭。enabled = true 且 targets 为空时,采集器会抓取 127.0.0.1:{fuse.web_port}。

字段默认值含义
enabledfalse是否发现并抓取 FUSE /metrics 端点
targets[]host:port 或完整的 http://host:port/metrics 地址

[web.observability.prometheus]

字段默认值含义
url空Prometheus 基础地址,例如 http://prometheus:9090
query_timeout5sPrometheus 查询 API 超时
fallback_builtintruemode = "auto" 时,Prometheus 不可用则回退到内置采集器
target_cache_ttl30s/api/v1/targets 响应的缓存时长

当 mode = "prometheus" 时,还需要按 etc/prometheus-curvine.yml 中的说明加上目标标签,大盘才能把指标归属到正确的角色。

[s3_gateway]

S3 兼容网关是一个独立服务(二进制 curvine-s3-gateway,通过 bin/curvine-s3-gateway.sh start 启动)。本段只被网关进程读取,Master 和 Worker 会忽略它。支持的 API 范围见 S3 对象存储网关。

字段默认值含义
listen0.0.0.0:9900S3 HTTP 监听地址
regionus-east-1GetBucketLocation 返回的区域,也用于 SigV4 签名范围
put_temp_dir/tmp/curvine-tempPUT 暂存目录(分片和普通上传共用)
put_memory_buffer_threshold1048576低于该大小的 PUT 在内存中缓冲,不落 put_temp_dir
put_max_memory_buffer16777216内存缓冲上限
access_key / secret_key空不使用分布式凭证存储时的静态密钥
enable_distributed_authfalse从 Curvine 加载凭证,而不是使用静态密钥
credentials_path空存放凭证文件的 Curvine 路径
cache_refresh_interval_secs30凭证缓存刷新间隔
get_chunk_size_mb1.0读块大小(MB),可选 0.5、1、2
signed_chunk_spool_dir/tmp/curvine-signed-spool大于 16 MiB 的已签名 aws-chunked 记录在签名校验通过前缓存到的绝对路径目录;请使用私有目录
signed_chunk_spool_max_bytes10GB(10737418240)每个网关进程的缓存上限;无法预留完整大小的记录返回 503 SlowDown。至少保留 5 GiB,以容纳任何合法的单条记录
web_port9003网关健康检查 / 指标 HTTP 端口

worker.enable_s3_gateway(默认 false)决定分片上传的暂存位置:false 时存放在网关宿主机的本地文件系统,true 时使用 Curvine DFS,从而允许多个网关实例共同处理同一次上传。

worker.enable_s3_gateway 由网关进程读取,Worker 本身不读取该字段。可以只在网关的配置文件里设置,无需重启 Worker。

[log]、[cli]、[job]

全局 [log]

顶层 [log] 由 Rust 客户端与 FUSE 共用。每个服务还有自己的嵌套 log 表(master.log、worker.log、mds.log、transfer.log),CLI 使用 [cli].log。

字段默认值含义
levelINFO日志级别
log_dirstdoutstdout、stderr 或用于文件日志的目录
file_name空日志文件基础名;为空时使用 curvine
max_log_files10保留的轮转文件数
max_file_size_mb100按大小轮转的阈值(MB);0 表示不限制大小
time_rotation空daily 或 hourly;空表示不按时间轮转
display_threadfalse输出线程名与 ID
display_positiontrue输出源码位置
targets[]将指定日志 target 拆分到独立文件

仅当 log_dir 为目录时才会轮转。大小与时间轮转都未设置时,文件按 100 MB 大小轮转;如果 max_file_size_mb = 0 且没有有效的 time_rotation,文件会按天轮转,避免无限增长。

[cli]

CliConf 只包含 log。CLI 默认日志级别为 warn,输出到 stdout。

[job]

[job] 配置 transfer.enabled = false 的客户端所使用的旧版 Master 侧任务实现。Transfer Job 的任务所有权、恢复和保留策略由 [transfer] 控制。

字段默认值含义
job_life_ttl24hJob 记录生命周期
job_cleanup_ttl10m过期 Job 清理周期
terminal_retention10m终态 Job 可查询时长
job_max_files100000单 Job 最大文件数
master_max_concurrent_load_jobs16Master 侧并发 load 规划任务数
master_max_background_load_jobs1024允许等待的后台 load 任务数
master_max_pending_load_job_submits4096准入前允许等待的提交请求数
master_load_job_runtime_threads4预留给 load 规划的运行时线程数
master_load_job_blocking_threads16预留给 load 规划的阻塞线程数
master_failed_load_job_retry_interval30s确定性 source-not-found 失败的重用窗口
task_timeout1h任务最大执行时间
task_report_interval10s任务进度上报间隔
worker_max_concurrent_tasks100单 Worker 最大并发任务数
worker_max_queued_tasks0Worker 同时持有的任务数上限(等待加运行中);超过后新任务收到可重试的“队列已满”应答。0 表示 2 × worker_max_concurrent_tasks
worker_queue_full_timeout30m单次提交等待已满的 Worker 队列腾出空间的最长时间,超时后放弃该任务的派发
load_parallel_streams8加载和导出任务中每个对象的并行读取流数;挂载可通过 load_task.parallel_streams 覆盖
load_min_bytes_per_stream32MB每个流最少的源数据字节数:对象被拆成 len / load_min_bytes_per_stream 个流,上限为 load_parallel_streams;挂载可通过 load_task.min_bytes_per_stream 覆盖
ufs_read_chunk_size2097152(2 MiB)单个 UFS 读取请求的范围大小;挂载可通过 opendal.read_chunk_size 覆盖
ufs_read_concurrent4每个流同时在途的范围请求数;挂载可通过 opendal.read_concurrent 覆盖。单个对象约占用 load_parallel_streams × ufs_read_concurrent × ufs_read_chunk_size(默认 64 MiB)读缓冲,一个 Worker 最多有 worker_max_concurrent_tasks 个这样的对象,调大前请考虑 Worker 内存

[transfer]

[transfer] 由独立 Transfer 服务读取,也由需要将 Load / Export 提交给该服务的客户端读取。Transfer 服务除本段外,还需要正常的 [client] Master 地址。灰度阶段应保持 Master 与 Worker 配置中的 Transfer 关闭,只在 Transfer 服务和选定客户端配置中启用。

字段默认值含义
enabledfalse在当前进程启用 Transfer 路由。客户端启用后 load、export 使用 Transfer;Transfer 服务端启用后启动该服务。
store_url空;推导为 sqlite://data/transfer/transfer.db状态存储 URL。支持 memory://、sqlite://、mysql://、postgres://、postgresql://。多实例使用一个共享的 mysql:// 或 postgres:// URL。
hostnamelocalhost未显式配置 endpoint 时使用的 RPC / Web 监听 hostname
rpc_port9010Transfer RPC 端口
web_port9011健康检查和指标 HTTP 端口
endpoints["<hostname>:<rpc_port>"]客户端访问的 Transfer RPC 地址;应填写 Service 或负载均衡地址
instance_id空可选的稳定服务 owner ID;为空时自动生成 UUID
max_running_transfers64当前实例可并发执行的最大 Job 数
client_pending_queue_size1024等待或正在提交的自动缓存请求上限
client_submit_concurrency64客户端自动缓存提交的最大并发数
max_tasks_per_transfer100000单个 Transfer Job 的最大任务数
ufs_max_concurrency_per_endpoint32单个 UFS endpoint 的最大并发任务数
task_max_retries3任务最大重试次数
lease_timeout120s用于恢复和多实例协调的 owner 租约时长
terminal_retention168hCompleted、Failed、Canceled Job 记录的保留时间
logtransfer.logTransfer 日志配置

新配置不要使用兼容字段 store_type、sqlite_path、mysql_url。store_url 根据 URL scheme 推导存储后端。内部队列、探测和调度参数不属于公开的用户配置面。

PostgreSQL 使用私有 CA 时,在 store_url 后追加 sslrootcert=/path/to/ca.pem;默认情况下 TLS 校验系统信任库。

[discovery]

服务发现默认关闭。启用时唯一支持的 provider 是 etcd。

字段默认值含义
enabledfalse启用 etcd 服务发现
provideretcd发现 provider;启用时必须为 etcd
endpoints[]etcd endpoints,例如 ["http://etcd-0:2379"]
prefix/curvineetcd key 绝对前缀
connect_timeout_ms3000etcd 连接超时
request_timeout_ms3000etcd 请求超时
watch_reconnect_min_ms1000Watch 重连退避下界
watch_reconnect_max_ms30000Watch 重连退避上界
watch_reconnect_jitter_ratio0.2Watch 重连抖动比例(0.0–1.0)
allow_stale_cachetrueWatch 断开时允许返回陈旧缓存

启用服务发现时,cluster_id 只能包含小写字母、数字、_ 和 -。实际 key 为 {prefix}/{cluster_id}/services/{kind}/{service_id}。

[fault_injection]

仅测试使用的故障控制面,默认关闭,正常部署不得启用。

字段默认值含义
enabledfalse暴露故障 HTTP 路由
auth_token_envCURVINE_FAULT_TOKEN保存 bearer token 的环境变量名

故障 HTTP 路由要求二进制使用 fault-injection Cargo feature 构建(例如 curvine-server/fault-injection)。如果启用了 [fault_injection] 但构建时未包含该 feature,服务启动会直接失败,而不是静默省略路由。

版本兼容策略

[master.compatibility] 与 [worker.compatibility] 字段相同:

字段默认值含义
modediagnosediagnose 只记录不兼容;enforce 拒绝不兼容的 peer
min_worker_version空Master 接受的最低 Worker 版本(空表示不限制)
min_client_version空接受的最低客户端版本(空表示不限制)
blocked_versions[]无论模式如何都拒绝的版本

协议版本范围是代码级契约,不是运维配置项。无效的 mode 字符串与无法解析的版本边界会退化为宽松默认值,而不是直接拒绝启动。

enforce 模式要求 Worker 在心跳中上报 component_info。早于该字段引入版本的 Worker 会被解析为 MissingInfo 并被拒绝,因此在全部 Worker 升级完成前应保持 diagnose。

示例骨架

format_master = false
format_worker = false
# net_interface = "eth0"

[master]
meta_dir = "data/meta"
# [master.compatibility]
# mode = "diagnose"

[mds]
enabled = false
rpc_port = 8998
web_port = 9004
kv_backend = "fdb"
fdb_cluster_file = "/etc/foundationdb/fdb.cluster"

[journal]
journal_addrs = [
  { id = 1, hostname = "master1", port = 8996 },
  { id = 2, hostname = "master2", port = 8996 },
  { id = 3, hostname = "master3", port = 8996 },
]
journal_dir = "data/journal"
leader_create_snapshot = true

[worker]
data_dir = ["[SSD]/data/data1"]
weight = 1

[client]
master_addrs = [
  { hostname = "master1", port = 8995 },
  { hostname = "master2", port = 8995 },
  { hostname = "master3", port = 8995 },
]

[transfer]
enabled = false

[fuse]
mnt_path = "/curvine-fuse"
web_port = 9003

[log]
level = "info"
log_dir = "stdout"

[cli]
log = { level = "warn", log_dir = "stdout", file_name = "cli.log" }

[discovery]
enabled = false