iPass 山海关 — 公司统一动态域名解析出口

一次泛解析,子域名无限;申请—审批—放行全流程在线。 DNS 只配一条泛解析 *.yourdomain.com → 本网关,所有内部服务、演示环境、动态 IP 后端统一从这里进出; 子域名映射通过管理台/接口热更新,不改 DNS、不 reload Nginx、不重启容器。

技术栈: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(只需给要访问的子域名加,泛解析由网关负责):

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 走一遍完整流程

  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 传递。

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

{
  "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

[
  {
    "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-<上游厂商真实密钥>",
    "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. 运维

# 实时看转发情况(自带 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            # 全部:域名网关 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 天)

续期后同步并生效:

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:

# 任何 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。
S
Description
尚数网 统一网关 (iPass 山海关) — vanilla nginx + Rust 动态模块。从 /ssw/ipass 平迁过来。
Readme
1.2 MiB
0 Stars 1 Watchers 0 Forks
Languages
Shell 40.1%
JavaScript 24.7%
Python 21.8%
Rust 8.5%
CSS 3.3%
Other 1.6%