ZBlog + 缤纷云 S4 图片存储插件：介绍与使用说明

张宁的个人博客2026-10-30阅读 14效率提升

适用平台：Z-BlogPHP  
适用插件：`bitiful_s4` v1.3.6  
整理日期：2026-10-30

>点击下载插件： [bitiful_s4_1.3.6.zip](https://zgc261.com/zb_users/upload/2026/10/20261030150815179334409583437.zip "bitiful_s4_1.3.6.zip")

本文按当前插件的实际功能整理，涵盖安装配置、Markdown 编辑器上传、本地副本、云端附件管理。文中的 `img261`、`zgc261.com` 和 `imgs.zgc261.com` 为当前网站示例，其他用户应替换成自己的配置。

## 一、缤纷云与插件分别做什么

缤纷云 S4 是兼容 S3 协议的对象存储服务，用于保存图片等文件；搭配独立域名和 CDN，可以为博客提供图片访问地址。

本插件连接 Z-BlogPHP 与缤纷云：用户在编辑器上传本地图片后，由博客服务器先接收，再上传到缤纷云。云端上传成功时，编辑器获得云端图片链接；云端上传失败但本地已保存成功时，则返回本地链接。

插件代码免费开源，采用 MIT 许可，没有收费激活。存储、请求、流量及 CDN 的服务费用按缤纷云的实际规则计费。插件为独立实现，并非缤纷云或 Z-Blog 官方插件。插件使用的缤纷云图标归原权利人所有。

### 当前主要功能

- 支持调用 Z-Blog Upload 接口的 Markdown、富文本编辑器上传图片。
- 支持可编辑的上传 API、独立图片域名、目录前缀和大小限制。
- 可选择保留本地图片副本，云端上传失败时保留本地图片并回退。
- 新图片采用 12 位随机字母和数字命名，不含 `-`、`_`。
- 独立的云端附件管理：预览、复制链接、月份筛选、分页、单张删除及手动多选删除。
- 按需检测图片是否被已保存的文章、页面或草稿引用，并支持仅删除未发现引用的图片。

## 二、安装前准备

### 1. 网站环境

| 项目 | 要求 |
| --- | --- |
| Z-BlogPHP | 1.7.3 或以上 |
| PHP | 7.4 或以上 |
| PHP 扩展 | cURL、Hash、OpenSSL；云端附件管理另需 SimpleXML；后台使用 Ctype |
| 图片类型校验 | 建议启用 Fileinfo；未启用时使用 PHP 图片解析能力进行备用校验 |
| 本地目录 | 网站的 `zb_users/upload/` 必须可写 |
| 网络 | 博客服务器可以通过 HTTPS 访问缤纷云 API，CA 证书和系统时间正常 |

即使关闭“保留本地图片副本”，上传也需要先在本地安全落盘，因此本地目录仍须可写。

### 2. 缤纷云侧准备

1. 创建存储桶，记录桶名、Region 和 API 端点。
2. 为博客创建子账户密钥。
3. 授予目标桶或目标目录的上传权限；使用云端管理时，还需要对象列举和删除权限。
4. 配置图片访问域名及有效的 HTTPS 证书。
5. 如使用 CDN，将域名关联到正确的存储桶，完成相应的 DNS CNAME 配置。
6. 确认访客能够通过最终图片域名读取图片。

**上传权限与图片公开读取是两回事。** 密钥能够写入文件，不代表访客能够通过图片链接访问该文件。

## 三、安装与配置

### 1. 安装插件

将整个插件目录上传到：

```text
网站目录/zb_users/plugin/bitiful_s4/
```

确认 `plugin.xml` 直接位于该目录下，避免多嵌套一层目录。文件夹 ZIP 不等于 Z-Blog 原生 `.zba` 安装包，不要直接改扩展名。

进入 Z-Blog 后台 → 插件管理，启用“缤纷云 S4 图片存储”，打开插件设置。

### 2. 参数填写

| 设置项 | 当前网站示例 | 填写说明 |
| --- | --- | --- |
| 存储桶 Bucket | `img261` | 仅填写真实桶名，不带协议和域名 |
| 上传 API | `s3.bitiful.net` | **不包含 `https://`**，也不带桶名、端口、斜杠或路径 |
| Region | `cn-east-1` | 以自己的缤纷云控制台显示为准 |
| Access Key / Secret Key | 自己的子账户密钥 | 保存后不回显；后续编辑时留空可保留原值 |
| 图片访问地址 | `https://imgs.zgc261.com` | 填写完整 HTTPS 地址，并确保能够读取图片 |
| 对象目录前缀 | `blog` | 云端图片保存到此前缀下；留空时位于桶根目录下的年月目录 |
| 图片大小上限 | 默认 20 MiB | 同时受 Z-Blog、PHP 和 Web 服务器的大小限制约束 |
| 启用新图片自动上传 | 建议开启 | 让后续新上传的图片自动转存云端 |
| 保留本地图片副本 | 建议首次接入时开启 | 便于核验本地保存、备份和故障排查 |

上传时，程序自动使用类似下面的地址：

```text
https://img261.s3.bitiful.net/对象路径
```

文章图片则使用设置的访问地址，例如：

```text
https://imgs.zgc261.com/blog/2026/10/a7Kp2mQ9xB4r.jpg
```

当前插件采用 HTTPS、S3 Signature V4 和虚拟主机式寻址。自定义上传 API 并不等于兼容所有 S3 服务；不支持路径式 API、自定义端口、内网端点或仅 IPv6 的端点。

### 3. 首次测试

1. 保存设置，点击“上传测试图片”。
2. 打开返回的图片链接，确认可以正常显示。
3. 到缤纷云控制台，确认对应对象存在。
4. 在 Markdown 编辑器中上传一张本地图片。
5. 确认编辑器插入的是预期图片域名的链接。
6. 发布或预览文章，确认前台图片正常。
7. 如开启本地副本，再通过服务器文件管理器检查本地文件。

测试图片也保存在当月目录，不会自动清理；可在插件的云端附件管理中确认后删除。

## 四、图片上传、本地副本与文件命名

### 1. 两个开关的含义

| 自动上传 | 保留本地副本 | 上传结果 | 本次本地图片 | 编辑器收到的链接 |
| --- | --- | --- | --- | --- |
| 开启 | 开启 | 云端成功 | 保留 | 云端链接 |
| 开启 | 关闭 | 云端成功 | 删除本次本地副本 | 云端链接 |
| 开启 | 任意 | 云端失败、本地保存成功 | 保留 | 本地链接 |
| 关闭 | 任意 | 使用系统本地上传流程 | 按系统流程保存 | 本地链接 |

“启用新图片自动上传”只控制后续上传，不会迁移以前的图片。

“保留本地图片副本”也只影响设置保存之后的新上传：关闭不会清理以前保留的副本，开启不会恢复以前已经删除的副本。

本地保存本身失败、图片类型校验失败或大小超限时，上传会报错；失败回退不表示可以绕过这些检查。

### 2. 文件名和保存路径

从 v1.3.4 起，新图片使用 12 位随机字母和数字命名，例如：

```text
a7Kp2mQ9xB4r.jpg
```

名称不含 `-`、`_`，不附加时间戳或其他固定前缀。

默认云端路径为：

```text
blog/年份/月份/12位随机名称.扩展名
```

对应的本地副本通常为：

```text
zb_users/upload/年份/月份/12位随机名称.扩展名
```

如果 Z-Blog 开启按年月日保存，本地路径还会多一层日期目录。年月以网站 PHP 运行时区为准。

历史图片不会被自动改名或移动。旧文件名即使含 `-`、`_`，也不影响正常访问，这两种字符本身是合法的网址字符。

### 3. 编辑器适用范围

正常使用原有编辑器的“上传图片”功能即可。本地已检查过 `Editormd` 和 `xiurr_editormd_plus` 的系统上传路径，其他编辑器是否支持取决于其是否调用 Z-Blog Upload 接口。

- 上传本地图片：符合接口要求时可自动转存。
- 粘贴 Markdown 中已有的远程图片链接：只保留原链接，不自动下载转存。
- 粘贴剪贴板图片：若编辑器通过系统 Base64 上传接口提交，则可处理；直接把 `data:` 内容写入正文时，不会触发转存。
- 不建议同时启用其他接管图片上传、目录或附件 URL 的云存储插件。

![](https://imgs.zgc261.com/blog/2026/10/gFwNlhxmhMGe.png)

## 五、本地附件与云端附件怎样管理

### 1. Z-Blog 原生附件管理

当前版本在 Z-Blog 原生附件管理及 Uplist 卡片中，显示已同步图片的**本地链接**。编辑器上传后仍返回云端链接，二者用途不同。

例如，同一张图片可能同时存在：

```text
本地：https://zgc261.com/zb_users/upload/2026/10/a7Kp2mQ9xB4r.jpg
云端：https://imgs.zgc261.com/blog/2026/10/a7Kp2mQ9xB4r.jpg
```

若上传时没有保留本地副本，附件管理里的本地地址可能无法打开；显示本地链接不会自动重建副本。

### 2. 插件的“附件管理（云端）”

进入插件 → 附件管理（云端）。页面直接读取当前存储桶及配置前缀中的对象，不依赖 Z-Blog 是否仍保留附件记录。

- 电脑端每行显示 6 张图片，窄屏自动调整列数。
- 每次最多读取 48 个对象，再从中筛选支持的图片；当前页可能少于 48 张。
- 顶部包含存储桶、筛选、检测引用三个独立区域及备注。
- 可按路径中的年月筛选，并翻页查看。
- 图片卡片保留预览、大小、时间、引用状态和操作入口，不直接显示文件名及存放路径。
- 支持复制云端链接、单张删除、本页手动多选和本页全选。
- 包括测试图片、历史图片，以及相同管理目录内其他来源上传的支持格式图片。

列表按存储服务返回顺序显示，不保证最新上传的图片排在最前。切换桶或前缀会改变管理范围；前缀为空时管理整个当前桶下的支持格式图片。

### 3. 删除范围对照

| 操作入口 | 本地图片 | 云端图片 | Z-Blog 附件记录 | 文章正文链接 |
| --- | --- | --- | --- | --- |
| Z-Blog 原生附件管理删除 | 调用系统流程尝试删除 | 不删除 | 删除 | 不自动替换 |
| 插件云端附件管理删除 | 保留 | 删除所选对象 | 保留 | 不自动替换 |
| 服务器文件管理器删除本地文件 | 删除指定本地文件 | 不删除 | 不自动处理 | 不自动替换 |

**目前没有“两端自动同步删除”功能。** 云端删除后，如果文章仍引用该对象，文章中的图片就可能无法显示；本地有副本也不会自动替换文章链接。

本次测试中，用户确认附件管理恢复本地链接后，删除行为恢复正常。但这不代表所有网站都能保证删除成功。原生 Z-Blog 删除流程会先删记录、再尝试删本地文件，且可能不报告文件删除失败。若记录消失但文件仍在，需要用服务器文件管理器检查权限和真实文件；当前插件没有独立扫描本地目录的管理页面。

## 六、手动多选删除与引用检测

### 1. 手动多选删除

1. 在图片左上角逐张勾选，或点击“本页全选”。
2. 点击“删除所选图片”。
3. 核对确认页中的图片清单、数量和预计容量。
4. 确认后执行删除。

手动模式不要求先检测引用，也允许选择已被文章引用的图片，因此需要自行确认用途。首次提交只展示确认清单，不会立即删除。

批量操作每批最多处理 3 张；失败后停止，不自动重试。禁用 JavaScript 时，每次确认最多处理 3 张，剩余图片需继续确认。不支持跨所有分页的一键清空。

### 2. 检测文章引用

点击“检测文章引用”后，插件扫描数据库中已保存的文章、独立页面和草稿，包括正文、摘要及可安全解析的 Markdown 等扩展内容。

| 图片状态 | 含义 |
| --- | --- |
| 已引用 | 找到能够明确匹配该对象的文章或页面引用 |
| 未发现引用 | 本次检测没有找到引用，不等于一定没有用途 |
| 无法判断 | 存在同名、旧域名或无法可靠解析的内容等情况 |
| 未检测 | 尚未检测，或结果已失效 |

检测由用户点击触发，不会在每次打开页面或每张图片上逐一查询文章。结果缓存 10 分钟，正常保存、删除文章或页面会使缓存失效。

**不设“上传超过 7 天”等时间门槛。** 刚上传但尚未写入已保存文章的图片，也可能显示未发现引用。

以下内容无法保证完整检测：

- 编辑器中尚未保存的内容。
- 主题设置、侧栏模块中的引用。
- 其他网站使用的图片。
- 无法还原的动态链接或特殊扩展字段。

### 3. 仅删除未引用

完成检测后，可点击“选中本页未发现引用的图片”，或逐张选择，再点击“仅删除未引用”。

这一模式会在准备清单及实际分批执行前重新复核引用。若发现图片已被引用、状态无法判断、扫描不完整或检测失败，会阻止相应清理。它与不依赖检测的手动删除是两种不同操作。

大站达到扫描时间或内存限制时，检测可能中止；当前没有分段续扫功能。遇到失败时，不应把失败结果当作未引用结论。

![](https://imgs.zgc261.com/blog/2026/10/qOpvSATK0cZw.png)

## 七、常见问题与排查

### 1. 上传提示“文件保存时出错”

这是本地保存阶段的错误，不一定是缤纷云故障。

依次检查：

1. `zb_users/upload/` 和年月子目录是否可写。
2. PHP 上传临时目录是否正常，临时文件是否被其他图片处理插件移走。
3. Z-Blog 允许的扩展名、系统上传上限、插件上限以及 PHP/Web 服务器限制。
4. 图片实际格式是否与扩展名一致。
5. Fileinfo 是否可用；当前版本已经增加备用图片类型校验。

本次还修改了两个 Markdown 编辑器的 `php/Uploader.class.php`，以显示更具体的保存错误。如果线上仍只显示笼统提示，需要同步对应编辑器的该文件，或查看服务器日志中的 `[bitiful_s4]` 记录。

### 2. 上传失败：HTTP 403 / AccessDenied

这是上传请求被拒绝。检查桶名、Region、API 域名、Access Key / Secret Key，以及子账户对目标对象目录的写入权限。

不要仅因为能登录控制台，就认为子账户可以写入目标目录。

### 3. 上传成功，但打开图片返回 403

先确认对象存在，再区分“原始对象地址”和“CDN 图片地址”。写入成功不代表匿名读取已放行。

本次接入的实际原因是**原文件访问保护**。直接请求原始对象地址时，服务返回：

```xml
<Code>OriginalFileProtected</Code>
<Message>Forbidden access to the original file, please access by Style function.</Message>
```

含义：禁止直接访问原文件，需要通过预设 Style 样式访问。

当前插件生成的是普通图片地址，没有自动追加 Style 规则。本次通过关闭相应的原文件访问保护，使普通图片链接恢复访问。若业务需要保留该保护，应另行配置明确的样式访问方案，当前插件未提供通用的样式后缀设置。

其他排查方向包括：桶读取策略、域名绑定、CDN 回源权限、访问控制以及缓存。CDN 页面显示“运行中”或 CNAME 已配置，并不保证每个对象都能读取。

### 4. 防盗链怎样填写

若使用 Referer 白名单，根域名和通配子域名建议分别填写，以免因匹配规则差异漏掉根域名。例如：

```text
zgc261.com
*.zgc261.com
```

是否带协议、是否支持通配，以实际 CDN 配置要求为准。本次截图要求不带协议和端口，每行一个。

如果希望把图片网址粘贴到浏览器地址栏后也能访问，需要允许空 Referer。允许空 Referer 会减弱单纯依靠 Referer 防盗链的限制能力，应结合自己的使用需求设置。

本次取消防盗链后仍然返回 403，最终通过原始地址的错误码定位到了原文件保护，因此不要只凭 403 就断定是防盗链。

### 5. 删除后图片链接仍能打开

可能是文件仍在，也可能命中浏览器、CDN 或反向代理缓存。

- 本地图片：通过服务器文件管理器核对实际文件是否存在。
- 云端图片：通过缤纷云控制台或插件列表核对对象是否存在。
- 对象已删除但仍能访问：根据需要刷新对应 CDN URL 缓存，并排除浏览器缓存。

不能仅凭链接还能打开，就确定存储中的对象没有删除。

### 6. 需要配置 CORS 吗

本插件由博客服务器转传文件，密钥不发送给浏览器，通常不需要为上传配置桶 CORS。若浏览器还有 Canvas 读取图片或其他跨域处理需求，再按相应功能配置。

## 八、升级、暂停与停用

### 升级

备份原目录后，用新版完整覆盖：

```text
zb_users/plugin/bitiful_s4/
```

不要只更新 `main.php`，还要同步客户端代码、引用检测代码、样式、脚本和图标。插件 ID 不变，正常覆盖升级保留原有配置。升级后刷新页面，必要时清理浏览器缓存，再用一张测试图验证上传和读取。

### 暂停新上传

关闭“启用新图片自动上传”，后续新图片按本地流程保存。历史图片、已插入的文章链接不会自动改变。

### 修改桶、域名或前缀

新设置作用于后续新上传；已有文章链接不会自动改写。云端附件管理改为显示新配置范围，旧桶或旧前缀中的对象需要切回原配置或到控制台管理。

### 停用或卸载

插件不主动删除已有配置、本地文件或云端对象。文章里已经保存的云端链接仍依赖原域名及对象存在，不会自动切换为本地链接。若没有保留本地副本，停用也不会恢复文件。

## 九、当前不包含的功能

- 历史本地图片一键迁移到云端。
- 已有 Markdown 远程图片链接自动抓取转存。
- 文章图片链接批量替换。
- 本地与云端同步删除。
- 基于真实目录的本地孤立图片扫描管理。
- 图片自动压缩、水印、分片上传。
- 普通附件（例如 PDF）转存；当前只处理支持的图片类型。
- 跨全部分页的一键删除。

## 十、日常使用建议

- 发布文章：照常在编辑器上传图片，发布后检查显示效果。
- 管理本地副本：使用 Z-Blog 原生附件管理；记录缺失或删除异常时，再到服务器文件管理器核对。
- 管理云端图片：使用插件“附件管理（云端）”。
- 清理候选图片：先检测引用，优先使用“仅删除未引用”，并结合人工判断。
- 手动批量删除：核对确认清单，避免删除仍在文章中使用的图片。
- 备份时同时保留文章数据库、插件配置以及所需的图片文件；密钥和数据库备份按网站管理资料保护。

## 参考资料

- [缤纷云 S4 官方介绍](https://docs.bitiful.com/bitiful-s4/intro)
- [Z-BlogPHP Upload 类源码](https://github.com/zblogcn/zblogphp/blob/master/zb_system/function/lib/base/upload.php)

本文记录当前插件实现及本次实际接入结果。缤纷云控制台入口、服务策略和计费以官方当前信息为准。

文章关键词: bitiful; 缤纷云

发表评论让交流带来新的灵感

« 2026年10月 »
一	二	三	四	五	六	日
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31