Files
ipass-plugin-cache/docs/cache-usage.md
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

27 KiB
Raw Permalink Blame History

统一制品缓存 · 使用说明

一句话:内容存在本地磁盘文件里(nginx 原生 proxy_cache),命中计数存在共享内存里 (ipass plugin-cache)。没有外部引擎、没有新进程、没有数据库——单 nginx + 一个 Rust 模块。


1. 现在是本地文件缓存吗?—— 是

层面 承载者 位置 重启 nginx 后
缓存内容(制品字节) nginx proxy_cache 本地磁盘 proxy_cache_path 指定的目录 保留(文件还在,命中不重新回源)
命中计数(HIT/MISS…) ipass plugin-cache ipass_state 共享内存(10m) 清零(计数是运行时读数,不是持久账)

实测证据(本机 dev-server.sh):

── 缓存盘真实文件(.run-dev/cache,levels=1:2 两级散列)──
  go         1 个文件  4.0K
  cargo      1 个文件  4.0K
  ...
  样例:cache/go/0/6b/decf43777bf2ea024deb844b8dd546b0

单个缓存文件的内部结构(nginx 自有格式,不是裸文件):

<二进制元数据头>
KEY: httpmock/go/pkg-a
HTTP/1.0 200 OK
Server: BaseHTTP/0.6 Python/3.13.12
Content-Length: 15
ETag: "15"
Cache-Control: public, max-age=3600

ECHO:GET /pkg-a          ← 这一段就是上游响应体

文件名 = proxy_cache_key 的 MD5(单向,反推不回来);但别以为原 key 就丢了 —— 它在文件内明文留着(KEY: <路由>:<URI><方法><Accept>),管理 API 的 「按制品失效」(§5.3.1)就是靠读这一行来定位条目的。

重启验证(同一个 URL,重启前已缓存):

重启后计数:{"HIT":0,"MISS":0,...}      ← 共享内存清零
重启后文件:6 个仍在
重启后请求:X-Cache-Status: HIT         ← 内容确实在盘上,没有回源
假上游请求数增量:0

2. 本机怎么试(5 分钟)

上游默认是本地假 registry(mock_upstream.py,确定性响应,专测「缓存 + 鉴权」这一层)。 本机 nginx 已编入 http_ssl_module(见 §3.2),所以也能直接连真实 https registry —— 见下方「真实 registry 贯通测试」。

cd /Users/rong/Desktop/cache

bash tests/cache/dev-server.sh start    # 起「假上游 + 加载 ipass 模块的 nginx」,留在前台
bash tests/cache/dev-server.sh demo     # 六生态各打两次,看 MISS→HIT
bash tests/cache/dev-server.sh stats    # 看管理 API 读数
bash tests/cache/dev-server.sh files    # 翻磁盘缓存文件
bash tests/cache/dev-server.sh purge    # 清缓存
bash tests/cache/dev-server.sh stop     # 关掉(保留缓存文件)

bash tests/cache/dev-server.sh clean    # 关掉并删净 .run-dev

demo 实际输出:

生态   首请求  二次     内容一致
go       MISS       HIT        yes
cargo    MISS       HIT        yes
pypi     MISS       HIT        yes
npm      MISS       HIT        yes
maven    MISS       HIT        yes
docker   MISS       HIT        yes

上游只应看到 6 行(HIT 不回源): 6

stats 实际输出:

生态          HIT  MISS     其他
go            1     1      0
cargo         1     1      0
pypi          1     1      0
npm           1     1      0
maven         1     1      0
docker        1     1      0
global        6     6      0

也支持自己 curl(制品路由与 stats 都要带统一 sk_ Key):

# 看 X-Cache-Status: MISS/HIT(Key 用 fixtures/users.json 里 alice 那把)
curl -D- -o/dev/null -H "Authorization: Bearer sk_alice_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
     http://127.0.0.1:18085/go/pkg-a
curl -s -H "Authorization: Bearer sk_alice_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
     http://127.0.0.1:18085/api/v1/cache/stats      # 看计数
