GeeseFS是一个高性能的、类POSIX的S3（Yandex，Amazon）文件系统，使用Go语言编写

概述

GeeseFS允许您将S3存储桶挂载为文件系统。

基于S3的FUSE文件系统通常存在性能问题，尤其是在处理小文件和元数据操作时。

GeeseFS通过使用积极的并行和异步处理来尝试解决这些问题。

另外，请查看我们的CSI S3驱动（基于GeeseFS）：https://github.com/yandex-cloud/csi-s3

POSIX兼容性矩阵

	GeeseFS	rclone	Goofys	S3FS	gcsfuse
写后读	+	+	-	+	+
部分写入	+	+	-	+	+
截断	+	-	-	+	+
fallocate	+	-	-	-	-
chmod/chown	Y	-	-	+	-
fsync	+	-	-	+	+
符号链接	Y	-	-	+	+
套接字文件	Y	-	-	+	-
设备文件	Y	-	-	-	-
自定义mtime	Y	+	-	+	+
xattr	+	-	+	+	-
目录重命名	+	+	*	+	+
readdir与变更	+	+	-	+	+

Y 仅在使用Yandex S3时正确工作。

* Goofys允许对不超过1000个条目的目录进行重命名，且此限制是硬编码的。

GeeseFS的非POSIX行为/限制列表：

支持文件模式/所有者/组、符号链接、自定义mtime和特殊文件（块/字符设备、命名管道、UNIX套接字），但仅在使用Yandex S3时能正确恢复，因为标准S3在列表中不返回用户元数据，而在标准S3中读取所有这些元数据需要为列表中的每个文件额外进行一次HEAD请求，这会使列表操作变得过慢。
特殊文件支持默认对Yandex S3启用（使用--no-specials禁用），对其他S3禁用。
文件模式/所有者/组默认即使对Yandex S3也是禁用的（使用--enable-perms启用）。禁用时，可以使用--(dir|file)-mode和--(uid|gid)选项设置全局权限。
自定义修改时间默认即使对Yandex S3也是禁用的（使用--enable-mtime启用）。禁用时：
- ctime、atime和mtime始终相同
- 用户无法设置文件修改时间（例如通过cp --preserve、rsync -a或utimes(2)）
不支持硬链接
不支持锁定
不支持"不可见"的已删除文件。如果应用程序在删除文件后保留打开的文件描述符，它将从文件系统操作中获得ENOENT错误

除上述项目外：

默认文件大小限制为1.03 TB，通过将文件分割为1000个5MB部分、1000个25MB部分和8000个125MB部分实现。您可以更改部分大小，但AWS自身的限制无论如何都是5 TB。

稳定性

GeeseFS已经足够稳定，可以通过大多数适用的xfstests测试，包括dirstress/fsstress压力测试（generic/007、generic/011、generic/013）。

另请参阅常见问题。

性能特性

	GeeseFS	rclone	Goofys	S3FS	gcsfuse
并行预读	+	-	+	+	-
并行多部分上传	+	-	+	+	-
随机读取时无预读	+	-	+	-	+
追加时服务器端复制	+	-	-	*	+
更新时服务器端复制	+	-	-	*	-
部分对象更新	+*	-	-	-	-
无额外RTT的xattrs	+*	-	-	-	+
文件查找时目录预加载	+	-	-	-	-
快速递归列表	+	-	*	-	+
异步写入	+	+	-	-	-
异步删除	+	-	-	-	-
异步重命名	+	-	-	-	-
读取的磁盘缓存	+	*	-	+	+
写入的磁盘缓存	+	*	-	+	-

* Goofys的递归列表优化有bug，在某些条件下可能会跳过文件

* S3FS使用服务器端复制，但它仍然会下载整个文件来更新它。而且它也有bug :-)

* rclone mount有VFS缓存，但它只能缓存整个文件。而且它也有bug - 在写入时经常会挂起。

* 无额外RTT的xattrs仅适用于Yandex S3（--list-type=ext-v1）。

部分对象更新(PATCH)仅适用于Yandex S3。

部分对象更新(PATCH)

使用Yandex S3可以进行部分对象更新(仅数据),无需服务器端复制或重新上传。

目前可以通过--enable-patch启用该功能,未来将默认为YC S3启用。

启用补丁上传具有以下优势:

快速fsync:由于无需复制,fsync现在更加高效
支持并发更新
更好的内存利用:需要缓存的中间状态更少,可以为(元)数据缓存使用更多内存
大文件性能更佳

注意:新文件、元数据更改和重命名仍会以分段上传的方式刷新到S3。

安装

