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

68 lines
6.8 KiB
Markdown
Raw 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.
# 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。
## 构建
前置:本仓需要主项目代码来解析依赖。
```bash
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`](docs/plugins.md)。