docs(me+plugin): 登记 /api/v1/me 能力目录扩展点(1.0.16)
CLAUDE.md - 「核心机制」补第 6 条:/api/v1/me 是插件装饰扩展点,不是写死端点; 加新字段往 decorate_me 里塞,不要另开 v1 端点(避免老客户端脚本被破坏, 也避免能力目录被拆成 N 个调用) - 提示协作者给同事/文档/SDK 展示能力时直接讲 me docs/plugin/PLUGIN_ARCHITECTURE.md - §2.3 更新 decorate_me 签名为 (User, port)(1.0.16 引入):传 &User 让 装饰零额外 shm 查询就能做权限收敛(upstreams 按 allowed_models 过滤); port 从 Host 头取(不写死是已知坑) - 新增「decorate_me = 能力目录的承载点」子段:拍板决策 + 当前塞入字段表 (domains / llm_usage / policy / upstreams / apix)+ 新增字段的纪律 - §6 纪律补第 7 条:能力目录走 decorate_me,不要另开 /api/v1/catalog - §7 已拍板补 1.0.16 一条 "me 承载能力目录" 不动代码,仅文档同步。
This commit is contained in:
1 parent
479024c61e
commit
dfbfe5cf6c
2 files changed
+45
-3
No files matched your search
@@ -170,6 +170,13 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载
|
|||||||
**重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。
|
**重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。
|
||||||
5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。
|
5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。
|
||||||
改 `HASH_ROUNDS` 或拼接顺序会让存量 `users.json` 全部登录失败(已用独立 Python 实现逐字节核对过)。
|
改 `HASH_ROUNDS` 或拼接顺序会让存量 `users.json` 全部登录失败(已用独立 Python 实现逐字节核对过)。
|
||||||
|
6. **`/api/v1/me` 是插件装饰扩展点,不是写死的端点**。`ipass_core::api::CoreExt::decorate_me`
|
||||||
|
是身份端点的唯一装饰入口,由装配根(gateway)实现并把 `User` 与 `port` 一起传进来——
|
||||||
|
装饰能零额外 shm 查询就完成权限收敛(如 upstreams 按 `allowed_models` 过滤)。
|
||||||
|
**加新字段给同事发现能力时,往 `decorate_me` 里塞,别另开 v1 端点**:
|
||||||
|
- 老 3 个 v1 端点(`/api/v1/{domains,upstreams,apix}`)保留不破坏既有客户端脚本
|
||||||
|
- me 一个响应 = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略;同事拿一把 key 一个 me 拿全
|
||||||
|
- 给前端 / 文档 / SDK 展示时也直接讲 me,不要再分别介绍三个端点
|
||||||
|
|
||||||
## LLM API 代理(2026-09-10 新增)
|
## LLM API 代理(2026-09-10 新增)
|
||||||
|
|
||||||
|
|||||||
@@ -104,7 +104,12 @@ core→plugin 循环依赖。解法是**扩展注册表**:
|
|||||||
```rust
|
```rust
|
||||||
pub trait CoreExt: Sync {
|
pub trait CoreExt: Sync {
|
||||||
fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰
|
fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰
|
||||||
fn decorate_me(&self, username: &str, view: &mut Value) {} // me 装饰
|
// 1.0.16 起:传 &User(不仅是 username),让装饰零额外 shm 查询就完成权限收敛
|
||||||
|
// ——upstreams 按 allowed_models 过滤就是靠这里拿白名单。
|
||||||
|
// port 从请求 Host 头取(http::host_port),让 view_all 能拼出正确的
|
||||||
|
// `https://lm.mayishangshu.cn:88/...` base_url(部署在 88 必须带端口,
|
||||||
|
// 443 反代又不能带,见 CLAUDE.md「`base_url` 端口必须自适应」)。
|
||||||
|
fn decorate_me(&self, _user: &User, _port: &str, _view: &mut Value) {}
|
||||||
fn reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收
|
fn reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收
|
||||||
fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) }
|
fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) }
|
||||||
}
|
}
|
||||||
@@ -115,6 +120,30 @@ preconfiguration 时 `set_ext(&GatewayExt)` 注入。这是方案对原设计的
|
|||||||
原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/
|
原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/
|
||||||
me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。
|
me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。
|
||||||
|
|
||||||
|
#### `decorate_me` = 能力目录的承载点(1.0.16 拍板)
|
||||||
|
|
||||||
|
`/api/v1/me` **不是写死的端点**,它的所有插件侧数据都来自 `decorate_me`。
|
||||||
|
拍板决策:**给同事展示能力(域名 / LLM 上游 / API 代理)时往 `decorate_me` 里塞,
|
||||||
|
不要另开 `/api/v1/catalog` 这类聚合端点**。原因:
|
||||||
|
|
||||||
|
- 老 3 个 v1 端点(`/api/v1/{domains,upstreams,apix}`)保留不破坏既有客户端脚本
|
||||||
|
- 一个 me = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略,同事拿一把 key 一个请求拿全
|
||||||
|
- 上游白名单过滤靠 `User.allowed_models` 在装饰里就地完成,**不用让客户端先拉 me 再拉
|
||||||
|
upstreams 自己过滤**
|
||||||
|
|
||||||
|
当前 GatewayExt 在 `decorate_me` 里塞的字段:
|
||||||
|
|
||||||
|
| 字段 | 来源 | 过滤/筛选 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `domains` | `plugin_domain::domains::by_owner(user)` | 仅本人 |
|
||||||
|
| `llm_usage` | `plugin_llm::stats::user(name, now)` | 仅本人 |
|
||||||
|
| `policy` | core + plugin_domain config 常量 | — |
|
||||||
|
| `upstreams` | `plugin_llm::upstreams::view_all(&available(&user.allowed_models), port)` | **enabled + 白名单** |
|
||||||
|
| `apix` | `plugin_apix::apix::view_all(&enabled(), port)` | **仅 enabled** |
|
||||||
|
|
||||||
|
⚠️ **新增装饰字段时一律在 `view` 之前算好 `port`**,并明确标注「从 Host 头取、不写死」——
|
||||||
|
硬编码端口是已知坑(CLAUDE.md「`base_url` 端口必须自适应」实测踩过)。
|
||||||
|
|
||||||
### 2.4 `users::on_delete` 钩子(`core/users.rs`)
|
### 2.4 `users::on_delete` 钩子(`core/users.rs`)
|
||||||
|
|
||||||
删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器:
|
删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器:
|
||||||
@@ -200,8 +229,12 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注
|
|||||||
4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib;
|
4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib;
|
||||||
`[profile.release]` 只在 workspace 根。
|
`[profile.release]` 只在 workspace 根。
|
||||||
5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。
|
5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。
|
||||||
6. **验证 = `bash tests/run.sh all` 262 项全绿**;单 crate 迭代
|
6. **验证 = `bash tests/run.sh all` 全绿**(**当前 281**:网关 102 + LLM 179);
|
||||||
`cargo build -p plugin-llm`(秒级)。
|
单 crate 迭代 `cargo build -p plugin-llm`(秒级)。
|
||||||
|
7. **能力目录走 `decorate_me`,不要另开 `/api/v1/catalog`**。1.0.16 拍板:
|
||||||
|
同事拿 key 一个 me 拿全(域名 + LLM 上游 + API 代理 + 用量 + 策略),
|
||||||
|
老 3 个 v1 端点保留不破坏。新增插件侧能力展示字段一律往 `decorate_me` 里塞,
|
||||||
|
别再另开 v1 端点把能力目录拆成 N 个调用。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -214,6 +247,8 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注
|
|||||||
- [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
|
- [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
|
||||||
`plugin_llm::stats`(单一写入口)
|
`plugin_llm::stats`(单一写入口)
|
||||||
- [x] `/api/admin/trend` 留 gateway(组合根)
|
- [x] `/api/admin/trend` 留 gateway(组合根)
|
||||||
|
- [x] **`/api/v1/me` 承载能力目录(1.0.16)**:网关通过 `decorate_me` 把 domains /
|
||||||
|
upstreams / apix 一次性塞进 me,老 3 个 v1 端点保留不破坏
|
||||||
|
|
||||||
**1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten
|
**1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten
|
||||||
(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、
|
(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、
|
||||||
|
|||||||
Reference in new issue
Block a user