FastCFS is a shared POSIX file system aimed at database storage

A file system positioned against Ceph

FastCFS is presented as a general distributed file system with strong consistency, high performance, high availability, and support for ten billion massive files. The comparison that appears in the documentation is with Ceph, and it appears twice: once in the main feature list, where the claim is that performance is better than Ceph on the premise of strong data consistency, and once in a benchmark section.

Those claims are the project's own and should be read as such. The benchmark section states that the IOPS ratio of sequential write is 6.x, sequential read is 2.x and random write is about 2.0 against Ceph, and points to a FastCFS versus Ceph benchmark document in the docs directory. The documentation does not describe the hardware, the client configuration or the test methodology behind those figures, so the numbers tell you the direction of the comparison rather than what you would measure on your own cluster.

What is more concrete is the positioning itself. FastCFS is aimed at being the back end storage of databases such as MySQL, PostgreSQL and Oracle, and at K8s, KVM, FTP, SMB and NFS. The topic tags say cloud native and FUSE interface, and the file is POSIX compatible with file locking supported. This is a file system for workloads that need a shared filesystem with ordinary POSIX semantics, not a consumer or backup oriented product.

Trunk file allocation is the answer to random writes

The most interesting engineering claim in the feature list is the one about random write performance: FCFS allocates space based on the trunk file, converting random writes from the client into sequential writes.

That is a specific mechanism rather than a slogan. Databases and virtual machine images are notorious for writing scattered pages, and a file system that lays out space contiguously can serve those writes as sequential I/O. The documentation extends the same reasoning to video monitoring, where smooth writing for multi channel videos with SATA disks is attributed to the sequential writing approach.

The other main features follow a similar logic. High availability is described as no single point and automatic failover. Ease of use is broken down into a simple and efficient architecture with native implementation, independence from third party components, and built in operation and maintenance tools. Full POSIX compatibility with file lock support is what makes it usable as a database directory rather than only as a blob store.

The claim of being independent of third party components is partly about the FUSE based client and partly about the components list, which is a mix of sibling projects from the same author, libfastcommon, libserverframe, libdiskallocator, fastDIR and faststore, each pinned to a specific tag.

Install and deploy is a shell script and a root requirement

There are two installation paths described. The first is the DIY path, where the Cluster Operation Tool is used to deploy FastCFS, with step by step instructions in an INSTALL document, and the recommendation to run libfuse_setup.sh for compiling and installing libfuse.

The second is the easy path, where fastcfs.sh handles compilation, installation and automatic configuration of libfastcommon, libserverframe, fastDIR, faststore and FastCFS. The script pulls or updates those six projects from GitHub, compiles and installs them in dependency order, and generates cluster related configuration files from config templates. The usage lines are short:

* install: pull/update codes from gitee, then make and install
* config: copy config files and configure them with local ip
* start | stop | restart: for service processes control

Getting the source is a single clone:

git clone https://github.com/happyfish100/FastCFS.git; cd FastCFS/

For a single node demo environment there is a one click script, and it must be run by root:

./helloWorld.sh

The equivalent explicit sequence also must be run by root:

./fastcfs.sh install
./fastcfs.sh config --force
./fastcfs.sh restart

Once the services are up, the mounted path shows up in the output of:

df -h /opt/fastcfs/fuse | grep fuse

The root requirement is not incidental. The project ships systemd unit templates in the repository (FastCFS.spec.in, FastCFS-auth.spec.in and FastCFS-vote.spec.in), and a distributed file system with FUSE mounts and background service processes is not something you install as an unprivileged user.

The dependency list is long and version pinned

The requirements section is specific enough to plan against.

For platforms, Linux with kernel version 3.10 or later is supported, with full support and a recommendation of 4.18 or newer. MacOS or FreeBSD is listed as server side only, which is a meaningful limitation if you want to mount the file system on a workstation.

The dependency chain starts with libfuse, version 3.9.4 or newer with 3.16.2 recommended, which itself needs Python 3.5 or newer, Ninja 1.7 or newer and gcc 4.7.0 or newer. Then come four sibling libraries from the same author, each pinned to a tag: libfastcommon at V1.0.88, libserverframe at V1.2.15, libdiskallocator at V1.1.14, and fastDIR and faststore both at V5.5.3.

Those tags are the interesting part. The README declares the current version as V5.5.3, and the dependency pins for fastDIR and faststore match it, which tells you the release artefacts are built in step with the two storage components. The tagged releases in the repository history are older, with V5.4.0 from 2025-04-06, V5.3.2 from 2024-09-25 and V5.1.0 from 2023-12-29. The last push was on 2026-09-19.

Building libfuse from source is called out separately, which suggests the project expects a system where the distribution FUSE version is too old, and where building it means dealing with Python, Ninja and gcc yourself.

