# ============================================================================ # cache-common.conf —— 各生态 cache location 共用的缓存/代理指令 # # 由 conf/cache-routes.conf 在每个 location 内 `include`。 # **每个 location 自己指定** `proxy_cache `(各生态分库),本文件只放公共项。 # # --------------------------------------------------------------------------- # 与「静态上游版」相比的三处关键变化(配合 plugin-cache 的变量层) # --------------------------------------------------------------------------- # # 1. `proxy_pass` 由字面量改为变量 `$cache_target`。上游地址与凭据因此来自 # 共享内存(`cx:`,由管理台写),**改上游不用改 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` = `:<完整 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;