# 统一制品缓存 · 使用说明 > 一句话:**内容存在本地磁盘文件里**(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: <路由>:<方法>`),管理 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: `,任何真实协议的坑都照不出来。要证明「按业务类型真的能用」, 得把上游换成真实 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`: ``` /conf/nginx.conf ← 用 conf/nginx.cache.conf 改名/替换 /conf/server.cache.conf /conf/cache-common.conf /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/`,各 50g、docker 200g;按机器盘量调整)。 ### 3.2 ⚠️ 关键:Linux 上必须重新编译模块 本机产出的是 **macOS 动态库 `libipass_gateway.dylib`**,Linux 用不了。生产部署前在目标机 (或同架构 Linux)重编: ```bash cd rust NGINX_SOURCE_DIR= NGINX_BUILD_DIR=/objs \ cargo build --release cp target/release/libipass_gateway.so /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 /conf/nginx.cache.conf # 先校验 nginx -c /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` 里 `http://HOST/maven` | ✅ 完整(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/ ` | ⚠️ 索引✅ / 包本体✖(见下) | ### ⚠️ 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` = `:[?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 " http://HOST/api/v1/cache/stats # 按生态 × 状态计数(共享内存) tail -f /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 按制品失效(比整区清空细一档) 整区清空解决的是「这个生态整体脏了」。但更常见的事故是**局部**的:上游把 `lodash@4.17.21` 发成了坏包、某个 `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*/*` = `<路由>:<方法>`)。**不解析 `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 测试中验证),不会返回脏数据。 > ★★ **绝不能删掉 `/npm` 这些目录本身。** nginx 只在**启动时**创建 > `cache/`,运行期只按 `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 /npm/*`(尾随 `/*`)或 `find -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 | 清缓存**误删 `/` 目录本身**会让该生态彻底不可用 | nginx 不自愈:`[crit] mkdir() failed` + 直接断开客户端,直到 reload(§5.3 详述) | **首选** `POST /api/admin/cache/purge`(只删文件、目录不动);手工清一律 `rm -rf //*` 或 `find -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") ```