Shrine项目中使用AWS S3存储的完整指南

Shrine项目中使用AWS S3存储的完整指南

shrine File Attachment toolkit for Ruby applications 项目地址: https://gitcode.com/gh_mirrors/shr/shrine

前言

在现代Web应用中，文件上传是一个常见需求。Shrine作为一个灵活的文件上传库，提供了多种存储后端支持，其中AWS S3是最常用的存储方案之一。本文将详细介绍如何在Shrine项目中配置和使用AWS S3存储。

环境准备

要使用Shrine的S3存储功能，首先需要安装aws-sdk-s3 gem：

# Gemfile
gem "aws-sdk-s3", "~> 1.14"

初始化S3存储

初始化S3存储需要提供以下基本信息：

require "shrine/storage/s3"

s3 = Shrine::Storage::S3.new(
  bucket: "my-app",        # 必填，存储桶名称
  region: "eu-west-1",     # 必填，AWS区域
  access_key_id: "abc",    # 访问密钥ID
  secret_access_key: "xyz" # 秘密访问密钥
)

权限要求

使用S3存储需要配置以下IAM权限：

• 对存储桶的s3:ListBucket权限
• 对对象的多种权限：s3:GetObject、s3:PutObject、s3:PutObjectAcl、s3:DeleteObject、s3:ListMultipartUploadParts和s3:AbortMultipartUpload

认证方式

除了使用访问密钥ID和秘密访问密钥外，AWS SDK还支持多种认证方式，如IAM角色、环境变量等。

访问底层对象

Shrine的S3存储提供了对底层AWS对象的访问：

s3.client  # Aws::S3::Client实例
s3.bucket  # Aws::S3::Bucket实例
s3.object("key") # Aws::S3::Object实例

文件可见性设置

默认设置

默认情况下，上传的文件是私有的，只能通过有时限的签名URL访问：

s3.upload(io, "key") # 使用"private" ACL上传
s3.url("key")        # 生成带签名的URL

公开文件

如果需要公开访问文件，可以设置public: true：

s3 = Shrine::Storage::S3.new(public: true, **s3_options)
s3.upload(io, "key") # 使用"public-read" ACL上传
s3.url("key")        # 生成公开URL

条件性公开

可以通过插件实现条件性公开：

Shrine.plugin :upload_options, store: -> (io, **) { { acl: "public-read" } }
Shrine.plugin :url_options,    store: -> (io, **) { { public: true } }

高级配置

前缀设置

使用前缀可以组织文件结构，特别适合同时使用缓存和存储的场景：

Shrine::Storage::S3.new(prefix: "cache", **s3_options)

上传选项

可以配置全局上传选项：

Shrine::Storage::S3.new(upload_options: { acl: "private" }, **s3_options)

或按上传配置：

Shrine.plugin :upload_options, store: -> (io, derivative: nil, **) do
  derivative == :thumb ? { acl: "public-read" } : { acl: "private" }
end

URL主机设置

可以使用CDN作为URL主机：

s3.url("image.jpg", host: "http://abc123.cloudfront.net")

通过插件自动设置：

plugin :url_options, store: { host: "http://abc123.cloudfront.net" }

CloudFront签名

通过CloudFront分发私有内容时，需要使用签名：

require "aws-sdk-cloudfront"

signer = Aws::CloudFront::UrlSigner.new(
  key_pair_id:      "cf-keypair-id",
  private_key_path: "./cf_private_key.pem"
)

Shrine::Storage::S3.new(signer: signer.method(:signed_url))

大文件处理

AWS SDK支持自动分片上传大文件，默认阈值如下：

• 上传：15MB
• 复制：100MB

可以自定义阈值：

Shrine::Storage::S3.new(
  multipart_threshold: { upload: 30*1024*1024, copy: 200*1024*1024 },
  **s3_options,
)

加密选项

服务器端加密

可以通过上传选项配置：

s3.upload(io, "key", sse_customer_algorithm: "AES256",
                     sse_customer_key:       "secret_key",
                     sse_customer_key_md5:   "secret_key_md5")

客户端加密

使用加密客户端：

encryption_client = Aws::S3::EncryptionV2::Client.new(...)
s3 = Shrine::Storage::S3.new(client: encryption_client, **other_options)

高级功能

传输加速

启用AWS S3传输加速：

Shrine::Storage::S3.new(use_accelerate_endpoint: true, **other_options)

批量删除

删除指定前缀的所有对象：

s3.delete_prefixed("some_prefix/")

缓存清理

定期清理旧文件：

# 删除7天前的文件
s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }

总结

Shrine与AWS S3的集成为Ruby应用提供了强大而灵活的文件存储解决方案。通过本文介绍的各种配置选项和高级功能，开发者可以根据项目需求定制最适合的文件上传策略。无论是简单的公开文件存储，还是需要加密、加速等高级特性的场景，Shrine都能提供良好的支持。

shrine File Attachment toolkit for Ruby applications 项目地址: https://gitcode.com/gh_mirrors/shr/shrine