ADCakeyuan's blog

截图变成一条不会失效的链接:PixNest 图床制作记

Published on
//
12 分钟读完
/
TL;DR

PixNest 制作记:为什么用 Pages + KV 而不是 R2,内容寻址去重怎么实现,直链缓存与删除如何配合,以及 1GB / 1000 次写入的免费额度意味着什么。

写博客、写 Issue、写周报,最容易被忽略的基础设施是图片链接。截图存在本地,发出去对方打不开;传到第三方图床,过两年站点没了,文章里的图全变成裂图。更隐蔽的是防盗链和限速:自己的文章,读者打开却是一片灰色占位符。

PixNest 是给这个问题写的一个私有图床。Cloudflare Pages 托管前端和 Functions,KV 存图片,Hono 负责路由。粘贴、拖拽或点选上传,返回一条可以直接嵌进 Markdown 的直链。管理需要令牌,直链公开——这是刻意的分工。全部代码 633 行,唯一的运行时依赖是 Hono,部署在 Cloudflare 免费档上,不需要绑卡。

PixNest 首页与图库

截图来自本地 wrangler pages dev,图库里的图片是通过同一套 Functions 真实上传的。

存储层:为什么是 KV,不是 R2

这个项目最早按「R2 图床」设计。真正落地时换成了 KV,原因很具体:R2 的免费额度更大(10GB),但开通需要绑定支付方式;KV 免费档只有 1GB,却不需要绑卡。对一个个人图床来说,这个差别比 10 倍容量更重要。

免费档的限制是:1GB 总量、每天 10 万次读、1000 次写。看起来读写都不宽裕,但直链不直接打 KV:第一次请求回源,之后由边缘缓存接住。命中缓存的请求不计 KV 读,日常阅读量基本碰不到 10 万的上限。真正先到顶的是 1GB 容量和每天 1000 次写入——按每张截图 100–500KB 算,1GB 能放几千张,一天传 1000 张则远超个人使用。

KV 不是对象存储,有些地方必须绕着走:没有 head(),判断对象是否存在只能 list({ prefix, limit: 1 });列出键是游标分页,不是数据库查询;元数据只能塞很短的 JSON。代码里存的元数据只有文件名、大小、MIME 和上传时间,刚好够图库页展示。

如果哪天图片超过 1GB,或者要给别人开多个账号,就该换 R2:容量更大、S3 兼容、能配生命周期规则。但在「免费、免绑卡、个人用」这三个约束下,KV 是更合适的那个。

内容寻址:同一张图只存一次

上传时先把文件读成 ArrayBuffer,用 Web Crypto 算 SHA-1,取前 16 个十六进制字符,加上扩展名作为 key:

const digest = await crypto.subtle.digest('SHA-1', buf)
const hash = [...new Uint8Array(digest)]
  .map((b) => b.toString(16).padStart(2, '0'))
  .join('')
  .slice(0, 16)
const key = `i/${hash}.${ext}`

16 个十六进制字符是 64 位,个人图床的规模下碰撞概率可以忽略,换来的是更短的 URL。扩展名来自 MIME 白名单(png / jpg / webp / gif / svg / avif),MIME 不认识时退回文件名后缀,两者都不认识就拒绝。

去重就靠这个 key。KV 没有 head(),所以写入前先 list({ prefix: key, limit: 1 }):存在就跳过写入,响应里带上 deduped: true,前端显示「去重命中」;不存在才 put,同时写入元数据。同一张图无论改多少次文件名、传多少次,都只占一份空间,链接也始终是同一条。

去重命中与三种复制格式

内容寻址还有一个副作用,恰好是直链设计需要的:URL 由内容决定,内容不变 URL 不变,内容一改哈希就变。所以一条图片 URL 指向的字节永远不会变,可以放心给它一年期的 immutable 缓存。

KV 的最终一致性在这里会露一次头:刚上传的图片,list 可能还没看到,去重判断会漏报,返回 deduped: false 并再写一次。因为 key 相同,写入只是覆盖同样的字节,不会产生冗余,也不会改变链接。这个「错误」不影响正确性,只是让标记短暂不准。

直链:公开、强缓存、可删除

直链路由是 GET /i/:key,不经过令牌中间件。key 先过一遍格式校验:/^[a-f0-9]{8,40}\.[a-z0-9]{2,5}$/i,只允许「十六进制哈希 + 扩展名」,挡住路径穿越和随手构造的 key。

真正的读取顺序是:先查 caches.default,命中直接返回;未命中再 IMAGES.getWithMetadata(key, { type: 'arrayBuffer' }) 回源 KV。响应头由元数据拼出来:

Content-Type: image/png
Cache-Control: public, max-age=31536000, immutable
ETag: "ff860581ef6e42e7.png"

