# CLAUDE.md ## 入口(规划中,gateway 接入后生效) | URL | 目标 | |-----|------| | `http://nginx/go/ /cargo/ /cargo-dl/ /pypi/ /pypi-files/ /npm/ /maven/ /v2/` | 数据面(nginx 原生 `proxy_cache`;本插件 access 鉴权 + log 计量) | | `http://nginx/api/admin/cache*` | 本插件认领的管理 API(Admin) | | `http://nginx/api/v1/cache*` | 账号态接入说明 / 命中统计(User) | ## 装配关系 本仓库是 **ipass-core 内核**的一个 *crate 级* 插件(不是 nginx 动态模块)。 nginx 动态模块没有稳定 ABI,所有插件在 gateway 装配层以 `ipass_plugin_xxx` extern "C" 入口函数形式注册到单个 cdylib `.so` 内。 **当前状态:尚未挂载到任何 gateway**(2026-09-24 由旧独立应用仓 `ipass/cache` 改造为插件仓;旧形态完整保留在 tag `legacy-app-final`)。 接入时需要做的配套改动: 1. 宿主 gateway 的 `PLUGINS` 数组加 `&ipass_plugin_cache::CachePlugin` 2. 宿主 conf 加 `proxy_cache_path` 与各生态 location;location 级开关 `ipass_cache` 需给 core `loc::Switch` 补 `Cache` 变体,并同步三个 gateway 的穷尽 match(保守 false)——接入轮一并处理 3. ipass-core `plugin_registry::KNOWN_PLUGINS` 加 `"cache"`、 `plugin-config.example.json` 补条目 4. `www/` 重写为 UMD 面板(`plugin-cache-admin.umd.js`,对齐兄弟仓) ## 启停 与其他插件一致走 R19 注册表:配置键 = `cache`(`Plugin::name()` 短名)。 禁用语义与 waf/sso 的「放行」**不同**,是 fail-closed → 404——数据面是 鉴权后的磁盘读,禁用时放行等于无鉴权读缓存(见 `src/handlers.rs`)。 详见 `../ipass-core/docs/toggle.md`。 ## 构建/开发 本机不启用 `nginx-sys/vendored`,沿用兄弟仓姿势:env 指向一份已 configure 的 nginx 源码树(bindgen 从其 `objs/Makefile` 抽 `-I`;路径不可 `mv`, 详见 `../ipass-waf/rust/BUILD.md` 同款说明)。 ```bash export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib export NGINX_SOURCE_DIR=/Users/xs/Documents/ipass/ngxbuild/nginx-1.30.4 export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs cargo check --release && cargo test --release ``` 兄弟仓库:`../ipass-core/`、`../ipass-plugin-{domain,llm,apix,sso,waf}/`。