update-agent-face.sh 与 readme.md 的 192.168.1.18:13300/raw 路径 一直写成 /ssw/ipass,实际仓库已迁移到 /ipass/ipass,需同步修正。 Co-Authored-By: Claude Opus 4.8 <[email protected]>
1512 lines
114 KiB
Markdown
Executable File
1512 lines
114 KiB
Markdown
Executable File
# iPass 山海关 — 尚数网 统一网关
|
||
|
||
> **一次泛解析,子域名无限;申请—审批—放行全流程在线。**
|
||
> 这是尚数网的**统一网关**,所有对外/对内服务统一从这里收口,当前承载两类能力:
|
||
>
|
||
> - **动态域名**:DNS 只配一条泛解析 `*.yourdomain.com` → 本网关,所有内部服务、演示环境、动态 IP 后端统一进出;
|
||
> 子域名映射通过管理台/接口热更新,**不改 DNS、不 reload Nginx、不重启容器**。
|
||
> - **LLM API 路由**:`lm.mayishangshu.cn:18098/<slot>/...` 作为公司所有大模型的统一出口,客户端只持一把网关签发的 Key。
|
||
>
|
||
> 未来各类需要统一收口的能力(访问审计、限流、代理路由等)都在这个网关上继续扩展。
|
||
|
||
技术栈:vanilla nginx + **Rust 动态模块**(`ngx-rust`)· 单容器 · 无数据库 · 无外部依赖 · 状态 = `data/` 下三个 JSON 文件
|
||
|
||
---
|
||
|
||
## 1. 它解决什么问题
|
||
|
||
给一个服务配个域名,传统链路是这样的:
|
||
|
||
```
|
||
申请子域名 → 加 DNS A 记录 → 写一段 server{} → nginx -s reload → 等 DNS 生效
|
||
```
|
||
|
||
只要服务地址变了(换端口、换机器、容器 IP 变了、临时开个演示环境),整条链路就要再来一遍。
|
||
更麻烦的是:**内网 IP 和动态 IP 根本无法在公网 DNS 里解析**,演示环境往往只能靠改 hosts 凑合。
|
||
|
||
而且如果放开给大家自己加,又会冒出第二个问题:**谁加的、什么时候过期、要不要收回,全凭自觉**。
|
||
一个临时演示域名挂上半年没人管、离职同事配的映射还在转发,这类事在「统一出口」里是会出事的。
|
||
|
||
本项目的做法是把「映射关系」从 DNS 层挪到网关层,再给它配一套**账号 + 申请审批**的治理:
|
||
|
||
```
|
||
DNS:*.yourdomain.com ──(泛解析,只配一次,永不修改)──▶ 本网关
|
||
网关:subdomain → backend 的映射表存在一个 JSON 文件里,通过管理台/接口热更新
|
||
治理:账号自己申请 → 临时授权权限免审放行 / 其余走管理员审批 → 临时域名 6 小时自动失效
|
||
```
|
||
|
||
于是「加一个子域名」退化成一次网页点击或一条 `curl`,**秒级生效、零重启**,而且每一步都有账号归属、有审批记录、有到期时间。
|
||
|
||
---
|
||
|
||
## 2. 核心价值
|
||
|
||
| 价值 | 说明 |
|
||
| --- | --- |
|
||
| **统一出口** | 全公司共用一个入口域名,出入网策略、访问审计、TLS 证书收敛到一处,不再每个项目各开一个口子 |
|
||
| **零运维变更** | 新增子域名 = 管理台点一下;不改 DNS、不改 Nginx、不 reload、不重启 |
|
||
| **打通内网 / 动态 IP** | 后端可填 `192.168.x.x:port`、容器服务名、随时变化的 IP —— 这类地址进不了公网 DNS,只能靠网关转发 |
|
||
| **旁路接入** | 后端服务**无需公网 IP、无需备案域名、无需改任何配置**即可被外部访问 |
|
||
| **权责清晰** | 每个域名有归属账号;每个账号有独立随机 API Key;谁申请、谁审批、什么时候到期,一目了然 |
|
||
| **临时域名自动回收** | 临时域名 6 小时自动失效,不用人工盯;过期即停止转发,记录保留可追溯 |
|
||
| **审批可控** | 「临时授权权限」把审批权下放给可信账号(免审直放),长期域名一律人工把关 |
|
||
| **可审计** | access.log 逐条记录 `subdomain → backend` + upstream 状态码 + 耗时;管理台保留申请/审批留痕 |
|
||
| **极轻量** | 单容器、零数据库、零外部依赖,起停一条命令 |
|
||
|
||
对比常见做法:
|
||
|
||
| 方案 | 加子域名耗时 | 内网/动态 IP | 需要 reload | 审批与归属 | 过期回收 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 每个服务加 DNS + server 块 | 分钟级 | ❌ | ✅ 要 | ❌ 无 | ❌ 无 |
|
||
| 纯 Nginx 反代 | 分钟级 | ✅ | ✅ 要 | ❌ 无 | ❌ 无 |
|
||
| 开放接口自助加映射 | 秒级 | ✅ | ❌ 不需要 | ❌ 无 | ❌ 无 |
|
||
| **本项目** | **秒级** | ✅ | ❌ **不需要** | ✅ **账号+审批** | ✅ **临时域名自动过期** |
|
||
|
||
---
|
||
|
||
## 3. 角色与权限模型
|
||
|
||
只有两种角色,规则简单到不会记错:
|
||
|
||
| 角色 | 登录管理台 | 申请临时域名 | 申请长期域名 | 管理账号 / 审批 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `admin` 管理员 | ✅ | ✅ 免审(管理员自身视为可信) | ✅ 免审 | ✅ |
|
||
| `user` 普通账号 | ❌ | 有权限免审 / 无权限待审 | 待审 | ❌ |
|
||
|
||
**临时授权权限**:管理员在创建账号时勾选,或事后随时授予/撤销,**有效期 6 小时**。
|
||
它只影响「临时域名能不能免审」,不影响长期域名,也不影响账号的其他能力。
|
||
过期即自动失效,不需要人工回收。
|
||
|
||
> 一句话记忆:**临时域名 + 有临时授权权限 = 直接放行;其他一切申请 = 管理员审核。**
|
||
|
||
---
|
||
|
||
## 4. 域名类型与状态机
|
||
|
||
### 两种域名
|
||
|
||
| 类型 | 代码 | 有效期 | 典型用途 |
|
||
| --- | --- | --- | --- |
|
||
| 临时 | `temp` | 审批通过后 **6 小时**自动失效 | 演示、联调、临时给外网看一眼 |
|
||
| 长期 | `long` | 长期有效 | 正式服务的固定入口 |
|
||
|
||
### 状态机
|
||
|
||
```
|
||
┌──── 有「临时授权权限」 ────▶ approved (reviewed_by=auto)
|
||
│ │ 6 小时后
|
||
申请 temp ──────┤ ▼
|
||
│ expired ──▶ 停止转发(记录保留)
|
||
└──── 无权限 ────▶ pending ──┬─ 管理员通过 ─▶ approved ─▶ 6 小时后 expired
|
||
└─ 管理员驳回 ─▶ rejected ──▶ 停止转发
|
||
|
||
申请 long ──────── 一律 ────────▶ pending ──┬─ 管理员通过 ─▶ approved(长期有效)
|
||
└─ 管理员驳回 ─▶ rejected
|
||
```
|
||
|
||
要点:
|
||
|
||
- **到期不等于删除**。临时域名过期后仅「不再转发」,记录仍在列表里显示为「已过期」,便于追溯;管理员可一键清理。
|
||
- **过期即释放**。某个子域名过期后,任何人都可以重新申请(不会一直被占着)。
|
||
- **审核即时生效**。审批通过后网关立刻开始转发,不需要重启、不需要等缓存(写操作会主动失效该子域名的转发缓存)。
|
||
|
||
### 子域名命名规则(`i` + 8 位随机数 + `dm`)
|
||
|
||
管理台「新建域名(直接放行)」的子域名不是自由输入,而是**三段拼装**,中间那段可点「换一个」重摇:
|
||
|
||
```
|
||
i + 8 位随机数字 + dm → i48291376dm
|
||
↑ ↑(可换) ↑
|
||
固定前缀 固定后缀
|
||
```
|
||
|
||
完整对外域名 = 子域名 + `.mayishangshu.cn`,即 `i48291376dm.mayishangshu.cn`。
|
||
面板「全部域名」里**点域名即复制**,且**带端口**——用 `:88` 打开面板就复制成
|
||
`i48291376dm.mayishangshu.cn:88`(端口跟随当前访问方式,理由见 §15「端口跟随调用方」)。
|
||
|
||
> **为什么后缀必须是 `dm`**:企业域名 server 的匹配正则是
|
||
> `^(.+dm)\.mayishangshu\.cn$`,捕获组**必须以 `dm` 结尾**;不以 `dm` 结尾的子域名
|
||
> 建出来也匹配不上转发 server(等于建了个打不开的域名)。这是硬约束,不是命名偏好。
|
||
|
||
规则真源在 **`rust/crates/plugin-domain/src/config.rs`**(`ENTERPRISE_ZONE` / `SUBDOMAIN_PREFIX` /
|
||
`SUBDOMAIN_SUFFIX` / `SUBDOMAIN_RAND_DIGITS`),由 `GET /api/admin/domains` 的
|
||
`subdomain_rule` 下发给面板——改后端常量,面板自动跟随;**改 zone 必须同步改
|
||
`conf/nginx.conf` 那条正则**(两处耦合,注释里已互相标注)。
|
||
|
||
**API 侧同规则**:`POST /api/admin/domains/create` 的 `subdomain` **缺省(或传空串)
|
||
即自动生成**同一形态的子域名,撞车会自动换一个重试(最多 5 次);传了值就用传入值
|
||
(仍做占用检查)。管理台提交的也是这个拼好的值,两条路径共用 `domains::create_by_admin`。
|
||
|
||
---
|
||
|
||
## 5. 架构与请求链路
|
||
|
||
```
|
||
DNS: *.yourdomain.com → 本网关 IP(泛解析,只配一次)
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────┐
|
||
│ nginx :80 + libipass_gateway.so │
|
||
│ gateway 装配根:7 条 ipass_* 指令 + │
|
||
│ PLUGINS 注册表 + dispatch_api 统一 404│
|
||
└───────────────┬───────────────────────┘
|
||
│ location 开关收敛(阶段处理器是 http 级的)
|
||
┌──────────────────────────┼───────────────────────────────┐
|
||
▼ ▼ ▼
|
||
Host = mdm…:18098 Host = lm…:18098/<slot>/… 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` 是它的持久化副本。
|
||
各表在 fork 前一次性装载进共享内存,**热路径零文件 I/O**;
|
||
未命中就等于「不存在」,不存在任何回源读文件的兜底路径。
|
||
- 所有写操作都会**同时更新共享内存与文件**(写穿),因此**审批一通过就立即生效**,且重启后配置不丢。
|
||
- 代价:手改 `data/*.json` 不再热生效,需重启。
|
||
- 转发侧只做一件事:查表 → 设置 `$proxy_backend_addr`。任何异常都只导致 404,不影响网关本身。
|
||
- **插件化边界**:依赖方向只能 plugin → core,内核不 import 插件;插件数据反向流只走装配根
|
||
(`CoreExt` 回填 / `on_delete` 钩子)。详见 `docs/plugin/PLUGIN_ARCHITECTURE.md`。
|
||
|
||
---
|
||
|
||
## 6. 目录结构
|
||
|
||
```
|
||
subdomain/
|
||
├── compose.yml # 单容器编排;镜像需自建(编译 nginx + Rust 模块)
|
||
├── Dockerfile # 两段构建:① 自编 vanilla nginx ② cargo 编 Rust 动态模块
|
||
├── readme.md # 本文档(人读)
|
||
├── CLAUDE.md # AI 协作者读的项目说明(含踩坑与性能基线)
|
||
├── .gitignore
|
||
├── conf/
|
||
│ └── nginx.conf # 四个 server(转发 / LLM / 管理 / 默认拒绝)、路由、共享内存声明、subdomain_* 系列指令(main 级 `ipass_state` / `ipass_data_dir` + location 级 `ipass_proxy` / `ipass_api` / `ipass_llm`)
|
||
├── rust/ # ★ Rust 动态模块(业务全部在这里;2026-09-13 起 workspace 化)
|
||
│ ├── Cargo.toml # workspace 根:members + 统一依赖 + [profile.release]
|
||
│ ├── build.rs # gateway 的 macOS -undefined dynamic_lookup
|
||
│ ├── vendor/ngx-rust/ # vendored 的 ngx-rust(不可换成 crates.io / git)
|
||
│ ├── crates/
|
||
│ │ ├── ipass-core/ # 内核:状态/账号/会话/下行鉴权(auth)/记账原语(usage)/契约(plugin,loc)/身份端点(api)
|
||
│ │ ├── plugin-domain/ # 域名插件:申请/审批/ResolveHandler(sub: 键空间)
|
||
│ │ ├── plugin-llm/ # LLM 插件:llm/upstreams/usage_filter/llm_audit/stats/handlers
|
||
│ │ └── plugin-apix/ # API 代理插件:apix/handlers/api(ax: 键空间)
|
||
│ └── gateway/ # 唯一 cdylib:模块壳(指令/开关)+ PLUGINS 注册表 + trend 组合端点
|
||
│ # 插件化架构详见 docs/plugin/PLUGIN_ARCHITECTURE.md
|
||
├── www/ # 管理台(多页,纯静态 + fetch)
|
||
│ ├── login.html # 登录页
|
||
│ ├── overview.html # 数据总览(卡片 + 趋势图 + Top 排名)
|
||
│ ├── review.html # 审核队列
|
||
│ ├── domains.html # 全部域名(新建 / 复制 / 删除)
|
||
│ ├── users.html # 账号管理
|
||
│ ├── upstreams.html # LLM 上游(API 组)
|
||
│ ├── usage.html # 用量统计(趋势 · 按人 · 按 API 组 · token)
|
||
│ ├── apix.html # API 代理(列表 + 弹出卡片编辑 + 免费预估测试)
|
||
│ └── assets/ # admin.css + core.js + chart.js + 各页 JS
|
||
├── tests/ # ★ 本机回归夹具(bash tests/run.sh [gateway|llm|all],281 项)
|
||
│ ├── run.sh # 统一入口:编译 + 渲染配置 + 起停 nginx + 跑断言
|
||
│ ├── gateway/ # 域名网关:nginx.conf.in + e2e.sh(102 条断言)+ 转发靶机
|
||
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(179 条)+ 假上游 + 合成夹具
|
||
│ # (.run/ 是运行目录,已 gitignore)
|
||
├── data/ # ★ 状态目录(需可写;运行期真源在共享内存)
|
||
│ ├── users.json # 账号表(含口令哈希与 API Key)
|
||
│ ├── domains.json # 子域名映射表 + 申请记录
|
||
│ ├── llm-upstreams.json # LLM 上游表(含厂商真 Key)
|
||
│ └── api-proxies.json # API 代理表(含供应商真 Key)
|
||
└── logs/ # 日志(容器内软链到 stdout/stderr)
|
||
```
|
||
|
||
容器内路径映射(见 `compose.yml`):
|
||
|
||
| 宿主 | 容器 | 权限 |
|
||
| --- | --- | --- |
|
||
| `./conf/nginx.conf` | `/usr/local/nginx/conf/nginx.conf` | 只读 |
|
||
| `./www` | `/usr/local/nginx/www` | 只读 |
|
||
| `./data` | `/usr/local/nginx/data` | **需可写** |
|
||
| (日志不挂载) | 镜像内已软链到 stdout/stderr | `docker compose logs` 查看 |
|
||
|
||
> **镜像需要自建**(`docker compose up -d --build`):官方 nginx 镜像里没有这个模块,
|
||
> 必须用与运行时**完全相同的 nginx 版本与 configure 参数**编译 `.so`,否则结构体偏移对不上。
|
||
|
||
---
|
||
|
||
## 7. 快速开始
|
||
|
||
### 7.1 换成你自己的域名
|
||
|
||
全局替换 `conf/nginx.conf` 里的 `yourdomain.com`(共 4 个 `server_name`:业务转发 server 的正则、LLM server、管理 server;默认拒绝 server 不涉及)。
|
||
|
||
### 7.2 DNS 泛解析(生产)
|
||
|
||
在你的域名服务商处加一条泛解析:`*.yourdomain.com` → 网关公网 IP。
|
||
**这只需要做一次,之后所有子域名都不用再碰 DNS。**
|
||
|
||
本机联调时改用 hosts(只需给要访问的子域名加,泛解析由网关负责):
|
||
|
||
```bash
|
||
echo "127.0.0.1 demo.yourdomain.com" | sudo tee -a /etc/hosts
|
||
echo "127.0.0.1 mdm.mayishangshu.cn:18098" | sudo tee -a /etc/hosts
|
||
```
|
||
|
||
### 7.3 启动
|
||
|
||
```bash
|
||
# 可选:指定初始管理员密码(不设则默认 123456,仅首次启动、users.json 不存在时生效)
|
||
export ADMIN_INIT_PASSWORD='<一个强密码>'
|
||
|
||
docker compose up -d --build # ★ 首次必须 --build:镜像里要编译 nginx + Rust 模块
|
||
docker compose logs -f # 看到「已创建初始管理员 admin」即为就绪
|
||
```
|
||
|
||
### 7.4 登录管理台
|
||
|
||
浏览器打开 **https://mdm.mayishangshu.cn:18098/admin**
|
||
|
||
- 初始账号:`admin` / `123456`(或你设置的 `ADMIN_INIT_PASSWORD`)
|
||
- **首次登录后请立刻在「账号管理」里改密码。**
|
||
|
||
### 7.5 走一遍完整流程
|
||
|
||
1. 「账号管理」→ 新建账号 `alice`,勾选 **给临时授权权限(6h)** → 记下弹出提示里的 API Key;
|
||
2. 再建一个 `bob`,**不勾选**;
|
||
3. alice 用 API Key 申请临时域名 → 返回「已直接放行」;
|
||
4. bob 用 API Key 申请临时域名 → 「审核队列」出现待审项;
|
||
5. 管理员在「审核队列」点通过 → bob 的域名立即可访问;
|
||
6. 6 小时后 alice 的临时域名自动变为「已过期」并停止转发。
|
||
|
||
---
|
||
|
||
## 8. 管理台使用
|
||
|
||
多页(每页一个 HTML,共用 `assets/` 里的样式与脚本),**`/admin` 直接进「数据总览」**:
|
||
|
||
| 页面 | 能力 |
|
||
| --- | --- |
|
||
| **数据总览** | 卡片:待审核申请 / 域名总数 / 可用中 / 账号总数 / LLM 上游数 / 今日与累计调用 / **今日与累计 token** / 可用模型数;**趋势图**:请求数、入/出 token(默认 14 天);**Top 8 排名**:按账号、按 API 组 |
|
||
| **审核队列** | 列出所有待审申请(子域名、后端、类型、申请人、提交时间),一键**通过**或**驳回** |
|
||
| **全部域名** | 管理员直接新建域名并放行(跳过审核,子域名按规则自动生成、可「换一个」);查看全部域名及其状态、到期倒计时;**点击域名即复制完整域名**(含端口);删除映射 |
|
||
| **账号管理** | 新建账号(含展示名、临时授权权限);账号列表:复制/重置 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 用量统计一致):
|
||
|
||
- **只统计真正转发给上游的请求**,401/403/404/429 不计;token 取自上游响应体里的 `usage`,
|
||
**抓不到记 0、不补估**(OpenAI 流式客户端需带 `stream_options.include_usage`)。
|
||
- 趋势是**按本地自然日分桶**的历史序列(后端 `ud:` / `udu:` / `uds:` 三组键,TTL 90 天),
|
||
与「今日 + 累计」是两套数据源——后者跨天归零、不区分日期,画不出曲线。
|
||
|
||
几点说明:
|
||
|
||
- **API Key 只在创建时完整展示一次**,列表里默认打码,可点「复制」取完整值;遗失就点「重置」(旧 Key 立即失效)。
|
||
- **删除账号会连带删除其名下所有域名**,避免出现无主映射。
|
||
- 状态徽章:`待审核`(黄)· `已放行`(绿)· `已驳回`(红)· `已过期`(灰);类型徽章 `临时 6h`(黄)/ `长期`(蓝)。
|
||
- 临时域名会显示到期时间与「剩余 X 小时 Y 分」。
|
||
|
||
---
|
||
|
||
## 9. 账号态 API(用 API Key 调用)
|
||
|
||
请求头携带 `X-API-Key: <你的 Key>`。适合脚本、CI、内部工具自助申请域名。
|
||
|
||
| 方法 | 路径 | 参数 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/api/v1/me` | - | 账号信息:角色、展示名、API Key、临时授权权限到期时间、名下域名、LLM 用量摘要 |
|
||
| GET | `/api/v1/domains` | - | 我申请的全部域名 |
|
||
| POST | `/api/v1/domains/apply` | `subdomain`、`backend`、`type`(`temp`/`long`) | 申请域名。符合免审条件即刻放行,否则进入待审 |
|
||
| POST | `/api/v1/domains/delete` | `id` | 删除自己名下的域名(只能删自己的) |
|
||
| GET | `/api/v1/upstreams` | - | 我有权限使用的 LLM 上游(`slot`、`base_url`、`anthropic_base_url`、`models`、`status` 健康状态) |
|
||
| GET | `/api/v1/models` | - | 我可用模型的**扁平清单**(每条含 `model`、`slot`、`base_url`),另附 `upstreams` 分组(含健康状态) |
|
||
| GET | `/api/v1/usage` | - | 我的 LLM 用量:今日 / 累计 / 最近调用时间 + 分上游明细 + 当前限流 |
|
||
|
||
> `/api/v1/models` 与 LLM 域名下的 `GET /v1/models` 是**同一份数据**、两种形状:
|
||
> 前者是网关统一响应体(`{code,msg,data}`,带 `base_url`),后者是 OpenAI SDK 期望的
|
||
> `{object:"list",data:[{id,...}]}`。客户端只认 SDK 时用后面的,自研/管理脚本用前面的。
|
||
|
||
### 9.1 上游健康状态(失效自动标记)
|
||
|
||
每个上游带一个 `status` 字段:`ok`(最近一次真实转发成功)/ `failed`(最近一次真实转发
|
||
失败,附 `status_code` 与 `checked_at`)/ `unknown`(从未被调用过)。
|
||
|
||
**数据来源是真实流量本身**:网关在 log 阶段把每次 LLM 转发的上游状态码写进共享内存
|
||
(`uh:<slot>`),4xx 视为「上游活着」(它对请求内容的意见),5xx / 连不上(502) /
|
||
等头超时(504) 记为失效;下一次成功转发自动恢复 `ok`,无需人工清理。这份缓存**只用于
|
||
展示**,不参与转发决策。管理台「LLM 上游」页会标出徽标,并对未探测/失效的上游在
|
||
打开面板时自动发一次 1-token 探测;「测试」按钮可随时手动刷新。
|
||
|
||
一把有效 Key 一次取齐「所有可用 API 地址 + 模型 + 健康状态」:
|
||
LLM 域名下 `GET /v1/models`(OpenAI 兼容形状)的顶层额外附 `x_ipass_upstreams`
|
||
(SDK 会忽略未知字段),每段含 `slot`、`base_url`(OpenAI 用)、`anthropic_base_url`、
|
||
`models`、`status`:
|
||
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $KEY" https://lm.mayishangshu.cn:88/v1/models | python3 -m json.tool
|
||
```
|
||
|
||
参数可用 JSON body、form 表单或 query string 传递。
|
||
|
||
```bash
|
||
export API=https://mdm.mayishangshu.cn:18098
|
||
export KEY=sk_你的key
|
||
|
||
# 申请临时域名(有临时授权权限时会直接放行)
|
||
curl -s -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
|
||
-d '{"subdomain":"demo","backend":"192.168.1.7:89","type":"temp"}' \
|
||
"$API/api/v1/domains/apply"
|
||
|
||
# 查看自己名下域名
|
||
curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains"
|
||
```
|
||
|
||
返回统一为 `{"code":200,"msg":"...","data":{...}}`。
|
||
|
||
**`backend` 取值形式**:`IP:端口`(推荐,无 DNS 依赖)、`hostname:端口`(经 `resolver` 解析)、`容器名:端口`(同 compose 网络内)。
|
||
|
||
**子域名规则**:小写字母/数字/短横线,不能以短横线开头,最长 62 位;`proxy-api`、`admin`、`www`、`api` 为系统保留名。大写会自动转小写。
|
||
|
||
---
|
||
|
||
## 10. 管理员 API(用登录会话调用)
|
||
|
||
需先 `POST /api/admin/login` 拿到会话 Cookie(管理台自动处理)。
|
||
|
||
| 方法 | 路径 | 参数 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/api/admin/login` | `username`、`password` | 登录(仅 `admin` 角色可用),返回会话 Cookie |
|
||
| POST | `/api/admin/logout` | - | 登出并销毁会话 |
|
||
| GET | `/api/admin/session` | - | 当前登录态 |
|
||
| GET | `/api/admin/users` | - | 账号列表(含 Key、展示名、临时授权状态、域名数、LLM 累计/今日用量) |
|
||
| POST | `/api/admin/users/create` | `username`、`password`、`role`、`grant_temp`、`display_name`(可选) | 新建账号,自动生成随机 Key |
|
||
| POST | `/api/admin/users/key` | `username` | 重置 API Key |
|
||
| POST | `/api/admin/users/grant` | `username`、`revoke`(可选)、`hours`(可选) | 授予(默认 6 小时,可指定)或撤销临时授权权限 |
|
||
| POST | `/api/admin/users/password` | `username`、`password` | 重置密码 |
|
||
| POST | `/api/admin/users/delete` | `username` | 删除账号并连带回收其域名 |
|
||
| POST | `/api/admin/users/display` | `username`、`display_name` | 设置展示名(中文名等;仅用于界面显示,不参与鉴权,传空串 = 回落账号名) |
|
||
| POST | `/api/admin/users/models` | `username`、`models`(逗号分隔 slot;空串 = 解除限制) | 设置可用 LLM 上游白名单;引用的 slot 必须已存在,否则报错 |
|
||
| POST | `/api/admin/users/limits` | `username`、`rpm`(每分钟,0/缺省=不限)、`daily`(每日,0/缺省=不限) | 设置 LLM 限流;`rpm` / `daily` 至少提供一个 |
|
||
| GET | `/api/admin/domains` | - | 全部域名 + 待审数量 + `subdomain_rule`(子域名命名规则,面板据此渲染输入框) |
|
||
| POST | `/api/admin/domains/review` | `id`、`action`(`approve`/`reject`) | 审批 |
|
||
| POST | `/api/admin/domains/create` | `backend`、`type`、`owner`、`subdomain`(可选) | 直接创建并放行。**`subdomain` 缺省/空串 = 自动生成** `i<8位随机数>dm`(撞车自动重试),传了就用传入值 |
|
||
| POST | `/api/admin/domains/delete` | `id` | 删除映射 |
|
||
| POST | `/api/admin/purge` | - | 清理已过期的临时域名与 7 天前的驳回记录 |
|
||
| GET | `/api/admin/upstreams` | - | LLM 上游列表(含 `base`、`models`、`model_count`、`note`、`enabled`,**不回显 `auth`**) |
|
||
| POST | `/api/admin/upstreams/save` | `slot`、`base`、`auth`、`models`(可选)、`enabled`(可选,缺省=启用)、`note` | 新增 / 更新上游;`auth` 留空 = 不透传鉴权头(本地免鉴权后端);`models` 逗号/顿号/分号/换行分隔,省略 = 保持原值 |
|
||
| POST | `/api/admin/upstreams/delete` | `slot` | 删除上游 |
|
||
| GET | `/api/admin/usage` | - | LLM 用量总览:全局合计 + 按账号 + 按上游(每个含今日 / 累计 / 最近调用 / token 合计) |
|
||
| GET | `/api/admin/trend` | `days`(可选,默认 14、上限 90) | LLM 用量趋势(图表数据源):按**本地自然日**分桶,返回 `{days, labels, total, users, slots}`,后三者各含 `requests` / `in` / `out` 三条与 `labels` 等长的数组 |
|
||
|
||
> 完整路由表以各插件 `api.rs` 的 `route()` 为准(ipass-core / plugin-domain / plugin-llm / plugin-apix 各管一段,精确匹配,新增接口三步见 CLAUDE.md「硬约定」)。LLM 相关接口(`users/models` / `users/limits` / `users/display` / `upstreams*` / `usage`)详见第 15 节。
|
||
|
||
---
|
||
|
||
## 11. 数据模型
|
||
|
||
### `data/users.json`
|
||
|
||
```json
|
||
{
|
||
"alice": {
|
||
"username": "alice",
|
||
"display_name": "爱丽丝",
|
||
"role": "user",
|
||
"salt": "<随机盐>",
|
||
"pwd_hash": "<迭代加盐 SHA-256>",
|
||
"api_key": "sk_<随机 48 位 hex>",
|
||
"allowed_models": ["openai", "deepseek"],
|
||
"llm_rpm": 60,
|
||
"llm_daily": 0,
|
||
"temp_grant_until": 1789059343,
|
||
"created_at": 1789037728
|
||
}
|
||
}
|
||
```
|
||
|
||
`temp_grant_until > 当前时间` 即表示该账号拥有「临时授权权限」。
|
||
|
||
`display_name` 是**纯展示用**的中文名/别名(管理台、用量报表按它显示,为空则回落 `username`)。
|
||
它**不参与任何鉴权或路由**,改它不需要重登、不影响 Key。上限 32 字符,禁止控制字符。
|
||
|
||
`api_key` 是**域名接口与 LLM 代理共用**的一把 Key:域名接口读 `X-API-Key`,
|
||
LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口。
|
||
|
||
`allowed_models` 是 LLM 代理可用的**上游白名单**(取值对应 `llm-upstreams.json` 的 key,
|
||
即 URL 第一段 slot,**不是具体模型名**)。**留空表示不限**;老数据没有该字段,
|
||
反序列化后即为空表,语义正好也是「不限」。
|
||
|
||
`llm_rpm` / `llm_daily` 是该账号的 LLM 限流:每分钟请求数 / 每日请求数,
|
||
`0` 表示**不限**;老数据缺省时取全局默认(`LLM_RPM_DEFAULT=60` / `LLM_DAILY_DEFAULT=0`,
|
||
定义在 `rust/crates/ipass-core/src/config.rs`,改策略只改那里)。详见「LLM API 代理 → 限流与配额」。
|
||
|
||
### `data/domains.json`
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "d_ed07615f1799",
|
||
"subdomain": "demo",
|
||
"backend": "192.168.1.7:89",
|
||
"type": "temp",
|
||
"owner": "alice",
|
||
"status": "approved",
|
||
"created_at": 1789037728,
|
||
"expires_at": 1789059328,
|
||
"reviewed_by": "auto",
|
||
"reviewed_at": 1789037728
|
||
}
|
||
]
|
||
```
|
||
|
||
- `type`:`temp`(临时)/ `long`(长期)
|
||
- `status`:`pending`(待审)/ `approved`(已放行)/ `rejected`(已驳回);「已过期」是运行时计算出的状态,不落盘
|
||
- `reviewed_by == "auto"` 表示凭临时授权权限免审放行,其余为管理员账号名
|
||
- 四个文件都是**原子写**(先写 `.tmp` 再 rename),并加了跨 worker 互斥锁,避免并发覆盖
|
||
|
||
### `data/llm-upstreams.json`
|
||
|
||
```json
|
||
{
|
||
"openai": {
|
||
"base": "https://api.openai.com",
|
||
"auth": "Bearer sk-<上游厂商真实密钥>",
|
||
"models": ["gpt-4o", "gpt-4o-mini", "text-embedding-3-small"],
|
||
"enabled": true,
|
||
"note": "生产 OpenAI",
|
||
"created_at": 1789037728
|
||
},
|
||
"deepseek": {
|
||
"base": "https://api.deepseek.com/v1",
|
||
"auth": "Bearer sk-<上游厂商真实密钥>",
|
||
"models": ["deepseek-chat", "deepseek-reasoner"],
|
||
"enabled": true,
|
||
"note": "",
|
||
"created_at": 1789037728
|
||
}
|
||
}
|
||
```
|
||
|
||
- key(`openai` / `deepseek`)就是客户端 URL 的第一段:
|
||
`https://lm.mayishangshu.cn:18098/openai/v1/chat/completions`
|
||
- `base` 必须显式带 `http://` 或 `https://`,可带路径(如 `https://gw.corp.com/llm`,
|
||
用于本身也挂在网关下的厂商)。**路径里若含 `/v1` 之类的版本段,网关会自动去重**:
|
||
上游 `base` 带 `/v1`、客户端又请求 `/v1/chat/completions` 时,只会拼出一个 `/v1`
|
||
(见「LLM API 代理 → 路径拼接」)
|
||
- `models` 是**这家上游提供的模型清单**,纯粹用于「模型发现」(`/v1/models` 与
|
||
`/api/v1/models`),**不影响转发**——网关照旧不解析请求体,也不按 `model` 字段路由。
|
||
留空 = 该上游不在模型列表里出现。上限 200 条、单条 128 字符
|
||
- `auth` 是**完整的 Authorization 头值**,转发时原样替换掉客户端传来的下游 Key;
|
||
留空表示不透传鉴权头(本地免鉴权后端,如 vLLM / Ollama)
|
||
- `enabled: false` 会立即从共享内存摘除,等价于停用(配置保留便于恢复)
|
||
- **该文件含上游厂商真实密钥,敏感级别等同 `users.json`**
|
||
|
||
#### 一个上游挂多个账号(`accounts`,可替代单个 `auth`)
|
||
|
||
同一厂商给了多把 Key、额度按周期清零时(典型:MiniMax「每周 + 每 5 小时」),
|
||
用 `accounts` 数组代替 `auth`,网关会把下游用户 Key **粘性绑定**到某一把上游 Key,
|
||
某把耗尽后自动切到同厂商下一把:
|
||
|
||
```json
|
||
{
|
||
"minimax": {
|
||
"base": "https://api.minimaxi.com",
|
||
"accounts": [
|
||
{"auth": "Bearer <key1>", "note": "主账号", "resets": [604800, 18000]},
|
||
{"auth": "Bearer <key2>", "note": "备用", "resets": [604800, 18000]}
|
||
],
|
||
"exhaust_status": [401, 402, 429, 403],
|
||
"exhaust_markers": ["\"status_code\":1004", "余额不足"],
|
||
"enabled": true
|
||
}
|
||
}
|
||
```
|
||
|
||
- `resets` 为**历史字段**(1.0.44 起不再参与路由,管理台已移除该输入):冷却与恢复改为
|
||
**指数退避 + 真实请求探测闭环**——耗尽账号到期后放一个**无绑定**真实请求过去探测,
|
||
2xx 立即回队、仍耗尽退避翻倍(60s→2m→…→30min 封顶),硬顶到期无条件回队自愈。
|
||
全链路不再需要知道厂商的重置窗口口径(旧的天锚定边界计算因两次算错锚点被整体删除,
|
||
见 `docs/llm/MULTI_ACCOUNT_ROUTING.md` §五)
|
||
- `accounts[].auth` 是完整的 `Authorization` 头值(如 `Bearer sk-…`)。**只填裸 key 也行**——
|
||
读出时 `normalize_auth` 自动补 `Bearer `,免去用户照着 placeholder 填了裸 key 而回 1004
|
||
(详见 `docs/llm/MULTI_ACCOUNT_ROUTING.md` §10)
|
||
- `exhaust_status` / `exhaust_markers` 是**上游级**耗尽判据(所有账号共用):
|
||
HTTP 状态码命中,或响应体流式扫描到标记子串,即判该账号额度耗尽
|
||
- 无绑定时按 `FNV-1a(下游 Key) % 可用账号数` **分散**(避免全压第一个账号触发厂商
|
||
「单账号 agent 并发上限」),但同一 Key 落点固定 → **prompt / token 缓存能命中**
|
||
- 管理台「上游」页的**密钥 / 负载**列展示每把 Key 的今日请求 / token / 耗尽次数、
|
||
负载比例条与 14 天迷你趋势,用于发现「谁被打满、谁在偏斜」
|
||
- 详见 `docs/llm/MULTI_ACCOUNT_ROUTING.md`
|
||
|
||
### `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/<slug>?<参数>`;网关**从 query 拼请求体**(`asset_id` 由服务端决定,
|
||
调用方只能选参数),换成 `key` 后转发(详见 §15.1)
|
||
- `base` / `key` / `supplier` 每条自带,无平台级凭据;`params` 是给调用方看的
|
||
参数清单(转发时不过滤);`enabled: false` 立即从共享内存摘除
|
||
- **该文件含供应商真实密钥,敏感级别等同 `users.json`**;管理台只回显掩码
|
||
|
||
---
|
||
|
||
## 12. 运维
|
||
|
||
```bash
|
||
# 实时看转发情况(自带 subdomain / backend / upstream 状态与耗时)
|
||
tail -f logs/access.log
|
||
|
||
# 看错误
|
||
tail -f logs/error.log
|
||
|
||
# 重启 / 停止
|
||
docker compose restart
|
||
docker compose down
|
||
|
||
# 备份状态(就是这两个文件)
|
||
cp -a data /path/to/backup/
|
||
```
|
||
|
||
**关于缓存**:映射命中后写入共享内存,TTL 600 秒(临时域名取剩余有效期与 600 秒的较小值)。
|
||
通过管理台或 API 的增删改都会**写穿共享内存**,**立即生效**;
|
||
如果你直接手工编辑了 `data/domains.json`,需要 `docker compose restart`(共享内存是运行期真源,改文件不热生效)。
|
||
|
||
**关于扩容**:共享内存和 JSON 文件都是**单实例内**的,多副本部署时各副本状态不共享。
|
||
当前定位是单实例出口;如需高可用,应把 `domains.json` 换成 Redis/etcd 之类的共享存储。
|
||
|
||
### 12.1 改了代码怎么验(本机回归)
|
||
|
||
夹具在仓库里 `tests/`,**不进 Docker**,直接在本机跑(秒级):
|
||
|
||
```bash
|
||
bash tests/run.sh # 全部:域名网关 102 条 + LLM 代理 197 条
|
||
bash tests/run.sh gateway # 只跑域名网关
|
||
bash tests/run.sh llm # 只跑 LLM 代理
|
||
```
|
||
|
||
脚本会自动 `cargo build`、把 `tests/*/nginx.conf.in` 渲染成带绝对路径的配置、
|
||
起 nginx(18080 转发 / 18081 靶机 / 18082 管理 / 18090 LLM 网关 / 18091 LLM 管理),跑完断言再收尾。
|
||
状态目录固定为 `tests/.run/*/data/`,**跑回归不会碰 `data/`**。期望输出「失败 0」。
|
||
|
||
> LLM 侧的关键断言不是看网关的响应码,而是读**假上游实际收到的请求头**——
|
||
> 「下游 Key 有没有真的被换成上游真 Key」只有这样才证得了。详见 `tests/README.md`。
|
||
|
||
### 12.2 TLS 证书管理(acme.sh)
|
||
|
||
证书是 acme.sh 签发的 `*.shangshuwang.cn` 泛域名 **ECC** 证书(SAN 含 `*.mayishangshu.cn`):
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| acme.sh 签发产物 | `~/.acme.sh/*.shangshuwang.cn_ecc/` |
|
||
| nginx 实际读取 | `conf/tls/*.shangshuwang.cn/fullchain.cer` + `*.shangshuwang.cn.key` |
|
||
| 当前有效期 | 2026-08-06 ~ 2026-11-04(Let's Encrypt 90 天) |
|
||
|
||
续期后同步并生效:
|
||
|
||
```bash
|
||
cp ~/.acme.sh/\*.shangshuwang.cn_ecc/fullchain.cer conf/tls/\*.shangshuwang.cn/
|
||
cp ~/.acme.sh/\*.shangshuwang.cn_ecc/\*.shangshuwang.cn.key conf/tls/\*.shangshuwang.cn/
|
||
nginx -s reload # 只换证书 reload 即可;改 conf/*.conf 或 rust/ 才需要 docker compose restart
|
||
```
|
||
|
||
> 证书是 ECC:校验 cert/key 配对要用公钥比对(`openssl x509 -pubkey` vs `openssl pkey -pubout`),
|
||
> `openssl rsa -modulus` 对 EC 私钥输出为空,会误报「不匹配」。
|
||
|
||
### 12.3 外网访问链路与环回(hairpin)
|
||
|
||
- 生产拓扑:DNS 泛解析 → 公网 IP → 路由器 NAT **18098 → 本机 18098**。
|
||
- **内网设备用公网 IP 访问「指向自己」的端口映射会失败**(hairpin 自环,路由器对
|
||
目标=发起者的回环流量处理不通);对其他内网机器的映射不受影响。
|
||
- 内网验证绕行:经内网代理机 TCP 中转(`:88 → 本机:18098`),外网访问用
|
||
`https://mdm.mayishangshu.cn:88/`(URL 必须显式带 `:88`)。
|
||
- 排查口诀(由内向外逐段定位):`curl -k https://127.0.0.1:18098/`(网关)→
|
||
`curl -k https://<LAN_IP>:18098/`(本机网卡)→ `curl -k https://<公网IP>:18098/`(NAT/环回)→
|
||
外部设备真域名(DNS+外网链路)。哪一段先断,问题就在哪一段。
|
||
|
||
### 12.4 更新部署(.11 一键脚本)
|
||
|
||
`deploy/update-ipass.sh` —— 拷到 .11 上跑,负责「拉新镜像 → 备份数据 → 删旧容器 →
|
||
用**原端口/原挂载**起新容器 → 自检」:
|
||
|
||
```bash
|
||
bash update-ipass.sh --check # 只体检:打印探测到的容器/端口/数据目录,不动任何东西
|
||
bash update-ipass.sh # 前台更新
|
||
bash update-ipass.sh --bg # 后台更新(日志落 ~/ipass-update-<时间>.log)
|
||
```
|
||
|
||
- **端口、附加挂载、网络、数据目录全部从旧容器自动复刻**(读 `docker inspect` 的静态配置,
|
||
所以容器处于停止态也能正确识别),不写死任何参数,避免换端口导致外部访问断掉。
|
||
- **持久化目录默认复用旧容器挂载**;全新部署时回落 `~/ipass/data`。可用 `DATA_DIR=` 覆盖。
|
||
- 动手前先 `tar` 备份数据目录到 `~/ipass-data-backup-<时间>.tar.gz`;旧镜像打上
|
||
`ipass-gateway:rollback-<时间>` 标签,结束时打印回滚命令。
|
||
- 数据目录会 `chown 65534:65534`(worker 是 nobody,不这么做写穿 JSON 会失败)。
|
||
- 私有仓库需先 `docker login`(或 `CR_USER=`/`CR_PASS=` 带凭据跑)。
|
||
- 旧容器若由 compose 创建,脚本会提示「已改用 docker run 接管」,想继续用 compose
|
||
请改用 `docker compose -f <file> up -d --force-recreate`。
|
||
|
||
### 12.5 远程更新控制面(ipass-agent)
|
||
|
||
`deploy/ipass-agent.py` —— 跑在 .11 上的**常驻 HTTP 服务**,把 §12.4 那套动作暴露成接口,
|
||
让**远端(AI / 值班人)不必登录服务器**就能完成「拉镜像 → 重启 → 看日志 → 回滚」,
|
||
形成「本机构建推送 → 远程自更新 → 远程自验证」的闭环(不必每次找人上机器操作)。
|
||
|
||
```bash
|
||
# 拷到 .11 后(用有 docker 权限的账号跑)
|
||
python3 ipass-agent.py --check # 只探测:打印容器/端口/数据目录,不动任何东西
|
||
python3 ipass-agent.py --bg # 后台常驻,默认 0.0.0.0:18099
|
||
python3 ipass-agent.py --bg --name ipass --data-dir /opt/ipass/data
|
||
python3 ipass-agent.py --stop # 停止
|
||
tail -f ~/ipass-agent.log # 日志(pid 在 ~/ipass-agent.pid)
|
||
```
|
||
|
||
**远程自更新(.11 上执行,改控制面不用人工拷文件)**:
|
||
|
||
```bash
|
||
bash <(curl -fsSL http://192.168.1.18:13300/ipass/ipass/raw/branch/main/deploy/update-agent-face.sh)
|
||
```
|
||
|
||
脚本自动:从 Gitea raw 下载新版 → 备份旧版(`*.bak-<时间戳>`)→ `py_compile` 校验 →
|
||
`--stop` 停旧 → **按原启动参数** `--bg` 重启 → `/health` 自检。
|
||
token 在 `~/.ipass-agent-token`,重启沿用,远端 `agent.sh` 无需改配置;全程不碰网关容器。
|
||
|
||
- 单文件、**只用 Python 标准库**(不需要 Flask / requests),有 `python3` 就能跑。
|
||
- **鉴权**:除 `/health` 外全部要 `Authorization: Bearer <token>`;token 首次启动随机生成并写入
|
||
`~/.ipass-agent-token`(权限 600),也可用 `--token` 或环境变量 `IPASS_AGENT_TOKEN` 指定。
|
||
- 端口/挂载/网络/env/重启策略**全部从旧容器 `docker inspect` 复刻**,不写死任何参数;
|
||
自定义 env 会保留,Docker 自带的(PATH / NGINX_VERSION…)不会照抄。
|
||
- 变更类接口是**异步任务**:立刻返回 `{"job":"<id>"}`,用 `GET /jobs/<id>?offset=N` 增量拉日志。
|
||
**同一时刻只允许一个变更任务**(第二个返回 409),避免并发删容器互相踩。
|
||
- 动手前自动 `tar` 备份数据目录(含 audit)到 `~/ipass/backup/ipass-data-<时间>.tar.gz`
|
||
(1.0.17 起不再给旧镜像打本地 `rollback-*` 标签——私仓永远保留所有 tag,回滚须显式传 tag)。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/health` | 存活 + 版本(**免鉴权**) |
|
||
| GET | `/` | 服务信息 + 端点清单 |
|
||
| GET | `/check` | 探测(dry-run),等价 `--check` |
|
||
| GET | `/status` | 容器状态 + 镜像 digest + 数据摘要 + 宿主探活 |
|
||
| GET | `/containers` | 所有容器(`managed` 字段标出哪个是**受管容器**) |
|
||
| GET | `/logs?tail=200` | **受管容器**的日志 |
|
||
| GET | `/data?file=users\|domains\|upstreams` | 数据文件摘要(**`api_key` 已脱敏**) |
|
||
| GET | `/jobs?limit=5`、`/jobs/<id>?offset=N` | 任务列表 / 任务详情 + 增量日志 |
|
||
| POST | `/pull` | `{image, registry_user?, registry_pass?}` → 只拉镜像 |
|
||
| POST | `/update` | `{image?, skip_pull?, name?, data_dir?, host_port?}` → 完整更新(`name` 只接受受管容器) |
|
||
| POST | `/rollback` | `{tag, restore_backup?}` → 回滚到指定 tag(1.0.17 起**必须显式传 tag**,本地没有会自动 pull);`restore_backup` 给 update 返回的备份 tar 路径时,先停容器把 data/audit 恢复成备份时刻再回滚(发版验证失败的自动回滚用,控制面 ≥1.0.2) |
|
||
| POST | `/restart` | 只重启容器(同步返回;`{name?}` 只接受受管容器) |
|
||
|
||
典型远程调用:
|
||
|
||
```bash
|
||
A=http://192.168.1.11:18099; T='Authorization: Bearer <token>'
|
||
|
||
curl -s -H "$T" $A/status # 先看现状
|
||
curl -s -H "$T" -H 'Content-Type: application/json' \
|
||
-d '{"image":"crpi-…/ssw188/nginx:ipass-1.0.1"}' $A/update # 更新,返回 job id
|
||
curl -s -H "$T" $A/jobs/<job-id> # 拉执行日志(7 步全记录)
|
||
curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback # 出事回滚
|
||
```
|
||
|
||
> `image` 填**当前要上的 tag**(§12.6 的约定:只增不改,发新版就换新号,别覆盖旧号)。
|
||
> 不传 `image` 时用服务启动时的默认值(`--image` 指定,缺省 `ipass-1.0.0`)。
|
||
|
||
#### 推荐走 `deploy/agent.sh`(别手敲上面的 curl)
|
||
|
||
裸 `curl -H "Authorization: Bearer …"` 会把凭据摆到命令行上:既容易漏进 shell 历史 / 进程列表,
|
||
也会命中**「可疑命令即使已加白名单仍需人工批准」**的安全策略,于是**每次都弹「凭证授权」**;
|
||
被拒时命令还会**静默无输出**,看着像服务挂了(实测踩过:一次 `/update` 就是这样没发出去)。
|
||
|
||
`deploy/agent.sh` 把凭据只从仓库根 `.env` 读,对外暴露的全是无凭据子命令,因此只需放行一条
|
||
`Bash(bash deploy/agent.sh:*)`:
|
||
|
||
```bash
|
||
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
|
||
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
|
||
bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印 7 步日志
|
||
bash deploy/agent.sh verify # 正式环境验收:登录 → 页面标记 → 后端 subdomain_rule
|
||
bash deploy/agent.sh release 1.0.7 # 一条龙:构建推送 → 更新 → live_check 发版后验证
|
||
# → 网关侧故障自动回滚镜像 + 恢复数据备份
|
||
bash deploy/agent.sh rollback <tag> [备份tar] # 出事回滚(带 tar 同时恢复数据)
|
||
```
|
||
|
||
`verify` 是「镜像真的换新了没有」的落地检查:它登录线上管理台,核对页面里的新标记
|
||
(如布局的 `max-width:1100px`、子域名规则的 `subdomain_rule` / `cdSubRoll`),
|
||
并读 `GET /api/admin/domains` 确认后端常量已生效——**光看容器起来是不够的**。
|
||
|
||
**爆炸半径:只碰一个容器**。虽然它等价 docker 权限,但**破坏性操作只作用于「受管容器」**——
|
||
`--name` 指定者优先,否则自动探测到的 ipass 容器;两者都没有时退化为 `ipass*` 前缀白名单。
|
||
`/update`、`/rollback`、`/restart` 请求里带 `name` 且**不等于**受管容器 → **直接 403**,
|
||
不建任务、更不会碰那个容器;`GET /containers` 的 `managed` 字段标明受管的是谁。
|
||
(实测:对同机另一个容器发这三种请求全部 403,该容器 `StartedAt` 前后完全不变。)
|
||
|
||
**安全**:这个服务能删/起容器,**等价服务器上的 docker 权限**,务必做到
|
||
① **必须设 token**(别用空/弱口令);② 只在内网监听(默认 `0.0.0.0`,可 `--bind 127.0.0.1`
|
||
或加防火墙);③ **绝不暴露到公网**。`/data` 对 `api_key` 已脱敏,但 `domains.json` 会原样返回。
|
||
|
||
> `update-ipass.sh`(§12.4)仍然保留:没有 python3、或服务没起来时的应急手段。
|
||
|
||
### 12.6 镜像发版与 tag 约定(只增不改)
|
||
|
||
对外镜像 tag 形如 **`ipass-1.0.0` / `ipass-1.0.1` / `ipass-1.0.2` ……**:
|
||
**每有一次代码变更就 +1 推新 tag,绝不覆盖已推送过的 tag。**
|
||
|
||
```bash
|
||
bash deploy/release.sh 1.0.2 # 构建 → 打 tag → 推送 → 打印远程更新命令
|
||
bash deploy/release.sh 1.0.2 # 再跑一次:远端同名 tag 已存在 → 直接拒绝
|
||
DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
|
||
```
|
||
|
||
- **为什么只增不改**:同名 tag 被覆盖后,远端 `pull` 到的内容与本地缓存 / 已打的
|
||
`rollback-<时间>` 标签对不上 → 回滚会选错镜像;也没法再从 tag 判断线上跑的是哪一版。
|
||
(控制面的回滚判重已改为按**镜像 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 <tag>`(推荐,一条龙)。
|
||
- 本机构建必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。
|
||
- ⚠️ **发版后把 `.env` 的 `IPASS_IMAGE_TAG` 同步成新 tag。** `update` 不带 tag 时用它做缺省值,
|
||
它落后于线上就会**静默降级**回旧镜像(真踩过:1.0.14 发完,`.env` 还停在 1.0.9)。
|
||
`agent.sh verify` 已加一条**漂移告警**(`.env` 默认 tag 与线上不一致时打印 `!` 提示,不判失败),
|
||
发版一条龙结尾必跑 verify,所以每次都会被提醒。该文件受沙箱**写入保护**(凭据文件),需人工改。
|
||
- **`agent.sh release` 失败不再停在原地**(一条龙 4 步:构建推送 → 更新 → **live_check 发版后验证**
|
||
→ 需要时自动回滚)。验证退出码 `1`=网关侧故障 → 自动 `POST /rollback {tag, restore_backup}`
|
||
**回滚镜像并恢复数据备份**(data/audit 一起回,故障版本可能已写穿污染),回滚后再验一遍;
|
||
`2`=验证不可用(缺 key / 拉不到目录)→ **不回滚**——盲回滚比带病观察危险,修好验证入口重跑。
|
||
验证内容全部**目录驱动**(从 `/api/v1/me` 拉 slot×模型 / apix 条目挨个真调,不写死),
|
||
上游/厂商侧问题(欠费、502、WAF)如实汇总告警但不染红发版。详见 `tests/README.md`。
|
||
⚠️ 自动回滚依赖控制面 ≥1.0.2(`restore_backup` + rollback 自动拉镜像),release 开头有版本闸门。
|
||
|
||
| tag | 内容 |
|
||
| --- | --- |
|
||
| `ipass-1.0.0` | 首个完整版(上游多模型 / 模型发现 / 用量统计)。⚠️ 该 tag 在 `base_url` 修复后被**同 tag 覆盖**过(digest 由 `046a9dd7…` 变为 `226321bec…`),是历史遗留;此后不再覆盖。 |
|
||
| `ipass-1.0.1` | `base_url` 端口跟随调用方 `Host`(修复 .11 上 88 端口回显地址打不通)。digest `226321bec…`,与 `ipass-1.0.0` 覆盖后的内容相同。**tag 只增不改的约定从这一版生效。** |
|
||
| `ipass-1.0.2` | 写共享内存失败必须出声(三处 `sync_shm` 不再丢弃返回值,`reload_shm` 增加「期望条数 vs 实际装载」核对)——热路径无回源兜底,静默失败等于「刚配好却 404/401 且日志无痕」。 |
|
||
| `ipass-1.0.3` | 管理台「新建 / 更新 LLM 上游」表单的上游地址、密钥输入框独占整行(原被网格压到 ~170px,地址与密钥看不全)。 |
|
||
| `ipass-1.0.4` | **LLM 出站请求头改为「默认不放行」**(`proxy_pass_request_headers off` + 凭据头抹空 + 显式放行清单),堵住网关自己的 Key 经 `x-api-key` 泄漏给上游厂商。详见 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md`。 |
|
||
| `ipass-1.0.5` | **上游健康自动标记 + 管理台连通性测试 + 可复制 API 地址**。健康数据来自真实流量(log 阶段写 `uh:<slot>`,4xx=活、5xx/502/504=失效、下次成功自愈);「测试」按钮内部重定向复用 LLM 转发链路真探测;上游列表 OpenAI/Anthropic 复制按钮与 `anthropic_base_url`;统计挪进独立「数据总览」tab。 |
|
||
| `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/<slug>` 把外部 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`。 |
|
||
| `ipass-1.0.14` | **LLM 上游多账号路由 + 额度耗尽自动切换 + 粘性绑定**(见 §15「上游配置」与 `docs/llm/MULTI_ACCOUNT_ROUTING.md`):一个 slot 挂多个账号 Key,下游 Key 与上游账号粘性绑定(`ukb:`,仅共享内存、重启重绑);无绑定时按 `FNV-1a(下游 Key) % n` 分散(均匀铺开避开厂商单账号并发上限,同时落点固定保住 prompt/token 缓存);厂商判额度耗尽(HTTP 状态码 或 响应体 marker,流式也扫)即冷却该账号并切下一个,冷却边界**天锚定**(对齐 MiniMax「5h 窗口、末段 4h 随天重置」)。**新增账号级负载统计**(`uda:`/`uex:` 日桶,复用内核 `usage` 原语、零新依赖):管理台「上游」页密钥列展示各 Key 今日请求/token/耗尽次数 + 负载比例条 + 14 天迷你趋势。回归 279 条全绿(网关 102 + LLM 177)。 |
|
||
| `ipass-1.0.15` | **auth 规范化(`normalize_auth`)+ 排障子命令**。表单 placeholder 写的是 `sk-...`,用户照着填了**裸 key**(无 `Bearer `),转发时原样发出 → 上游回 1004。`plugin-llm` 新增 `normalize_auth`:trim 后无空白即自动补 `Bearer `,**写入(`upsert`)+ 读出(`read_upa`)双处应用**——前者让存量在下次保存时归正,后者让线上坏数据立即可用、无需用户重填。`deploy/agent.sh` 新增 `upstreams`(逐账号掩码/冷却/今日负载,掩码为空显式标红)与 `upstream-test <slot>`(调测试接口并打厂商真实响应,不靠管理台按钮)两个排障子命令。回归 281 条全绿(网关 102 + LLM 179)。 |
|
||
| `ipass-1.0.16` | **`/api/v1/me` 聚合能力目录**(upstreams + apix 一处拿全)。commit `479024c`,详见 `docs/plugin/ME_CAPABILITY_CATALOG.md`。 |
|
||
| `ipass-1.0.17` | **备份路径迁 `~/ipass/backup/` + 删 `rollback-*` 本地标签**。commit `6b8d694`。 |
|
||
| `ipass-1.0.18` | **运行期统计落盘 / 重启恢复 + 审计口径收口**。worker 退出钩子 + 周期落盘(默认 60s)双保险 → `data/llm-stats.json`;恢复 put-if-absent 跨 worker 幂等。**新增统计前缀必须同步 `stats_persist::PREFIXES`**(漏一处 → 该列发版后从 0 起算)。审计改只追加 `meta.jsonl`(不再复制完整 body),`excerpt` = 前 100 字节,`body_hash` = 全文 SHA256 前 16 hex;`AUDIT_MAX_BYTES` 10GB→1GB。回归 292 条全绿(网关 102 + LLM 190)。commit `16cf68d`。 |
|
||
| `ipass-1.0.19` | **「上次落盘/恢复」记录移入共享内存**(`spr:`/`spd:`)—— 1.0.18 把它放在进程内静态量上,落到哪个 worker 报哪个数,「日志里明明发生了 N 次、状态页报 0」踩过两次。commit `1bc316e`。 |
|
||
| `ipass-1.0.20` | **apix 透传模式 passthrough —— 通用内部 REST 出口**。vendor 模式假设单一供应商收口 + 网关拼体,OCR / 文生图 / TTS 这类多端点多 body 的内部服务接不进来。passthrough 走独立 `/apixp/` location(不施加 vendor 强约束,方法/请求体/Content-Type 原样透传,含 multipart),上游路径 = base + `/apixp/<slug>` 之后的 URI 尾部(含 query 由模块拼),Key 可空(内部服务免鉴权)。模型加 `mode` 字段(默认 vendor,旧数据零迁移);shm payload 4 字段 `base\nkey\nasset_id\nmode`;handler 校验「路径前缀 vs mode」一致(vendor slug 走 `/apixp/` → 404,反之亦然);探测按 mode 分流(vendor POST 预估 / passthrough GET 打上游根);鉴权仍走同一把 `sk_` + 配额 + 用量统计(slot 前缀 `api/<slug>`,passthrough 同样计)。真源 `docs/apix/PASSTHROUGH_MODE.md`。回归 327 条全绿(网关 102 + LLM 225,§11.6 新增 35 条)。commit `4533db8`,digest `ff34f7ef…`。 |
|
||
| `ipass-1.0.21` | **fix(apix): passthrough 新建可空 Key**。1.0.20 现场踩坑:`upsert` 统一要求「基址与密钥」,但 passthrough 设计是 Key 可空(handler 已放行),管理台提交 passthrough + 空 Key 直接 400。修:vendor 必须 base + key 都填;passthrough 仅 base 必填,key 可空。补 2 条断言防回归。commit `d05ebfb`,digest `f1087cf2…`。 |
|
||
| `ipass-1.0.22` | **feat(apix): `usage_hint` 字段 —— 让用户 AI 自己知道怎么调**。`/api/v1/me` 把账号能力目录下发给用户 AI 后,AI 必须能自己拼出调用语法(路径尾部 / Content-Type / 字段名 / Swagger)。`desc` 是中文给运维看的,`params` 只对 vendor 有意义,对 passthrough 是空数组——AI 拿到后不知怎么调。加 `usage_hint` 字段:管理员按 OpenAPI 风格填自由文本(截断 1KB),由 `/api/v1/me` 原样透传给用户 AI。**不进 shm**(热路径只查 base/key/asset_id/mode,进 shm 占带宽)。真源 `docs/apix/PASSTHROUGH_MODE.md` §3「`/api/v1/me` 用法」。commit `26a0f2f`,digest `8bb81353…`。 |
|
||
| `ipass-1.0.44` | **上游账号冷却改为「指数退避 + 真实请求探测」闭环**。旧口径按账号 `resets` 算天锚定重置边界,锚点算错过两次(1.0.14 / 1.0.24),造成「厂商 15:00 重置、网关锁到 18:00」——天锚定计算整体删除,`resets` 只存不路由。新口径:`uac:` = `<backoff>:<next_probe>:<hard_cap>`,到期放**一个无绑定**真实请求过去探测,2xx 即 `clear_cool` 回队、仍耗尽则退避翻倍(首轮 `ipass_probe_min`,默认 60s,30min 封顶无条件回队自愈)。`pick_account` 自此**必须保持纯决策**(四个 `$llm_*` 变量各求值一次),副作用只放 log 阶段。附带修复:探测窗口判定改**严格小于**(秒级时钟下 `>=` 会让刚标记的账号在下一请求就被当探测目标,1s 短退避时实际只等了 0.05s,冷却形同虚设)。真源 `docs/llm/MULTI_ACCOUNT_ROUTING.md`。回归 370 条全绿(网关 108 + LLM 262,新增「探测恢复闭环」剧本)。 |
|
||
|
||
---
|
||
|
||
## 13. 安全
|
||
|
||
已做的:
|
||
|
||
- **口令加盐迭代哈希**(1000 轮 SHA-256 + 每账号随机盐),不落明文、不回传哈希。
|
||
- **API Key 随机生成**(`sk_` + 24 字节密码学随机数),比较使用**常量时间**实现,避免时序侧信道。
|
||
- **管理员会话**:随机会话令牌存共享内存,Cookie 带 `HttpOnly` + `SameSite=Strict`,8 小时滑动过期,重启即失效。
|
||
- **登录限速**:同一 IP 5 分钟内失败 10 次即拒绝(429),成功登录后清零。
|
||
- **越权隔离**:普通账号无法登录管理台、无法访问管理员接口、无法删除他人域名。
|
||
- **最小暴露**:`conf/`、`www/` 以只读方式挂载进容器;默认 server 对非 `*.yourdomain.com` 的请求直接 403。
|
||
|
||
需要你注意的:
|
||
|
||
1. **三个入口均已上 TLS**(`mdm`/`lm`/`*.dm` 共用 18098 ssl + 通配符证书,见 §12.2);
|
||
TLS 在网关终结,网关到后端仍是内网 HTTP——敏感后端请自行加内网 TLS。
|
||
2. 初始管理员密码默认 `123456`,**首次登录必须修改**;生产建议通过 `ADMIN_INIT_PASSWORD` 注入后再首次启动。
|
||
3. 建议把 `mdm.mayishangshu.cn:18098` 管理入口限制在内网或加一层来源 IP 白名单,普通业务域名照常对外。
|
||
4. `data/` 里含账号哈希与全部 API Key,**不要提交进版本库、不要放进共享目录**。
|
||
|
||
---
|
||
|
||
## 14. 已知限制 / 待办
|
||
|
||
| 项 | 现状 | 建议 |
|
||
| --- | --- | --- |
|
||
| HTTPS | ✅ 已完成(2026-09-11):`mdm`/`lm`/`*.dm` 均 `18098 ssl` + `*.mayishangshu.cn` 通配符证书 | 证书续期与同步流程见 §12.2 |
|
||
| 多副本 | 状态在本地 JSON + 共享内存(**单机内**跨 worker 安全),不跨副本 | 需高可用时改 Redis/etcd |
|
||
| 手改配置文件不生效 | 共享内存是运行期真源,改 `data/*.json` 需重启 | 需要保留热改能力就加一个显式 reload 入口 |
|
||
| 上传体积 | 业务转发放开到 100MB,管理 API 限 2MB | 有更大需求改 `client_max_body_size`,**同时调大 `client_body_buffer_size`**(否则 body 被截断) |
|
||
| 审批通知 | 待审只体现在管理台的角标上 | 可接企业微信/邮件机器人推送 |
|
||
| 审计日志 | 依赖 access.log 与记录内的 `reviewed_by/reviewed_at` | 需要更细的操作审计可另开 `audit.json` |
|
||
| Linux 部署权限 | macOS 上 Docker Desktop 忽略属主;Linux 下 worker 以 `nobody` 运行 | `chown -R nobody:nobody data logs` 后再启动 |
|
||
|
||
---
|
||
|
||
## 15. LLM API 代理
|
||
|
||
把 `lm.mayishangshu.cn:88` 作为公司所有大模型的统一出口。客户端只持有一把**本网关签发的 Key**
|
||
(就是 `users.json` 里属于自己账号的那把 `sk_...`),各家厂商的真实密钥全部由网关保管——
|
||
客户端看不到,也不需要逐家去申请。
|
||
|
||
> 端口以部署为准:三个域名共用**宿主 88**(容器内 nginx 监听 18098,`-p 88:18098`),
|
||
> 所以对外一律写 `:88`。88 不是 443,**漏掉端口会打到别处**——详见「上游配置」的 `base_url`。
|
||
|
||
### 怎么用
|
||
|
||
`<slot>` 是上游名,对应 `data/llm-upstreams.json` 的 key:
|
||
|
||
```bash
|
||
# 任何 OpenAI 兼容客户端:只改 base_url 与 api_key
|
||
curl https://lm.mayishangshu.cn:88/openai/v1/chat/completions \
|
||
-H "Authorization: Bearer sk_<你的 API Key>" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
|
||
```
|
||
|
||
```bash
|
||
# Anthropic 兼容客户端(Claude Code / Claude SDK):base_url 要补 /anthropic 段
|
||
export ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn:88/minimax/anthropic
|
||
export ANTHROPIC_AUTH_TOKEN=sk_<你的 API Key> # 发 Authorization: Bearer —— 走网关用它
|
||
# SDK 会自己在后面拼 /v1/messages,实际打到 /minimax/anthropic/v1/messages
|
||
```
|
||
|
||
> ⚠️ **Anthropic 客户端最容易用错的两个变量**(Anthropic 官方语义):
|
||
>
|
||
> | 变量 | 发出的请求头 | 用在哪 |
|
||
> | --- | --- | --- |
|
||
> | `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer` | **走网关/代理**——本网关认的就是这个 |
|
||
> | `ANTHROPIC_API_KEY` | `x-api-key` | **直连 Anthropic 官方**才用 |
|
||
>
|
||
> 配成 `ANTHROPIC_API_KEY` 属于配置偏差:请求仍能过(网关两种头都认,且出站时会把它摘掉、
|
||
> 不会泄漏给上游厂商),但语义不对,别依赖这个行为。`BASE_URL` 末尾**必须带 `/anthropic`**,
|
||
> 漏掉会打到 `…/minimax/v1/messages` → 厂商侧 404。
|
||
>
|
||
> **不想猜路径就用现成的**:管理台「LLM 上游」每行 slot 旁有 **OpenAI / Anthropic 两枚
|
||
> 点击复制按钮**;或用 Key 调 `GET /api/v1/upstreams` / `GET /api/v1/models`,
|
||
> 响应里 `base_url`(OpenAI 用)与 `anthropic_base_url`(Anthropic 用)都是拼好的完整地址。
|
||
|
||
- **同一把 Key 通吃**:域名接口用 `X-API-Key`,LLM 代理用 `Authorization: Bearer` 或 `x-api-key`,
|
||
都是同一把;改密码不影响 Key,重置 Key 则两处同时失效。
|
||
- **换厂商不改客户端**:把 base_url 里的 `openai` 换成 `deepseek` 即可(需管理员给你开白名单)。
|
||
- **流式(SSE)原生支持**:`"stream": true` 逐块透传,网关不做缓冲。
|
||
- 支持 `?query` 参数、多模态大 body(上限 100MB)、上游 `base` 带路径的网关型上游。
|
||
|
||
```bash
|
||
# 发现可用模型(用同一把 Key,网关本地应答)
|
||
curl -s https://lm.mayishangshu.cn:88/v1/models \
|
||
-H "Authorization: Bearer sk_<你的 API Key>"
|
||
```
|
||
|
||
### 模型发现
|
||
|
||
**一家上游通常挂很多模型**,网关把「谁提供哪些模型」登记在上游配置的 `models` 字段里
|
||
(见「上游配置」)。两处可查,**数据同源、形状不同**:
|
||
|
||
| 入口 | 响应形状 | 给谁用 |
|
||
| --- | --- | --- |
|
||
| `GET https://lm.mayishangshu.cn:88/v1/models` | OpenAI 规范 `{object:"list",data:[{id,object,owned_by}]}` | OpenAI SDK / 各类现成客户端 |
|
||
| `GET <管理端口>/api/v1/models` | 网关统一体 `{code,msg,data:{items,upstreams}}` | 自研客户端、脚本(带 `base_url`,可直接拼请求) |
|
||
|
||
- 两者都**按你的白名单过滤**:只列出你有权限使用的上游所登记的模型
|
||
- `id` 即模型名(如 `deepseek-chat`),`owned_by` 是该模型所属的**上游 slot**
|
||
- 网关**本地应答、不转发上游**(各家上游的 `/v1/models` 实现不一、有的还要另配鉴权),
|
||
因此结果只反映**配置里登记了什么**
|
||
- 模型清单只管「发现」,**不影响转发**:网关仍不解析请求体、不按 `model` 字段路由,
|
||
请求真正去哪儿由 URL 第一段 slot 决定
|
||
|
||
### 用量统计
|
||
|
||
两个视角,**统计的是同一份共享内存计数**:
|
||
|
||
| 视角 | 入口 | 内容 |
|
||
| --- | --- | --- |
|
||
| 管理员 | `GET /api/admin/usage`(管理台「用量统计」页) | 全局合计 + 按账号 + 按上游,每项含今日 / 累计 / 最近调用时间 / token 合计 |
|
||
| 管理员 | `GET /api/admin/trend?days=N`(管理台「用量统计」页趋势图) | 按自然日分桶:全局 / 按账号 / 按 API 组,每种含请求数与入/出 token |
|
||
| 账号本人 | `GET /api/v1/usage` | 自己的今日 / 累计 / 最近调用 + 分上游明细 + 当前限流 |
|
||
| 摘要 | `GET /api/v1/me` 的 `llm_usage` | 一个请求拿到用量摘要,便于客户端自我节流 |
|
||
|
||
```bash
|
||
curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage"
|
||
```
|
||
|
||
口径(**容易和限流混淆,务必看清**):
|
||
|
||
- **只统计「真正转发出去」的请求**:鉴权、白名单、限流全部通过之后才 +1。
|
||
被拒的请求(401 / 403 / 404 / 429)**不计入用量**——它们没产生厂商费用
|
||
- 与配额计数(`st:`,`llm_daily` 判限用)**刻意分开**:配额宁可多算(防滥用),用量要准(对账)
|
||
- 同样是**请求级**而非 token 级(原因见「限流与配额」)
|
||
- 计数只存共享内存(`ust:` 每账号、`ums:` 每账号×上游),**重启归零**;
|
||
与域名 / Key 等配置不同,用量是运行期指标,不落盘
|
||
- 管理台账号列表另有一列 `llm_today` 直接显示今日用量
|
||
|
||
#### 上游账号级负载(多账号路由的「问题发现」视角)
|
||
|
||
一个上游挂多把 Key 时,管理台「上游」页的**密钥 / 负载**列逐账号展示:
|
||
|
||
| 展示项 | 含义 | 数据源(共享内存键) |
|
||
| --- | --- | --- |
|
||
| 今日 N 请求 · 入 X / 出 Y tok | 该 Key 今日真实转发量与 token 消耗 | `uda:<slot>:<idx>:<day>` |
|
||
| 比例条 | 该 Key 占**本上游负载最大 Key** 的百分比(谁在扛、有没有偏斜) | 同上 |
|
||
| 14 天迷你趋势 | 悬停显示近 14 天合计 / 峰值 / 峰值日期 | 同上 + `trend_labels` |
|
||
| `冷却` 徽标 | 该账号当前处于额度耗尽冷却 | `uac:<slot>:<idx>` |
|
||
| `耗尽N` 徽标 | **今日**被判额度耗尽并冷却的次数 | `uex:<slot>:<idx>:<day>` |
|
||
| 上游级合计 | `N 把 Key · 今日合计 M 请求` | 账号负载求和 |
|
||
|
||
计数点在 **log 阶段**(`access` 阶段的 `pick_account` 只做决策、不记账——它会因
|
||
`$llm_target/$llm_auth/$llm_acct` 三个变量各触发一次),口径与请求级用量一致:
|
||
**只算真的转发出去的请求**。账号级序列**不参与任何转发决策**,纯展示。
|
||
设计取舍与键布局见 `docs/llm/MULTI_ACCOUNT_ROUTING.md` §七。
|
||
|
||
### 路径拼接(版本段去重)
|
||
|
||
客户端请求路径会**原样接到上游 `base` 之后**,但有一处特例容易绊到人:
|
||
|
||
| 上游 `base` | 客户端请求 | 实际转发 |
|
||
| --- | --- | --- |
|
||
| `https://api.deepseek.com` | `/v1/chat/completions` | `https://api.deepseek.com/v1/chat/completions` |
|
||
| `https://api.deepseek.com/v1` | `/chat/completions` | `https://api.deepseek.com/v1/chat/completions` |
|
||
| `https://api.deepseek.com/v1` | `/v1/chat/completions` | `https://api.deepseek.com/v1/chat/completions`(**去重**) |
|
||
|
||
即:当 `base` 的路径段(如 `/v1`)与请求路径开头重复时,**只保留一份**。
|
||
没有这一步,`base` 带 `/v1` 的上游会收到 `/v1/v1/...`,表现为上游 **404 且响应体为空**,
|
||
很难从网关侧看出来(网关自己的日志一切正常)。
|
||
|
||
> 因此上游只要是 OpenAI 兼容实现,`base` 带不带 `/v1` **都能用**——这是刻意的兼容设计。
|
||
|
||
### 权限与错误
|
||
|
||
每个账号有一份**可用上游白名单**(`allowed_models`),管理员在账号管理里指定,**留空 = 不限**。
|
||
被拒时返回的是 OpenAI 兼容错误体(`{"error":{"code":...,"message":...}}`),SDK 能正确解析:
|
||
|
||
| 状态码 | type / code | 含义 |
|
||
| --- | --- | --- |
|
||
| 400 | `invalid_request_error` | 路径缺少上游段,正确形式 `/<slot>/v1/...` |
|
||
| 401 | `invalid_api_key` | 缺 Key / Key 无效 / Key 已被重置 |
|
||
| 403 | `permission_denied` | 该账号不在这个上游的白名单里 |
|
||
| 404 | `model_not_found` | 上游不存在或已停用 |
|
||
| 429 | `rate_limit_error` / `rate_limit_exceeded` | 超过每分钟限流,SDK 会自动退避重试 |
|
||
| 429 | `insufficient_quota` | 超过每日配额,次日 0 点(本地时区)重置 |
|
||
| 502 | `upstream_unavailable` | 上游不可达 |
|
||
|
||
### 限流与配额
|
||
|
||
按 **Key(账号)** 限流,两个维度各自独立,`0` 都表示不限:
|
||
|
||
| 维度 | 字段 | 全局默认 | 窗口 |
|
||
| --- | --- | --- | --- |
|
||
| 每分钟请求数 | `llm_rpm` | 60 | 自然分钟(滚动对齐) |
|
||
| 每日请求数 | `llm_daily` | 0(不限) | 本地自然日(东八区 0 点重置) |
|
||
|
||
- 管理台「账号管理 → 限额」可直接改,**改动立即生效**(写穿共享内存,无需重启)
|
||
- 计数存在共享内存里(每账号固定一个键),重启归零;这是刻意的——配额是
|
||
「防滥用软限制」,不值得为它引入持久化复杂度
|
||
- 是**请求级**而不是 token 级:token 数在上游响应体里,而 SSE 必须关缓冲透传,
|
||
网关不缓冲就解析不到 `usage` 字段;要 token 级计费得自建 upstream,与单容器零依赖红线冲突
|
||
- 今日用量在管理台账号列表可见(`llm_today`,来自同一份共享内存计数)
|
||
- 被限流的请求**不会**转发到上游,不产生厂商费用
|
||
|
||
### HTTPS(可选)
|
||
|
||
生产配置默认只听 80。启用方式:把 `conf/tls/llm.conf.example` 复制为同目录 `llm.conf`,
|
||
换成真实证书路径,`docker compose restart`。`conf/tls/` 下的 `*.conf` 会被自动 include,
|
||
**目录为空时等于没配**,不影响启动。`compose.yml` 已映射 443 并挂载该目录。
|
||
自签证书命令与 acme.sh 泛解析签法见 `conf/tls/README.md`。
|
||
|
||
注意:TLS server 块的 location 与 80 端口的 LLM server 是**两份**(nginx 不支持同一 server
|
||
「可选 ssl」),改 location 时记得两处同步。
|
||
|
||
### 上游配置
|
||
|
||
管理员通过 `POST /api/admin/upstreams/save` / `delete` 维护,写入 `data/llm-upstreams.json`,
|
||
**改动立即生效、无需重启**。字段说明见「数据模型」。
|
||
|
||
`models` 用于**模型发现**;管理台「上游管理」有「模型」列与「编辑」按钮可直接维护,
|
||
支持一次粘贴多行(逗号 / 顿号 / 分号 / 换行都当分隔符)。
|
||
|
||
**一个上游挂多个账号**:同一个 `slot` 可配 `accounts[]`(多把上游 Key + 各自的额度重置周期),
|
||
下游 Key 与上游账号**粘性绑定**、某把耗尽自动切下一把;管理台「密钥 / 负载」列逐 Key 展示
|
||
今日请求/token/耗尽次数 + 负载比例条 + 14 天迷你趋势。字段与设计见「数据模型」小节与
|
||
`docs/llm/MULTI_ACCOUNT_ROUTING.md`。
|
||
|
||
`GET /api/v1/upstreams`(账号态)与 `GET /api/v1/models`(`upstreams` 分组)会给每个可用
|
||
上游回两个**拼好的完整地址**:`base_url`(OpenAI 客户端直接当 `base_url` 用)与
|
||
`anthropic_base_url`(Anthropic 客户端直接当 `ANTHROPIC_BASE_URL` 用),以及 `status`
|
||
健康状态——不必自己关心上游 `base` 里有没有 `/v1`、也不用猜协议段。
|
||
|
||
> ⚠️ **`base` 写到哪一层,决定 `base_url` 是否「协议中立」。** 上游 `base` 若只写到 host
|
||
> (`.11` 上 `minimax` = `https://api.minimaxi.com`),回显的 `base_url` 就是
|
||
> `https://lm.mayishangshu.cn:88/minimax`,**末尾没有协议段**:
|
||
>
|
||
> - **OpenAI 系客户端**直接用它即可(SDK 自己拼 `/v1/chat/completions`);
|
||
> - **Anthropic 系客户端必须自己补 `/anthropic`**:
|
||
> `ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn:88/minimax/anthropic`(SDK 再拼 `/v1/messages`)。
|
||
> 漏掉 `/anthropic` 会打到 `…/minimax/v1/messages` → 厂商侧 404。
|
||
>
|
||
> 这样**一条 host 粒度的记录能同时服务两套协议**。反过来,`base` 写全路径
|
||
> (如 `…/anthropic`)时回显地址自带协议段、可直接用,但该记录被钉死在这条路径下,
|
||
> 另一协议 404。取舍与实测见 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md` §七。
|
||
|
||
**端口跟随调用方**:`base_url` 里的端口取自你请求管理接口时用的 `Host` 头。
|
||
本网关用宿主 **88** 端口承载三个域名,而 88 不是 443,所以客户端拿到的地址里
|
||
**必须带 `:88`** 才能连上;如果哪天前面挂了 443 反代,用 `Host: mdm.mayishangshu.cn`
|
||
(不带端口)访问时回显的 `base_url` 也会自动不带端口。写死任何一种都会在另一种部署下
|
||
给出「看着对、打不通」的地址。
|
||
|
||
---
|
||
|
||
## 15.1 API 代理(外部 API 供应商)
|
||
|
||
把外部 API 供应商的资产挂到网关下,
|
||
与 LLM 代理**共用同一把账号 API Key、同一份限流与用量统计**——差别只在下游形态:
|
||
供应商只有一个收口 `POST /api/v1/ai/request`,资产靠**请求体里的 `asset_id`** 区分。
|
||
|
||
```text
|
||
GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签发>
|
||
→ access 阶段 ApiProxyHandler(ipass_apix 开关)
|
||
① 取 URL 第一段 → slug = search
|
||
② 查 ukey:<key> → 身份 + 配额(与 LLM 同一套)
|
||
③ 查 ax:<slug> → base + 供应商 Key + asset_id(纯内存)
|
||
④ 放行;GET 被改写成 POST:proxy_method + proxy_set_body $apix_body
|
||
$apix_body 由网关**从 query 拼**(见下);$apix_key 换上供应商 Key
|
||
→ 转发到供应商(下游 sk_ 到此为止,绝不带出去)
|
||
```
|
||
|
||
**为什么请求体必须由网关拼**:供应商只认一个收口 URL,资产全靠 body 里的 `asset_id` 区分。
|
||
如果让客户端自己带 `asset_id`,管理员就失去「只暴露免费资产」的控制力。所以
|
||
**资产选择权留在服务端**:`slug → asset_id` 由管理员在「API 代理」页配置,调用方只能决定 query 参数。
|
||
|
||
**调用方式**:`/apix/<slug>?<参数>=<值>`。参数只能走 query string——转发决策在 access 阶段,
|
||
那时请求体还读不到。网关把全部 query 参数原样塞进 `call_data`(`prompt` 提到顶层,供应商模型类资产用它当必填),
|
||
再 `proxy_method POST` + `proxy_set_body` 转成带体请求。例如 `GET /apix/search?q=nginx` 会向供应商发:
|
||
|
||
```json
|
||
{"asset_id":"searxng-search","call_data":{"q":"nginx"}}
|
||
```
|
||
|
||
**管理台「API 代理」页**(`/admin/apix.html`):
|
||
|
||
- **代理列表**:每个代理自带该供应商的 `基址 / 供应商 Key / asset_id`,由管理员在「新建 / 编辑」
|
||
弹出卡片里填写。供应商只是被代理方之一,**没有「平台级」凭据面板**。真 Key 只落在
|
||
`data/api-proxies.json`,列表只显示掩码 `ak_***`。
|
||
- 每个代理给复制调用地址 / 测试 / 编辑 / 启停 / 删除。停用立刻对调用方表现为 404
|
||
(共享内存已摘除,无回源兜底)。「测试」走该供应商的**免费**预估接口 `/api/v1/ai/estimate`,
|
||
不执行资产、不扣费,顺带把供应商余额 `current_balance_usd` 带回来。
|
||
|
||
**接口**
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `GET` | `/apix/<slug>?<参数>` | 账号态:转发到供应商对应资产 |
|
||
| `GET` | `/api/v1/apix` | 账号态:列出已启用的代理与调用地址 |
|
||
| `GET` | `/api/admin/apix` | 管理:凭据掩码 + 代理列表 |
|
||
| `POST` | `/api/admin/apix/save` | 新建 / 更新代理(`slug` / `asset_id` / `params` / `enabled`) |
|
||
| `POST` | `/api/admin/apix/delete` | 删除代理(调用方立即 404) |
|
||
| `POST` | `/api/admin/apix/test` | 连通性 / 余额探测(内部重定向到 `/_apix_probe/<slug>`,`internal` 挡外部直连) |
|
||
|
||
**硬约束**
|
||
|
||
- `apix.rs` 与 `llm.rs` 共用下游 `sk_` 鉴权与配额;`data/api-proxies.json` 含供应商真 Key,
|
||
**敏感级别等同 `users.json`**,不要复制到其他地方。
|
||
- 出站头默认不放行(`proxy_pass_request_headers off`)+ 抹空 `x-api-key`/`api-key`/`Authorization`,
|
||
再显式放行 `Host` / `X-API-Key`(=供应商 Key)/ `Content-Type`。**抹空三条是堵漏关键**,
|
||
漏 `Content-Type` 会令供应商侧解析失败。
|
||
- shm 键 `ax:<slug>`,value = `base\n供应商Key\nasset_id`。写操作必须走 `apix::sync_shm`
|
||
(停用 = 删键),否则「面板显示已保存、调用却 404」。
|
||
|
||
## 16. 变更记录
|
||
|
||
- **2026-09-14 LLM 上游多账号路由 + 账号级负载统计(`ipass-1.0.14`)**
|
||
- **多账号**:`llm-upstreams.json` 的 slot 新增 `accounts[]`(`auth` / `note` / `resets`)
|
||
与上游级 `exhaust_status` / `exhaust_markers`;顶层单 `auth` 保留兼容(`accounts` 为空时合成单账号)。
|
||
- **路由**(access 阶段 `pick_account`):粘性绑定 `ukb:<downstream_key>` 优先 → 无绑定时
|
||
`FNV-1a(下游 Key) % 可用数` 冷分散 → 绑定账号冷却则跳过重新分散 → 全冷却选最早恢复。
|
||
分散解决厂商「单账号 agent 并发上限」,绑定保证同一用户落点固定以命中 prompt/token 缓存。
|
||
- **耗尽检测**(log 阶段,双保险):`$upstream_status` 命中 `exhaust_status`,或
|
||
body filter 流式扫到 `exhaust_markers` → `$llm_acct` 定位本次账号 → 写冷却 `uac:`。
|
||
- **天锚定冷却**:边界 = `day0 + ceil(已过/窗口)×窗口` 且封顶次日 0 点
|
||
(MiniMax 5h 窗口、24=5×4+4 → 20:00–24:00 末段只有 4h、随天重置;`RESET_DAY_OFFSET_SEC` 默认北京时间)。
|
||
- **账号级负载统计**(新):`uda:<slot>:<idx>:<day>`(请求/token)与 `uex:` (耗尽次数)日桶,
|
||
复用内核 `usage::bump_day`,**无数据库、无新进程**;计数点只在 log 阶段一次
|
||
(`pick_account` 会被三个变量各触发一次,不能在里面记账)。管理台「上游」页密钥列展示
|
||
每把 Key 今日负载 + 比例条 + 14 天迷你趋势 + 冷却/耗尽徽标;`view()` 附 `trend_labels`。
|
||
- 回归 **279 条全绿**(网关 102 + LLM 177,新增 6 条多账号/负载断言);前端以真实
|
||
`admin.css` + `upstreams.js` 渲染路径做无头浏览器断言(比例条成比例、条块数、悬停日期、无溢出)。
|
||
- 专章:`docs/llm/MULTI_ACCOUNT_ROUTING.md`(数据模型 / 路由 / 冷却数学 / shm 布局 / 负载统计)。
|
||
|
||
- **2026-09-14(续17)「上次落盘」记录移入共享内存(`ipass-1.0.19`,已发版)**
|
||
- **起因**:1.0.18 首次线上验证时发现 —— `error.log` 里明明有 10 次 `[stats] 落盘`
|
||
(来自 `6#0` / `18#0` / `23#0` 多个 worker),`/api/admin/stats/persist` 却报
|
||
「上次落盘:(本进程还没落过)」。
|
||
- **根因**:`LAST_DUMP_AT` 是**每 worker 的进程内静态量**。`maybe_dump()` 挂在记账路径上,
|
||
记账每 worker 各算各的 → 「上次落盘时刻」也就每 worker 一份;接口落到没落过盘的
|
||
worker 就报 0。**与 1.0.18 已修过的 `spr:last`(上次恢复)是同一类错误**。
|
||
- **修法**:时刻发布到共享内存 `spd:last`(`publish_dump` 取 `max`;读-改-写无原子性保证、
|
||
理论差 ≤1 秒,对状态展示与分钟级节流无影响)。一次解决两件事 —— **上报一致**
|
||
(所有 worker 报同一份)+ **节流收敛**(`maybe_dump` 新增慢路径查它,把「8 个 worker
|
||
各写一遍同一个文件」收敛成「全局每间隔一次」)。快路径仍是原子比较,热路径代价不变。
|
||
- 回归 **299 条全绿**(网关 102 + LLM 197):新增「状态页报告的上次落盘时刻非空」断言 ——
|
||
测试套件开 **2 个 worker**,正是能暴露该分歧的拓扑。
|
||
- 已知问题(另案):审计容量巡检的 `LAST_PURGE_AT` / `PURGING` 同样是每 worker 静态量,
|
||
启动时每个 worker 都会 `purge(true)`,理论上可能多删最旧审计目录;影响面仅「留档比上限更少」,
|
||
修它需要跨 worker 互斥原语。见 `docs/llm/STATS_PERSISTENCE.md` §十。
|
||
- 发版:commit `1bc316e` → `ipass-1.0.19`
|
||
(digest `sha256:8f8a4444…e5ba`,job `20260914-201252-3d17`,7 步全过)。
|
||
**线上复验**:`bash deploy/agent.sh stats-persist` 由「(本进程还没落过)」变为真实时刻,
|
||
连查 5 次均一致;`stats-dump` 后时刻更新且任意 worker 立刻可见(读写两向跨 worker 一致)。
|
||
本次 1.0.18→1.0.19 也是一次**真实发版验证**:重启后 `restored_keys = 14/14`,
|
||
发起版前的统计快照完成恢复,**没有清零**。
|
||
- ⚠️ 两个发版副发现(既有问题,未修):
|
||
① **宿主上的控制面 `ipass-agent.py` 仍是旧版** —— job 日志里还在走「备份到 `~/ipass-data-backup-*.tar.gz`」
|
||
与「旧镜像留 rollback 标签」,而这两步 1.0.17 已改掉(控制面跑在宿主、不在镜像里,需单独部署)。
|
||
② **容器 TZ = UTC**,状态页/审计的时间显示比北京慢 8 小时,且 `util::day_id`(`localtime_r`)
|
||
让趋势日桶按 **UTC 日界**(北京 08:00 换日)—— 而冷却窗口用 `RESET_DAY_OFFSET_SEC=28800`
|
||
按北京日。两处口径不一致。要改必须**同时**处理:设 `TZ=Asia/Shanghai` 就必须把
|
||
`RESET_DAY_OFFSET_SEC` 归 0,否则双重偏移(改一处必改另一处)。
|
||
|
||
- **2026-09-14(续16)统计落盘/恢复 + 审计口径收口(`ipass-1.0.18`,已发版)**
|
||
- **起因**:发版后管理台「用量」与「趋势」从 0 重新长起来。根因是这两类数据
|
||
(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`/`uda:`/`uex:`/`uh:`)**只活在共享内存**,
|
||
进程退出即消失;而上游/账号/域名/用户都有 `data/*.json` 所以不丢 —— 这个反差是定位关键。
|
||
- **方案(不引入数据库)**:一个 JSON 快照 `data/llm-stats.json`(与 `users.json` 同级,
|
||
落在宿主卷上)。**两个落盘点互补**:worker 退出钩子(`gateway::exit_process`,
|
||
覆盖发版 / `docker stop` / `nginx -s quit`,**零丢失**;镜像已声明 `STOPSIGNAL SIGQUIT`)
|
||
+ 记账后按间隔节流落盘(默认 60 秒,覆盖 `SIGKILL`/OOM/断电)。
|
||
启动时 `init_process` 恢复,**put-if-absent** → 多 worker 天然幂等、绝不把计数恢复成 N 倍,
|
||
也不会覆盖恢复期间新产生的数据;过期键两侧一致地跳过(90 天日桶不因重启续命)。
|
||
- **刻意不持久化**:配置类 `up:`/`upa:`/`upe:`/`ax:`/`ukey:`/`sub:`(各有数据文件,
|
||
存两份会出现两个真源互相覆盖)、`ukb:`(粘性,设计上重启即重绑)、内核 `st:`/`rl:`/`fail:`/`sess:`
|
||
(**重启清零是有意的**,多送一点额度好过把用户锁死)。⚠️ **新增统计前缀必须同步白名单**,否则该维度发版即清零且**不报错**。
|
||
- **接口/配置**:`GET /api/admin/stats/persist`(文件状态 + 内存现状 + 上次恢复结果)、
|
||
`POST /api/admin/stats/dump`(强制落一次);指令 `ipass_stats_persist <秒>`(0=只留退出钩子),
|
||
生产 conf **刻意不写**(用默认 60,避免旧镜像 unknown directive 起不来)。
|
||
- **顺带修的真 bug:审计 `excerpt` 双重编码**。1.0.18 首版把手工转义(含两侧引号)的结果
|
||
塞进 `json!()` 被二次转义,落盘成 `"excerpt":"\"{\\\"model\\\"…"`,解码后多一层引号,
|
||
任何按前缀匹配的消费方都解析不到 → 改为只做 UTF-8 解码、转义交给序列化器。
|
||
另确认 `body_hash` 必须是**全文** SHA256(只哈希前 100 字节会因所有请求开头相同而**全量碰撞**)。
|
||
- **「上次恢复」计数不再放进程内静态量**:`init_process` 每 worker 跑一次、只有第一个 worker 真在写键,
|
||
否则接口落到哪个 worker 就报哪个数(运维看到随机值)→ 发布到 shm `spr:last`
|
||
(`restored==0` 不写、已有则**累加** + `max(total)`,覆盖 worker 间恢复重叠)。
|
||
- 回归 **299 条全绿**(网关 102 + LLM 197;【15】段 14 条:间隔压 1 秒 → 快照产出与白名单 →
|
||
状态页上次落盘时刻非空 → `nginx -s quit` → 重启后恢复键数 > 0 且 == 快照键数、
|
||
alice 累计用量不变、再打一笔为 **+1** 而非从 0 重来、趋势日桶仍在、`uda:` 账号负载仍可读)。
|
||
- 测试踩坑(**已写进 `CLAUDE.md`**):本机 `safe-delete` 钩子在「同一 turn 累计删除 > 50 个文件」后
|
||
会**静默拦掉**后续所有删除(`rm -rf` 与 python `rmtree` 同样被拦),导致清不掉上一轮的
|
||
`llm-stats.json` → 被 `restore()` 灌进本轮(carol 用量 2 变 6、上游健康 `unknown` 变 `ok`),
|
||
**看起来像新功能有 bug,实为测试间状态泄漏**。修法:复位用 `mv`(rename 不算删除);
|
||
审计目录残留则改为断言**本轮增量 = 0**,对历史残留免疫。
|
||
- 新文档:`docs/llm/STATS_PERSISTENCE.md`(含 runbook)、`docs/llm/AUDIT_LOG.md`
|
||
(两者此前被代码注释与 `Dockerfile` 引用但文件并不存在)。
|
||
|
||
- **2026-09-14(续15.5)控制面备份路径 + 审计目录权限 + 去掉本地 rollback 标签(`ipass-1.0.17`,commit `6b8d694`)**
|
||
- **备份路径**:`~/ipass-data-backup-<时间>.tar.gz` → `~/ipass/backup/ipass-data-<时间>.tar.gz`
|
||
(`ls ~` 不再被一堆备份文件名刷屏)。
|
||
- **审计目录权限**:宿主侧首建 `audit/` 后显式 `chmod 777`。agent 以 root 跑,`os.makedirs`
|
||
建的目录属主是 root,而容器内 worker 是 `nobody` → 写不动,日志刷
|
||
`[audit] 建日期目录失败 Permission denied`、**审计整个废掉**(实测踩过)。
|
||
用 777 而非按 uid chown:宿主 uid 与容器内 `nobody(65534)` 不一定一致,
|
||
且 audit 是 append-only 元数据、无防篡改语义。
|
||
- **去掉「旧镜像在本地打 rollback tag」**:镜像动辄 100 MB+,本地磁盘越积越多;
|
||
阿里云私仓永远保留所有 tag,回滚 `docker pull` 即可。更新从 7 步变 6 步,
|
||
`op_rollback` 不再自动选本地 rollback-tag,**必须显式传 tag**(否则报错指引去阿里云拉)。
|
||
- ⚠️ 控制面 `deploy/ipass-agent.py` **跑在宿主、不在镜像里**,改动需单独部署到 .11 ——
|
||
否则线上仍是旧逻辑(1.0.19 发版的 job 日志里就是这么暴露的,见下一条)。
|
||
|
||
- **2026-09-14(续15.4)`/api/v1/me` = 能力目录扩展点(`ipass-1.0.16`,commit `dfbfe5c`)**
|
||
- **拍板**:给同事/文档/SDK 展示能力(域名 / LLM 上游 / API 代理)时**往 `CoreExt::decorate_me`
|
||
里塞,不要另开 `/api/v1/catalog` 这类聚合端点**(不破坏既有 3 个 v1 端点与老客户端脚本;
|
||
一把 key 一个请求拿全身份 + 域名 + 上游 + API 代理 + 用量 + 策略)。
|
||
- `decorate_me` 签名改为 `(&User, port, &mut Value)`:传 `&User` 让装饰**零额外 shm 查询**
|
||
就完成权限收敛(`upstreams` 按 `allowed_models` 过滤);`port` 从 Host 头取(**不写死**,
|
||
88 要带端口、443 反代不能带)。
|
||
- 仅文档同步,不动代码:`CLAUDE.md`(核心机制补第 6 条)+ `docs/plugin/PLUGIN_ARCHITECTURE.md`
|
||
(§2.3 子段、§6 纪律第 7 条、§7 已拍板)。
|
||
|
||
- **2026-09-14(续15)auth 规范化 + 排障子命令(`ipass-1.0.15`)**
|
||
- **根因**:表单 placeholder 写 `sk-...`,用户照着填了**裸 key**(无 `Bearer `),
|
||
转发时原样发 → 上游回 1004。`agent.sh upstreams` 一打就看出来:deepseek 掩码是
|
||
`Bearer s...d425`(正常),minimax 掩码是 `sk-cp-...`(**无 `Bearer `**),
|
||
完美的对照组。
|
||
- **`normalize_auth` 兜底**:`plugin-llm` 新增,规则「trim 后含空白 → 已完整;
|
||
否则补 `Bearer `」。**两处应用**——`upsert` 写入时归正(下次保存自愈)、
|
||
`read_upa` 读出时归正(**让线上坏数据立即可用,无需用户重填**)。
|
||
兼容 Basic / 自定义 scheme / 前后空格 / 内部含空格的特殊情况(详见 §15 与
|
||
`docs/llm/MULTI_ACCOUNT_ROUTING.md` §10)。
|
||
- **`agent.sh` 加两个排障子命令**:`upstreams` 逐账号打掩码/冷却/今日负载
|
||
(**掩码为空显式标 `**空**`**——这是发现「只填了裸 key」类问题的关键指示器,
|
||
旧镜像的回显脱敏后看不出问题);`upstream-test <slot>` 调测试接口并打印
|
||
厂商真实响应(不靠管理台按钮 OCR 截图)。
|
||
- 回归 **281 条全绿**(网关 102 + LLM 179,新增 2 条 normalize 断言:裸 key 200 +
|
||
靶机实收 `Bearer sk-NORM-NO-SCHEME`)。
|
||
- 教训:**placeholder 写「前缀而不是字面值」会诱导用户漏填必要部分**——正确写法是
|
||
`Bearer sk-…` + 表单说明「只填裸 key 也会自动补 Bearer」(已改)。
|
||
上游回 1004 / "Please carry the API secret key" 之类的**厂商原话**比"401"这种
|
||
通用状态码更能锁定根因——管理台测试按钮旧版本不回 body,是这个 bug 没被立刻发现
|
||
的次因。
|
||
|
||
- **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/<slug>?<参数>` → 供应商 `POST /api/v1/ai/request`,
|
||
网关**从 query 拼体**(`asset_id` 由服务端决定,调用方只能选参数),`sk_` 下行 Key 换成供应商 Key 后转发。
|
||
- `data/api-proxies.json`(含供应商真 Key,等同 `users.json` 敏感度):`base` + `key` + `items{slug→asset_id/params/enabled}`;
|
||
shm 写穿 `ax:`,停用 = 摘键。
|
||
- 6 个 nginx 变量(`$apix_target/$apix_host/$apix_key/$apix_body/$apix_probe_target/$apix_probe_body`),
|
||
GET 经 `proxy_method POST` + `proxy_set_body` 改写成带体请求;探测走 `/_apix_probe/<slug>`(`internal`)。
|
||
- 管理台 `apix.html` + `assets/apix.js`:每条代理自带供应商凭据、增删启停、复制地址、免费预估测试(弹出卡片填写)。
|
||
- 计费天然并入既有体系:用量按 `api/<slug>` 归组(与 LLM 上游同片键空间),趋势 / 用量页直接出现。
|
||
|
||
- **2026-09-13(续6)管理台图表(用量/token/趋势/按人/按 API 组)+ 单页拆分多页(`ipass-1.0.8`)**
|
||
- **趋势数据源(日桶)**:`ust:`/`utt:` 只有「今日 + 累计」两个数,**画不出历史曲线**(今日跨天归零、
|
||
累计不区分日期)。新增一组**键名带日窗 id** 的桶 `ud:`(全局)/ `udu:<user>:<day>` /
|
||
`uds:<slot>:<day>`,value = `请求数:入token:出token`,TTL 90 天由共享内存自然淘汰;
|
||
读取是**按键精确取**(`get_live`),不做前缀扫描,键数增长不拖慢任何热路径。
|
||
`stats::record`(请求)/ `stats::add_tokens`(token)各写一次同一批键、字段互补。
|
||
- 新增 `GET /api/admin/trend?days=N`(默认 14、上限 90):返回 `{days, labels, total, users, slots}`,
|
||
每条含 `requests`/`in`/`out` 三条等长数组——**图表直接能吃**,前端不做二次聚合。
|
||
按账号/按上游维度要先有名册(键里带日窗 id 扫不出来),由接口把 `users`/`upstreams` 名字传进去;
|
||
全 0 的序列标 `empty: true`,前端不画,避免一堆贴轴死线把图例挤爆。
|
||
- **管理台拆成多页**(原 `www/admin.html` 1100+ 行单文件):`login.html` + `overview` / `review` /
|
||
`domains` / `users` / `upstreams` / `usage` 六个页面 + `assets/`(`admin.css` + `core.js` +
|
||
`chart.js` + 各页 JS)。每页 `<base href="/admin/">`,于是挂在 `/admin` 还是 `/admin/x.html`
|
||
都用同一套相对路径;nginx 侧 `location = /admin` 仍进总览(保持既有入口与 e2e 断言),
|
||
`location /admin/` alias 到 `www/`。
|
||
- **图表自己画、不引三方库**:管理台是容器里的一把静态文件,引 CDN 等于把可用性押在公网可达性上
|
||
(内网部署直接白屏),引本地副本又要把几百 KB 第三方代码塞进镜像。`assets/chart.js` 不到 200 行,
|
||
折线/面积用 SVG、条形用 HTML+CSS(文字对齐交给浏览器比 SVG `text` 稳)。
|
||
- **展示面**:总览 = 卡片(含今日/累计 token)+ 请求数趋势 + token 趋势 + 按账号/按 API 组 Top 8;
|
||
用量页 = 区间(7/14/30/90 天)+ 全局/按账号/按 API 组三种趋势视角 + 指标切换(请求数 / 入 token /
|
||
出 token / token 合计)+ 两张明细表(新增入/出 token 列)。
|
||
- 回归扩至 **227 条断言**(网关 102 + LLM 125);`bash deploy/agent.sh verify` 新增
|
||
「趋势接口返回 7 天序列」作为「镜像真的换新」的证据。
|
||
|
||
- **2026-09-12(续5)LLM token 计量 + 对话审计日志(`ipass-1.0.7`)**
|
||
- **关键发现**:`ngx_http_top_body_filter` 是 extern 全局符号(`ngx_http.c:74`),动态模块可直接
|
||
FFI 引用注册 body filter —— 推翻"必须写额外 C 模块"的调研结论,token 计量收敛进现有单 .so。
|
||
- **token 计量**(`llm_usage.rs`):body filter 透传 SSE 的同时旁路累积尾部 chunk,`last_buf` 时
|
||
解析 `usage`(OpenAI `stream_options.include_usage` 尾块 / Anthropic `message_delta`),
|
||
log 阶段经 `stats::add_tokens` 写 `utt:`/`utms:` 键;用量接口(admin/自查)增加 tokens 维度。
|
||
- **对话审计**(`llm_audit.rs`):log 阶段把请求体临时文件复制进 `audit/`(data 兄弟目录)+
|
||
`meta.jsonl`(user/slot/status/token);**10 GiB 容量阈值**触发式清理,按日期目录从最旧删起。
|
||
- **踩坑**:SSE 三件套里的 `proxy_request_buffering off` 管的是**请求体**方向,与 SSE 无关,
|
||
且与 `client_body_in_file_only` 互斥(nginx `ngx_http_request_body.c:1334` 直接短路不落盘)
|
||
—— LLM location 删掉它后审计才恢复,SSE 流式不受影响(由 `proxy_buffering off` 保障)。
|
||
- **发版顺序**:控制面挂载逻辑在宿主 `ipass-agent.py` 里 → **先在 .11 跑自更新脚本
|
||
(§12.5 `update-agent-face.sh`)再 `agent.sh update ipass-1.0.7`**,否则新容器缺审计挂载。
|
||
- 测试 207 全绿(LLM 117 + 网关 90;靶机 usage 块用 `"usage_probe"` 标记门控不破坏 CHUNKS=3 契约)。
|
||
- 落地:`ipass-1.0.7`(digest `5cd68ec4…`,commit `401f9be`)。
|
||
- **2026-09-12(续4)管理台布局自适应 + 控制面收敛到 `deploy/agent.sh`(`ipass-1.0.6`)**
|
||
- **布局自适应**:`.wrap` 去掉 `max-width:1180px` 居中锁与 `margin:0 auto`——大屏上原版面只占
|
||
中间一小块、右侧大片留白且表格被压窄。改为铺满视口;配套给 `.grid-form` 限宽 `1100px`,
|
||
否则面板变宽后 `auto-fit` 的 `minmax(160px,1fr)` 会把字段摊成十几列、表单被拉散。
|
||
1920 视口实测:面板 **1872px** / 表格 **1830px**(改造前约 1132px),表单 1100px。
|
||
- **控制面不再手敲 curl**:安全策略里「可疑命令即使已加 `allow` 白名单仍需人工批准」会命中
|
||
含 `Authorization: Bearer …` / `. ./.env` 的命令 → **每次都弹「凭证授权」**,拒绝时还**静默无输出**
|
||
(实测一次 `/update` 因此根本没发出去,差点误判成服务故障)。新增 `deploy/agent.sh`:
|
||
凭据只从 `.env` 读,对外全是无凭据子命令(`status` / `update` / `wait` / `verify` / `release` /
|
||
`rollback` / `data` / `logs`),只需放行 `Bash(bash deploy/agent.sh:*)`。
|
||
- **新增正式环境验收 `agent.sh verify`**:登录线上管理台 → 核对页面新标记 → 读
|
||
`GET /api/admin/domains` 确认 `subdomain_rule`。**只看容器起来是不够的**,这条能证「镜像真的换新 + 新代码在跑」。
|
||
- 落地:`ipass-1.0.6`(digest `96c0e952…`,commit `12f20dd`)已更新到 .11,7/7 步全过,
|
||
回滚点 `ipass-1.0.5`;`agent.sh verify` 复验通过(页面 4 个标记 + `subdomain_rule` 全中)。
|
||
- 踩坑:`agent.sh` 首跑报 `LIVE_PORT…: unbound variable` —— **变量后紧跟中文标点会被并进变量名**
|
||
(`$LIVE_PORT(` → 变量名 `LIVE_PORT(`),中文项目高频;改成 `${LIVE_PORT}` 并用脚本全量扫过一遍。
|
||
|
||
- **2026-09-12(续3)子域名规则固化(`i` + 8 位随机数 + `dm`)+ 点击复制 + API 同规则**
|
||
- 管理台「新建域名(直接放行)」的子域名改为**三段拼装**:固定 `i` + 8 位随机数字输入框(带「换一个」)+ 固定 `dm`。
|
||
随机源用**拒绝采样**(只接受 `< 250` 的字节)保证 0–9 等概率;`getrandom` 不可用时退化为 xorshift、
|
||
**绝不 panic**(`panic = "abort"` 会打死 worker,见 `rust/src/util.rs::rand_digits`)。
|
||
- **规则真源收敛到 `rust/src/config.rs`**(`ENTERPRISE_ZONE` / `SUBDOMAIN_PREFIX` / `SUBDOMAIN_SUFFIX` /
|
||
`SUBDOMAIN_RAND_DIGITS` / `SUBDOMAIN_GEN_ATTEMPTS`),由 `GET /api/admin/domains` 的 `subdomain_rule`
|
||
下发给面板 —— 改后端常量面板自动跟随,避免前后端各写一份而漂移。**`dm` 后缀是硬约束**:
|
||
企业域名 server 的匹配正则捕获组必须**以 `dm` 结尾**,否则域名建出来也匹配不上转发 server(见 §4)。
|
||
- **API 侧同规则**:`POST /api/admin/domains/create` 的 `subdomain` **缺省或空串即自动生成**同形态子域名,
|
||
撞车自动换号重试(最多 5 次);手填撞车直接报错。管理台提交的是拼好的值,两条路径共用 `domains::create_by_admin`。
|
||
- 域名列表里**点完整域名即复制**,且**带端口**——`location.port` 跟随当前访问方式(用 `:88` 打开面板就复制成
|
||
`i48291376dm.mayishangshu.cn:88`);`GET /api/admin/domains` 的 `view()` 增加 `host` 字段供面板渲染。
|
||
- 回归扩至 **201 条**(网关 **90** + LLM **111**),`bash tests/run.sh all` 全绿。网关新增段「【10】管理台建域名
|
||
(自动子域名 i+8位+dm)」13 条:规则下发(zone/前缀后缀拼 `idm`/digits=8)、无 `subdomain` 自动生成 200 +
|
||
形态 `^i[0-9]{8}dm$` + `host` 形态、空串同样自动、两次随机值不同、列表含刚建域名、手填合规 200、重复手填 400。
|
||
另用真实 Chromium 逐项实测:三段同行(非堆叠)、「换一个」生效、非数字过滤(`a1b2c3d4e5f6` → `1234`)、
|
||
点击复制 toast 内容正确。
|
||
|
||
- **2026-09-12(续2)上游健康自动标记 + 连通性测试 + 复制地址(`ipass-1.0.5`)**
|
||
- 健康标记在 log 阶段由**真实流量自己当探针**(`uh:<slot>`,无需常驻探测进程);
|
||
状态码从 `$upstream_status` 变量读(`r->upstream` 在上游 finalize 时已置空)。
|
||
- 「测试」按钮经 `ngx_http_internal_redirect` 复用 LLM 转发链路;**URI 必须拷进请求池**
|
||
(internal_redirect 只浅拷贝 ngx_str_t,栈上 String 返回即悬垂——实测踩坑)。
|
||
- 客户端防错指引进 §15(`ANTHROPIC_AUTH_TOKEN` vs `ANTHROPIC_API_KEY`、`/anthropic` 段)。
|
||
- **2026-09-12(续)LLM 出站头「默认不放行」+ 统一注册(`ipass-1.0.4`)**
|
||
- **修复凭据泄漏(安全)**:LLM location 此前只覆写 `Authorization`,客户端放在 `x-api-key`
|
||
里的**网关自己的 Key** 会被原样送给上游厂商 —— 厂商拿到它可反调本网关挂的**全部**上游。
|
||
MiniMax 两处都认,把缺陷掩盖成了 200。改为 `proxy_pass_request_headers off`
|
||
+ 凭据头抹空(`x-api-key` / `api-key` / `x-goog-api-key`)+ 显式放行清单
|
||
(`Content-Type` / `Accept` / `anthropic-version` / `anthropic-beta` / `openai-beta` / `User-Agent`)。
|
||
与 LiteLLM / one-api / Higress 的做法一致,调研与验收证据见
|
||
`docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md`。
|
||
- **`minimax` 上游 base 改到 host 粒度**(`…/anthropic` → `https://api.minimaxi.com`):
|
||
同一条记录、同一把 Key,`/minimax/anthropic/v1/messages` 仍 **200**(落点一字不变),
|
||
`/minimax/v1/chat/completions` 由 **404 → 200**。⚠️ 客户端 `base_url` 用法随之变化,见 §15 提示框。
|
||
- `ipass-1.0.2` / `ipass-1.0.3` 内容见 §12.6 的 tag 表(写共享内存失败必须出声;上游表单地址/密钥框独占整行)。
|
||
- 回归扩至 **167 条**(网关 78 + LLM 89),全绿;新增断言经过反证(还原成改造前配置 → 86 通过 / 3 失败)。
|
||
|
||
- **2026-09-12 .11 实机交付验证 + `base_url` 端口自适应**
|
||
- 在 .11 完成镜像更新(`ipass-1.0.0`,digest `046a9dd7…`):端口 `88:18098`、
|
||
网络 `ipass_default`、数据目录 `/home/train11/ipass/data` 全部复刻,3 账号 / 1 域名 / 1 上游无损。
|
||
- 给 `deepseek` 上游登记 `deepseek-chat` / `deepseek-reasoner`,模型发现随之可用。
|
||
- **`base_url` 改为端口自适应**(`http::host_port`)。此前回显不带端口,而本网关在宿主 **88**
|
||
上;不带端口的地址会落到 443 上的**出口 SSL 设备**(实测 `HTTP 200` + 一个 HTML 登录页),
|
||
客户端照它配置必然失败。挂在 443 反代后面时又必须不带端口 → 只能跟随调用方 Host。
|
||
- §15 对外示例端口由 `:18098` 更正为宿主 `:88`。
|
||
- 回归扩至 **155 条**(网关 78 + LLM 77),`bash tests/run.sh all` 全绿。
|
||
|
||
- **2026-09-12 远程更新控制面 `deploy/ipass-agent.py`(跑在 .11 的 HTTP 服务)**
|
||
- 把 §12.4 的更新动作暴露成 HTTP 接口,远端可自助完成「拉镜像 → 重启 → 看日志 → 回滚」,
|
||
不再需要每次人工登录服务器操作(见 §12.5)。
|
||
- 单文件、仅 Python 标准库;Bearer token 鉴权(`~/.ipass-agent-token`,600);
|
||
`--bg` 双 fork + `setsid` 真后台,另有 `--stop` / `--check`。
|
||
- 变更类接口为异步任务(`POST` 返 `job id`,`GET /jobs/<id>?offset=N` 增量拉日志);
|
||
**同一时刻只允许一个变更任务**,并发请求返回 409。
|
||
- 端口/挂载/网络/env/重启策略全部从旧容器 `docker inspect` 复刻(自定义 env 保留、
|
||
Docker 自带的不照抄);动手前自动备份数据 + 打 `rollback-<时间>` 标签。
|
||
- 修掉两个真实隐患:① HTTP/1.1 下鉴权失败的请求体不消费会把残包当成下一个请求(串包);
|
||
② 端口映射同一 host:container 在 inspect 里有 IPv4/IPv6 两条,不去重会重复 `-p`。
|
||
- 本机用真实流程验证:自动探测 → update(7 步全过、env/端口复刻)→ rollback 回到旧镜像
|
||
→ restart / logs / data 脱敏 → 409 并发保护 → 同连接残包测试 → `--bg`/`--stop`。
|
||
- **2026-09-12 一键更新脚本 `deploy/update-ipass.sh`(.11 部署用)**
|
||
- 拉新镜像 → `tar` 备份数据 → 删旧容器 → **按旧容器复刻端口/挂载/网络**起新容器 → 自检。
|
||
- 参数全部自动探测(读 `docker inspect` 静态配置,**停止态容器也能正确识别**;
|
||
`docker port` 对未运行容器返回空,会静默把端口回落成默认值,故不使用)。
|
||
- 端口映射去重:同一映射 inspect 里可能同时含 IPv4/IPv6 两项,重复 `-p` 会导致
|
||
「address already in use」。
|
||
- `--bg` 用 `setsid`/`start_new_session` 真正脱离会话——实测仅 `nohup &`
|
||
会被父进程组连带杀掉(表现为「删完旧容器就停住,新容器没起来」)。
|
||
- 旧镜像自动打 `ipass-gateway:rollback-<时间>` 标签并打印回滚命令。
|
||
- **2026-09-12 上游多模型 + 模型发现 + 用量统计 + 展示名**
|
||
- **上游可挂多个模型**:`llm-upstreams.json` 每个上游新增 `models` 清单(管理台可编辑,
|
||
逗号 / 顿号 / 分号 / 换行都当分隔符),**仅用于模型发现**,不参与转发路由
|
||
(网关仍不解析请求体、不按 `model` 字段路由)。
|
||
- **模型列表 API**:`GET /v1/models`(LLM 域名下,OpenAI `{object:"list",data:[{id,...}]}` 形状)
|
||
与 `GET /api/v1/models`(管理端口,统一响应体 + `base_url`),**同源、按白名单过滤、网关本地应答**。
|
||
另有 `GET /api/v1/upstreams` 列出可用上游及其 `base_url`。
|
||
- **用量统计(请求级)**:新增 `GET /api/admin/usage`(管理台「用量统计」Tab:按账号 / 按上游)
|
||
与 `GET /api/v1/usage`(账号本人,含分上游明细与限流回显);`/api/v1/me` 附带 `llm_usage` 摘要。
|
||
口径:**只统计真正转发出去的请求**,401/403/404/429 **不计**;与配额计数 `st:` 刻意分开;
|
||
计数存共享内存(`ust:` 每账号、`ums:` 每账号×上游),重启归零、不落盘。
|
||
- **账号展示名**:`users.json` 新增 `display_name`(中文名等,**纯展示、不参与鉴权**),
|
||
对应 `POST /api/admin/users/display`;管理台账号列表与用量报表按展示名优先显示、空则回落账号名。
|
||
- **修复 `/v1` 版本段重复拼接**:上游 `base` 自带 `/v1`(如 DeepSeek)时,客户端再带 `/v1`
|
||
会拼成 `/v1/v1/...` → 上游 404 且**响应体为空**(极难排查)。新增 `join_target()` 去重,
|
||
账号态 `base_url` 同步保留上游路径;三种路径组合均有回归覆盖。
|
||
- **修复「删账号后仍留在用量榜」**:用量键(`ust:` / `ums:`)是按前缀扫出来出报表的,
|
||
删账号时没清 → 已删账号会一直挂在用量榜上。新增 `stats::forget()`,在 `users::delete` 里调用
|
||
(与「删账号必须摘 `ukey:` 索引」同类的正确性问题,只是影响面在报表不在鉴权)。
|
||
- 管理台:新增「用量统计」Tab、账号「展示名」与「LLM 用量」列、上游「模型」列与「编辑」按钮。
|
||
- 回归扩至 **153 条断言**(网关 78 + LLM 75),`bash tests/run.sh all` 全绿。
|
||
- **2026-09-11 端口 18098 + 三域名分流 + 构建树内化**
|
||
- 三个 mayishangshu 域名收敛到同端口 **18098 ssl**(路由器 NAT 18098 → 本机 18098):
|
||
管理台 `mdm`、LLM `lm`、企业转发 `*.dm`,共用 `*.mayishangshu.cn` 通配符证书
|
||
(`conf/tls/*.shangshuwang.cn/`,acme.sh 签发,已 gitignore)。
|
||
- 本机 nginx 构建树从 `/tmp` 搬入 `build/ngxbuild/`(含 nginx/pcre 源码包,已 gitignore)。
|
||
**搬动构建树后必须原地 `./configure && make` 重配**——`objs/Makefile` 里写死了绝对路径,
|
||
悬空会导致 `cargo build` 找不到 `pcre.h`(功能参数不变则 `NGX_MODULE_SIGNATURE` 不变,无需重编模块)。
|
||
- 回归夹具重置由 `rm` 改为 **`cp` 覆盖写**(新增 `tests/gateway/fixtures/`),
|
||
兼容本机安全钩子;修复 `tests/run.sh all` 收尾未初始化变量。当时 **89 条断言全绿**
|
||
(2026-09-12 已扩至 153 条)。
|
||
- TLS 证书管理与外网访问链路(hairpin 环回)分别见 §12.2 / §12.3。
|
||
- **2026-09-10 限流/配额 + HTTPS**
|
||
- 新增按 Key 的 LLM 限流:`llm_rpm`(每分钟,默认 60)/ `llm_daily`(每日,默认不限),
|
||
账号缺省取全局默认、`0` = 不限,配置编码进 `ukey:` payload,热路径仍是纯共享内存。
|
||
- 计数器为每账号固定单键(`rl:<user>` / `st:<user>`,value = `<窗id>:<计数>`),
|
||
跨窗靠读时比对窗 id 归零——避免 shm 键随时间无限累积。
|
||
- 新增接口 `POST /api/admin/users/limits`;用户列表合并今日用量 `llm_today`;
|
||
管理台账号行显示「LLM 今日 n 次 · 限 x/分 · y/日」并可弹窗修改。
|
||
- 429 错误体区分 `rate_limit_error`(SDK 退避重试)与 `insufficient_quota`。
|
||
- HTTPS 可选启用:`conf/tls/*.conf` 自动 include(空目录不影响启动)、
|
||
`compose.yml` 映射 443、模板 `conf/tls/llm.conf.example`;生产 Dockerfile
|
||
**补编 `--with-http_ssl_module`**(此前没编,443 在容器里起不来——模板验证时发现)。
|
||
- 本机 nginx 重编带 ssl 模块;LLM 回归扩至 **34 条**(新增限流 10 条 + HTTPS 3 条)。
|
||
- **2026-09-10 本机回归夹具入库**
|
||
- 原先散在 `/tmp/ngxrun`、`/tmp/llmrun` 的验证夹具**移入仓库 `tests/`**,统一入口
|
||
`bash tests/run.sh [gateway|llm|all]`(自动 `cargo build` + 起停 nginx + 跑断言 + 收尾)。
|
||
- 测试配置改为 `*.conf.in` 模板渲染(`@MODULE@` / `@REPO@` / `@RUN@` 占位),
|
||
状态目录固定为 `tests/.run/*/data/` —— 跑回归**不会接触生产 `data/`**。
|
||
- 新增 LLM 侧断言 34 条:Key 替换 / 路径拼接 / 白名单 / 停用摘除 / SSE 不缓冲 / 限流 / HTTPS。
|
||
其中「Key 是否真被替换」读的是**假上游实际收到的请求头**,而不是网关自己的响应。
|
||
- **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 改为**自编译 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`),
|
||
覆盖全部接口 + 转发即时生效/失效 + 越权隔离。
|
||
- **2026-09-10 LLM API 代理**
|
||
- 新增 `lm.mayishangshu.cn:18098` 统一出口:客户端用与域名接口**同一把** API Key 鉴权,
|
||
网关换成上游真实密钥后转发,下游不接触厂商 Key。
|
||
- 上游由 URL 前缀(`/<slot>/...`)决定,**不解析请求体**——access 阶段读不到 body。
|
||
- 新增 `data/llm-upstreams.json` 上游表(base + 真实 Key + 启用开关),
|
||
以及账号级白名单 `allowed_models`(空 = 不限)。
|
||
- 新增接口:`GET|POST /api/admin/upstreams*`、`POST /api/admin/users/models`、`GET /api/v1/upstreams`。
|
||
- 账号 Key 索引进共享内存(`ukey:`),LLM 热路径不回读 `users.json`;
|
||
重置/删除账号时同步摘除,避免「换了 Key 却还能用」。
|
||
- 支持 SSE 流式透传、上游 base 带路径、多模态大 body。
|
||
- **2026-09-10 权限化改造(不向后兼容)**
|
||
- 新增账号体系:多账号 + 每账号随机 API Key + 角色(`admin` / `user`)。
|
||
- 新增「临时授权权限」(6 小时,管理员勾选授予):持有者在申请临时域名时**免审直接放行**。
|
||
- 新增临时/长期域名区分与审核流:无权限的临时域名、以及全部长期域名进入管理员审核队列。
|
||
- 新增管理台单页(登录、审核队列、全部域名、账号管理),用户态(API Key)与管理态(登录会话)分权。
|
||
- 数据落盘从单个扁平映射 `proxy_config.json` 迁移为 `data/users.json` + `data/domains.json`(原 `test` / `testa` 两条映射已迁移为 admin 名下的长期域名)。
|
||
- 转发链路新增:状态与有效期校验、缓存 TTL 按剩余有效期收敛、写操作主动失效缓存。
|
||
- 安全加固:口令加盐迭代哈希、常量时间比较、`HttpOnly`+`SameSite` 会话、登录限速、只读挂载、默认拒绝。
|
||
- **2026-09-10 整理**
|
||
- 校验规则修正:原先的校验正则误用了 Perl 风格语法(`%w`/`%d`)却交给 PCRE 的 `ngx.re` 执行,已改为 PCRE 语法。
|
||
- 管理台 `[hidden]` 失效修复(author 样式的 `display` 会盖掉 UA 的 `display:none`)。
|
||
- 补齐 `.gitignore`;清理 `.DS_Store`;`resolver` 改为国内可用 DNS。
|