Goofys 是一款用 Go 语言编写的高性能云存储挂载工具，能够将 AWS S3、Azure Blob、Google Cloud Storage、MinIO 等云对象存储服务挂载为本地文件系统，像使用普通文件夹一样访问云端数据。

特性	说明
高性能	针对云存储特性深度优化，比传统 s3fs 快数倍
多后端支持	AWS S3、Azure Blob、Azure Data Lake、Google Cloud Storage、MinIO、Ceph 等
配置驱动	支持配置文件定义多个挂载点，部署简单
服务模式	支持注册为系统服务，开机自动启动
类 POSIX	兼容大部分常用文件操作

Goofys 追求性能优先，而非完全的 POSIX 兼容。这是因为云对象存储与本地文件系统有本质区别：

• 云存储不支持随机写入 → 仅支持顺序追加写入
• 云存储不存储文件权限 → 通过参数统一指定
• 云存储有网络延迟 → 优化请求减少往返次数

如需本地缓存加速，可配合 catfs 使用。

---

• Linux 或 macOS 操作系统
• FUSE 驱动（Linux 需要安装 fuse 包，macOS 需要安装 osxfuse）
• Go 1.25+（仅从源码编译时需要）

# Linux x86_64
curl -L https://github.com/kahing/goofys/releases/latest/download/goofys -o /usr/local/bin/goofys
chmod +x /usr/local/bin/goofys

# macOS（需要先安装 osxfuse）
brew install goofys

brew cask install osxfuse
brew install goofys

# 确保 Go 1.25+ 已安装
go install github.com/kahing/goofys@latest

创建 AWS 凭证文件 ~/.aws/credentials：

[default]
aws_access_key_id = AKID1234567890
aws_secret_access_key = MY-SECRET-KEY

提示：也支持通过环境变量 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 配置，或使用 AWS CLI 的 aws configure 命令。

# 最简单的方式：直接挂载
goofys bucket-name /mnt/s3

# 挂载带前缀的路径（只挂载特定目录）
goofys bucket-name:prefix /mnt/s3

# 后台运行
goofys bucket-name /mnt/s3 &

# 查看帮助
goofys --help

---

对于生产环境，推荐使用配置文件管理多个挂载点，实现一键部署。

Goofys 会按以下顺序查找配置文件，找到第一个存在的即可：

1. 命令行指定：--config /path/to/config.toml
2. ~/.config/goofys/config.toml
3. ~/.goofys.toml
4. /etc/goofys/config.toml

# 在默认位置生成配置
goofys config init

# 指定路径生成配置
goofys config init /etc/goofys/config.toml

# 验证配置文件是否正确
goofys config validate

# 查看实际使用的配置文件路径
goofys config path

创建 /etc/goofys/config.toml：

# 全局配置
debug = false

# 是否后台运行
# 注意：作为系统服务运行时，此选项无效
detach = true

# 默认文件权限
uid = 1000          # 文件所有者
gid = 1000          # 文件所属组
dir_mode = "0755"   # 目录权限
file_mode = "0644"  # 文件权限

# 挂载选项
mount_options = ["allow_other"]

# ==================== 挂载点定义 ====================

# 第一个挂载点：AWS S3
[mounts.s3]
status = true           # 启用此挂载
backend = "s3"          # 后端类型
bucket = "my-bucket"  # S3 存储桶名称
mount_path = "/mnt/s3"  # 本地挂载路径
# 凭证可通过环境变量或 AWS CLI 配置，此处也可直接指定
# aws_access_key_id = "xxx"
# aws_secret_access_key = "xxx"

# 第二个挂载点：MinIO
[mounts.minio]
status = true
backend = "minio"
bucket = "my-minio-bucket"
mount_path = "/mnt/minio"
endpoint = "https://minio.example.com:9000"
signature_version = "v4"

将 Goofys 注册为系统服务，实现开机自动启动：

