API 图库插件更新日志（1.0.0 → 1.4.2）

开源地址：https://github.com/lu7875/halo-plugin-api-gallery ｜ 当前版本 1.4.2 插件包下载：https://github.com/lu7875/halo-plugin-api-gallery/releases/download/v1.4.2/api-gallery-1.4.2.jar

1.4.2（2026-11-04）

上架前复查整改版本：补齐 3xx 相关地址链路的校验，并让诊断接口与上架材料中的脱敏声明完全一致。

安全

• 响应中的图片地址统一校验：1.4.1 已修复「自动跟随 302/307 导致跳转到内网」的服务端请求问题。复查发现 302 随机图源会把 Location 当作图片地址写入缓存与图库，200 兜底文本和随机单张 JSON 的 url 字段也是同类外部地址，此前未做校验。现在这三类地址都会先按当前响应地址归一为绝对 URL，再执行与跳转目标相同的「协议 + 主机 + DNS 解析 IP」校验；指向内网、回环、云元数据或非 http 协议的地址直接丢弃。列表型图源 JSON 里的 url 属业务数据字段（服务端不请求、仅由访客浏览器加载），保持兼容不做 DNS 级校验。
• 诊断接口脱敏与声明对齐：/diagnose 不再回显响应首行内容（firstRow）与异常消息（message），改为只给第一行的字段名 rowFields；异常只回类名；补齐 contentType 字段。

修正

• 后台设置「作者博客」改为「作者主页」，说明文字改指向 GitHub 仓库 Issue。
• 补建 GitHub Release v1.4.2 并附上插件包，下载直链可直接用于上架。

测试

• 新增 4 个用例：302 Location 指向云元数据 / file:// 被丢弃、合法 Location 正常采集、随机 JSON 中的内网图片地址被丢弃。全量 53 个测试通过。

1.4.1（2026-11-03）

本版本修复应用市场审核发现的 SSRF 跳转绕过问题，并修正上架材料中的失效链接。

安全

• 修复 302/307 跳转绕过 SSRF 防护：此前只校验后台配置的初始地址，而 HTTP 客户端会自动跟随 3xx 跳转，跳转后的目标地址不再校验。恶意图源可先返回公网地址，再在 Location 里指向内网、回环或云元数据地址。现改为所有对外请求关闭自动跟随（Redirect.NEVER），手动逐跳跟随，每跳重新执行「协议 + 主机 + DNS 解析 IP」校验，最大 5 跳防重定向循环，Location 支持相对路径与协议相对路径。

修正

• 上架材料中的源码仓库、问题反馈链接统一为 https://github.com/lu7875/halo-plugin-api-gallery；作者主页与插件主页改为可访问的 GitHub 地址。
• 补充 AI 辅助编码与人工复查声明。

1.4.0（2026-10-26）

本版本为安全整改版本，建议所有使用者升级。

安全

• 收紧匿名访问范围：新增独立的 console.gallery.halo.run 接口组承载管理类接口，与该组相关的 /sources、/diagnose、/sync、/push-to-photos、/photos 不再向访客放行。对外公开组 api.gallery.halo.run 现在只剩 /items 与 /random 两个只读接口。此前匿名访客可直接调用 /diagnose 触发服务端对外请求并读到图源地址与错误信息。
• 诊断结果脱敏：/diagnose 不再返回响应正文（bodyHead）与调用堆栈（stackTop），改为返回 bodyLength 与 looksLikeJson 这类结论性字段。
• 新增图源地址 SSRF 防护：所有对外请求发出前统一校验——仅允许 http/https 协议，并拒绝回环地址、私有网段（10/8、172.16/12、192.168/16）、链路本地与云厂商元数据地址（169.254.0.0/16）、IPv6 唯一本地地址（fc00::/7）、组播与保留网段。命中时该数据源会被标记为不可用，同步时记录明确的拒绝原因。

修复

• 补齐前台展示页制品：此前 gallery.html 放在源码根目录，static/ 与 ui/ 均为空目录，打成 JAR 后不存在。现已移入 src/main/resources/static/，并补充 extensions/reverseProxy.yaml（Halo 不会自动暴露插件的 static 目录，必须声明 ReverseProxy 才能访问）。实际访问地址：/plugins/api-gallery/assets/static/gallery.html。
• 展示页不再依赖需要授权的 /sources，来源筛选改为从已加载数据推导，访客可直接访问。

变更

• 开源信息统一：补充 MIT LICENSE 文件并打入 JAR，plugin.yaml 增加 repo 与 issues 字段。

注意

• /sources、/diagnose 等接口路径已迁移到新的管理组，若你在脚本中调用过这些地址，需把 api.gallery.halo.run 换成 console.gallery.halo.run。公开接口不受影响。
• 使用 PAT 调用时需确认令牌授权范围包含对应接口组，否则会返回 403。

1.3.1（2026-10-25）

新增

• 后台设置页新增「关于」分组，展示作者博客与作者信息。
• 补充插件简介描述。

说明

• 本版本仅涉及后台展示信息与文案，功能与 1.3.0 一致。
• 升级会重启插件，内存缓存清空后自动重新累积，属正常现象。

1.3.0（2026-10-25）

修复

• 图库攒满后就不再更新（核心问题）：旧版本同步时把旧缓存排在前面、新采样的图排在后面，达到「最多累积」上限后被截断丢弃的永远是新图，留下的全是老图。结果就是：图池一旦攒满，即使定时同步照常运行，图库内容也永久静止。现改为滚动更新：新采样的图排在最前面，达到上限时淘汰最老的，每一轮同步都会换进一批新图。

新增

• 被滚动淘汰的旧图会同步从「图库管理」插件中删除，避免 /console/photos 里的记录只增不减。

建议配置

1.2.0（2026-10-25）

修复

• 后台修改同步周期后不生效：旧版本只在插件启动时读一次周期，把 60 分钟改成 5 分钟后仍按 60 分钟跑。现改为保存设置时立即按新周期重新排期，无需重启插件。

新增

• 响应结构新增「随机单张 JSON」类型：适用于每次请求返回一张随机图的 JSON 接口。
• 同步状态对外可见：/sources 与 /diagnose 新增 intervalMinutes（当前实际生效周期）、nextSyncAt（下次同步时间）、secondsUntilNextSync（距下次同步秒数）、lastSync、errors。

1.1.0（2026-10-25）

新增

• 响应结构新增「302 跳转到随机图片」类型：适用于没有列表接口、每次请求直接 302 跳转到一张随机图的图源。插件会重复采样若干次、收集每次的跳转地址并去重，攒成一个图集。
• 随机类图源新增「采样次数」「最多累积」两项配置。
• 随机类图源拉取失败时保留已攒下的图，不会清空。

1.0.0（2026-10-25）

首个版本。

• 后台配置任意数量的图片 API 数据源，各自独立开关
• 自动识别顶层数组 / {items:[...]} / 单个对象三种响应结构
• url、id、title、tags 字段名可单独指定，留空自动推断
• 定时同步（默认 60 分钟，可调 5–1440 分钟），后台保存后即时触发
• 自动为匿名用户放行只读接口，前台无需登录即可展示
• 对接官方「图库管理」插件，把图片地址写成 Photo 记录，不占本地存储
• 对外接口：/items、/sources、/random、/sync、/push-to-photos、/photos
• 附带自包含展示页（瀑布流 + 懒加载 + 灯箱 + 按源筛选）