README

S3 Uploads 是一个 WordPress 插件，用于将上传文件存储在 S3 上。S3 Uploads 旨在成为一个轻量级的“即插即用”插件，用于在 Amazon S3 上存储上传文件，而不是本地文件系统。

它专注于提供高度可靠的 S3 接口，没有任何“花哨的功能”，WP-Admin UI 或其他。它包含一些有用的 WP-CLI 命令，用于生成 IAM 用户、列出 S3 上的文件以及将现有库迁移到 S3。

要求

PHP >= 7.1
WordPress >= 5.3

设置环境

S3 Uploads 需要通过 Composer 进行安装

composer require humanmade/s3-uploads

注意： Composer 的自动加载器必须在加载 S3 Uploads 之前加载。我们建议在加载 wp-config.php 之前加载它，如下所示。

require_once __DIR__ . '/vendor/autoload.php';

配置

一旦安装了插件，请将以下常量添加到您的 wp-config.php

define( 'S3_UPLOADS_BUCKET', 'my-bucket' );
define( 'S3_UPLOADS_REGION', '' ); // the s3 bucket region (excluding the rest of the URL)

// You can set key and secret directly:
define( 'S3_UPLOADS_KEY', '' );
define( 'S3_UPLOADS_SECRET', '' );

// Or if using IAM instance profiles, you can use the instance's credentials:
define( 'S3_UPLOADS_USE_INSTANCE_PROFILE', true );

请参阅此区域列表 http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region 了解 S3_UPLOADS_REGION 的值。

允许在存储桶名称之后使用路径前缀，这是可选的。例如，如果您希望将所有文件上传到名为“my-bucket”的存储桶中的“my-folder”内部，您可以使用

define( 'S3_UPLOADS_BUCKET', 'my-bucket/my-folder' );

然后您需要启用该插件。为此，请使用以下 WP-CLI 命令

wp plugin activate S3-Uploads

插件名称必须与您克隆 S3 Uploads 到的目录匹配；如果您正在使用 Composer，请使用

wp plugin activate s3-uploads

接下来，您应该验证您的设置。您可以使用 verify 命令来完成此操作

wp s3-uploads verify

您需要自己创建 IAM 用户，或将必要的权限附加到现有用户，您可以通过 wp s3-uploads generate-iam-policy 输出策略

列出 S3 上的文件

S3-Uploads 内置了 WP-CLI 命令，用于列出 S3 存储桶中的文件，以进行调试等。

wp s3-uploads ls [<path>]

将文件上传到 S3

如果您有一个现有的媒体库，其中包含附件文件，请使用以下命令将它们全部从本地磁盘复制到 S3。

wp s3-uploads upload-directory <from> <to> [--verbose]

例如，要将整个上传目录迁移到 S3，请运行

wp s3-uploads upload-directory /path/to/uploads/ uploads

还有一个通用的 cp 命令，用于任意复制到和从 S3。

wp s3-uploads cp <from> <to>

注意：由于 <from> 或 <to> 可以是 S3 或本地位置，您必须指定完整的 S3 位置，例如 s3://mybucket/mydirectory，例如 cp ./test.txt s3://mybucket/test.txt。

私有上传

WordPress（因此 S3 Uploads）的默认行为是所有上传的媒体文件都是公开可访问的。在某些情况下，这可能不是所希望的。S3 Uploads 支持将 S3 对象设置为 private ACL，并为所有标记为私有的文件提供临时签名的 URL。

S3 Uploads 不假设或提供 UI 来标记附件为私有，相反，您应该集成 s3_uploads_is_attachment_private WordPress 过滤器来控制行为。例如，要标记所有附件为私有

add_filter( 's3_uploads_is_attachment_private', '__return_true' );

私有上传可以通过调用 S3_Uploads::set_attachment_files_acl( $id, 'public-read' ) 或反之来转换为公共。例如

S3_Uploads::get_instance()->set_attachment_files_acl( 15, 'public-read' );

所有私有文件URL的默认过期时间为6小时。您可以通过使用WordPress过滤器s3_uploads_private_attachment_url_expiry来修改此设置。值可以是strtotime可解释的任何字符串。例如

add_filter( 's3_uploads_private_attachment_url_expiry', function ( $expiry ) {
	return '+1 hour';
} );

