A lightweight JSDelivr Proxy with cache.
轻量级 JSDelivr 反代:回源 jsDelivr(或可自定义的镜像),并把资源缓存在进程内(TTL 2 小时)。 不依赖任何外部服务——没有 Redis,也不需要 MySQL / RabbitMQ,一个二进制即可运行。
HTTP 层基于 axum 0.8 + tower-http,
缓存基于 moka 0.12(future 特性)。
请求 /avatar/<hash>?s=200&d=identicon 即可代理头像;支持的参数见
Gravatar 官方文档。
[gravatar]
upstream = "https://www.gravatar.com"可通过 JSDRLIVR_PROXY_GRAVATAR_UPSTREAM 环境变量指定上游。
上游为基础 URL,可包含路径前缀;请求会在其后追加 /avatar/<hash> 并透传查询参数。
省略配置时使用上面的默认值。
Gravatar 与 jsDelivr 共用 [cache] 配置及缓存实例,包括 TTL、容量预算、内容去重、
压缩、流式返回和并发合并回源;只有成功且完整下载的响应才会缓存。
头像缓存键为 avatar/<hash> 加原始查询字符串,不同尺寸或默认头像参数分别缓存。
可在现有管理面板查看,或按 avatar/ 前缀清除所有头像缓存。
jsdelivr.allowlist 和 jsdelivr.referer_check 仅作用于 jsDelivr 请求。
- TTL 2 小时:每个 path 独立过期,命中不续期;预加载刷新只续期对应 path。
- 内容去重:path 映射到原始正文的 BLAKE3 摘要,相同正文只存一份压缩数据, 例如内容相同的 GitHub tag 与 HEAD。Content-Type 仍按 path 保存。 映射和正文共用字节预算;正文淘汰后访问对应 path 会重新回源。 新增或续期映射时会续期共享正文,但不影响其他 path 的 TTL。 按 path 清除只删除映射,无引用正文保留到自身 TTL 到期或容量淘汰;清空缓存则同时删除两者。
- 按字节计容:
max_capacity_mb是整个缓存的字节预算(moka 的容量单位是 weigher 权重,本项目的 weigher 返回条目的实际字节数),默认 256MB。 - 单条目上限:超过
max_entry_size_mb(默认 16MB)的资源仍会正常返回给客户端, 但不会进入缓存,避免单个超大文件挤占整个预算。 - 条目压缩:缓存里的响应体默认用 zstd 压缩(
compression,可选none/zstd/brotli),上面两项预算都按压缩后的体积核算。 - 异步填充:首个未命中请求收到上游响应头后即可流式返回,完整下载后在后台压缩入库;下载失败不会缓存残缺正文,客户端断开后仍继续填充。
- 并发合并回源:同一路径的后续未命中请求等待正在进行的缓存填充,完成后读取缓存。
- 淘汰策略是 moka 的 W-TinyLFU(带准入过滤的近似 LRU),而不是严格的 LRU。
管理面板区分可用路径数、独立正文数与无引用正文,展示共享正文节省的压缩后字节数。 正文压缩比只比较去重后的原始正文与压缩正文,不计映射和摘要开销。 列表展示正文摘要及全缓存中的共享路径数(不受前缀筛选影响);每行大小包含完整正文,不能相加作为总占用。 按路径清除后的提示会说明正文仍可保留,清空全部则释放两类条目。
管理接口的 entry_count 统计可用 path 数,stored_bytes 统计映射和去重后的正文占用。
body_count、body_stored_bytes 和 raw_bytes 分别统计保留的独立正文数、压缩正文体积和原始体积,包含无引用正文;
orphan_body_count 和 orphan_stored_bytes 单独统计无引用正文数量及占用(含摘要键)。
deduplicated_bytes 统计有效映射共享正文节省的压缩后字节数,不计元数据。
列表增加 checksum(BLAKE3 十六进制摘要)和 shared_paths(全缓存有效引用数)。
.js / .css / .json 这类文本资源 zstd 通常能压到 1/3 ~ 1/4,
等于同样的 max_capacity_mb 能装下三四倍的热点文件;
命中时根据请求的 Accept-Encoding(包含 q=0 与通配符)判断客户端能力,
支持缓存编码时直接发送 zstd / Brotli 字节,并设置 Content-Encoding 和 Vary: Accept-Encoding。
不支持时才解压,交给全局响应压缩器协商 gzip、Brotli、zstd 或 deflate;
未声明编码能力时返回未压缩内容。全局压缩器也处理回源流及其他路由的响应,已编码的响应不会重复压缩。
compression |
说明 |
|---|---|
zstd(默认) |
压缩率与速度均衡,解压吞吐在 GB/s 量级 |
brotli |
文本压缩率略高于 zstd,压缩慢得多;固定 quality 5 |
none |
不压缩,命中路径是零拷贝,内存里存的就是原始字节 |
已经压过的资源(woff2、png、wasm 等)压不动时会原样存放,
因此开启压缩不会让缓存占用反而上升。压缩等级与字典目前不可配置。
权衡(相对 Redis 版本的退步):缓存位于进程内,重启即全部丢失; 多副本部署时各副本各自持有一份缓存,不再共享,回源次数会随副本数上升。 由于回源是幂等的只读操作,这只影响缓存命中率,不影响正确性。 如果确实需要跨副本共享缓存,建议在本服务前面再放一层 CDN / 反代缓存, 而不是让服务本身重新背上一个有状态依赖。
公网部署时,一个不设限的 jsDelivr 反代等于一台任何人都能白嫖的开放代理: 别人只要把域名换成你的,就能用你的带宽和 IP 分发任意 jsDelivr 资源。 白名单让运维方把代理钉死在自己的包 / 仓库上。
默认不限制:不写 [jsdelivr.allowlist](或三个列表全为空)时行为与之前完全一致,
老部署升级上来不受任何影响。只要任意一个列表非空,白名单即生效,
未命中的请求在读缓存与回源之前就被拒绝(返回 403,不产生上游流量,也不会污染缓存),
并以 warn! 记录被拒绝的路径。
[jsdelivr.allowlist]
# 允许的 provider;留空 = 不限制 provider
providers = ["npm", "gh"]
# 允许的 npm 包;留空 = 该 provider 下所有包都允许
npm = ["vue", "@hitokoto/core", "@hitokoto"]
# 允许的 GitHub 仓库;留空 = 该 provider 下所有仓库都允许
gh = ["hitokoto-osc", "hitokoto-osc/sentences-bundle"]匹配规则:
| 配置项 | 条目形式 | 含义 |
|---|---|---|
providers |
npm |
放行该 provider |
npm |
vue |
精确匹配包名 |
npm |
@hitokoto/core |
精确匹配 scoped 包 |
npm |
@hitokoto |
匹配该 scope 下的所有包 |
gh |
hitokoto-osc |
匹配该 owner 的全部仓库 |
gh |
hitokoto-osc/sentences-bundle |
精确匹配单个仓库 |
几个必须知道的细节:
- 版本号先剥离再匹配:
npm/vue@3.5.0/dist/vue.js按vue判定; scoped 包的@scope是独立片段,@scope/pkg@1.2.3能被正确拆开。 combine/会被拆开逐个校验。/combine/npm/a@1/x.js,npm/b@2/y.js在一次请求里打包多个资源,只校验最外层路径等于给整个白名单开后门; 本实现按,拆分后对每一个分量套用完整规则,任意一个不通过就整体 403。- 匹配不区分大小写(GitHub 的 owner/repo 大小写不敏感),
且严格按片段整体比较:
hitokoto-osc不会匹配hitokoto-osc-evil,@hitokoto也不会匹配@hitokoto-evil——前缀匹配是白名单最经典的绕过方式。 - 无法按资源粒度识别的 provider(
wp、esm等)在白名单生效时, 必须显式写进providers才会放行;无法解析的路径一律拒绝。
对应的环境变量(列表用逗号分隔):
配置文件([jsdelivr.allowlist]) |
环境变量 |
|---|---|
providers |
JSDRLIVR_PROXY_JSDELIVR_ALLOWLIST_PROVIDERS |
npm |
JSDRLIVR_PROXY_JSDELIVR_ALLOWLIST_NPM |
gh |
JSDRLIVR_PROXY_JSDELIVR_ALLOWLIST_GH |
JSDRLIVR_PROXY_JSDELIVR_ALLOWLIST_PROVIDERS="npm,gh" \
JSDRLIVR_PROXY_JSDELIVR_ALLOWLIST_NPM="vue,@hitokoto" ./jsdelivr_proxy环境变量方式仅在不使用
-c <配置文件>时生效(-c会关掉环境变量 source, 这是既有行为)。列表键的逗号拆分在src/conf/mod.rs的LIST_VALUED_KEYS中登记。
可选校验资源请求的来源域名,默认关闭。启用后在读取缓存和回源之前校验,
不符合规则的请求返回 HTTP 403;管理接口、Webhook、首页和 /about 等独立路由不受影响。
[jsdelivr.referer_check]
enabled = true
allow_empty = false
domains = ["example.com", "www.example.com"]domains 只填写域名,不带协议、端口、路径或通配符。仅接受 HTTP/HTTPS Referer,
提取主机名后进行不区分大小写的完整匹配,忽略端口与路径;子域名需要单独列出。
例如 example.com 不会放行 sub.example.com 或 example.com.evil.test。
启用校验但域名列表为空时,所有非空 Referer 都会被拒绝。
allow_empty 默认 false;设置为 true 时允许缺少 Referer 头、空字符串或纯空白值,
但不会放行格式无效、重复或域名不匹配的 Referer。
启用时响应添加 Vary: Referer,让下游缓存按 Referer 区分响应。
此配置独立于用于回源的 jsdelivr.referer。
配置文件([jsdelivr.referer_check]) |
环境变量 | 默认值 |
|---|---|---|
enabled |
JSDRLIVR_PROXY_JSDELIVR__REFERER_CHECK__ENABLED |
false |
allow_empty |
JSDRLIVR_PROXY_JSDELIVR__REFERER_CHECK__ALLOW_EMPTY |
false |
domains |
JSDRLIVR_PROXY_JSDELIVR__REFERER_CHECK__DOMAINS |
[] |
环境变量中的域名用逗号分隔;使用 -c <配置文件> 时不读取环境变量配置。
冷启动之后第一个请求每个资源的人,都要替所有人吃一次回源延迟(实测 gcore 回源 0.7 ~ 2.3 秒)。预载把指定仓库 / 包的前端资源在启动时就灌进缓存, 让第一个真实请求也是命中(实测 4ms)。
默认不预载:不写 [preload](或 targets 为空)时行为与之前完全一致。
[[preload.targets]]
provider = "gh"
name = "hitokoto-osc/sentences-bundle"只写这两行就够了:版本默认取仓库的默认分支,内容默认取全部前端资源文件
并跳过 . 开头的隐藏目录。
| provider | version 省略时 |
说明 |
|---|---|---|
gh |
HEAD |
jsDelivr 侧解析为仓库的默认分支(实测 @HEAD 与 @<默认分支> 返回同一份清单) |
npm |
latest |
dist-tag |
version 也可以写成分支名、tag、commit 或 semver 范围。清单接口只认具体版本
(npm/vue@latest 会被它拒掉),因此 dist-tag 与 semver 范围会先经
/v1/packages/.../resolved?specifier= 换算一次;反过来 gh 的分支名能被清单接口
直接接受,却不能被 resolved 解析。两条路都试过,写哪种形态都能用。
gh 的
latest在 jsDelivr 的原意是「最新的 tag」,和「默认分支」不是一回事。 本项目按「默认 = 默认分支」的语义把 gh 的latest归一成了HEAD; 要最新 tag 请直接写 tag,或者写 semver 范围(如"1.0")让resolved去挑。
必须知道的一点:预热的是精确的缓存键,而缓存键就是客户端请求的路径
(gh/<owner>/<repo>@<version>/<file>)。version 会原样进键,所以它要和客户端
实际请求的版本串一致 —— 预热 @HEAD 命中不了请求 @master 的客户端。
要覆盖多个版本串,就写多个 [[preload.targets]]。启动日志会打出每个目标
预热出来的键前缀,可以直接核对。
默认放行的扩展名(不区分大小写):
| 类别 | 扩展名 |
|---|---|
| 脚本 | js mjs cjs |
| 样式 | css |
| 标记 / 结构化数据 | json html htm wasm |
| 图片 | apng avif bmp gif ico jpeg jpg png svg webp |
| 字体 | eot otf ttf woff woff2 |
刻意不收录 map(source map,只对调试有用且动辄数 MB)、d.ts、md 等
浏览器不会加载的文件。
. 开头的隐藏目录与隐藏文件(.github/、.vscode/、.gitignore)默认全部跳过,
判定按路径片段进行,vue.global.min.js 这种带点的文件名不受影响。
四个可选的收窄 / 放宽开关:
| 字段 | 作用 |
|---|---|
extensions |
覆盖默认集合;["*"] = 不按扩展名过滤 |
include |
只要这些路径前缀下的文件;留空 = 整个仓库 |
exclude |
排除这些前缀,优先级高于 include |
include_hidden |
连隐藏目录一起预载,默认 false |
include / exclude 按路径片段整体比较,不是裸的 starts_with:
/dist 命中 /dist/vue.js,但不会命中 /dist-old/x.js。
预载条目和普通条目共用同一份 TTL,get_or_fetch 命中时既不回源也不续期,
所以只载一次的话 TTL 一到就全没了。预载因此是个周期性任务,
默认周期是 cache.ttl_secs 的 3/4(默认 TTL 下即 5400 秒),保证条目在过期前被续上。
续期不等于重新下载:清单接口带有每个文件的 SHA-256,摘要没变且条目还在缓存里时,
只把旧值重新写回去重置 TTL,一个字节都不用重传。日志里的 warmed / renewed
就是这两条路径的计数。
几道防呆闸:
- 清单里体积超过
cache.max_entry_size_mb的文件在下载之前就被跳过 —— 反正下下来也进不了缓存; - 单个目标最多预载
max_files个文件(默认 512); - 计划下载量超过整个缓存预算时打
warn!(那种配置下条目只会互相淘汰); - 被资源白名单拒绝的目标直接跳过并告警:那些资源永远服务不出去, 预热它们只是白占缓存预算。
预载失败(数据 API 不可达、目标配错等)只影响预热本身,HTTP 服务照常启动与服务。
配置文件([preload]) |
环境变量 | 默认值 | 说明 |
|---|---|---|---|
enabled |
JSDRLIVR_PROXY_PRELOAD_ENABLED |
有 targets 即开 |
总开关 |
data_api |
JSDRLIVR_PROXY_PRELOAD__DATA_API |
https://data.jsdelivr.com |
列清单用的数据 API |
refresh_interval_secs |
JSDRLIVR_PROXY_PRELOAD__REFRESH_INTERVAL_SECS |
cache.ttl_secs x 3/4 |
刷新周期,下限 60 秒 |
concurrency |
JSDRLIVR_PROXY_PRELOAD_CONCURRENCY |
4 |
单目标内的并发回源数 |
max_files |
JSDRLIVR_PROXY_PRELOAD__MAX_FILES |
512 |
单目标预载文件数上限 |
data_api与jsdelivr.mirror是两个不同的服务:gcore 等镜像只分发资源, 不提供/v1/packages清单接口,所以它们分开配。
[[preload.targets]]是数组表,config的环境变量 source 表达不了, 只能写在配置文件里;上面这些标量项才能用环境变量覆盖。
默认全部关闭:不设置管理员 Key 时,/admin 与管理 API 一律返回 503,
不设置 Webhook secret 时 /webhook/cache/purge 同样返回 503。
老部署升级上来不会多出任何可访问的入口。
# 管理面板 / 管理 API(缺省即关闭)
JSDRLIVR_PROXY_ADMIN_KEY="用一个足够长的随机串"
# 缓存清除 Webhook(缺省即关闭),与上面是两把独立的钥匙
JSDRLIVR_PROXY_ADMIN__WEBHOOK_SECRET="另一个随机串"浏览器打开 http://<host>:<port>/admin,填入管理员 Key 即可看到:
- 进程:CPU 占用、常驻内存 RSS、虚拟内存、运行时长(有管理页面连接时每 5 秒采样一次,多页面共享采样);
- 请求:启动以来非管理请求总数、请求速率和响应状态分类,附 RSS 与区间请求数图表(最近 120 点);
- 缓存:条目数、已占用 / 预算、原始体积与实际压缩比,以及当前 TTL 等配置;
- 缓存条目:按占用从大到小列出,可按前缀筛选,可单条清除、按前缀清除或清空;
- 操作记录:谁在什么时候从哪个地址清了什么。
页面本身不含任何数据,也不加载任何外部资源;Key 只存在浏览器 localStorage 里,
每次请求以 Authorization: Bearer <key> 发出。
面板使用 SSE 每 5 秒推送汇总、缓存列表及操作记录;页面隐藏或关闭时断开, 最后一个订阅断开后停止进程采样。网络中断后每 3 秒重连,20 秒未收到数据也会重连; 鉴权失败时停止重试。图表仅保留当前页面内存中的历史,断线期间不计算请求速率。 请求计数始终运行,重启归零;不包含管理路由以及 CDN 命中后未回源的请求。 总数在收到请求时累加,1xx–5xx 分类在响应头生成时累加,因此尚未生成响应的请求不在状态分类中。
通过 CDN / 反向代理部署时,需为 /admin/api/* 禁用缓存,并转发 Authorization。
事件流要求支持流式响应并关闭响应缓冲;服务端已发送 Cache-Control: no-store, no-transform
和 X-Accel-Buffering: no,但 CDN 配置可能覆盖它们。空闲超时应大于 20 秒,
总连接时长限制到达后页面会重连;不支持流式响应的 CDN 应让管理路径直连源站。
例如 CloudFront
分别提供响应包间隔超时与完整响应超时,不能仅凭支持 HTTP 就认定能持续推送。
全部要求 Authorization: Bearer <管理员 Key>,响应沿用项目统一的
{status, message, data, ts} 结构(事件流除外)。
| 方法与路径 | 说明 |
|---|---|
GET /admin/api/stats |
进程最近采样、请求统计与缓存汇总;本接口不启动采样 |
GET /admin/api/events?prefix=&limit=&offset= |
SSE snapshot 事件,包含 stats 及统一响应结构的 cache、audit;查询参数用于缓存列表 |
GET /admin/api/cache?prefix=&limit=&offset= |
缓存条目列表,按占用降序;limit 默认 100、上限 1000 |
POST /admin/api/cache/purge |
清除缓存,请求体见下 |
GET /admin/api/audit?limit=&offset= |
操作记录,最新在前 |
清除请求体三选一,同时给多个会被拒绝(避免「本想清一个前缀,结果清了全部」):
缓存键就是客户端请求的路径,所以前缀 gh/owner/repo@HEAD 只清这一个版本,
gh/owner/repo 则连带该仓库的所有版本。返回里的 missed 是「点名了但本来就不在缓存里」的条数。
BODY='{"prefix":"gh/hitokoto-osc/sentences-bundle@HEAD"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -r | cut -d' ' -f1)
curl -X POST http://<host>:<port>/webhook/cache/purge \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: sha256=$SIG" \
-d "$BODY"请求体与管理 API 的清除接口完全一致,鉴权换成对原始请求体的 HMAC-SHA256 签名,
放在 X-Hub-Signature-256 头里(GitHub / Gitea 的 webhook 格式,sha256= 前缀可省略)。
之所以不复用管理员 Key:一是签名是 GitHub 这类服务唯一能配的凭证, 二是把 secret 交给 CI 或仓库以后,它泄露也只等于「能清缓存」,不等于拿到管理员权限。
签名校验失败不会写进操作记录。这个端点在校验通过前是无鉴权的, 逐次记录会让任何人都能把远端审计库灌满;失败仍然以
warn记进程序日志。
默认存在进程内的环形缓冲里(最近 500 条),重启即丢失——这保住了「一个二进制、 零外部依赖」的默认部署形态。需要持久化时配上 Turso:
JSDRLIVR_PROXY_ADMIN_TURSO_URL="libsql://<db>-<org>.turso.io"
JSDRLIVR_PROXY_ADMIN_TURSO_TOKEN="<turso db tokens create 生成的 token>"表(admin_audit_log)会在启动时自动建好。启动时连不上 Turso不会导致启动失败,
只会退回内存缓冲并打一条 warn——记不了审计日志不该让反代本身停摆。
实现上没有引入官方的 libsql SDK:它的远程路径建在比 reqwest 更旧的一代 HTTP
栈上,接进来会多出 37 个 crate,以及 rustls / tower / hyper-rustls / thiserror 各两份。
Turso 的 /v2/pipeline 是有正式文档的稳定 JSON 协议,直接用现成的 reqwest 说这个协议,
依赖树一个字节都没变。
配置文件([admin]) |
环境变量 | 默认值 | 说明 |
|---|---|---|---|
key |
JSDRLIVR_PROXY_ADMIN_KEY |
空 = 关闭 | 管理面板与管理 API 的 Key |
webhook_secret |
JSDRLIVR_PROXY_ADMIN__WEBHOOK_SECRET |
空 = 关闭 | Webhook 的 HMAC secret |
turso.url |
JSDRLIVR_PROXY_ADMIN_TURSO_URL |
空 = 用内存 | Turso 数据库地址,libsql:// 会被改写成 https:// |
turso.token |
JSDRLIVR_PROXY_ADMIN_TURSO_TOKEN |
空 = 用内存 | Turso 访问 token |
webhook_secret字段名自身带下划线,所以层级必须用双下划线分隔, 写成JSDRLIVR_PROXY_ADMIN_WEBHOOK_SECRET会被解析成admin.webhook.secret而静默失效。
每次打 tag 发布时,同一份构建会同时推送到 Docker Hub 与 GitHub Packages,
两边内容完全一致(同一个 manifest list,含 linux/amd64 与 linux/arm64),
按网络情况任选其一即可:
docker pull hitokoto/jsdelivr-proxy:latest # Docker Hub
docker pull ghcr.io/hitokoto-osc/jsdelivr_proxy:latest # GitHub Packages除 latest 外还提供 vX.Y.Z / vX.Y / vX 三级 tag。
仓库自带 compose 编排(仅 app 一个服务):
docker compose up -d --buildcompose 中通过 JSDRLIVR_PROXY_SERVER_PORT=8000 把容器端口固定为 8000 并映射到宿主机
8000。arm64 机器请把 docker-compose.yml 中的 dockerfile
改为 manifest/docker/release/aarch64-linux-musl/Dockerfile。
程序自身的默认监听地址是
0.0.0.0:28319(见src/conf/server.rs), 直接运行二进制时用的是这个端口;compose 里的8000来自环境变量覆盖。
支持两种方式,任选其一:
- 环境变量(compose 默认方式),前缀为
JSDRLIVR_PROXY_,如JSDRLIVR_PROXY_SERVER_PORT、JSDRLIVR_PROXY_JSDELIVR_MIRROR; 配置项字段名本身含下划线时,层级要用双下划线分隔,否则会被当成多层嵌套而静默失效, 例如JSDRLIVR_PROXY_CACHE__TTL_SECS; - 配置文件:参考
config.example.toml,在./data/config.toml放置配置并挂载./data:/app/data。
可用的缓存配置项:
配置文件([cache]) |
环境变量 | 默认值 | 说明 |
|---|---|---|---|
ttl_secs |
JSDRLIVR_PROXY_CACHE__TTL_SECS |
7200 |
缓存存活时间(秒) |
max_capacity_mb |
JSDRLIVR_PROXY_CACHE__MAX_CAPACITY_MB |
256 |
缓存总字节预算(MB) |
max_entry_size_mb |
JSDRLIVR_PROXY_CACHE__MAX_ENTRY_SIZE_MB |
16 |
单条目上限(MB),超过则不缓存 |
compression |
JSDRLIVR_PROXY_CACHE_COMPRESSION |
"zstd" |
条目压缩算法:none / zstd / brotli |
迁移到 axum 后可在 stable 工具链上构建(已在 rustc 1.91 stable 验证):
cargo build --releaseCI 与
manifest/docker/**目前仍固定使用 nightly 工具链,本次未一并调整。
运行:
./target/release/jsdelivr_proxy # 监听 0.0.0.0:28319
JSDRLIVR_PROXY_SERVER_PORT=8000 ./target/release/jsdelivr_proxy
{ "all": true } // 全部 { "prefix": "gh/hitokoto-osc/sentences-bundle@HEAD" } // 按前缀 { "keys": ["npm/vue@3.4.21/dist/vue.global.prod.js"] } // 精确若干条