- docs §七:本次改造实际发出的配置、生产验收表(.11 临时挂 echo 上游)、 反证结果(还原成改造前 → 3 条凭据断言如实变红)、统一注册的改前改后实测、 两个副作用(路径空间放大 / base_url 变协议中立)与回退命令。 - readme:§12.6 tag 表补齐 1.0.2 / 1.0.3 / 1.0.4(这三版此前没登记); §15 增加提示框说明「base 写到哪一层决定 base_url 是否协议中立」及 Anthropic 客户端必须自己补 /anthropic;§16 补本轮变更记录。
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(77 条)+ 假上游 + 合成夹具
│ # (.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(只需给要访问的子域名加,泛解析由网关负责):
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 启动
# 可选:指定初始管理员密码(不设则默认 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 走一遍完整流程
- 「账号管理」→ 新建账号
alice,勾选 给临时授权权限(6h) → 记下弹出提示里的 API Key; - 再建一个
bob,不勾选; - alice 用 API Key 申请临时域名 → 返回「已直接放行」;
- bob 用 API Key 申请临时域名 → 「审核队列」出现待审项;
- 管理员在「审核队列」点通过 → bob 的域名立即可访问;
- 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 传递。
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
{
"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
[
{
"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
{
"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. 运维
# 实时看转发情况(自带 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 tests/run.sh # 全部:域名网关 78 条 + LLM 代理 77 条
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 天) |
续期后同步并生效:
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 -pubkeyvsopenssl 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 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 / 值班人)不必登录服务器就能完成「拉镜像 → 重启 → 看日志 → 回滚」,
形成「本机构建推送 → 远程自更新 → 远程自验证」的闭环(不必每次找人上机器操作)。
# 拷到 .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 |
所有容器(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?} 只接受受管容器) |
典型远程调用:
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)。
爆炸半径:只碰一个容器。虽然它等价 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 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。 |
13. 安全
已做的:
- 口令加盐迭代哈希(1000 轮 SHA-256 + 每账号随机盐),不落明文、不回传哈希。
- API Key 随机生成(
sk_+ 24 字节密码学随机数),比较使用常量时间实现,避免时序侧信道。 - 管理员会话:随机会话令牌存共享内存,Cookie 带
HttpOnly+SameSite=Strict,8 小时滑动过期,重启即失效。 - 登录限速:同一 IP 5 分钟内失败 10 次即拒绝(429),成功登录后清零。
- 越权隔离:普通账号无法登录管理台、无法访问管理员接口、无法删除他人域名。
- 最小暴露:
conf/、www/以只读方式挂载进容器;默认 server 对非*.yourdomain.com的请求直接 403。
需要你注意的:
- 三个入口均已上 TLS(
mdm/lm/*.dm共用 18098 ssl + 通配符证书,见 §12.2); TLS 在网关终结,网关到后端仍是内网 HTTP——敏感后端请自行加内网 TLS。 - 初始管理员密码默认
123456,首次登录必须修改;生产建议通过ADMIN_INIT_PASSWORD注入后再首次启动。 - 建议把
mdm.mayishangshu.cn:18098管理入口限制在内网或加一层来源 IP 白名单,普通业务域名照常对外。 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:
# 任何 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"}]}'
- 同一把 Key 通吃:域名接口用
X-API-Key,LLM 代理用Authorization: Bearer或x-api-key, 都是同一把;改密码不影响 Key,重置 Key 则两处同时失效。 - 换厂商不改客户端:把 base_url 里的
openai换成deepseek即可(需管理员给你开白名单)。 - 流式(SSE)原生支持:
"stream": true逐块透传,网关不做缓冲。 - 支持
?query参数、多模态大 body(上限 100MB)、上游base带路径的网关型上游。
# 发现可用模型(用同一把 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 |
一个请求拿到用量摘要,便于客户端自我节流 |
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:88/<slot><上游路径>——客户端拿它当 base_url 直接拼即可,
不必自己关心上游 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(续)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 失败)。
- 修复凭据泄漏(安全):LLM location 此前只覆写
-
2026-09-12 .11 实机交付验证 +
base_url端口自适应- 在 .11 完成镜像更新(
ipass-1.0.0,digest046a9dd7…):端口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全绿。
- 在 .11 完成镜像更新(
-
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、LLMlm、企业转发*.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。
- 三个 mayishangshu 域名收敛到同端口 18098 ssl(路由器 NAT 18098 → 本机 18098):
管理台
-
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 条)。
- 新增按 Key 的 LLM 限流:
-
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两段构建、vendoredngx-rust。 - 本地回归:
tests/gateway/e2e.sh共 55 条断言(bash tests/run.sh gateway), 覆盖全部接口 + 转发即时生效/失效 + 越权隔离。 - 旧实现完整归档于
archive/openresty-lua-20260910/(含SHA256SUMS与 tarball,刻意排除data/)。
- 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从 Lua 平移进 Rust 模块,
接口路径、请求/响应格式、
-
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会话、登录限速、只读挂载、默认拒绝。
- 新增账号体系:多账号 + 每账号随机 API Key + 角色(
-
2026-09-10 整理
- 校验规则修正:原先的校验正则误用了 Lua 语法(
%w/%d)却交给 PCRE 的ngx.re执行,已改为 PCRE 语法。 - 管理台
[hidden]失效修复(author 样式的display会盖掉 UA 的display:none)。 - 补齐
.gitignore;清理.DS_Store;resolver改为国内可用 DNS。
- 校验规则修正:原先的校验正则误用了 Lua 语法(