Files
ipass-plugin-cache/conf/cache-common.conf
T
ssw 43718bd0c4 iPass cache gateway 源码
容量管理: 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 容量管理章节
2026-09-21 09:25:11 +08:00

132 lines
7.6 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ============================================================================
# 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;