# 管理台(要配上游 / 一键复制下游地址走这里):http://127.0.0.1:18085/admin

全量回归(不需要常驻)

bash tests/cache/run.sh          # Tier1 纯 nginx 23/23 + Tier2 ipass 24/24 + 生产配置校验
bash tests/cache/run.sh tier1    # 只跑纯 nginx 缓存层
bash tests/cache/run.sh tier2    # 只跑「六生态记账 + stats 鉴权 + 管理 API」
bash tests/cache/run.sh prod     # 只跑生产配置语法/模块加载校验
bash tests/cache/e2e-auth.sh     # 统一 Key + 动态上游 + 磁盘缓存(29/29 为基线)

Tier2 与 e2e-auth 跑的都是生产 conf 的渲染副本(借 tests/cache/lib-render.sh), 不再是各自维护的平行 conf —— 曾经因为抄了两份,生产 conf 换成变量上游后 Tier2 仍在按静态上游渲染,整层挂掉且症状像模块坏了。

真实 registry 贯通测试(证明各生态的真实协议路径能穿过网关)

假上游只回 ECHO:<method> <path>,任何真实协议的坑都照不出来。要证明「按业务类型真的能用」, 得把上游换成真实 registry:

bash tests/cache/test-real-registries.sh                 # 需先 dev-server.sh start
ONLY=go,npm bash tests/cache/test-real-registries.sh     # 只测指定路由
GO_UP=https://goproxy.io bash tests/cache/test-real-registries.sh   # 换镜像源

它用管理 API(与 UI 同一条路)把 7 个路由配成真实上游,然后按「各生态真实客户端会打的 协议路径」各拉两次,断言 MISS→HIT 且两次响应体一致。实测基线:

路由 探测路径(真实协议) 实测
go golang.org/x/text/@v/list 200,382 B
npm lodash(packument) 200,247,678 B
maven commons-lang3/maven-metadata.xml 200,1,102 B
pypi simple/requests/ 200,82,826 B
cargo index.crates.io/config.json 200,76 B
cargo-dl crates/serde/serde-1.0.0.crate 200,58,433 B
docker library/alpine/manifests/latest 401(预期)

docker 的 401 是协议要求,不是故障:registry v2 要先向 auth 端点换短期 token, 真实客户端会做这一步(token 由 $cache_auth 透传给上游);裸 curl 没 token 自然 401。 又因为 401 不在 proxy_cache_valid 里,它也不会被缓存 —— 这正是「只缓存能缓存的」。

go / docker 的官方源在国内不通(实测超时),脚本默认换 goproxy.cn / docker.m.daocloud.io;要改就设 GO_UP / DOCKER_UP 等环境变量。

