diff --git a/CLAUDE.md b/CLAUDE.md index a2dc1a3..591d80e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,14 +11,7 @@ DNS 只配一条泛解析 `*.yourdomain.com` → 本网关;**子域名 → 后 定位覆盖**动态域名、LLM API 路由及未来各类统一出口能力**;另有一条 `lm.mayishangshu.cn:18098//...` 作为 LLM 统一出口(同一把 API Key 鉴权,下游永远拿不到厂商真 Key)。 技术栈:自编译 vanilla nginx + Rust 动态模块(`ngx-rust`)。无数据库、无 Redis、无消息队列、无额外常驻进程。 -状态 = `data/` 下三个 JSON 文件;**映射/会话/Key 索引全部常驻共享内存,热路径零文件 I/O**。 - -> **历史(2026-09-10)**:原实现是 OpenResty + Lua,已**全量重写**为 vanilla nginx + Rust 动态模块 -> (`rust/`、`conf/nginx.conf`、`Dockerfile`、`compose.yml`)。 -> 旧版完整归档于 `archive/openresty-lua-20260910/`(含 `SHA256SUMS` 与 tarball,已刻意排除 `data/`)。 -> 重写动机与依据见「性能基线」——**不要因为 Lua 版跑得动就回退**,收益在 miss 路径与多 worker,不在命中路径。 -> -> 顶层 `lua/` 目录是重写时的遗留副本,归档里已有权威版本;确认无引用后可删(**删前先问**)。 +状态 = `data/` 下四个 JSON 文件;**映射/会话/Key 索引全部常驻共享内存,热路径零文件 I/O**。 ## 构建与依赖(Rust 版 —— 踩过的坑都在这) @@ -131,7 +124,7 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载 | 路径 | 职责 | | --- | --- | -| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` / 三个 `subdomain_*` 开关 | +| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` + 四个 location 开关(`ipass_proxy` / `ipass_llm` / `ipass_apix` / `ipass_api`) | | `www/` | 管理台(多页,纯静态 + fetch):`login.html` + `overview/review/domains/users/upstreams/usage/apix.html` + `assets/`(共享 CSS/JS/图表)。每页 ``,见「管理台多页」 | | `data/users.json` | 账号表(含口令哈希与 API Key) | | `data/domains.json` | 子域名映射表 + 申请记录 | @@ -140,7 +133,6 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载 | `logs/access.log` | 已扩展字段:`backend=$proxy_backend_addr` | | `tests/` | **本机回归夹具**(`bash tests/run.sh [gateway\|llm\|all]`):`*.conf.in` 模板 + 断言脚本 + LLM 假上游;`tests/.run/` 是运行目录,已 gitignore。详见「本机验证夹具」 | | `docs/plugin/PLUGIN_ARCHITECTURE.md` | **插件化架构(as-built)**:契约、边界解法、装配清单、与 sso 的差异 | -| `archive/openresty-lua-20260910/` | 旧 Lua 版归档,**只读参考,勿再修改** | **插件化后的三条新纪律**(完整版见 `docs/plugin/PLUGIN_ARCHITECTURE.md` §6): @@ -166,13 +158,14 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载 - **API**(content,`ipass_api on`):**先异步读请求体**再分发(access 阶段拿不到 body,见「两段式读体」)。 - **API 代理**(access,`ipass_apix on`):查 `ukey:` 鉴权 + `ax:` 定供应商资产 → 填 `$apix_target/$apix_host/$apix_key/$apix_body`; **请求体由网关从 query 拼**(`asset_id` 服务端决定),GET 经 `proxy_method POST` + `proxy_set_body` 转带体请求。 -2. **共享内存是唯一真源,JSON 文件只是持久化副本**(**与旧版正好相反**)。 - 旧版是「文件是真源、shm 只是 600s 缓存」,代价是每次 miss 都要同步读文件 + 全表 JSON 解码 + O(n) 扫描。 +2. **共享内存是唯一真源,JSON 文件只是持久化副本**(**与重构前版本相反**)。 + 重构前是「文件是真源、shm 只是 600s 缓存」,代价是每次 miss 都要同步读文件 + 全表 JSON 解码 + O(n) 扫描。 现在**所有写操作同时写 shm 与文件**(write-through),miss 就等于「不存在」, 热路径永远零文件 I/O。**所以写穿不是优化,而是正确性要求**:漏掉 `sync_shm` 等于配置没生效。 - ⚠️ 语义代价:绕过 API 直接改 `data/*.json` **不再热生效**,需重启或走管理接口。 -3. **免审判定只有一处**:`domains::apply()` 里 `auto = dtype == "temp" && user.has_temp_permission(now)`。 - 改审批策略**只能改这里**,不要在 `api.rs` 里另写一套。 +3. **免审判定只有一处**:`plugin-domain` 的 `domains::apply()` 里 + `auto = dtype == "temp" && user.has_temp_permission(now)`。 + 改审批策略**只能改这里**,不要在身份端点或 api 层里另写一套。 4. **改 Key / 删域名必须摘掉旧索引**。`users::sync_shm` / `domains::sync_shm` 负责推 `ukey:` / `sub:`; **重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。 5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。 @@ -198,9 +191,9 @@ POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签 | 位置 | 职责 | | --- | --- | -| `rust/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler | -| `rust/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是 `domains.rs` 在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现 | -| `rust/src/stats.rs` | 用量计数(`ust:` 每账号 / `ums:` 每账号×上游,请求级、只读 shm)与 `overview()` 投影;**唯一写点在 `LlmHandler` 鉴权全通过之后** | +| `crates/plugin-llm/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler | +| `crates/plugin-llm/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是域名插件在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现 | +| `crates/plugin-llm/src/stats.rs` | 用量账本(`ust:` 每账号 / `ums:` 每账号×上游,请求级、只读 shm)与 `overview()` 投影;**唯一写点在 `LlmHandler` 鉴权全通过之后** | | `data/llm-upstreams.json` | 上游表(**含真实密钥**);`base` 可带路径,`auth` 是完整的 Authorization 值,`models` 仅供模型发现 | | `conf/nginx.conf` | `lm.mayishangshu.cn:18098` server;SSE 三件套 + `proxy_ssl_server_name` | | `users.json` → `allowed_models` | 上游白名单;**空 = 不限**(老数据没有该字段,反序列化即空表) | @@ -274,7 +267,7 @@ location 与 80 端口 LLM server 是两份拷贝,改一处记得同步另一 | query 参数丢失 | 变量形式的 `proxy_pass` 不会自动追加 args,靠 `llm::upstream_uri` 拼好 | **本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)、LLM 网关(18090) -与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **90 条** + LLM **111 条** +与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **102 条** + LLM **160 条** (`bash tests/run.sh all`,期望失败 0)。 `tests/llm/upstream.py` 会把收到的 `path` / `auth` / `host` / `body` 记到 `.run/llm/upstream.log` @@ -296,24 +289,24 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 ** | 变量 `proxy_pass`,不走模块 | 隔离「变量转发」本身开销 | 同上 | | shm 未命中(随机 Host / 扫描) | 查表未命中即 404,**无文件 I/O** | **与命中同量级**(旧版这里是 25× 慢) | -**换语言不提升热路径** —— 命中路径的开销测不出来,Lua 版在这一点上的结论仍然成立。 -收益来自两个结构变化,而不是「Rust 比 LuaJIT 快」: +**换语言不提升热路径** —— 命中路径的开销测不出来,重构前版本在这点上的结论仍然成立。 +收益来自两个结构变化,而不是换实现语言带来的解释器/编译器差异: -1. **miss 路径归零**。旧版 miss = 同步读文件 + `cjson` 解码 + O(n) 线性扫描, +1. **miss 路径归零**。旧版 miss = 同步读文件 + JSON 解码 + O(n) 线性扫描, 随机 Host 场景实测比命中**慢 25 倍**(见下表);新版配置全量常驻 shm,miss 就是「查不到」。 2. **可以开多 worker**。旧版 miss 的同步文件 I/O 会阻塞整个 worker,只能 `worker_processes 1` (实测单 worker 是全局瓶颈);新版热路径无阻塞 I/O,`worker_processes auto` 是安全默认。 -### 迁移依据(旧版 Lua 实测,保留作决策记录) +### 迁移依据(重构前实测,保留作决策记录) -单 openresty 容器、`ab -k -c 50`、12 核宿主机(前三条 ±20% 噪声,视为同一水平带): +单 worker 容器、`ab -k -c 50`、12 核宿主机(前三条 ±20% 噪声,视为同一水平带): | 路径 | 说明 | 吞吐 | | --- | --- | --- | -| 字面量 `proxy_pass` | 无 Lua,基准 | ~12.6k rps | -| 变量 `proxy_pass`,无 Lua | 隔离变量转发本身的开销 | ~11.1k rps | -| **shm 命中(旧版热路径)** | `access_by_lua` + `proxy_pass $backend_addr` | **~11.3k rps** | -| 缓存未命中:读 546B + cjson + 扫描 | `domains.resolve` 的真实成本 | ~5.7k rps(**-50%**) | +| 字面量 `proxy_pass` | 静态反代基线 | ~12.6k rps | +| 变量 `proxy_pass`,无动态语言 | 隔离变量转发本身的开销 | ~11.1k rps | +| **shm 命中(旧版热路径)** | `proxy_pass $backend_addr` | **~11.3k rps** | +| 缓存未命中:读 546B + JSON 解码 + 扫描 | `domains.resolve` 的真实成本 | ~5.7k rps(**-50%**) | | 缓存未命中:读 265KB / 1000 条 | 同上,表变大 | ~566 rps(**-95%**) | | 裸 `ngx.shared` get | 单次 | **0.073 µs/op** | @@ -327,13 +320,13 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 ** | 方案 | 说明 | 吞吐 | | --- | --- | --- | | **配置全量放内存** | shm 查表,miss = 不存在,**零 I/O** | **~13.9k rps** | -| 旧版 · 小表(3 条 / 812B) | miss → 读文件 + cjson + 线性扫描 | ~7.7k rps(**1.8× 慢**) | +| 旧版 · 小表(3 条 / 812B) | miss → 读文件 + JSON 解码 + 线性扫描 | ~7.7k rps(**1.8× 慢**) | | 旧版 · 大表(1000 条 / 266KB) | 同上,表变大 | ~543 rps(**25× 慢**) | -下表是当时针对**旧版 Lua** 得出的四点实施结论,**现在都已在 Rust 版落实**—— -保留它是为了说明当前设计为什么长这样,别按 Lua 的写法去理解: +下表是当时针对**重构前**得出的四点实施结论,**现在都已在 Rust 版落实**—— +保留它是为了说明当前设计为什么长这样: -| 结论(Lua 语境) | Rust 版对应实现 | +| 结论 | Rust 版对应实现 | | --- | --- | | 全量装载只跑一次,别每个 worker 各跑一遍 | 装载放在 `state_zone_init`(nginx 在 **fork 之前**回调一次),`init_process` 只负责播种 admin | | 必须跨 worker 共享,不能用模块级容器 | `ngx_shared_memory_add` + `SlabPool` + `RbTreeMap`;**锁也分配在共享内存里**(`RwLock` 在 slab 上),否则跨 worker 不互斥 | @@ -359,10 +352,12 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 ** **改配置/接口时的硬规矩** -- **新增接口三步**:① 在 `api.rs` 写 handler,返回统一用 `http::ok/fail`; - ② 在 `route()` 表加一行,`Guard` 选 `Public` / `User` / `Admin`; - ③ 涉及域名/Key/上游变更的,**必须调对应的 `sync_shm`**——漏了就等于没生效(无回源兜底)。 - 鉴权由分发器统一兜底,**不要在单个 handler 里重复实现**。 +- **新增接口三步**:① 在对应 crate 的 `api.rs` 写 handler(身份类进 `ipass-core`, + 业务类进所属插件 crate),返回统一用 `http::ok/fail`; + ② 在该 crate 的 `route()` 表加一行,`Guard` 选 `Public` / `User` / `Admin`; + ③ 涉及域名/Key/上游/代理变更的,**必须调对应的 `sync_shm`**——漏了就等于没生效(无回源兜底)。 + 鉴权由 gateway 分发器统一兜底,**不要在单个 handler 里重复实现**; + 插件 handler 不认领时返回 `None`,**绝不自行 404**。 - **所有写操作必须同时更新 shm 与 JSON 文件**。只写一边会出现「重启后配置回滚」或「改了不生效」。 - **写共享内存失败必须出声**。`state::put_*` 返回 `false`(zone 满 / 分配失败)时,三处 `sync_shm` 会 `log_err`(带对象标识与后果),三处 `reload_shm` 会核对「期望条数 vs 实际装载」。**别丢掉返回值**—— @@ -495,6 +490,9 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送 `rollback-*` 标签错位 → 回滚选错镜像,也没法从 tag 判断线上是哪一版。 - 脚本用 `docker manifest inspect` 探测远端,**同名 tag 存在即拒发**(需先 `docker login`); 发版前校验 `git status` 干净,保证 **tag ↔ commit** 一一对应。 + ⚠️ **脚本不校验是否已 push**——1.0.12 发版成功但代码没推到 Gitea,远端看不到(实测踩过)。 + **发版前先 `git push`**;日常一律走 `bash deploy/agent.sh release ` 一条龙 + (构建 → push CR → 远程更新 → 验收)。 - 本机必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。 - 发完之后在 .11 上更新走下一节的控制面,**`image` 显式填新 tag**。 @@ -567,7 +565,7 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback 夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。 ```bash -bash tests/run.sh # 全部:域名网关 90 条 + LLM 代理 111 条 +bash tests/run.sh # 全部 262 项:域名网关 102 条 + LLM 代理 160 条 bash tests/run.sh gateway # 只跑域名网关 bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游) ``` @@ -579,8 +577,8 @@ bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游) | 路径 | 作用 | | --- | --- | | `tests/run.sh` | 统一入口:编译 + 渲染配置 + 起停 + 跑断言 | -| `tests/gateway/e2e.sh` | **90 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理端与清理 | -| `tests/llm/e2e.sh` | **111 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** | +| `tests/gateway/e2e.sh` | **102 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理端与清理 | +| `tests/llm/e2e.sh` | **160 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** | | `tests/.run/` | 运行目录(渲染出的配置、`data/`、`logs/`、cookie)——**已 gitignore,随时可删** | **两条不许破的线**: diff --git a/Dockerfile b/Dockerfile index 3094f71..093016e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,9 +1,8 @@ # ipass-gateway —— 多阶段构建 # -# 与旧版(官方 openresty 镜像)的区别:这里必须自己编译 nginx。 -# 原因见 CLAUDE.md:ngx-rust 官方明确要求「针对生产上真正要用的那份 nginx 源码 + -# 完全相同的 configure 参数」编译模块,否则 bindgen 看到的符号/API 与实际运行时不一致。 -# OpenResty 的 nginx 打了大量补丁,不属于受支持组合,因此本项目改用官方 nginx。 +# 这里必须自己编译 nginx。原因见 CLAUDE.md:ngx-rust 官方明确要求「针对生产上 +# 真正要用的那份 nginx 源码 + 完全相同的 configure 参数」编译模块,否则 bindgen +# 看到的符号/API 与实际运行时不一致。 # --------------------------------------------------------------------------- # 构建阶段:编译 nginx + 编译 Rust 动态模块 diff --git a/compose.yml b/compose.yml index 1e6524c..3667194 100644 --- a/compose.yml +++ b/compose.yml @@ -4,7 +4,7 @@ # export ADMIN_INIT_PASSWORD='<初始管理员密码>' # 仅首次启动、users.json 不存在时生效 # docker compose up -d --build # -# 与旧版(官方 openresty 镜像)的区别:镜像需要自己构建(编译 nginx + Rust 模块), +# 镜像需要自建(编译 nginx + Rust 模块): # 因此用 build 而不是 image。conf 仍为只读挂载,data 可写。 services: gateway: diff --git a/conf/nginx.conf b/conf/nginx.conf index a4c1cc0..c59c85b 100644 --- a/conf/nginx.conf +++ b/conf/nginx.conf @@ -1,13 +1,12 @@ # ============================================================================ # iPass 山海关(ipass-gateway)—— vanilla nginx + Rust 动态模块 # -# 与旧 OpenResty 版的差异: -# * 不再需要 lua_package_path / lua_shared_dict / init_worker_by_lua -# * 共享内存由 ipass_state 指令创建,模块内部管理 -# * 管理 API 由 ipass_api 指令开启(content 阶段) -# * 转发热路径由 ipass_proxy 指令开启(access 阶段) +# * 共享内存由 ipass_state 指令创建,模块内部管理 +# * 管理 API 由 ipass_api 指令开启(content 阶段) +# * 转发热路径由 ipass_proxy 指令开启(access 阶段) +# * LLM 代理由 ipass_llm / API 代理由 ipass_apix(access 阶段) # -# 阶段处理器是 http 级的,所以**必须**靠上面两个开关按 location 收敛, +# 阶段处理器是 http 级的,所以**必须**靠 location 开关收敛, # 否则管理台自己也会被转发逻辑 404 掉。 # ============================================================================ @@ -57,7 +56,7 @@ http { # 模板见 conf/tls/llm.conf.example,说明见 conf/tls/README.md include /usr/local/nginx/conf/tls/*.conf; - # ========== 共享内存(替代旧版的 lua_shared_dict 三件套)========== + # ========== 共享内存(一张表,前缀区分用途)========== # 一张表同时承载:转发映射 / 管理会话 / 登录失败计数。 # 容量实测约 124 B/条,10m 足够放约 8 万条。 ipass_state state 10m; diff --git a/docs/plugin/PLUGIN_ARCHITECTURE.md b/docs/plugin/PLUGIN_ARCHITECTURE.md index c5dc800..20eb4d5 100644 --- a/docs/plugin/PLUGIN_ARCHITECTURE.md +++ b/docs/plugin/PLUGIN_ARCHITECTURE.md @@ -214,3 +214,8 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注 - [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走 `plugin_llm::stats`(单一写入口) - [x] `/api/admin/trend` 留 gateway(组合根) + +**1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten +(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、 +`state::iter_prefix_ex`。逐条采纳/撤回理由见 `SSO_UPSTREAM_DECISIONS.md`; +契约(trait / Switch / CoreExt)不变。 diff --git a/readme.md b/readme.md index 0602c26..eecc92e 100755 --- a/readme.md +++ b/readme.md @@ -145,39 +145,39 @@ DNS:*.yourdomain.com ──(泛解析,只配一次,永不修改)──▶ DNS: *.yourdomain.com → 本网关 IP(泛解析,只配一次) │ ▼ - ┌──────────────────────────────────┐ - │ nginx :80 + Rust 动态模块 │ - └───────────────┬──────────────────┘ - │ 按 Host 分流(模块自己解析 Host) - ┌──────────────────────────┴──────────────────────────┐ - ▼ ▼ - Host = mdm.mayishangshu.cn:18098 Host = <任意>.yourdomain.com - ┌──────────────────────────────────┐ ┌──────────────────────────────┐ - │ /admin 管理台(多页 HTML) │ │ 模块 access 阶段 │ - │ /api/v1/* 账号态 (X-API-Key)│ │ │ │ - │ /api/admin/* 管理员态(登录会话)│ │ ▼ │ - │ │ │ │ domains.rs: 查 sub: 共享内存 │ - │ ▼ │ │ (全量常驻,miss = 不存在) │ - │ api.rs 统一分发(content 阶段, │ │ 校验 status=approved │ - │ 先异步读请求体) │ │ 且 temp 未过期 │ - │ ├─ users.rs 账号/Key/授权 │ │ │ │ - │ ├─ domains.rs 申请/审核/过期 │ │ ▼ │ - │ └─ session.rs 管理员会话 │ │ 写 $proxy_backend_addr │ - │ │ │◀──────────┤ ▼ │ - │ ▼ │ sync_shm proxy_pass http://$proxy_backend│ - │ data/users.json(持久化副本) │ (写穿) └──────────────────────────────┘ - │ data/domains.json │ - └──────────────────────────────────┘ + ┌───────────────────────────────────────┐ + │ nginx :80 + libipass_gateway.so │ + │ gateway 装配根:7 条 ipass_* 指令 + │ + │ PLUGINS 注册表 + dispatch_api 统一 404│ + └───────────────┬───────────────────────┘ + │ location 开关收敛(阶段处理器是 http 级的) + ┌──────────────────────────┼───────────────────────────────┐ + ▼ ▼ ▼ + Host = mdm…:18098 Host = lm…:18098//… Host = <任意>.yourdomain.com + ipass_api on(content) ipass_llm / ipass_apix on ipass_proxy on(access) + ┌────────────────────┐ ┌────────────────────────┐ ┌───────────────────────────┐ + │ CorePlugin(内核) │ │ LlmPlugin / ApixPlugin │ │ DomainPlugin │ + │ 身份端点+会话 │ │ ukey: 鉴权 + 配额 │ │ 查 sub: 共享内存 │ + │ 先异步读请求体 │ │ up:/ax: 定上游 │ │ (全量常驻,miss = 不存在)│ + │ 再按 PLUGINS 顺序 │ │ 换上游真 Key 后转发 │ │ 校验 status=approved │ + │ 分发,无人认领 404 │ │ (下游不接触厂商 Key) │ │ 且 temp 未过期 │ + └─────────┬──────────┘ └───────────┬────────────┘ │ 写 $proxy_backend_addr │ + │ │ └────────────┬──────────────┘ + │ sync_shm(写穿) │ sync_shm │ + ▼ ▼ ▼ + data/ 四表:users.json / domains.json / llm-upstreams.json / api-proxies.json(持久化副本) ``` 设计要点: - **共享内存才是运行期唯一真源**,`data/*.json` 是它的持久化副本。 - 三个表(转发映射 / 账号 Key / LLM 上游)在 fork 前一次性装载进共享内存, - **热路径零文件 I/O**;未命中就等于「不存在」,不存在任何回源读文件的兜底路径。 + 各表在 fork 前一次性装载进共享内存,**热路径零文件 I/O**; + 未命中就等于「不存在」,不存在任何回源读文件的兜底路径。 - 所有写操作都会**同时更新共享内存与文件**(写穿),因此**审批一通过就立即生效**,且重启后配置不丢。 - 代价:手改 `data/*.json` 不再热生效,需重启。 - 转发侧只做一件事:查表 → 设置 `$proxy_backend_addr`。任何异常都只导致 404,不影响网关本身。 +- **插件化边界**:依赖方向只能 plugin → core,内核不 import 插件;插件数据反向流只走装配根 + (`CoreExt` 回填 / `on_delete` 钩子)。详见 `docs/plugin/PLUGIN_ARCHITECTURE.md`。 --- @@ -223,9 +223,7 @@ subdomain/ │ ├── domains.json # 子域名映射表 + 申请记录 │ ├── llm-upstreams.json # LLM 上游表(含厂商真 Key) │ └── api-proxies.json # API 代理表(含供应商真 Key) -├── logs/ # 日志(容器内软链到 stdout/stderr) -└── archive/ - └── openresty-lua-20260910/ # 旧 OpenResty+Lua 版归档(只读参考) +└── logs/ # 日志(容器内软链到 stdout/stderr) ``` 容器内路径映射(见 `compose.yml`): @@ -300,6 +298,7 @@ docker compose logs -f # 看到「已创建初始管理员 admin」即为 | **账号管理** | 新建账号(含展示名、临时授权权限);账号列表:复制/重置 API Key、授权或取消「临时授权权限」、改密码、设置可用上游与限流、删除账号 | | **LLM 上游** | 新建/编辑/启停/删除上游;模型清单维护;每行 slot 旁有 **OpenAI / Anthropic 两枚复制地址按钮**(按当前 Host 自动生成、已处理 `/v1` 拼接去重,点一下即复制,客户端拿去当 `base_url`,不用自己猜路径);**健康徽标**(`ok` 绿 / `failed` 红 / `unknown` 灰,打开面板自动探测,**测试**按钮可手动刷新) | | **用量统计** | 区间切换(7/14/30/90 天)+ **趋势视角**(全局 / 按账号 / 按 API 组)+ 两张明细表(今日 / 累计 / **入 token / 出 token** / 最近调用 / 分上游明细)+ 指标可切换的排名图 | +| **API 代理** | 外部 API 供应商资产挂到网关下(复用 `sk_` 鉴权 + 配额 + 用量):**列表页 + 弹出卡片编辑**(`IP.modal`),代理增删启停 / 复制地址(含示例 `?q=关键词`)/ 免费预估测试;供应商 Key 只回显掩码 | 趋势与 token 口径(与 §15 用量统计一致): @@ -471,7 +470,7 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口 - `type`:`temp`(临时)/ `long`(长期) - `status`:`pending`(待审)/ `approved`(已放行)/ `rejected`(已驳回);「已过期」是运行时计算出的状态,不落盘 - `reviewed_by == "auto"` 表示凭临时授权权限免审放行,其余为管理员账号名 -- 三个文件都是**原子写**(先写 `.tmp` 再 rename),并加了跨 worker 互斥锁,避免并发覆盖 +- 四个文件都是**原子写**(先写 `.tmp` 再 rename),并加了跨 worker 互斥锁,避免并发覆盖 ### `data/llm-upstreams.json` @@ -510,6 +509,34 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口 - `enabled: false` 会立即从共享内存摘除,等价于停用(配置保留便于恢复) - **该文件含上游厂商真实密钥,敏感级别等同 `users.json`** +### `data/api-proxies.json` + +```json +{ + "items": { + "web-search": { + "asset_id": "searxng-search", + "supplier": "provider-x", + "base": "https://api.example.com", + "key": "ak_<供应商真实密钥>", + "name": "网页搜索", + "desc": "按关键词搜索并返回结果", + "params": ["q"], + "enabled": true, + "note": "", + "created_at": 1789037728 + } + } +} +``` + +- 每条代理 = 挂在网关下的一个外部 API 供应商资产,账号用**同一把** `sk_` Key 调 + `GET /apix/?<参数>`;网关**从 query 拼请求体**(`asset_id` 由服务端决定, + 调用方只能选参数),换成 `key` 后转发(详见 §15.1) +- `base` / `key` / `supplier` 每条自带,无平台级凭据;`params` 是给调用方看的 + 参数清单(转发时不过滤);`enabled: false` 立即从共享内存摘除 +- **该文件含供应商真实密钥,敏感级别等同 `users.json`**;管理台只回显掩码 + --- ## 12. 运维 @@ -530,8 +557,8 @@ cp -a data /path/to/backup/ ``` **关于缓存**:映射命中后写入共享内存,TTL 600 秒(临时域名取剩余有效期与 600 秒的较小值)。 -通过管理台或 API 的增删改都会主动失效对应缓存,**立即生效**; -如果你直接手工编辑了 `data/domains.json`,需要 `docker compose restart` 让共享内存清空(或等 TTL 到期)。 +通过管理台或 API 的增删改都会**写穿共享内存**,**立即生效**; +如果你直接手工编辑了 `data/domains.json`,需要 `docker compose restart`(共享内存是运行期真源,改文件不热生效)。 **关于扩容**:共享内存和 JSON 文件都是**单实例内**的,多副本部署时各副本状态不共享。 当前定位是单实例出口;如需高可用,应把 `domains.json` 换成 Redis/etcd 之类的共享存储。 @@ -720,6 +747,8 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送 (控制面的回滚判重已改为按**镜像 id** 而非 tag 名比较,但 tag 本身仍应保持不可变。) - 脚本用 `docker manifest inspect` 探测远端,**同名 tag 已存在即拒绝发版**(需先 `docker login`)。 - 脚本先校验 `git status` 干净,保证 **tag ↔ commit** 一一对应(提交里记下 tag)。 + ⚠️ **脚本不校验是否已 push**——1.0.12 曾发版成功但代码没推到 Gitea,远端看不到。 + **发版前先 `git push`**,或直接走 `bash deploy/agent.sh release `(推荐,一条龙)。 - 本机构建必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。 | tag | 内容 | @@ -733,6 +762,11 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送 | `ipass-1.0.6` | **子域名规则固化为 `i`+8 位随机数+`dm`**(规则真源在 `config.rs`,经 `subdomain_rule` 下发给面板;API 不传 `subdomain` 即自动生成、撞车重试)+ **域名列表点完整域名即复制**(带端口,跟随调用方)+ **管理台布局改为自适应**(去掉 1180px 居中锁;表单另限宽 1100px)。digest `96c0e952…`,commit `12f20dd`。 | | `ipass-1.0.7` | **LLM token 级计量 + 对话审计日志**:body filter 旁路(FFI 全局符号注册,单 .so 无需额外 C 模块)解析 SSE 尾部 `usage` → `utt:`/`utms:` 键,用量接口增加 tokens 维度;log 阶段请求体归档到 `audit/`(data 兄弟目录,**10 GiB 容量阈值**触发式清理);LLM location 去掉 `proxy_request_buffering off`(与 body 落盘互斥,SSE 由 `proxy_buffering off` 保障)。控制面更新后自动挂审计卷。digest `5cd68ec4…`,commit `401f9be`。**注意:需先更新控制面(§12.5 自更新脚本)再 update,否则新容器缺审计挂载。** | | `ipass-1.0.8` | **管理台图表 + 单页拆分多页**。后端新增日桶 `ud:`/`udu:`/`uds:`(趋势数据源,TTL 90 天)与 `GET /api/admin/trend`;前端拆为 `login` + `overview`/`review`/`domains`/`users`/`upstreams`/`usage` 六页 + `assets/`(自绘 SVG 图表,零第三方依赖)。`/admin` 仍进总览;`agent.sh verify` 增加「趋势返回 7 天序列」作为换新证据。回归 227 条(网关 102 + LLM 125)。 | +| `ipass-1.0.9` | **新增「API 代理」板块**(见 §15.1 与 §16 续7):`/apix/` 把外部 API 供应商资产挂到网关下,复用 `sk_` 鉴权 + 配额 + 用量统计。 | +| `ipass-1.0.10` | 修复管理台登录页因会话探测 401 被通用兜底重定向的自刷新死循环(`/api/admin/session` 排除出 401 兜底)。commit `dbee9ff`。 | +| `ipass-1.0.11` | **API 代理去「市场」概念**:每条代理自带 `supplier`/`base`/`key`,无平台级凭据;管理台编辑改弹出卡片(`IP.modal`)。commit `1fb83e4`。 | +| `ipass-1.0.12` | **插件化重构**:workspace 化(ipass-core + 三插件 crate + gateway 唯一 cdylib),行为完全等价,262 项回归全绿。commit `ddd4172`。架构见 `docs/plugin/PLUGIN_ARCHITECTURE.md`。 | +| `ipass-1.0.13` | 采纳 sso 上游化建议 4 条(`User.extra` flatten / `split_value` rposition / `iter_prefix_ex` / `users::update_extra`)。commit `ee05b27`,评估记录 `docs/plugin/SSO_UPSTREAM_DECISIONS.md`。 | --- @@ -1021,6 +1055,29 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签 ## 16. 变更记录 +- **2026-09-13(续11)插件化重构(`ipass-1.0.12`)** + - 单 crate 拆为 **workspace**:`ipass-core`(内核)+ `plugin-domain` / `plugin-llm` / `plugin-apix` + 三个插件 crate(一律 rlib)+ `gateway`(**唯一 cdylib**,产物仍为 `libipass_gateway.so`)。 + 指令名、conf、`data/*.json` 零变化,行为完全等价。 + - 契约:`Plugin` trait(`dispatch_api` 不认领返回 `None`,404 由 gateway 统一发)、 + `loc::Switch` 并集注入、`CoreExt` 扩展注册表(身份端点的插件数据由 gateway 回填)、 + `users::on_delete` 钩子(删账号连带清理插件键空间)、`ctx_index` 注入(插件挂请求级状态)。 + - 下行鉴权/配额下沉 `core::auth`(LLM 与 apix 两条链路共用);记账原语下沉 `core::usage`, + 用量解读归 plugin-llm,apix 记账走同一写入口(slot 带 `api/` 前缀);`/api/admin/trend` 留 gateway。 + - 架构真源:`docs/plugin/PLUGIN_ARCHITECTURE.md`(as-built)。 +- **2026-09-13(续10)采纳 sso 上游化建议 4 条(`ipass-1.0.13`,commit `ee05b27`)** + - `User.extra` flatten(插件字段透传,存量数据零破坏)+ `users::update_extra`; + - `state::split_value` 改 `rposition`(payload 内含 `0x1f` 不再被截断,真 bug); + - `state::iter_prefix_ex`(返回 `(key, payload, exp)`,能力补齐)。 + - 评估与撤回记录:`docs/plugin/SSO_UPSTREAM_DECISIONS.md` + (A6-1 密码最短长度 6→8 会破坏测试边界用例,撤回)。 +- **2026-09-13(续9)API 代理去「市场」概念(`ipass-1.0.11`)** + - 每条代理自带 `supplier` / `base` / `key`,不再有平台级凭据与目录直拉面板; + 管理台编辑改**弹出卡片**(`IP.modal`),修示例地址拼接。 +- **2026-09-13(续8)修复管理台登录死循环(`ipass-1.0.10`)** + - 登录页会话探测的 401 被 core.js 通用兜底当作会话过期重定向回登录页,形成自刷新死循环; + 将 `/api/admin/session` 排除出通用 401 兜底。 + - **2026-09-13(续7)新增「API 代理」板块:把外部免费 API 供应商挂到网关下(`ipass-1.0.9`)** - 新增 `rust/src/apix.rs` + 模块:`/apix/?<参数>` → 供应商 `POST /api/v1/ai/request`, 网关**从 query 拼体**(`asset_id` 由服务端决定,调用方只能选参数),`sk_` 下行 Key 换成供应商 Key 后转发。 @@ -1208,18 +1265,17 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签 状态目录固定为 `tests/.run/*/data/` —— 跑回归**不会接触生产 `data/`**。 - 新增 LLM 侧断言 34 条:Key 替换 / 路径拼接 / 白名单 / 停用摘除 / SSE 不缓冲 / 限流 / HTTPS。 其中「Key 是否真被替换」读的是**假上游实际收到的请求头**,而不是网关自己的响应。 -- **2026-09-10 全量重写为 vanilla nginx + Rust 动态模块**(取代下面的 OpenResty+Lua 实现) - - 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从 Lua 平移进 Rust 模块, - **接口路径、请求/响应格式、`data/*.json` 字段与口令哈希算法全部保持兼容**,前端 `admin.html` 无需改动。 +- **2026-09-10 全量重写为 vanilla nginx + Rust 动态模块**(取代重构前的实现) + - 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从重构前实现平移进 Rust, + **接口路径、请求/响应格式、`data/*.json` 字段与口令哈希算法全部保持兼容**,前端管理台无需改动。 - 换掉了「文件是真源、共享内存只是缓存」的语义:**共享内存成为运行期真源**, 三个表在 fork 前一次性装载,热路径零文件 I/O,miss 不再回源读文件。 写操作全部写穿(shm + 文件),因此**审批通过即刻生效**,且重启不丢配置。 (动机:旧版随机 Host 未命中场景实测比命中慢 **25 倍**,且同步文件 I/O 迫使 `worker_processes 1`。) - - `worker_processes 1` → `auto`;Nginx 由官方 OpenResty 镜像改为**自编译 vanilla nginx**。 - - 新增 `rust/src`(13 个源文件,另含 `build.rs`)、`Dockerfile` 两段构建、vendored `ngx-rust`。 + - `worker_processes 1` → `auto`;Nginx 改为**自编译 vanilla nginx**(自编译是 ngx-rust 模块对运行环境的要求——见 Dockerfile 注释)。 + - 新增 `rust/` workspace(`crates/{ipass-core, plugin-domain, plugin-llm, plugin-apix}` + `gateway` cdylib)、`Dockerfile` 两段构建、vendored `ngx-rust`。 - 本地回归:`tests/gateway/e2e.sh` 共 **55 条断言**(`bash tests/run.sh gateway`), 覆盖全部接口 + 转发即时生效/失效 + 越权隔离。 - - 旧实现完整归档于 `archive/openresty-lua-20260910/`(含 `SHA256SUMS` 与 tarball,刻意排除 `data/`)。 - **2026-09-10 LLM API 代理** - 新增 `lm.mayishangshu.cn:18098` 统一出口:客户端用与域名接口**同一把** API Key 鉴权, 网关换成上游真实密钥后转发,下游不接触厂商 Key。 @@ -1234,12 +1290,11 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签 - 新增账号体系:多账号 + 每账号随机 API Key + 角色(`admin` / `user`)。 - 新增「临时授权权限」(6 小时,管理员勾选授予):持有者在申请临时域名时**免审直接放行**。 - 新增临时/长期域名区分与审核流:无权限的临时域名、以及全部长期域名进入管理员审核队列。 - - 新增管理台单页 `www/admin.html`:登录、审核队列、全部域名、账号管理。 - - 新增 API 分发器 `lua/api.lua`,用户态(API Key)与管理态(登录会话)分权。 + - 新增管理台单页(登录、审核队列、全部域名、账号管理),用户态(API Key)与管理态(登录会话)分权。 - 数据落盘从单个扁平映射 `proxy_config.json` 迁移为 `data/users.json` + `data/domains.json`(原 `test` / `testa` 两条映射已迁移为 admin 名下的长期域名)。 - 转发链路新增:状态与有效期校验、缓存 TTL 按剩余有效期收敛、写操作主动失效缓存。 - 安全加固:口令加盐迭代哈希、常量时间比较、`HttpOnly`+`SameSite` 会话、登录限速、只读挂载、默认拒绝。 - **2026-09-10 整理** - - 校验规则修正:原先的校验正则误用了 Lua 语法(`%w`/`%d`)却交给 PCRE 的 `ngx.re` 执行,已改为 PCRE 语法。 + - 校验规则修正:原先的校验正则误用了 Perl 风格语法(`%w`/`%d`)却交给 PCRE 的 `ngx.re` 执行,已改为 PCRE 语法。 - 管理台 `[hidden]` 失效修复(author 样式的 `display` 会盖掉 UA 的 `display:none`)。 - 补齐 `.gitignore`;清理 `.DS_Store`;`resolver` 改为国内可用 DNS。 diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 4ca9b5d..16d56fe 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -32,10 +32,10 @@ nginx-sys = { path = "vendor/ngx-rust/nginx-sys" } # 业务层依赖:全部是纯 Rust 实现,不引入任何系统库或常驻依赖 serde = { version = "1", features = ["derive"] } -serde_json = "1" # 替代 cjson;空 Vec/Vec 天然序列化为 [] / {},与旧版一致 -sha2 = "0.10" # 替代 resty.sha256;算法与旧版逐位一致(迭代加盐 SHA-256) -getrandom = "0.2" # 替代 resty.random;不可退化成可预测伪随机(API Key 由它生成) -libc = "0.2" # 仅用于 localtime_r / time(旧版由 os.date / ngx.time 提供) +serde_json = "1" # 序列化为紧凑 JSON;空 Vec/Vec 自动产出 [] / {} +sha2 = "0.10" # 迭代加盐 SHA-256;hash_password 算法已用独立 Python 实现逐位核对过 +getrandom = "0.2" # 不可退化成可预测伪随机(API Key / salt 由它生成) +libc = "0.2" # 仅用于 localtime_r(取本地时区) # 内核 crate(插件/gateway 一律引用它,方向只能是 plugin → core) ipass-core = { path = "crates/ipass-core" } diff --git a/rust/crates/ipass-core/src/config.rs b/rust/crates/ipass-core/src/config.rs index 91c583b..fcec74c 100644 --- a/rust/crates/ipass-core/src/config.rs +++ b/rust/crates/ipass-core/src/config.rs @@ -1,10 +1,11 @@ //! 内核策略常量(唯一真源)。 //! -//! 与旧 OpenResty 版的 `lua/config.lua` 一一对应:**改策略只改这里**, -//! 不要散落到各模块里,否则行为会出现多处真源。 +//! 内核策略常量(唯一真源)。 //! -//! 插件自有常量在各自 crate(plugin-domain/config.rs、plugin-llm/config.rs); -//! 这里只留「身份 / 会话 / 配额 / 两条下行链路共用」的部分。 +//! **改策略只改这里**,不要散落到各模块里,否则行为会出现多处真源。 +//! +//! 插件自有常量在各自 crate(plugin-domain/config.rs、plugin-llm/config.rs、 +//! plugin-apix/config.rs);这里只留「身份 / 会话 / 配额 / 两条下行链路共用」的部分。 /// 管理员授予的「临时授权权限」有效时长(秒) pub const TEMP_GRANT_TTL: i64 = 6 * 3600; diff --git a/rust/crates/ipass-core/src/session.rs b/rust/crates/ipass-core/src/session.rs index 35d05f7..173fb8e 100644 --- a/rust/crates/ipass-core/src/session.rs +++ b/rust/crates/ipass-core/src/session.rs @@ -1,10 +1,10 @@ //! 管理员登录会话。 //! //! 会话存在共享内存里:**nginx 重启即全部失效**,这是预期行为 -//! (旧版用 `lua_shared_dict admin_sessions`,同样如此)。 +//! ——管理会话不需要跨重启延续。 //! //! Cookie 为 `ipass_admin_session=<64 位 hex>`,HttpOnly + SameSite=Strict, -//! 每次校验命中都会滑动续期(与旧版一致)。 +//! 每次校验命中都会滑动续期。 use crate::config::{COOKIE_NAME, SESSION_TTL}; use crate::state; diff --git a/rust/crates/ipass-core/src/state.rs b/rust/crates/ipass-core/src/state.rs index 5dcaa4f..56434a0 100644 --- a/rust/crates/ipass-core/src/state.rs +++ b/rust/crates/ipass-core/src/state.rs @@ -1,8 +1,7 @@ //! 共享内存状态层。 //! -//! 这是「配置放内存」的落点,替代旧版的 `lua_shared_dict proxy_cache / -//! admin_sessions / lua_locks` 三个字典。全部派生状态集中在一张 -//! `RbTreeMap` 里,用键前缀区分用途: +//! 这是「配置放内存」的落点:所有派生状态集中在**一张** `RbTreeMap`, +//! 用键前缀区分用途: //! //! ```text //! sub: → \x1f 转发映射 @@ -12,9 +11,8 @@ //! //! ## 为什么过期时间写在 value 里,而不是靠字典的 TTL //! -//! 旧版 `lua_shared_dict` 自带 `set(key, val, ttl)` 自动回收;`RbTreeMap` -//! 是纯数据结构,没有 TTL。因此把到期时刻编码进 value,读取时判断—— -//! 语义上反而更精确(到期即失效,不受回收延迟影响)。 +//! 共享内存是裸 `RbTreeMap`,没有 TTL 自动回收。把到期时刻编码进 value, +//! 读取时判断——语义上反而更精确(到期即失效,不受回收延迟影响)。 //! //! ## 为什么锁必须放进共享内存 //! diff --git a/rust/crates/ipass-core/src/store.rs b/rust/crates/ipass-core/src/store.rs index ae75713..19e0d5d 100644 --- a/rust/crates/ipass-core/src/store.rs +++ b/rust/crates/ipass-core/src/store.rs @@ -1,8 +1,8 @@ //! JSON 文件存储层:原子写 + 跨 worker 互斥。 //! -//! 与旧版 `lua/store.lua` 语义一致——**状态就是几个 JSON 文件**,不引入数据库。 -//! 差别只有一处:互斥锁从 `resty.lock`(基于 lua_shared_dict)换成共享内存里的 -//! `RwLock`,因为新版已经有一块共享内存了,不必再造一个字典。 +//! **状态就是几个 JSON 文件**,不引入数据库。互斥锁在共享内存里的 `RwLock` +//! ——内核本来就要持一块共享内存(state zone),文件锁复用同一块 slab pool, +//! 不必再单独造字典。 //! //! 所有写操作统一走 `update_*`,流程固定为: //! diff --git a/rust/crates/ipass-core/src/users.rs b/rust/crates/ipass-core/src/users.rs index 9b41d1d..365ab2c 100644 --- a/rust/crates/ipass-core/src/users.rs +++ b/rust/crates/ipass-core/src/users.rs @@ -1,6 +1,6 @@ //! 账号体系:管理员与普通账号共用一张表。 //! -//! 对应旧版 `lua/users.lua`。数据结构见 `models::User`。 +//! 账号数据见 `models::User`。 //! //! 「临时授权权限」= 该账号申请**临时域名**时可跳过管理员审核、直接放行。 //! 注意它只对 temp 生效,long 域名无论谁申请都要审核。 diff --git a/rust/crates/ipass-core/src/util.rs b/rust/crates/ipass-core/src/util.rs index 6988480..22ee3cc 100644 --- a/rust/crates/ipass-core/src/util.rs +++ b/rust/crates/ipass-core/src/util.rs @@ -1,6 +1,7 @@ //! 通用工具:时间 / 随机 / 摘要 / 口令哈希 / 常量时间比较 / 格式化 / 参数解码。 //! -//! 对应旧版的 `lua/util.lua`。其中 `hash_password` 的算法**必须逐位一致**, +//! 其中 `hash_password` 的算法**必须逐位一致**(口径沿用自重构前实现, +//! 存量 `users.json` 才能正常登录), //! 否则旧的 `data/users.json` 里的口令哈希将全部失效。 use sha2::{Digest, Sha256}; diff --git a/rust/gateway/src/lib.rs b/rust/gateway/src/lib.rs index 3e202a1..1a8009f 100644 --- a/rust/gateway/src/lib.rs +++ b/rust/gateway/src/lib.rs @@ -1,18 +1,12 @@ -//! iPass 山海关(ipass-gateway)—— nginx + Rust 动态模块(v2) +//! iPass 山海关(ipass-gateway)—— nginx + Rust 动态模块 //! //! 尚数网 统一网关(动态域名 / LLM API 路由及未来各类统一出口能力)。 -//! 本模块承担原 OpenResty + Lua 版的**全部**职责: //! -//! | 旧版(Lua) | 新版(Rust) | -//! |------------------------------------|-------------------------| -//! | `lua_shared_dict proxy_cache` | `state` 共享内存映射表 | -//! | `lua_shared_dict admin_sessions` | `state` 会话键 | -//! | `lua_shared_dict lua_locks` | `state` 文件写锁 | -//! | `store.lua`(cjson + resty.lock) | `store` + serde_json | -//! | `users.lua` / `domains.lua` | `users` / `domains` | -//! | `api.lua` 路由表 | `api` 精确匹配路由表 | -//! | `proxy.lua` 转发热路径 | `ResolveHandler` | -//! | —(新增能力) | `LlmHandler` LLM 代理 | +//! 插件化定型后(2026-09-13),本 crate 仅作"装配壳":模块入口、7 条 +//! `ipass_*` 指令、`ModuleConfig` 开关、`ApiHandler` content 阶段两段式读体 +//! 后按 PLUGINS 顺序分发、trend 组合端点、state_zone_init 三表装载、 +//! `init_process` 播种 admin + 审计目录启动巡检。具体业务实现都在 +//! `crates/ipass-core` 与三个 `plugin-*` crate 里。 //! //! ## 三条热路径 //!