- 从本仓移除 ipass-core / plugin-domain / plugin-llm / plugin-apix / gateway / vendor/ngx-rust(这些属主项目 ipass/ipass) - 添加 git submodule deps/ipass -> http://192.168.1.18:13300/ipass/ipass(提供 core/gateway/ngx-rust/其他插件用于编译 cache 插件) - rust/Cargo.toml workspace 仅含 plugin-cache,依赖经 ../deps/ipass/rust/... 解析 - 移除根 tests/run.sh(主项目通用回归入口,非 cache 专用) - 修复 .gitignore:所有 tests/cache/.run-* 运行时目录均不入库(此前 .run-auth/.run-cap 被误提交,已解除跟踪) - 新增/更新 AGENTS.md 与 docs/plugins.md:明确本仓只含 cache 插件、core 从主项目取、submodule 升级方式、构建/接线说明
6.8 KiB
AGENTS.md — iPass cache 网关(插件仓)
面向 AI agent 的项目上手与改造约束。先读这份,再碰代码。
这是什么
iPass 统一制品缓存网关的插件仓(内网 Gitea:ipass/cache)。
一个 nginx 入口 + 一把统一 sk_ Key + 8 个路由(go / cargo / cargo-dl / pypi / pypi-files / npm / maven / docker v2),数据面用 nginx 原生 proxy_cache(本地磁盘),鉴权 / 计量 / 上游表由 Rust 模块管。
本仓只含 cache 插件本身的源码(见下「仓库边界」)。内核 ipass-core、模块壳 gateway、vendored ngx-rust、以及 domain/llm/apix 等其他子系统,不在本仓——它们属于主项目 ipass/ipass,本仓通过 git submodule(deps/ipass)引用,仅用于编译 cache 插件时解析依赖。
仓库边界(改前必看)
- ✅ 入库(本仓库职责):
rust/crates/plugin-cache(cache 插件源码)、conf(cache 网关 nginx 模板)、www(cache 管理台前端)、tests/cache(cache 端到端)、docs、AGENTS.md、docs/plugins.md。 - 🔗 以 submodule 引入(非本仓源码,来自
ipass/ipass,不要在本仓改):deps/ipass/(ipass-core/gateway/vendor/ngx-rust/plugin-domain/plugin-llm/plugin-apix)。 - ❌ 不入库(见
.gitignore):rust/target/、build/、*.dylib/*.so、tests/cache/.run-*/(所有测试运行时目录)、.workbuddy/。 - 远程:
origin = http://ssw:[email protected]:13300/ipass/cache.git,分支main。
⚠️ 避免相互干扰:本仓与主项目
ipass/ipass代码分离。cache 插件的全部修改只落在本仓;ipass-core等内核/框架的修改回到ipass/ipass。改内核共享内存 schema 前务必评估对所有插件的影响。
代码布局
本仓是一个单成员 cargo workspace,只编 plugin-cache:
| 组件 | 位置 | 版本 | 职责 | 归属 |
|---|---|---|---|---|
plugin-cache |
rust/crates/plugin-cache |
0.1.0 | 统一制品缓存:8 路由代理、命中计量、上游动态注入、管理 API、容量管理 | ★ 本仓库 |
ipass-core |
deps/ipass/rust/crates/ipass-core(submodule) |
2.0.0 | 内核:共享内存 / 账号 / 会话 / 认证 / 存储 / 通用原语 | 主项目 ipass/ipass |
gateway |
deps/ipass/rust/gateway(submodule) |
2.0.0 | 唯一 cdylib:聚合插件 ngx_module_t、FFI 边界 |
主项目 |
vendor/ngx-rust |
deps/ipass/rust/vendor/ngx-rust(submodule) |
— | vendored ngx + nginx-sys(离线编译) |
主项目(vendored) |
plugin-domain / plugin-llm / plugin-apix |
deps/ipass/rust/crates/*(submodule) |
2.0.0 | 其他子系统 | 主项目各子系统 |
plugin-cache 的依赖(ipass-core / ngx / nginx-sys)在 rust/Cargo.toml 中通过 ../deps/ipass/rust/... 指向 submodule。依赖方向单向:plugin-cache → ipass-core → vendor/ngx-rust → nginx C 进程;跨 .so 不传 Rust 类型(否则双重 free),所以只有 gateway 是 cdylib,其余全是 rlib。
构建
前置:本仓需要主项目代码来解析依赖。
git submodule update --init deps/ipass # 拉取 ipass-core / gateway / ngx-rust ...
- 仅类型检查 / 编译插件(rlib):
cd rust && cargo build -p plugin-cache。 这会顺着../deps/ipass把ipass-core与nginx-sys一起编出来(nginx-sys 需要NGINX_SOURCE_DIR/NGINX_BUILD_DIR指向一份 nginx 源码,见技能nginx-rs-module-local-verify)。 - 产出可加载模块(cdylib)并跑端到端:本仓没有
gateway(cdylib 在 submodule 里)。要在本机得到libipass_gateway.dylib并运行tests/cache/*.sh,请在主项目ipass/ipass中装配 cache 插件:- 把本仓的
rust/crates/plugin-cache放到ipass/ipass/rust/crates/plugin-cache(或让主项目以 submodule/override 消费本仓); - 在
ipass/ipass/rust/Cargo.toml的members加"crates/plugin-cache",在ipass/ipass/rust/gateway/Cargo.toml的[dependencies]加plugin-cache.workspace = true; - 按技能
nginx-rs-module-local-verify编译gateway得到.dylib,再以tests/cache/dev-server.sh/test-cache*.sh验证。
主项目
ipass/ipass当前的gateway只装配 domain/llm/apix(不含 cache),所以上面第 2 步是接 cache 的唯一接线点。 - 把本仓的
- macOS 编译 nginx 必须
-DNGX_HAVE_SCHED_SETAFFINITY=0;[profile.release]只能放 workspace 根(panic="abort",丢了意味着 panic 跨 FFI 边界展开进 nginx)。
端到端验证(基线,连跑两轮一致)
cache 测试都在 tests/cache/:
tests/cache/test-cache.sh23/23、tests/cache/test-ipass-cache.sh24/24、tests/cache/validate-prod-conf.sh✅、tests/cache/e2e-auth.sh29/29。- 容量管理:
tests/cache/test-cache-capacity.sh48/48。 - 跑法见
tests/cache/run.sh(或单独bash tests/cache/<脚本>);任何「读上游日志做断言」的步骤先断言本次 MISS,且测试开头清$RUN/cache。
不可动摇的架构约定(改前要懂)
- 上游地址 / 凭据只存共享内存
cx:<route>(管理台写穿,落盘data/cache-upstreams.json);conf 只出现变量名$cache_target/$cache_host/$cache_auth。改上游不改 conf、不 reload。 $cache_key必须含 query(<route>:<uri>[?args]);proxy_cache_key = $cache_key$request_method$http_accept(不含sk_)。sk_绝不外传上游:出站Authorization三段式(本路由凭据 → 透传客户端值 → 丢弃网关sk_);同时抹掉x-api-key/api-key。- 未配上游的路由 → 503(不是 500)。
- 唯一 conf 渲染器:
tests/cache/lib-render.sh(cache_render_prod_conf/cache_write_upstreams)。禁止手抄第二份「生产 conf → 测试前缀」替换逻辑。 - 清理缓存只删文件,绝不删
cache/<eco>目录本身(否则[crit] mkdir failed+ 客户端断开);批量清理用find <子树> -type f -delete+ 残留自检。 - 生成 / 改写 conf 一律用 python,不用 BSD
sed;脚本里curl统一--noproxy '*'(本机代理会吞 localhost)。
提交规范
- 只提交源码(
.gitignore已排除产物);push 到ipass/cache的main。 - 改动范围:只动本仓的
plugin-cache/conf/www/tests/cache/docs。若要升级ipass-core等,请到ipass/ipass改,或在本仓git submodule update拉新提交后git add deps/ipass。禁止在deps/ipass/里直接改代码(那是主项目源码)。 - 大 push 设
http.postBuffer=524288000;若报unable to get credential storage lock,先rm -f ~/.git-credentials.lock(无 git 进程时)。