随机图片 API 是我给 Halo 写的第二个小插件,刚上架官方应用商店。它只做一件事:在站点上开一条你自己的路径,访问它就 302 跳到附件库里随机一张图。配好之后,正文里直接写一个 img 标签指向它就行,每刷新一次换一张——不用改主题、不用写脚本、不用另找图床。


一、想要一个随机图接口,却不想为此架个服务

博客头图、每日一图、相册封面、「随便看看」入口——这些场景要的东西其实是同一个:一个每次访问都返回不同图片的 URL。

常见的三个做法都不太顺手:

  • 图床 + 第三方随机图 API。 省事,但图片不在自己站点上,图床一挂全站头图跟着挂,也做不到「只在某个相册里随机」。
  • Nginx 加 random_index。 能随机,但它是按目录随机文件,跟 Halo 的附件库完全是两套东西——后台传的图用不上,想在文章里按分组挑图更没法做。
  • 主题里塞一段 JS 随机换 src。 只对主题页面有效,接口本身并不存在;换主题就没了,RSS、邮件、外部引用一律拿不到。

问题在于:图片本来就躺在 Halo 的附件库里,缺的只是「把它随机取出来」这一个出口。所以插件只做出口——一条路径、一个 302,别的一概不管。


二、它是怎么工作的

请求进来之后,链路很短:

一次请求的完整链路

