admin 762d308745 test+deploy: 探针改目录驱动 + 三态判定 + 发版失败自动回滚(镜像+数据)
两件事:

1) 验证脚本统一从 /api/v1/me 拉能力目录(新增 tests/me_catalog.py 共享模块)。
   之前 slot×模型、apix 条目写死在脚本里——配置是管理台动态的,改配置后探针
   要么漏验新上游、要么拿旧模型名误报。现在 test_models 按 upstreams×models
   全展开(both 双格式并发),apix_check 按目录逐条探;拉不到目录退出码 2
   (验证失效 ≠ 上游没问题,不许假绿)。
   三态口径:❌ 网关侧故障(错误体归属 + HTTP 码 + error.code 值三重判据——
   智谱 401 体也是 {"error":{code,message}} 形状,光看形态会把欠费误判成发版
   故障);⚠️ 上游/厂商侧(欠费 402、不可达 502/504、WAF、200 软错误)
   **如实汇总反馈但不染红发版**;网关 429 限流按 GW_WARN 处理。
   live_check.sh 退出码语义固定:0 过 / 1 网关侧故障 / 2 验证不可用。
   分类器 15 个边界场景离线单测全对(撞形状/码集合/软错误/不误伤正常 200)。

2) agent.sh release 改 4/4 步:验证失败不再停在原地——
   抓 PRE_IMG + update job 的备份路径 → live_check → rc=1 时自动
   POST /rollback {tag, restore_backup} 回滚镜像并恢复 data/audit,回滚后
   再跑 verify 自检;rc=2(验证不可用)**不回滚**(盲回滚比带病观察危险)。
   ipass-agent 1.0.2:rollback 本地无镜像自动 pull(自动路径不许卡「先手动拉」);
   新增 restore_data——先 stop 容器(防周期落盘把污染写回)、备份 tar 解包顶替
   data/audit、现目录改名 .broken-<ts> 留证、只认 ~/ipass/backup/ 下的 tar。
   restore_data 本地单测过(恢复/留证/staging 清理/越界拒绝)。
   release 开头加控制面版本闸门:<1.0.2 会静默忽略 restore_backup → 中止
   (IPASS_FORCE_RELEASE=1 可跳过),⚠️ 线上控制面还是 1.0.1,发版前先上 .11
   跑 §12.5 自更新。
   附带修 bash 老坑:`$VAR` 紧跟全角字符被吞进变量名(unbound variable,
   live_check A 路径实测炸出),统一 ${VAR}。

线上实测:live_check 三步全绿(LLM 10/10 目录全展开 + apix 3/3 + 验收)。
只动 tests/deploy,不进镜像;ipass-agent 属控制面(跑宿主),需单独自更新。
2026-09-17 08:41:48 +08:00

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

要点:

  • 到期不等于删除。临时域名过期后仅「不再转发」,记录仍在列表里显示为「已过期」,便于追溯;管理员可一键清理。
  • 过期即释放。某个子域名过期后,任何人都可以重新申请(不会一直被占着)。
  • 审核即时生效。审批通过后网关立刻开始转发,不需要重启、不需要等缓存(写操作会主动失效该子域名的转发缓存)。

子域名命名规则(i + 8 位随机数 + dm)

管理台「新建域名(直接放行)」的子域名不是自由输入,而是三段拼装,中间那段可点「换一个」重摇:

   i   +   8 位随机数字   +   dm        →   i48291376dm
   ↑          ↑(可换)        ↑
 固定前缀                 固定后缀

完整对外域名 = 子域名 + .mayishangshu.cn,即 i48291376dm.mayishangshu.cn。 面板「全部域名」里点域名即复制,且带端口——用 :88 打开面板就复制成 i48291376dm.mayishangshu.cn:88(端口跟随当前访问方式,理由见 §15「端口跟随调用方」)。

为什么后缀必须是 dm:企业域名 server 的匹配正则是 ^(.+dm)\.mayishangshu\.cn$,捕获组必须以 dm 结尾;不以 dm 结尾的子域名 建出来也匹配不上转发 server(等于建了个打不开的域名)。这是硬约束,不是命名偏好。

规则真源在 rust/crates/plugin-domain/src/config.rs(ENTERPRISE_ZONE / SUBDOMAIN_PREFIX / SUBDOMAIN_SUFFIX / SUBDOMAIN_RAND_DIGITS),由 GET /api/admin/domains 的 subdomain_rule 下发给面板——改后端常量,面板自动跟随;改 zone 必须同步改 conf/nginx.conf 那条正则(两处耦合,注释里已互相标注)。

API 侧同规则:POST /api/admin/domains/create 的 subdomain 缺省(或传空串) 即自动生成同一形态的子域名,撞车会自动换一个重试(最多 5 次);传了值就用传入值 (仍做占用检查)。管理台提交的也是这个拼好的值,两条路径共用 domains::create_by_admin。


5. 架构与请求链路

                    DNS: *.yourdomain.com  →  本网关 IP(泛解析,只配一次)
                                     │
                                     ▼
                   ┌───────────────────────────────────────┐
                   │  nginx :80 + libipass_gateway.so      │
                   │  gateway 装配根:7 条 ipass_* 指令 +   │
                   │  PLUGINS 注册表 + dispatch_api 统一 404│
                   └───────────────┬───────────────────────┘
                                   │ location 开关收敛(阶段处理器是 http 级的)
        ┌──────────────────────────┼───────────────────────────────┐
        ▼                          ▼                               ▼
 Host = mdm…:18098         Host = lm…:18098/<slot>/…      Host = <任意>.yourdomain.com
 ipass_api on(content)   ipass_llm / ipass_apix on      ipass_proxy on(access)
 ┌────────────────────┐   ┌────────────────────────┐    ┌───────────────────────────┐
 │ CorePlugin(内核)  │   │ LlmPlugin / ApixPlugin │    │ DomainPlugin              │
 │  身份端点+会话       │   │  ukey: 鉴权 + 配额      │    │  查 sub: 共享内存          │
 │  先异步读请求体      │   │  up:/ax: 定上游         │    │  (全量常驻,miss = 不存在)│
 │  再按 PLUGINS 顺序  │   │  换上游真 Key 后转发     │    │  校验 status=approved      │
 │  分发,无人认领 404 │   │  (下游不接触厂商 Key)  │    │  且 temp 未过期            │
 └─────────┬──────────┘   └───────────┬────────────┘    │  写 $proxy_backend_addr    │
           │                          │                 └────────────┬──────────────┘
           │ sync_shm(写穿)          │ sync_shm                     │
           ▼                          ▼                              ▼
   data/ 四表:users.json / domains.json / llm-upstreams.json / api-proxies.json(持久化副本)

