CCLEE OSS 使用指南：WordPress 媒体库上传同步到阿里云 OSS
CCLEE OSS 是 WordPress 阿里云 OSS 插件：后台媒体库上传的文件——图片、PDF、视频等所有附件——自动同步到你自己的阿里云 OSS Bucket，前台媒体 URL 自动重写为 OSS 或 CDN 域名（图片额外覆盖 srcset 与各尺寸缩略图）。文件访问不再经过网站服务器，由 OSS/CDN 直接响应，页面加载更快。
插件为商用授权制：授权 Token 与站点域名绑定，粘贴到设置页即可激活（离线验签，无需常连授权服务器）；插件更新由 CCLEE 更新服务器分发，仅有效授权站点可接收。
CCLEE OSS 能为你做什么
媒体加载更快。 图片是网页里占比最大的流量，附件下载同样吃带宽。启用后媒体文件直接从 OSS/CDN 域名响应，配合 CDN 加速域名可让访客就近加载，页面打开更快。
网站服务器更轻。 图片与附件的下载流量不再消耗网站服务器的带宽，服务器资源留给网站程序与动态请求，访问高峰更从容。
全自动接入，现有内容零改动。 后台上传即同步（图片、PDF、视频等全部媒体类型）；前台 URL 自动重写，主题、编辑器、已发布的文章都不需要改任何东西；图片的原图与全部缩略图尺寸一并覆盖。
故障兜底，数据安全。 OSS 任一环节异常自动回退本地，网站照常运行；媒体数据存在你自己的 Bucket 里，插件不会删除已上云的数据，授权到期也只是新上传回退本地。
适合谁用
- 媒体较多的网站：博客、作品集、WooCommerce 电商（产品图 + 变体图多）、提供 PDF 目录或资料下载的站点
- 图片加载慢、或服务器带宽吃紧的站长
- 已有阿里云账号、希望媒体数据存放在自己 Bucket 的用户（存储与流量按阿里云官方定价直接结算，数据完全在自己手里）
功能一览
| 功能 | 说明 |
|---|---|
| 上传即上云 | 后台上传的媒体文件（图片、PDF、视频等）自动推送到 OSS，无需手动迁移 |
| 存量媒体补推 | 激活前已存在的媒体一键批量推送，带进度、可暂停续传，失败的单独列出、重跑不重复上传 |
| 全尺寸覆盖 | 原图与全部缩略图同步上传，regenerate-thumbnails 重建的尺寸同样覆盖 |
| 大文件同步 | 视频、压缩包等大文件（10MB 以上）自动分段上传，普通服务器也传得稳 |
| URL 自动重写 | 原图、srcset、尺寸图 URL 指向 CDN 域名（未配置时用 Bucket 公网域名），附件下载链接同样重写 |
| 数据库 URL 替换 | 可选：把数据库已存的媒体链接批量替换为 OSS/CDN 域名，替换前自动备份，支持一键回滚 |
| 本地副本管理 | 纯云模式下新上传确认同步成功即删本地副本，存量媒体批量下线；需要本地文件的操作自动临时取回 |
| 一键回迁 | 从 OSS 把媒体整体拉回服务器，停用插件或站点搬家时数据完整回本地 |
| 删除同步 | 可选开启：删除媒体库附件时同步删除 OSS 上的对象 |
| 静默回退 | OSS 任一环节异常自动回退本地存储，不打断 WordPress 原生流程 |
| 授权更新 | 更新包由 CCLEE 更新服务器分发并经 sha256 校验，仅有效授权站点可下载 |
快速入门
前提条件
- WordPress 6.4+，PHP 8.0+
- 阿里云账号，且已创建 Bucket（读写权限选公共读）
- CCLEE 为你的站点域名签发的授权 Token
第一步：安装并激活插件
- WordPress 后台 → 插件 → 安装插件 → 上传插件
- 选择
cclee-oss.zip→ 点击现在安装 - 安装完成后点击启用
第二步：粘贴授权 Token
- 进入 设置 → CCLEE OSS
- 在 License Token 粘贴 CCLEE 交付给你的授权 Token
- 点击保存
Token 与站点域名绑定
授权 Token 签发时绑定了你的站点域名（自动忽略 www 与端口后比对）。保存时插件会当场验签并核对域名，域名不符会被拒绝保存。站点更换域名后，需要联系 CCLEE 重新签发。
第三步：创建 RAM 子账号（最小权限）
插件只需要「向你的 Bucket 写入和删除对象」两个权限。按最小权限原则创建专用 RAM 子账号（创建权限策略 → 创建用户 → 授权，全程约 10 分钟），完整操作步骤见 阿里云 RAM 子账号配置指南。
完成后你会拿到一对 AccessKey ID / Secret，下一步填入插件时要用。
第四步：填写 OSS 配置
回到 设置 → CCLEE OSS，填入：
| 设置项 | 填写内容 |
|---|---|
| AccessKey ID / AccessKey Secret | 第三步保存的 RAM 密钥 |
| Bucket | 你的 Bucket 名 |
| Endpoint | Bucket 所在地域的公网 endpoint（见 Bucket 概览页），如 oss-cn-hangzhou.aliyuncs.com；与 Bucket 同地域的阿里云 ECS 优先填内网 endpoint |
| CDN 域名 | 可选。已给 Bucket 绑定 CDN 加速域名则填写，媒体 URL 将使用该域名；留空使用 Bucket 公网域名 |
填完点击保存。
第五步：上传测试图验证
- 后台 → 媒体 → 添加新文件，上传一张测试图片
- 在媒体库中点击该图片查看文件 URL（或打开前台引用该图的页面）
- 图片 URL 已指向 OSS/CDN 域名即为配置成功
授权与更新
到期与续期
- Token 内置有效期，到期前 14 天后台顶部会出现续期提示条
- 续期只需在设置页粘贴新 Token 并保存，无需其他操作
到期或吊销后会发生什么
插件做软降级，不做任何破坏性操作：
- 新上传的媒体改存本地，网站照常运行
- 已上传到 OSS 的文件与图片 URL 不受影响，前台展示如常
- 不会删除你 Bucket 里的任何数据
断网宽限期
授权状态随插件更新检查回传（约每 12 小时一次）。服务器临时无法联网不会立即失效——以最后一次成功校验时刻为基准，保留 14 天宽限期；期间恢复联网即自动恢复正常。
插件更新
- WordPress 后台的更新检查自动进行，有新版本时在「插件」页正常更新
- 更新包下载时经 sha256 完整性校验，不符即中止安装
- 仅有效授权站点能收到新版本
行为开关
| 开关 | 默认 | 说明 |
|---|---|---|
| Keep Local Copy | 开 | 上云后保留本地副本。关闭前需完成存量补推与数据库 URL 替换；关闭后新上传的文件在确认同步成功后自动删除本地副本 |
| Sync Delete to OSS | 关 | 删除媒体库附件时，同步删除 OSS 上的对象（原图 + 全部缩略图） |
本地文件是兜底真相
OSS 上传、删除、URL 重写任一环节失败时，插件静默回退 WordPress 原生行为（文件留在本地），你的网站不会因 OSS 故障而中断。
纯云模式：媒体只存 OSS，释放主机空间
主机磁盘空间紧张时，可以让服务器不再保留媒体副本。进入纯云模式按顺序三步，插件的保护机制会保证顺序不被打乱：
- 补推存量媒体：设置页点击「补推」，把激活前已存在的媒体全部推送到桶里（带进度、可暂停续传）
- 运行数据库 URL 替换：把数据库中已存的媒体链接批量替换为桶/CDN 域名，替换前自动备份；验证通过后插件才允许后续的删除操作
- 删除本地副本：关闭「Keep Local Copy」——此后新上传的文件确认同步成功即自动删除本地副本；存量媒体用「下线任务」批量释放（编辑历史仍留在服务器）
两道保护贯穿全程：下线前逐个确认云端文件完好，内容对不上的先重传再删；只要数据库里还有链接没完成替换验证，任何删除任务都会拒绝启动——操作顺序再乱也不会裂图。
纯云模式下，需要本地文件的操作照常可用
重新生成缩略图、图像编辑器裁剪旋转、PDF 缩略图这类需要本地文件的操作，会在操作期间自动从桶里取回文件，结束后自动清理，不需要手动搬文件。
想搬回本地存储？
设置页的「从 OSS 恢复」任务把桶里的文件整体拉回服务器（可安全重复执行）；如果运行过 URL 替换，再用「URL 回滚」把数据库链接还原为本地链接。两步完成后即可停用插件——这也是日后站点搬家、更换 Bucket 的回迁通道。
常见问题
用 CCLEE OSS 需要花多少钱？
费用分两部分：插件授权向 CCLEE 购买；媒体文件的存储与流量费用由你的阿里云 Bucket 按官方定价直接结算——数据在你自己的 Bucket 里，阿里云直接计费，CCLEE 不加价。
非图片文件（PDF、视频等附件）也会同步吗？
会。所有通过媒体库上传的文件都会同步到 OSS，附件的下载链接同样自动重写为 OSS/CDN 域名；缩略图子尺寸与 srcset 覆盖是图片文件特有的额外处理。
大文件（如视频）同步会出问题吗？
不会。10MB 以上的大文件自动分段上传，普通配置的服务器也传得稳；没传成功的文件会集中列在设置页的失败清单里，照着清单补传即可。
缩略图（子尺寸）也会上传到 OSS 吗？
会。原图与全部生成的子尺寸都会推送，包括 regenerate-thumbnails 这类插件重建出的尺寸；各尺寸的 srcset URL 也会一并重写指向 OSS。
授权到期后，已上云的图片会丢失吗？
**不会。**授权到期或被吊销后，插件进入软降级：只是新上传的媒体改存本地，已上传到 OSS 的文件与 URL 保持原样，前台图片照常显示，Bucket 中的数据不会被删除。
上传到 OSS 失败会影响发文章吗？
不会。上传、删除、URL 重写任一环节失败，插件都会静默回退 WordPress 原生行为（文件保留在本地媒体库），后台操作与前台访问均不受影响。
换域名或站点搬家后，授权还有效吗？
Token 与站点域名绑定。域名变化后原 Token 将无法通过校验，需要联系 CCLEE 按新域名重新签发，拿到新 Token 粘贴保存即可恢复。
可以删除本地副本、只保留 OSS 吗？
可以。在设置页依次完成「补推存量媒体」和「数据库 URL 替换」后，关闭「Keep Local Copy」即进入纯云模式：新上传的文件确认同步成功后自动删除本地副本，存量媒体用「下线任务」批量释放。删除前插件会逐个核对桶内副本，数据库还在引用本地文件时删除任务会拒绝执行；想搬回本地时，「从 OSS 恢复」任务可整体回迁。
数据库 URL 替换是必须的吗？
不是必选。默认模式下数据库始终保存本地链接，前台显示时实时改写，不替换一切正常。只有进入纯云模式（删除本地副本）前才需要替换——让数据库链接与桶内文件直接对应，前台改写照顾不到的存量链接（旧 http:// 链接、页面构建器数据里的链接）也能一并处理。替换前自动备份，随时可一键回滚。
换 Bucket 或 CDN 域名，需要改数据库吗？
默认模式不需要：数据库始终保存本地链接，前台输出时实时改写为 OSS/CDN 域名，换域名只需在设置页改一处。如果运行过数据库 URL 替换，先用「URL 回滚」把链接还原为本地链接，换好域名后按需重新替换。
想停用插件、把媒体搬回本地怎么办？
两步：设置页运行「从 OSS 恢复」把桶内文件拉回服务器；如果运行过 URL 替换，再运行「URL 回滚」把数据库链接还原为本地链接。完成后即可停用插件，数据完整回到本地。
Endpoint 应该填公网还是内网？
与 Bucket 同地域的阿里云 ECS 优先填内网 endpoint（更快、不走公网）；其他情况（外部服务器、不同地域）填公网 endpoint。两类地址都能在 Bucket 概览页查到。
插件更新怎么获取？
WordPress 后台的更新检查自动进行（约每 12 小时一次），有新版本时在「插件」页正常点击更新即可，无需手动下载。更新仅对有效授权站点开放。
获取授权与技术支持
CCLEE OSS 按站点域名签发授权，支持购买、续期与换域名重签。联系我们获取授权：
联系 CCLEE