# 文派智储

文派智储（WPSSS）对象存储静态加速，产品使用文档。

# 常见问题速答

## 会不会拖慢后台

媒体统计合并为一次数据库查询并带缓存；体检结果缓存一分钟。补传队列在后台低速率运行，不占前台资源。

## 停用插件会怎样

未配置自定义域名时，前台地址立刻回到本地（渲染期改写停止）。已配置自定义域名的，停用后媒体地址仍指向该域名（WordPress 的媒体地址选项由插件接管），桶与本地文件、数据库标记都保留，重新激活即恢复；想彻底回到本地地址，请先在设置里清空自定义域名，或走卸载流程。

## 桶里对象能直接被搜到吗

公开读的桶地址是可访问的，是否被搜索引擎收录取决于是否有链接指向。隐私内容用签名访问或付费目录策略。

## 支持 WebP / AVIF 吗

支持——上传什么格式就存什么格式。格式转换建议在 CDN/图片处理层做（如 COS 数据万象压缩、OSS 图片处理样式）。

## 可以多个站共用一个桶吗

可以：每个站用不同的「对象前缀」（如 site-a/、site-b/），地址互不冲突。

---

# 体检、排障与常见问题

## 体检（doctor）

概览页与 wp sss doctor 输出同一份体检：配置完整度、匿名读可达性、签名配置、上传地址前缀等，末尾附队列状态（待传 / 失败 / 后台任务 / 运行锁）。有阻断项会明确写出修法。

## 常用排障入口

- **工具 → 排障 → 扫描**：最近一批附件的本地缺失、访问域名不一致、http 明文、失败标记、前缀不符。
- **诊断**：贴一个裂图地址，插件给出判定链（哪个环节改写了地址、对象是否在桶）。
- **抽检远端**：按编号从新到旧抽最新进桶的 10 个附件做 HEAD，确认对象真的在。
- **操作记录**：最近 50 条上传/失败/删除/拉回。

## 常见问题

### 前台图片 404

- 对象真的在桶里吗——用抽检远端确认
- 地址是桶域名还是本地？本地说明附件未进桶或已解除标记
- 开了签名访问？签名过期会 403/404，页面缓存要短于签名有效期

### 补传一直失败

- 看操作记录里的失败原因：密钥权限、本地文件缺失、文件类型被排除
- 0 字节的损坏文件也能上传（0.9.1 起），如果仍失败看具体报错
- 连续失败 3 次会退出队列，修好后用「重试失败项」

### 点「开始补传」立即结束

0.9.0 的一个缺陷会导致待传队列被误清空（已在 0.9.1 修复）。确认你运行的是 0.9.1 或更高版本。

### 删除远端时报「前缀不符」

插件的对象键带前缀保护：换了前缀后拉回/删除会拒绝操作旧前缀对象，避免写错目录。把插件前缀改回原值，或用厂商控制台处理。

## 边界与已知限制

- 多站点（Multisite）暂不支持，不要在网络层激活。
- COS / OBS / 七牛的超大文件上传是单请求（超时按体积放大）；百兆以上建议用 OSS / S3 兼容厂商。
- 桶内对象没有版本控制时删除不可恢复——建议在云控制台开启版本控制。

---

# WP-CLI 命令手册

命令行适合批量操作与自动化，不经过页面缓存与网关超时。所有命令以 wp sss 开头。

