# 插件边界说明:本仓库(cache) vs 主项目(ipass/ipass) ## 仓库拆分原则 为避免 cache 插件与 iPass 主框架相互干扰,本仓 `ipass/cache` **只保留 cache 插件本身的源码**;内核 `ipass-core`、模块壳 `gateway`、vendored `ngx-rust`、以及 domain/llm/apix 等其他子系统,**全部留在主项目 `ipass/ipass`**,本仓以 git submodule 形式引用: ``` 本仓 ipass/cache ├── rust/crates/plugin-cache ← 本仓唯一源码成员(cache 插件) ├── conf/ www/ tests/cache/ docs/ ← cache 专属资产 └── deps/ipass/ (submodule → http://192.168.1.18:13300/ipass/ipass) ├── rust/crates/ipass-core ← 内核(主项目维护) ├── rust/gateway ← 唯一 cdylib(主项目) ├── rust/vendor/ngx-rust ← vendored 绑定(主项目 pin) └── rust/crates/plugin-domain|llm|apix ← 其他子系统(主项目) ``` 本仓 `rust/Cargo.toml` 的 workspace 仅含 `crates/plugin-cache`,其依赖通过 `../deps/ipass/rust/...` 解析到 submodule。 ## 依赖方向(单向) ``` plugin-cache(本仓) │ 依赖 ▼ ipass-core(submodule)──▶ vendor/ngx-rust(submodule)──▶ nginx C 进程 ▲ gateway(submodule,唯一 cdylib,聚合 plugin 的 ngx_module_t) ``` 只有 `gateway` 是 cdylib,其余全是 rlib(跨 `.so` 传 Rust 类型会双重 free)。 ## 本仓库负责(cache) ### `plugin-cache`(rust/crates/plugin-cache,v0.1.0)★ 本仓唯一源码 统一制品缓存插件,本仓库的核心交付: - 8 路由制品代理:go / cargo / cargo-dl / pypi / pypi-files / npm / maven / docker v2 - 命中计量(`stats.rs`)、上游动态注入(`upstreams.rs` + `cx:` 共享内存写穿) - 管理 API(`api.rs` / `handlers.rs`):`GET /api/admin/cache` 容量、`POST /api/admin/cache/purge` 整区清理、`POST /api/admin/cache/invalidate` 按制品精准失效 - 容量管理(`zones.rs`:直读 nginx `file_cache` 共享内存记账,双轴磁盘 + keys_zone 索引内存) - 配套前端:`www/cache.html` + `www/assets/cache.js`(容量面板 + 按制品失效工具条) - 测试:`tests/cache/test-cache-capacity.sh`(48/48)、`test-real-registries.sh`、`verify-cache-eviction.sh` - 文档:`docs/cache-usage.md` > 改 cache 的路由行为、容量、purge / invalidate,只动本仓的 `plugin-cache` 与 `www/assets/cache.js`。 ## 主项目维护(ipass/ipass,经 submodule 引入) ### `ipass-core`(deps/ipass/rust/crates/ipass-core,v2.0.0)— 内核 共享内存原语(`cx:` / `ust:` / `ums:` / `ud:` 键空间)、账号 / 会话 / 认证(`auth::downstream_key`,`sk_` 三种携带位统一)、存储、通用 HTTP/api 框架、`config` / `state` / `usage` 记账原语。所有 plugin 依赖它,**方向只能是 plugin → core**。共享内存 schema 变更会影响全部 plugin,改前务必评估。 ### `gateway`(deps/ipass/rust/gateway)— 唯一 cdylib nginx 模块入口;聚合所有 plugin 的 `ngx_module_t`;FFI 边界(`panic="abort"`,跨 `.so` 不传 Rust 类型);模块加载顺序。**注意**:主项目 `gateway` 当前只装配 domain/llm/apix(不含 cache),要把 cache 编进可加载模块,需在主项目把 `plugin-cache` 加进 `members` 与 `gateway` 依赖(见 AGENTS.md「构建」)。 ### `plugin-domain` / `plugin-llm` / `plugin-apix`(deps/ipass/rust/crates/*)— 其他子系统 - `plugin-domain`:动态域名(子域名映射 / 申请审批 / 转发决策) - `plugin-llm`:LLM 路由 / 上游管理 / 配额计费 / 对话审计 / 用量趋势 - `plugin-apix`:API 代理(外部供应商资产挂网关) 由对应子系统团队在 `ipass/ipass` 维护;本仓不持有其源码,也不在其职责内。 ### `vendor/ngx-rust`(deps/ipass/rust/vendor/ngx-rust)— 上游 vendored `ngx` + `nginx-sys`(Rust 的 nginx C 绑定 fork)。主项目 pin 版本、vendored 以离线编译;上游是 ngx-rust 项目,iPass 维护其 vendoring 与 `panic="abort"` 配置。升级需重 pin + 全量重编译。 ### nginx / 构建链(build/)— 外部依赖 `build/nginx-1.30.4`、OpenSSL、PCRE2 源码与构建脚本;生产带 SSL 的完整 nginx 由 iPass 运维维护。本仓 `build/` 不入库。 ## 责任边界速查 | 组件 | 物理位置 | 归属 | 改前注意 | |------|----------|------|----------| | `plugin-cache` | 本仓 `rust/crates/plugin-cache` | 本仓库(cache) | 容量 / purge / invalidate 逻辑在此 | | `ipass-core` | submodule `deps/ipass/...` | 主项目 `ipass/ipass` | 共享内存 schema 变更影响所有 plugin | | `gateway` | submodule `deps/ipass/...` | 主项目 | 模块加载 / FFI 边界;当前不含 cache | | `plugin-domain` / `plugin-llm` / `plugin-apix` | submodule `deps/ipass/...` | 主项目各子系统 | 不在本仓库职责内 | | `vendor/ngx-rust` | submodule `deps/ipass/...` | 上游(vendored, 主项目 pin) | 升级需重 pin + 重编译 | | nginx / 构建链 | 外部 | 外部 | 生产 SSL conf 在主项目运维 | ## 如何更新内核 / 框架版本 本仓记录的 submodule 提交钉在 `.gitmodules` / gitlink。要跟进主项目的新内核: ```bash cd deps/ipass && git fetch && git checkout <新commit-or-main> && cd - git add deps/ipass # 更新 gitlink git commit -m "bump ipass-core via submodule" ``` **不要在 `deps/ipass/` 里直接改代码**——那是主项目的源码,改了也不会被本仓提交,且会与上游冲突。