JuiceFS S3 网关Gateway实战指南架构原理、部署配置与高级功能详解【免费下载链接】juicefsJuiceFS is a distributed POSIX file system built on top of Redis and S3.项目地址: https://gitcode.com/GitHub_Trending/ju/juicefsJuiceFS S3 网关是 JuiceFS 提供的多种访问方式之一它把 JuiceFS 文件系统以 Amazon S3 兼容协议对外暴露让任何支持 S3 API 的 SDK、命令行工具和应用程序都可以直接读写 JuiceFS 上存储的文件。本文以 docs/zh_cn/guide/gateway.md 为主线结合仓库内 cmd/gateway.go、pkg/gateway/gateway.go 与 deploy/juicefs-s3-gateway.yaml 等源码完整讲解 S3 网关的架构原理、快速启动、客户端接入、常用与高级功能IAM 访问控制、桶事件通知等帮助你把它用起来、用好、用对。架构与原理JuiceFS 中的文件以对象形式分块存储到底层对象存储中元数据则由独立的元数据引擎如 Redis管理。JuiceFS 提供了 FUSE POSIX、WebDAV、S3 网关、CSI 驱动等多种访问方式其中 S3 网关是较为常用的一种JuiceFS S3 网关功能是通过 MinIO S3 Gateway 实现的利用 MinIO 的object接口将 JuiceFS 文件系统作为 MinIO 服务器的后端存储从而提供接近原生 MinIO 的使用体验同时继承 MinIO 的许多高级功能。在这种架构中JuiceFS 就相当于 MinIO 实例的一块本地磁盘原理与minio server /data1命令类似。从源码看这一设计在 pkg/gateway/gateway.go 中实现为jfsObjects结构体它实现了 MinIO 的ObjectLayer接口NewJFSGateway返回minio.ObjectLayer网关启动时由 cmd/gateway.go 将 JuiceFS 文件系统实例jfs包装为jfsGateway并交给 MinIO 服务进程处理 S3 请求。JuiceFS S3 网关的常见使用场景有为 JuiceFS 开放 S3 接口应用可以通过 S3 SDK 访问 JuiceFS 上存储的文件使用 S3 客户端使用 s3cmd、AWS CLI、MinIO 客户端mc方便地访问和操作 JuiceFS 上存储的文件管理 JuiceFS 中的文件S3 网关提供了基于网页的文件管理器可以在浏览器中直接管理 JuiceFS 中的文件集群复制在跨集群复制数据的场景下作为集群的统一数据出口避免跨区访问元数据以提升数据传输性能详见「使用 S3 网关进行跨区域数据同步」。快速开始启动 S3 网关需要一个已经创建完毕的 JuiceFS 文件系统如果尚不存在请参考独立使用文档创建。下方假定元数据引擎 URL 为redis://localhost:6379/1。设置管理员凭证由于网关基于 MinIO 开发因此需要先设置MINIO_ROOT_USER和MINIO_ROOT_PASSWORD两个环境变量它们会成为访问 S3 API 时认证身份用的 Access Key 和 Secret Key是拥有最高权限的管理员凭证export MINIO_ROOT_USERadmin export MINIO_ROOT_PASSWORD12345678 # Windows 用户请改用 set 命令设置环境变量 set MINIO_ROOT_USERadmin注意MINIO_ROOT_USER的长度至少 3 个字符MINIO_ROOT_PASSWORD的长度至少 8 个字符。这一限制在源码 cmd/gateway.go 中有明确校验——未正确设置时会直接报错退出例如MINIO_ROOT_USER should be specified as an environment variable with at least 3 characters注意排查。启动 S3 网关# 第一个参数是元数据引擎的 URL第二个是 S3 网关监听的地址和端口 juicefs gateway redis://localhost:6379/1 localhost:9000 # 从 v1.2 开始S3 网关支持后台启动追加 --background 或 -d 参数均可 # 后台运行场景下使用 --log 指定日志输出文件路径 juicefs gateway redis://localhost:6379 localhost:9000 -d --log/var/log/juicefs-s3-gateway.logS3 Gateway 默认没有启用多桶支持可以添加--multi-buckets选项开启。还可以添加其他选项优化 S3 网关比如将默认的本地缓存设置为 20 GiB--cache-size单位为 MiB20480 MiB ≈ 20 GiBjuicefs gateway --cache-size 20480 redis://localhost:6379/1 localhost:9000在这个例子中假设 JuiceFS 文件系统使用的是本地 Redis 数据库。当 S3 网关启用后在当前主机上可以使用http://localhost:9000访问 S3 网关的管理界面一个基于网页的文件管理器如果你希望通过局域网或互联网上的其他主机访问 S3 网关则需要调整监听地址例如juicefs gateway redis://localhost:6379/1 0.0.0.0:9000这样一来S3 网关将默认接受所有网络请求。不同位置的 S3 客户端可以使用不同的地址访问S3 网关所在主机中的第三方客户端可使用http://127.0.0.1:9000或http://localhost:9000访问与 S3 网关所在主机处于同一局域网的第三方客户端可使用http://192.168.1.8:9000访问假设网关主机内网 IP 为 192.168.1.8通过互联网访问可使用http://110.220.110.220:9000假设网关主机公网 IP 为 110.220.110.220。访问 S3 网关各类支持 S3 API 的客户端、桌面程序、Web 程序都可以访问 JuiceFS S3 网关。使用时请注意 S3 网关监听的地址和端口。以下示例均假设使用第三方客户端访问本地主机上运行的 S3 网关实际场景请根据情况调整访问地址。使用 AWS CLI下载并安装 AWS CLI 后执行配置$ aws configure AWS Access Key ID [None]: admin AWS Secret Access Key [None]: 12345678 Default region name [None]: Default output format [None]:程序会以交互方式引导你完成新配置的添加其中Access Key ID与MINIO_ROOT_USER相同Secret Access Key与MINIO_ROOT_PASSWORD相同区域名称和输出格式留空即可。之后即可使用aws s3命令访问 JuiceFS 存储例如# 列出所有 bucket $ aws --endpoint-url http://localhost:9000 s3 ls # 列出 bucket 中的对象 $ aws --endpoint-url http://localhost:9000 s3 ls s3://bucket使用 MinIO 客户端mc为避免兼容性问题推荐使用RELEASE.2021-04-22T17-40-00Z版本的 mc。下载安装完成后添加一个新的 aliasmc alias set juicefs http://localhost:9000 admin 12345678然后可以通过 mc 客户端在本地磁盘、JuiceFS 存储以及其他云存储之间自由进行文件和文件夹的复制、移动、增删等管理操作$ mc ls juicefs/jfs [2021-10-20 11:59:00 CST] 130KiB avatar-2191932_1920.png [2021-10-20 11:59:00 CST] 4.9KiB box-1297327.svg [2021-10-20 11:59:00 CST] 21KiB cloud-4273197.svg [2021-10-20 11:59:05 CST] 17KiB hero.svg [2021-10-20 11:59:06 CST] 1.7MiB hugo-rocha-qFpnvZ_j9HU-unsplash.jpg常用功能多桶支持默认情况下juicefs gateway只允许一个 bucketbucket 名字为文件系统名字。如果需要多个桶可以在启动时添加--multi-buckets开启多桶支持该参数会把 JuiceFS 文件系统顶级目录下的每个子目录都导出为一个 bucket创建 bucket 的行为在文件系统上的反映就是顶级目录下创建了一个同名子目录juicefs gateway redis://localhost:6379/1 localhost:9000 --multi-buckets这一行为在源码 pkg/gateway/gateway.go 的MakeBucketWithLocation中实现开启MultiBucket时创建 bucket 会直接调用n.fs.Mkdir在文件系统顶级目录下建立同名目录isValidBucketNamepkg/gateway/gateway.go则保证在未开启多桶时只有文件系统名对应的 bucket 合法。保留 ETag默认 S3 网关不会保存和返回对象的 ETag 信息可以通过--keep-etag开启juicefs gateway myjfs localhost:9000 --keep-etag开启后通过网关上传到 JuiceFS 的文件就可以用 S3 API 的head-object获取 ETag 了aws s3api --endpointhttp://localhost:9000 head-object --bucket myjfs --key test123/test.etag { AcceptRanges: bytes, LastModified: Wed, 23 Apr 2025 00:17:16 GMT, ContentLength: 7, ETag: \d2fde576f44a6601b73201234b491904\, ContentType: application/octet-stream, Metadata: {} }这个 ETag 通过 MD5 算法生成并以 key 为s3-etag的扩展属性xattr写入文件——对应源码中的常量const s3Etag s3-etagpkg/gateway/gateway.go。如果你使用--enable-xattr挂载 JuiceFS也可以用getfattr获取这个 ETaggetfattr -n s3-etag test.etag # file: test.etag s3-etagd2fde576f44a6601b73201234b491904开启对象标签默认不支持对象标签可以通过--object-tag开启。标签数据同样以 xattrkey 为s3-tags对应源码 pkg/gateway/gateway.go保存在文件中并在上传、分片合并等环节被读写见 pkg/gateway/gateway.go 的PutObjectTags/GetObjectTags/DeleteObjectTags实现。开启对象元数据v1.3 起默认不支持对象元数据可以通过--object-meta开启。源码中对象元数据以s3-meta为 xattr keypkg/gateway/gateway.go保存存储时仅保留x-amz-meta-前缀的用户自定义元数据以及cache-control、content-disposition、content-type这几个系统元数据见s3UserControlledSystemMeta与setObjMetapkg/gateway/gateway.go。启用虚拟主机风格请求默认情况下S3 网关支持格式为http://mydomain.com/bucket/object的路径类型请求。MINIO_DOMAIN环境变量用于启用虚拟主机类型请求如果请求的Host头信息匹配(.).mydomain.com则匹配的模式$1被用作 bucket路径被用作 object。例如export MINIO_DOMAINmydomain.com命令行也提供了等价的--domain参数启动时如果设置了该参数cmd/gateway.go 会把它写入MINIO_DOMAIN环境变量再启动 MinIO 服务。调整 IAM 刷新时间默认 IAM 缓存的刷新时间为 5 分钟对应 cmd/gateway.go 中--refresh-iam-interval的默认值5m可以通过--refresh-iam-interval调整。该参数的值是一个带单位的时间字符串例如300ms、-1.5h或2h45m有效时间单位是ns、us或µs、ms、s、m、h。设置后会被写入MINIO_REFRESH_IAM_INTERVAL环境变量cmd/gateway.go。例如设置 1 分钟刷新juicefs gateway xxxx xxxx --refresh-iam-interval 1m多 Gateway 实例JuiceFS 的分布式特性使得可以在多个节点上同时启动多个 S3 网关实例以提高可用性和性能。这种情况下每个 S3 网关实例独立处理请求但它们都访问同一个 JuiceFS 文件系统需要注意以下几点所有实例启动时需要使用相同的用户其 UID 和 GID 相同节点之间 IAM 刷新时间可以不同但要保证 IAM 刷新时间不要太短以免对 JuiceFS 造成过大压力每个实例的监听地址和端口可以自由设置如果在同一台机器上启动多个实例需要确保端口不冲突。以守护进程的形式运行S3 网关可以通过 systemd 以 Linux 守护进程的形式在后台运行cat /lib/systemd/system/juicefs-gateway.serviceEOF [Unit] DescriptionJuicefs S3 Gateway Requiresnetwork.target Aftermulti-user.target StartLimitIntervalSec0 [Service] Typesimple Userroot EnvironmentMINIO_ROOT_USERadmin EnvironmentMINIO_ROOT_PASSWORD12345678 ExecStart/usr/local/bin/juicefs gateway redis://localhost:6379 localhost:9000 Restarton-failure RestartSec60 [Install] WantedBymulti-user.target EOF设置进程开机自启动systemctl daemon-reload systemctl enable juicefs-gateway --now systemctl status juicefs-gateway检阅进程日志journalctl -xefu juicefs-gateway.service在 Kubernetes 上部署 S3 网关安装需要 Helm 3.1.0 及以上版本helm repo add juicefs https://juicedata.github.io/charts/ helm repo updateHelm chart 同时支持 JuiceFS 社区版和企业版通过填写 values 中不同的字段来区分使用的版本。编辑values-mycluster.yamlsecret: name: name metaurl: meta-url storage: storage-type accessKey: access-key secretKey: secret-key bucket: bucket建议把values-mycluster.yaml纳入 Git或其他的源码管理方式管理这样即使 values 配置不断变化也能对其进行追溯和回滚。填写完毕保存后即可部署# 不论是初次安装还是后续调整配置重新上线都可以使用下方命令 helm upgrade --install -f values-mycluster.yaml s3-gateway juicefs/juicefs-s3-gateway部署完毕后按照输出文本的提示获取 Kubernetes Service 的地址并测试访问$ kubectl -n kube-system get svc -l app.kubernetes.io/namejuicefs-s3-gateway NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE juicefs-s3-gateway ClusterIP 10.101.108.42 none 9000/TCP 142m部署完成后会启动一个名为juicefs-s3-gateway的 Deployment查看其 Pod$ kubectl -n kube-system get po -l app.kubernetes.io/namejuicefs-s3-gateway NAME READY STATUS RESTARTS AGE juicefs-s3-gateway-5c69d574cc-t92b6 1/1 Running 0 136m仓库中还提供了一个不依赖 Helm 的 Kubernetes 部署清单 deploy/juicefs-s3-gateway.yaml它使用initContainers先执行juicefs format初始化文件系统再以juicefs gateway ${METAURL} ${NODE_IP}:9000启动网关同时暴露 9000 端口S3 服务与 9567 端口监控指标凭证通过 Secret 注入可作为参考模板。高级功能JuiceFS S3 网关的核心功能是对外提供 S3 接口目前对 S3 协议的支持已经比较完善。在 v1.2 版本中又添加了身份和访问控制IAM和桶事件通知的支持。这些高级功能要求 mc 客户端的版本为RELEASE.2021-04-22T17-40-00Z。如果你不知道有哪些功能或某个功能如何使用可以在子命令后加-h查看帮助说明。身份和访问控制IAM普通用户在 v1.2 版本之前juicefs gateway只在启动时创建一个超级用户该超级用户只属于这个进程——即使多个 gateway 背后是同一个文件系统其用户也是进程间隔离的可以为每个 gateway 进程设置不同的超级用户相互独立、互不影响。在 v1.2 版本之后juicefs gateway启动时仍需要设置超级用户仍为进程隔离但允许使用mc admin user add添加新的用户新添加的用户将是同文件系统共享的。可以使用mc admin user进行管理支持添加、关闭、启用、删除用户也支持查看所有用户、展示用户信息以及查看用户的策略$ mc admin user -h NAME: mc admin user - manage users USAGE: mc admin user COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] COMMANDS: add add a new user disable disable user enable enable user remove remove user list list all users info display info of a user policy export user policies in JSON format svcacct manage service accounts例如添加用户# 添加新用户 $ mc admin user add myjfs user1 admin123 # 查看当前用户 $ mc admin user list myjfs enabled user1 # 以 JSON 格式查看用户信息 $ mc admin user list myjfs --json { status: success, accessKey: user1, userStatus: enabled }服务账户服务账户service accounts的作用是为现有用户创建一个相同权限的副本让不同的应用可以使用独立的访问密钥。服务账户的权限继承自父用户可以通过mc admin user svcacct命令管理$ mc admin user svcacct -h NAME: mc admin user svcacct - manage service accounts USAGE: mc admin user svcacct COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] COMMANDS: add add a new service account ls List services accounts rm Remove a service account info Get a service account info set edit an existing service account enable Enable a service account disable Disable a services account服务账户会从主账户继承权限并保持与主账户权限一致且服务账户不可以直接附加权限策略。比如为名为user1的用户创建一个名为svcacct1的服务账户mc admin user svcacct add myjfs user1 --access-key svcacct1 --secret-key 123456abc如果user1是只读权限那么svcacct1也是只读权限若想让svcacct1拥有其他权限需要调整user1的权限。AssumeRole 安全令牌服务S3 网关安全令牌服务STS可让客户端请求临时凭证访问网关资源。临时凭证的工作原理与默认管理员凭证几乎相同但有两个不同点临时凭证是短期的可以配置为持续几分钟到几小时不等过期后 S3 网关不再识别它们不允许使用它们进行任何 API 请求访问临时凭证不需要与应用程序一起存储它们动态生成并在请求时提供给应用程序过期后应用可以请求新的凭证。AssumeRole需要现有网关用户的授权凭据返回的临时安全凭证包括访问密钥、秘密密钥和安全令牌应用于这些临时凭据的策略继承自网关用户凭据。默认有效期为 1 小时可通过可选参数DurationSeconds指定取值范围 90015 分钟到 6048007 天。API 请求参数Version指示 STS API 版本信息唯一支持的值是2011-06-15出于兼容性原因借用自 AWS STS API 文档。类型为 String必填。AUTHPARAMS指示 STS API 授权信息支持 AWS Signature V4 签名授权。DurationSeconds持续时间秒取值范围 90015 分钟至 6048007 天超出则操作失败默认 3600 秒。类型为 Integer可选。PolicyJSON 格式的 IAM 内联会话策略可选。生成会话的权限是预设策略名称和此处设置的策略集合的交集不能用该策略授予比被假定预设策略名称允许的更多权限。最小长度为 1最大长度为 2048。POST 请求示例http://minio:9000/?ActionAssumeRoleDurationSeconds3600Version2011-06-15Policy{Version:2012-10-17,Statement:[{Sid:Stmt1,Effect:Allow,Action:s3:*,Resource:arn:aws:s3:::*}]}AUTHPARAMS响应示例?xml version1.0 encodingUTF-8? AssumeRoleResponse xmlnshttps://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleResult AssumedRoleUser Arn/ AssumeRoleId/ /AssumedRoleUser Credentials AccessKeyIdY4RJU1RNFGK48LGO9I2S/AccessKeyId SecretAccessKeysYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg/SecretAccessKey Expiration2019-08-08T20:26:12Z/Expiration SessionTokeneyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.../SessionToken /Credentials /AssumeRoleResult ResponseMetadata RequestIdc6104cbe-af31-11e0-8154-cbc7ccf896c7/RequestId /ResponseMetadata /AssumeRoleResponse使用 AWS CLI 请求 AssumeRole启动 S3 网关并创建名为foobar的用户配置 AWS CLI[foobar] region us-east-1 aws_access_key_id foobar aws_secret_access_key foo12345使用 AWS CLI 请求 AssumeRole API。注意--role-arn和--role-session-name对 S3 网关没有意义可以设置为满足命令行要求的任意值$ aws --profile foobar --endpoint-url http://localhost:9000 sts assume-role --policy {Version:2012-10-17,Statement:[{Sid:Stmt1,Effect:Allow,Action:s3:*,Resource:arn:aws:s3:::*}]} --role-arn arn:xxx:xxx:xxx:xxxx --role-session-name anything { AssumedRoleUser: { Arn: }, Credentials: { SecretAccessKey: xbnWUoNKgFxiuv3RI9UgqP3tULQMdIHj4psd4, SessionToken: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..., Expiration: 2019-02-20T19:56:59-08:00, AccessKeyId: K9DTIMUVZXEXJL3ATUOY } }Go 应用程序可参考 MinIO 官方的 assume-role 示例程序实现。注意环境变量设置的超级用户无法使用 AssumeRole API只有通过mc admin user add添加的用户才能使用。权限管理默认新创建的用户没有任何权限需要使用mc admin policy赋权后才可使用。该命令支持权限的增删改查以及为用户添加、删除、更新权限$ mc admin policy -h NAME: mc admin policy - manage policies defined in the MinIO server USAGE: mc admin policy COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] COMMANDS: add add new policy remove remove policy list list all policies info show info on a policy set set IAM policy on a user or group unset unset an IAM policy for a user or group update Attach new IAM policy to a user or groupS3 网关内置了以下 4 种常用策略readonly只读用户readwrite可读写用户writeonly只写用户consoleAdmin可读可写可管理可管理指可以调用管理 API比如创建用户等。例如设置某个用户为只读# 设置 user1 为只读 $ mc admin policy set myjfs readonly useruser1 # 查看用户策略 $ mc admin user list myjfs enabled user1 readonly如需自定义策略可以使用mc admin policy add$ mc admin policy add -h NAME: mc admin policy add - add new policy USAGE: mc admin policy add TARGET POLICYNAME POLICYFILE POLICYNAME: Name of the canned policy on MinIO server. POLICYFILE: Name of the policy file associated with the policy name. EXAMPLES: 1. Add a new canned policy writeonly. $ mc admin policy add myjfs writeonly /tmp/writeonly.json策略文件必须是 JSON 格式、具有 IAM 兼容语法且不超过 2048 个字符。该语法可以实现更精细化的访问控制如果不熟悉可以先用下面的命令查看内置策略并在此基础上修改$ mc admin policy info myjfs readonly { Version: 2012-10-17, Statement: [ { Effect: Allow, Action: [ s3:GetBucketLocation, s3:GetObject ], Resource: [ arn:aws:s3:::* ] } ] }用户组管理JuiceFS S3 网关支持创建用户组类似于 Linux 用户组的概念使用mc admin group管理。可以把一个或多个用户设置为一个组然后为组统一赋权用法与用户管理类似$ mc admin group -h NAME: mc admin group - manage groups USAGE: mc admin group COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] COMMANDS: add add users to a new or existing group remove remove group or members from a group info display group info list display list of groups enable enable a group disable disable a group匿名访问管理如果希望特定的对象或桶可以被任何人访问可以使用mc policy命令配置匿名访问策略Name: mc policy - manage anonymous access to buckets and objects USAGE: mc policy [FLAGS] set PERMISSION TARGET mc policy [FLAGS] set-json FILE TARGET mc policy [FLAGS] get TARGET mc policy [FLAGS] get-json TARGET mc policy [FLAGS] list TARGET PERMISSION: Allowed policies are: [none, download, upload, public]. FILE: A valid S3 policy JSON filepath.S3 网关默认内置 4 种匿名权限none不允许匿名访问一般用来清除已有权限download允许任何人读取upload允许任何人写入public允许任何人读写。例如设置一个允许匿名下载的对象# 设置 testbucket1/afile 为匿名访问 mc policy set download useradmin/testbucket1/afile # 查看具体权限 mc policy get-json useradmin/testbucket1/afile $ mc policy --recursive links useradmin/testbucket1/ http://127.0.0.1:9001/testbucket1/afile # 直接下载该对象 wget http://127.0.0.1:9001/testbucket1/afile # 清除 afile 的 download 权限 mc policy set none useradmin/testbucket1/afile配置生效时间JuiceFS S3 网关的所有管理 API 更新操作都会立即生效并持久化到 JuiceFS 文件系统中接受该 API 请求的客户端也会立即生效。但多机运行时情况有所不同S3 网关在处理请求鉴权时会直接采用内存缓存信息作为校验基准避免每次请求都读取配置带来的不可接受的性能问题。目前缓存刷新策略是每 5 分钟强制更新内存缓存部分操作也会触发缓存更新保证多机情况下配置生效最长不超过 5 分钟可以通过--refresh-iam-interval参数调整。如果希望某个 S3 网关立即生效可以手动重启它。生成预签名 URLJuiceFS S3 网关支持使用mc share命令管理存储桶上对象的预签名 URL用于下载和上传对象。使用详情可参考 mc 命令的帮助信息。桶事件通知桶事件通知功能可以用来监视存储桶中对象上发生的事件从而触发一些行为。目前支持的对象事件类型有s3:ObjectCreated:Puts3:ObjectCreated:CompleteMultipartUploads3:ObjectAccessed:Heads3:ObjectCreated:Posts3:ObjectRemoved:Deletes3:ObjectCreated:Copys3:ObjectAccessed:Get支持的全局事件有s3:BucketCreateds3:BucketRemoved可以使用 mc 客户端工具通过 event 子命令设置和监听事件通知。MinIO 发送的用于发布事件的通知消息是 JSON 格式的。JuiceFS S3 网关为减少依赖裁剪了部分事件目标类型目前存储桶事件支持发布到以下目标RedisMySQLPostgreSQLWebHooks$ mc admin config get myjfs | grep notify notify_webhook publish bucket notifications to webhook endpoints notify_mysql publish bucket notifications to MySQL databases notify_postgres publish bucket notifications to Postgres databases notify_redis publish bucket notifications to Redis datastores以下示例假设 JuiceFS 文件系统名为images启用 S3 Gateway 服务后在 mc 中定义其别名为myjfs。对于 S3 Gateway 而言JuiceFS 文件系统名images就是一个存储桶名。使用 Redis 发布事件Redis 事件目标支持两种格式namespace和access。使用namespace格式时S3 网关将存储桶里的对象同步成 Redis hash 中的条目每个条目对应存储桶里的一个对象key 设为存储桶名称/对象名称value 是该网关对象的 JSON 格式事件数据。对象更新或删除时hash 中对应条目也会相应更新或删除。使用access格式时网关使用RPUSH将事件添加到 list 中每个元素是一个 JSON 格式的 list包含两个元素——时间戳字符串以及含有该存储桶操作事件数据的 JSON 对象。此格式下 list 中的元素不会更新或删除。配置与验证步骤配置 Redis 到 S3 网关使用mc admin config set命令配置 Redis 为事件通知目标# 命令行参数 # mc admin config set myjfs notify_redis[:name] addressxxx formatnamespace|access keyxxxx passwordxxxx queue_dir queue_limit0 # 具体举例 $ mc admin config set myjfs notify_redis:1 address127.0.0.1:6379/1 formatnamespace keybucketevents passwordyoursecret queue_dir queue_limit0可通过mc admin config get myjfs notify_redis查看配置项$ mc admin config get myjfs notify_redis notify_redis enableoff formatnamespace address key password queue_dir queue_limit0各配置项含义notify_redis[:name] 支持设置多个 redis只需 name 不同即可 address* (address) Redis 服务器的地址。例如localhost:6379 key* (string) 存储/更新事件的 Redis keykey 会自动创建 format* (namespace*|access) 是 namespace 还是 access默认是 namespace password (string) Redis 服务器的密码 queue_dir (path) 未发送消息的暂存目录例如 /home/events queue_limit (number) 未发送消息的最大限制默认是 100000 comment (sentence) 可选的注释说明S3 网关支持持久事件存储持久存储会在 Redis broker 离线时备份事件并在其恢复在线时重播事件。事件存储目录通过queue_dir设置最大限制通过queue_limit设置。更新配置前可先用mc admin config get获取当前配置更新后需要手动重启JuiceFS S3 网关使配置生效mc admin service restart暂不受支持。重启后网关启动时会输出类似SQS ARNs: arn:minio:sqs::1:redis的信息。可以添加任意多个 Redis 目标只需为每个实例提供不同的标识符如上例notify_redis:1中的 1。启用 bucket 通知在名为images的存储桶上开启事件通知需要使用上一步输出的 ARN 信息mc event add myjfs/images arn:minio:sqs::1:redis --suffix .jpg mc event list myjfs/images arn:minio:sqs::1:redis s3:ObjectCreated:*,s3:ObjectRemoved:*,s3:ObjectAccessed:* Filter: suffix.jpg验证 Redis启动redis-cli并运行 monitor 命令查看网关在 Redis 上执行的操作redis-cli -a yoursecret 127.0.0.1:6379 monitor OK上传一个名为myphoto.jpg的文件到images存储桶mc cp myphoto.jpg myjfs/images回到 monitor 终端即可看到namespace格式下的 HSET 操作127.0.0.1:6379 monitor OK 1712562516.867831 [1 192.168.65.1:59280] hset bucketevents images/myphoto.jpg {\Records\:[...]}如果使用access格式则看到的是 RPUSH 操作127.0.0.1:6379 monitor OK 1712562751.922469 [1 192.168.65.1:61102] rpush aceesseventskey [{\Event\:[...]}]使用 MySQL 发布事件MySQL 通知目标支持namespace和access两种格式namespace格式下S3 网关将存储桶里的对象同步成数据库表中的行每行有两列key_name存储桶名加对象名和valueJSON 格式事件数据对象更新或删除时表中相应行也会更新或删除。access格式下网关将事件添加到表中行有两列event_time事件发生时间和event_dataJSON 格式事件数据此格式下不会有行被删除或修改。配置步骤以namespace为例确保 MySQL 版本满足最低要求JuiceFS S3 网关要求 MySQL 5.7.8 及以上因为使用了该版本引入的 JSON 数据类型。配置 MySQL 到 S3 网关mc admin config set myjfs notify_mysql:myinstance tableminio_images dsn_stringroot:123456tcp(172.17.0.1:3306)/miniodb查看配置项$ mc admin config get myjfs notify_mysql formatnamespace dsn_string table queue_dir queue_limit0 max_open_connections2各配置项含义notify_mysql[:name] 发布存储桶通知到 MySQL 数据库需要多个 endpoint 时可为每个配置添加用户指定的 name如 notify_mysql:myinstance ARGS: dsn_string* (string) MySQL 数据源名称连接字符串格式为 user:passwordtcp(host:port)/database必填 table* (string) 存储/更新事件的数据库表名表会自动创建 format* (namespace*|access) namespace 或 access默认是 namespace queue_dir (path) 未发送消息的暂存目录例如 /home/events queue_limit (number) 未发送消息的最大限制默认是 100000 comment (sentence) 可选的注释说明同样支持持久事件存储。更新配置并重启网关后启动时会输出类似SQS ARNs: arn:minio:sqs::myinstance:mysql的信息。启用 bucket 通知# 使用 MySQL ARN 在 images 存储桶上添加通知配置--suffix 参数用于过滤事件 mc event add myjfs/images arn:minio:sqs::myinstance:mysql --suffix .jpg # 打印 images 存储桶上的通知配置 mc event list myjfs/images arn:minio:sqs::myinstance:mysql s3:ObjectCreated:*,s3:ObjectRemoved:*,s3:ObjectAccessed:* Filter: suffix.jpg验证 MySQL上传一张 JPEG 图片到images存储桶然后在 MySQL 终端列出minio_images表的所有记录即可看到刚插入的记录。使用 PostgreSQL 发布事件整体方法与使用 MySQL 相同不再赘述。需要注意的是该功能要求 PostgreSQL 9.5 及以上版本S3 网关使用了 PostgreSQL 9.5 引入的INSERT ON CONFLICT即 UPSERT特性以及 9.4 引入的jsonb数据类型。使用 Webhook 发布事件Webhook 采用推的方式获取数据而不是一直去拉取。配置 webhook 到 S3 网关notify_webhook[:name] 发布存储桶通知到 webhook endpoints ARGS: endpoint* (url) webhook server endpoint例如 http://localhost:8080/minio/events auth_token (string) opaque token 或者 JWT authorization token queue_dir (path) 未发送消息的暂存目录例如 /home/events queue_limit (number) 未发送消息的最大限制默认是 100000 client_cert (string) Webhook 的 mTLS 身份验证的客户端证书 client_key (string) Webhook 的 mTLS 身份验证的客户端证书密钥 comment (sentence) 可选的注释说明用mc admin config set更新配置endpoint 是监听 webhook 通知的服务地址mc admin config set myjfs notify_webhook:1 queue_limit0 endpointhttp://localhost:3000 queue_dir保存配置并重启服务让配置生效重启时 endpoint 必须是启动且可访问的。启用 bucket 通知此处 ARN 值为arn:minio:sqs::1:webhookmc mb myjfs/images-thumbnail mc event add myjfs/images arn:minio:sqs::1:webhook --event put --suffix .jpg如果 mc 报告无法创建 Bucket请检查 S3 Gateway 是否启用了多桶支持。采用 Thumbnailer 进行验证Thumbnailer 是一个使用 MinIOlistenBucketNotificationAPI 的缩略图生成器示例项目JuiceFS 用它监听 S3 网关通知——文件上传到网关后Thumbnailer 监听到该通知、生成缩略图并上传回网关。安装并启动 Thumbnailergit clone https://github.com/minio/thumbnailer/ npm install打开其config/webhook.json配置文件添加 MinIO server 配置然后启动NODE_ENVwebhook node thumbnail-webhook.jsThumbnailer 运行在http://localhost:3000/。按前述步骤配置好 webhook 通知后上传一张图片mc cp ~/images.jpg myjfs/images .../images.jpg: 8.31 KB / 8.31 KB ┃▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓┃ 100.00% 59.42 KB/s 0s稍等片刻后用mc ls检查存储桶内容即可看到生成的缩略图mc ls myjfs/images-thumbnail [2017-02-08 11:39:40 IST] 992B images-thumbnail.jpg小结JuiceFS S3 网关基于 MinIO S3 Gateway 构建把 JuiceFS 文件系统以标准 S3 协议暴露给任意 S3 客户端兼顾了 POSIX 语义与对象存储生态的兼容性。本文覆盖了从架构原理、快速启动、AWS CLI / mc 客户端接入到多桶、ETag、对象标签与元数据、虚拟主机风格请求、IAM 刷新时间、多实例与 systemd / Kubernetes 部署等常用功能并深入讲解了 v1.2 起提供的 IAM 访问控制用户、服务账户、AssumeRole STS、策略、用户组、匿名访问与桶事件通知Redis / MySQL / PostgreSQL / Webhook等高级能力。相关底层实现可在 cmd/gateway.go 与 pkg/gateway/gateway.go 中进一步研读。【免费下载链接】juicefsJuiceFS is a distributed POSIX file system built on top of Redis and S3.项目地址: https://gitcode.com/GitHub_Trending/ju/juicefs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考