Files
ipass-plugin-cache/docs/plugins.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

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