Files
ipass__ipass/readme.md
T
admin 5e8c38aef4 feat(deploy): 新增 ipass-agent.py —— 跑在 .11 的远程更新控制面(HTTP)
把 update-ipass.sh 的动作暴露成 HTTP 接口,远端(AI/值班人)不必登录服务器即可
完成「拉镜像 → 重启 → 看日志 → 回滚」,形成「本机构建推送 → 远程自更新 → 自验证」闭环。

- 单文件、仅 Python 标准库(无 Flask/requests);Bearer token 鉴权,token 落
  ~/.ipass-agent-token(600);--bg 双 fork + setsid 真后台,另有 --stop/--check。
- 端点:/health /check /status /containers /logs /data(脱敏) /jobs[/id] /pull /update
  /rollback /restart。
- 变更类接口为异步任务(返 job id,/jobs/<id>?offset=N 增量取日志);
  同一时刻只允许一个变更任务,并发返回 409。
- 端口/挂载/网络/env/重启策略全部从旧容器 docker inspect 复刻;自定义 env 保留、
  Docker 自带的不照抄;动手前自动备份数据 + 打 rollback-<时间> 标签。

修掉两个真实隐患:
- HTTP/1.1 下鉴权失败的请求体若不消费,残包会被当作下一个请求的请求行 → 响应串包
  (已在 _dispatch 开头统一读掉 body)。
- 端口映射同一 host:container 在 inspect 中含 IPv4/IPv6 两条,不去重会重复 -p。

本机用真实流程验证:自动探测 → update 7 步全过(端口/自定义 env 复刻)→ rollback
回到旧镜像 → restart/logs/data 脱敏 → 409 并发保护 → 同连接残包测试 → --bg/--stop。

文档:readme §12.5 / §16、CLAUDE.md 新增「远程控制面」小节。
2026-09-12 10:20:49 +08:00

897 lines
55 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(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`。
### 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)
```
- 单文件、**只用 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` | 容器列表(只留与 ipass/nginx 相关的) |
| 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?}` → 完整更新 |
| POST | `/rollback` | `{tag?}` → 回滚到最近(或指定)的 `rollback-*` 镜像 |
| POST | `/restart` | 只重启容器(同步返回) |
典型远程调用:
```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.0"}' $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 # 出事回滚
```
**安全**:这个服务能删/起容器,**等价服务器上的 docker 权限**,务必做到
① **必须设 token**(别用空/弱口令);② 只在内网监听(默认 `0.0.0.0`,可 `--bind 127.0.0.1`
或加防火墙);③ **绝不暴露到公网**。`/data` 对 `api_key` 已脱敏,但 `domains.json` 会原样返回。
> `update-ipass.sh`(§12.4)仍然保留:没有 python3、或服务没起来时的应急手段。
---
## 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/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。