<table id="bkmrk-%E5%91%BD%E4%BB%A4-%E4%BD%9C%E7%94%A8-wp-sss-status-"><thead><tr><th>命令</th><th>作用</th></tr></thead><tbody><tr><td><code>wp sss status</code></td><td>配置概览（不回显密钥）：厂商、桶、区域、开关状态</td></tr><tr><td><code>wp sss doctor</code></td><td>体检：配置、匿名读、签名、警告项 + 队列状态一行</td></tr><tr><td><code>wp sss probe</code></td><td>连通测试：写入并删除一个临时对象</td></tr><tr><td><code>wp sss set &#45;&#45;bucket&#61;&#46;&#46;&#46; &#45;&#45;region&#61;&#46;&#46;&#46; &#45;&#45;access&#45;key&#45;id&#61;&#46;&#46;&#46; &#45;&#45;access&#45;key&#45;secret&#61;&#46;&#46;&#46;</code></td><td>配置；–from-env 从 env 文件读密钥避免进 shell 历史</td></tr><tr><td><code>wp sss offload &#91;&#45;&#45;limit&#61;N&#93; &#91;&#45;&#45;id&#61;ID&#93; &#91;&#45;&#45;source&#61;failed&#93; &#91;&#45;&#45;dry&#45;run&#93; &#91;&#45;&#45;before&#61;ID&#93;</code></td><td>补传；–source=failed 只重试失败项</td></tr><tr><td><code>wp sss pull &#91;&#45;&#45;limit&#61;N&#93; &#91;&#45;&#45;id&#61;ID&#93; &#91;&#45;&#45;on&#45;exist&#61;rename&#124;overwrite&#93; &#91;&#45;&#45;dry&#45;run&#93; &#91;&#45;&#45;before&#61;ID&#93; &#91;&#45;&#45;delete&#45;remote &#45;&#45;yes&#93;</code></td><td>拉回；删桶必须 –yes</td></tr><tr><td><code>wp sss url &#60;附件ID&#62;</code></td><td>看某个附件当前对外的桶地址</td></tr><tr><td><code>wp sss rewrite &#91;&#45;&#45;from&#61;URL &#45;&#45;to&#61;URL&#93; &#91;&#45;&#45;apply&#93;</code></td><td>地址改写；默认只预览</td></tr><tr><td><code>wp sss copy &#45;&#45;to&#45;bucket&#61;&#46;&#46;&#46; &#91;&#45;&#45;to&#45;driver&#47;&#45;&#45;to&#45;region&#47;&#45;&#45;to&#45;endpoint&#47;&#45;&#45;to&#45;ak&#47;&#45;&#45;to&#45;sk&#47;&#45;&#45;to&#45;prefix&#93; &#91;&#45;&#45;limit&#93; &#91;&#45;&#45;before&#93; &#91;&#45;&#45;dry&#45;run&#93; &#91;&#45;&#45;update&#45;keys &#45;&#45;yes&#93;</code></td><td>桶间/厂商间搬运</td></tr><tr><td><code>wp sss upload &#60;本地文件&#62; &#91;&#45;&#45;key&#61;对象键&#93;</code></td><td>把服务器上的文件进桶（第三方落盘文件）</td></tr><tr><td><code>wp sss scan &#47; wp sss diagnose &#60;URL&#62;</code></td><td>扫描最近附件状态 / 诊断单个地址</td></tr><tr><td><code>wp sss delete &#60;对象键&#62; &#45;&#45;yes</code></td><td>只删桶内对象；参数是对象键（不是附件 ID），不会动媒体库附件。附件的完整对象键见媒体库附件侧栏或 <code>wp sss diagnose</code></td></tr></tbody></table>

env 文件格式（`--from-env`）：

```
WPSSS_OSS_BUCKET=demo
WPSSS_OSS_REGION=oss-cn-hangzhou
WPSSS_OSS_ACCESS_KEY_ID=LTAI...
WPSSS_OSS_ACCESS_KEY_SECRET=...
```

---

# 迁移与地址改写：渲染期改写、写库工具与换桶

## 渲染期改写（默认，零写库）

插件在页面渲染时把媒体地址换成桶地址——文章、小工具、分类描述、评论、RSS、REST、区块模板（FSE）、自定义背景/头图全覆盖。数据库里的原始数据永远不动，停用插件即还原。

正文里**写死的本站 uploads 地址**同样处理：只有对应附件确实已进桶才换；未进桶的旧图保持本地，不会因为整站换主机而 404。

## 写库改写（换域名后一次性做）

工具 → 迁移 → 改写文章中的媒体地址：把数据库里的旧地址（旧 CDN 域、旧 https/http）换成当前桶地址。写入正文、摘要与文章自定义字段（含序列化数据），插件不能撤销——先预览命中数，确认有数据库备份再写入。它不改网站设置（options）与主题设置（theme\_mods）。

## 换桶 / 换厂商