缓存控制

您可以使用以下常量定义上传媒体默认的HTTP Cache-Control头：

define( 'S3_UPLOADS_HTTP_CACHE_CONTROL', 30 * 24 * 60 * 60 );
	// will expire in 30 days time

您还可以使用S3_UPLOADS_HTTP_EXPIRES常量配置Expires头。例如，如果您想要设置一个资产不实际过期，可以将Expires头设置在遥远的未来。例如

define( 'S3_UPLOADS_HTTP_EXPIRES', gmdate( 'D, d M Y H:i:s', time() + (10 * 365 * 24 * 60 * 60) ) .' GMT' );
	// will expire in 10 years time

默认行为

由于S3上传是一个即插即用的插件，激活它将开始重写图像URL到S3，并将新上传的文件放在S3上。有时这可能不是所需的行为，因为网站管理员可能希望在启用S3上传并将所有上传请求定向到S3之前，使用wp-cli命令上传大量媒体到S3。在这种情况下，可以将S3_UPLOADS_AUTOENABLE定义为false。例如，在您的wp-config.php中放置以下内容：

define( 'S3_UPLOADS_AUTOENABLE', false );

要启用S3上传的重写，请使用以下wp-cli命令：wp s3-uploads enable / wp s3-uploads disable来切换行为。

URL重写

默认情况下，S3上传将使用规范S3 URI引用上传，即[bucket名称].s3.amazonaws.com/uploads/[文件路径]。如果您想使用其他URL来提供图像（例如，如果您希望将S3作为CloudFlare的源），应在您的wp-config.php中定义S3_UPLOADS_BUCKET_URL

// Define the base bucket URL (without trailing slash)
define( 'S3_UPLOADS_BUCKET_URL', 'https://your.origin.url.example/path' );

如果当前网站不需要，可以禁用S3上传的URL重写功能。在这种情况下，插件将只上传文件到S3存储桶。

// disable URL rewriting alltogether
define( 'S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true );

S3对象权限

可以通过设置S3_UPLOADS_OBJECT_ACL常量来控制通过此插件上传到S3的文件的对象权限。如果未指定，默认设置是public-read，允许任何人对对象进行读取。如果您不希望上传公开可读，则可以在wp-config文件中将S3_UPLOADS_OBJECT_ACL定义为private或authenticated-read之一

// Set the S3 object permission to private
define('S3_UPLOADS_OBJECT_ACL', 'private');

有关S3权限的更多信息，请参阅Amazon S3权限文档。

自定义端点

根据您的需求，您可能希望使用Minio、Ceph、Digital Ocean Spaces、Scaleway和其他S3兼容对象存储系统。

您可以通过在wp-content/mu-plugins/目录中的文件中添加以下代码来配置端点，例如wp-content/mu-plugins/s3-endpoint.php

<?php
// Filter S3 Uploads params.
add_filter( 's3_uploads_s3_client_params', function ( $params ) {
	$params['endpoint'] = 'https://your.endpoint.com';
	$params['use_path_style_endpoint'] = true;
	$params['debug'] = false; // Set to true if uploads are failing.
	return $params;
} );

临时会话令牌

如果您的S3访问配置为除了访问密钥和秘密之外还需要临时会话令牌，您应使用以下代码配置凭据：

// Filter S3 Uploads params.
add_filter( 's3_uploads_s3_client_params', function ( $params ) {
	$params['credentials']['token'] = 'your session token here';
	return $params;
} );

离线开发

虽然可以使用S3上传进行本地开发（这实际上是一种不需要从生产同步所有上传到开发的好方法），但如果您想离线开发，您有几个选项。

只需在您的开发环境中禁用S3上传插件。
定义S3_UPLOADS_USE_LOCAL常量，插件处于激活状态。

选项2将允许您为生产兼容性运行S3上传插件，它将基本上使用本地流包装器模拟Amazon S3，并将上传实际上存储在您的WP上传目录/s3/中。

鸣谢

由Human Made为高流量和大规模网站创建。我们在每月有数百万页面浏览量的网站和数千个网站上运行S3上传。

由Joe Hoyle编写和维护。感谢所有我们的贡献者。

想要加入我们的乐趣吗？加入我们，成为人类！

人工制造 / s3-uploads

维护者

详细信息