设计要点:

  • 共享内存才是运行期唯一真源,data/*.json 是它的持久化副本。 各表在 fork 前一次性装载进共享内存,热路径零文件 I/O; 未命中就等于「不存在」,不存在任何回源读文件的兜底路径。
  • 所有写操作都会同时更新共享内存与文件(写穿),因此审批一通过就立即生效,且重启后配置不丢。
  • 代价:手改 data/*.json 不再热生效,需重启。
  • 转发侧只做一件事:查表 → 设置 $proxy_backend_addr。任何异常都只导致 404,不影响网关本身。
  • 插件化边界:依赖方向只能 plugin → core,内核不 import 插件;插件数据反向流只走装配根 (CoreExt 回填 / on_delete 钩子)。详见 docs/plugin/PLUGIN_ARCHITECTURE.md。

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 动态模块(业务全部在这里;2026-09-13 起 workspace 化)
│   ├── Cargo.toml            # workspace 根:members + 统一依赖 + [profile.release]
│   ├── build.rs              # gateway 的 macOS -undefined dynamic_lookup
│   ├── vendor/ngx-rust/      # vendored 的 ngx-rust(不可换成 crates.io / git)
│   ├── crates/
│   │   ├── ipass-core/       # 内核:状态/账号/会话/下行鉴权(auth)/记账原语(usage)/契约(plugin,loc)/身份端点(api)
│   │   ├── plugin-domain/    # 域名插件:申请/审批/ResolveHandler(sub: 键空间)
│   │   ├── plugin-llm/       # LLM 插件:llm/upstreams/usage_filter/llm_audit/stats/handlers
│   │   └── plugin-apix/      # API 代理插件:apix/handlers/api(ax: 键空间)
│   └── gateway/              # 唯一 cdylib:模块壳(指令/开关)+ PLUGINS 注册表 + trend 组合端点
│                             #   插件化架构详见 docs/plugin/PLUGIN_ARCHITECTURE.md
├── www/                      # 管理台(多页,纯静态 + fetch)
│   ├── login.html            # 登录页
│   ├── overview.html         # 数据总览(卡片 + 趋势图 + Top 排名)
│   ├── review.html           # 审核队列
│   ├── domains.html          # 全部域名(新建 / 复制 / 删除)
│   ├── users.html            # 账号管理
│   ├── upstreams.html        # LLM 上游(API 组)
│   ├── usage.html            # 用量统计(趋势 · 按人 · 按 API 组 · token)
│   ├── apix.html             # API 代理(列表 + 弹出卡片编辑 + 免费预估测试)
│   └── assets/               # admin.css + core.js + chart.js + 各页 JS
├── tests/                    # ★ 本机回归夹具(bash tests/run.sh [gateway|llm|all],281 项)
│   ├── run.sh                # 统一入口:编译 + 渲染配置 + 起停 nginx + 跑断言
│   ├── gateway/              # 域名网关:nginx.conf.in + e2e.sh(102 条断言)+ 转发靶机
│   └── llm/                  # LLM 代理:nginx.conf.in + e2e.sh(179 条)+ 假上游 + 合成夹具
│                             #   (.run/ 是运行目录,已 gitignore)
├── data/                     # ★ 状态目录(需可写;运行期真源在共享内存)
│   ├── users.json            # 账号表(含口令哈希与 API Key)
│   ├── domains.json          # 子域名映射表 + 申请记录
│   ├── llm-upstreams.json    # LLM 上游表(含厂商真 Key)
│   └── api-proxies.json      # API 代理表(含供应商真 Key)
└── logs/                     # 日志(容器内软链到 stdout/stderr)

容器内路径映射(见 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. 管理台使用

多页(每页一个 HTML,共用 assets/ 里的样式与脚本),/admin 直接进「数据总览」:

页面 能力
数据总览 卡片:待审核申请 / 域名总数 / 可用中 / 账号总数 / LLM 上游数 / 今日与累计调用 / 今日与累计 token / 可用模型数;趋势图:请求数、入/出 token(默认 14 天);Top 8 排名:按账号、按 API 组
审核队列 列出所有待审申请(子域名、后端、类型、申请人、提交时间),一键通过或驳回
全部域名 管理员直接新建域名并放行(跳过审核,子域名按规则自动生成、可「换一个」);查看全部域名及其状态、到期倒计时;点击域名即复制完整域名(含端口);删除映射
账号管理 新建账号(含展示名、临时授权权限);账号列表:复制/重置 API Key、授权或取消「临时授权权限」、改密码、设置可用上游与限流、删除账号
LLM 上游 新建/编辑/启停/删除上游;模型清单维护;每行 slot 旁有 OpenAI / Anthropic 两枚复制地址按钮(按当前 Host 自动生成、已处理 /v1 拼接去重,点一下即复制,客户端拿去当 base_url,不用自己猜路径);健康徽标(ok 绿 / failed 红 / unknown 灰,打开面板自动探测,测试按钮可手动刷新)
用量统计 区间切换(7/14/30/90 天)+ 趋势视角(全局 / 按账号 / 按 API 组)+ 两张明细表(今日 / 累计 / 入 token / 出 token / 最近调用 / 分上游明细)+ 指标可切换的排名图
API 代理 外部 API 供应商资产挂到网关下(复用 sk_ 鉴权 + 配额 + 用量):列表页 + 弹出卡片编辑(IP.modal),代理增删启停 / 复制地址(含示例 ?q=关键词)/ 免费预估测试;供应商 Key 只回显掩码

趋势与 token 口径(与 §15 用量统计一致):

  • 只统计真正转发给上游的请求,401/403/404/429 不计;token 取自上游响应体里的 usage, 抓不到记 0、不补估(OpenAI 流式客户端需带 stream_options.include_usage)。
  • 趋势是按本地自然日分桶的历史序列(后端 ud: / udu: / uds: 三组键,TTL 90 天), 与「今日 + 累计」是两套数据源——后者跨天归零、不区分日期,画不出曲线。

几点说明:

  • 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、anthropic_base_url、models、status 健康状态)
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 时用后面的,自研/管理脚本用前面的。

9.1 上游健康状态(失效自动标记)

每个上游带一个 status 字段:ok(最近一次真实转发成功)/ failed(最近一次真实转发 失败,附 status_code 与 checked_at)/ unknown(从未被调用过)。

数据来源是真实流量本身:网关在 log 阶段把每次 LLM 转发的上游状态码写进共享内存 (uh:<slot>),4xx 视为「上游活着」(它对请求内容的意见),5xx / 连不上(502) / 等头超时(504) 记为失效;下一次成功转发自动恢复 ok,无需人工清理。这份缓存只用于 展示,不参与转发决策。管理台「LLM 上游」页会标出徽标,并对未探测/失效的上游在 打开面板时自动发一次 1-token 探测;「测试」按钮可随时手动刷新。

一把有效 Key 一次取齐「所有可用 API 地址 + 模型 + 健康状态」: LLM 域名下 GET /v1/models(OpenAI 兼容形状)的顶层额外附 x_ipass_upstreams (SDK 会忽略未知字段),每段含 slot、base_url(OpenAI 用)、anthropic_base_url、 models、status:

curl -s -H "Authorization: Bearer $KEY" https://lm.mayishangshu.cn:88/v1/models | python3 -m json.tool

参数可用 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 - 全部域名 + 待审数量 + subdomain_rule(子域名命名规则,面板据此渲染输入框)
POST /api/admin/domains/review id、action(approve/reject) 审批
POST /api/admin/domains/create backend、type、owner、subdomain(可选) 直接创建并放行。subdomain 缺省/空串 = 自动生成 i<8位随机数>dm(撞车自动重试),传了就用传入值
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 用量总览:全局合计 + 按账号 + 按上游(每个含今日 / 累计 / 最近调用 / token 合计)
GET /api/admin/trend days(可选,默认 14、上限 90) LLM 用量趋势(图表数据源):按本地自然日分桶,返回 {days, labels, total, users, slots},后三者各含 requests / in / out 三条与 labels 等长的数组

完整路由表以各插件 api.rs 的 route() 为准(ipass-core / plugin-domain / plugin-llm / plugin-apix 各管一段,精确匹配,新增接口三步见 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/crates/ipass-core/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

一个上游挂多个账号(accounts,可替代单个 auth)

同一厂商给了多把 Key、额度按周期清零时(典型:MiniMax「每周 + 每 5 小时」), 用 accounts 数组代替 auth,网关会把下游用户 Key 粘性绑定到某一把上游 Key, 某把耗尽后自动切到同厂商下一把:

{
  "minimax": {
    "base": "https://api.minimaxi.com",
    "accounts": [
      {"auth": "Bearer <key1>", "note": "主账号", "resets": [604800, 18000]},
      {"auth": "Bearer <key2>", "note": "备用",   "resets": [604800, 18000]}
    ],
    "exhaust_status": [401, 402, 429, 403],
    "exhaust_markers": ["\"status_code\":1004", "余额不足"],
    "enabled": true
  }
}
  • resets 为历史字段(1.0.44 起不再参与路由,管理台已移除该输入):冷却与恢复改为 指数退避 + 真实请求探测闭环——耗尽账号到期后放一个无绑定真实请求过去探测, 2xx 立即回队、仍耗尽退避翻倍(60s→2m→…→30min 封顶),硬顶到期无条件回队自愈。 全链路不再需要知道厂商的重置窗口口径(旧的天锚定边界计算因两次算错锚点被整体删除, 见 docs/llm/MULTI_ACCOUNT_ROUTING.md §五)
  • accounts[].auth 是完整的 Authorization 头值(如 Bearer sk-…)。只填裸 key 也行—— 读出时 normalize_auth 自动补 Bearer ,免去用户照着 placeholder 填了裸 key 而回 1004 (详见 docs/llm/MULTI_ACCOUNT_ROUTING.md §10)
  • exhaust_status / exhaust_markers 是上游级耗尽判据(所有账号共用): HTTP 状态码命中,或响应体流式扫描到标记子串,即判该账号额度耗尽
  • 无绑定时按 FNV-1a(下游 Key) % 可用账号数 分散(避免全压第一个账号触发厂商 「单账号 agent 并发上限」),但同一 Key 落点固定 → prompt / token 缓存能命中
  • 管理台「上游」页的密钥 / 负载列展示每把 Key 的今日请求 / token / 耗尽次数、 负载比例条与 14 天迷你趋势,用于发现「谁被打满、谁在偏斜」
  • 详见 docs/llm/MULTI_ACCOUNT_ROUTING.md

data/api-proxies.json

{
  "items": {
    "web-search": {
      "asset_id": "searxng-search",
      "supplier": "provider-x",
      "base": "https://api.example.com",
      "key": "ak_<供应商真实密钥>",
      "name": "网页搜索",
      "desc": "按关键词搜索并返回结果",
      "params": ["q"],
      "enabled": true,
      "note": "",
      "created_at": 1789037728
    }
  }
}
  • 每条代理 = 挂在网关下的一个外部 API 供应商资产,账号用同一把 sk_ Key 调 GET /apix/<slug>?<参数>;网关从 query 拼请求体(asset_id 由服务端决定, 调用方只能选参数),换成 key 后转发(详见 §15.1)
  • base / key / supplier 每条自带,无平台级凭据;params 是给调用方看的 参数清单(转发时不过滤);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(共享内存是运行期真源,改文件不热生效)。

关于扩容:共享内存和 JSON 文件都是单实例内的,多副本部署时各副本状态不共享。 当前定位是单实例出口;如需高可用,应把 domains.json 换成 Redis/etcd 之类的共享存储。

12.1 改了代码怎么验(本机回归)

夹具在仓库里 tests/,不进 Docker,直接在本机跑(秒级):

bash tests/run.sh            # 全部:域名网关 102 条 + LLM 代理 197 条
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 -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 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)

远程自更新(.11 上执行,改控制面不用人工拷文件):

bash <(curl -fsSL http://192.168.1.18:13300/ssw/ipass/raw/branch/main/deploy/update-agent-face.sh)

脚本自动:从 Gitea raw 下载新版 → 备份旧版(*.bak-<时间戳>)→ py_compile 校验 → --stop 停旧 → 按原启动参数 --bg 重启 → /health 自检。 token 在 ~/.ipass-agent-token,重启沿用,远端 agent.sh 无需改配置;全程不碰网关容器。

  • 单文件、只用 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 备份数据目录(含 audit)到 ~/ipass/backup/ipass-data-<时间>.tar.gz (1.0.17 起不再给旧镜像打本地 rollback-* 标签——私仓永远保留所有 tag,回滚须显式传 tag)。
方法 路径 说明
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, restore_backup?} → 回滚到指定 tag(1.0.17 起必须显式传 tag,本地没有会自动 pull);restore_backup 给 update 返回的备份 tar 路径时,先停容器把 data/audit 恢复成备份时刻再回滚(发版验证失败的自动回滚用,控制面 ≥1.0.2)
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)。

推荐走 deploy/agent.sh(别手敲上面的 curl)

裸 curl -H "Authorization: Bearer …" 会把凭据摆到命令行上:既容易漏进 shell 历史 / 进程列表, 也会命中**「可疑命令即使已加白名单仍需人工批准」的安全策略,于是每次都弹「凭证授权」; 被拒时命令还会静默无输出**,看着像服务挂了(实测踩过:一次 /update 就是这样没发出去)。

deploy/agent.sh 把凭据只从仓库根 .env 读,对外暴露的全是无凭据子命令,因此只需放行一条 Bash(bash deploy/agent.sh:*):

bash deploy/agent.sh status                  # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh update [tag]            # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
bash deploy/agent.sh wait <job-id>           # 轮询任务直到结束并打印 7 步日志
bash deploy/agent.sh verify                  # 正式环境验收:登录 → 页面标记 → 后端 subdomain_rule
bash deploy/agent.sh release 1.0.7           # 一条龙:构建推送 → 更新 → live_check 发版后验证
                                             #   → 网关侧故障自动回滚镜像 + 恢复数据备份
bash deploy/agent.sh rollback <tag> [备份tar] # 出事回滚(带 tar 同时恢复数据)

verify 是「镜像真的换新了没有」的落地检查:它登录线上管理台,核对页面里的新标记 (如布局的 max-width:1100px、子域名规则的 subdomain_rule / cdSubRoll), 并读 GET /api/admin/domains 确认后端常量已生效——光看容器起来是不够的。

爆炸半径:只碰一个容器。虽然它等价 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)。 ⚠️ 脚本不校验是否已 push——1.0.12 曾发版成功但代码没推到 Gitea,远端看不到。 发版前先 git push,或直接走 bash deploy/agent.sh release <tag>(推荐,一条龙)。
  • 本机构建必须走经典构建器(脚本已内置 DOCKER_BUILDKIT=0):buildx 写 activity 会被沙箱拦 rename。
  • ⚠️ 发版后把 .env 的 IPASS_IMAGE_TAG 同步成新 tag。 update 不带 tag 时用它做缺省值, 它落后于线上就会静默降级回旧镜像(真踩过:1.0.14 发完,.env 还停在 1.0.9)。 agent.sh verify 已加一条漂移告警(.env 默认 tag 与线上不一致时打印 ! 提示,不判失败), 发版一条龙结尾必跑 verify,所以每次都会被提醒。该文件受沙箱写入保护(凭据文件),需人工改。
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。
ipass-1.0.5 上游健康自动标记 + 管理台连通性测试 + 可复制 API 地址。健康数据来自真实流量(log 阶段写 uh:<slot>,4xx=活、5xx/502/504=失效、下次成功自愈);「测试」按钮内部重定向复用 LLM 转发链路真探测;上游列表 OpenAI/Anthropic 复制按钮与 anthropic_base_url;统计挪进独立「数据总览」tab。
ipass-1.0.6 子域名规则固化为 i+8 位随机数+dm(规则真源在 config.rs,经 subdomain_rule 下发给面板;API 不传 subdomain 即自动生成、撞车重试)+ 域名列表点完整域名即复制(带端口,跟随调用方)+ 管理台布局改为自适应(去掉 1180px 居中锁;表单另限宽 1100px)。digest 96c0e952…,commit 12f20dd。
ipass-1.0.7 LLM token 级计量 + 对话审计日志:body filter 旁路(FFI 全局符号注册,单 .so 无需额外 C 模块)解析 SSE 尾部 usage → utt:/utms: 键,用量接口增加 tokens 维度;log 阶段请求体归档到 audit/(data 兄弟目录,10 GiB 容量阈值触发式清理);LLM location 去掉 proxy_request_buffering off(与 body 落盘互斥,SSE 由 proxy_buffering off 保障)。控制面更新后自动挂审计卷。digest 5cd68ec4…,commit 401f9be。注意:需先更新控制面(§12.5 自更新脚本)再 update,否则新容器缺审计挂载。
ipass-1.0.8 管理台图表 + 单页拆分多页。后端新增日桶 ud:/udu:/uds:(趋势数据源,TTL 90 天)与 GET /api/admin/trend;前端拆为 login + overview/review/domains/users/upstreams/usage 六页 + assets/(自绘 SVG 图表,零第三方依赖)。/admin 仍进总览;agent.sh verify 增加「趋势返回 7 天序列」作为换新证据。回归 227 条(网关 102 + LLM 125)。
ipass-1.0.9 新增「API 代理」板块(见 §15.1 与 §16 续7):/apix/<slug> 把外部 API 供应商资产挂到网关下,复用 sk_ 鉴权 + 配额 + 用量统计。
ipass-1.0.10 修复管理台登录页因会话探测 401 被通用兜底重定向的自刷新死循环(/api/admin/session 排除出 401 兜底)。commit dbee9ff。
ipass-1.0.11 API 代理去「市场」概念:每条代理自带 supplier/base/key,无平台级凭据;管理台编辑改弹出卡片(IP.modal)。commit 1fb83e4。
ipass-1.0.12 插件化重构:workspace 化(ipass-core + 三插件 crate + gateway 唯一 cdylib),行为完全等价,262 项回归全绿。commit ddd4172。架构见 docs/plugin/PLUGIN_ARCHITECTURE.md。
ipass-1.0.13 采纳 sso 上游化建议 4 条(User.extra flatten / split_value rposition / iter_prefix_ex / users::update_extra)。commit ee05b27,评估记录 docs/plugin/SSO_UPSTREAM_DECISIONS.md。
ipass-1.0.14 LLM 上游多账号路由 + 额度耗尽自动切换 + 粘性绑定(见 §15「上游配置」与 docs/llm/MULTI_ACCOUNT_ROUTING.md):一个 slot 挂多个账号 Key,下游 Key 与上游账号粘性绑定(ukb:,仅共享内存、重启重绑);无绑定时按 FNV-1a(下游 Key) % n 分散(均匀铺开避开厂商单账号并发上限,同时落点固定保住 prompt/token 缓存);厂商判额度耗尽(HTTP 状态码 或 响应体 marker,流式也扫)即冷却该账号并切下一个,冷却边界天锚定(对齐 MiniMax「5h 窗口、末段 4h 随天重置」)。新增账号级负载统计(uda:/uex: 日桶,复用内核 usage 原语、零新依赖):管理台「上游」页密钥列展示各 Key 今日请求/token/耗尽次数 + 负载比例条 + 14 天迷你趋势。回归 279 条全绿(网关 102 + LLM 177)。
ipass-1.0.15 auth 规范化(normalize_auth)+ 排障子命令。表单 placeholder 写的是 sk-...,用户照着填了裸 key(无 Bearer ),转发时原样发出 → 上游回 1004。plugin-llm 新增 normalize_auth:trim 后无空白即自动补 Bearer ,写入(upsert)+ 读出(read_upa)双处应用——前者让存量在下次保存时归正,后者让线上坏数据立即可用、无需用户重填。deploy/agent.sh 新增 upstreams(逐账号掩码/冷却/今日负载,掩码为空显式标红)与 upstream-test <slot>(调测试接口并打厂商真实响应,不靠管理台按钮)两个排障子命令。回归 281 条全绿(网关 102 + LLM 179)。
ipass-1.0.16 /api/v1/me 聚合能力目录(upstreams + apix 一处拿全)。commit 479024c,详见 docs/plugin/ME_CAPABILITY_CATALOG.md。
ipass-1.0.17 备份路径迁 ~/ipass/backup/ + 删 rollback-* 本地标签。commit 6b8d694。
ipass-1.0.18 运行期统计落盘 / 重启恢复 + 审计口径收口。worker 退出钩子 + 周期落盘(默认 60s)双保险 → data/llm-stats.json;恢复 put-if-absent 跨 worker 幂等。新增统计前缀必须同步 stats_persist::PREFIXES(漏一处 → 该列发版后从 0 起算)。审计改只追加 meta.jsonl(不再复制完整 body),excerpt = 前 100 字节,body_hash = 全文 SHA256 前 16 hex;AUDIT_MAX_BYTES 10GB→1GB。回归 292 条全绿(网关 102 + LLM 190)。commit 16cf68d。
ipass-1.0.19 「上次落盘/恢复」记录移入共享内存(spr:/spd:)—— 1.0.18 把它放在进程内静态量上,落到哪个 worker 报哪个数,「日志里明明发生了 N 次、状态页报 0」踩过两次。commit 1bc316e。
ipass-1.0.20 apix 透传模式 passthrough —— 通用内部 REST 出口。vendor 模式假设单一供应商收口 + 网关拼体,OCR / 文生图 / TTS 这类多端点多 body 的内部服务接不进来。passthrough 走独立 /apixp/ location(不施加 vendor 强约束,方法/请求体/Content-Type 原样透传,含 multipart),上游路径 = base + /apixp/<slug> 之后的 URI 尾部(含 query 由模块拼),Key 可空(内部服务免鉴权)。模型加 mode 字段(默认 vendor,旧数据零迁移);shm payload 4 字段 base\nkey\nasset_id\nmode;handler 校验「路径前缀 vs mode」一致(vendor slug 走 /apixp/ → 404,反之亦然);探测按 mode 分流(vendor POST 预估 / passthrough GET 打上游根);鉴权仍走同一把 sk_ + 配额 + 用量统计(slot 前缀 api/<slug>,passthrough 同样计)。真源 docs/apix/PASSTHROUGH_MODE.md。回归 327 条全绿(网关 102 + LLM 225,§11.6 新增 35 条)。commit 4533db8,digest ff34f7ef…。
ipass-1.0.21 fix(apix): passthrough 新建可空 Key。1.0.20 现场踩坑:upsert 统一要求「基址与密钥」,但 passthrough 设计是 Key 可空(handler 已放行),管理台提交 passthrough + 空 Key 直接 400。修:vendor 必须 base + key 都填;passthrough 仅 base 必填,key 可空。补 2 条断言防回归。commit d05ebfb,digest f1087cf2…。
ipass-1.0.22 feat(apix): usage_hint 字段 —— 让用户 AI 自己知道怎么调。/api/v1/me 把账号能力目录下发给用户 AI 后,AI 必须能自己拼出调用语法(路径尾部 / Content-Type / 字段名 / Swagger)。desc 是中文给运维看的,params 只对 vendor 有意义,对 passthrough 是空数组——AI 拿到后不知怎么调。加 usage_hint 字段:管理员按 OpenAPI 风格填自由文本(截断 1KB),由 /api/v1/me 原样透传给用户 AI。不进 shm(热路径只查 base/key/asset_id/mode,进 shm 占带宽)。真源 docs/apix/PASSTHROUGH_MODE.md §3「/api/v1/me 用法」。commit 26a0f2f,digest 8bb81353…。
ipass-1.0.44 上游账号冷却改为「指数退避 + 真实请求探测」闭环。旧口径按账号 resets 算天锚定重置边界,锚点算错过两次(1.0.14 / 1.0.24),造成「厂商 15:00 重置、网关锁到 18:00」——天锚定计算整体删除,resets 只存不路由。新口径:uac: = <backoff>:<next_probe>:<hard_cap>,到期放一个无绑定真实请求过去探测,2xx 即 clear_cool 回队、仍耗尽则退避翻倍(首轮 ipass_probe_min,默认 60s,30min 封顶无条件回队自愈)。pick_account 自此必须保持纯决策(四个 $llm_* 变量各求值一次),副作用只放 log 阶段。附带修复:探测窗口判定改严格小于(秒级时钟下 >= 会让刚标记的账号在下一请求就被当探测目标,1s 短退避时实际只等了 0.05s,冷却形同虚设)。真源 docs/llm/MULTI_ACCOUNT_ROUTING.md。回归 370 条全绿(网关 108 + LLM 262,新增「探测恢复闭环」剧本)。

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: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"}]}'
# Anthropic 兼容客户端(Claude Code / Claude SDK):base_url 要补 /anthropic 段
export ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn:88/minimax/anthropic
export ANTHROPIC_AUTH_TOKEN=sk_<你的 API Key>     # 发 Authorization: Bearer —— 走网关用它
# SDK 会自己在后面拼 /v1/messages,实际打到 /minimax/anthropic/v1/messages

⚠️ Anthropic 客户端最容易用错的两个变量(Anthropic 官方语义):

变量 发出的请求头 用在哪
ANTHROPIC_AUTH_TOKEN Authorization: Bearer 走网关/代理——本网关认的就是这个
ANTHROPIC_API_KEY x-api-key 直连 Anthropic 官方才用

配成 ANTHROPIC_API_KEY 属于配置偏差:请求仍能过(网关两种头都认,且出站时会把它摘掉、 不会泄漏给上游厂商),但语义不对,别依赖这个行为。BASE_URL 末尾必须带 /anthropic, 漏掉会打到 …/minimax/v1/messages → 厂商侧 404。

不想猜路径就用现成的:管理台「LLM 上游」每行 slot 旁有 OpenAI / Anthropic 两枚 点击复制按钮;或用 Key 调 GET /api/v1/upstreams / GET /api/v1/models, 响应里 base_url(OpenAI 用)与 anthropic_base_url(Anthropic 用)都是拼好的完整地址。

  • 同一把 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(管理台「用量统计」页) 全局合计 + 按账号 + 按上游,每项含今日 / 累计 / 最近调用时间 / token 合计
管理员 GET /api/admin/trend?days=N(管理台「用量统计」页趋势图) 按自然日分桶:全局 / 按账号 / 按 API 组,每种含请求数与入/出 token
账号本人 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 直接显示今日用量

上游账号级负载(多账号路由的「问题发现」视角)

一个上游挂多把 Key 时,管理台「上游」页的密钥 / 负载列逐账号展示:

展示项 含义 数据源(共享内存键)
今日 N 请求 · 入 X / 出 Y tok 该 Key 今日真实转发量与 token 消耗 uda:<slot>:<idx>:<day>
比例条 该 Key 占本上游负载最大 Key 的百分比(谁在扛、有没有偏斜) 同上
14 天迷你趋势 悬停显示近 14 天合计 / 峰值 / 峰值日期 同上 + trend_labels
冷却 徽标 该账号当前处于额度耗尽冷却 uac:<slot>:<idx>
耗尽N 徽标 今日被判额度耗尽并冷却的次数 uex:<slot>:<idx>:<day>
上游级合计 N 把 Key · 今日合计 M 请求 账号负载求和

计数点在 log 阶段(access 阶段的 pick_account 只做决策、不记账——它会因 $llm_target/$llm_auth/$llm_acct 三个变量各触发一次),口径与请求级用量一致: 只算真的转发出去的请求。账号级序列不参与任何转发决策,纯展示。 设计取舍与键布局见 docs/llm/MULTI_ACCOUNT_ROUTING.md §七。

路径拼接(版本段去重)

客户端请求路径会原样接到上游 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 用于模型发现;管理台「上游管理」有「模型」列与「编辑」按钮可直接维护, 支持一次粘贴多行(逗号 / 顿号 / 分号 / 换行都当分隔符)。

一个上游挂多个账号:同一个 slot 可配 accounts[](多把上游 Key + 各自的额度重置周期), 下游 Key 与上游账号粘性绑定、某把耗尽自动切下一把;管理台「密钥 / 负载」列逐 Key 展示 今日请求/token/耗尽次数 + 负载比例条 + 14 天迷你趋势。字段与设计见「数据模型」小节与 docs/llm/MULTI_ACCOUNT_ROUTING.md。

GET /api/v1/upstreams(账号态)与 GET /api/v1/models(upstreams 分组)会给每个可用 上游回两个拼好的完整地址:base_url(OpenAI 客户端直接当 base_url 用)与 anthropic_base_url(Anthropic 客户端直接当 ANTHROPIC_BASE_URL 用),以及 status 健康状态——不必自己关心上游 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 也会自动不带端口。写死任何一种都会在另一种部署下 给出「看着对、打不通」的地址。


15.1 API 代理(外部 API 供应商)

把外部 API 供应商的资产挂到网关下, 与 LLM 代理共用同一把账号 API Key、同一份限流与用量统计——差别只在下游形态: 供应商只有一个收口 POST /api/v1/ai/request,资产靠请求体里的 asset_id 区分。

GET /apix/search?q=nginx                 Authorization: Bearer sk_<本网关签发>
  → access 阶段 ApiProxyHandler(ipass_apix 开关)
      ① 取 URL 第一段                 → slug = search
      ② 查 ukey:<key>                 → 身份 + 配额(与 LLM 同一套)
      ③ 查 ax:<slug>                  → base + 供应商 Key + asset_id(纯内存)
      ④ 放行;GET 被改写成 POST:proxy_method + proxy_set_body $apix_body
         $apix_body 由网关**从 query 拼**(见下);$apix_key 换上供应商 Key
  → 转发到供应商(下游 sk_ 到此为止,绝不带出去)

为什么请求体必须由网关拼:供应商只认一个收口 URL,资产全靠 body 里的 asset_id 区分。 如果让客户端自己带 asset_id,管理员就失去「只暴露免费资产」的控制力。所以 资产选择权留在服务端:slug → asset_id 由管理员在「API 代理」页配置,调用方只能决定 query 参数。

调用方式:/apix/<slug>?<参数>=<值>。参数只能走 query string——转发决策在 access 阶段, 那时请求体还读不到。网关把全部 query 参数原样塞进 call_data(prompt 提到顶层,供应商模型类资产用它当必填), 再 proxy_method POST + proxy_set_body 转成带体请求。例如 GET /apix/search?q=nginx 会向供应商发:

{"asset_id":"searxng-search","call_data":{"q":"nginx"}}

管理台「API 代理」页(/admin/apix.html):

  • 代理列表:每个代理自带该供应商的 基址 / 供应商 Key / asset_id,由管理员在「新建 / 编辑」 弹出卡片里填写。供应商只是被代理方之一,没有「平台级」凭据面板。真 Key 只落在 data/api-proxies.json,列表只显示掩码 ak_***。
  • 每个代理给复制调用地址 / 测试 / 编辑 / 启停 / 删除。停用立刻对调用方表现为 404 (共享内存已摘除,无回源兜底)。「测试」走该供应商的免费预估接口 /api/v1/ai/estimate, 不执行资产、不扣费,顺带把供应商余额 current_balance_usd 带回来。

接口

方法 路径 说明
GET /apix/<slug>?<参数> 账号态:转发到供应商对应资产
GET /api/v1/apix 账号态:列出已启用的代理与调用地址
GET /api/admin/apix 管理:凭据掩码 + 代理列表
POST /api/admin/apix/save 新建 / 更新代理(slug / asset_id / params / enabled)
POST /api/admin/apix/delete 删除代理(调用方立即 404)
POST /api/admin/apix/test 连通性 / 余额探测(内部重定向到 /_apix_probe/<slug>,internal 挡外部直连)

硬约束

  • apix.rs 与 llm.rs 共用下游 sk_ 鉴权与配额;data/api-proxies.json 含供应商真 Key, 敏感级别等同 users.json,不要复制到其他地方。
  • 出站头默认不放行(proxy_pass_request_headers off)+ 抹空 x-api-key/api-key/Authorization, 再显式放行 Host / X-API-Key(=供应商 Key)/ Content-Type。抹空三条是堵漏关键, 漏 Content-Type 会令供应商侧解析失败。
  • shm 键 ax:<slug>,value = base\n供应商Key\nasset_id。写操作必须走 apix::sync_shm (停用 = 删键),否则「面板显示已保存、调用却 404」。

16. 变更记录

  • 2026-09-14 LLM 上游多账号路由 + 账号级负载统计(ipass-1.0.14)

    • 多账号:llm-upstreams.json 的 slot 新增 accounts[](auth / note / resets) 与上游级 exhaust_status / exhaust_markers;顶层单 auth 保留兼容(accounts 为空时合成单账号)。
    • 路由(access 阶段 pick_account):粘性绑定 ukb:<downstream_key> 优先 → 无绑定时 FNV-1a(下游 Key) % 可用数 冷分散 → 绑定账号冷却则跳过重新分散 → 全冷却选最早恢复。 分散解决厂商「单账号 agent 并发上限」,绑定保证同一用户落点固定以命中 prompt/token 缓存。
    • 耗尽检测(log 阶段,双保险):$upstream_status 命中 exhaust_status,或 body filter 流式扫到 exhaust_markers → $llm_acct 定位本次账号 → 写冷却 uac:。
    • 天锚定冷却:边界 = day0 + ceil(已过/窗口)×窗口 且封顶次日 0 点 (MiniMax 5h 窗口、24=5×4+4 → 20:00–24:00 末段只有 4h、随天重置;RESET_DAY_OFFSET_SEC 默认北京时间)。
    • 账号级负载统计(新):uda:<slot>:<idx>:<day>(请求/token)与 uex: (耗尽次数)日桶, 复用内核 usage::bump_day,无数据库、无新进程;计数点只在 log 阶段一次 (pick_account 会被三个变量各触发一次,不能在里面记账)。管理台「上游」页密钥列展示 每把 Key 今日负载 + 比例条 + 14 天迷你趋势 + 冷却/耗尽徽标;view() 附 trend_labels。
    • 回归 279 条全绿(网关 102 + LLM 177,新增 6 条多账号/负载断言);前端以真实 admin.css + upstreams.js 渲染路径做无头浏览器断言(比例条成比例、条块数、悬停日期、无溢出)。
    • 专章:docs/llm/MULTI_ACCOUNT_ROUTING.md(数据模型 / 路由 / 冷却数学 / shm 布局 / 负载统计)。
  • 2026-09-14(续17)「上次落盘」记录移入共享内存(ipass-1.0.19,已发版)

    • 起因:1.0.18 首次线上验证时发现 —— error.log 里明明有 10 次 [stats] 落盘 (来自 6#0 / 18#0 / 23#0 多个 worker),/api/admin/stats/persist 却报 「上次落盘:(本进程还没落过)」。
    • 根因:LAST_DUMP_AT 是每 worker 的进程内静态量。maybe_dump() 挂在记账路径上, 记账每 worker 各算各的 → 「上次落盘时刻」也就每 worker 一份;接口落到没落过盘的 worker 就报 0。与 1.0.18 已修过的 spr:last(上次恢复)是同一类错误。
    • 修法:时刻发布到共享内存 spd:last(publish_dump 取 max;读-改-写无原子性保证、 理论差 ≤1 秒,对状态展示与分钟级节流无影响)。一次解决两件事 —— 上报一致 (所有 worker 报同一份)+ 节流收敛(maybe_dump 新增慢路径查它,把「8 个 worker 各写一遍同一个文件」收敛成「全局每间隔一次」)。快路径仍是原子比较,热路径代价不变。
    • 回归 299 条全绿(网关 102 + LLM 197):新增「状态页报告的上次落盘时刻非空」断言 —— 测试套件开 2 个 worker,正是能暴露该分歧的拓扑。
    • 已知问题(另案):审计容量巡检的 LAST_PURGE_AT / PURGING 同样是每 worker 静态量, 启动时每个 worker 都会 purge(true),理论上可能多删最旧审计目录;影响面仅「留档比上限更少」, 修它需要跨 worker 互斥原语。见 docs/llm/STATS_PERSISTENCE.md §十。
    • 发版:commit 1bc316e → ipass-1.0.19 (digest sha256:8f8a4444…e5ba,job 20260914-201252-3d17,7 步全过)。 线上复验:bash deploy/agent.sh stats-persist 由「(本进程还没落过)」变为真实时刻, 连查 5 次均一致;stats-dump 后时刻更新且任意 worker 立刻可见(读写两向跨 worker 一致)。 本次 1.0.18→1.0.19 也是一次真实发版验证:重启后 restored_keys = 14/14, 发起版前的统计快照完成恢复,没有清零。
    • ⚠️ 两个发版副发现(既有问题,未修): ① 宿主上的控制面 ipass-agent.py 仍是旧版 —— job 日志里还在走「备份到 ~/ipass-data-backup-*.tar.gz」 与「旧镜像留 rollback 标签」,而这两步 1.0.17 已改掉(控制面跑在宿主、不在镜像里,需单独部署)。 ② 容器 TZ = UTC,状态页/审计的时间显示比北京慢 8 小时,且 util::day_id(localtime_r) 让趋势日桶按 UTC 日界(北京 08:00 换日)—— 而冷却窗口用 RESET_DAY_OFFSET_SEC=28800 按北京日。两处口径不一致。要改必须同时处理:设 TZ=Asia/Shanghai 就必须把 RESET_DAY_OFFSET_SEC 归 0,否则双重偏移(改一处必改另一处)。
  • 2026-09-14(续16)统计落盘/恢复 + 审计口径收口(ipass-1.0.18,已发版)

    • 起因:发版后管理台「用量」与「趋势」从 0 重新长起来。根因是这两类数据 (ust:/ums:/utt:/utms:/ud:/udu:/uds:/uda:/uex:/uh:)只活在共享内存, 进程退出即消失;而上游/账号/域名/用户都有 data/*.json 所以不丢 —— 这个反差是定位关键。
    • 方案(不引入数据库):一个 JSON 快照 data/llm-stats.json(与 users.json 同级, 落在宿主卷上)。两个落盘点互补:worker 退出钩子(gateway::exit_process, 覆盖发版 / docker stop / nginx -s quit,零丢失;镜像已声明 STOPSIGNAL SIGQUIT)
      • 记账后按间隔节流落盘(默认 60 秒,覆盖 SIGKILL/OOM/断电)。 启动时 init_process 恢复,put-if-absent → 多 worker 天然幂等、绝不把计数恢复成 N 倍, 也不会覆盖恢复期间新产生的数据;过期键两侧一致地跳过(90 天日桶不因重启续命)。
    • 刻意不持久化:配置类 up:/upa:/upe:/ax:/ukey:/sub:(各有数据文件, 存两份会出现两个真源互相覆盖)、ukb:(粘性,设计上重启即重绑)、内核 st:/rl:/fail:/sess: (重启清零是有意的,多送一点额度好过把用户锁死)。⚠️ 新增统计前缀必须同步白名单,否则该维度发版即清零且不报错。
    • 接口/配置:GET /api/admin/stats/persist(文件状态 + 内存现状 + 上次恢复结果)、 POST /api/admin/stats/dump(强制落一次);指令 ipass_stats_persist <秒>(0=只留退出钩子), 生产 conf 刻意不写(用默认 60,避免旧镜像 unknown directive 起不来)。
    • 顺带修的真 bug:审计 excerpt 双重编码。1.0.18 首版把手工转义(含两侧引号)的结果 塞进 json!() 被二次转义,落盘成 "excerpt":"\"{\\\"model\\\"…",解码后多一层引号, 任何按前缀匹配的消费方都解析不到 → 改为只做 UTF-8 解码、转义交给序列化器。 另确认 body_hash 必须是全文 SHA256(只哈希前 100 字节会因所有请求开头相同而全量碰撞)。
    • 「上次恢复」计数不再放进程内静态量:init_process 每 worker 跑一次、只有第一个 worker 真在写键, 否则接口落到哪个 worker 就报哪个数(运维看到随机值)→ 发布到 shm spr:last (restored==0 不写、已有则累加 + max(total),覆盖 worker 间恢复重叠)。
    • 回归 299 条全绿(网关 102 + LLM 197;【15】段 14 条:间隔压 1 秒 → 快照产出与白名单 → 状态页上次落盘时刻非空 → nginx -s quit → 重启后恢复键数 > 0 且 == 快照键数、 alice 累计用量不变、再打一笔为 +1 而非从 0 重来、趋势日桶仍在、uda: 账号负载仍可读)。
    • 测试踩坑(已写进 CLAUDE.md):本机 safe-delete 钩子在「同一 turn 累计删除 > 50 个文件」后 会静默拦掉后续所有删除(rm -rf 与 python rmtree 同样被拦),导致清不掉上一轮的 llm-stats.json → 被 restore() 灌进本轮(carol 用量 2 变 6、上游健康 unknown 变 ok), 看起来像新功能有 bug,实为测试间状态泄漏。修法:复位用 mv(rename 不算删除); 审计目录残留则改为断言本轮增量 = 0,对历史残留免疫。
    • 新文档:docs/llm/STATS_PERSISTENCE.md(含 runbook)、docs/llm/AUDIT_LOG.md (两者此前被代码注释与 Dockerfile 引用但文件并不存在)。
  • 2026-09-14(续15.5)控制面备份路径 + 审计目录权限 + 去掉本地 rollback 标签(ipass-1.0.17,commit 6b8d694)

    • 备份路径:~/ipass-data-backup-<时间>.tar.gz → ~/ipass/backup/ipass-data-<时间>.tar.gz (ls ~ 不再被一堆备份文件名刷屏)。
    • 审计目录权限:宿主侧首建 audit/ 后显式 chmod 777。agent 以 root 跑,os.makedirs 建的目录属主是 root,而容器内 worker 是 nobody → 写不动,日志刷 [audit] 建日期目录失败 Permission denied、审计整个废掉(实测踩过)。 用 777 而非按 uid chown:宿主 uid 与容器内 nobody(65534) 不一定一致, 且 audit 是 append-only 元数据、无防篡改语义。
    • 去掉「旧镜像在本地打 rollback tag」:镜像动辄 100 MB+,本地磁盘越积越多; 阿里云私仓永远保留所有 tag,回滚 docker pull 即可。更新从 7 步变 6 步, op_rollback 不再自动选本地 rollback-tag,必须显式传 tag(否则报错指引去阿里云拉)。
    • ⚠️ 控制面 deploy/ipass-agent.py 跑在宿主、不在镜像里,改动需单独部署到 .11 —— 否则线上仍是旧逻辑(1.0.19 发版的 job 日志里就是这么暴露的,见下一条)。
  • 2026-09-14(续15.4)/api/v1/me = 能力目录扩展点(ipass-1.0.16,commit dfbfe5c)

    • 拍板:给同事/文档/SDK 展示能力(域名 / LLM 上游 / API 代理)时往 CoreExt::decorate_me 里塞,不要另开 /api/v1/catalog 这类聚合端点(不破坏既有 3 个 v1 端点与老客户端脚本; 一把 key 一个请求拿全身份 + 域名 + 上游 + API 代理 + 用量 + 策略)。
    • decorate_me 签名改为 (&User, port, &mut Value):传 &User 让装饰零额外 shm 查询 就完成权限收敛(upstreams 按 allowed_models 过滤);port 从 Host 头取(不写死, 88 要带端口、443 反代不能带)。
    • 仅文档同步,不动代码:CLAUDE.md(核心机制补第 6 条)+ docs/plugin/PLUGIN_ARCHITECTURE.md (§2.3 子段、§6 纪律第 7 条、§7 已拍板)。
  • 2026-09-14(续15)auth 规范化 + 排障子命令(ipass-1.0.15)

    • 根因:表单 placeholder 写 sk-...,用户照着填了裸 key(无 Bearer ), 转发时原样发 → 上游回 1004。agent.sh upstreams 一打就看出来:deepseek 掩码是 Bearer s...d425(正常),minimax 掩码是 sk-cp-...(无 Bearer ), 完美的对照组。
    • normalize_auth 兜底:plugin-llm 新增,规则「trim 后含空白 → 已完整; 否则补 Bearer 」。两处应用——upsert 写入时归正(下次保存自愈)、 read_upa 读出时归正(让线上坏数据立即可用,无需用户重填)。 兼容 Basic / 自定义 scheme / 前后空格 / 内部含空格的特殊情况(详见 §15 与 docs/llm/MULTI_ACCOUNT_ROUTING.md §10)。
    • agent.sh 加两个排障子命令:upstreams 逐账号打掩码/冷却/今日负载 (掩码为空显式标 **空**——这是发现「只填了裸 key」类问题的关键指示器, 旧镜像的回显脱敏后看不出问题);upstream-test <slot> 调测试接口并打印 厂商真实响应(不靠管理台按钮 OCR 截图)。
    • 回归 281 条全绿(网关 102 + LLM 179,新增 2 条 normalize 断言:裸 key 200 + 靶机实收 Bearer sk-NORM-NO-SCHEME)。
    • 教训:placeholder 写「前缀而不是字面值」会诱导用户漏填必要部分——正确写法是 Bearer sk-… + 表单说明「只填裸 key 也会自动补 Bearer」(已改)。 上游回 1004 / "Please carry the API secret key" 之类的厂商原话比"401"这种 通用状态码更能锁定根因——管理台测试按钮旧版本不回 body,是这个 bug 没被立刻发现 的次因。
  • 2026-09-13(续11)插件化重构(ipass-1.0.12)

    • 单 crate 拆为 workspace:ipass-core(内核)+ plugin-domain / plugin-llm / plugin-apix 三个插件 crate(一律 rlib)+ gateway(唯一 cdylib,产物仍为 libipass_gateway.so)。 指令名、conf、data/*.json 零变化,行为完全等价。
    • 契约:Plugin trait(dispatch_api 不认领返回 None,404 由 gateway 统一发)、 loc::Switch 并集注入、CoreExt 扩展注册表(身份端点的插件数据由 gateway 回填)、 users::on_delete 钩子(删账号连带清理插件键空间)、ctx_index 注入(插件挂请求级状态)。
    • 下行鉴权/配额下沉 core::auth(LLM 与 apix 两条链路共用);记账原语下沉 core::usage, 用量解读归 plugin-llm,apix 记账走同一写入口(slot 带 api/ 前缀);/api/admin/trend 留 gateway。
    • 架构真源:docs/plugin/PLUGIN_ARCHITECTURE.md(as-built)。
  • 2026-09-13(续10)采纳 sso 上游化建议 4 条(ipass-1.0.13,commit ee05b27)

    • User.extra flatten(插件字段透传,存量数据零破坏)+ users::update_extra;
    • state::split_value 改 rposition(payload 内含 0x1f 不再被截断,真 bug);
    • state::iter_prefix_ex(返回 (key, payload, exp),能力补齐)。
    • 评估与撤回记录:docs/plugin/SSO_UPSTREAM_DECISIONS.md (A6-1 密码最短长度 6→8 会破坏测试边界用例,撤回)。
  • 2026-09-13(续9)API 代理去「市场」概念(ipass-1.0.11)

    • 每条代理自带 supplier / base / key,不再有平台级凭据与目录直拉面板; 管理台编辑改弹出卡片(IP.modal),修示例地址拼接。
  • 2026-09-13(续8)修复管理台登录死循环(ipass-1.0.10)

    • 登录页会话探测的 401 被 core.js 通用兜底当作会话过期重定向回登录页,形成自刷新死循环; 将 /api/admin/session 排除出通用 401 兜底。
  • 2026-09-13(续7)新增「API 代理」板块:把外部免费 API 供应商挂到网关下(ipass-1.0.9)

    • 新增 rust/src/apix.rs + 模块:/apix/<slug>?<参数> → 供应商 POST /api/v1/ai/request, 网关从 query 拼体(asset_id 由服务端决定,调用方只能选参数),sk_ 下行 Key 换成供应商 Key 后转发。
    • data/api-proxies.json(含供应商真 Key,等同 users.json 敏感度):base + key + items{slug→asset_id/params/enabled}; shm 写穿 ax:,停用 = 摘键。
    • 6 个 nginx 变量($apix_target/$apix_host/$apix_key/$apix_body/$apix_probe_target/$apix_probe_body), GET 经 proxy_method POST + proxy_set_body 改写成带体请求;探测走 /_apix_probe/<slug>(internal)。
    • 管理台 apix.html + assets/apix.js:每条代理自带供应商凭据、增删启停、复制地址、免费预估测试(弹出卡片填写)。
    • 计费天然并入既有体系:用量按 api/<slug> 归组(与 LLM 上游同片键空间),趋势 / 用量页直接出现。
  • 2026-09-13(续6)管理台图表(用量/token/趋势/按人/按 API 组)+ 单页拆分多页(ipass-1.0.8)

    • 趋势数据源(日桶):ust:/utt: 只有「今日 + 累计」两个数,画不出历史曲线(今日跨天归零、 累计不区分日期)。新增一组键名带日窗 id 的桶 ud:(全局)/ udu:<user>:<day> / uds:<slot>:<day>,value = 请求数:入token:出token,TTL 90 天由共享内存自然淘汰; 读取是按键精确取(get_live),不做前缀扫描,键数增长不拖慢任何热路径。 stats::record(请求)/ stats::add_tokens(token)各写一次同一批键、字段互补。
    • 新增 GET /api/admin/trend?days=N(默认 14、上限 90):返回 {days, labels, total, users, slots}, 每条含 requests/in/out 三条等长数组——图表直接能吃,前端不做二次聚合。 按账号/按上游维度要先有名册(键里带日窗 id 扫不出来),由接口把 users/upstreams 名字传进去; 全 0 的序列标 empty: true,前端不画,避免一堆贴轴死线把图例挤爆。
    • 管理台拆成多页(原 www/admin.html 1100+ 行单文件):login.html + overview / review / domains / users / upstreams / usage 六个页面 + assets/(admin.css + core.js + chart.js + 各页 JS)。每页 <base href="/admin/">,于是挂在 /admin 还是 /admin/x.html 都用同一套相对路径;nginx 侧 location = /admin 仍进总览(保持既有入口与 e2e 断言), location /admin/ alias 到 www/。
    • 图表自己画、不引三方库:管理台是容器里的一把静态文件,引 CDN 等于把可用性押在公网可达性上 (内网部署直接白屏),引本地副本又要把几百 KB 第三方代码塞进镜像。assets/chart.js 不到 200 行, 折线/面积用 SVG、条形用 HTML+CSS(文字对齐交给浏览器比 SVG text 稳)。
    • 展示面:总览 = 卡片(含今日/累计 token)+ 请求数趋势 + token 趋势 + 按账号/按 API 组 Top 8; 用量页 = 区间(7/14/30/90 天)+ 全局/按账号/按 API 组三种趋势视角 + 指标切换(请求数 / 入 token / 出 token / token 合计)+ 两张明细表(新增入/出 token 列)。
    • 回归扩至 227 条断言(网关 102 + LLM 125);bash deploy/agent.sh verify 新增 「趋势接口返回 7 天序列」作为「镜像真的换新」的证据。
  • 2026-09-12(续5)LLM token 计量 + 对话审计日志(ipass-1.0.7)

    • 关键发现:ngx_http_top_body_filter 是 extern 全局符号(ngx_http.c:74),动态模块可直接 FFI 引用注册 body filter —— 推翻"必须写额外 C 模块"的调研结论,token 计量收敛进现有单 .so。
    • token 计量(llm_usage.rs):body filter 透传 SSE 的同时旁路累积尾部 chunk,last_buf 时 解析 usage(OpenAI stream_options.include_usage 尾块 / Anthropic message_delta), log 阶段经 stats::add_tokens 写 utt:/utms: 键;用量接口(admin/自查)增加 tokens 维度。
    • 对话审计(llm_audit.rs):log 阶段把请求体临时文件复制进 audit/(data 兄弟目录)+ meta.jsonl(user/slot/status/token);10 GiB 容量阈值触发式清理,按日期目录从最旧删起。
    • 踩坑:SSE 三件套里的 proxy_request_buffering off 管的是请求体方向,与 SSE 无关, 且与 client_body_in_file_only 互斥(nginx ngx_http_request_body.c:1334 直接短路不落盘) —— LLM location 删掉它后审计才恢复,SSE 流式不受影响(由 proxy_buffering off 保障)。
    • 发版顺序:控制面挂载逻辑在宿主 ipass-agent.py 里 → 先在 .11 跑自更新脚本 (§12.5 update-agent-face.sh)再 agent.sh update ipass-1.0.7,否则新容器缺审计挂载。
    • 测试 207 全绿(LLM 117 + 网关 90;靶机 usage 块用 "usage_probe" 标记门控不破坏 CHUNKS=3 契约)。
    • 落地:ipass-1.0.7(digest 5cd68ec4…,commit 401f9be)。
  • 2026-09-12(续4)管理台布局自适应 + 控制面收敛到 deploy/agent.sh(ipass-1.0.6)

    • 布局自适应:.wrap 去掉 max-width:1180px 居中锁与 margin:0 auto——大屏上原版面只占 中间一小块、右侧大片留白且表格被压窄。改为铺满视口;配套给 .grid-form 限宽 1100px, 否则面板变宽后 auto-fit 的 minmax(160px,1fr) 会把字段摊成十几列、表单被拉散。 1920 视口实测:面板 1872px / 表格 1830px(改造前约 1132px),表单 1100px。
    • 控制面不再手敲 curl:安全策略里「可疑命令即使已加 allow 白名单仍需人工批准」会命中 含 Authorization: Bearer … / . ./.env 的命令 → 每次都弹「凭证授权」,拒绝时还静默无输出 (实测一次 /update 因此根本没发出去,差点误判成服务故障)。新增 deploy/agent.sh: 凭据只从 .env 读,对外全是无凭据子命令(status / update / wait / verify / release / rollback / data / logs),只需放行 Bash(bash deploy/agent.sh:*)。
    • 新增正式环境验收 agent.sh verify:登录线上管理台 → 核对页面新标记 → 读 GET /api/admin/domains 确认 subdomain_rule。只看容器起来是不够的,这条能证「镜像真的换新 + 新代码在跑」。
    • 落地:ipass-1.0.6(digest 96c0e952…,commit 12f20dd)已更新到 .11,7/7 步全过, 回滚点 ipass-1.0.5;agent.sh verify 复验通过(页面 4 个标记 + subdomain_rule 全中)。
    • 踩坑:agent.sh 首跑报 LIVE_PORT…: unbound variable —— 变量后紧跟中文标点会被并进变量名 ($LIVE_PORT( → 变量名 LIVE_PORT(),中文项目高频;改成 ${LIVE_PORT} 并用脚本全量扫过一遍。
  • 2026-09-12(续3)子域名规则固化(i + 8 位随机数 + dm)+ 点击复制 + API 同规则

    • 管理台「新建域名(直接放行)」的子域名改为三段拼装:固定 i + 8 位随机数字输入框(带「换一个」)+ 固定 dm。 随机源用拒绝采样(只接受 < 250 的字节)保证 0–9 等概率;getrandom 不可用时退化为 xorshift、 绝不 panic(panic = "abort" 会打死 worker,见 rust/src/util.rs::rand_digits)。
    • 规则真源收敛到 rust/src/config.rs(ENTERPRISE_ZONE / SUBDOMAIN_PREFIX / SUBDOMAIN_SUFFIX / SUBDOMAIN_RAND_DIGITS / SUBDOMAIN_GEN_ATTEMPTS),由 GET /api/admin/domains 的 subdomain_rule 下发给面板 —— 改后端常量面板自动跟随,避免前后端各写一份而漂移。dm 后缀是硬约束: 企业域名 server 的匹配正则捕获组必须以 dm 结尾,否则域名建出来也匹配不上转发 server(见 §4)。
    • API 侧同规则:POST /api/admin/domains/create 的 subdomain 缺省或空串即自动生成同形态子域名, 撞车自动换号重试(最多 5 次);手填撞车直接报错。管理台提交的是拼好的值,两条路径共用 domains::create_by_admin。
    • 域名列表里点完整域名即复制,且带端口——location.port 跟随当前访问方式(用 :88 打开面板就复制成 i48291376dm.mayishangshu.cn:88);GET /api/admin/domains 的 view() 增加 host 字段供面板渲染。
    • 回归扩至 201 条(网关 90 + LLM 111),bash tests/run.sh all 全绿。网关新增段「【10】管理台建域名 (自动子域名 i+8位+dm)」13 条:规则下发(zone/前缀后缀拼 idm/digits=8)、无 subdomain 自动生成 200 + 形态 ^i[0-9]{8}dm$ + host 形态、空串同样自动、两次随机值不同、列表含刚建域名、手填合规 200、重复手填 400。 另用真实 Chromium 逐项实测:三段同行(非堆叠)、「换一个」生效、非数字过滤(a1b2c3d4e5f6 → 1234)、 点击复制 toast 内容正确。
  • 2026-09-12(续2)上游健康自动标记 + 连通性测试 + 复制地址(ipass-1.0.5)

    • 健康标记在 log 阶段由真实流量自己当探针(uh:<slot>,无需常驻探测进程); 状态码从 $upstream_status 变量读(r->upstream 在上游 finalize 时已置空)。
    • 「测试」按钮经 ngx_http_internal_redirect 复用 LLM 转发链路;URI 必须拷进请求池 (internal_redirect 只浅拷贝 ngx_str_t,栈上 String 返回即悬垂——实测踩坑)。
    • 客户端防错指引进 §15(ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY、/anthropic 段)。
  • 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 失败)。
  • 2026-09-12 .11 实机交付验证 + base_url 端口自适应

    • 在 .11 完成镜像更新(ipass-1.0.0,digest 046a9dd7…):端口 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 全绿。
  • 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 动态模块(取代重构前的实现)

    • 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从重构前实现平移进 Rust, 接口路径、请求/响应格式、data/*.json 字段与口令哈希算法全部保持兼容,前端管理台无需改动。
    • 换掉了「文件是真源、共享内存只是缓存」的语义:共享内存成为运行期真源, 三个表在 fork 前一次性装载,热路径零文件 I/O,miss 不再回源读文件。 写操作全部写穿(shm + 文件),因此审批通过即刻生效,且重启不丢配置。 (动机:旧版随机 Host 未命中场景实测比命中慢 25 倍,且同步文件 I/O 迫使 worker_processes 1。)
    • worker_processes 1 → auto;Nginx 改为自编译 vanilla nginx(自编译是 ngx-rust 模块对运行环境的要求——见 Dockerfile 注释)。
    • 新增 rust/ workspace(crates/{ipass-core, plugin-domain, plugin-llm, plugin-apix} + gateway cdylib)、Dockerfile 两段构建、vendored ngx-rust。
    • 本地回归:tests/gateway/e2e.sh 共 55 条断言(bash tests/run.sh gateway), 覆盖全部接口 + 转发即时生效/失效 + 越权隔离。
  • 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 小时,管理员勾选授予):持有者在申请临时域名时免审直接放行。
    • 新增临时/长期域名区分与审核流:无权限的临时域名、以及全部长期域名进入管理员审核队列。
    • 新增管理台单页(登录、审核队列、全部域名、账号管理),用户态(API Key)与管理态(登录会话)分权。
    • 数据落盘从单个扁平映射 proxy_config.json 迁移为 data/users.json + data/domains.json(原 test / testa 两条映射已迁移为 admin 名下的长期域名)。
    • 转发链路新增:状态与有效期校验、缓存 TTL 按剩余有效期收敛、写操作主动失效缓存。
    • 安全加固:口令加盐迭代哈希、常量时间比较、HttpOnly+SameSite 会话、登录限速、只读挂载、默认拒绝。
  • 2026-09-10 整理

    • 校验规则修正:原先的校验正则误用了 Perl 风格语法(%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%