功能(本轮 5 项需求的落地):
- 上游可挂多模型:llm-upstreams.json 每上游新增 models 清单(仅用于模型发现,不参与路由)
- 模型发现:GET /v1/models(OpenAI {object:list} 形状,网关本地应答)+ /api/v1/models + /api/v1/upstreams
- 用量统计:/api/admin/usage(管理台「用量统计」Tab)+ /api/v1/usage + /me 的 llm_usage 摘要
口径:只统计真正转发出去的请求,401/403/404/429 不计;与配额计数 st: 刻意分开
- 账号展示名 display_name(纯展示,不进 ukey:)
- 修复 /v1 版本段重复拼接(llm::join_target)→ 上游 base 自带 /v1 时不再 404 空体
- 修复删账号未清用量键(stats::forget)
部署脚本 deploy/update-ipass.sh:
- 拉镜像 → tar 备份数据 → 删旧容器 → 按旧容器复刻端口/挂载/网络起新容器 → 自检
- 参数从 docker inspect 静态配置读取(docker port 对停止态容器返回空,会让端口静默回落)
- 端口按 host:container 去重(inspect 同一映射含 IPv4/IPv6 两项,重复 -p 会 address already in use)
- --bg 用 setsid/start_new_session 真正脱离会话(仅 nohup & 会被父进程组连带杀掉)
- 旧镜像自动打 rollback-<时间> 标签,收尾打印回滚命令
回归:bash tests/run.sh all → 网关 78 + LLM 75 = 153 条断言全绿。
文档:readme §12.4 / §15 / §16、CLAUDE.md 常用操作 + 排障速查已同步。
827 lines
50 KiB
Markdown
Executable File
827 lines
50 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
|
||
```
|
||
|
||
要点:
|
||
|
||
- **到期不等于删除**。临时域名过期后仅「不再转发」,记录仍在列表里显示为「已过期」,便于追溯;管理员可一键清理。
|
||
- **过期即释放**。某个子域名过期后,任何人都可以重新申请(不会一直被占着)。
|
||
- **审核即时生效**。审批通过后网关立刻开始转发,不需要重启、不需要等缓存(写操作会主动失效该子域名的转发缓存)。
|
||
|
||
---
|
||
|
||
## 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(78 条断言)+ 转发靶机
|
||
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(75 条)+ 假上游 + 合成夹具
|
||
│ # (.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. 管理台使用
|
||
|
||
单页应用,四个区域:
|
||
|
||
| 区域 | 能力 |
|
||
| --- | --- |
|
||
| **顶部统计** | 待审核申请 / 域名总数 / 可用中 / 账号总数 |
|
||
| **审核队列** | 列出所有待审申请(子域名、后端、类型、申请人、提交时间),一键**通过**或**驳回** |
|
||
| **全部域名** | 管理员直接新建域名并放行(跳过审核);查看全部域名及其状态、到期倒计时;删除映射 |
|
||
| **账号管理** | 新建账号(角色、勾选临时授权权限);账号列表:复制/重置 API Key、授权或取消「临时授权权限」、改密码、删除账号 |
|
||
|
||
几点说明:
|
||
|
||
- **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`、`models`、`note`) |
|
||
| 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 时用后面的,自研/管理脚本用前面的。
|
||
|
||
参数可用 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` | - | 全部域名 + 待审数量 |
|
||
| POST | `/api/admin/domains/review` | `id`、`action`(`approve`/`reject`) | 审批 |
|
||
| POST | `/api/admin/domains/create` | `subdomain`、`backend`、`type`、`owner` | 直接创建并放行 |
|
||
| 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 # 全部:域名网关 78 条 + LLM 代理 75 条
|
||
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`。
|
||
|
||
---
|
||
|
||
## 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:18098` 作为公司所有大模型的统一出口。客户端只持有一把**本网关签发的 Key**
|
||
(就是 `users.json` 里属于自己账号的那把 `sk_...`),各家厂商的真实密钥全部由网关保管——
|
||
客户端看不到,也不需要逐家去申请。
|
||
|
||
### 怎么用
|
||
|
||
`<slot>` 是上游名,对应 `data/llm-upstreams.json` 的 key:
|
||
|
||
```bash
|
||
# 任何 OpenAI 兼容客户端:只改 base_url 与 api_key
|
||
curl https://lm.mayishangshu.cn:18098/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"}]}'
|
||
```
|
||
|
||
- **同一把 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:18098/v1/models \
|
||
-H "Authorization: Bearer sk_<你的 API Key>"
|
||
```
|
||
|
||
### 模型发现
|
||
|
||
**一家上游通常挂很多模型**,网关把「谁提供哪些模型」登记在上游配置的 `models` 字段里
|
||
(见「上游配置」)。两处可查,**数据同源、形状不同**:
|
||
|
||
| 入口 | 响应形状 | 给谁用 |
|
||
| --- | --- | --- |
|
||
| `GET https://lm.mayishangshu.cn:18098/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`(账号态)会给每个可用上游回一个 `base_url`,形如
|
||
`https://lm.mayishangshu.cn/<slot><上游路径>`——客户端拿它当 `base_url` 直接拼即可,
|
||
不必自己关心上游 `base` 里有没有 `/v1`。
|
||
|
||
---
|
||
|
||
## 16. 变更记录
|
||
|
||
- **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。
|