文派智储

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

常见问题速答

会不会拖慢后台

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

停用插件会怎样

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

桶里对象能直接被搜到吗

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

支持 WebP / AVIF 吗

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

可以多个站共用一个桶吗

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

体检、排障与常见问题

体检（doctor）

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

常用排障入口

常见问题

前台图片 404

补传一直失败

点「开始补传」立即结束

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

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

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

边界与已知限制

WP-CLI 命令手册

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

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

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 目录。默认只写磁盘，前台地址仍指向桶——要改回本地地址需解除标记或拉回并删除。

范围

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

模式 行为
只补缺失（默认） 服务器上没有的才从桶里取；已有的原样保留
旧文件改名保留 现有本地文件改名为「原名-local-时间戳」保留，再写入桶里的版本；想对照两份时用这个
覆盖 桶里的文件直接替换本地同名文件，无法恢复

删除桶内对象（高危）

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

解除进桶标记

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

WooCommerce 付费下载与私有对象

付费文件的特殊性

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

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

策略 行为 适合
不进桶（默认） woocommerce_uploads 留在服务器，靠本地权限拦截 大多数站点：付费文件本来就不大，源站直接供下载
私有进桶，下载走签名 对象以私有 ACL 上传，商品下载地址带签名，知道地址也拿不走 大文件 / 高下载量，想卸载源站流量
照常进桶 跟随全站对象访问设置 桶本身就是私有 + 签名模式的站点

下载地址的自动回退

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

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

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

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

32MB 以上自动分片上传

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

厂商 大文件上传
阿里云 OSS 分片上传（32MB 起；须签名版本 V4，默认即是。用回 V1 的旧对接超过 32MB 会退回单请求）
S3 兼容全家（AWS / TOS / GCS / R2 / MinIO / DO / Wasabi） 分片上传（32MB 起）
腾讯云 COS / 华为云 OBS / 七牛 KODO 单请求，超时按体积放大（每 2MB 加 1 秒 + 30 秒余量）

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

分段下载（拉回）

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

WooCommerce 数字商品

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

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

新上传

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

存量补传队列

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

失败退避

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

wp sss offload --source=failed

缩略图与主文件标记

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

keep_local：本地备份

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

媒体库里也能直接操作

高级设置里的上传开关

自定义域名与 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

两种模式

公开读 签名 URL（私有）
原理 桶允许匿名 GET，地址永久有效 桶拒绝匿名，地址带签名与过期时间
适合 内容站、无付费墙 付费内容、隐私文件
缓存 可以长缓存（默认 30 天） 签名会过期，页面缓存时长必须小于签名有效期
风险 知道地址就能下载 签名算法暴露密钥？不会——签名只在服务端计算

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（元数据服务）。

密钥的日常管理

选择云厂商与站点场景

三种站点场景

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

场景 服务器位置 推荐 说明
国内站 服务器与访客都在中国大陆 国内云（OSS / COS / OBS 等） 备案域名 + 国内区域延迟最低
跨境站 站点与访客主要在海外，管理后台在国内 S3 兼容（AWS / R2 / GCS 等） 厂商如有海外区域同样可选国内云
混合站 服务器在海外，访客中外都有 两组都列出，自行选择 按访客 majority 决定桶区域

支持矩阵

厂商 类型 要点
阿里云 OSS 原生 推荐 V4 签名；支持 ECS RAM 角色免密钥；全球加速填「源区域」
腾讯云 COS 原生 APPID 填桶主账号的，不是子账户的；可选数据万象压缩/预览/审核
七牛云 KODO 原生 必须配置已备案的自定义域名，默认域名不能对外
华为云 OBS 原生 常规配置即可
火山引擎 TOS 原生（独立卡） 「国内云」组直接选「火山 TOS」卡片；不是 ImageX 产品
AWS / DO / R2 / MinIO / Wasabi S3 兼容 endpoint + 区域 + 密钥；R2 与 MinIO 注意 path-style
Google Cloud Storage 独立厂商卡 「国际与兼容云」组直接选；预设自动锁定 GCS，走 S3 兼容协议（HMAC 密钥）

百度 BOS 暂不支持。

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

选择建议

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

文派智储是什么

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

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

工作原理速览

安装与激活

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

第一次补传存量媒体

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

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

回退

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