⚠️ 它跑在已有实例上(默认 BASE=http://127.0.0.1:18085),只配上游、发请求、 清缓存文件(保留目录结构),不起停服务、也不 pkill。但跑完上游表就被改成真实上游了, dev-server.sh demo 依赖假上游的 /pkg-a 会因此失效 —— 恢复:dev-server.sh stop && start。

容量与淘汰的实测见 §5.4(tests/cache/verify-cache-eviction.sh)。


3. 生产怎么部署

3.1 文件放置

nginx prefix 的 conf/ 下放三个文件 + mime.types:

<prefix>/conf/nginx.conf          ← 用 conf/nginx.cache.conf 改名/替换
<prefix>/conf/server.cache.conf
<prefix>/conf/cache-common.conf
<prefix>/modules/libipass_gateway.so

conf/nginx.cache.conf 顶部需要改两处绝对路径:

load_module /usr/local/nginx/modules/libipass_gateway.so;   # 改成你的 prefix

以及 error_log / pid / ipass_data_dir / ipass_audit_dir、六个 proxy_cache_path (默认 /var/cache/ipass-cache/<eco>,各 50g、docker 200g;按机器盘量调整)。

3.2 ⚠️ 关键:Linux 上必须重新编译模块

本机产出的是 macOS 动态库 libipass_gateway.dylib,Linux 用不了。生产部署前在目标机 (或同架构 Linux)重编:

cd rust
NGINX_SOURCE_DIR=<nginx 源码目录> NGINX_BUILD_DIR=<nginx 源码>/objs \
  cargo build --release
cp target/release/libipass_gateway.so <prefix>/modules/

前提:该 nginx 必须同源编译(nginx -V 的版本与 configure 参数要和 NGINX_SOURCE_DIR 一致)—— 动态模块 ABI 与 nginx 构建严格绑定。本机现在这份 nginx 是裁剪版 (--without-http_rewrite_module --without-http_ssi_module --without-http_gzip_module,无 PCRE/SSL), 生产请用你们完整的 nginx 源码与参数重跑 ./configure 后再编模块。

3.3 起停

nginx -t -c <prefix>/conf/nginx.cache.conf    # 先校验
nginx    -c <prefix>/conf/nginx.cache.conf

首次启动需要环境里有 ADMIN_INIT_PASSWORD(env ADMIN_INIT_PASSWORD; 已在配置里声明, 否则 nginx 会把它从环境中剥离)。


4. 客户端怎么接

把 HOST 换成网关域名(生产 listen 8080,建议前置 443 TLS)。

生态 客户端配置 是否完整走缓存
Go export GOPROXY=http://HOST/go ✅ 完整
npm npm config set registry http://HOST/npm/ ✅ 完整(packument + tarball 同源)
Maven settings.xml 里 <mirror><url>http://HOST/maven</url> ✅ 完整(POM/JAR 同源)
Docker /etc/docker/daemon.json → {"registry-mirrors":["https://HOST"]} ✅ 但必须 TLS,且只对 docker.io 官方镜像生效
cargo [registries.crates-io] index = "sparse+http://HOST/cargo/" ⚠️ 索引✅ / 包本体✖(见下)
pip pip install -i http://HOST/pypi/simple/ <pkg> ⚠️ 索引✅ / 包本体✖(见下)

⚠️ cargo / pypi 的包本体是「绝对 URL」边界

  • crates.io 稀疏索引的 config.json 里 "dl": "https://static.crates.io/crates", cargo 会直连 static.crates.io 取 .crate,不经过网关。
  • PyPI simple 页里的 href 指向 files.pythonhosted.org,pip 同样直连。

配置里已经预留 /cargo-dl/(→ static.crates.io)与 /pypi-files/(→ files.pythonhosted.org) 两个 location,要真正命中需二选一:

  1. 给 nginx 加 http_sub_module,用 sub_filter 把索引响应里的绝对 URL 重写成网关地址 (--with-http_sub_module,本机当前版本没编这个模块);
  2. 网络层重定向:内网 DNS 把这两个域名指到网关,配证书。

两者都归到 cargo / pypi 生态计数(插件已做前缀映射)。


5. 缓存策略与运维

5.1 当前策略(conf/cache-common.conf + 各 proxy_cache_path)

项 值 含义
proxy_cache_key $cache_key$request_method$http_accept($cache_key = <route>:<uri>[?args],由模块算) 必须显式给定。变量式 proxy_pass 下 $proxy_host 不可靠;且必须并入方法与 Accept —— nginx 的 proxy_cache 不实现 Vary,不并入就会把 HEAD/GET、不同 Accept 的响应混成同一条。键里不含任何下游凭据(见 §6 边界)
proxy_cache_valid 200 301 308 → 1d;404 → 1m 只缓存这些状态码;206(range)/401 等不缓存
proxy_cache_use_stale error/timeout/updating/5xx 上游抖动时用陈旧副本兜底
proxy_cache_lock on(age 10s / timeout 30s) 同 key 并发只回源一次,防击穿
proxy_cache_revalidate on 带 If-None-Match 回源校验,省带宽
proxy_ignore_headers Cache-Control Expires Set-Cookie Vary 镜像型缓存的标准取舍:不被上游 no-cache 拦
inactive 7d 7 天没被访问即淘汰。与容量无关,与 max_size 各自独立生效
max_size go/cargo/pypi/npm/maven 各 50g,docker 200g 单生态容量上限,超了按 LRU(最久未访问先删)淘汰。⚠️ 是软上限:淘汰由 cache manager 渐进执行,短时猛灌可短暂远超,随后收敛 —— 实测见 §5.4
keys_zone 100m(docker 200m) 索引内存;1m ≈ 8000 个 key 的元数据

要改容量就改 proxy_cache_path 的 max_size / inactive(改完需 reload/重启 nginx)。

5.2 看命中率

curl -s -H "Authorization: Bearer <sk_...>" http://HOST/api/v1/cache/stats   # 按生态 × 状态计数(共享内存)
tail -f <prefix>/logs/cache.log               # 逐请求日志:cache=HIT|MISS uri=... rt=... eco=...

cache.log 的 log_format 里带了 $upstream_cache_status,排障用这个最直接。

⚠️ 计数是进程内共享内存,nginx 重启即清零;它是「运行态读数」不是「持久账单」。 需要跨重启的历史曲线,得把 stats 定期抓走落到 PG/Prometheus。

安全:/api/v1/cache/stats 是 账号态接口(Guard::User)——必须带统一 sk_ Key, 无 Key / 错 Key 一律 401。它刻意不回显上游地址与凭据(账号态只需要知道 「往哪个地址发请求」)。管理员的全量快照在 GET /api/admin/cache,走登录会话。

5.3 清缓存

开源 nginx 没有 proxy_cache_purge(商业版专属),本配置也没用它。现在首选 下面的管理 API(模块自己动手,绝不会误删目录),rm 只当兜底:

# ① 管理 API(推荐):清空某生态 / 全部;只删缓存文件,目录结构保留
curl -sX POST -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"zone":"npm"}'  http://HOST/api/admin/cache/purge     # 单个生态
curl -sX POST -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"zone":"all"}'  http://HOST/api/admin/cache/purge     # 全部
#   返回 {selector, items:[{zone,dir,files,bytes,dir_exists}], total:{files,bytes}}

