文派智储 文派智储（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 开头。 命令 作用 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 扫描最近附件状态 / 诊断单个地址 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 # 搬完把附件对象键改成新前缀 copy 只搬对象，不改插件配置。搬完后把插件设置切到新桶（区域/密钥/前缀）。 加了 –update-keys 的，切换后附件直接指向新前缀。 跨厂商搬运走「分段下载 → 上传」中转，大文件也安全。 拉回本地与卸载 拉回本地（工具 → 迁移） 把桶里的文件下载回服务器 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()。 存量补传队列 工具 → 日常 → 开始补传。顶部有进度条：百分比按首轮「已处理 + 剩余」为基线实时推进，文字行同步显示本轮成功 / 失败 / 剩余。 一次一个附件：每个请求只上传一个附件，不会因网关超时中断整批。 可暂停：点「暂停」立即停；网络中断自动暂停，再点继续。 关页继续：关掉页面后，后台任务每分钟最多补 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 接入要点 在云厂商或自建 CDN 处添加加速域名，回源到桶（回源 Host 用桶绑定的自定义域名）。 在桶上绑定该自定义域名（阿里云 OSS 控制台 → 传输管理 → 绑定域名；需 DNS 归属验证）。 CDN 侧配好 HTTPS 证书。 回源协议用 HTTPS；回源 Range 分片回源建议开启（插件分段拉回会用到）。 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（元数据服务）。 密钥的日常管理 设置页里已保存的密钥显示为「已保存」，留空保存时保持不变——换密钥时填新值，不用重填旧的。 导出设置 JSON 不包含密钥；换站迁移时密钥要重新填。 怀疑泄露就立刻在云控制台禁用该 AccessKey，插件侧换新的。 选择云厂商与站点场景 三种站点场景 向导第 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 暂不支持。 填完桶名与密钥后，高级设置里点「读取桶信息」可自动回填区域等桶信息，避免手滑填错。 选择建议 主要访客在哪里，桶区域就选哪里——对象存储的加速效果取决于访客到桶的距离。 需要 CDN：任何厂商都可以，在桶前面加一层你自己的 CDN（见《自定义域名与 CDN》）。 换厂商不可怕：插件自带桶间搬运（见《迁移与地址改写》），先用测试桶试，随时切。 开始使用文派智储：五分钟把媒体库搬进对象存储 文派智储是什么 文派智储（WPSSS）把 WordPress 媒体库的图片、视频、文档上传到对象存储桶（如阿里云 OSS、腾讯云 COS），页面仍在源站渲染。访客的下载流量从源站卸载到云厂商，源站只负责 PHP 与数据库——这是大流量站点最常见的加速结构之一。 它与「整站搬到云」不同：你的 WordPress 还是原来的 WordPress，只是 wp-content/uploads 里的文件住进了桶里，前台地址自动指向桶域名。 工作原理速览 上传即进桶：媒体库新上传的附件自动写入桶；本地是否保留副本由「本地备份」开关决定。 地址自动改写：文章、缩略图、srcset、REST 接口里的媒体地址在渲染时换成桶域名，数据库里的原始数据不动。 页面留源站：HTML、PHP、后台不走桶，缓存策略与现在完全一致。 安装与激活 在插件页上传安装 wpsss.zip，或把解压后的目录放到 wp-content/plugins/。 激活后左侧菜单出现「文派智储」，进入先看概览页；未配置时点「开始设置向导」走四步。 向导第 1 步选择站点场景（国内 / 跨境 / 混合），影响推荐的厂商排序。 第 2 步填桶名、区域、AccessKey——建议先用测试桶走完流程，确认无误再切生产桶。 第 3 步先看「已为你配置」清单与运行体检；第 4 步完成页点「测试连通」：插件会向桶写入一个临时对象并删除，验证密钥与权限真的可用。 第一次补传存量媒体 配置完成后，到「工具 → 日常」点「开始补传」。队列一次上传一个附件，页面显示实时进度；中途可以暂停，关掉页面也行——后台每分钟最多补 2 个，慢慢清完。一个几千附件的站通常几个小时收尾，不需要守着。 新上传的附件不需要补传，上传那一刻已经进桶了。 回退 随时可以停用插件：标记与桶内对象都在，重新激活即恢复。想完全回到本地，用「拉回本地」把文件取回来，再解除进桶标记。详见《拉回本地与卸载》。