把纸鱼博客的媒体文件交给七牛云 Kodo 托管。启用后，后台媒体库上传、文章封面、正文插图都继续走原来的上传入口，文件落到七牛云，站点只保存 CDN 地址——不用改主题，也不用改核心文件。
插件介绍
纸鱼博客默认把上传文件存在服务器的 public/uploads。站点图片一多，备份体积、磁盘占用和访问速度都会成为问题。这个插件把上传流程接到七牛云对象存储：文件通过服务端签名直传 Kodo，前台通过绑定的 CDN 域名访问，服务器的磁盘和带宽只承担页面本身。
上传凭证在服务端生成，AccessKey 和 SecretKey 不会出现在浏览器里。云端上传失败时核心会自动回退本地存储，不会让一次上传整体失败；失败原因写入 runtime/error.log，方便排查配置问题。
主要功能
- 接管全部上传入口：媒体库、文章封面、正文插图、页面图片共用核心上传接口，启用即生效。
- 服务端签名：PutPolicy 上传凭证由插件生成，密钥不下发到前端。
- 区域可选：支持华东-浙江、华北-河北、华南-广东、华东-浙江2、北美-洛杉矶、亚太-新加坡、亚太-河内、亚太-胡志明市，按 Bucket 所在区域选择上传和删除线路。
- 自定义 CDN 域名：返回并入库的是绑定域名的完整地址，可带 https 和自定义端口。
- 云上删除：在媒体库删除文件时同步删除七牛云对象；只处理当前 CDN 域名下的地址，不会误删其他存储的文件。
- 连接测试：在插件设置页点“测试存储连接”，会真实上传一个临时文件再删除，上传和删除两条链路一起验证。
- 失败回退：七牛云不可达、签名错误或返回非 2xx 时回退本地存储，上传不中断。
- 路径可控：对象默认落在
前缀/年/月/随机名.扩展名，前缀可留空。
使用前准备
- 登录七牛云控制台，进入「对象存储 Kodo」创建存储空间（Bucket），记下空间名称和所属区域。
- 在存储空间的「域名管理」里绑定一个已备案的 CDN 域名，并按七牛云提示完成 CNAME 解析。
- 确认存储空间的访问控制为公开读取。插件返回的是普通 CDN 地址，私有空间需要每次访问重新签名，当前版本不支持。
- 在「密钥管理」里获取 AccessKey 和 SecretKey。
插件设置
| 设置项 | 说明 |
|---|---|
| AccessKey / SecretKey | 七牛云「密钥管理」中的账号密钥，只保存在服务端。 |
| 存储空间 Bucket | 例如 pafish-media，必须与密钥同账号。 |
| 存储区域 | 与 Bucket 所属区域一致。区域选错时上传通常返回 400/401。 |
| CDN 加速域名 | 绑定到 Bucket 的访问域名，例如 https://cdn.example.com。只填域名，不要带路径、查询参数或末尾的 /key。 |
| 对象路径前缀 | 默认 pafish，最终对象名形如 pafish/2026/10/1a2b3c4d5e6f7a8b9c0d.jpg；留空表示放在根目录。 |
| 自定义上传域名 | 一般留空，按区域自动使用 up-*.qiniup.com。使用上传代理或特殊线路时才需要填写。 |
保存后点「测试存储连接」。测试成功会显示 Bucket 和 CDN 域名；如果提示“上传成功，但删除测试失败”，说明上传凭证没问题，问题在管理 API 的签名、区域线路或服务器出网。
注意事项
- 只迁移新上传：启用前已经存在的本地图片仍留在
public/uploads，插件不会搬运历史文件；需要的话自行上传到七牛云并替换正文地址。 - 同时只生效一个存储插件：核心按插件启用顺序取第一个声明存储能力且已启用的插件。装了这个插件后，请停用缤纷云等其他存储后端，避免实际写入的不是你以为的那一个。
- 停用插件不会删云端文件：停用后新上传回到本地，已有文章的七牛云地址仍然可以访问；但在媒体库删除旧文件时不会再调用七牛云删除接口。
- 删除依赖域名匹配：只有 URL 的 host 与当前配置的 CDN 域名一致时才会删除云端对象；更换域名后，旧域名下的文件需要到七牛云控制台手动清理。
- CDN 域名必须已经生效：上传成功只代表对象写进了 Bucket。域名没有绑定、CNAME 没生效或空间不是公开读取时，前台图片会 404，而插件本身不会报错。
- 服务器时间要准确：上传凭证和管理凭证都带时间戳，服务器时间偏差过大会被七牛云拒绝（通常是 401）。
- 建议使用 HTTPS：CDN 域名和自定义上传域名都支持 http，但后台在 HTTPS 下混用 http 资源会遇到浏览器拦截。
常见问题
上传后图片 404
先到七牛云控制台确认对象确实存在，再检查 CDN 域名是否绑定、CNAME 是否生效、Bucket 是否为公开读取。插件返回的地址由「CDN 加速域名 + 对象路径」拼成，域名填错时上传仍然会成功。
提示“上传失败（HTTP 401/403）”
检查 AccessKey、SecretKey、Bucket 是否属于同一账号，区域是否选对，以及服务器时间是否准确。403 也可能是上传凭证的 scope 与表单里的 key 不一致，正常由插件生成时不会出现。
提示“上传成功，但删除测试失败”
上传和删除走的是不同域名：上传是 up-*.qiniup.com，删除是 rs-*.qiniuapi.com。确认服务器能访问管理域名，并检查区域是否与 Bucket 一致。插件在区域主机不可达时会回退 rs.qiniuapi.com。
日志里出现“云存储上传失败，回退本地”
说明七牛云这一步抛错了，但上传本身没有失败，文件落在了本地。到 runtime/error.log 搜索 [pafish-plugin] 云存储上传失败 查看具体原因，修好配置后重新上传即可。
版本更新。