# ② 管理台 UI:「容量与淘汰」面板 → 每行「清空」按钮 / 顶部「清空全部」

# ③ 本机开发实例
bash tests/cache/dev-server.sh purge

# ④ 兜底:手工 rm(务必带尾随 /*,见下方警告)
rm -rf /var/cache/ipass-cache/npm/*      # ← 尾随 /* 是关键:只删内容,保留 npm 目录本身

POST /api/admin/cache/purge 是管理态接口(走登录会话,Guard::Admin), 无会话 401。按 zone=<生态名> 或 zone=all 选择;只递归删缓存文件、不删任何目录 (正是为了避开本节末尾那个 [crit] mkdir() failed 的坑),未知 zone 或缺少 zone 参数一律 400 并回显已知 zone 名。清理不影响正确性:删掉的只是磁盘副本, 请求会 MISS 回源重建。

5.3.1 按制品失效(比整区清空细一档)

整区清空解决的是「这个生态整体脏了」。但更常见的事故是局部的:上游把 [email protected] 发成了坏包、某个 maven-metadata.xml 发布错了版本 —— 这时清掉整个 npm 区意味着几十 GB 白重拉,而真正要扔的只有那几个文件。

# 预览(默认!不传 apply 只算不删)
curl -sX POST -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"zone":"all","match":"lodash"}' http://HOST/api/admin/cache/invalidate
# 确认失效
curl -sX POST -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"zone":"npm","match":"lodash","apply":1}' http://HOST/api/admin/cache/invalidate

管理台「容量与淘汰」面板底部就是它的 UI:填关键字 → 预览命中(列出命中的 cache key) → 确认失效。

按制品失效:预览命中

参数 说明
zone 生态/区名,或 all(默认)
match 必填。含 */? 时按 glob 匹配,否则按子串匹配;两种都大小写敏感
apply 不传 = 预览(只返回会删哪些);传 1 = 真删

