随机图片 API:让 Halo 每次刷新都换一张图
随机图片 API 是我给 Halo 写的第二个小插件,刚上架官方应用商店。它只做一件事:在站点上开一条你自己的路径,访问它就 302 跳到附件库里随机一张图。配好之后,正文里直接写一个
img标签指向它就行,每刷新一次换一张——不用改主题、不用写脚本、不用另找图床。
一、想要一个随机图接口,却不想为此架个服务
博客头图、每日一图、相册封面、「随便看看」入口——这些场景要的东西其实是同一个:一个每次访问都返回不同图片的 URL。
常见的三个做法都不太顺手:
- 图床 + 第三方随机图 API。 省事,但图片不在自己站点上,图床一挂全站头图跟着挂,也做不到「只在某个相册里随机」。
- Nginx 加
random_index。 能随机,但它是按目录随机文件,跟 Halo 的附件库完全是两套东西——后台传的图用不上,想在文章里按分组挑图更没法做。 - 主题里塞一段 JS 随机换
src。 只对主题页面有效,接口本身并不存在;换主题就没了,RSS、邮件、外部引用一律拿不到。
问题在于:图片本来就躺在 Halo 的附件库里,缺的只是「把它随机取出来」这一个出口。所以插件只做出口——一条路径、一个 302,别的一概不管。
二、它是怎么工作的
请求进来之后,链路很短:

拆开看是四步:
- 按请求路径匹配到一条规则;
- 规则里可选地限定存储策略和附件分组,把候选范围缩到这部分附件;
- 只留图片(优先
image/*,媒体类型缺失时看扩展名),并排除 SVG、XML、HTML; - 从候选里随机挑一张,取它的永久 permalink,返回
302 Found。
最后一步是 302,不是直接吐字节——插件不代理图片流。这个选择决定了后面很多事:S3、OSS、本地存储一视同仁,不需要给插件额外的出网权限,图片该有的 CDN 缓存、防盗链、图片处理参数一个都不丢,插件本身也不占带宽。
三、三步装上
环境要求两条:Halo >= 2.27.0、Java 21。
- 「应用市场」搜 随机图片 API → 安装 → 启用。
- 「插件 → 随机图片 API → 随机图片 API」标签页,点「添加规则」,路径填
/random/image,保存。 - 在任意文章里引用:
<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。