```
wp sss copy --to-bucket=新桶 --dry-run        # 先看计划
wp sss copy --to-bucket=新桶 --limit=200      # 分批搬（同厂商服务端复制，不占本地带宽）
wp sss copy --to-bucket=新桶 --to-driver=s3-compat --to-region=...  # 跨厂商走分段中转
wp sss copy --to-bucket=新桶 --update-keys --yes  # 搬完把附件对象键改成新前缀
```

1. copy 只搬对象，不改插件配置。搬完后把插件设置切到新桶（区域/密钥/前缀）。
2. 加了 –update-keys 的，切换后附件直接指向新前缀。
3. 跨厂商搬运走「分段下载 → 上传」中转，大文件也安全。

---

# 拉回本地与卸载

## 拉回本地（工具 → 迁移）

把桶里的文件下载回服务器 uploads 目录。默认**只写磁盘，前台地址仍指向桶**——要改回本地地址需解除标记或拉回并删除。

### 范围

- **批量拉回**：对已进桶的附件按编号从新到旧处理，一次拉一个，关掉页面即停。
- **单个附件**：填媒体库编号，只处理这一个（媒体库列表页也有行内「拉回本地」）。

### 本地已有同名文件时（三选一）

<table id="bkmrk-%E6%A8%A1%E5%BC%8F-%E8%A1%8C%E4%B8%BA-%E5%8F%AA%E8%A1%A5%E7%BC%BA%E5%A4%B1%EF%BC%88%E9%BB%98%E8%AE%A4%EF%BC%89-%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%8A%E6%B2%A1"><thead><tr><th>模式</th><th>行为</th></tr></thead><tbody><tr><td>只补缺失（默认）</td><td>服务器上没有的才从桶里取；已有的原样保留</td></tr><tr><td>旧文件改名保留</td><td>现有本地文件改名为「原名-local-时间戳」保留，再写入桶里的版本；想对照两份时用这个</td></tr><tr><td>覆盖</td><td>桶里的文件直接替换本地同名文件，**无法恢复**</td></tr></tbody></table>

## 删除桶内对象（高危）

勾选「永久删除桶内对象」会多出红色警示：桶里没有回收站（除非开启版本控制）。确认清单：先只拉回 → 媒体库打开核对 → 确认本地备份在——三步都过再勾「本地已经打开核对过」。付费下载文件删除会即时影响订单交付。

## 解除进桶标记

让插件「忘记」这批附件：标记删掉、桶内对象保留、前台改回本地地址。用于迁走插件或换对接方式。批量操作每批 20 个，需要勾选确认。

---

# WooCommerce 付费下载与私有对象

## 付费文件的特殊性

WooCommerce 的可下载商品文件放在 `uploads/woocommerce_uploads/`，本地靠 .htaccess 拒绝直链。进桶之后这个保护消失了——如果桶是公开读、对象键可预测，知道地址就能绕过付费墙。插件用「付费下载目录」策略解决这个问题。

## 三档策略（设置 → 高级 → 付费下载目录）

<table id="bkmrk-%E7%AD%96%E7%95%A5-%E8%A1%8C%E4%B8%BA-%E9%80%82%E5%90%88-%E4%B8%8D%E8%BF%9B%E6%A1%B6%EF%BC%88%E9%BB%98%E8%AE%A4%EF%BC%89-woo"><thead><tr><th>策略</th><th>行为</th><th>适合</th></tr></thead><tbody><tr><td>**不进桶（默认）**</td><td>woocommerce\_uploads 留在服务器，靠本地权限拦截</td><td>大多数站点：付费文件本来就不大，源站直接供下载</td></tr><tr><td>**私有进桶，下载走签名**</td><td>对象以私有 ACL 上传，商品下载地址带签名，知道地址也拿不走</td><td>大文件 / 高下载量，想卸载源站流量</td></tr><tr><td>照常进桶</td><td>跟随全站对象访问设置</td><td>桶本身就是私有 + 签名模式的站点</td></tr></tbody></table>

## 下载地址的自动回退

插件改写商品下载地址前会先确认对象真的在桶里——商家本地直传的文件、已拉回删除的对象，下载地址自动退回本地路径，订单交付不会 404。

## 已经把付费文件传进桶了怎么办

