Skip to main content

S3 网关

JuiceFS 会将文件分块存储到底层的对象存储中,暴露给用户的往往是 POSIX 接口,而如果你需要同时用 S3 兼容接口访问 JuiceFS 中的文件,就可以用到 S3 网关。其架构图如下:

JuiceFS S3 Gateway architecture

常见的使用场景有:

  • 为 JuiceFS 文件系统暴露 S3 接口,应用可以通过 S3 SDK 访问 JuiceFS 上存储的文件
  • 使用 s3cmd、AWS CLI、MinIO 客户端来方便地访问和操作 JuiceFS 上存储的文件
  • 在跨集群复制数据的场景下,作为集群的统一数据出口,避免跨区访问元数据以提升数据传输性能,详见「使用 S3 网关进行跨区域数据同步」

部署 S3 网关

gateway 命令和 mount 命令类似,会读取 JuiceFS 客户端在本地的配置文件(默认 ~/.juicefs/$VOL_NAME.conf),如果配置文件尚未获取,那么需要先使用 auth 命令对文件系统进行认证,并获取配置文件。

juicefs auth $VOL_NAME --token=xxx --access-key=xxx --secret-key=xxx

JuiceFS S3 网关基于开源的 MinIO 代码实现,因此部署时需要指定 MinIO 相关认证信息:

export MINIO_ACCESS_KEY="admin"
export MINIO_SECRET_KEY="password"

如果未能正确设置,将会遭遇类似 MINIO_ROOT_USER should be specified as an environment variable with at least 3 characters 的报错,注意排查。

认证信息填写完毕,运行 gateway 命令启动网关:

juicefs gateway myjfs 127.0.0.1:8888

启动成功会看到类似下面的输出:

2023/03/21 20:15:49.945403 juicefs[97188] <INFO>: connected to 47.103.20.252:9308 [client.go:874]
2023/03/21 20:15:49.965411 juicefs[97188] <INFO>: Cache: /Users/herald/.juicefs/cache/jfs8 capacity: 102400 MB [disk_cache.go:747]
Endpoint: http://127.0.0.1:8888

Browser Access:
http://127.0.0.1:8888

Object API (Amazon S3 compatible):
Go: https://docs.min.io/docs/golang-client-quickstart-guide
Java: https://docs.min.io/docs/java-client-quickstart-guide
Python: https://docs.min.io/docs/python-client-quickstart-guide
JavaScript: https://docs.min.io/docs/javascript-client-quickstart-guide
.NET: https://docs.min.io/docs/dotnet-client-quickstart-guide

你可以根据需要调整 S3 网关监听的地址和端口,假设你的服务器公网 IP 是 111.2.3.4,你希望能通过互联网开放网关的访问,并绑定 9000 端口,可以这样调整启动命令:

juicefs gateway myjfs 111.2.3.4:9000

JuiceFS 云服务 S3 网关启动成功后,在浏览器中直接访问设置的地址,例如上例中的 http://127.0.0.1:8888,打开网页版文件管理器,输入之前设置的 Access Key 和 Secret Key 登录即可。

另外,还可以使用 AWS CLIMinIO 客户端等工具以及各种语言版本的 S3 SDK 访问 JuiceFS 云服务 S3 网关。

启用 virtual-hosted-style

S3 网关基于开源的 MinIO 代码,因此同样支持 MINIO_DOMAIN 环境变量,可以用他来开启 virtual-hosted-style 支持:

export MINIO_DOMAIN=mydomain.com
juicefs gateway myjfs 111.2.3.4:9000

如果你使用下方的 Helm chart 部署,也可以在 values 中指定 envs 来设置相同的环境变量。

在 Kubernetes 上部署 S3 网关

安装需要 Helm 3.1.0 及以上版本,请参照 Helm 文档进行安装。

helm repo add juicefs https://juicedata.github.io/charts/
helm repo update

Helm chart 同时支持 JuiceFS 社区版和企业版,通过填写 values 中不同的字段来区分具体使用的版本,默认的 values 使用了社区版 JuiceFS 客户端镜像,因此如需使用企业版为例,请在一份单独的 values 文件中单独覆盖以下字段:

values-mycluster.yaml
# values 默认使用社区版 mount 镜像,需要覆盖为商业版
image:
repository: juicedata/mount
tag: "ee-5.0.21-f900c6e"

secret:
name: "myjfs"
# 如果填写了 token 字段,则作为企业版对待,社区版专属的配置会被忽略
token: "xxx"
accessKey: "xxx"
secretKey: "xxx"
提示

别忘了把上方的 values-mycluster.yaml 纳入 Git 项目(或者其他的源码管理方式)管理起来,这样一来,就算 values 的配置不断变化,也能对其进行追溯和回滚。

填写完毕保存,就可以使用下方命令部署了:

# 不论是初次安装,还是后续调整配置重新上线,都可以使用下方命令
helm upgrade --install -f values-mycluster.yaml s3-gateway juicefs/juicefs-s3-gateway

部署完毕以后,按照输出文本的提示,获取 Kubernetes Service 的地址,并测试是否可以正常访问。

对象存储中并没有符号链接这一概念——然而 JuiceFS 却支持符号链接。因此如果你的 JuiceFS 文件系统中包含符号链接,那么将其部署成 S3 网关时,需要注意下方要点。

  • 所有的符号链接,不论相对还是绝对路径,都应指向 JuiceFS 文件系统内的文件(而不是目录)。如果符号链接指向宿主机本地文件系统的文件,或者指向了目录,那么在 S3 网关中将无法解析。

  • 相对路径符号链接可以正常使用,不会在 S3 Gateway 下遇到额外问题。

  • 如果需要在 S3 网关中访问 JuiceFS 文件系统内的绝对路径,那么需要在启动网关的时候修改 --mountpoint 参数,将其指定为挂载点。

    假设挂载点为 /jfs,在 JuiceFS 文件系统里创建了如下符号链接:

    $ ls -alh /jfs
    file.txt -> /jfs/dir/file.txt

    那么需要用如下命令启动网关,确保符号链接可以正常解析:

    juicefs gateway myjfs 127.0.0.1:8888 --mountpoint=/jfs