refactor: 改造为独立插件仓 ipass-plugin-cache(对齐兄弟仓形态)

- 扁平化:rust/crates/plugin-cache/src → src/,单包 Cargo.toml(name ipass-plugin-cache 2.0.0),
  path 依赖改 ../ipass-core(内核+vendor ngx),删除旧单体拆分残留(rust/ 层级、
  deps/ipass submodule、.gitmodules、conf/、tests/、多页静态 www/、AGENTS.md)
- R19 启停对齐:access/log 热路径加 plugin_registry::plugin_enabled("cache")
  门控,fail-closed 404(数据面是鉴权后磁盘读,禁用放行=无鉴权读缓存盘);
  location 圈定暂用 8 前缀路由表,ipass_cache 指令待 gateway 接入轮
- 旧独立应用形态保留在 tag legacy-app-final
- 文档:CLAUDE.md(装配关系+未挂载待办+本机编译 env 姿势)、README.md、
  docs/cache-usage.md 保留;docs/plugins.md(单体时代)删除
- 验证:cargo check --release 通过,cargo test 4 passed

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
adminandClaude Opus 4.8 committed 2026-09-24 21:15:57 +08:00
1 parent f7c70a0e19
commit 2c8fb2a1ee
128 files changed
+110 -9496

No files matched your search

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