缤纷云 S4 存储WordPress插件

# 缤纷云 S4 存储插件 使用说明

> 将 WordPress 媒体库（图片/视频/附件）自动上传到「缤纷云 S4」对象存储，**上传即直达云端**，节省服务器磁盘与带宽。
> 插件采用标准 S3 协议 + 原生 PHP 实现（零第三方依赖），兼容缤纷云 S4（Endpoint: `https://s3.bitiful.net`，Region: `cn-east-1`）。

---

## 一、功能特性

| 功能 | 说明 |
| --- | --- |
| 上传即同步 | 上传图片后自动把原图 + 全部缩略图同步到缤纷云 S4 |
| 删除本地副本 | 可选：上传成功后删除服务器本地文件，图片「直接」存在云端 |
| URL 自动替换 | 前台图片链接、srcset、媒体库预览全部指向云端访问域名 |
| 删除同步 | 在 WordPress 删除媒体时，同步删除云端对象 |
| 回源下载 | 本地文件被删后，编辑图片等场景自动从云端下载回本地，功能不受影响 |
| 一键迁移 | 把已有媒体库批量同步到云端 |
| 连接测试 | 设置页一键验证密钥与存储桶配置 |
| 零依赖 | 原生 PHP 实现 AWS Signature V4 签名，无需 Composer，低配置服务器可用 |

---

## 二、使用前准备（缤纷云侧，约 5 分钟）

