仓库拆分:本仓只保留 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 升级方式、构建/接线说明
This commit is contained in:
ssw committed 2026-09-21 11:05:45 +08:00
1 parent 43718bd0c4
commit 0464971c5c
205 files changed
+164 -27456

No files matched your search

+79
View File
@@ -0,0 +1,79 @@
# 插件边界说明:本仓库(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/` 里直接改代码**——那是主项目的源码,改了也不会被本仓提交,且会与上游冲突。