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 CLI、MinIO 客户端等工具以及各种语言版本的 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
最后于 更新
Follow us on X
Let's chat on Slack