缓存
对于初次接触的使用者来说，你可以把 Curvine 简单理解为：一个可以像本地磁盘一样使用的分布式文件缓存。它不用你关心数据存在集群的哪台机器、哪种存储上，只需通过一个挂载点，就能轻松使用分布式的缓存能力，适配绝大多数日常文件操作场景。
一、什么是 Curvine？
Curvine 是一款分布式文件缓存系统，它能够把集群内的各类存储介质、远端存储资源整合在一起，构建出一个统一的文件目录空间，并且对外提供可直接挂载的文件系统。
和传统分布式文件系统不同，Curvine 最大的亮点是完整兼容 POSIX 语义，使用体验和你电脑上的本地磁盘几乎没有区别。不用额外学习复杂的操作指令，也不用改造原有应用，不管是日常开发、数据缓存、git clone、数据库文件存储、日志写入还是临时文件存放，直接把文件路径指向 Curvine 挂载点即可，完全做到“即挂即用”。
二、核心特性
| 核心能力 | 通俗说明 |
|---|---|
| 统一命名空间 | 只用一个挂载点，就能访问全部文件目录，不用关心数据具体存在哪台 Worker 节点、哪种存储介质上；文件路径、权限设置和本地文件系统完全一致，上手零成本。 |
| 高速缓存，重复访问更流畅 | 常用的工作数据会驻留在集群内速度更快的介质中，反复访问这些数据时，能大幅减少对远端存储或低速存储的 I/O 请求，打开、读取文件的速度更快。 |
| 智能分层存储 | 支持内存（MEM）、固态硬盘（SSD）、机械硬盘（HDD）多种存储层级，管理员提前配置好各层级路径，使用者可以指定优先写入的介质；当优先层级空间不足时，数据会自动向下一层级溢出，平衡速度、成本和存储容量。 |
| 智能空间管理 | 通过 TTL 时间过期和配额 + LRU 淘汰双重机制管控存储空间，避免缓存无限占用集群容量，不用手动清理也能保持空间充足。 |
| 完整 POSIX 文件语义 | 全面支持各类标准文件操作，包括随机写、并发写、文件锁、扩展属性、软硬链接、稀疏文件等，能适配日志、数据库、项目构建等真实业务场景，原有本地应用直接迁移即可使用。 |
三、和本地磁盘一样的使用体验
Curvine 完全贴合本地磁盘使用习惯。
3.1 多进程并发写入
多个客户端、多个进程可以同时写入同一个文件，不需要应用自己做协调管控，只要写入文件的不同偏移位置，就不会出现数据混乱，和本地多进程写文件的语义完全一致。
3.2 自由随机写入
不限制只能顺序写或追加写，支持在文件的任意位置随时写入数据，适配数据库、大文件修改等需要随机读写的场景。
3.3 常用命令全兼容
Linux 系统下所有常规文件操作命令，比如 cp（复制）、mv（移动）、rm（删除）、mkdir（新建文件夹）、ls（查看目录）、find（查找文件）等，在 Curvine 挂载点上都能正常使用，操作习惯完全不用改。
四、POSIX 高级特性详解
Curvine 完整支持各类 POSIX 高级特性，满足各类复杂业务需求，具体能力说明如下：
| 特性名称 | 详细说明 |
|---|---|
| 随机写 & 并发写 | 支持文件任意位置写入，多客户端可同时操作同一文件的不同区域，适配日志、数据库等对写入灵活性要求高的场景。 |
扩展属性（xattr） | 完整支持文件扩展属性，使用者可以自定义存储文件的专属元数据，方便做文件标记、业务关联等操作。 |
| 符号链接（软链接） | 支持软链接功能，建议链接目标都指向 Curvine 内部路径；如果链接到本机其他目录或其他节点本地路径，分布式环境下其他节点可能无法正常访问。 |
| 硬链接 | 支持硬链接，语义和本地文件系统一致，仅适用于 Curvine 内部同一文件系统范围内，跨系统无法创建。 |
| 文件锁 | 兼容 POSIX 锁和 BSD 锁，考虑到分布式环境的稳定性，文件锁带有默认 5 分钟超时自动释放机制，避免客户端或节点异常导致锁一直占用，引发死锁问题。 |
| 稀疏文件（文件空洞） | 支持稀疏文件模式，没有实际写入数据的空洞区域不会占用物理存储空间，节省集群存储资源。 |
| 空间预分配 | 支持提前为文件分配存储空间，避免大文件写入过程中出现空间不足的问题，保证写入流程稳定。 |
| 常规文件属性 | 文件权限位、访问/修改时间戳、文件截断等基础 inode 语义，完全遵循 POSIX 标准，和本地文件操作体验一致。 |
五、分层存储使用说明
Curvine 支持多层级存储介质，通过简单配置即可指定数据存储优先级，兼顾速度与成本。
5.1 工作原理
Worker 节点配置各存储层级的路径和标签，使用者在客户端指定优先使用的存储类型，数据会优先写入目标层级；当该层级容量不足时，会自动降级到下一层级存储，无需手动干预。
5.2 配置示例
Worker 节点配置：
[worker]
data_dir = [
'[MEM]/mem',
'[SSD]/data/ssd',
'[HDD]/data/hdd'
]
客户端配置：
[client]
storage_type = "mem"
配置效果：新建文件优先存入内存层，内存空间不足时，自动依次存入 SSD、HDD 层。
六、缓存策略
6.1 写入策略
写入策略控制挂载路径上的数据写入方式，通过 cv mount ... --write-type <类型> 配置，CLI 默认值为 fs_mode。
| 策略 | CLI 取值 | 行为 | 适用场景 |
|---|---|---|---|
| CacheMode | cache_mode | 直接写到底层 UFS，Curvine 主要承担统一访问与缓存读取层。 | 数据主存仍在 UFS 的场景。 |
| FsMode | fs_mode | 优先写入 Curvine 命名空间；首次挂载时可能触发元数据 resync。 | 由 Curvine 管理缓存命名空间的场景。 |
6.2 读取校验
当前面向用户的读侧校验开关是挂载参数 --read-verify-ufs：
| 策略 | 行为 |
|---|---|
| 关闭 | 信任缓存与统一文件系统默认回退逻辑。 |
| 开启 | 读前按 UFS 元数据（mtime 与文件长度）校验缓存。 |
当校验失败或缓存未命中时，会直接从 UFS 读取；若该挂载启用了自动缓存，可同时异步将数据加载到 Curvine。
七、数据过期管理（TTL）
为了合理管控缓存空间，Curvine 支持为文件、目录配置过期时间和过期策略，自主控制数据生命周期。
7.1 基础配置示例
[client]
ttl_ms = "1d"
ttl_action = "delete"
配置效果：文件从最后一次修改时间（mtime）开始计算，1 天后自动过期，执行删除操作。
7.2 按挂载配置 TTL
使用 cv mount 挂载 UFS 时，可为该挂载设置 TTL：
| 选项 | 类型 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|
--ttl-ms | duration | 7d（挂载默认） | 缓存数据过期时间 | 24h、7d、30d |
挂载点的 TTL 动作由 write_type 推导：
cache_mode挂载默认对应deletefs_mode挂载默认对应free
7.3 过期策略说明
| 策略取值 | 具体含义 |
|---|---|
none | 关闭时间过期功能，数据会一直保留，直到手动删除或其他策略清理。 |
delete | 过期后彻底删除文件数据和元数据，是最常用的“到期清理”策略，时间从文件最后修改时间算起。 |
free | 过期后只释放文件占用的数据块，保留目录和元数据，适合需要保留目录结构、清理缓存数据的场景。 |
7.4 使用注意：mtime 与数据拷贝
使用 rclone 等工具往 Curvine 拷贝文件时，工具会保留源文件的原始修改时间（mtime）。如果源文件本身已经存放很久，拷贝后可能会立刻触发 TTL 过期，导致文件被删除或释放。
建议大批量导入数据前，先确认 TTL 配置，或导入后手动调整文件 mtime、临时关闭 TTL，避免数据误清理。
7.5 Master 节点（TTL 检查器）
在集群配置的 [master] 段中，使用以下 TOML 键：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ttl_checker_interval | duration | 1h | TTL 检查器运行间隔 |
ttl_checker_retry_attempts | u32 | 3 | TTL 操作失败时的最大重试次数 |
ttl_bucket_interval | duration | 1h | 批量处理过期 inode 的桶时间间隔 |
ttl_max_retry_duration | duration | 10m | 失败 TTL 操作的最大重试时长 |
ttl_retry_interval | duration | 1s | 重试间隔 |
7.6 执行流程
八、数据淘汰机制（配额与 LRU）
除了按时间过期，Curvine 还支持基于存储配额的自动淘汰，防止集群存储空间被写满，保障系统稳定运行。
8.1 工作原理
开启配额淘汰后，当集群存储用量达到设定的高水位线时，系统会自动按照 LRU（最近最少使用）规则，清理长时间没有访问过的数据，直到存储空间回落至安全范围。
8.2 配置示例
[master]
enable_quota_eviction = true
quota_eviction_high_rate = 0.8
8.3 与 TTL 的关联
如果设置 ttl_action = "none"，关闭了时间过期策略，那么数据也不会被配额 LRU 机制淘汰删除，适合需要长期保留的重要数据。
九、缓存方式
9.1 自动缓存
当某挂载配置了非零 TTL（例如 cv mount s3://bucket/prefix /path --ttl-ms 7d）时，即启用该挂载的自动缓存。在该挂载下首次读取某个 UFS 文件（缓存未命中）时，Curvine 会提交一个异步加载任务，将数据拉取到 Curvine；本次读取由 UFS 直接返回，任务在后台执行。
在日志中可看到类似输出：
Submit async cache successfully for s3://bucket/cache/test.log, job res CacheJobResult { job_id: 7c00853f-13c8-43c1-8b3f-44740750b5a0, target_path: /s3/cache/test.log }
可用 job_id 查询缓存任务状态：
bin/cv load-status 7c00853f-13c8-43c1-8b3f-44740750b5a0
9.2 主动缓存
可以使用 load 命令主动加载 UFS 数据到 Curvine，示例如下：
bin/cv load s3://bucket/cache/test.log
自动缓存与主动缓存可同时使用；主动缓存可缩短该文件首次读取的等待时间。
加载数据前，须先将 UFS 挂载到 Curvine（cv mount）。
自动缓存与主动缓存均使用固定缓存路径，与 UFS 目录结构一致。
十、快速小结
| 核心维度 | Curvine 核心要点 |
|---|---|
| 产品定位 | 分布式文件缓存，支持 POSIX 挂载，使用体验等同于本地磁盘 |
| 核心优势 | 统一命名空间、分层智能存储、TTL + LRU 双重空间管控、完整 POSIX 语义 |
| 写入能力 | 支持随机写、多客户端并发写同一文件，适配复杂业务 |
| 高级特性 | 支持扩展属性、软硬链接、带超时的文件锁、稀疏文件、空间预分配 |
| 存储管理 | 多介质分层存储，客户端可指定优先级，空间不足自动降级 |
| 空间管控 | 基于 mtime 的 TTL 过期 + 可选配额 LRU 自动淘汰，灵活管控存储容量 |