容量管理: 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 容量管理章节
27 KiB
统一制品缓存 · 使用说明
一句话:内容存在本地磁盘文件里(nginx 原生
proxy_cache),命中计数存在共享内存里 (ipassplugin-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,要真正命中需二选一:
- 给 nginx 加
http_sub_module,用sub_filter把索引响应里的绝对 URL 重写成网关地址 (--with-http_sub_module,本机当前版本没编这个模块); - 网络层重定向:内网 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 | 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 | 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")

