
有些老程序只认本地文件系统,给它一个 S3 端点它读不懂。把它们搬进对象存储的常规做法是改代码接 SDK,代价不小。ZeroFS 走了另一条路:它是一套以 S3 为底的日志结构文件系统,把 RustFS 桶当底层存储,在主机上用 NFS 挂出一棵普通目录树。程序照旧往目录里写文件,ZeroFS 在背后把每一次写翻译成桶里的对象。官方集成目录有这篇指南,下面对着它把链路跑通,再讲清楚它给的是演示、生产里还差什么。
官方那套演示跑的是什么
官方指南用 ZeroFS v2.3.5(镜像 ghcr.io/barre/zerofs)配 rustfs/rustfs-x86-musl:v2.3.1 验证过:建一个桶、生成 zerofs.toml、把 storage 和 aws 两段指到 RustFS、起容器、在 Linux 上 mount 成 NFS、写文件、重启 ZeroFS 再读回来。整条链路是通的,能看到桶里落下 LSM 树的 WAL 和 SST 对象。
它值钱的地方是让你一次看懂"对象存储能不能当文件系统的底"。它没覆盖的是生产里的三件事:镜像版本、耐久性和权限。指南自己写明这是本地集成测试、不适用于生产,跑的是单实例,文件系统进程和 RustFS 之间的信任关系是裸的。下面把这几个缺口逐个补上。
文件在桶里到底是什么形状
ZeroFS 把文件系统操作翻译成一棵存在桶里的 LSM 键值树。写入先进 WAL(预写日志,崩溃后靠它重放),再刷成 SST 段(排序字符串表,只读的数据文件),压实(compaction)在后台把小段并成大段。客户端通过 NFS、9P 或 NBD 看到的就是一棵普通目录树。
这里要先接受一个事实:文件在桶里不是一对一存放的。你在挂载点写的一个 hello.txt,不会变成桶里一个叫 hello.txt 的对象。它会被切成键值写进 WAL 和 SST,落在 zerofs-data/ 下的 compacted/、manifest/、wal/ 三个前缀里。这也是 ZeroFS 能"用对象存储假装成块设备"的原因,它自己管着一套索引。
这个形状带来几个实际后果。第一,别指望直接去桶里找一个文件名然后用 aws s3 cp 取出来读,取到的是 SST 段,不是你的文件,必须通过 ZeroFS 挂载点按 POSIX 路径读。第二,桶里的对象由 ZeroFS 全权管理,手工删改 compacted/ 或 manifest/ 下的东西会破坏文件系统的一致性,等同于直接篡改一台盘的元数据。第三,容量账要按文件系统算而不是按对象数算。一个 8MB 的文件在桶里可能对应好几个 SST 段加日志,对象数量会比文件数多。想真正把桶当普通网盘那样按文件名取对象,得用 s3fs 或 rclone 那类一对一映射的工具,和 ZeroFS 是两种不同用途。
把配置和挂载串起来
先建桶,再用官方镜像生成初始配置:
bash
rc mb rustfs/zerofs-demo
docker run --rm -u root:root -v /opt/zerofs:/cfg -w /cfg \
--entrypoint /bin/sh ghcr.io/barre/zerofs:latest -c "zerofs init"
然后编辑 zerofs.toml,把 storage 和 aws 两段指向 RustFS:
toml
[cache]
dir = "/cache"
disk_size_gb = 5.0
[storage]
url = "s3://zerofs-demo/zerofs-data"
encryption_password = "${ZEROFS_PASSWORD}"
[servers.nfs]
addresses = ["0.0.0.0:2049"]
[servers.rpc]
addresses = ["0.0.0.0:7000"]
[aws]
access_key_id = "${AWS_ACCESS_KEY_ID}"
secret_access_key = "${AWS_SECRET_ACCESS_KEY}"
endpoint = "http://<your-rustfs-endpoint>:9000"
default_region = "us-east-1"
allow_http = "true"
endpoint 和 allow_http 这两个键一起把 ZeroFS 从 AWS 重定向到 RustFS。自定义端点默认走路径风格寻址,不需要额外开关。encryption_password 是文件系统层的加密口令,和 RustFS 那边的服务端加密是两回事,别混。
启动前先处理缓存目录权限,官方镜像以 UID 1001 运行:
bash
mkdir -p /opt/zerofs/cache && chown -R 1001:1001 /opt/zerofs/cache
docker run -d --name zerofs --network oo-rustfs_default -p 2049:2049 \
-e ZEROFS_PASSWORD=<encryption-password> \
-e AWS_ACCESS_KEY_ID=<your-access-key> \
-e AWS_SECRET_ACCESS_KEY=<your-secret-key> \
-v /opt/zerofs/zerofs.toml:/zerofs.toml:ro \
-v /opt/zerofs/cache:/cache \
ghcr.io/barre/zerofs:latest run -c /zerofs.toml
在主机上装 NFS 客户端并挂载。参数里 port=2049 和 mountport=2049 是关键,ZeroFS 把 mountd 流量也放在同一个端口上:
bash
apt-get install -y nfs-common
mkdir -p /mnt/zerofs
mount -t nfs -o async,nolock,rsize=1048576,wsize=1048576,tcp,port=2049,mountport=2049,hard \
127.0.0.1:/ /mnt/zerofs
验证重启后文件还在
挂载点现在就是一棵普通目录树,直接写文件:
bash
echo "written via zerofs nfs mount on rustfs" > /mnt/zerofs/hello.txt
dd if=/dev/urandom of=/mnt/zerofs/data/inner/blob.bin bs=1M count=8
重启前先强制把还没落盘的写刷进桶,否则缓冲区的东西会丢:
bash
docker exec zerofs zerofs flush -c /zerofs.toml
umount /mnt/zerofs
docker restart zerofs
mount -t nfs -o async,nolock,rsize=1048576,wsize=1048576,tcp,port=2049,mountport=2049,hard \
127.0.0.1:/ /mnt/zerofs
cat /mnt/zerofs/hello.txt
sha1sum /mnt/zerofs/data/inner/blob.bin
文件内容完好、哈希对得上,说明数据确实从桶里回放出来了。再列一下桶确认落点:
bash
rc ls rustfs/zerofs-demo/ -r | head -4
看到 zerofs-data/compacted/、manifest/、wal/ 下各有一个 .sst 或 .json 文件就对了。每个文件在桶里都被切成键值写进这几类段文件,重启后 ZeroFS 从 manifest 找到当前有效的段、从 WAL 重放没合并的写,目录树就还原了。这也解释了为什么 flush 之后才能确保最新写入进了桶。没 flush 的内容还停在内存或缓存里,没落到 WAL 对象。
单实例演示和可用之间的差距
官方这套是单实例 NFS 服务,指南明确注明是本地集成测试、不适用于生产。把它往生产推,先要面对的是单点问题:ZeroFS 进程挂了,挂载点就不可用,虽然桶里的对象还在,但客户端读不到。官方后续步骤里提到的基于同一桶的高可用复制,是另一个话题,需要按 ZeroFS 自己的多实例方案来配,不是把容器副本数调成 2 就成。
其次是缓存层的 durability 边界。zerofs.toml 里 cache 的 disk_size_gb 给的是本地缓存盘容量,缓存是可重建的、桶才是真相来源,所以这块盘可以用普通 SSD,但要有足够空间承接 compaction 期间的临时段。缓存打满或写不进去,会以写入报错的形式暴露,排障时先看 /cache 的剩余空间和属主,别急着查网络。
卡住时的几个检查点
挂载失败或卡住,先确认主机装了 nfs-common,再看 ZeroFS 是不是在客户端能到的网络上监听 0.0.0.0:2049。mount 参数里 port 和 mountport 两个都要写 2049,写错一个就挂不上。
启动报 missing field uid,是 zerofs.toml 里出现了 servers.webui 段却没给 uid 和 gid。ZeroFS v2.3.5 要求这一对字段同时存在,补上 uid = 1000、gid = 1000,不需要 Web UI 就把整段删掉。
缓存目录报 Permission denied,是挂载卷之前没改属主,容器里是 UID 1001,重新 chown 一遍再启动。
容器崩溃后写入丢了,是 ZeroFS 会缓冲写入、周期性刷盘。演示环境用上面那条 flush 命令手动刷;要严格耐久性的客户端走 9P 挂载,它的 fsync 会等到数据真正落到稳定存储才返回。
上生产要补的两件事
权限先补。别把根凭证喂给 ZeroFS,在控制台给它单独建一把访问密钥,只授权 zerofs-demo 这一个桶的读写(官方的访问密钥管理页有创建步骤)。ZeroFS 自己还有一层 encryption_password,口令要单独保管,丢了桶里的 LSM 树就解不开。
版本再补。官方指南验证时用的是 ZeroFS v2.3.5 和 rustfs-x86-musl:v2.3.1,当前稳定版是 RustFS 1.0.6(2026-11-15 发布),生产把镜像钉到对应 tag。另外这套文件系统最终落到对象存储上,走的是 S3 基础操作,换版本时用官方的 S3 兼容性说明核对一遍列举、读写、分段上传这几类调用,别默认每个版本都一致。