# 上传与补传：队列、暂停与失败退避

## 新上传

媒体库上传（含 REST/XML-RPC 程序化上传）在生成附件元数据的同时进桶：主文件、原图、各尺寸一个不落。第三方直接放进 uploads 目录的文件不会自动进桶——用镜像回源，或让开发者调用 wpsss\_file\_upload()。

## 存量补传队列

工具 → 日常 → 开始补传。顶部有进度条：百分比按首轮「已处理 + 剩余」为基线实时推进，文字行同步显示本轮成功 / 失败 / 剩余。

- **一次一个附件**：每个请求只上传一个附件，不会因网关超时中断整批。
- **可暂停**：点「暂停」立即停；网络中断自动暂停，再点继续。
- **关页继续**：关掉页面后，后台任务每分钟最多补 2 个附件直到清完（需要站点 cron 正常工作），队列清空后自动停止。
- **断点续传**：按附件编号从新到旧处理，中断后从上次位置继续。点「从最新开始」可清掉续传位置重新扫（已进桶的自动跳过）。

## 失败退避

同一个附件连续失败 3 次后，自动退出补传队列（避免一个坏文件卡住整队）。队列清空后如果只剩失败项，工具页会明确提示剩多少个、到哪里查原因：到「工具 → 排障 → 体检」，修好后点「重试失败项」，或命令行：

```
wp sss offload --source=failed
```

## 缩略图与主文件标记

设置里可以关掉「同时上传缩略图」。此时插件给附件打上「主文件」标记：主文件地址照常指向桶，各尺寸地址保持本地——前台不会因为尺寸文件不在桶里而裂图。PDF 附件同理：PDF 本体进桶，预览缩略图留在本地。0 字节的损坏文件也能如实上传（对象按 0 字节保存）。

## keep\_local：本地备份

默认开启（推荐）：桶与本地各一份，源站挂了也能从本地恢复。关闭后本地文件在上传成功后删除——此时插件会接管 get\_attached\_file（编辑图片等场景退回桶地址），上传重名文件也会先查桶避免覆盖。关闭本地备份需要管理员在高级设置操作。

## 媒体库里也能直接操作

- **状态列「对象存储」**：每个附件标出已进桶 / 未进桶 / 失败（附原因），列表页还有「全部 / 已进桶 / 未进桶 / 失败」筛选。
- **行内动作**：未进桶的附件在列表行内点「补传到桶」；已进桶的可「拉回本地」。
- **批量操作**：列表勾选后批量「补传到桶」或「拉回本地」。
- **附件编辑页侧栏**：显示对象键与对外地址，可直接打开，也可单附件补传 / 拉回。

## 高级设置里的上传开关

- **远端已有则跳过**：桶里已有同名对象时不再重复上传（默认关；适合重建桶后避免覆盖）。
- **自动重命名**：同名冲突时的处理——关闭（默认，按原名加 -1、-2 递增）/ md5 / 时间戳。
- **不进桶的扩展名**：填了就不上传的扩展名清单；`php`、`htaccess` 无论如何都不进桶。

---