使用 Ruby AWS SDK 访问 Ceph RGW S3 接口：桶与对象操作完整指南

存储分布式文件系统对象存储后端高可用【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址https://gitcode.com/gh_mirrors/ce/ceph点击查看免费下载导读Ceph Object GatewayRGW对外提供与 Amazon S3 API 兼容的 RESTful 接口任何遵循 S3 协议的客户端包括 Ruby 生态中的aws-sdk与aws-s3两个 gem都可以直接对接。本文以 Ceph 官方文档 doc/radosgw/s3/ruby.rst 为骨架系统讲解用 Ruby 完成连接配置、桶的增删查、对象的上传下载与 ACL 管理、签名/未签名 URL 生成等完整操作并结合仓库中的 RGW 源码如 src/rgw/rgw_acl_s3.cc与配套文档如 doc/radosgw/s3/authentication.rst、doc/radosgw/s3/commons.rst补充底层原理与实操细节。读完本文你将能够用两种主流 Ruby SDK 快速接入 Ceph RGW并理解其认证、ACL 与路径访问模式的实现机制。适用前提本文示例面向 Ceph RGW 的 S3 兼容接口文中出现的objects.dreamhost.com为官方文档沿用的示例主机名实际使用时请替换为你的 RGW 网关地址如rgw.example.com并替换为自己的access_key_id/secret_access_key。两种 SDK 的适用版本分别为aws-sdk gem ~2与aws-s3 gem老一代 gem。一、Ceph RGW 的 S3 兼容接口与 Ruby 生态选型Ceph 通过 RGW 组件暴露一套与 Amazon S3 API 基本数据访问模型兼容的 RESTful API其功能支持清单List Buckets、Create/Delete Bucket、Put/Get/Delete Object、Object ACL、Multipart Uploads、Object/Bucket Tagging、Bucket Policy、S3-select 等详见 doc/radosgw/s3.rst 中的特性支持表。Ruby 开发者对接 RGW 主要有两条技术路线路线gem适用场景现代 SDKaws-sdk~ 2官方文档 doc/radosgw/s3/ruby.rst 前半部分示例面向Aws::S3::Client接口推荐新项目使用经典 gemaws-s3官方文档后半部分示例面向AWS::S3命名空间接口更贴近早期 S3 REST 语义两种 SDK 均通过 HTTP 调用 RGW 的 S3 端点认证依赖 AWS 签名Signature v2/v4因此只要是合法的 S3 凭据即可工作无需任何 Ceph 专用客户端库。二、现代 SDKaws-sdk gem ~2连接配置与客户端初始化2.1 全局连接设置官方推荐使用Aws.config.update进行全局配置一次性声明端点、凭据与访问模式Aws.config.update( endpoint: https://objects.dreamhost.com., access_key_id: my-access-key, secret_access_key: my-secret-key, force_path_style: true, region: us-east-1 )参数含义与注意事项endpointRGW 网关地址。必须显式指定否则 SDK 会默认指向 AWS 官方 S3 服务。access_key_id/secret_access_keyS3 凭据可由radosgw-admin user create创建用户时生成详见下文准备凭据小节。force_path_style: true强制使用path-style访问模式GET /mybucket。这几乎总是对接 RGW 的正确选择——因为 RGW 默认并未为每个桶分配子域名virtual-hosted-styleGET /Host: mybucket.cname.domain.com需要额外配置rgw_dns_name或 zonegroup 的hostnames。两种访问模式的差异与配置方法参见 doc/radosgw/s3/commons.rst。regionRGW 对 region 值不做强制校验填写任意值如us-east-1即可满足签名计算要求。2.2 实例化客户端s3_client Aws::S3::Client.new之后所有桶与对象操作均通过s3_client完成。2.3 准备凭据对接 RGW 前的账号准备在真实环境中你需要先在 RGW 中创建 S3 用户并获取访问密钥这属于 RGW 管理面操作可参考 doc/radosgw/adminops.rst 中的用户管理章节典型命令形如radosgw-admin user create --uidruby-user --display-nameRuby User --gen-access-key --gen-secret-key创建成功后命令会返回access_key与secret_key将其填入上面的Aws.config.update即可。RGW 对请求的认证基于 AWS 签名v2/v4SDK 会自动完成签名计算只有手工构造原始 HTTP 请求时才需要自行计算签名详见 doc/radosgw/s3/authentication.rst。三、桶操作列出、创建、清空与删除3.1 列出自己拥有的桶List Owned Bucketss3_client.list_buckets.buckets.each do |bucket| puts #{bucket.name}\t#{bucket.creation_date} end输出形如mahbuckat1 2011-04-21T18:05:39.000Z mahbuckat2 2011-04-21T18:05:48.000Z mahbuckat3 2011-04-21T18:07:18.000Z该操作对应 S3 的GET /服务级请求Service Ops在 RGW 侧由s3:ListAllMyBuckets权限控制。3.2 创建桶Create Buckets3_client.create_bucket(bucket: my-new-bucket)若希望桶默认为私有可显式传入acl选项s3_client.create_bucket(bucket: my-new-bucket, acl: private)acl选项canned ACL支持以下取值private仅所有者可读写默认public-read公开可读public-read-write公开读写慎用authenticated-read仅已认证用户可读这四个 canned ACL 值与 RGW 服务端实现一一对应见 src/rgw/rgw_acl_s3.cc 中的解析逻辑private/public-read/public-read-write/authenticated-read。需要注意的是官方文档 doc/radosgw/s3.rst 明确指出 RGW 对桶的 canned ACL 集合与 AWS 存在差异Different set of canned ACLs。3.3 列出桶内容List a Buckets Contents3_client.get_objects(bucket: my-new-bucket).contents.each do |object| puts #{object.key}\t#{object.size}\t#{object.last-modified} end输出形如myphoto1.jpg 251262 2011-08-08T21:35:48.000Z myphoto2.jpg 262518 2011-08-08T21:38:01.000Z注意官方文档此处写的是get_objects实际现代aws-sdkv2中列出对象的标准方法是list_objects或list_objects_v2返回结构均为contents数组字段key、size、last_modified一致。若你的 SDK 版本提示找不到get_objects请改用s3_client.list_objects(bucket: my-new-bucket).contents.each do |object| puts #{object.key}\t#{object.size}\t#{object.last_modified} end3.4 删除桶Delete Bucket⚠️ 注意桶必须为空才能删除成功否则操作会失败s3_client.delete_bucket(bucket: my-new-bucket)3.5 非空桶的强制删除删除非空桶前必须先清空桶SDK 提供了便捷方法Aws::S3::Bucket.new(my-new-bucket, client: s3_client).clear!清空之后即可删除桶s3_client.delete_bucket(bucket: my-new-bucket)clear!会遍历桶内对象并逐个调用delete_object等效于先list_objects再循环删除因此数据量极大时建议评估耗时与请求配额。四、对象操作上传、ACL 管理、下载与删除4.1 创建对象Put Object在桶my-new-bucket中创建hello.txt内容为字符串Hello World!s3_client.put_object( key: hello.txt, body: Hello World!, bucket: my-new-bucket, content_type: text/plain )content_type显式指定Content-Type元数据若省略SDK 会根据body类型推断。上传大文件时可改用put_object的文件流形式或使用 Multipart UploadRGW 支持见 doc/radosgw/s3.rst 功能表。4.2 修改对象 ACL使hello.txt公开可读、secret_plans.txt私有s3_client.put_object_acl(bucket: my-new-bucket, key: hello.txt, acl: public-read) s3_client.put_object_acl(bucket: my-new-bucket, key: private.txt, acl: private)RGW 的 ACL 模型包含READ、WRITE、READ_ACP、WRITE_ACP、FULL_CONTROL五种权限作用于桶与对象时语义不同例如READ在桶上表示可列出桶内对象在对象上表示可读取该对象完整权限对照与 S3 操作到 ACL 权限的映射表见 doc/radosgw/s3/authentication.rst。4.3 下载对象到本地文件Get Object将对象poetry.pdf下载并保存到本地目录s3_client.get_object( bucket: my-new-bucket, key: poetry.pdf, response_target: /home/larry/documents/poetry.pdf )response_target指定本地保存路径SDK 会以文件流方式落盘避免将大对象整体读入内存。4.4 删除对象Delete Objects3_client.delete_object(key: goodbye.txt, bucket: my-new-bucket)RGW 侧由s3:DeleteObject权限控制对应WRITE级 ACL 权限。五、生成对象下载 URL未签名公开与预签名限时对于公开对象已通过 ACL 设为public-read可以生成无需签名的直接访问 URLputs Aws::S3::Object.new( key: hello.txt, bucket_name: my-new-bucket, client: s3_client ).public_url对于私有对象如secret_plans.txt生成预签名 URLpresigned URL在有效期内任何人都可通过该 URL 下载即使对象本身是私有的有效期过后 URL 立即失效puts Aws::S3::Object.new( key: secret_plans.txt, bucket_name: hermes_ceph_gem, client: s3_client ).presigned_url(:get, expires_in: 60 * 60)expires_in单位为秒上例为 1 小时60 * 60。输出形如http://objects.dreamhost.com/my-bucket-name/hello.txt http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?SignatureXXXXXXXXXXXXXXXXXXXXXXXXXXXExpires1316027075AWSAccessKeyIdXXXXXXXXXXXXXXXXXXX预签名 URL 的本质是将签名作为查询参数Signature、Expires、AWSAccessKeyId附加到 URL 上RGW 在收到请求时会校验签名与有效期。这是临时授权下载最常用的手段适合限时分享私有文件场景。小提示示例中第二个 URL 的桶名为hermes_ceph_gem这是官方文档的历史笔误实际应为你自己的桶名如my-new-bucket请按需替换。六、经典 gemaws-s3老一代 SDK 的对应操作aws-s3gem 提供与aws-sdk平行的操作集合接口风格更接近早期 S3 REST 语义适合维护旧项目。以下逐一给出对应实现。6.1 建立连接AWS::S3::Base.establish_connection!( :server objects.dreamhost.com, :use_ssl true, :access_key_id my-access-key, :secret_access_key my-secret-key )establish_connection!建立全局连接use_ssl决定是否走 HTTPS。注意该接口没有force_path_style参数若 RGW 未配置桶子域名需要注意主机名与路径的解析方式。6.2 列出自己拥有的桶AWS::S3::Service.buckets.each do |bucket| puts #{bucket.name}\t#{bucket.creation_date} end输出同上mahbuckat1 ...。6.3 创建桶AWS::S3::Bucket.create(my-new-bucket)6.4 列出桶内容new_bucket AWS::S3::Bucket.find(my-new-bucket) new_bucket.each do |object| puts #{object.key}\t#{object.about[content-length]}\t#{object.about[last-modified]} endobject.about返回对象的元数据哈希包含content-length字节数与last-modified。6.5 删除桶⚠️ 同样要求桶为空否则失败AWS::S3::Bucket.delete(my-new-bucket)6.6 非空桶强制删除aws-s3直接支持:force true一步完成清空与删除AWS::S3::Bucket.delete(my-new-bucket, :force true)这是与aws-sdk实现先clear!再delete_bucket最明显的 API 差异。6.7 创建对象AWS::S3::S3Object.store( hello.txt, Hello World!, my-new-bucket, :content_type text/plain )6.8 修改对象 ACL通过 Grant 列表改写 ACL公开hello.txt、私有化secret_plans.txtpolicy AWS::S3::S3Object.acl(hello.txt, my-new-bucket) policy.grants [ AWS::S3::ACL::Grant.grant(:public_read) ] AWS::S3::S3Object.acl(hello.txt, my-new-bucket, policy) policy AWS::S3::S3Object.acl(secret_plans.txt, my-new-bucket) policy.grants [] AWS::S3::S3Object.acl(secret_plans.txt, my-new-bucket, policy)这里先读取对象当前 ACL再整体替换grants列表空列表即私有最后回写。6.9 下载对象到本地文件aws-s3以流式分块方式下载并写入文件open(/home/larry/documents/poetry.pdf, w) do |file| AWS::S3::S3Object.stream(poetry.pdf, my-new-bucket) do |chunk| file.write(chunk) end end6.10 删除对象AWS::S3::S3Object.delete(goodbye.txt, my-new-bucket)6.11 生成下载 URL签名/未签名# 未签名公开对象URL puts AWS::S3::S3Object.url_for( hello.txt, my-new-bucket, :authenticated false ) # 预签名限时 1 小时URL puts AWS::S3::S3Object.url_for( secret_plans.txt, my-new-bucket, :expires_in 60 * 60 ):authenticated false生成不带签名的公开 URL:expires_in生成带签名的限时 URL。输出格式与aws-sdk示例一致。七、两种 SDK 操作对照一览操作aws-sdk~2aws-s3连接配置Aws.config.updateAws::S3::Client.newAWS::S3::Base.establish_connection!列出桶s3_client.list_buckets.bucketsAWS::S3::Service.buckets创建桶s3_client.create_bucket(bucket: ...)AWS::S3::Bucket.create(...)列出桶内容list_objects(bucket: ...).contentsBucket.find(...)后迭代删除桶空s3_client.delete_bucket(bucket: ...)AWS::S3::Bucket.delete(...)强制删除Bucket.new(...).clear!后删除AWS::S3::Bucket.delete(..., :force true)创建对象put_object(key:, body:, bucket:, content_type:)S3Object.store(key, value, bucket, :content_type ...)修改 ACLput_object_acl(bucket:, key:, acl:)读写S3Object.aclpolicy.grants下载对象get_object(bucket:, key:, response_target:)S3Object.stream分块写文件删除对象delete_object(key:, bucket:)S3Object.delete(key, bucket)未签名 URLObject#public_urlurl_for(..., :authenticated false)预签名 URLObject#presigned_url(:get, expires_in:)url_for(..., :expires_in ...)八、背后的实现要点结合 RGW 源码canned ACL 的服务端解析create_bucket与put_object_acl传入的acl字符串在 RGW 服务端由 src/rgw/rgw_acl_s3.cc 解析并映射为具体的 grant 集合支持private、public-read、public-read-write、authenticated-read四种取值非法取值会返回参数错误。认证机制RGW 支持 AWS Signature v4 与 v2 两种签名算法SDK 自动完成签名x-amz-content-sha256头支持实际负载校验值、UNSIGNED-PAYLOAD以及多种流式负载模式详见 doc/radosgw/s3/authentication.rst。访问模式force_path_style: true对应 path-style 请求GET /mybucket是 RGW 部署的常见形态如需 virtual-hosted-styleHost: mybucket.cname.domain.com需通过rgw_dns_name配置或在 zonegroup 中声明hostnames参见 doc/radosgw/s3/commons.rst。签名 URL 的校验预签名 URL 通过查询参数携带签名与过期时间RGW 校验通过后放行匿名下载因此时效性与签名完整性由 RGW 统一保障客户端无需额外处理。九、常见问题与排错建议endpoint忘记配置SDK 会默认连向 AWS 官方 S3请求将失败或指向错误服务务必显式设置 RGW 地址。桶删除失败检查桶是否为空。非空桶需先clear!或:force true。403 AccessDenied确认access_key_id/secret_access_key正确且该用户对目标桶/对象拥有相应 ACL 或桶策略权限RGW 支持桶策略与 ACL 两种授权模型官方建议优先使用桶策略见 doc/radosgw/s3/authentication.rst 末尾说明。URL 上出现异常主机名检查是否启用了 virtual-hosted-style 而 RGW 未配置桶子域名保持force_path_style: true通常是更稳妥的选择。对象上传大文件put_object直接上传适合中小文件超大对象建议使用 Multipart Upload APIRGW 支持见 doc/radosgw/s3.rst 特性表。赞分享存储分布式文件系统对象存储后端高可用【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址https://gitcode.com/gh_mirrors/ce/ceph点击查看免费下载相关推荐使用 C AWS SDK 对接 Ceph RGW S3 网关从连接建立、桶与对象操作到预签名 URL 的完整实践使用 C AWS SDK 对接 Ceph RGW S3 网关从连接建立、桶与对象操作到预签名 URL 的完整实践 本文以 Ceph RADOS Gateway存储分布式文件系统对象存储后端高可用如何用 start-cluster.sh 为 LibreChat 本地搭建三节点 Redis Cluster 并通过 .env 连接验证如何用 start cluster.sh 为 LibreChat 本地搭建三节点 Redis Cluster 并通过 .env 连接验证 LibreChat 本存储分布式文件系统对象存储后端高可用Ceph 对象存储 Java S3 开发实战基于 AWS Java SDK 2.17 的完整操作指南Ceph 对象存储 Java S3 开发实战基于 AWS Java SDK 2.17 的完整操作指南 本指南以 Ceph 对象网关RADOS Gateway存储分布式文件系统对象存储后端高可用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考