Files
ipass__ipass/readme.md
T
admin 0b1d983cac 定位更名:尚数网 统一网关(原「公司统一动态域名解析出口」)
- readme 头部改为统一网关定位,明确两类能力:动态域名、LLM API 路由,预留未来扩展
- CLAUDE.md / compose.yml / Cargo.toml description / lib.rs 模块注释同步更名
2026-09-11 15:58:41 +08:00

684 lines
39 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
```
要点:
- **到期不等于删除**。临时域名过期后仅「不再转发」,记录仍在列表里显示为「已过期」,便于追溯;管理员可一键清理。
- **过期即释放**。某个子域名过期后,任何人都可以重新申请(不会一直被占着)。
- **审核即时生效**。审批通过后网关立刻开始转发,不需要重启、不需要等缓存(写操作会主动失效该子域名的转发缓存)。
---
## 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(55 条断言)+ 转发靶机
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(22 条)+ 假上游 + 合成夹具
│ # (.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、临时授权权限到期时间、名下域名 |
| GET | `/api/v1/domains` | - | 我申请的全部域名 |
| POST | `/api/v1/domains/apply` | `subdomain`、`backend`、`type`(`temp`/`long`) | 申请域名。符合免审条件即刻放行,否则进入待审 |
| POST | `/api/v1/domains/delete` | `id` | 删除自己名下的域名(只能删自己的) |
参数可用 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` | 新建账号,自动生成随机 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/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` / `note` / `enabled`,**不回显 `auth`**) |
| POST | `/api/admin/upstreams/save` | `slot`、`base`、`auth`、`enabled`(可选,缺省=启用)、`note` | 新增 / 更新上游;`auth` 留空 = 不透传鉴权头(本地免鉴权后端) |
| POST | `/api/admin/upstreams/delete` | `slot` | 删除上游 |
> 完整路由表以 `rust/src/api.rs` 的 `route()` 为准(精确匹配,新增接口三步见 CLAUDE.md「硬约定」)。LLM 相关接口(`users/models` / `users/limits` / `upstreams*`)详见第 15 节。
---
## 11. 数据模型
### `data/users.json`
```json
{
"alice": {
"username": "alice",
"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 > 当前时间` 即表示该账号拥有「临时授权权限」。
`api_key` 是**域名接口与 LLM 代理共用**的一把 Key:域名接口读 `X-API-Key`,
LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口。
`allowed_models` 是 LLM 代理可用的上游白名单(取值对应 `llm-upstreams.json` 的 key)。
**留空表示不限**;老数据没有该字段,反序列化后即为空表,语义正好也是「不限」。
`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-<上游厂商真实密钥>",
"enabled": true,
"note": "生产 OpenAI",
"created_at": 1789037728
},
"deepseek": {
"base": "https://api.deepseek.com",
"auth": "Bearer sk-<上游厂商真实密钥>",
"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`,
用于本身也挂在网关下的厂商)
- `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 # 全部:域名网关 55 条 + LLM 代理 34 条
bash tests/run.sh gateway # 只跑域名网关
bash tests/run.sh llm # 只跑 LLM 代理
```
脚本会自动 `cargo build`、把 `tests/*/nginx.conf.in` 渲染成带绝对路径的配置、
起 nginx(18080 转发 / 18081 靶机 / 18082 管理 / 18090 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+外网链路)。哪一段先断,问题就在哪一段。
---
## 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` 带路径的网关型上游。
### 权限与错误
每个账号有一份**可用上游白名单**(`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`,
**改动立即生效、无需重启**。字段说明见「数据模型」。
---
## 16. 变更记录
- **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 条断言全绿**。
- 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。