3FS：DeepSeek Fire-Flyer 高性能分布式文件系统部署与挂载指南

一、项目官方信息

Fire-Flyer File System（3FS） 是面向 AI 训练与推理负载的高性能分布式文件系统，利用现代 SSD 与 RDMA 网络提供共享存储层，简化分布式应用开发。

特点：

• 分离式架构：聚合数千块 SSD 与数百存储节点的带宽，应用可忽略 locality 访问；
• 强一致性：用 CRAQ（Chain Replication with Apportioned Queries）实现强一致；
• 文件接口：无状态元数据服务，后端用事务型 KV（如 FoundationDB），沿用熟悉的文件 API，无需学习新存储接口；
• 适用：数据准备、dataloader、大规模并行 checkpoint、推理 KVCache。

二、官方图片

上图为 3FS 仓库在 GitHub 上的社交预览图。官方另有性能图（180 节点读吞吐 6.6 TiB/s、GraySort、KVCache 吞吐）。

三、环境要求

• 操作系统：Ubuntu 20.04/22.04、openEuler 2403sp1、OpenCloudOS 9 / TencentOS 4；
• 现代 SSD（NVMe）与 RDMA/InfiniBand 网络（生产环境）；
• 依赖：cmake、libuv、lz4、xz、gflags、glog、boost、clang-14、lld-14 等；
• 额外组件：libfuse 3.16.1+、FoundationDB 7.1+、Rust 工具链（1.75+，推荐 1.85+）。

四、构建与部署步骤

1. 克隆并初始化子模块

git clone https://github.com/deepseek-ai/3fs
cd 3fs
git submodule update --init --recursive
./patches/apply.sh

2. 安装系统依赖

以 Ubuntu 22.04 为例：

apt install cmake libuv1-dev liblz4-dev liblzma-dev libdouble-conversion-dev libdwarf-dev libunwind-dev \
  libaio-dev libgflags-dev libgoogle-glog-dev libgtest-dev libgmock-dev clang-format-14 clang-14 clang-tidy-14 lld-14 \
  libgoogle-perftools-dev google-perftools libssl-dev gcc-12 g++-12 libboost-all-dev build-essential

并安装：libfuse 3.16.1+、FoundationDB 7.1+、Rust 1.85+。

3. 编译

# <method> 按环境选 g++10 或 g++11
cmake -S . -B build \
      -DCMAKE_CXX_COMPILER=clang++-14 -DCMAKE_C_COMPILER=clang-14 \
      -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
      -DSHUFFLE_METHOD=g++11
cmake --build build -j 32

注意：必须显式指定 -DSHUFFLE_METHOD（g++10 或 g++11）锁定 shuffle 算法；集群一旦部署，后续所有构建必须保持同一配置以保证兼容。

4. 用 Docker 构建镜像

# TencentOS-4
docker pull docker.io/tencentos/tencentos4-deepseek3fs-build:latest
# OpenCloudOS-9
docker pull docker.io/opencloudos/opencloudos9-deepseek3fs-build:latest

5. 运行测试集群

按部署指南（deploy/README.md）启动一个测试集群。

五、使用方法

• 挂载使用：3FS 对外提供文件接口，挂载后像普通文件系统一样读写，无需学习新 API；
• 数据准备：把分析流水线输出组织成层级目录，高效管理大量中间产物；
• Dataloader：跨计算节点随机访问训练样本，免去预取与 shuffle；
• Checkpoint：支持大规模训练的高吞吐并行 checkpoint；
• KVCache：以比 DRAM 更低成本提供高吞吐、大容量推理 KVCache；
• 基准测试：用官方 fio engine（benchmarks/fio_usrbio）跑分。

六、常见问题 FAQ

1. 3FS 面向什么场景？ AI 训练与推理：数据准备、dataloader、并行 checkpoint、推理 KVCache。

2. 为什么要指定 -DSHUFFLE_METHOD？ 历史上用了 std::shuffle，不同编译器版本编译出的二进制不兼容；必须锁定，且集群一旦部署就保持一致。

3. 元数据后端用什么？ 事务型 KV（如 FoundationDB 7.1+）。

4. 生产网络要求？ 官方集群用 InfiniBand/RDMA（如 2×200Gbps），配合 NVMe SSD。

5. 怎么跑测试集群？ 按 deploy/README.md 部署指南操作。

6. 性能数据？ 180 存储节点 + 500 客户端读吞吐约 6.6 TiB/s；KVCache 峰值读吞吐达 40 GiB/s。

七、跳转链接

• GitHub 仓库：https://github.com/deepseek-ai/3fs
• 设计文档：https://github.com/deepseek-ai/3fs/blob/main/docs/design_notes.md
• 部署指南：https://github.com/deepseek-ai/3fs/blob/main/deploy/README.md