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 容量管理章节
This commit is contained in:
commit
43718bd0c4
324 files changed
+40403
No files matched your search
@@ -0,0 +1,473 @@
|
||||
# 统一制品缓存 · 使用说明
|
||||
|
||||
> 一句话:**内容存在本地磁盘文件里**(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**)
|
||||
→ **确认失效**。
|
||||
|
||||

|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `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,两步:预览 → 确认)。
|
||||
|
||||
```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")
|
||||
```
|
||||
Reference in new issue
Block a user