- 从本仓移除 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 升级方式、构建/接线说明
5.6 KiB
插件边界说明:本仓库(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:直读 nginxfile_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。要跟进主项目的新内核:
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/ 里直接改代码——那是主项目的源码,改了也不会被本仓提交,且会与上游冲突。