Files
ipass-plugin-cache/AGENTS.md
T
ssw 0464971c5c 仓库拆分:本仓只保留 cache 插件源码,core/gateway/其他插件经 submodule 引入
- 从本仓移除 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 升级方式、构建/接线说明
2026-09-21 11:05:45 +08:00

6.8 KiB
Raw Blame History

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 插件:
    1. 把本仓的 rust/crates/plugin-cache 放到 ipass/ipass/rust/crates/plugin-cache(或让主项目以 submodule/override 消费本仓);
    2. 在 ipass/ipass/rust/Cargo.toml 的 members 加 "crates/plugin-cache",在 ipass/ipass/rust/gateway/Cargo.toml 的 [dependencies] 加 plugin-cache.workspace = true;
    3. 按技能 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.sh 23/23、tests/cache/test-ipass-cache.sh 24/24、tests/cache/validate-prod-conf.sh ✅、tests/cache/e2e-auth.sh 29/29。
  • 容量管理:tests/cache/test-cache-capacity.sh 48/48。
  • 跑法见 tests/cache/run.sh(或单独 bash tests/cache/<脚本>);任何「读上游日志做断言」的步骤先断言本次 MISS,且测试开头清 $RUN/cache。

不可动摇的架构约定(改前要懂)

  1. 上游地址 / 凭据只存共享内存 cx:<route>(管理台写穿,落盘 data/cache-upstreams.json);conf 只出现变量名 $cache_target / $cache_host / $cache_auth。改上游不改 conf、不 reload。
  2. $cache_key 必须含 query(<route>:<uri>[?args]);proxy_cache_key = $cache_key$request_method$http_accept(不含 sk_)。
  3. sk_ 绝不外传上游:出站 Authorization 三段式(本路由凭据 → 透传客户端值 → 丢弃网关 sk_);同时抹掉 x-api-key / api-key。
  4. 未配上游的路由 → 503(不是 500)。
  5. 唯一 conf 渲染器:tests/cache/lib-render.sh(cache_render_prod_conf / cache_write_upstreams)。禁止手抄第二份「生产 conf → 测试前缀」替换逻辑。
  6. 清理缓存只删文件,绝不删 cache/<eco> 目录本身(否则 [crit] mkdir failed + 客户端断开);批量清理用 find <子树> -type f -delete + 残留自检。
  7. 生成 / 改写 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 进程时)。

插件边界

见 docs/plugins.md。