切到「私有进桶」后新对象私有，旧对象还是公开的。用厂商控制台的批量 ACL 工具把旧对象改私有，或拉回本地后再按新策略重新补传。

---

# 大文件：分片上传与分段下载

## 32MB 以上自动分片上传

超过 32MB 的文件自动走分片上传（multipart）：文件切成 8MB 一片逐片上传，失败自动放弃不留残件。内存占用固定，与文件大小无关。

<table id="bkmrk-%E5%8E%82%E5%95%86-%E5%A4%A7%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0-%E9%98%BF%E9%87%8C%E4%BA%91-oss-%E5%88%86%E7%89%87%E4%B8%8A"><thead><tr><th>厂商</th><th>大文件上传</th></tr></thead><tbody><tr><td>阿里云 OSS</td><td>分片上传（32MB 起；须签名版本 V4，默认即是。用回 V1 的旧对接超过 32MB 会退回单请求）</td></tr><tr><td>S3 兼容全家（AWS / TOS / GCS / R2 / MinIO / DO / Wasabi）</td><td>分片上传（32MB 起）</td></tr><tr><td>腾讯云 COS / 华为云 OBS / 七牛 KODO</td><td>单请求，超时按体积放大（每 2MB 加 1 秒 + 30 秒余量）</td></tr></tbody></table>

COS / OBS / 七牛的几百 MB 文件：单请求超时已放宽，但慢链路可能仍超时——建议这类大文件放上述分片厂商，或用厂商工具直传后 `wp sss offload` 补登记。

## 分段下载（拉回）

所有厂商的拉回都走 Range 分段：每段 8MB 落到临时文件，完成后校验总大小再原子改名到目标位置。拉一个 2GB 的视频，内存占用始终是 8MB。

## WooCommerce 数字商品

付费下载的大 ZIP 现在可以进桶了：上传走分片，下载地址走签名（见《WooCommerce 付费下载》）。

---

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

## 新上传

媒体库上传（含 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` 无论如何都不进桶。

---

# 自定义域名与 CDN

## 为什么需要自定义域名

- 阿里云 2019 年后的默认域名在浏览器里会强制下载而不是预览；
- 默认域名有带宽与 QPS 限制；
- 七牛必须配置自定义域名，默认域名不能对外；
- 自有域名方便挂 CDN、换厂商不动前台地址。

设置 → 自定义域名填 CDN 或桶绑定的 HTTPS 地址（如 `https://img.example.com`）。只要 CDN 已经指向存储桶，填它的地址即可，不限厂商。

## CDN 接入要点

1. 在云厂商或自建 CDN 处添加加速域名，回源到桶（回源 Host 用桶绑定的自定义域名）。
2. 在桶上绑定该自定义域名（阿里云 OSS 控制台 → 传输管理 → 绑定域名；需 DNS 归属验证）。
3. CDN 侧配好 HTTPS 证书。
4. 回源协议用 HTTPS；回源 Range 分片回源建议开启（插件分段拉回会用到）。
5. CORS：如果主题有跨域取图（canvas 处理等），CDN/桶要允许站点源。

## 换自定义域名

改设置里的自定义域名即可，前台地址渲染期自动切换。存量内容里写死的旧域名用「改写文章中的媒体地址」处理（见《迁移与地址改写》）。

---

# 对象访问方式：公开读与签名 URL

## 两种模式

<table id="bkmrk-%E5%85%AC%E5%BC%80%E8%AF%BB-%E7%AD%BE%E5%90%8D-url%EF%BC%88%E7%A7%81%E6%9C%89%EF%BC%89-%E5%8E%9F%E7%90%86-%E6%A1%B6%E5%85%81"><thead><tr><th></th><th>公开读</th><th>签名 URL（私有）</th></tr></thead><tbody><tr><td>原理</td><td>桶允许匿名 GET，地址永久有效</td><td>桶拒绝匿名，地址带签名与过期时间</td></tr><tr><td>适合</td><td>内容站、无付费墙</td><td>付费内容、隐私文件</td></tr><tr><td>缓存</td><td>可以长缓存（默认 30 天）</td><td>签名会过期，页面缓存时长必须小于签名有效期</td></tr><tr><td>风险</td><td>知道地址就能下载</td><td>签名算法暴露密钥？不会——签名只在服务端计算</td></tr></tbody></table>