1. 注册并登录 [缤纷云控制台](https://www.bitiful.com/) ，完成**实名认证**。
2. 点击左侧「对象存储」→「桶列表」→ **创建存储桶**（桶名需唯一）。
3. 进入该桶的「访问管理」，**开启「公开桶」**（否则图片无法被公网直接访问）；页面顶部可看到**访问域名**（形如 `https://你的桶名.s3.bitiful.net`）。
4. 创建**子账户**，手动为其分配对象读写权限（至少勾选 `PutObject` / `DeleteObject` / `ListObjects` / `GetObject`），生成并保存 **AccessKey / SecretKey**（SecretKey 只显示一次，请妥善保管）。
5. （可选）若使用自定义域名：在「自定义域名」绑定已**国内备案**的域名，插件里填该域名即可。

---

## 三、安装插件

1. WordPress 后台 → 「插件」→「安装插件」→「上传插件」→ 选择 `bitiful-s4-storage.zip` → 立即安装 → 启用。
   - 或手动解压到 `wp-content/plugins/bitiful-s4-storage/` 后启用。

## 四、配置插件

进入「设置 → 缤纷云 S4 存储」，填写：

| 配置项 | 说明 |
| --- | --- |
| 启用插件 | 勾选后媒体开始自动同步到云端 |
| AccessKey | 缤纷云子账户 AccessKey |
| SecretKey | 缤纷云子账户 SecretKey（留空则保留原值） |
| 服务端点 Endpoint | 默认 `https://s3.bitiful.net`（控制台「桶设置」底部可查） |
| 区域 Region | 默认 `cn-east-1` |
| 存储桶名称 | 你创建的桶名 |
| 访问域名 | 用于生成对外链接。留空自动推导为 `https://桶名.s3.bitiful.net`；绑定自定义域名则填自定义域名 |
| 对象键前缀 | 可选。例如填 `blog`，对象路径为 `blog/2026/09/xxx.jpg` |
| Path-Style 寻址 | 默认关闭（虚拟主机风格）。特殊环境可开启 |
| 删除本地文件 | 开启后上传成功即删除本地副本，只存云端 |
| 删除时同步云端 | 开启后 WP 中删除媒体会同步删除云端对象 |
| 调试日志 | 开启后错误信息写入 `error_log`（前缀 `[Bitiful-S4]`） |

填好后：**保存设置 → 测试连接**（应提示连接成功）→ 如需迁移已有媒体，点「同步已有媒体到云端」。

## 五、使用流程

1. 上传新图片：媒体库正常上传即可，插件自动同步到缤纷云，前台访问地址自动变为云端地址。
2. 迁移旧媒体：设置页点「同步已有媒体到云端」，批量上传原图与缩略图（开启"删除本地文件"后迁移完成本地会被清理）。
3. 删除媒体：在 WP 中删除媒体，云端对象同步删除。
4. 编辑图片：裁剪等操作自动回源下载，编辑结果再同步上传。

## 六、常见问题（FAQ）

**Q：上传失败？**
开启「调试日志」后查看 `error_log` 中 `[Bitiful-S4]` 日志。最常见原因：子账户缺少权限、桶未开启公开桶、密钥错误。上传失败时**不会删除本地文件**，媒体仍可用。

**Q：图片无法公网访问？**
确认存储桶已开启「公开桶」；使用自定义域名需国内备案并绑定成功。

**Q：卸载插件后图片还能访问吗？**
能。图片已存在缤纷云，不受插件影响。但若开启过「删除本地文件」，卸载后 WP 媒体 URL 会恢复为本地地址而本地文件已不在，建议卸载前先关闭「删除本地文件」或把媒体下载回本地。

**Q：占用服务器流量吗？**
上传由服务器发起一次；之后前台访问图片全部走云端，不占服务器带宽，可搭配缤纷云 CDN 进一步加速。

**Q：支持 PHP 低版本吗？**
插件要求 PHP ≥ 7.4、WordPress ≥ 5.6，兼容最新版 WordPress（测试至 6.8+）。

## 七、技术说明

- 兼容 S3 协议，使用 AWS Signature Version 4 签名（已用 AWS 官方 SDK 测试向量验证一致）。
- 上传使用流式 PutObject（`UNSIGNED-PAYLOAD`），支持较大文件且不占用过多内存。
- 桶域名格式：虚拟主机风格 `https://桶名.s3.bitiful.net/对象键`；Path-Style 为 `https://endpoint/桶名/对象键`。

## 八、文件结构

```
bitiful-s4-storage/
├── bitiful-s4-storage.php            # 插件主文件
├── includes/
│   ├── class-bitiful-s3-client.php   # 零依赖 S3 签名客户端
│   ├── class-bitiful-s4-plugin.php   # 上传/URL/删除/迁移逻辑
│   └── class-bitiful-s4-admin.php    # 后台设置页与 AJAX
├── uninstall.php                     # 卸载清理
└── readme.txt                        # WordPress 插件说明
```

=== 缤纷云 S4 存储 (Bitiful S4 Storage) ===
Contributors: bitiful-s4
Tags: 对象存储, 缤纷云, bitiful, S3, 云存储, 媒体库, CDN
Requires at least: 5.6
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

将 WordPress 媒体库自动上传到缤纷云 S4 对象存储，上传图片直达云端，节省服务器磁盘与带宽。

== Description ==

= 功能特性 =

* 媒体上传即同步：上传图片/视频/附件后自动上传到缤纷云 S4（原图 + 全部缩略图）。
* 删除本地副本：可选在上传成功后删除服务器本地文件，让图片"直接"存在云端。
* URL 自动替换：前台图片链接、srcset、媒体库预览全部指向云端访问域名。
* 删除同步：在 WordPress 删除媒体时，同步删除云端对象。
* 回源下载：本地文件被删除后，编辑图片等场景会自动从云端下载回本地，功能不受影响。
* 一键迁移：把已有媒体库批量同步到云端。
* 连接测试：设置页一键测试密钥与存储桶配置是否可用。
* 零第三方依赖：原生 PHP 实现 S3 签名（AWS Signature V4），无需 Composer，低配置服务器也可流畅运行。
* 兼容自定义域名：支持绑定自有域名（需国内备案）。

= 兼容性 =

* 兼容缤纷云 S4（Endpoint: https://s3.bitiful.net，Region: cn-east-1）。
* 采用标准 S3 协议，理论上也适用于其他 S3 兼容存储（修改 Endpoint / Region 即可）。

== Installation ==

1. 在 WordPress 后台「插件 → 安装插件 → 上传插件」上传本插件 zip 并启用；或解压到 `wp-content/plugins/bitiful-s4-storage` 后启用。
2. 前往「设置 → 缤纷云 S4 存储」完成配置：
   - 在缤纷云控制台创建存储桶，并在「访问管理」开启「公开桶」；
   - 创建子账户并授权对象读写（PutObject / DeleteObject / ListObjects / GetObject），获取 AccessKey / SecretKey；
   - 填写 AccessKey、SecretKey、存储桶名称；访问域名可留空自动推导，或填自定义域名。
3. 点击「保存设置」→「测试连接」确认配置正确。
4. 若需把已有媒体上传到云端，点击「同步已有媒体到云端」。
5. 之后上传的媒体将自动同步到缤纷云 S4。

== Frequently Asked Questions ==

= 上传失败怎么办？ =

开启「调试日志」后查看 error_log 中的 [Bitiful-S4] 日志；最常见原因是子账户缺少权限或存储桶未开启公开桶。上传失败时插件不会删除本地文件，媒体仍可正常使用。

= 图片无法公网访问？ =

请确认存储桶已设置为「公开桶」。若使用自定义域名，需在国内完成备案并正确绑定。

= 卸载插件后图片还能访问吗？ =

能。图片已存储在缤纷云，云端对象不受插件影响。卸载后 WordPress 媒体 URL 会恢复为本地地址，由于本地副本可能已被删除（若开启了"删除本地文件"），建议卸载前先关闭「删除本地文件」或将媒体下载回本地。

= 会消耗多少服务器流量？ =

上传由服务器发起一次，之后前台访问图片全部走云端/CDN，不再消耗服务器流量。

== Changelog ==

= 1.0.0 =
* 首次发布：上传同步、URL 替换、删除同步、回源下载、一键迁移、连接测试。

下载地址

链接：https://pan.quark.cn/s/6a498db59a23