预编译二进制文件:
- Linux amd64。你可能还需要先安装FUSE工具(fuse3或fuse RPM/Debian软件包)。
- Mac amd64, arm64。你还需要安装osxfuse/macfuse才能使GeeseFS工作。
- Windows x64。你还需要先安装WinFSP。
或者使用Go 1.13或更高版本从源代码构建:

$ git clone https://github.com/yandex-cloud/geesefs
$ cd geesefs
$ go build

使用方法

$ cat ~/.aws/credentials
[default]
aws_access_key_id = AKID1234567890
aws_secret_access_key = MY-SECRET-KEY
$ $GOPATH/bin/geesefs <bucket> <mountpoint>
$ $GOPATH/bin/geesefs [--endpoint https://...] <bucket:prefix> <mountpoint> # 如果你只想挂载前缀下的对象

你也可以通过AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY环境变量提供凭证。

要在启动时挂载S3存储桶,请确保为root配置了凭证,并在/etc/fstab中添加以下内容:

bucket    /mnt/mountpoint    fuse.geesefs    _netdev,allow_other,--file-mode=0666,--dir-mode=0777    0    0

你也可以通过添加,--shared-config=/path/to/credentials来使用不同路径的凭证文件。

另请参阅:Azure Blob Storage说明。

Windows

安装WinFSP和GeeseFS后,一切都是相同的,只是GeeseFS无法作为守护进程运行,所以如果你想隐藏控制台窗口,需要手动创建系统服务。

你可以将凭证放在C:\Users\<USERNAME>\.aws\credentials中,或者将凭证放在任何文件中并用--shared-config file.txt指定,或者使用环境变量:

set AWS_ACCESS_KEY_ID=...
set AWS_SECRET_ACCESS_KEY=...

然后用geesefs <bucket> <mountpoint>启动GeeseFS,其中<mountpoint>可以是驱动器(如K:)或不存在的目录。例如:

geesefs-win-x64.exe testbucket K:

基准测试

参见bench/README.md。

配置

你可以进行很多调整。使用geesefs -h查看选项列表。

常见问题

内存限制

**0.37.0版本新功能:**元数据缓存内存使用现在也受限制,由元数据引起的OOM错误现在应该不会再出现。

GeeseFS将RAM用于两个目的:

元数据(文件列表)。一个元数据条目使用约1 KB的数据。缓存条目的总数受--entry-limit和--stat-cache-ttl限制,因为未过期的条目不能从缓存中移除。修改过的条目和具有打开的文件/目录描述符的条目也永远不会从缓存中移除。缓存TTL默认为60秒,缓存条目限制默认为100000,但实际上GeeseFS能够更快地列出文件,所以在对一个很长的存储桶进行简单列举时,实际限制将达到约250000。
数据。GeeseFS中默认的数据缓存限制为1 GB(--memory-limit)。GeeseFS在需要从服务器加载数据时使用缓存作为读取缓冲区,在用户应用程序写入数据时使用缓存作为写入缓冲区。

同时,默认的"大"预读设置为100 MB,这对线性读取性能是最优的。

然而,这意味着超过10个进程同时尝试读取大文件可能会超过内存限制,因为它们请求超过1000 MB的缓冲区,在这种情况下,GeeseFS将向其中一些进程返回ENOMEM错误。

你可以通过提高--memory-limit(例如到4 GB)或降低--read-ahead-large(例如到20 MB)来解决这个问题。

最大化吞吐量

如果你有大量可用的网络带宽,想要实现更高的线性写入速度,请确保你正在写入多个文件(而不仅仅是1个),并使用以下选项启动geesefs:

geesefs --no-checksum --memory-limit 4000 \
    --max-flushers 32 --max-parallel-parts 32 --part-sizes 25

这增加了并行性,代价是将最大文件大小减少到250 GB(10000个部分 * 25 MB)并增加内存使用。在有大量可用网络带宽的情况下,你将能够达到约1.6 GB/s的写入速度。例如,使用fio:

fio -name=test -ioengine=libaio -direct=1 -bs=4M -iodepth=1 -fallocate=none \
    -numjobs=8 -group_reporting -rw=write -size=10G

并发更新

GeeseFS 不支持从多个主机同时更新同一文件。如果你尝试这样做,应确保一个主机在修改文件后调用 fsync()，然后至少等待 --stat-cache-ttl (默认1分钟)，再允许其他主机开始更新文件。另一种方法是使用 setfattr -n .invalidate <文件名> 强制刷新文件/目录缓存。这会强制 GeeseFS 从服务器重新检查文件/目录状态。如果不这样做，你可能会遇到丢失更新(冲突)，日志中会以如下方式报告:

main.WARNING 文件 xxx/yyy 在远程被删除或调整大小，丢弃本地更改

并发 PATCH

使用 Yandex S3 时,可以通过 PATCH 方法(--enable-patch)从多个主机同时更新单个对象/文件。然而,并发更改不会报告给客户端,所以你必须停止所有写入并刷新 inode 缓存才能看到其他主机做出的更改。

强烈建议在非重叠范围内写入数据以避免冲突。如果进行重叠写入,则必须确保主机之间协调并串行化更新,在下一次重叠写入之前执行 fsync()。

另外请注意,即使使用 PATCH,最佳性能也是在写入与对象部分边界对齐时实现的(即默认情况下前 5GB 使用 5MB 的块),因为服务器可能会对修补的对象部分进行内部读-修改-写操作,而且如果太多并行请求试图修改同一对象部分,也可能返回错误。这种"PATCH 失败"会在日志中以如下方式报告:

main.WARNING 由于并发更新,无法修补文件 %s (inode %d) 的 %d-%d 范围

通常,GeeseFS 会重试以这种方式失败的请求,但如果你不希望重试,也可以通过启用 --drop-patch-conflicts 选择丢弃缓存的更新。

异步写入错误

GeeseFS 在内存(或启用时的磁盘缓存)中缓冲更新并异步刷新,因此写入者不会从不成功的写入中获得错误。发生错误时,GeeseFS 会将修改保留在缓存中,并稍后重试将其刷新到服务器。GeeseFS 会一直尝试刷新数据,直到成功或你停止 GeeseFS 挂载进程。如果在写入过程中有太多更改的数据且达到内存限制,写入请求会挂起,直到一些数据刷新到服务器以便释放一些内存。

fsync

如果你想确保更改实际上已持久化到服务器,必须对文件或目录调用 fsync。对目录调用 fsync 会使 GeeseFS 刷新其中的所有更改。这比 Linux 和 POSIX 行为更严格,后者在对目录执行 fsync 时只刷新其中的目录条目(即重命名的文件)。

如果在 fsync 期间发生服务器或网络错误,调用者会收到错误代码。

调用 fsync 的示例。注意,目录和文件都应该作为文件打开:

#!/usr/bin/python

import sys, os
os.fsync(os.open(sys.argv[1], os.O_RDONLY))

命令行 sync 工具和 syncfs 系统调用不适用于 GeeseFS,因为它们根本没有在 FUSE 中连接。

故障排除

如果你遇到 GeeseFS 的任何问题 - 如崩溃、挂起或其他异常行为:

如果尚未更新,请更新到最新版本
检查系统日志(syslog/journalctl)和 dmesg 中是否有来自 GeeseFS 的错误消息
尝试在调试模式下启动 GeeseFS: --debug_s3 --debug_fuse --log-file /path/to/log.txt, 重现问题并通过 Issues 或其他方式发送给我们。
如果遇到崩溃,还可以收集核心转储并发送给我们:
- 运行 ulimit -c unlimited
- 使用 sudo sysctl -w kernel.core_pattern=/tmp/core-%e.%p.%h.%t 设置所需的核心转储路径
- 使用 GOTRACEBACK=crash 环境变量启动 geesefs

许可证

根据 Apache License 2.0 版许可

参见 LICENSE 和 AUTHORS

与 S3 的兼容性

geesefs 可用于:

Yandex 对象存储(默认)
Amazon S3
Ceph (以及基于 Ceph 的 Digital Ocean Spaces、DreamObjects、gridscale 等)
Minio
OpenStack Swift
Azure Blob 存储(尽管它不是 S3)
Backblaze B2
Selectel S3

它还应该可以与任何实现了多部分上传和多部分服务器端复制(UploadPartCopy)的 S3 一起工作。

已知不兼容的服务:

CloudFlare R2。他们在限流方面存在问题 - 如果你超过每秒 5 个请求,他们会返回 403 Forbidden 而不是使用 HTTP 429 状态码。

重要提示:如果你将 geesefs 与非 Yandex S3 一起使用,应使用 --list-type 2 或 --list-type 1 选项挂载。

以下后端继承自 Goofys 代码并仍然存在,但已损坏:

Google Cloud Storage
Azure Data Lake Gen1
Azure Data Lake Gen2

参考

Yandex 对象存储
Amazon S3
Amazon SDK for Go
其他相关 fuse 文件系统
- goofys: GeeseFS 是 Goofys 的一个分支。
- s3fs: 另一个流行的 S3 文件系统。
- gcsfuse: Google Cloud Storage 的文件系统。Goofys 从这个项目借鉴了一些框架代码。
S3Proxy
fuse 绑定, gcsfuse 也使用了这个