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

474 lines
27 KiB
Markdown
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.
# 统一制品缓存 · 使用说明
> 一句话:**内容存在本地磁盘文件里**(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 贯通测试」。
```bash
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**):
```bash
# 看 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
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
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` 顶部需要改两处**绝对路径**:
```nginx
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)重编:
```bash
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 起停
```bash
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 看命中率
```bash
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` 只当兜底:
```bash
# ① 管理 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 白重拉**,而真正要扔的只有那几个文件。
```bash
# 预览(默认!不传 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**)
→ **确认失效**。
![按制品失效:预览命中](img/capacity-invalidate.png)
| 参数 | 说明 |
|---|---|
| `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` 的「容量与淘汰」面板直接读它:
![容量与淘汰面板](img/capacity-panel.png)
- **数据来源是 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,两步:预览 → 确认)。
```bash
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")
```