容量管理: zones.rs 直读 nginx file_cache 共享内存记账(双轴: 磁盘 + keys_zone 索引内存), ?scan=1 扫盘上限 20 万文件; POST /api/admin/cache/purge 整区清理(只删文件不删目录, 根治 [crit] mkdir failed); POST /api/admin/cache/invalidate 按制品精准失效(预览->确认两步式, glob/子串, 删除上限 5000/扫描上限 20 万); GET /api/admin/cache 新增 capacity 块; 前端容量面板 + 按制品失效工具条; 测试 test-cache-capacity.sh 48/48(容量 27 + 精准失效 21, 含 EXPECT_MIN 护栏与前端静态契约); docs 容量管理章节
132 lines
7.6 KiB
Plaintext
132 lines
7.6 KiB
Plaintext
# ============================================================================
|
||
# cache-common.conf —— 各生态 cache location 共用的缓存/代理指令
|
||
#
|
||
# 由 conf/cache-routes.conf 在每个 location 内 `include`。
|
||
# **每个 location 自己指定** `proxy_cache <zone>`(各生态分库),本文件只放公共项。
|
||
#
|
||
# ---------------------------------------------------------------------------
|
||
# 与「静态上游版」相比的三处关键变化(配合 plugin-cache 的变量层)
|
||
# ---------------------------------------------------------------------------
|
||
#
|
||
# 1. `proxy_pass` 由字面量改为变量 `$cache_target`。上游地址与凭据因此来自
|
||
# 共享内存(`cx:<route>`,由管理台写),**改上游不用改 conf、不用 reload**。
|
||
# 代价:变量式 proxy_pass 不推导 Host、不追加 query —— 两者都由模块算好,
|
||
# 所以这里必须显式 `proxy_set_header Host $cache_host`。
|
||
#
|
||
# 2. `proxy_cache_key` 不再用 `$scheme$proxy_host$request_uri`(变量式下
|
||
# `$proxy_host` 不可靠),改用模块给的 `$cache_key`,并**并入方法 +
|
||
# Accept**(下面的注释详述为什么这是正确性问题,不是调优)。
|
||
#
|
||
# 3. 出站鉴权头改成三段式(`proxy_pass_request_headers on` + 抹掉三个
|
||
# 网关 Key 携带位 + 用 `$cache_auth` 下发)——见文件下半部分。
|
||
#
|
||
# ⚠️ 本文件**不得**使用 rewrite 模块的 `set` / `if`;生态判定由 plugin-cache
|
||
# 直读 `r->uri` 首段完成,不需要 `set $cache_ecosystem`。
|
||
# (`return` / `rewrite` 本身可用:本机构建与 ipass 生产都带 --with-pcre,
|
||
# rewrite 模块在编。它们只在 cache-routes.conf 里用。)
|
||
# ============================================================================
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# 缓存键
|
||
# ---------------------------------------------------------------------------
|
||
#
|
||
# `$cache_key` = `<route>:<完整 URI + query>`,**不含任何下游凭据** —— 缓存因此是
|
||
# 「全站共享」的:同一个 go module / npm 包被 N 个账号拉,只回源一次。
|
||
# 这正是制品缓存的价值所在;鉴权在 access 层(谁能读),数据在共享层复用。
|
||
# 代价:任一有效 Key 都能命中别人拉过的制品 —— 对公开 registry 无碍,
|
||
# 若某路由指向**私有**上游,请理解这一点再启用。
|
||
#
|
||
# ★ query 必须进键(由模块的 `$cache_key` 负责,本行不要再自己拼 `$args`):
|
||
# npm 的 `?write=true`、docker 的 `?ns=`、go 的 `?go-get=1`、cargo 的
|
||
# `?archive=tar.gz` 都靠 query 区分实体。变量式 `proxy_pass` 下 `$uri`
|
||
# **不含** query,只按 `$uri` 做键会把 `/x?a` 与 `/x?b` 当成同一个资源,
|
||
# 把错的制品发给客户端(且第二次完全不回源,很难察觉)。
|
||
#
|
||
# ★ 为什么要并入 `$request_method` 与 `$http_accept`(这是正确性,不是调优):
|
||
#
|
||
# · `$request_method`:Docker 客户端对同一 URL 先 `HEAD` 看清单存不存在、
|
||
# 再 `GET` 取清单(registry 协议如此)。若两者共用一个键,一次 HEAD 的
|
||
# **空体**响应会被缓存下来并回给随后的 GET,客户端拿到 0 字节清单直接失败。
|
||
#
|
||
# · `$http_accept`:nginx 的 proxy_cache **不实现 Vary**(只能靠
|
||
# proxy_ignore_headers 把 Vary 忽略掉,无法参与分档)。而上游同一 URL
|
||
# 会因为 Accept 返回**不同实体**:
|
||
# - npm:`application/vnd.npm.install-v1+json` → 精简元数据,
|
||
# 缺省 → 完整元数据;
|
||
# - PyPI simple:`application/vnd.pypi.simple.v1+json` → JSON,
|
||
# `text/html` → HTML;
|
||
# - Docker:清单 v2 / OCI / v1 的 mediaType 由 Accept 偏好决定。
|
||
# 不并入 Accept 就会出现「发给 A 的实体被回给 B」的串档。代价是每个
|
||
# Accept 变体一个桶(现代客户端取值收敛,实际只多一个桶)。
|
||
#
|
||
# 注:刻意**不**再带 `$scheme`/`$proxy_host`:同一份制品无论客户端走 http
|
||
# 还是 https、走哪个域名进来,上游都是同一个,共享一份缓存更省盘也更省带宽。
|
||
proxy_cache_key $cache_key$request_method$http_accept;
|
||
|
||
# 只缓存完整 GET/HEAD(200/301/308);404 短缓存;206(range)/401 等不缓存,避免错片
|
||
proxy_cache_methods GET HEAD;
|
||
proxy_cache_valid 200 301 308 1d;
|
||
proxy_cache_valid 404 1m;
|
||
|
||
# 上游抖动时用陈旧副本兜底;并发同键只回源一次(防击穿)
|
||
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
|
||
proxy_cache_lock on;
|
||
proxy_cache_lock_age 10s;
|
||
proxy_cache_lock_timeout 30s;
|
||
|
||
# 带 If-None-Match / If-Modified-Since 回源校验,省带宽
|
||
proxy_cache_revalidate on;
|
||
|
||
# 加速缓存:不被上游 no-cache/Set-Cookie/Vary 拦下(镜像型缓存的标准取舍)
|
||
# ⚠️ Vary 被忽略是**必须**的——见上面缓存键的说明,我们已用 Accept 显式分档;
|
||
# 留着 Vary 反而会让 nginx 拒绝缓存这些响应。
|
||
proxy_ignore_headers Cache-Control Expires Set-Cookie Vary;
|
||
|
||
proxy_http_version 1.1;
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# 出站请求头(镜像型:默认透传,但抹掉「本网关自己的 Key」)
|
||
# ---------------------------------------------------------------------------
|
||
#
|
||
# 与 LLM/API 代理的 allowlist 策略**刻意不同**:那些是无状态 API,客户端
|
||
# 头没有语义;而镜像必须原样带上客户端的 `Accept` / `Range` /
|
||
# `If-None-Match` / `User-Agent`,否则 docker 的 mediaType 协商、range 取
|
||
# 大 blob、条件请求全部失效。所以这里保持 `on`(nginx 默认),只在三个
|
||
# 「网关 Key 的携带位」上显式抹空。
|
||
#
|
||
# 为什么必须抹:`sk_` 是客户端访问**本网关**的身份(auth::downstream_key 认
|
||
# Authorization / x-api-key / api-key 三处)。原样透传给上游 = 把网关钥匙
|
||
# 递给上游厂商,对方可拿它反调本网关的其它路由刷额度。ipass 的 LLM 路径
|
||
# 记过同一个坑(宽松厂商把这缺陷掩盖成 200,换严格厂商才暴露成 401)。
|
||
proxy_pass_request_headers on;
|
||
proxy_set_header x-api-key "";
|
||
proxy_set_header api-key "";
|
||
|
||
# 变量形式 proxy_pass 不会推导 Host,必须显式设(上游多为 Cloudflare 前端,
|
||
# Host 不符会被直接拒)
|
||
proxy_set_header Host $cache_host;
|
||
|
||
# Authorization 三段式(由模块里的 `$cache_auth` 实现,语义见其文档):
|
||
# 配了上游凭据 → 下发配置值(管理员写全 `Bearer xxx` / `Basic yyy`)
|
||
# 没配 → 透传客户端值(Docker Hub 的短期 Bearer token 走这条)
|
||
# 客户端那把恰好是下行 sk_ → 丢弃
|
||
proxy_set_header Authorization $cache_auth;
|
||
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $remote_addr;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
|
||
# registry 大 blob / 慢索引:放宽超时
|
||
proxy_read_timeout 300s;
|
||
proxy_send_timeout 300s;
|
||
|
||
# 变量式/直连上游为 HTTPS 时开 SNI;证书校验此阶段关闭(镜像多为公开源,
|
||
# 且目标主机来自管理台配置而非请求。要严格校验需另配 proxy_ssl_trusted_certificate)
|
||
proxy_ssl_server_name on;
|
||
proxy_ssl_protocols TLSv1.2 TLSv1.3;
|
||
proxy_ssl_verify off;
|
||
|
||
# 观测:每次响应带回缓存命中状态(ipass plugin-cache 亦从同一变量记账)
|
||
add_header X-Cache-Status $upstream_cache_status always;
|
||
add_header X-Cache-Eco $cache_eco always;
|