写缓存用 ctx.waitUntil(cache.put(...)),不阻塞响应;回源一次之后,同一个边缘节点上的后续请求就不再碰 KV。ETag 直接用 key,既短又天然唯一。

删除同时做两件事:删 KV 里的对象,再 caches.default.delete('/i/<key>')。但这里有一个必须说清楚的边界:Cache API 的删除只作用于当前数据中心,它不是全局 purge。KV 删除后回源一定是 404,可其他机房的缓存副本仍可能在 TTL 内继续返回旧图。不常用 query 参数的话,正常直链没有这个问题;一旦 URL 带了 ?v=2,缓存键就变了,删除也清不到那份副本。

这是「免费 + 强缓存」的代价:删除是尽力而为,不是全球秒级生效。要硬删除,得换 R2 并调用 Cloudflare 的缓存清除接口,或者用带版本的 URL 让旧链接自然淘汰。

同一份代码里还有一个取舍:允许上传 SVG,并原样以 image/svg+xml 返回。放在 <img> 里不会执行脚本,但如果有人直接打开直链,SVG 内的脚本会在站点同源下运行。令牌把上传者限制成了站主自己,所以实际风险可控;如果以后开放注册,SVG 就该关掉或加 CSP。

鉴权:一把令牌,写操作全关,直链全开

所有 /api/* 都过一个 Bearer 令牌中间件:

const parts = (c.req.header('Authorization') || '').split(/\s+/).filter(Boolean)
const token = parts.length === 2 && /^Bearer$/i.test(parts[0]) ? parts[1] : ''
if (!c.env.UPLOAD_TOKEN || !token || token !== c.env.UPLOAD_TOKEN) {
  return c.json({ success: false, error: 'Unauthorized' }, 401)
}

两个细节。第一,!c.env.UPLOAD_TOKEN 也拒绝——忘记配置环境变量时,站点是「全关」而不是「裸奔」。第二,令牌只保护写操作和图库列表,/i/:key 不设防,因为图床的意义就是把链接发给别人。安全模型不是访问控制,而是「URL 不被猜到」:64 位哈希对个人图床足够,但任何拿到链接的人都能看图,敏感图片不该传。

令牌设置弹窗

令牌保存在浏览器 localStorage,401 时自动弹出设置框;curl 和 PicGo 则直接在 Header 里带 Authorization: Bearer <token>。没有多用户、没有限流、没有防爆破——一把长随机令牌,一个站主,够用就行。

前端:三种上传姿势,一个串行队列

拖拽、Ctrl+V 粘贴、点击选择,最后都汇到同一个 handleFiles:先按 MIME 过滤,再检查令牌,然后一张一张传。队列是串行的,uploading 标志阻止并发上传;上传用 XMLHttpRequest 而不是 fetch,只因为前者能拿到上传进度事件。

每张图上传完生成一张结果卡,带 URL、Markdown、HTML 三种复制格式;图库用 KV 的游标分页,每页 60 张,「加载更多」只在 list_complete 为 false 时出现。顶部显示的「已加载 N 张 · 总体积」只统计当前已加载的页,不是全库统计——这是分页图库诚实的写法。

上传结果与图库

整个前端 271 行 JavaScript,没有框架、没有构建步骤;后端 160 行 TypeScript,Hono 负责 /api 下的路由,Pages Functions 只做两件事:把 /api/* 交给 Hono,把 /i/:key 交给图片处理函数。

免费额度的真实边界

把项目跑起来只需要三步:建 KV 命名空间、在 wrangler.jsonc 填 ID、在 Pages 环境变量里设 UPLOAD_TOKEN。npx wrangler pages deploy public 就能上线。但免费档不是没有代价:

  • 1GB 是硬上限:存满之后新图写不进去,图库页会显示已加载体积,但不会替你自动清理。
  • 每天 1000 次写入:批量导入几千张图会撞墙,需要分几天传。
  • 单张 10MB、六种格式:HEIC 不在白名单里,iPhone 原图要先转一道。
  • 最终一致性与缓存删除:去重标记可能短暂漏报;删除不是全球即时生效。
  • 没有图片处理:不压缩、不生成缩略图、不转换格式,直链就是原图,流量和存储都按原图算。

这些限制写在 README 里,也写在代码里。它们不是「以后优化」的待办,而是这套免费架构的边界。知道边界在哪,用起来反而安心:1GB 用完就清理,需要更多就换 R2,迁移的路径是现成的。

PixNest 解决的问题很小:让一张截图有一条不会因为第三方跑路而失效的链接。它不追求成为图床产品,只是把「上传—拿链接—嵌进文章」这条路径缩到最短,并且把数据放在自己掌控的存储里。

源码在 GitHub,在线版在 这里(直链公开,管理需要令牌)。

本文由 AI 自动写作流水线生成;文中的上传、去重、删除与缓存行为均在本机 wrangler pages dev 环境中实际运行验证,截图来自该环境。