# 安装服务（需要 root 权限）
goofys service install /etc/goofys/config.toml

# 启动服务
goofys service start

# 查看服务状态
goofys service status

# 停止服务
goofys service stop

在 /etc/fstab 中添加一行：

goofys#bucket-name    /mnt/s3    fuse    _netdev,allow_other,--file-mode=0666,--dir-mode=0777    0    0

---

[mounts.aws]
backend = "s3"
bucket = "my-bucket"
# 可选：指定区域
# region = "us-west-2"

[mounts.minio]
backend = "minio"
bucket = "my-bucket"
endpoint = "https://minio.example.com:9000"
signature_version = "v4"

[mounts.azure]
backend = "azblob"
bucket = "my-container"
# 推荐通过环境变量配置连接字符串
# connection_string = "xxx"

[mounts.adl]
backend = "adlgen2"
bucket = "my-filesystem"
endpoint = "https://myaccount.dfs.core.windows.net"

[mounts.gcs]
backend = "gcs"
bucket = "my-bucket"
# 使用应用默认凭证（ADC）
# credentials_file = "/path/to/service-account.json"

---

参数	说明	默认值
-f, --foreground	前台运行，不fork到后台	后台运行
--debug	开启调试日志	关闭
--uid	文件所有者用户ID	当前用户
--gid	文件所属组ID	当前用户组
--file-mode	新建文件权限	0644
--dir-mode	新建目录权限	0755
--region	AWS 区域	自动检测
--endpoint	S3 兼容服务地址	AWS S3
--stat-cache-ttl	文件元数据缓存时间	1小时
--type-cache-ttl	文件类型缓存时间	1小时
--profile	AWS 凭证配置名	default

---

在 AWS EC2 m5.4xlarge（us-west-2a）实例上测试，连接到 us-west-2 的 S3 存储桶：

详细测试方法和原始数据见 bench/bench.sh

# 确保 EC2 实例角色有 S3 写入权限
sudo docker run -e BUCKET=$TESTBUCKET -e CACHE=false \
    --rm --privileged --net=host \
    -v /tmp/cache:/tmp/cache kahing/goofys-bench

# 结果会写入 $TESTBUCKET

---

由于云存储与本地文件系统的本质差异，Goofys 存在以下特性：

限制	说明	应对方式
顺序写入	仅支持追加写入，不支持随机 seek	使用追加模式写入
权限模拟	不存储文件权限	使用 --file-mode 参数
无链接	不支持符号链接和硬链接	-
时间戳	ctime、atime 始终等于 mtime	-
目录重命名	无法重命名包含超过 1000 个子项的目录	分批重命名
删除行为	unlink 即使文件不存在也返回成功	-
同步	fsync 被忽略，数据在 close 时刷新	-

---

Q: 挂载后文件权限显示为 root？ A: 使用 --uid 和 --gid 参数指定正确的用户 ID。

Q: 挂载点无法访问，提示 permission denied？ A: 检查 FUSE 是否正确安装，确保当前用户在 fuse 用户组中。

Q: 如何提升文件列表加载速度？ A: 调整缓存参数：goofys --stat-cache-ttl 1h --type-cache-ttl 1h bucket /mnt/s3

Q: 支持哪些 Linux 发行版？ A: 主流发行版均可（Ubuntu、Debian、CentOS、RHEL、Fedora、Arch 等）。

Q: 可以同时挂载多个存储桶吗？ A: 可以，使用配置文件定义多个 [mounts.xxx] 即可。

---

• AWS 官方文档
• AWS SDK for Go
• FUSE 绑定 (jacobsa/fuse)
• gcsfuse - Google Cloud Storage 的 FUSE 实现
• s3fs-fuse - 另一个流行的 S3 文件系统
• catfs - 可与 Goofys 配合使用的缓存层

---

Apache License 2.0

版权所有 (C) 2015 - 2019 Ka-Hing Cheung