Halo 附件存储接入兰空图床商业版 v2
Halo 附件存储接入兰空图床商业版 v2
[!TIP] 把 Lsky Pro 兰空图床 变成 Halo 的附件存储后端：支持开源版 v1 与商业版 v2 双 API，并补齐删除同步、云处理缩略图、自动归档等原版缺失能力。装完，Halo 上传的图片就直接进你自己的图床。
一、这是什么
halo-lsky-pro 是一个 Halo 插件：装上之后，你在 Halo 后台「附件」上传的图片不再存服务器本地，而是直接传到你的兰空图床，并返回图床访问链接。
本仓库是 ichenhe/halo-lsky-pro 的 fork（原版仅支持开源版 v1 API），在原版基础上新增了商业版 Lsky Pro v2 API 的完整支持，并修掉几个历史遗留问题。
| 项目 | 说明 |
|---|---|
| 上游仓库 | ichenhe/halo-lsky-pro |
| 本 fork | lqbby/halo-lsky-pro |
| 插件名 | chenhe-lsky-pro（后台显示「Lsky Pro 兰空图床」） |
| 兼容 Halo | >= 2.22.0 |
| 许可证 | GPL-3.0 |
二、上传流程一图看懂
你在 Halo 后台上传图片附件
│
▼
halo-lsky-pro 插件
│
├── v1 开源版 --> POST /api/v1/upload （参数 strategy_id）
│
└── v2 商业版 --> POST /api/v2/upload （参数 storage_id，必填）
│
▼
兰空图床存储
│
▼
返回图床访问链接
│
▼
Halo 列表 / 网格缩略图（?w=400 ~ 1600）
三、核心功能
3.1 开源版 vs 商业版
| 能力 | v1（开源版） | v2（商业版） |
|---|---|---|
| 上传接口 | POST /api/v1/upload |
POST /api/v2/upload |
| 策略参数名 | strategy_id |
storage_id（必填） |
| 删除同步 | DELETE /api/v1/images/{key} |
DELETE /api/v2/user/photos（按 ID 数组） |
| 缩略图 | ❌ 不支持 | ✅ 云处理 ?w={宽度} |
| 自动归档相册 | ❌ | ✅ 按 yyyy-MM 自动建相册 |
| 去 EXIF / 公开图片 | ❌ | ✅ is_remove_exif / is_public |
3.2 本 fork 相比原版新增
| # | 功能 | 说明 |
|---|---|---|
| 1 | v2 API 支持 | 商业版图床直接可用，添加策略时选 API 版本即可 |
| 2 | 删除同步 | v2 删除走 DELETE /api/v2/user/photos，Halo 删附件时图床文件同步删除 |
| 3 | 文件大小回填 | v2 响应不含 size，插件统计真实字节数回填，Halo 附件大小正确 |
| 4 | 云处理缩略图 | S/M/L/XL 四档（400/800/1200/1600），列表/网格不再拉原图 |
| 5 | 上传参数扩展 | 「去 EXIF」「设为公开图片」两个开关 |
| 6 | 按日期自动归档 | 未指定相册时按 yyyy-MM（如 2026-09）自动创建/复用 |
| 7 | storage_id 前置校验 | v2 缺 storage_id 时给中文友好报错，而非模糊 422 |
| 8 | 修复布尔校验 | is_public/is_remove_exif 改传 1/0，修复 Laravel 严格校验 422 |
四、安装
4.1 下载插件
从 GitHub Release 下载最新 jar：
https://github.com/lqbby/halo-lsky-pro/releases
例如 v1.3.4：
https://github.com/lqbby/halo-lsky-pro/releases/download/v1.3.4/halo-lsky-pro-1.3.4.jar
4.2 安装到 Halo
- 进入 Halo 后台 → 插件
- 点右上角 安装 → 选择下载的
.jar文件 - 等插件加载完成，状态变「已启用」
[!TIP] 插件启用后无需在设置页做任何配置，直接去「附件 → 存储策略」添加策略即可。
五、配置教程
5.1 前置准备：拿齐三件套
| 需要的东西 | 在哪拿 |
|---|---|
| 图床地址 | 兰空访问地址，如 https://tc.example.com |
| API Token | 见下方「获取 Token」 |
| 储存策略 ID（v2 必填） | 兰空后台「储存」页，进某策略，URL 里的数字即 ID |
开源版（v1） 通过 API 接口申请：
curl --location --request POST 'https://example.com/api/v1/tokens' \
--form 'email="your-email"' \
--form 'password="your-password"'
商业版（v2） 在兰空前台个人中心 → API 设置里直接生成 Token（通常是 1|xxxxx 或 Bearer xxx 格式）。
[!TIP] 实用技巧：后台「储存」页没直接显示数字 ID 的话，按 F12 打开开发者工具，点进某个储存策略，看地址栏或 Network 请求里的
id。相册 ID 同理。
5.2 添加存储策略
Halo 后台 → 附件 → 存储策略 → 新建策略，选「Lsky Pro 兰空图床」：
| 字段 | 填什么 |
|---|---|
| Lsky Pro 地址 | 图床地址，如 https://tc.example.com（不带 / 和 api 后缀） |
| API 版本 | 开源版选 v1，商业版选 v2 |
| API Token | 上一步拿到的 Token |
| 储存策略 ID | v2 必填，填后台查到的数字 ID |
| 相册 ID | 可选，留空则不指定相册 |
| 按日期自动归档到相册 | v2 专属开关 |
| 移除图片 EXIF 信息 | v2 专属开关，去隐私 |
| 设为公开图片 | v2 专属开关，控制广场可见性 |
| 实例 ID | 建议手动设固定值（见下文） |
填完点 验证图床设置，提示通过后保存。
5.3 关键字段说明
① 按日期自动归档：勾选后若「相册 ID」留空，插件自动按上传月份归档到 2026-09 这样的相册（不存在则自动创建），图床相册按月自动整理。
② 移除 EXIF：上传时剥离 GPS 定位、设备型号等元信息，适合直接传手机 / 相机原图。
③ 实例 ID（重要）：Halo 允许一个插件建多个存储策略，插件靠「实例 ID」判断附件归哪个 Lsky 实例，删除时才能正确同步。每个附件上传时记录当时的实例 ID，永不改变。
[!WARNING] 建议一开始就手动设一个固定值（如
lsky-main）。默认值跟图床地址绑定，一旦地址变更，旧附件会失去关联，删除时无法同步删除图床文件。
六、新增功能详解
6.1 云处理缩略图（v2 专属，最有价值）
Halo 的文章列表、网格视图会按 S=400 / M=800 / L=1200 / XL=1600 四档宽度请求缩略图。原版插件这一块是空实现，等于列表页每次都拉原图，又慢又费流量。
本 fork 通过商业版云处理能力，用 ?w={宽度} 参数动态生成四档缩略图：
原图：https://tc.example.com/i/xxx/abc.jpg
S：https://tc.example.com/i/xxx/abc.jpg?w=400
M：https://tc.example.com/i/xxx/abc.jpg?w=800
L：https://tc.example.com/i/xxx/abc.jpg?w=1200
XL：https://tc.example.com/i/xxx/abc.jpg?w=1600
[!CAUTION] 前提：必须在兰空后台开启「云处理 → 支持参数
w」（默认关闭）。官方提示随意开启w可能被他人利用来刷图（构造不同宽度 URL 反复请求），建议配合 CDN / 反代做访问控制。
6.2 删除同步
- v1：
DELETE /api/v1/images/{key}，用图片key删除； - v2：
DELETE /api/v2/user/photos，body 传图片id数组，返回204。
插件自动记录每张图的删除标识（v1 用 key、v2 用 id），Halo 里删附件时图床文件同步删除，不留孤儿文件。
6.3 文件大小回填
商业版 v2 的上传响应不返回文件大小，而 Halo 需要这个值展示附件大小。插件改为上传时统计真实字节数回填，让 Halo 显示的大小与实际一致。
6.4 上传参数扩展
| 插件开关 | 兰空参数 | 作用 |
|---|---|---|
| 移除图片 EXIF 信息 | is_remove_exif |
剥离隐私元信息 |
| 设为公开图片 | is_public |
控制图片在广场是否公开 |
七、注意事项 / 常见问题
- v2 上传必须填「储存策略 ID」：
storage_id是商业版上传必填参数，留空会报错。 - 缩略图要开云处理
w：不开则缩略图功能不生效（插件回退用原图）。 - 图床端别开「格式转换/压缩」：否则 Halo 显示的附件大小会不准（统计的是原始字节数）。
- 仅支持图片附件：受兰空限制，其他附件用 Halo 本地存储或别的插件。
- 实例 ID 别乱改：中途改会导致之前图片无法关联，删除时无法同步。
八、版本历史
| 版本 | 主要变更 |
|---|---|
| v1.3.2 | fork 基础版，支持 v2 API（storage_id 参数、多种状态格式兼容） |
| v1.3.3 | ✅ v2 删除同步、文件大小回填、storage_id 必填前置校验 |
| v1.3.4 | ✅ 云处理缩略图、去 EXIF/公开图片、按日期自动归档 |
| (hotfix) | ✅ 修复 is_public/is_remove_exif 传 Boolean 导致的 422 布尔校验报错 |
九、相关链接
- 仓库地址：https://github.com/lqbby/halo-lsky-pro
- 下载地址：https://github.com/lqbby/halo-lsky-pro/releases
- 上游仓库：https://github.com/ichenhe/halo-lsky-pro
- 问题反馈：https://github.com/lqbby/halo-lsky-pro/issues
[!NOTE] 本文基于
halo-lsky-prov1.3.4 + hotfix 编写。