## Cache-Control

对象写入时的 `Cache-Control` 响应头决定 CDN 与浏览器缓存：留空用智能默认（公开读 30 天 / 签名 1 小时），也可以自定义如 `public, max-age=604800`。改设置只影响新上传的对象，存量对象要重新覆盖或用厂商工具改头。

## 签名模式的重要提醒

开了签名访问后，页面缓存（含 CDN 的 HTML 缓存）里存的签名地址会随时间失效。规则：**页面缓存时长 ≤ 签名有效期的一半**。默认签名 1 小时，页面缓存最长 30 分钟，否则访客会看到裂图。

## 切换模式

公开读 ↔ 签名可以随时切，地址改写是渲染期的。但桶的匿名权限要自己在云控制台改：公开读要求桶策略允许匿名 GET；签名模式建议桶设为私有。

---

# 密钥安全与最小权限

## 用专用子账号，不要用主账号密钥

插件的 AccessKey 会写入数据库。如果用云厂商主账号（阿里云 RAM、腾讯云子账号体系之外）的密钥，一旦数据库泄露，攻击者就能操作你账号下的所有资源。正确做法是为插件建一个**只有目标桶权限**的子账号。

## 阿里云 OSS 策略示例

在 RAM 访问控制新建用户（如 `wpsss-mysite`），创建 AccessKey，然后挂一条自定义策略：

```
{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:PutObject", "oss:GetObject", "oss:DeleteObject",
      "oss:GetObjectMeta", "oss:HeadObject",
      "oss:ListObjects", "oss:ListObjectsV2",
      "oss:GetBucketInfo", "oss:GetBucketLocation"
    ],
    "Resource": [
      "acs:oss:*:<你的UID>:<你的桶名>",
      "acs:oss:*:<你的UID>:<你的桶名>/*"
    ]
  }]
}
```

这套权限覆盖插件全部功能：上传、下载、删除、分片上传、桶间复制、体检。不需要的权限一个都不给。

## ECS 服务器免密钥（仅阿里云）

如果 WordPress 跑在阿里云 ECS 上，可以不填 AccessKey，改用 RAM 角色：在高级设置的「凭证」下拉选「ECS 实例 RAM 角色」，并填「RAM 角色名」，插件通过 ECS 元数据接口取临时密钥。临时密钥每小时轮换，比长期密钥更安全。注意安全组要放行 `100.100.100.200`（元数据服务）。

## 密钥的日常管理

- 设置页里已保存的密钥显示为「已保存」，留空保存时保持不变——换密钥时填新值，不用重填旧的。
- 导出设置 JSON 不包含密钥；换站迁移时密钥要重新填。
- 怀疑泄露就立刻在云控制台禁用该 AccessKey，插件侧换新的。

---

# 选择云厂商与站点场景

## 三种站点场景

向导第 1 步与设置页都可以选站点场景，它只影响后台的厂商推荐顺序，不改变任何技术行为：

<table id="bkmrk-%E5%9C%BA%E6%99%AF-%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%BD%8D%E7%BD%AE-%E6%8E%A8%E8%8D%90-%E8%AF%B4%E6%98%8E-%E5%9B%BD%E5%86%85%E7%AB%99-%E6%9C%8D"><thead><tr><th>场景</th><th>服务器位置</th><th>推荐</th><th>说明</th></tr></thead><tbody><tr><td>国内站</td><td>服务器与访客都在中国大陆</td><td>国内云（OSS / COS / OBS 等）</td><td>备案域名 + 国内区域延迟最低</td></tr><tr><td>跨境站</td><td>站点与访客主要在海外，管理后台在国内</td><td>S3 兼容（AWS / R2 / GCS 等）</td><td>厂商如有海外区域同样可选国内云</td></tr><tr><td>混合站</td><td>服务器在海外，访客中外都有</td><td>两组都列出，自行选择</td><td>按访客 majority 决定桶区域</td></tr></tbody></table>

## 支持矩阵

