Files
adminandClaude Code 877ab5eaf4 docs(cache): 本机构建路径更新为共享位置
影响
- CLAUDE.md 里的 NGINX_SOURCE_DIR 还指向已迁走的旧目录,照着抄会直接构建失败。

改动
- CLAUDE.md:NGINX_SOURCE_DIR 改为 /Users/xs/Documents/ipass/ngxbuild/nginx-1.30.4。

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 18:09:15 +08:00

50 lines
2.3 KiB
Markdown
Raw Permalink 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.
# 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}/`。