为什么默认预览:支持通配就意味着「写宽了 = 事故」(一个 * 等价于整区清空)。 把「表达式对不对」与「真的动手」拆成两次调用,前端据此做成两步。

它怎么找到条目:读每个缓存文件里明文的 KEY: 行(如 npm:/npm/lodashGET*/* = <路由>:<URI><方法><Accept>)。不解析 ngx_http_file_cache_header_t —— 那个结构体跨版本增删过字段,按偏移读会错位, 表现不是报错而是「静默匹配不到」或更糟的「匹配到错的东西然后删掉」。

想先看清 key 长什么样:match 填 * 预览一遍,会列出(最多 50 条)现有 key 的形态。

match 命中为空返回 200 + matched:0(不当错误——最常见的原因只是关键字写错)。 单次删除上限 5000 条、扫描上限 20 万文件,触顶返回 truncated:true,此时数字是下界。 与 purge 同样的两条硬约束:只删文件不删目录、删的是副本不影响正确性。

删文件后 nginx 的 keys_zone 里可能还留着条目,但下次请求会因文件缺失而 MISS 回源 (已在 Tier1/Tier2 测试中验证),不会返回脏数据。

★★ 绝不能删掉 <cache>/npm 这些目录本身。 nginx 只在启动时创建 cache/<eco>,运行期只按 levels=1:2 建下级目录;父目录被删后它不会自愈: 此后每次写缓存都是 [crit] mkdir() ".../cache/npm/a" failed (2: No such file or directory), 并且 nginx 直接断开客户端连接(curl 报 Empty reply from server、code 000), 该生态 100% 不可用,直到 reload / 重启 nginx 才恢复。 安全的清法是 rm -rf <cache>/npm/*(尾随 /*)或 find <cache> -type f -delete。 注意时机差异:脚本里「先清缓存、再起 nginx」是安全的(启动会重建目录结构), 在已运行的实例上清才危险 —— 仓库里的测试脚本一律用 -type f 形式,正是为此。

5.4 容量与淘汰(实测)

「磁盘写满了谁清?」—— nginx 自带机制,不需要外部脚本。两条规则独立生效:

规则 参数 行为
容量淘汰 max_size cache manager 持续比对 zone 用量,超上限就按 LRU(最久未访问先删)删到上限以下
闲置淘汰 inactive 条目在该时间内未被访问过就删(与容量无关)

两者都按 zone 配置(proxy_cache_path 上一行一个 zone),互不干扰。

实测(tests/cache/verify-cache-eviction.sh,临时把参数改小到可观测):

  • 容量:npm zone 配 max_size=1m,灌入 15 × 200KB ≈ 3MB → 磁盘被逐步压回上限附近;且最早的条目再请求变 MISS、最新的仍 HIT —— 证明淘汰顺序确实是 LRU。
  • 闲置:maven zone 配 inactive=10s,灌 1 个对象 → 闲置 15s 后磁盘文件归零、再请求 MISS。

⚠️ max_size 是软上限,不是硬配额:淘汰由 cache manager 渐进执行 (每秒一轮、每轮删有限个条目),所以短时猛灌可以短暂远超上限(实测到 3 倍), 随后收敛。若场景是「一次导入几十 GB」,别指望它立刻刹住 —— 必要时给缓存盘单独挂载 + 限额。

复现:bash tests/cache/verify-cache-eviction.sh(自起自停独立实例,端口 18086)。

5.4.1 容量可见 + 可管(管理台「容量与淘汰」面板)

自动淘汰只解决「撑爆」,不解决「看不见、管不了」。为此 plugin-cache 增加了 容量水位快照,管理台 http://HOST/admin 的「容量与淘汰」面板直接读它:

容量与淘汰面板

  • 数据来源是 nginx 自己的共享内存记账(ngx_http_file_cache_t / sh), 不是扫盘:口径与淘汰动作同源,所以「面板显示 91%」和「nginx 正在淘汰」说的是同一件事; 且读数 O(1),不随缓存变大而变慢。
  • 分两条轴展示:磁盘轴(used_bytes / limit_bytes / pct)与索引内存轴 (keys_zone 字节数、entries_cap_est、index_pressure),外加 entries、cold、 loading、inactive_secs、dir_exists。
  • 水位判定(ok / warn / crit,80% / 95%)在后端算好下发,前端只画条上色 —— 避免「同一块盘两个页面两种颜色」。
  • 每条线一个「清空」按钮(= §5.3 的 purge API),顶部「清空全部」;面板底部是 「按制品失效」工具条(= §5.3.1,两步:预览 → 确认)。
curl -s -b cookies.txt http://HOST/api/admin/cache          # 只读 nginx 记账(O(1))
curl -s -b cookies.txt 'http://HOST/api/admin/cache?scan=1' # 顺带盘点磁盘(见下)

?scan=1 的两个数并排才有意义:nginx 的记账在「手工删过缓存文件」之后是滞后的 (节点要等再被访问或到期才回收),只有拿磁盘实测(disk_bytes / disk_files)一比, 才知道差额是真实占用还是虚账。面板会如实显示差额(「账比盘多 N」),不替你把账抹平。

  • scan 默认关:扫盘是 find 级遍历(上限 20 万文件 / 6 层),大 zone 慎点; 面板上的「盘点磁盘」按钮就是临时 ?scan=1。
  • 返回结构:capacity.available / zones[](每区含上述字段)/ totals (zones / limit_bytes / used_bytes / pct / entries / disk_bytes / warn / crit)。

验证:bash tests/cache/test-cache-capacity.sh(独立实例 :18087,48/48 全绿)覆盖 六区识别、上限取自 conf、共享 zone 路由列全、记账与 du 同量级、?scan=1 ≈ du、 越权 401、未知 zone/缺参 400、清理只删文件目录保留、记账滞后如实、清空后无 [crit], 按制品失效(预览不删盘 → 命中 key 回显 → 只删命中项且对照项不被误伤 → 删后 MISS→200 → glob 子串/跨生态 → zone 限定不跨区 → 无命中 200 → 参数与越权), 外加前端静态契约(面板锚点齐 + 「定义了却没人调用」检测 —— API 全绿但面板空白正是这么发生的)。


6. 已知边界 / 可选的下一步

# 边界 影响 处理方式
1 本机 nginx 无 http_ssl_module 已解决 本机构建现已对齐 ipass 生产参数:--with-pcre --with-http_ssl_module --with-http_realip_module(脚本 build/build-nginx-ssl.sh,产物 build/nginx-1.30.4/objs/nginx),proxy_ssl_* 与 return/rewrite 均可如实校验,不再需要任何降级 —
2 无 http_rewrite_module 已解决 同上(--with-pcre 带 rewrite 模块),return / rewrite 可用;cache-routes.conf 用了 return 302 /admin 与 rewrite ^ /admin/cache.html last —
3 cargo/pypi 包本体绝对 URL 这两个生态只缓存到索引 加 http_sub_module + sub_filter 重写,或 DNS 层导流
4 /api/v1/cache/stats 免鉴权 已收口 现在是 Guard::User:无 Key 401、带 sk_ 200(Tier2 与 e2e 各有一条断言钉住,别改回匿名) —
5 计数不持久 重启清零 定期抓取落库
6 无 PURGE API / 无法按制品失效 已解决 POST /api/admin/cache/purge(zone=<生态名>/all)整区清空;POST /api/admin/cache/invalidate(match=<子串|glob>,默认只预览)按制品失效。两者都只删文件不删目录,未知 zone/缺参 400。管理台「容量与淘汰」面板有对应 UI 单次上限:删除 5000 条 / 扫描 20 万文件(触顶返回 truncated:true,数字为下界)
7 缓存全站共享、键里不含 sk_ 任一有效 Key 能命中别人拉过的制品;若某路由指向私有上游会串档 公开 registry 无碍;私有上游需按用户分档(键里加身份)或别共用这一层
8 cache-routes.conf 的 include 用相对名 必须放在 nginx conf/ 下(或 prefix 的 conf 路径里);拷到别处会 open() failed 部署时整目录放到 nginx conf/ 下即可(校验脚本已按此渲染)
9 没有磁盘占用 / 条目数指标 已解决 管理台「容量与淘汰」面板 + GET /api/admin/cache 的 capacity 块已暴露 nginx 记账的 used_bytes/limit_bytes/pct/entries 与索引内存轴,水位 ok/warn/crit 后端判定(§5.4.1) 提醒:记账是运行态读数(重启清零),要跨重启的历史曲线仍须定期抓走落库;?scan=1 的磁盘实测是 find 级(大 zone 慎点)
10 清缓存误删 <cache>/<eco> 目录本身会让该生态彻底不可用 nginx 不自愈:[crit] mkdir() failed + 直接断开客户端,直到 reload(§5.3 详述) 首选 POST /api/admin/cache/purge(只删文件、目录不动);手工清一律 rm -rf <cache>/<eco>/* 或 find <cache> -type f -delete;别删目录

7. 代码与文件索引

conf/nginx.cache.conf          生产顶层(load_module + resolver + 六 zone + include)
conf/server.cache.conf         明文入口 server 块(include cache-routes.conf)
conf/cache-routes.conf         路由与鉴权开关(八个 location,两个入口复用同一份)
conf/cache-common.conf         共用缓存/代理指令(变量上游 + $cache_auth 三段式)
conf/tls/cache.conf.example    TLS 入口模板(对外 https,Docker 镜像加速必需)

rust/crates/plugin-cache/
  lib.rs                       插件注册(postconfig 挂 log handler + 预取变量索引 + 发现 proxy_cache 区)
  cache.rs                     $cache_target/$cache_host/$cache_upstream_key/$cache_auth/$cache_eco/$cache_key
  upstreams.rs                 上游表:落盘 + 写穿共享内存 + 查表(key = 路由名)
  models.rs                    data/cache-upstreams.json 的结构
  handlers.rs                  access 闸门(未配上游 503 + 统一 Key 鉴权)与 log 记账
  stats.rs                     共享内存计数(复用内核 usage 原语)
  zones.rs                     ★缓存容量:直读 nginx file_cache 共享内存记账 + 安全清理 / 按制品失效(只删文件)
  api.rs                       /api/admin/cache*(管理态,含 purge / invalidate)+ /api/v1/cache*(账号态)
  config.rs                    路由/生态/状态清单与映射(route_of_seg / route_uri / eco_of_route)

tests/cache/
  run.sh                       统一回归入口(tier1|tier2|prod|all)
  lib-render.sh                把**生产 conf** 渲染进测试前缀(e2e/Tier2/dev-server 共用)
  dev-server.sh                本机可交互试跑(start/demo/stats/files/urls/admin/purge/logs/status/stop/clean)
  e2e-auth.sh                  统一 Key + 动态上游 + 磁盘缓存(32/32 基线)
  test-real-registries.sh      对**真实 registry**按业务类型贯通(go/npm/maven/pypi/cargo/cargo-dl/docker)
  verify-cache-eviction.sh     容量淘汰(max_size/LRU)与闲置淘汰(inactive)实测(独立实例 :18086)
  test-cache-capacity.sh       ★容量水位读数 + purge + 按制品失效 + 越权/参数校验 + 目录保护 + 前端静态契约(独立实例 :18087,48/48)
  test-cache.sh                Tier1:纯 nginx proxy_cache(自己的 conf,不加载模块)
  test-ipass-cache.sh          Tier2:六生态记账 + stats 鉴权(跑生产 conf 副本)
  validate-prod-conf.sh        生产配置语法/模块加载校验(断言 SSL 在编 + resolver 已声明)
  mock_upstream.py             确定性假上游(支持 Range 与 `?bytes=N` 指定响应体大小)
  nginx.cache.local.conf       Tier1 专用配置模板(唯一还允许存在的"测试自有 conf")