The TODO list reads as a change log

Section nine of the README is an unusual document to find in a project README, and it is one of the more revealing parts.

The list is titled a TODO list, but nearly every entry is marked done. The completed items are the ones that describe the consistency and recovery machinery: data recovery after a single disk fault in fstore, rebalancing of the data masters after machine recovery, leader election using the more than half principle to prevent brain split, importing a public vote node in the two copy scenario to prevent brain split, binlog deduplication and historical data deletion, data submission by majority confirmation to ensure data consistency, and an intelligent majority mechanism for the two replica case. There are also entries on POSIX compatibility testing and improvement, a slice storage engine plugin to support massive data with limited memory, adaptation to RDMA networks, and a recycle bin in fdir so an accidental delete is recoverable.

One item is not marked done: cluster online expansion.

Reading a list like this tells you two things about the project. It tells you that the reliability mechanisms were built recently and deliberately, with the brain split problem addressed in two separate ways. And it tells you that expanding a running cluster without downtime is not a solved problem, which for an infrastructure team is a significant gap in a storage system.

The three node roles implied by the systemd unit templates, an auth service, a vote service and the main FastCFS service, match the leader election and voting entries in the list, so the architecture is a small quorum based cluster rather than a peer to peer mesh.

Two integration paths beyond POSIX

The documentation describes how FastCFS is meant to be consumed, and there are two paths that matter for an infrastructure decision.

The first is the FUSE mount. A client mounts the file system and it appears as an ordinary directory, which is why the file lock support and POSIX compatibility claims matter, and why the mount point check in the installation section uses a plain df command on /opt/fastcfs/fuse.

The second is the K8s path, through a separate CSI driver project, fastcfs-csi, maintained alongside the main repository. That driver is what lets a FastCFS cluster serve Kubernetes persistent volumes, which is the deployment shape most cloud native teams would actually want. The project also documents classical application scenes, and those describe the workloads it is meant for rather than a general purpose file share: database storage with two methods, conventional exclusive data and high level shared data, plus database cloudification; file storage for documents, pictures and videos, described as easier to integrate with general software than object storage; unified storage where the database and file storage share a storage cluster to improve resource utilisation; high performance computing; and video monitoring.

The business support section is worth a mention for anyone reading this for a decision. The project offers technical support and customized development and points to a CSDN blog and a WeChat subscription for the fastdfs related articles, which are Chinese only. There is no documented community forum in English, no commercial support contract and no compatibility matrix, so a team outside the Chinese ecosystem is buying into a smaller support net than a Ceph or Gluster deployment would offer.

Where FastCFS is the wrong choice

Four situations rule it out.

The first is S3 style object storage. FastCFS is a filesystem with POSIX semantics, file locks and a FUSE client. If your application wants to PUT and GET objects with a key, a content type and a ranged read, this is the wrong shape of tool, and the documentation's own framing, general software integration versus object storage, points the other way.

The second is a container platform that has already standardised elsewhere. If your organisation runs a CSI driver for its existing storage, adding a second file system means a second operator skill set, a second failure domain and a second thing to page someone about at 3am. The fastcfs-csi driver exists, but the ecosystem around it is the author's, not a vendor's.

The third is a requirement to expand a running cluster. Online expansion is the one item on the TODO list that is not done, and a storage system you cannot grow without downtime is a poor fit for a platform team that expects capacity to arrive continuously.

The fourth is licensing. FastCFS is AGPL-3.0, and for a company that modifies it and serves it over a network, that is a substantially different obligation from the permissive licences of most infrastructure projects. The instruction here is not legal advice, but it is the kind of thing that has to be cleared before a pilot, not after.

There is a real alternative, and it is the comparison the project itself invites. Ceph offers object and block storage, a mature operator ecosystem and a large deployment community, at the cost of the consistency and small dependency profile FastCFS argues for. The honest framing is that FastCFS makes a specific set of trade-offs, mainly around random write performance and a small C codebase, and takes on the operational consequences of a project with a single primary maintainer and a Chinese language support channel.

Editorial conclusion

FastCFS fits an infrastructure team that needs a shared POSIX file system for database data directories, virtual machine images or K8s persistent volumes, and that wants the implementation in C with a small dependency footprint and a FUSE based client rather than a kernel module. It is the wrong choice for a team looking for a drop in object store, for a container environment that has already standardised on an existing CSI driver, or for anyone who cannot accept AGPL-3.0 licensing for a modified or network deployed service. Before adopting it, check three things: that your kernel and FUSE versions meet the documented requirements, that the service topology configured by the tooling matches what you intend to run, and that the failure and recovery behaviour around the leader election and majority commit rules in the documentation matches your durability requirements, since the project describes those mechanisms as recently completed rather than long proven.

Frequently asked questions

Official sources

1. happyfish100/FastCFS on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases