Files
ipass__ipass/readme.md
T

1141 lines
77 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/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 + 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 │
└──────────────────────────────────┘
```
设计要点:
- **共享内存才是运行期唯一真源**,`data/*.json` 是它的持久化副本。
三个表(转发映射 / 账号 Key / LLM 上游)在 fork 前一次性装载进共享内存,
**热路径零文件 I/O**;未命中就等于「不存在」,不存在任何回源读文件的兜底路径。
- 所有写操作都会**同时更新共享内存与文件**(写穿),因此**审批一通过就立即生效**,且重启后配置不丢。
- 代价:手改 `data/*.json` 不再热生效,需重启。
- 转发侧只做一件事:查表 → 设置 `$proxy_backend_addr`。任何异常都只导致 404,不影响网关本身。
---
## 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 动态模块(业务全部在这里)
│ ├── Cargo.toml # ngx / nginx-sys 走 path 依赖(vendor)
│ ├── build.rs # macOS 需要 -undefined dynamic_lookup
│ ├── vendor/ngx-rust/ # vendored 的 ngx-rust(不可换成 crates.io / git)
│ └── src/
│ ├── lib.rs # 模块入口:指令、共享内存装载、变量注册、三个阶段处理器
│ ├── api.rs # API 统一分发器(路由表 + 鉴权分流)
│ ├── users.rs # 账号:创建/改密/重置 Key/授予与撤销临时授权
│ ├── domains.rs # 域名:申请/审核/过期判定/写穿共享内存/清理
│ ├── upstreams.rs # LLM 上游(含真实密钥)
│ ├── session.rs # 管理员登录会话
│ ├── state.rs # 共享内存(SlabPool + RbTreeMap + RwLock)
│ ├── store.rs # JSON 原子读写 + 跨 worker 文件锁
│ ├── http.rs # 参数合并、两段式请求体读取、JSON 响应
│ ├── util.rs # 随机数/摘要/口令哈希/常量时间比较/日志
│ ├── models.rs # User / DomainEntry 结构
│ ├── llm.rs # LLM 转发热路径
│ └── config.rs # 全部策略常量(TTL、保留名、长度上限)
├── www/
│ └── admin.html # 管理台单页(登录 / 审核队列 / 全部域名 / 账号管理 / 用量统计)
├── tests/ # ★ 本机回归夹具(bash tests/run.sh [gateway|llm|all])
│ ├── run.sh # 统一入口:编译 + 渲染配置 + 起停 nginx + 跑断言
│ ├── gateway/ # 域名网关:nginx.conf.in + e2e.sh(90 条断言)+ 转发靶机
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(111 条)+ 假上游 + 合成夹具
│ # (.run/ 是运行目录,已 gitignore)
├── data/ # ★ 状态目录(需可写;运行期真源在共享内存)
│ ├── users.json # 账号表(含口令哈希与 API Key)
│ ├── domains.json # 子域名映射表 + 申请记录
│ └── llm-upstreams.json # LLM 上游表(含厂商真 Key)
├── logs/ # 日志(容器内软链到 stdout/stderr)
└── archive/
└── openresty-lua-20260910/ # 旧 OpenResty+Lua 版归档(只读参考)
```
容器内路径映射(见 `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. 管理台使用
单页应用,六个 Tab(**数据总览为默认页**,统计不再占审核队列的版面):
| Tab | 能力 |
| --- | --- |
| **数据总览** | 待审核申请 / 域名总数 / 可用中 / 账号总数 / LLM 上游数 / 今日与累计调用 / 可用模型数 |
| **审核队列** | 列出所有待审申请(子域名、后端、类型、申请人、提交时间),一键**通过**或**驳回** |
| **全部域名** | 管理员直接新建域名并放行(跳过审核,子域名按规则自动生成、可「换一个」);查看全部域名及其状态、到期倒计时;**点击域名即复制完整域名**(含端口);删除映射 |
| **账号管理** | 新建账号(角色、勾选临时授权权限);账号列表:复制/重置 API Key、授权或取消「临时授权权限」、改密码、删除账号 |
| **LLM 上游** | 新建/编辑/启停/删除上游;模型清单维护;每行 slot 旁有 **OpenAI / Anthropic 两枚复制地址按钮**(按当前 Host 自动生成、已处理 `/v1` 拼接去重,点一下即复制,客户端拿去当 `base_url`,不用自己猜路径);**健康徽标**(`ok` 绿 / `failed` 红 / `unknown` 灰,打开面板自动探测,**测试**按钮可手动刷新) |
| **用量统计** | 全局合计 + 按账号 + 按上游的今日 / 累计 / 最近调用 |
几点说明:
- **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 用量总览:全局合计 + 按账号 + 按上游(每个含今日 / 累计 / 最近调用) |
> 完整路由表以 `rust/src/api.rs` 的 `route()` 为准(精确匹配,新增接口三步见 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/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`**
---
## 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` 让共享内存清空(或等 TTL 到期)。
**关于扩容**:共享内存和 JSON 文件都是**单实例内**的,多副本部署时各副本状态不共享。
当前定位是单实例出口;如需高可用,应把 `domains.json` 换成 Redis/etcd 之类的共享存储。
### 12.1 改了代码怎么验(本机回归)
夹具在仓库里 `tests/`,**不进 Docker**,直接在本机跑(秒级):
```bash
bash tests/run.sh # 全部:域名网关 90 条 + LLM 代理 111 条
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/ssw/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` 备份数据目录、给旧镜像打 `ipass-gateway:rollback-<时间>` 标签。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| 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?}` → 回滚到最近(或指定)的 `rollback-*` 镜像 |
| 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 # 一条龙:构建推送 → 更新 → 验收
bash deploy/agent.sh rollback [tag] # 出事回滚
```
`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)。
- 本机构建必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。
| 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,否则新容器缺审计挂载。** |
---
## 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`(管理台「用量统计」Tab) | 全局合计 + 按账号 + 按上游,每项含今日 / 累计 / 最近调用时间 |
| 账号本人 | `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` 直接显示今日用量
### 路径拼接(版本段去重)
客户端请求路径会**原样接到上游 `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` 用于**模型发现**;管理台「上游管理」有「模型」列与「编辑」按钮可直接维护,
支持一次粘贴多行(逗号 / 顿号 / 分号 / 换行都当分隔符)。
`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` 也会自动不带端口。写死任何一种都会在另一种部署下
给出「看着对、打不通」的地址。
---
## 16. 变更记录
- **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 动态模块**(取代下面的 OpenResty+Lua 实现)
- 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从 Lua 平移进 Rust 模块,
**接口路径、请求/响应格式、`data/*.json` 字段与口令哈希算法全部保持兼容**,前端 `admin.html` 无需改动。
- 换掉了「文件是真源、共享内存只是缓存」的语义:**共享内存成为运行期真源**,
三个表在 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`。
- 本地回归:`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。
- 上游由 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 小时,管理员勾选授予):持有者在申请临时域名时**免审直接放行**。
- 新增临时/长期域名区分与审核流:无权限的临时域名、以及全部长期域名进入管理员审核队列。
- 新增管理台单页 `www/admin.html`:登录、审核队列、全部域名、账号管理。
- 新增 API 分发器 `lua/api.lua`,用户态(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 语法。
- 管理台 `[hidden]` 失效修复(author 样式的 `display` 会盖掉 UA 的 `display:none`)。
- 补齐 `.gitignore`;清理 `.DS_Store`;`resolver` 改为国内可用 DNS。