兰空图床插件（lkstc）使用说明

版本：1.0.0 ｜ 作者：kuakeba.cn ｜ 适用宿主：Zsens Admin（社区版）

对接兰空图床（Lsky Pro）V1 / V2 接口：编辑器图片自动上传图床并使用外链，支持任意兰空图床 API（自行搭建或使用作者的图床）、远程图片同步、本地图片批量上图床、一键取回本地并自动改写文章图片地址。

一、功能概览

• 任意兰空 API：接口地址可自定义，兼容兰空 V2（商业版）与 V1（开源版）
• 编辑器自动上传：复制粘贴 / 手动上传的文章图片直接进图床并插入外链；上传失败自动回退本地存储，编辑器不中断
• 场景可控：可配置接管哪些上传场景（文章编辑器 / 视频封面 / 头像等），只接管图片类型
• 链接过滤：按关键字过滤指定 URL 图片链接（如指定域名/路径），命中即跳过不上传不改写
• 储存策略与相册：V2 支持指定储存策略ID（桶ID），V1/V2 均支持自定义相册ID
• 远程图片同步：已发表文章中的外链图片 → 下载 → 上传图床 → 正文改为图床外链
• 本地图片批量同步：本站本地图片全部上传到图床存储，正文改为图床外链
• 一键取回本地：图床图片下载回本站 /storage/uploads/lkstc/，正文改为本地地址，并关联图片记录（重复取回自动复用本地文件）
• 发帖自动同步（可选）：文章发布/更新后自动把正文远程与本地图片同步到图床
• 双重去重：按文件 MD5 + 来源地址去重，多篇文章共用图片只上传一次
• 批量工具断点续跑：分批处理，中断后点击重新执行可从断点继续

二、运行环境

• PHP 8.0+（本机 8.0.2 实测可用），建议开启 curl 扩展
• 已安装并启用「社区」（community）宿主插件（文章同步依赖 community_topic 表）
• 一个兰空图床账号与 API Token（自建或作者的图床均可）

三、安装

1. 把 plugins/lkstc 目录整体上传到项目 plugins/ 下。
2. 后台「应用中心 → 兰空图床 → 安装」。
3. 安装时自动创建记录表 lkstc_image 并注册后台菜单「兰空图床」。

卸载会删除记录表（不影响已上传到图床的图片与已取回的本地文件），卸载前请先备份。

四、配置项

后台「应用中心 → 兰空图床 → 配置」：

Token 获取：图床后台 → 接口 → API Tokens → 生成新 Token（勾选上传权限）。

五、后台工具（兰空图床菜单）

① 扫描文章图片

统计所有社区文章正文中的图片数量，不修改任何数据。建议先扫描评估工作量。

② 图片同步到图床

• 同步远程图片：仅处理外链图片（下载 → 图床 → 改写）
• 本地图片同步上图床：仅处理本站 /storage/ 本地图片
• 全部同步：远程 + 本地一起处理

已在图床的地址与被「链接过滤」命中的地址自动跳过；同一张图片多篇文章引用只上传一次（MD5 去重）。

③ 一键取回本地

把文章中的图床图片下载回本站 /storage/uploads/lkstc/日期/，正文改为本地地址。已取回过的图片自动复用本地文件，不会重复下载。

三个工具均为分批执行并显示进度与日志；网络中断后点「重新执行」从断点继续。取回/同步只改写 community_topic.content，操作前建议备份数据库。

六、工作原理

编辑器上传链路

wangEditor 粘贴/选择图片
  → 社区 upload 接口 → UploadService::store
    → HookService::handleUpload（本插件接管，仅图片 + 场景匹配）
      → 兰空 API 上传 → 返回图床外链写入编辑器
    → 失败返回 null → 自动回退本地存储

同步/取回链路

后台批量工具 → 分批读取 community_topic.content
  → 正则提取 <img src> → 分类（lsky/local/remote/skip）
  → 下载/读盘 → 兰空上传（或反向取回）
  → str_replace 改写正文 → 更新数据库

记录表 {前缀}lkstc_image

七、常见问题

Q：上传失败/测试连接失败？

A：依次排查：① 接口地址不要带末尾斜杠与路径；② 接口版本 V1/V2 是否选对（开源 1.x 选 V1，商业 2.x 选 V2）；③ Token 是否有上传权限且未过期；④ PHP 需开启 curl 扩展。

Q：粘贴的图片还是本地地址？

A：确认「编辑器上传自动上图床」已开启、图床配置就绪（后台首页无黄色警告）；若图床上传失败会自动回退本地存储保证编辑器可用，此时可检查 Token 后用「本地图片同步上图床」补救。

Q：某张图片不想上传图床？

A：在配置「图片链接过滤」中加入该图片地址的任意特征串（域名或路径片段），命中即跳过。

Q：同步会重复扣图床空间吗？

A：不会。按文件 MD5 + 来源地址双重去重，相同文件直接复用已上传记录。

Q：取回本地后图床上的图片会删除吗？

A：不会。取回只下载并改写正文链接，图床图片保留；如需清理请到图床后台操作。

Q：V2 的桶ID（储存策略ID）在哪里看？

A：兰空 2.x 后台 → 储存策略 → 列表中的 ID 列。留空则使用默认策略。