拆开看是四步:

  1. 按请求路径匹配到一条规则;
  2. 规则里可选地限定存储策略和附件分组,把候选范围缩到这部分附件;
  3. 只留图片(优先 image/*,媒体类型缺失时看扩展名),并排除 SVG、XML、HTML;
  4. 从候选里随机挑一张,取它的永久 permalink,返回 302 Found。

最后一步是 302,不是直接吐字节——插件不代理图片流。这个选择决定了后面很多事:S3、OSS、本地存储一视同仁,不需要给插件额外的出网权限,图片该有的 CDN 缓存、防盗链、图片处理参数一个都不丢,插件本身也不占带宽。


三、三步装上

环境要求两条:Halo >= 2.27.0、Java 21。

  1. 「应用市场」搜 随机图片 API → 安装 → 启用。
  2. 「插件 → 随机图片 API → 随机图片 API」标签页,点「添加规则」,路径填 /random/image,保存。
  3. 在任意文章里引用:
<img src="/random/image" alt="随机图片" />

验证一下:

curl -I https://your-halo-site/random/image
HTTP/1.1 302 Found
Location: /upload/example.jpg
Cache-Control: no-store, no-cache, must-revalidate, max-age=0

看到 302 加一个 /upload/ 开头的 Location,就是通了。

路径怎么选:推荐两段路径(/random/image),比单段的 /random 安全得多——Halo 里主题路由、文章永久链接都可能先一步匹配,两段路径撞车的概率小一个数量级。另外 /api、/apis、/console、/upload、/archives、/tags 这些保留前缀会被直接拒掉,设置页会即时校验格式和前缀,不合规根本存不进去,不用等访问时报错才发现。


四、规则:一条路径一件事

每条规则由三个维度加一个开关组成:

配置说明
API 路径以 / 开头,形如 /random/image;保存后立即生效,不用重启插件
存储策略可选。留空不限制;选了就只从该策略取图
附件分组可选。留空=所选策略下全部可见分组;隐藏分组(头像等)自动排除
启用该规则关掉后该路径立即停止供图,规则配置保留

路径可以随时改,改完刷新页面就生效——不用重载插件,也不用重启 Halo。这一点比改主题模板舒服:接口地址是自己的,将来换主题、换存储策略、重整附件分组,正文里已经写好的 <img> 都不用动。

多条规则各管一件事,比如:

路径范围用途
/random/image全部可见图片通用随机头图
/random/wallpaper存储策略 s3 + 分组「壁纸」只在大图里随机
/random/pic分组「文章配图」给旧文章补一张随机插图

分组留空和策略留空可以叠加:两个都留空就是从全部可见附件里取,只填分组就是「不限策略、只要这个分组」,只填策略就是「这个策略下所有分组」。


五、能拿来做什么

随机头图。 最直接的用法,放在主题的 post.html 或首页模板里:

<img src="/random/image" alt="随机头图" />

因为 302 响应带 no-store,每次加载页面都会重新随机,不会出现「刷了半天还是那张」。

主题模板里当背景图:

<div class="hero" style="background-image: url('/random/image')"></div>

相册 / 每日一图。 把一组图单独放一个分组,给它一条路径,然后在独立页面里当封面用。想换一批图,只要在附件里换分组内容,接口一个字节都不用改。

RSS、邮件、外部引用。 因为它就是一个普通 URL,返回的是一次 302,所以任何能发链接的地方都能用——这点是主题里写 JS 换 src 做不到的。

当「随机推荐」用。 顺手 fetch('/random/image') 读一下响应的 redirect: 'manual',就能拿到今天这次随机到的图片地址,再拿去拼文案。


六、设置项

设置默认值说明
随机图片规则空可加多条,一条规则对应一个路径
启用该规则开启关闭后该路径立即停止供图,配置保留
API 路径—/ 开头,保存后立即生效
存储策略空留空表示不限制
附件分组空留空=所选策略下全部可见分组(不含隐藏分组)
附件列表缓存(秒)30范围 0–3600;0 表示每次请求都重新查附件表

七、几个不太显眼但值得说的处理

只挑图片,而且刻意排除 SVG。 优先看 image/* 媒体类型,缺失时按扩展名判断;SVG、XML、HTML 一律排除。这三类都能内联脚本,被同源引用就是个 XSS 入口——随机图这种「内容自己可控、请求方不可控」的接口,不该给它们开口子。

302 不被缓存,图片照常缓存。 no-store、no-cache、max-age=0 只加在 302 响应上,跳转过去的图片该由 CDN 和存储服务决定缓存策略。两件事分开管,不会互相污染。

附件名单有短 TTL 缓存,并合并并发请求。 头图这种位置,一次页面加载可能被十几个人同时打到。每次请求都扫一遍附件表并不划算,所以名单在内存里缓存默认 30 秒,并发的请求会合并成一次查询。代价是新传的图最多晚一个缓存周期出现,急着看就把缓存设成 0。

用公开 permalink,不用预签名链接。 这是「跳转后图片能一直看」的前提。签名链接会过期,permalink 不会,所以不会出现「昨天还好好的,今天全变 403」。

升级不碰数据。 升级不改附件、不清设置,规则原样保留;卸载也不会删除任何附件,只让路径失效。


八、几个需要提前知道的限制

  • 存储桶必须可公开读。 插件不代签链接,私有桶里的图会 302 到一个 403 的地址。用 S3 兼容存储的话,记得把桶或访问域名设成公开读。
  • 目标图片的缓存跟插件无关。 no-store 只管 302 那一下;如果 CDN 把目标图片缓存住了,它还是缓存着。想固定用某张图,直接写附件 permalink。
  • 新传 / 新删的图有延迟。 最多一个缓存周期,原因见上一节。
  • 路径可能和主题路由撞车。 Halo 里主题路由优先匹配,撞上了就换个路径,两段路径基本不会遇到。
  • 接口是公开只读的,没有鉴权、没有限流、没有防盗链。它只返回 302,不返回附件元数据,但如果你的图片本身不该被公开枚举,就别把它接到随机接口上。
  • 它不是图床。 不管上传、不管压缩、不管格式转换,也不关心你的图片有多大。

九、隐私

这一节写得比较细,因为「随机」「API」两个词容易让人联想到第三方图源。实际情况是:

  • 不收集、不上传、不共享任何站点数据或访客数据;
  • 不发起任何外部网络请求,没有遥测、统计、崩溃上报;
  • 只从 Halo 附件库读图片名称和公开访问地址,不读取图片内容;
  • 服务端日志只记录规则路径、存储策略名和错误原因,不含访客信息;
  • 接口只回一个 302,不返回附件列表、不返回元数据。

插件本身没有任何外部依赖,也不加载 CDN、外部字体和统计脚本。


✅ 总结:随机图片 API 补的是 Halo 一直缺的一个小口子——附件库里的图,需要一个不依赖主题的取用方式。一条路径、一个 302、多重规则、零外部依赖、数据不出站。如果你的头图已经三年没换过,或者相册里的图从来没人点进去看,装上它,改一行 <img src> 就行。

应用商店:https://www.halo.run/store/apps/app-uau1i3so | 开源仓库:litxiaoxi/halo-plugin-random-image-api(MIT)

用下来有任何问题或者想要的功能,欢迎在仓库提 issue。