<table id="bkmrk-%E5%8E%82%E5%95%86-%E7%B1%BB%E5%9E%8B-%E8%A6%81%E7%82%B9-%E9%98%BF%E9%87%8C%E4%BA%91-oss-%E5%8E%9F%E7%94%9F-"><thead><tr><th>厂商</th><th>类型</th><th>要点</th></tr></thead><tbody><tr><td>阿里云 OSS</td><td>原生</td><td>推荐 V4 签名；支持 ECS RAM 角色免密钥；全球加速填「源区域」</td></tr><tr><td>腾讯云 COS</td><td>原生</td><td>APPID 填桶主账号的，不是子账户的；可选数据万象压缩/预览/审核</td></tr><tr><td>七牛云 KODO</td><td>原生</td><td>必须配置已备案的自定义域名，默认域名不能对外</td></tr><tr><td>华为云 OBS</td><td>原生</td><td>常规配置即可</td></tr><tr><td>火山引擎 TOS</td><td>原生（独立卡）</td><td>「国内云」组直接选「火山 TOS」卡片；不是 ImageX 产品</td></tr><tr><td>AWS / DO / R2 / MinIO / Wasabi</td><td>S3 兼容</td><td>endpoint + 区域 + 密钥；R2 与 MinIO 注意 path-style</td></tr><tr><td>Google Cloud Storage</td><td>独立厂商卡</td><td>「国际与兼容云」组直接选；预设自动锁定 GCS，走 S3 兼容协议（HMAC 密钥）</td></tr></tbody></table>

百度 BOS 暂不支持。

填完桶名与密钥后，高级设置里点「读取桶信息」可自动回填区域等桶信息，避免手滑填错。

## 选择建议

- 主要访客在哪里，桶区域就选哪里——对象存储的加速效果取决于访客到桶的距离。
- 需要 CDN：任何厂商都可以，在桶前面加一层你自己的 CDN（见《自定义域名与 CDN》）。
- 换厂商不可怕：插件自带桶间搬运（见《迁移与地址改写》），先用测试桶试，随时切。

---

# 开始使用文派智储：五分钟把媒体库搬进对象存储

## 文派智储是什么

文派智储（WPSSS）把 WordPress 媒体库的图片、视频、文档上传到对象存储桶（如阿里云 OSS、腾讯云 COS），页面仍在源站渲染。访客的下载流量从源站卸载到云厂商，源站只负责 PHP 与数据库——这是大流量站点最常见的加速结构之一。

它与「整站搬到云」不同：你的 WordPress 还是原来的 WordPress，只是 `wp-content/uploads` 里的文件住进了桶里，前台地址自动指向桶域名。

## 工作原理速览

- **上传即进桶**：媒体库新上传的附件自动写入桶；本地是否保留副本由「本地备份」开关决定。
- **地址自动改写**：文章、缩略图、srcset、REST 接口里的媒体地址在渲染时换成桶域名，数据库里的原始数据不动。
- **页面留源站**：HTML、PHP、后台不走桶，缓存策略与现在完全一致。

## 安装与激活

1. 在插件页上传安装 wpsss.zip，或把解压后的目录放到 `wp-content/plugins/`。
2. 激活后左侧菜单出现「文派智储」，进入先看概览页；未配置时点「开始设置向导」走四步。
3. 向导第 1 步选择站点场景（国内 / 跨境 / 混合），影响推荐的厂商排序。
4. 第 2 步填桶名、区域、AccessKey——建议先用**测试桶**走完流程，确认无误再切生产桶。
5. 第 3 步先看「已为你配置」清单与运行体检；第 4 步完成页点「测试连通」：插件会向桶写入一个临时对象并删除，验证密钥与权限真的可用。

## 第一次补传存量媒体

配置完成后，到「工具 → 日常」点「开始补传」。队列一次上传一个附件，页面显示实时进度；中途可以暂停，关掉页面也行——后台每分钟最多补 2 个，慢慢清完。一个几千附件的站通常几个小时收尾，不需要守着。

新上传的附件不需要补传，上传那一刻已经进桶了。

## 回退

随时可以停用插件：标记与桶内对象都在，重新激活即恢复。想完全回到本地，用「拉回本地」把文件取回来，再解除进桶标记。详见《拉回本地与卸载》。

---