diff --git a/CLAUDE.md b/CLAUDE.md index d3cfb0d..4b61776 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -160,8 +160,9 @@ POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签 | 位置 | 职责 | | --- | --- | | `rust/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler | -| `rust/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是 `domains.rs` 在 LLM 侧的翻版 | -| `data/llm-upstreams.json` | 上游表(**含真实密钥**);`base` 可带路径,`auth` 是完整的 Authorization 值 | +| `rust/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是 `domains.rs` 在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现 | +| `rust/src/stats.rs` | 用量计数(`ust:` 每账号 / `ums:` 每账号×上游,请求级、只读 shm)与 `overview()` 投影;**唯一写点在 `LlmHandler` 鉴权全通过之后** | +| `data/llm-upstreams.json` | 上游表(**含真实密钥**);`base` 可带路径,`auth` 是完整的 Authorization 值,`models` 仅供模型发现 | | `conf/nginx.conf` | `lm.mayishangshu.cn:18098` server;SSE 三件套 + `proxy_ssl_server_name` | | `users.json` → `allowed_models` | 上游白名单;**空 = 不限**(老数据没有该字段,反序列化即空表) | @@ -186,6 +187,26 @@ POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签 与 `insufficient_quota`。是请求级不是 token 级:SSE 关缓冲透传就拿不到响应体里的 usage, token 计费与零依赖红线冲突,别轻易许诺。 +**模型发现(2026-09-12)**:上游的 `models` 只是**登记清单**。网关本地应答 `/v1/models` +(LLM 域名下,OpenAI `{object:"list",...}` 形状)与 `/api/v1/models`(管理端口,统一响应体 + `base_url`), +**不转发上游**。判断顺序关键:`llm::is_models_probe` 必须在**解析 slot 之前**,否则 `/v1/models` +会被当成 `slot=v1` 直接 404。**绝不按 `model` 字段路由**(同硬约束 3)——模型名与 slot 是两套东西。 + +**用量统计(2026-09-12)**:`stats::record` 只统计**真正转发出去**的请求,401/403/404/429 不计, +所以它在 `check_quota` 之后、`NGX_DECLINED` 之前调用,**挪位置就改变了语义**。与配额计数 `st:` +**刻意分开**(配额宁可多算防滥用,用量要准对账),别想着合并。计数只在 shm(`ust:` 每账号、 +`ums:` 每账号×上游)、重启归零、不落盘——要持久化就得加文件,与红线冲突。 +**删账号必须调 `stats::forget`**:用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上 +(与「删账号必须摘 `ukey:`」同类,只是影响面在报表不在鉴权,最容易漏)。 + +**路径拼接去重(2026-09-12 修复)**:`llm::join_target(base, path)` 在 base 路径段与请求路径开头 +重复时只保留一份——上游 `base` 带 `/v1`、客户端又带 `/v1` 时,少这一步就会拼成 `/v1/v1/...` +→ 上游 **404 且响应体为空**,而网关侧日志一切正常,极难排查。`upstreams::base_url` 对外回显的 +`base_url` 必须同样**保留上游路径**,否则发给客户端的地址本身就错。 + +**账号展示名**:`users.json` 的 `display_name` 是**纯展示字段**(`users::view` 额外回一个 `name` = +展示名优先、空则回落账号名)。**不参与鉴权、不进 `ukey:` payload**,热路径看不到它,别当身份用。 + **HTTPS(可选)**:`conf/tls/*.conf` 被 `conf/nginx.conf` include,空目录 = 没配、不影响启动; 模板 `conf/tls/llm.conf.example`。`compose.yml` 已映射 443。**生产 Dockerfile 必须带 `--with-http_ssl_module`**(2026-09-10 补上,此前没编,443 server 在容器里会起不来); @@ -199,18 +220,26 @@ location 与 80 端口 LLM server 是两份拷贝,改一处记得同步另一 | 全站 401 | `ukey:` 索引没装载 → 看启动日志「已装载 N 个账号 Key」;Key 刚重置则旧 Key 立即失效 | | 某账号一直 403 | `allowed_models` 非空且不含该 slot;记住空表 = 不限 | | 404 但上游明明配了 | `enabled: false` 会被摘除;或手改了 json 没重启(热路径无回源兜底) | +| 上游 404 且**响应体为空** | 上游 `base` 带 `/v1` 而客户端也带 `/v1` → 拼成 `/v1/v1/...`;查 `llm::join_target` 的去重分支 | +| `/v1/models` 反而 404 | `is_models_probe` 的位置错了:**必须在解析 slot 之前**,否则被当成 `slot=v1` | +| 用量一直是 0 | 被拒的请求(401/403/404/429)**不计用量**;或 `stats::record` 被挪出了"鉴权全通过之后" | +| 删了账号还在用量榜上 | 没调 `stats::forget`(清 `ust:` / `ums:` 前缀) | | 流式退化成一次性返回 | `proxy_buffering off` 丢了 | | 上游报 Host / 证书错 | `proxy_set_header Host $llm_host` 或 `proxy_ssl_server_name on` 丢了 | | query 参数丢失 | 变量形式的 `proxy_pass` 不会自动追加 args,靠 `llm::upstream_uri` 拼好 | -**本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)与网关(18090)后跑断言。 +**本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)、LLM 网关(18090) +与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **78 条** + LLM **75 条** +(`bash tests/run.sh all`,期望失败 0)。 `tests/llm/upstream.py` 会把收到的 `path` / `auth` / `host` / `body` 记到 `.run/llm/upstream.log` ——**验证「Key 是否真的被替换」最直接的手段**,只看网关自己的响应是看不出来的。 夹具账号(`tests/llm/fixtures/`,**合成数据**):alice 白名单=`openai`、bob 空白名单=不限、 -carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。run.sh 会自动生成自签证书 + -渲染 443 server(端口 18443)跑 HTTPS 组——前提是本机 nginx 带 `http_ssl_module`, -否则该组自动跳过。**勿复用生产 `data/`。** +carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 **`deepseeklike`**(`base` 自带 `/v1`), +专测**版本段去重**。run.sh 会自动生成自签证书 + 渲染 443 server(端口 18443)跑 HTTPS 组—— +前提是本机 nginx 带 `http_ssl_module`,否则该组自动跳过。**勿复用生产 `data/`。** +夹具重置一律用 **`cp` 覆盖写**(`tests/gateway/fixtures/`、`tests/llm/fixtures/`), +**不要 `rm` 运行目录里的 json**——本机安全钩子会拦 `rm`,残留脏数据会导致大面积假失败。 ## 性能基线(实测,勿凭直觉优化) @@ -315,7 +344,10 @@ docker compose restart # ★ 改完 rust/ 或 conf/ 后必须重启( docker compose logs -f # ---- 开发:本机直接跑(不跑 Docker,改一行 1~2 秒出结果)---- -cd rust && NGINX_BUILD_DIR=/tmp/ngxbuild/nginx-1.30.4/objs cargo build +cd rust && NGINX_SOURCE_DIR=../build/ngxbuild/nginx-1.30.4 \ + NGINX_BUILD_DIR=../build/ngxbuild/nginx-1.30.4/objs \ + LIBCLANG_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib \ + cargo build # 产物:rust/target/debug/libipass_gateway.dylib # 管理台 @@ -337,25 +369,50 @@ curl -s -b /tmp/c.txt https://mdm.mayishangshu.cn:18098/api/admin/domains curl -H "Host: demo.yourdomain.com" http://127.0.0.1/ ``` +### 生产更新(.11):`deploy/update-ipass.sh` + +镜像推到 Aliyun CR 后,在 .11 上跑这一个脚本即可(**不要手写 `docker run` 参数**): + +```bash +bash update-ipass.sh --check # 只体检:打印探测到的容器/端口/数据目录 +bash update-ipass.sh # 前台更新 +bash update-ipass.sh --bg # 后台更新(日志 ~/ipass-update-<时间>.log) +``` + +设计要点(都是踩过坑才这么写的,改脚本时别退回去): + +- **端口/挂载/网络一律从旧容器复刻**,读 `docker inspect` 的 `HostConfig` 而**不是** `docker port` + —— 后者对「已停止/未启动」容器返回空,会让端口静默回落成 18098。 +- **端口映射必须按 `host:container` 去重**:inspect 里同一映射可能同时含 IPv4/IPv6 两项, + 重复 `-p` 直接 `address already in use`。 +- **`--bg` 必须 `setsid` / `start_new_session`**:只 `nohup &` 时,脚本被父进程组回收, + 表现是「删完旧容器就停住,新容器没起来」(数据没事,但服务是断的)。 +- 数据目录 `chown 65534:65534`(worker 是 nobody),否则写穿 JSON 失败。 +- 动手前 `tar` 备份 + 旧镜像打 `rollback-<时间>` 标签,收尾打印回滚命令。 +- 旧容器若是 compose 创建,脚本会提示「已用 docker run 接管」。 + +> 验证脚本本身:本机用 `NAME=ipass-dt HOST_PORT=<高位> DATA_DIR=/tmp/... SKIP_PULL=1` +> 跑一遍即可(`SKIP_PULL=1` 用本地镜像,避免误部署旧 tag)。 + ## 本机验证夹具(改完必跑) 夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。 ```bash -bash tests/run.sh # 全部:域名网关 55 条 + LLM 代理 34 条 +bash tests/run.sh # 全部:域名网关 78 条 + LLM 代理 75 条 bash tests/run.sh gateway # 只跑域名网关 bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游) ``` `run.sh` 干的事:`cargo build` → 把 `tests/*/nginx.conf.in` 渲染成 `tests/.run/*/nginx.conf` (`@MODULE@` / `@REPO@` / `@RUN@` 换成绝对路径)→ 起 nginx(18080 转发 / 18081 靶机 / -18082 管理 / 18090 LLM)→ 跑断言 → 收尾停进程。**期望输出「失败 0」。** +18082 管理 / 18090 LLM / 18091 LLM 管理)→ 跑断言 → 收尾停进程。**期望输出「失败 0」。** | 路径 | 作用 | | --- | --- | | `tests/run.sh` | 统一入口:编译 + 渲染配置 + 起停 + 跑断言 | -| `tests/gateway/e2e.sh` | **55 条断言**:鉴权会话 / 账号 / 申请审核 / 免审 / 越权隔离 / Key 重置 / 清理 | -| `tests/llm/e2e.sh` | **34 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接 / SSE 不缓冲 / 限流 / HTTPS | +| `tests/gateway/e2e.sh` | **78 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / 清理 | +| `tests/llm/e2e.sh` | **75 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** | | `tests/.run/` | 运行目录(渲染出的配置、`data/`、`logs/`、cookie)——**已 gitignore,随时可删** | **两条不许破的线**: @@ -417,6 +474,9 @@ ADMIN_INIT_PASSWORD='<自定>' build/ngxbuild/nginx-1.30.4/objs/nginx \ | 后端是 hostname 却连不上 | `resolver` 是否可达(当前 `223.5.5.5 119.29.29.29`) | | 内网设备用公网 IP 打不开「指向自己」的端口映射 | hairpin 自环:路由器对「目标=发起者自己」的回环处理不通,对**其他**内网机器的映射正常。绕行:经内网代理机 TCP 中转(`:88 → 18098`),外网带 `:88` 访问(详见 readme §12.3) | | 疑似证书问题,但 `conf/tls` 里的证书没过期 | 先 `openssl s_client -servername <域名>` 看浏览器/链路**实际**收到的证书;acme.sh 签发产物在 `~/.acme.sh/`,**与 `conf/tls/` 是两份**,续期后必须拷贝过去再 reload | +| 更新脚本「删完旧容器就停住,新容器没起来」 | 后台方式没真正脱离会话。必须 `setsid` / `start_new_session`,仅 `nohup &` 会被父进程组连带杀掉。数据在 `DATA_DIR` 未受影响,按打印的回滚命令起回来 | +| 更新后端口变了 / 外部访问不通 | 旧容器处于停止态时 `docker port` 返回空 → 端口回落成默认值。要读 `docker inspect` 的 `HostConfig.PortBindings` | +| 更新时报 `address already in use` | 端口参数重复(inspect 里同一映射含 IPv4/IPv6 两项),按 `host:container` 去重 | > 线上日志字段:`logs/access.log` 的 `backend=$proxy_backend_addr` 直接给出命中的后端; > 模块自身的装载/审核/删除动作打在 `logs/error.log`(`[ipass]` / `[api]` 前缀)。 diff --git a/deploy/compose.yml b/deploy/compose.yml new file mode 100644 index 0000000..ef9c1c4 --- /dev/null +++ b/deploy/compose.yml @@ -0,0 +1,22 @@ +# iPass 山海关 生产部署(192.168.1.11) +# +# 前置: +# docker load -i ipass-gateway-2.0.0.tar.gz +# mkdir -p /opt/ipass && tar -xzf ipass-data-2.0.0.tar.gz -C /opt/ipass +# chown -R 65534:65534 /opt/ipass/data # 容器 worker 是 nobody(uid 65534),必须可写 +# +# 启动: +# docker compose -f compose.yml up -d +# +# 数据持久化在宿主机 /opt/ipass/data,容器随便删重建,状态不丢。 +# 升级镜像:load 新 tar 后 `docker compose -f compose.yml up -d --force-recreate`。 +services: + gateway: + image: ipass-gateway:2.0.0 + container_name: ipass-gateway + ports: + - "88:18098" # 路由器 88 → .11:88;管理 mdm / LLM lm / 企业 *.dm 三域名同端口 + # - "80:80" # 如需 *.yourdomain.com 明文转发再放开 + volumes: + - /opt/ipass/data:/usr/local/nginx/data + restart: always diff --git a/deploy/update-ipass.sh b/deploy/update-ipass.sh new file mode 100755 index 0000000..ed584cb --- /dev/null +++ b/deploy/update-ipass.sh @@ -0,0 +1,330 @@ +#!/usr/bin/env bash +# ============================================================================= +# iPass 山海关 —— 一键更新脚本(在 .11 上运行) +# +# 干的事:拉新镜像 → 备份数据 → 删旧容器 → 复用原端口/挂载起新容器 → 自检 +# +# 用法: +# bash update-ipass.sh # 前台跑 +# bash update-ipass.sh --bg # 后台跑(日志落 ~/ipass-update-<时间>.log) +# bash update-ipass.sh --check # 只体检(打印探测结果),不改任何东西 +# +# 私有仓库若未登录,先执行(或带凭据跑): +# docker login crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com +# CR_USER=xxx CR_PASS=yyy bash update-ipass.sh +# +# 可覆盖的环境变量(一般不用动,脚本会自动探测旧容器): +# IMAGE=... 镜像地址 +# NAME=... 容器名 (默认:自动探测含 ipass 的容器,兜底 ipass) +# HOST_PORT=... 宿主机端口 (默认:复用旧容器映射,兜底 18098) +# DATA_DIR=... 持久化目录 (默认:复用旧容器挂载,兜底 ~/ipass/data) +# KEEP_OLD=1|0 是否留存旧镜像做回滚标签(默认 1) +# ============================================================================= +set -euo pipefail + +IMAGE="${IMAGE:-crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:ipass-1.0.0}" +COMPAT_TAG="${COMPAT_TAG:-ipass-gateway:2.0.0}" # 旧 compose 引用的本地名,顺带对齐 +CONTAINER_DATA=/usr/local/nginx/data # 容器内数据目录(镜像内固定) +NAME="${NAME:-}" +HOST_PORT="${HOST_PORT:-}" +DATA_DIR="${DATA_DIR:-}" +KEEP_OLD="${KEEP_OLD:-1}" +TS="$(date +%Y%m%d-%H%M%S)" + +c_ok() { printf '\033[32m✓\033[0m %s\n' "$*"; } +c_warn() { printf '\033[33m!\033[0m %s\n' "$*"; } +c_err() { printf '\033[31m✗\033[0m %s\n' "$*" >&2; } +step() { printf '\n\033[36m==> %s\033[0m\n' "$*"; } + +# ---------------------------------------------------------------- 后台模式 +if [ "${1:-}" = "--bg" ]; then + SELF="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")" + LOG="$HOME/ipass-update-$TS.log" + # 光靠 nohup 不够:非交互 shell(ssh 直接执行、被父进程组回收)会把子进程一起带走。 + # 优先 setsid 开新会话;没有 setsid 就用 python 的 start_new_session;最后才退回 nohup。 + if command -v setsid >/dev/null 2>&1; then + setsid bash "$SELF" >>"$LOG" 2>&1 /dev/null 2>&1; then + BG_PID="$(python3 - "$SELF" "$LOG" <<'PY' +import subprocess, sys +with open(sys.argv[2], "a") as f: + p = subprocess.Popen(["bash", sys.argv[1]], stdout=f, stderr=subprocess.STDOUT, + stdin=subprocess.DEVNULL, start_new_session=True) +print(p.pid) +PY +)" + else + nohup bash "$SELF" >>"$LOG" 2>&1 /dev/null || true + printf '已后台启动,PID %s\n日志:%s\n跟踪:tail -f %s\n' "$BG_PID" "$LOG" "$LOG" + exit 0 +fi +CHECK_ONLY=0 +[ "${1:-}" = "--check" ] && CHECK_ONLY=1 + +# ---------------------------------------------------------------- 选 docker 前缀 +if docker info >/dev/null 2>&1; then + DOCKER="docker" +elif sudo -n docker info >/dev/null 2>&1; then + DOCKER="sudo docker" +else + c_err "当前用户既不能直连 docker,也无法免密 sudo。请用 root 跑,或把用户加入 docker 组。" + exit 1 +fi + +need_root() { if [ "$(id -u)" = "0" ]; then "$@"; else sudo -n "$@"; fi; } + +# ---------------------------------------------------------------- 探测旧容器 +OLD_NAME="" +if [ -n "$NAME" ]; then + OLD_NAME="$NAME" +else + for cand in ipass ipass-gateway; do + if $DOCKER inspect "$cand" >/dev/null 2>&1; then OLD_NAME="$cand"; break; fi + done + if [ -z "$OLD_NAME" ]; then + OLD_NAME="$($DOCKER ps -a --format '{{.Names}}' 2>/dev/null | grep -i ipass | head -1 || true)" + fi + [ -z "$OLD_NAME" ] && OLD_NAME="ipass" +fi +NAME="$OLD_NAME" + +OLD_IMAGE=""; OLD_DATA=""; OLD_NET=""; OLD_COMPOSE=""; MAIN_PORT="" +PORT_ARGS=""; MOUNT_ARGS="" +if $DOCKER inspect "$NAME" >/dev/null 2>&1; then + OLD_IMAGE="$($DOCKER inspect -f '{{.Config.Image}}' "$NAME")" + OLD_DATA="$($DOCKER inspect -f "{{range .Mounts}}{{if eq .Destination \"$CONTAINER_DATA\"}}{{.Source}}{{end}}{{end}}" "$NAME" 2>/dev/null || true)" + # 复用旧容器的全部端口映射(80 / 443 / 18098 等一个都不丢)。 + # 必须读 inspect 的 HostConfig 而不是 `docker port`:后者对「已停止/未启动」的 + # 容器不返回任何映射,会导致端口静默回落到默认值。 + SEEN_PORTS="" + while read -r cport hip hport; do + [ -z "$cport" ] && continue + [ -z "$hport" ] && continue + cport="${cport%%/*}" # 去掉 /tcp 后缀 + case "$hip" in + ""|"-"|"0.0.0.0"|"::") key="$hport:$cport" ;; + *) key="$hip:$hport:$cport" ;; + esac + case " $SEEN_PORTS " in *" $key "*) continue;; esac + SEEN_PORTS="$SEEN_PORTS $key" + PORT_ARGS="$PORT_ARGS -p $key" + [ "$cport" = "18098" ] && MAIN_PORT="$hport" + done < <($DOCKER inspect -f '{{range $p, $b := .HostConfig.PortBindings}}{{range $b}}{{$p}} {{if .HostIp}}{{.HostIp}}{{else}}-{{end}} {{.HostPort}}{{"\n"}}{{end}}{{end}}' "$NAME" 2>/dev/null || true) + # 复用数据目录以外的额外挂载(证书卷等) + while IFS=$'\t' read -r src dst; do + [ -z "$src" ] && continue + [ "$dst" = "$CONTAINER_DATA" ] && continue + MOUNT_ARGS="$MOUNT_ARGS -v $src:$dst" + done < <($DOCKER inspect -f '{{range .Mounts}}{{.Source}}{{"\t"}}{{.Destination}}{{"\n"}}{{end}}' "$NAME" 2>/dev/null || true) + OLD_NET="$($DOCKER inspect -f '{{.HostConfig.NetworkMode}}' "$NAME" 2>/dev/null || true)" + OLD_COMPOSE="$($DOCKER inspect -f '{{index .Config.Labels "com.docker.compose.project"}}' "$NAME" 2>/dev/null || true)" + c_ok "发现现有容器 $NAME" + printf ' 镜像 %s\n' "$OLD_IMAGE" + printf ' 端口 %s\n' "${PORT_ARGS:-<无映射>}" + printf ' 数据 %s -> %s\n' "${OLD_DATA:-<未挂载>}" "$CONTAINER_DATA" + [ -n "$MOUNT_ARGS" ] && printf ' 附加挂载 %s\n' "$MOUNT_ARGS" + if [ -n "$OLD_COMPOSE" ]; then + c_warn "该容器来自 compose 项目「${OLD_COMPOSE}」;本脚本会用 docker run 直接接管(参数按旧容器复刻)" + c_warn "如想继续用 compose 管理,请改跑:docker compose -f up -d --force-recreate" + fi +else + c_warn "未发现现有容器(首次部署?),走默认参数" +fi + +# ---------------------------------------------------------------- 定端口 +if [ -n "$HOST_PORT" ]; then + PORT_ARGS=" -p $HOST_PORT:18098"; MAIN_PORT="$HOST_PORT" # 显式指定则以它为准 +elif [ -z "$PORT_ARGS" ]; then + PORT_ARGS=" -p 18098:18098"; MAIN_PORT="18098" # 首次部署兜底 +fi + +# ---------------------------------------------------------------- 定数据目录 +if [ -z "$DATA_DIR" ]; then + if [ -n "$OLD_DATA" ]; then + DATA_DIR="$OLD_DATA" # 最安全:原样复用,绝不换地方 + elif [ -f "$HOME/ipass/data/users.json" ] || [ -f "$HOME/ipass/data/domains.json" ]; then + DATA_DIR="$HOME/ipass/data" + elif [ -f "$HOME/ipass/users.json" ] || [ -f "$HOME/ipass/domains.json" ]; then + DATA_DIR="$HOME/ipass" # ~/ipass 本身就是数据目录 + else + DATA_DIR="$HOME/ipass/data" # 全新:按 ~/ipass/data 约定创建 + fi +fi +case "$DATA_DIR" in "~"*) DATA_DIR="$HOME${DATA_DIR#\~}";; esac +_p="$(dirname "$DATA_DIR")"; _b="$(basename "$DATA_DIR")" +[ -d "$_p" ] && DATA_DIR="$(cd "$_p" && pwd)/$_b" # 规范化;父目录不存在则先不动 + +# 附加网络 +NET_ARG="" +[ -n "$OLD_NET" ] && [ "$OLD_NET" != "bridge" ] && [ "$OLD_NET" != "default" ] && NET_ARG=" --network $OLD_NET" + +step "本次部署参数" +printf ' 镜像 %s\n' "$IMAGE" +printf ' 容器名 %s\n' "$NAME" +printf ' 端口 %s\n' "${PORT_ARGS:- -p 18098:18098}" +printf ' 数据目录 %s -> %s\n' "$DATA_DIR" "$CONTAINER_DATA" +printf ' 附加 %s\n' "${NET_ARG:-无}${MOUNT_ARGS:+ $MOUNT_ARGS}" +if [ -n "$OLD_DATA" ] && [ "$DATA_DIR" != "$OLD_DATA" ]; then + c_warn "数据目录与旧容器不一致!如需换地方请手动迁移;不想改就删掉 DATA_DIR=... 覆盖" +fi + +if [ "$CHECK_ONLY" = "1" ]; then + step "体检模式:不动任何东西" + ls -la "$DATA_DIR" 2>/dev/null | head -12 || c_warn "$DATA_DIR 尚不存在" + exit 0 +fi + +# ---------------------------------------------------------------- 1. 拉镜像 +step "1/6 拉取镜像" +pull() { $DOCKER pull "$IMAGE"; } +if [ "${SKIP_PULL:-0}" = "1" ]; then + $DOCKER image inspect "$IMAGE" >/dev/null 2>&1 \ + && c_warn "SKIP_PULL=1:跳过拉取,直接用本地镜像(仅供内网/离线调试)" \ + || { c_err "SKIP_PULL=1 但本地没有 $IMAGE"; exit 1; } +elif ! pull; then + CR_HOST="${IMAGE%%/*}" + if [ -n "${CR_USER:-}" ] && [ -n "${CR_PASS:-}" ]; then + printf '%s' "$CR_PASS" | $DOCKER login "$CR_HOST" -u "$CR_USER" --password-stdin + pull || { c_err "登录后仍拉取失败,检查网络/权限"; exit 1; } + else + c_err "拉取失败(多为私有仓库未登录)。请先执行:" + printf ' docker login %s\n' "$CR_HOST" + printf '或带凭据:CR_USER=xxx CR_PASS=yyy bash %s\n' "$0" + exit 1 + fi +fi +NEW_ID="$($DOCKER image inspect -f '{{.Id}}' "$IMAGE")" +c_ok "已拉取 ${NEW_ID:0:19}" + +# ---------------------------------------------------------------- 2. 备份数据 +step "2/6 备份数据目录" +BACKUP="" +if [ -d "$DATA_DIR" ] && [ -n "$(ls -A "$DATA_DIR" 2>/dev/null || true)" ]; then + BACKUP="$HOME/ipass-data-backup-$TS.tar.gz" + if tar -czf "$BACKUP" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")" 2>/dev/null \ + || need_root tar -czf "$BACKUP" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")"; then + c_ok "已备份到 ${BACKUP}($(du -h "$BACKUP" 2>/dev/null | cut -f1))" + else + c_err "备份失败,中止(不冒数据风险)"; exit 1 + fi +else + c_warn "$DATA_DIR 为空或不存在,跳过备份" +fi + +# ---------------------------------------------------------------- 3. 留旧镜像 +step "3/6 保留旧镜像做回滚" +ROLLBACK_TAG="" +if [ "$KEEP_OLD" = "1" ] && [ -n "$OLD_IMAGE" ] && [ "$OLD_IMAGE" != "$IMAGE" ]; then + if $DOCKER image inspect "$OLD_IMAGE" >/dev/null 2>&1; then + OLD_ID="$($DOCKER image inspect -f '{{.Id}}' "$OLD_IMAGE")" + ROLLBACK_TAG="${COMPAT_TAG%:*}:rollback-$TS" + if $DOCKER tag "$OLD_ID" "$ROLLBACK_TAG" 2>/dev/null; then + c_ok "旧镜像存为 $ROLLBACK_TAG" + else + c_warn "回滚标签创建失败(继续)"; ROLLBACK_TAG="" + fi + fi +else + c_warn "跳过(无旧镜像或不保留)" +fi +$DOCKER tag "$NEW_ID" "$COMPAT_TAG" >/dev/null 2>&1 && c_ok "本地标签 $COMPAT_TAG 已指向新镜像" + +# ---------------------------------------------------------------- 4. 删旧容器 +step "4/6 停止并删除旧容器" +if $DOCKER inspect "$NAME" >/dev/null 2>&1; then + $DOCKER rm -f "$NAME" >/dev/null && c_ok "已删除 $NAME" || { c_err "删除失败"; exit 1; } +else + c_warn "容器 $NAME 不存在,跳过" +fi + +# ---------------------------------------------------------------- 5. 起新容器 +step "5/6 启动新容器" +mkdir -p "$DATA_DIR" +# worker 是 nobody(65534);数据目录必须可写,否则写穿 JSON 会失败 +if ! need_root chown -R 65534:65534 "$DATA_DIR" 2>/dev/null; then + c_warn "chown 65534 失败,退化为 0777(功能可用,权限略宽)" + chmod -R 0777 "$DATA_DIR" 2>/dev/null || true +fi +# 首次部署补种(挂载点会遮住镜像内数据,所以挂到另一个路径去取) +for f in users.json domains.json llm-upstreams.json; do + if [ ! -f "$DATA_DIR/$f" ]; then + c_warn "缺 ${f},从镜像补种" + $DOCKER run --rm --entrypoint sh -v "$DATA_DIR:/seed" "$IMAGE" \ + -c "cp -n $CONTAINER_DATA/$f /seed/ 2>/dev/null || true" >/dev/null 2>&1 || true + fi +done + +# shellcheck disable=SC2086 +if ! $DOCKER run -d \ + --name "$NAME" \ + --restart always \ + $PORT_ARGS \ + -v "$DATA_DIR:$CONTAINER_DATA" \ + $MOUNT_ARGS \ + $NET_ARG \ + "$IMAGE" >/dev/null; then + c_err "新容器启动失败,而旧容器已删除——数据在 $DATA_DIR,未受影响。" + RECOVER="${ROLLBACK_TAG:-${OLD_IMAGE:-$IMAGE}}" + printf '\n先确认端口没被别的进程占着:\n' + printf ' ss -lntp | grep %s # 或 lsof -i :%s\n' "${MAIN_PORT:-18098}" "${MAIN_PORT:-18098}" + printf '\n然后手动起回来(旧镜像):\n' + printf ' %s run -d --name %s --restart always %s -v %s:%s%s%s %s\n' \ + "$DOCKER" "$NAME" "$PORT_ARGS" "$DATA_DIR" "$CONTAINER_DATA" "$MOUNT_ARGS" "$NET_ARG" "$RECOVER" + exit 1 +fi +c_ok "容器已启动:$NAME" + +# ---------------------------------------------------------------- 6. 自检 +step "6/6 自检" +READY=0; CODE="" +for _ in $(seq 1 30); do + CODE="$($DOCKER exec "$NAME" curl -sk -o /dev/null -w '%{http_code}' \ + -H 'Host: mdm.mayishangshu.cn' https://127.0.0.1:18098/api/admin/users 2>/dev/null || true)" + if [ -n "$CODE" ] && [ "$CODE" != "000" ]; then READY=1; break; fi + sleep 1 +done +if [ "$READY" = "1" ]; then + c_ok "服务已就绪(容器内自测 HTTP ${CODE};401 = 模块正常,只是没会话)" +else + c_err "30 秒未就绪,查日志:$DOCKER logs --tail 50 $NAME" +fi + +printf '\n-- nginx 配置语法 --\n' +$DOCKER exec "$NAME" /usr/local/nginx/sbin/nginx -t 2>&1 | sed 's/^/ /' || true + +printf '\n-- 数据状态 --\n' +$DOCKER exec "$NAME" sh -c "ls -l $CONTAINER_DATA/*.json" 2>/dev/null | sed 's/^/ /' || true +UCNT="$($DOCKER exec "$NAME" sh -c "grep -o '\"username\"' $CONTAINER_DATA/users.json 2>/dev/null | wc -l" 2>/dev/null || echo 0)" +printf ' 账号数:%s\n' "${UCNT// /}" + +printf '\n-- 宿主机探活 --\n' +HP="${MAIN_PORT:-18098}" +HCODE="$(curl -sk -o /dev/null -w '%{http_code}' -H 'Host: mdm.mayishangshu.cn' \ + "https://127.0.0.1:$HP/api/admin/users" 2>/dev/null || echo 000)" +if [ "$HCODE" != "000" ]; then + c_ok "https://127.0.0.1:$HP 可达(HTTP ${HCODE})" +else + c_warn "宿主机 $HP 无响应(容器内正常则检查防火墙/映射)" +fi + +cat <} + 启动参数 $PORT_ARGS -v $DATA_DIR:$CONTAINER_DATA$MOUNT_ARGS$NET_ARG + 日志 $DOCKER logs -f $NAME +EOF +if [ -n "$ROLLBACK_TAG" ]; then +cat < `/api/v1/models` 与 LLM 域名下的 `GET /v1/models` 是**同一份数据**、两种形状: +> 前者是网关统一响应体(`{code,msg,data}`,带 `base_url`),后者是 OpenAI SDK 期望的 +> `{object:"list",data:[{id,...}]}`。客户端只认 SDK 时用后面的,自研/管理脚本用前面的。 参数可用 JSON body、form 表单或 query string 传递。 @@ -322,12 +329,13 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains" | 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 | +| 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` | - | 全部域名 + 待审数量 | @@ -335,11 +343,12 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains" | 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` 留空 = 不透传鉴权头(本地免鉴权后端) | +| 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` / `upstreams*`)详见第 15 节。 +> 完整路由表以 `rust/src/api.rs` 的 `route()` 为准(精确匹配,新增接口三步见 CLAUDE.md「硬约定」)。LLM 相关接口(`users/models` / `users/limits` / `users/display` / `upstreams*` / `usage`)详见第 15 节。 --- @@ -351,6 +360,7 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains" { "alice": { "username": "alice", + "display_name": "爱丽丝", "role": "user", "salt": "<随机盐>", "pwd_hash": "<迭代加盐 SHA-256>", @@ -366,11 +376,15 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains" `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)。 -**留空表示不限**;老数据没有该字段,反序列化后即为空表,语义正好也是「不限」。 +`allowed_models` 是 LLM 代理可用的**上游白名单**(取值对应 `llm-upstreams.json` 的 key, +即 URL 第一段 slot,**不是具体模型名**)。**留空表示不限**;老数据没有该字段, +反序列化后即为空表,语义正好也是「不限」。 `llm_rpm` / `llm_daily` 是该账号的 LLM 限流:每分钟请求数 / 每日请求数, `0` 表示**不限**;老数据缺省时取全局默认(`LLM_RPM_DEFAULT=60` / `LLM_DAILY_DEFAULT=0`, @@ -407,13 +421,15 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口 "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", + "base": "https://api.deepseek.com/v1", "auth": "Bearer sk-<上游厂商真实密钥>", + "models": ["deepseek-chat", "deepseek-reasoner"], "enabled": true, "note": "", "created_at": 1789037728 @@ -424,7 +440,12 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口 - 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` 会立即从共享内存摘除,等价于停用(配置保留便于恢复) @@ -461,13 +482,13 @@ cp -a data /path/to/backup/ 夹具在仓库里 `tests/`,**不进 Docker**,直接在本机跑(秒级): ```bash -bash tests/run.sh # 全部:域名网关 55 条 + LLM 代理 34 条 +bash tests/run.sh # 全部:域名网关 78 条 + LLM 代理 75 条 bash tests/run.sh gateway # 只跑域名网关 bash tests/run.sh llm # 只跑 LLM 代理 ``` 脚本会自动 `cargo build`、把 `tests/*/nginx.conf.in` 渲染成带绝对路径的配置、 -起 nginx(18080 转发 / 18081 靶机 / 18082 管理 / 18090 LLM 网关),跑完断言再收尾。 +起 nginx(18080 转发 / 18081 靶机 / 18082 管理 / 18090 LLM 网关 / 18091 LLM 管理),跑完断言再收尾。 状态目录固定为 `tests/.run/*/data/`,**跑回归不会碰 `data/`**。期望输出「失败 0」。 > LLM 侧的关键断言不是看网关的响应码,而是读**假上游实际收到的请求头**—— @@ -505,6 +526,27 @@ nginx -s reload # 只换证书 reload 即可;改 conf/*.conf 或 rust/ 才 `curl -k https://:18098/`(本机网卡)→ `curl -k https://<公网IP>:18098/`(NAT/环回)→ 外部设备真域名(DNS+外网链路)。哪一段先断,问题就在哪一段。 +### 12.4 更新部署(.11 一键脚本) + +`deploy/update-ipass.sh` —— 拷到 .11 上跑,负责「拉新镜像 → 备份数据 → 删旧容器 → +用**原端口/原挂载**起新容器 → 自检」: + +```bash +bash update-ipass.sh --check # 只体检:打印探测到的容器/端口/数据目录,不动任何东西 +bash update-ipass.sh # 前台更新 +bash update-ipass.sh --bg # 后台更新(日志落 ~/ipass-update-<时间>.log) +``` + +- **端口、附加挂载、网络、数据目录全部从旧容器自动复刻**(读 `docker inspect` 的静态配置, + 所以容器处于停止态也能正确识别),不写死任何参数,避免换端口导致外部访问断掉。 +- **持久化目录默认复用旧容器挂载**;全新部署时回落 `~/ipass/data`。可用 `DATA_DIR=` 覆盖。 +- 动手前先 `tar` 备份数据目录到 `~/ipass-data-backup-<时间>.tar.gz`;旧镜像打上 + `ipass-gateway:rollback-<时间>` 标签,结束时打印回滚命令。 +- 数据目录会 `chown 65534:65534`(worker 是 nobody,不这么做写穿 JSON 会失败)。 +- 私有仓库需先 `docker login`(或 `CR_USER=`/`CR_PASS=` 带凭据跑)。 +- 旧容器若由 compose 创建,脚本会提示「已改用 docker run 接管」,想继续用 compose + 请改用 `docker compose -f up -d --force-recreate`。 + --- ## 13. 安全 @@ -566,6 +608,69 @@ curl https://lm.mayishangshu.cn:18098/openai/v1/chat/completions \ - **流式(SSE)原生支持**:`"stream": true` 逐块透传,网关不做缓冲。 - 支持 `?query` 参数、多模态大 body(上限 100MB)、上游 `base` 带路径的网关型上游。 +```bash +# 发现可用模型(用同一把 Key,网关本地应答) +curl -s https://lm.mayishangshu.cn:18098/v1/models \ + -H "Authorization: Bearer sk_<你的 API Key>" +``` + +### 模型发现 + +**一家上游通常挂很多模型**,网关把「谁提供哪些模型」登记在上游配置的 `models` 字段里 +(见「上游配置」)。两处可查,**数据同源、形状不同**: + +| 入口 | 响应形状 | 给谁用 | +| --- | --- | --- | +| `GET https://lm.mayishangshu.cn:18098/v1/models` | OpenAI 规范 `{object:"list",data:[{id,object,owned_by}]}` | OpenAI SDK / 各类现成客户端 | +| `GET <管理端口>/api/v1/models` | 网关统一体 `{code,msg,data:{items,upstreams}}` | 自研客户端、脚本(带 `base_url`,可直接拼请求) | + +- 两者都**按你的白名单过滤**:只列出你有权限使用的上游所登记的模型 +- `id` 即模型名(如 `deepseek-chat`),`owned_by` 是该模型所属的**上游 slot** +- 网关**本地应答、不转发上游**(各家上游的 `/v1/models` 实现不一、有的还要另配鉴权), + 因此结果只反映**配置里登记了什么** +- 模型清单只管「发现」,**不影响转发**:网关仍不解析请求体、不按 `model` 字段路由, + 请求真正去哪儿由 URL 第一段 slot 决定 + +### 用量统计 + +两个视角,**统计的是同一份共享内存计数**: + +| 视角 | 入口 | 内容 | +| --- | --- | --- | +| 管理员 | `GET /api/admin/usage`(管理台「用量统计」Tab) | 全局合计 + 按账号 + 按上游,每项含今日 / 累计 / 最近调用时间 | +| 账号本人 | `GET /api/v1/usage` | 自己的今日 / 累计 / 最近调用 + 分上游明细 + 当前限流 | +| 摘要 | `GET /api/v1/me` 的 `llm_usage` | 一个请求拿到用量摘要,便于客户端自我节流 | + +```bash +curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage" +``` + +口径(**容易和限流混淆,务必看清**): + +- **只统计「真正转发出去」的请求**:鉴权、白名单、限流全部通过之后才 +1。 + 被拒的请求(401 / 403 / 404 / 429)**不计入用量**——它们没产生厂商费用 +- 与配额计数(`st:`,`llm_daily` 判限用)**刻意分开**:配额宁可多算(防滥用),用量要准(对账) +- 同样是**请求级**而非 token 级(原因见「限流与配额」) +- 计数只存共享内存(`ust:` 每账号、`ums:` 每账号×上游),**重启归零**; + 与域名 / Key 等配置不同,用量是运行期指标,不落盘 +- 管理台账号列表另有一列 `llm_today` 直接显示今日用量 + +### 路径拼接(版本段去重) + +客户端请求路径会**原样接到上游 `base` 之后**,但有一处特例容易绊到人: + +| 上游 `base` | 客户端请求 | 实际转发 | +| --- | --- | --- | +| `https://api.deepseek.com` | `/v1/chat/completions` | `https://api.deepseek.com/v1/chat/completions` | +| `https://api.deepseek.com/v1` | `/chat/completions` | `https://api.deepseek.com/v1/chat/completions` | +| `https://api.deepseek.com/v1` | `/v1/chat/completions` | `https://api.deepseek.com/v1/chat/completions`(**去重**) | + +即:当 `base` 的路径段(如 `/v1`)与请求路径开头重复时,**只保留一份**。 +没有这一步,`base` 带 `/v1` 的上游会收到 `/v1/v1/...`,表现为上游 **404 且响应体为空**, +很难从网关侧看出来(网关自己的日志一切正常)。 + +> 因此上游只要是 OpenAI 兼容实现,`base` 带不带 `/v1` **都能用**——这是刻意的兼容设计。 + ### 权限与错误 每个账号有一份**可用上游白名单**(`allowed_models`),管理员在账号管理里指定,**留空 = 不限**。 @@ -613,10 +718,47 @@ curl https://lm.mayishangshu.cn:18098/openai/v1/chat/completions \ 管理员通过 `POST /api/admin/upstreams/save` / `delete` 维护,写入 `data/llm-upstreams.json`, **改动立即生效、无需重启**。字段说明见「数据模型」。 +`models` 用于**模型发现**;管理台「上游管理」有「模型」列与「编辑」按钮可直接维护, +支持一次粘贴多行(逗号 / 顿号 / 分号 / 换行都当分隔符)。 + +`GET /api/v1/upstreams`(账号态)会给每个可用上游回一个 `base_url`,形如 +`https://lm.mayishangshu.cn/<上游路径>`——客户端拿它当 `base_url` 直接拼即可, +不必自己关心上游 `base` 里有没有 `/v1`。 + --- ## 16. 变更记录 +- **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` 通配符证书 @@ -625,7 +767,8 @@ curl https://lm.mayishangshu.cn:18098/openai/v1/chat/completions \ **搬动构建树后必须原地 `./configure && make` 重配**——`objs/Makefile` 里写死了绝对路径, 悬空会导致 `cargo build` 找不到 `pcre.h`(功能参数不变则 `NGX_MODULE_SIGNATURE` 不变,无需重编模块)。 - 回归夹具重置由 `rm` 改为 **`cp` 覆盖写**(新增 `tests/gateway/fixtures/`), - 兼容本机安全钩子;修复 `tests/run.sh all` 收尾未初始化变量。当前 **89 条断言全绿**。 + 兼容本机安全钩子;修复 `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`(每日,默认不限), diff --git a/rust/src/api.rs b/rust/src/api.rs index 2b5c642..1607c27 100644 --- a/rust/src/api.rs +++ b/rust/src/api.rs @@ -24,6 +24,7 @@ use crate::http; use crate::models::User; use crate::session; use crate::state; +use crate::stats; use crate::upstreams; use crate::users; use crate::util; @@ -77,6 +78,7 @@ fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> { ("POST", "/api/admin/users/delete") => (Guard::Admin, h_admin_user_delete), ("POST", "/api/admin/users/models") => (Guard::Admin, h_admin_user_models), ("POST", "/api/admin/users/limits") => (Guard::Admin, h_admin_user_limits), + ("POST", "/api/admin/users/display") => (Guard::Admin, h_admin_user_display), ("GET", "/api/admin/domains") => (Guard::Admin, h_admin_domains), ("POST", "/api/admin/domains/review") => (Guard::Admin, h_admin_domain_review), ("POST", "/api/admin/domains/create") => (Guard::Admin, h_admin_domain_create), @@ -85,7 +87,10 @@ fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> { ("GET", "/api/admin/upstreams") => (Guard::Admin, h_admin_upstreams), ("POST", "/api/admin/upstreams/save") => (Guard::Admin, h_admin_upstream_save), ("POST", "/api/admin/upstreams/delete") => (Guard::Admin, h_admin_upstream_delete), + ("GET", "/api/admin/usage") => (Guard::Admin, h_admin_usage), ("GET", "/api/v1/me") => (Guard::User, h_me), + ("GET", "/api/v1/models") => (Guard::User, h_my_models), + ("GET", "/api/v1/usage") => (Guard::User, h_my_usage), ("GET", "/api/v1/upstreams") => (Guard::User, h_my_upstreams), ("GET", "/api/v1/domains") => (Guard::User, h_my_domains), ("POST", "/api/v1/domains/apply") => (Guard::User, h_apply), @@ -217,24 +222,31 @@ fn h_admin_users(r: *mut ngx_http_request_t, _actor: Actor) -> Status { *counts.entry(d.owner).or_insert(0) += 1; } + let now = util::now(); + // 一次扫表拿到所有人的 LLM 用量(含各自的上游明细),避免逐账号查共享内存 + let usage: HashMap = + stats::all_users(now).into_iter().map(|u| (u.username.clone(), u)).collect(); + let items: Vec = users::all() .iter() .map(|u| { let mut v = users::view(u); + let mut usage_json = json!({ "today": 0, "total": 0, "last_ts": 0, "last_ts_text": "" }); + if let Some(uu) = usage.get(&u.username) { + usage_json = uu.usage.json(); + } if let Value::Object(ref mut m) = v { m.insert( "domain_count".to_owned(), json!(counts.get(&u.username).copied().unwrap_or(0)), ); - // 今日 LLM 用量:读 shm 的日窗计数(与热路径同一数据源) + // 今日 LLM 用量:与热路径同一数据源(共享内存)——注意口径是 + // **已转发**的请求,不含被限流/越权拒掉的那些 m.insert( "llm_today".to_owned(), - json!(state::window_count( - config::KEY_ST_PREFIX, - &u.username, - util::day_id(util::now()) - )), + json!(usage.get(&u.username).map(|x| x.usage.today).unwrap_or(0)), ); + m.insert("llm_usage".to_owned(), usage_json); } v }) @@ -249,14 +261,15 @@ fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status { match users::create( p.get("username").map(String::as_str).unwrap_or(""), + p.get("display_name").map(String::as_str).unwrap_or(""), p.get("password").map(String::as_str).unwrap_or(""), p.get("role").map(String::as_str).unwrap_or("user"), grant_temp, ) { Ok(user) => { util::log_notice(&format!( - "[api] 创建账号 {} role={} temp_grant={grant_temp}", - user.username, user.role + "[api] 创建账号 {} name={} role={} temp_grant={grant_temp}", + user.username, user.display_name, user.role )); http::ok(r, users::view(&user), "账号创建成功") } @@ -264,6 +277,17 @@ fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status { } } +/// 设置展示名(中文姓名等)。传空串 = 清空,前端回落到账号名。 +fn h_admin_user_display(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let p = http::params(r); + let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default(); + + match users::set_display_name(&username, p.get("display_name").map(String::as_str).unwrap_or("")) { + Ok(u) => http::ok(r, users::view(&u), "已更新展示名"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + fn h_admin_user_key(r: *mut ngx_http_request_t, _actor: Actor) -> Status { let p = http::params(r); let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default(); @@ -399,6 +423,8 @@ fn h_me(r: *mut ngx_http_request_t, actor: Actor) -> Status { "domains".to_owned(), json!(domains::view_all(&domains::by_owner(&user.username))), ); + // 用量摘要(明细走 /api/v1/usage)——让客户端一个请求就能决定要不要自我节流 + m.insert("llm_usage".to_owned(), stats::user(&user.username, util::now()).json()); m.insert( "policy".to_owned(), json!({ @@ -493,11 +519,16 @@ fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status { Some(v) => util::to_bool(Some(v)), }; + // models 缺省 = 保持原清单;显式传(哪怕是空串)= 覆盖。 + // 分隔符同时接受换行/逗号/顿号/分号——粘一份厂商文档里的模型列表是常见操作。 + let models = p.get("models").map(|raw| parse_model_list(raw)); + let slot_raw = p.get("slot").map(String::as_str).unwrap_or(""); match upstreams::upsert( slot_raw, p.get("base").map(String::as_str).unwrap_or(""), + models, p.get("auth"), enabled, p.get("note"), @@ -505,13 +536,26 @@ fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status { Ok(up) => { // 用校验后的 slot 回显;直接拿原始入参会把大小写差异带进响应 let slot = upstreams::validate_slot(slot_raw).unwrap_or_default(); - util::log_notice(&format!("[api] 保存 LLM 上游 {slot} enabled={enabled}")); + util::log_notice(&format!( + "[api] 保存 LLM 上游 {slot} enabled={enabled} models={}", + up.models.len() + )); http::ok(r, upstreams::view(&slot, &up), "已保存") } Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), } } +/// 把管理台/接口传入的模型列表串拆成模型名数组。 +/// +/// 允许的写法(混用也认):`a,b` / `a、b` / `a;b` / 一行一个。 +pub fn parse_model_list(raw: &str) -> Vec { + raw.split(|c: char| c == ',' || c == '、' || c == ';' || c == '\n' || c == '\r' || c == '\t') + .map(|s| util::trim(s).to_owned()) + .filter(|s| !s.is_empty()) + .collect() +} + fn h_admin_upstream_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status { let p = http::params(r); match upstreams::remove(p.get("slot").map(String::as_str).unwrap_or("")) { @@ -523,7 +567,18 @@ fn h_admin_upstream_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status } } -/// 设置某账号可用的 LLM 上游白名单。`models` 传空串 = 解除限制。 +/// 管理员:LLM 用量总览(每人 / 每上游 / 合计)。 +/// +/// 口径是**请求数**,且只统计真正转发出去的请求(见 `stats` 模块头注释)。 +/// 想看 token 级用量得改架构(自建 upstream 拦响应体),不在本项目范围。 +fn h_admin_usage(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + http::ok(r, stats::overview(util::now()), "ok") +} + +/// 设置某账号可用的 LLM 上游白名单(`models` 字段 = 上游 slot 列表,传空串 = 解除限制)。 +/// +/// 注意与**上游登记模型清单**(`Upstream.models`)是两件事:这里管"这个账号能用哪几家 +/// 上游",那里管"这家上游提供哪些模型"。白名单按 slot 生效,模型发现再按白名单过滤。 fn h_admin_user_models(r: *mut ngx_http_request_t, _actor: Actor) -> Status { let p = http::params(r); let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default(); @@ -589,30 +644,35 @@ fn h_admin_user_limits(r: *mut ngx_http_request_t, _actor: Actor) -> Status { } } -/// 账号态:看看自己能用哪些上游。 -/// -/// 刻意只回显 slot 与拼接好的 base_url——**不回显任何密钥**(连脱敏都不给, -/// 上游密钥与调用方无关,没有知道的必要)。 -fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::User(user) = actor else { - return http::fail( +/// 账号态接口的公共前置:取账号身份,取不到就回 401。 +fn user_or_401(r: *mut ngx_http_request_t, actor: Actor) -> Result { + match actor { + Actor::User(u) => Ok(u), + _ => Err(http::fail( r, HTTPStatus::UNAUTHORIZED, "API Key 无效或缺失,请在请求头携带 X-API-Key", - ); + )), + } +} + +/// 账号态:看看自己能用哪些上游。 +/// +/// 刻意只回显 slot / base_url / **模型清单**——**不回显任何密钥**(连脱敏都不给, +/// 上游密钥与调用方无关,没有知道的必要)。 +fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let user = match user_or_401(r, actor) { + Ok(u) => u, + Err(e) => return e, }; - let items: Vec = upstreams::all() + let items: Vec = upstreams::available(&user.allowed_models) .into_iter() - .filter(|(slot, up)| { - up.enabled - && (user.allowed_models.is_empty() - || user.allowed_models.iter().any(|s| s == slot)) - }) .map(|(slot, up)| { json!({ "slot": slot, - "base_url": format!("https://llm.yourdomain.com/{slot}"), + "base_url": upstreams::base_url(&slot, &up), + "models": up.models, "note": up.note, }) }) @@ -620,3 +680,83 @@ fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status { http::ok(r, json!({ "items": items }), "ok") } + +/// 账号态:列出自己**可用的模型**(上游登记的模型清单,按白名单过滤)。 +/// +/// 与 LLM 域名下的 `GET /v1/models` 是同一份数据:那边给 OpenAI SDK 用 +/// (形状 `{object:"list",data:[{id,...}]}`),这边给管理/自研客户端用 +/// (形状 `{code,msg,data}`,带 base_url 便于直接拼请求)。 +fn h_my_models(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let user = match user_or_401(r, actor) { + Ok(u) => u, + Err(e) => return e, + }; + + let available = upstreams::available(&user.allowed_models); + let mut items: Vec = Vec::new(); + for (slot, up) in &available { + for model in &up.models { + items.push(json!({ + "model": model, + "slot": slot, + "base_url": upstreams::base_url(slot, up), + "note": up.note, + })); + } + } + + http::ok( + r, + json!({ + "items": items, + "upstreams": available + .iter() + .map(|(slot, up)| json!({ + "slot": slot, + "base_url": upstreams::base_url(slot, up), + "models": up.models, + })) + .collect::>(), + }), + "ok", + ) +} + +/// 账号态:查自己的 LLM 用量(今日 / 累计 / 最近调用 + 分上游明细)。 +fn h_my_usage(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let user = match user_or_401(r, actor) { + Ok(u) => u, + Err(e) => return e, + }; + + let now = util::now(); + let usage = stats::user(&user.username, now); + let models: Vec = stats::user_models(&user.username, now) + .into_iter() + .map(|(slot, u)| { + json!({ + "slot": slot, + "today": u.today, + "total": u.total, + "last_ts": u.last_ts, + "last_ts_text": if u.last_ts > 0 { util::fmt_time(u.last_ts) } else { String::new() }, + }) + }) + .collect(); + + http::ok( + r, + json!({ + "username": user.username, + "display_name": user.display_name, + "today": usage.today, + "total": usage.total, + "last_ts": usage.last_ts, + "last_ts_text": if usage.last_ts > 0 { util::fmt_time(usage.last_ts) } else { String::new() }, + "models": models, + // 限额一起回显:客户端可据此自我节流,不必等 429 + "limits": { "rpm": user.llm_rpm, "daily": user.llm_daily }, + }), + "ok", + ) +} diff --git a/rust/src/config.rs b/rust/src/config.rs index 34eeff9..666186c 100644 --- a/rust/src/config.rs +++ b/rust/src/config.rs @@ -27,6 +27,8 @@ pub const UPSTREAM_SLOT_MAX_LEN: usize = 32; pub const UPSTREAM_BASE_MAX_LEN: usize = 200; pub const USERNAME_MIN_LEN: usize = 2; pub const USERNAME_MAX_LEN: usize = 32; +/// 展示名(中文姓名等)长度上限。按**字符数**算,一个汉字算 1。 +pub const DISPLAY_NAME_MAX_LEN: usize = 32; /// 子域名总长上限:首字符 + 最多 61 个后续字符 pub const SUBDOMAIN_MAX_LEN: usize = 62; @@ -86,6 +88,25 @@ pub const KEY_RL_PREFIX: &[u8] = b"rl:"; /// 键前缀:LLM 每日配额计数。键 = `st:`,value = `<日窗id>:<计数>`。 /// 同时是管理台「今日用量」的数据源。 pub const KEY_ST_PREFIX: &[u8] = b"st:"; +/// 键前缀:LLM **每用户**用量统计(口径 = 已放行的请求)。 +/// +/// 键 = `ust:`,value = `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。 +/// 与 `st:` 的区别:`st:` 是**配额执行**用的计数(先增后判,被拒的请求也计入), +/// 这里统计的是**真的转发出去**的请求——两者在超限时会差几个数,属预期。 +pub const KEY_UST_PREFIX: &[u8] = b"ust:"; +/// 键前缀:LLM **每用户 × 每上游**用量统计。 +/// +/// 键 = `ums::`(username 与 slot 都不含 `:`,切分安全), +/// value 同 `ust:`。管理台的「每个模型用量」就是把这些键按 slot 聚合出来的。 +pub const KEY_UMS_PREFIX: &[u8] = b"ums:"; + +/// LLM 代理对外域名,用于账号态 API 回显 `base_url`。 +/// 改域名只改这里(`conf/nginx.conf` 的 LLM server_name 要同步改)。 +pub const LLM_PUBLIC_HOST: &str = "lm.mayishangshu.cn"; +/// 单个模型名长度上限 +pub const MODEL_NAME_MAX_LEN: usize = 128; +/// 单个上游可登记的模型数量上限(挡住把整个模型库灌进 shm/JSON 的手滑) +pub const UPSTREAM_MODELS_MAX: usize = 200; /// 共享内存 value 内部分隔符(ASCII US)。 /// 后端地址只含 `[A-Za-z0-9._-]` 与 `:`,用户名只含 `[A-Za-z0-9_-]`, /// 都不可能包含该字节,所以切分是安全的。 diff --git a/rust/src/lib.rs b/rust/src/lib.rs index a199ce4..98b48dd 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -45,6 +45,7 @@ mod llm; mod models; mod session; mod state; +mod stats; mod store; mod upstreams; mod util; @@ -268,6 +269,12 @@ impl HttpRequestHandler for LlmHandler { ); }; + // 「列出可用模型」是网关自己的元信息接口(OpenAI 兼容形状), + // 在查上游之前就地应答——否则 `/v1/models` 会被当成 slot=v1 → 404。 + if llm::is_models_probe(r) { + return llm::respond_models(r, &allowed); + } + if state::get_upstream(&slot).is_none() { return llm::fail( r, @@ -295,6 +302,11 @@ impl HttpRequestHandler for LlmHandler { return resp; } + // 用量统计:走到这里说明请求**真的会被转发**,才计入。 + // 被拒的请求(401/403/404/429)不进统计——那是给人看的数字, + // 把拒绝也算进"用量"只会误导(与配额计数 st: 的语义刻意不同)。 + stats::record(&username, &slot, util::now()); + Status::NGX_DECLINED } } diff --git a/rust/src/llm.rs b/rust/src/llm.rs index fefdc37..9174ff8 100644 --- a/rust/src/llm.rs +++ b/rust/src/llm.rs @@ -157,6 +157,46 @@ fn host_of(base: &str) -> &str { } } +/// 拆 base:`https://api.deepseek.com/v1` → `("https://api.deepseek.com", "/v1")` +fn split_origin(base: &str) -> (&str, &str) { + let Some(i) = base.find("://") else { + return (base, ""); + }; + let after = &base[i + 3..]; + match after.find('/') { + Some(j) => (&base[..i + 3 + j], &after[j..]), + None => (base, ""), + } +} + +/// 拼上游完整 URL:`base + 客户端路径(已剥掉 slot)`。 +/// +/// **唯一的例外是版本段重复**:上游 base 自带路径(如 DeepSeek 的 +/// `https://api.deepseek.com/v1`)而客户端路径又正好以同一段开头时, +/// 只保留一份。否则会拼出 `/v1/v1/chat/completions`。 +/// +/// ```text +/// base .../v1 + /v1/chat/completions → .../v1/chat/completions (去重) +/// base .../v1 + /chat/completions → .../v1/chat/completions (照常前缀) +/// base .../llm + /v1/chat/completions → .../llm/v1/chat/completions +/// ``` +/// +/// 这条规则是**实测踩坑换来的**:厂商文档里的 base_url 通常自带 `/v1` +/// (`https://api.deepseek.com/v1`),管理员照抄进 `llm-upstreams.json`, +/// 客户端又按 OpenAI 习惯把 `/v1` 带上 → 上游 404 且**响应体为空**, +/// 从网关侧完全看不出是拼接问题。去重后两种写法都通, +/// base_url 也就能做到「把厂商文档里的 host 换成网关域名」的逐个字符替换。 +fn join_target(base: &str, path: &str) -> String { + let (origin, base_path) = split_origin(base); + if !base_path.is_empty() { + let with_slash = format!("{base_path}/"); + if path == base_path || path.starts_with(&with_slash) { + return format!("{origin}{path}"); + } + } + format!("{base}{path}") +} + // =========================================================================== // 响应 // =========================================================================== @@ -253,6 +293,44 @@ pub unsafe fn check_quota( None } +// =========================================================================== +// 模型发现(本地应答,不去上游) +// =========================================================================== + +/// 是不是"列出模型"请求:`GET /v1/models`(OpenAI SDK 的 `client.models.list()`)。 +/// +/// **必须在查 slot 之前判断**:URL 第一段被当作 slot,`/v1/models` 天然会被 +/// 解析成 `slot=v1` → 「上游不存在」404。这两个路径是本网关自己的元信息接口, +/// 与"某个上游的模型清单"(`GET //v1/models`,照常透传给厂商)互不干扰。 +pub fn is_models_probe(r: *mut ngx_http_request_t) -> bool { + if !crate::http::method_str(r).eq_ignore_ascii_case("GET") { + return false; + } + let uri = crate::http::uri(r); + let uri = uri.trim_end_matches('/'); + uri == "/v1/models" || uri == "/models" +} + +/// 本地应答模型列表,形状与 OpenAI 的 `/v1/models` 一致。 +/// +/// 客户端 SDK 只认这个形状,返回项目自己的 `{code,msg,data}` 会让 SDK +/// 报"无法解析的响应"——与错误体必须 OpenAI 兼容是同一个理由。 +pub fn respond_models(r: *mut ngx_http_request_t, allowed: &[String]) -> Status { + let data: Vec = upstreams::models_flat(allowed) + .into_iter() + .map(|(model, slot)| { + json!({ "id": model, "object": "model", "created": 0, "owned_by": slot }) + }) + .collect(); + + let body = json!({ "object": "list", "data": data }).to_string(); + // 与错误路径同一手法:自己把响应发出去,再把状态码交回 nginx。 + // 注意**不能**返回 NGX_OK——access 阶段的 OK 语义是"放行、继续走 content", + // 那样 `proxy_pass` 照样会执行,客户端拿到模型列表的同时上游被真调一次。 + let _ = crate::http::send(r, HTTPStatus::OK, &body); + Status(HTTPStatus::OK.0 as ngx_int_t) +} + // =========================================================================== // 变量 get_handler // =========================================================================== @@ -299,7 +377,7 @@ pub extern "C" fn var_get( let payload = state::get_upstream(&slot)?; let (base, auth) = upstreams::split_payload(&payload); Some(match data { - VAR_TARGET => format!("{}{}", base, upstream_uri(r)), + VAR_TARGET => join_target(base, &upstream_uri(r)), VAR_HOST => host_of(base).to_owned(), VAR_AUTH => auth.to_owned(), _ => return None, diff --git a/rust/src/models.rs b/rust/src/models.rs index 4b7e9d6..8110313 100644 --- a/rust/src/models.rs +++ b/rust/src/models.rs @@ -16,6 +16,12 @@ pub type UserTable = BTreeMap; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct User { pub username: String, + /// 中文姓名等展示名。**只用于展示**,不参与鉴权、不参与热路径查询。 + /// + /// `username` 规则是 ASCII(`valid_username`),中文名塞不进账号名, + /// 所以「吴桂荣」这类实名单独放这里;留空时前端回落到 `username`。 + #[serde(default)] + pub display_name: String, /// `admin` | `user` pub role: String, pub salt: String, @@ -67,6 +73,14 @@ pub type UpstreamTable = BTreeMap; pub struct Upstream { /// 上游基址,含 scheme,如 `https://api.openai.com`(可带端口) pub base: String, + /// 该上游**挂载的模型名清单**(如 `deepseek-chat` / `deepseek-reasoner`)。 + /// + /// 一个上游(一家厂商)通常挂多个模型,客户端要能先"列出有什么"再选。 + /// 这里只是网关侧的**清单**,用于 `GET /v1/models` 之类的模型发现; + /// 转发本身仍按 URL 里的 slot 走,**不校验 model 字段**(access 阶段读不到 body)。 + /// 留空表示"清单未知"——模型发现接口就不列该上游的模型,但转发照常可用。 + #[serde(default)] + pub models: Vec, /// 完整的 Authorization 头值,如 `Bearer sk-xxx`。 /// 留空表示不透传鉴权头(本地免鉴权后端,如 vLLM / Ollama) #[serde(default)] diff --git a/rust/src/state.rs b/rust/src/state.rs index 497c380..e3d9288 100644 --- a/rust/src/state.rs +++ b/rust/src/state.rs @@ -219,6 +219,29 @@ pub fn clear_prefix(prefix: &[u8]) { } } +/// 遍历某前缀下的全部条目,返回 `(去掉前缀的键名, payload)`。 +/// +/// 这是**低频读**接口(管理台聚合用量统计),不是热路径——每次都会克隆一份 +/// 字符串出来,别拿它做每请求调用。`expires_at` 刻意不返回:统计键永不过期, +/// 调用方用 payload 里的日窗 id 自行判断"今日"。 +pub fn iter_prefix(prefix: &[u8]) -> Vec<(String, String)> { + let Some(root) = root() else { + return Vec::new(); + }; + let guard = root.map.read(); + guard + .iter() + .filter_map(|(k, v)| { + let name = k.as_bytes().strip_prefix(prefix)?; + let (payload, _) = split_value(v.as_bytes())?; + Some(( + String::from_utf8_lossy(name).into_owned(), + String::from_utf8_lossy(payload).into_owned(), + )) + }) + .collect() +} + // =========================================================================== // 业务语义封装 // =========================================================================== diff --git a/rust/src/stats.rs b/rust/src/stats.rs new file mode 100644 index 0000000..38409f0 --- /dev/null +++ b/rust/src/stats.rs @@ -0,0 +1,282 @@ +//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。 +//! +//! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、 +//! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。 +//! +//! ```text +//! ust: → <日窗id>:<今日数>:<累计数>:<最近调用时间戳> +//! ums:: → 同 上 +//! ``` +//! +//! ## 口径:只统计"真的转发出去"的请求 +//! +//! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**, +//! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同—— +//! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义; +//! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。 +//! +//! ## 为什么不做 token 级 +//! +//! token 数在上游响应体里,而 SSE 必须关缓冲透传(`proxy_buffering off`), +//! 网关不缓冲就解析不到 `usage` 字段。要做 token 级计费得自建 upstream +//! 把响应拦下来重组流,与「不引入额外常驻进程 / 不改 nginx 原生转发」冲突。 +//! 因此口径统一为**请求数**,并在文档里写明。 + +use std::collections::BTreeMap; + +use serde_json::{Value, json}; + +use crate::config::{KEY_UMS_PREFIX, KEY_UST_PREFIX}; +use crate::state; +use crate::util; + +/// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。 +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Usage { + /// 今日(本地自然日)请求数 + pub today: i64, + /// 累计请求数(自该计数键建立以来,不随跨天归零) + pub total: i64, + /// 最近一次调用时间戳;0 = 从未调用 + pub last_ts: i64, +} + +impl Usage { + /// 累加(聚合用)。`last_ts` 取最大。 + fn merge(&mut self, other: &Usage) { + self.today += other.today; + self.total += other.total; + if other.last_ts > self.last_ts { + self.last_ts = other.last_ts; + } + } + + pub fn json(&self) -> Value { + json!({ + "today": self.today, + "total": self.total, + "last_ts": self.last_ts, + "last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() }, + }) + } +} + +/// 一个账号的用量 + 其下每个上游的明细 +pub struct UserUsage { + pub username: String, + pub usage: Usage, + pub models: Vec<(String, Usage)>, +} + +/// 一个上游的用量 + 用它的每个账号的明细 +pub struct ModelUsage { + pub slot: String, + pub usage: Usage, + pub users: Vec<(String, Usage)>, +} + +// =========================================================================== +// 编解码 +// =========================================================================== + +/// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。 +/// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。 +fn encode(day: i64, u: &Usage) -> String { + format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts) +} + +/// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。 +fn decode(payload: &str, day: i64) -> Usage { + let mut it = payload.split(':'); + let stored_day = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); + let today = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); + let total = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); + let last_ts = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); + Usage { today: if stored_day == day { today } else { 0 }, total, last_ts } +} + +fn bump(prefix: &[u8], name: &str, day: i64, now: i64) { + let current = state::get(prefix, name.as_bytes()) + .map(|(payload, _)| decode(&payload, day)) + .unwrap_or_default(); + + let next = Usage { + today: current.today + 1, + total: current.total + 1, + last_ts: now, + }; + // 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次), + // 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。 + state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0); +} + +// =========================================================================== +// 写 +// =========================================================================== + +/// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。 +pub fn record(username: &str, slot: &str, now: i64) { + if username.is_empty() || slot.is_empty() { + return; + } + let day = util::day_id(now); + bump(KEY_UST_PREFIX, username, day, now); + bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now); +} + +/// 删除账号时清理其全部用量键(`ust:` 与 `ums::*`)。 +/// +/// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让 +/// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的 +/// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。 +pub fn forget(username: &str) { + if username.is_empty() { + return; + } + state::remove(KEY_UST_PREFIX, username.as_bytes()); + + // 先物化键名再删,避免"遍历中改表" + let prefix = format!("{username}:"); + let keys: Vec = state::iter_prefix(KEY_UMS_PREFIX) + .into_iter() + .map(|(name, _)| name) + .filter(|name| name.starts_with(&prefix)) + .collect(); + for name in keys { + state::remove(KEY_UMS_PREFIX, name.as_bytes()); + } +} + +// =========================================================================== +// 读 +// =========================================================================== + +/// 单账号读数(不含模型明细) +pub fn user(username: &str, now: i64) -> Usage { + let day = util::day_id(now); + state::get(KEY_UST_PREFIX, username.as_bytes()) + .map(|(payload, _)| decode(&payload, day)) + .unwrap_or_default() +} + +/// 单账号 × 上游明细,按 slot 升序 +pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> { + let day = util::day_id(now); + let prefix = format!("{username}:"); + let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX) + .into_iter() + .filter_map(|(name, payload)| { + let slot = name.strip_prefix(&prefix)?.to_owned(); + Some((slot, decode(&payload, day))) + }) + .collect(); + out.sort_by(|a, b| a.0.cmp(&b.0)); + out +} + +/// 全部账号的用量(含各自的模型明细),按账号名升序。 +/// +/// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。 +pub fn all_users(now: i64) -> Vec { + let day = util::day_id(now); + + let mut by_user: BTreeMap> = BTreeMap::new(); + for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { + let Some((username, slot)) = name.split_once(':') else { + continue; + }; + by_user + .entry(username.to_owned()) + .or_default() + .push((slot.to_owned(), decode(&payload, day))); + } + for models in by_user.values_mut() { + models.sort_by(|a, b| a.0.cmp(&b.0)); + } + + state::iter_prefix(KEY_UST_PREFIX) + .into_iter() + .map(|(username, payload)| { + let usage = decode(&payload, day); + let models = by_user.remove(&username).unwrap_or_default(); + UserUsage { username, usage, models } + }) + .collect() +} + +/// 全部上游的用量(含用到它的账号明细),按 slot 升序。 +pub fn all_models(now: i64) -> Vec { + let day = util::day_id(now); + + // slot → (总量, 各账号) + let mut by_slot: BTreeMap)> = BTreeMap::new(); + for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { + let Some((username, slot)) = name.split_once(':') else { + continue; + }; + let u = decode(&payload, day); + let entry = by_slot.entry(slot.to_owned()).or_default(); + entry.0.merge(&u); + entry.1.push((username.to_owned(), u)); + } + + by_slot + .into_iter() + .map(|(slot, (usage, mut users))| { + users.sort_by(|a, b| a.0.cmp(&b.0)); + ModelUsage { slot, usage, users } + }) + .collect() +} + +/// 全局合计 +pub fn totals(now: i64) -> Usage { + let day = util::day_id(now); + let mut sum = Usage::default(); + for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) { + sum.merge(&decode(&payload, day)); + } + sum +} + +/// 管理台用量页的完整投影 +pub fn overview(now: i64) -> Value { + let users: Vec = all_users(now) + .into_iter() + .map(|u| { + json!({ + "username": u.username, + "today": u.usage.today, + "total": u.usage.total, + "last_ts": u.usage.last_ts, + "last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() }, + "models": u.models.iter().map(|(slot, usage)| { + json!({ "slot": slot, "today": usage.today, "total": usage.total }) + }).collect::>(), + }) + }) + .collect(); + + let models: Vec = all_models(now) + .into_iter() + .map(|m| { + json!({ + "slot": m.slot, + "today": m.usage.today, + "total": m.usage.total, + "last_ts": m.usage.last_ts, + "last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() }, + "users": m.users.iter().map(|(name, usage)| { + json!({ "username": name, "today": usage.today, "total": usage.total }) + }).collect::>(), + }) + }) + .collect(); + + let sum = totals(now); + json!({ + "total": sum.json(), + "users": users, + "models": models, + }) +} diff --git a/rust/src/upstreams.rs b/rust/src/upstreams.rs index 9e936eb..b0016e1 100644 --- a/rust/src/upstreams.rs +++ b/rust/src/upstreams.rs @@ -15,7 +15,10 @@ use serde_json::{Value, json}; -use crate::config::{KEY_UP_PREFIX, UPSTREAM_BASE_MAX_LEN, UPSTREAM_SLOT_MAX_LEN}; +use crate::config::{ + KEY_UP_PREFIX, LLM_PUBLIC_HOST, MODEL_NAME_MAX_LEN, UPSTREAM_BASE_MAX_LEN, + UPSTREAM_MODELS_MAX, UPSTREAM_SLOT_MAX_LEN, +}; use crate::models::Upstream; use crate::state; use crate::store; @@ -51,6 +54,34 @@ pub fn validate_slot(raw: &str) -> Result { Ok(s) } +/// 模型名清单:去空白、去空项、去重、限长。 +/// +/// 刻意**允许** `/` `.` `:` 等字符——`Qwen/Qwen2.5-7B`(HF 风格)、 +/// `llama3:8b`(Ollama 标签)都是合法模型名。只挡空白与控制字符, +/// 因为模型名要出现在 URL/JSON/HTML 里,空白只会带来歧义。 +fn check_models(raw: &[String]) -> Result, String> { + let mut out: Vec = Vec::new(); + for item in raw { + let m = util::trim(item); + if m.is_empty() { + continue; + } + if m.chars().count() > MODEL_NAME_MAX_LEN { + return Err(format!("模型名「{m}」超过 {MODEL_NAME_MAX_LEN} 个字符")); + } + if m.chars().any(char::is_whitespace) || m.chars().any(char::is_control) { + return Err(format!("模型名「{m}」不能包含空格或控制字符")); + } + if !out.iter().any(|x| x == m) { + out.push(m.to_owned()); + } + } + if out.len() > UPSTREAM_MODELS_MAX { + return Err(format!("单个上游最多登记 {UPSTREAM_MODELS_MAX} 个模型")); + } + Ok(out) +} + /// 上游基址:必须显式带 `http://` 或 `https://`。 /// /// 比子域名的 `backend`(纯 host:port)宽——LLM 上游常挂在网关路径下 @@ -139,6 +170,55 @@ pub fn get(slot: &str) -> Option { store::read_upstreams().remove(slot) } +/// 某账号**可用**的上游(已启用,且在白名单内;`allowed` 为空 = 不限)。 +/// +/// 账号态接口与模型发现都用它,避免"能看见但不能用"或反之的两套判定。 +pub fn available(allowed: &[String]) -> Vec<(String, Upstream)> { + all() + .into_iter() + .filter(|(slot, up)| { + up.enabled && (allowed.is_empty() || allowed.iter().any(|s| s == slot)) + }) + .collect() +} + +/// 客户端应当使用的 base_url。 +/// +/// 规则:**把上游 base 的 scheme+host 换成网关域名,路径原样保留**—— +/// 这样它才真的能和厂商文档里的 base_url 逐个字符替换: +/// +/// ```text +/// https://api.deepseek.com/v1 → https://lm.mayishangshu.cn/deepseek/v1 +/// https://api.openai.com → https://lm.mayishangshu.cn/openai +/// ``` +/// +/// 反过来(不管上游 base 的路径、一律拼 `/v1`)会让「base 自带 /v1」的上游 +/// 变成 `/v1/v1/chat/completions` → 上游 404,且客户端拿到的是空响应体, +/// 排查起来完全看不出是网关拼错了。**实测踩过,别再改回去。** +pub fn base_url(slot: &str, up: &Upstream) -> String { + let rest = up.base.split("://").nth(1).unwrap_or(""); + let path = match rest.find('/') { + Some(i) => &rest[i..], + None => "", + }; + format!("https://{LLM_PUBLIC_HOST}/{slot}{path}") +} + +/// 模型发现:把可用上游挂载的模型摊平成 `(模型名, slot)` 列表。 +/// +/// 没登记 `models` 的上游不产出任何条目(清单未知 ≠ 有 0 个模型), +/// 但它的转发能力不受影响——模型发现只是"告诉你有什么", +/// 不是"允许你用什么"。 +pub fn models_flat(allowed: &[String]) -> Vec<(String, String)> { + let mut out = Vec::new(); + for (slot, up) in available(allowed) { + for model in &up.models { + out.push((model.clone(), slot.clone())); + } + } + out +} + // =========================================================================== // 写入 // =========================================================================== @@ -146,16 +226,22 @@ pub fn get(slot: &str) -> Option { /// 新增或覆盖一个上游。 /// /// `auth = None` 表示**保持原值**(表单只改 base 时不必回填密钥); -/// `Some("")` 表示显式清空。`enabled = false` 会立刻从共享内存移除。 +/// `Some("")` 表示显式清空。`models = None` 同款语义(保持原清单)。 +/// `enabled = false` 会立刻从共享内存移除。 pub fn upsert( slot_raw: &str, base_raw: &str, + models: Option>, auth_raw: Option<&String>, enabled: bool, note: Option<&String>, ) -> Result { let slot = validate_slot(slot_raw)?; let base = validate_base(base_raw)?; + let models = match models { + Some(list) => Some(check_models(&list)?), + None => None, + }; let key = slot.clone(); let up = store::update_upstreams(move |table| { @@ -170,13 +256,17 @@ pub fn upsert( Some(n) => util::trim(n).to_owned(), None => existing.as_ref().map(|e| e.note.clone()).unwrap_or_default(), }; + let models = match models { + Some(m) => m, + None => existing.as_ref().map(|e| e.models.clone()).unwrap_or_default(), + }; let created_at = existing .as_ref() .map(|e| e.created_at) .filter(|&t| t > 0) .unwrap_or_else(util::now); - let item = Upstream { base, auth, enabled, note, created_at }; + let item = Upstream { base, models, auth, enabled, note, created_at }; table.insert(key.clone(), item.clone()); Ok(item) })?; @@ -213,6 +303,9 @@ pub fn view(slot: &str, up: &Upstream) -> Value { json!({ "slot": slot, "base": up.base, + "base_url": base_url(slot, up), + "models": up.models, + "model_count": up.models.len(), "auth_set": !up.auth.is_empty(), "auth_mask": if up.auth.is_empty() { "-".to_owned() } else { util::mask_key(&up.auth) }, "enabled": up.enabled, diff --git a/rust/src/users.rs b/rust/src/users.rs index d1dc09b..5ea18a3 100644 --- a/rust/src/users.rs +++ b/rust/src/users.rs @@ -15,11 +15,12 @@ use serde_json::{Value, json}; use crate::config::{ - INIT_ADMIN_PASSWORD_DEFAULT, INIT_ADMIN_PASSWORD_ENV, INIT_ADMIN_USER, KEY_UKEY_PREFIX, - PASSWORD_MIN_LEN, TEMP_GRANT_TTL, USERNAME_MAX_LEN, USERNAME_MIN_LEN, + DISPLAY_NAME_MAX_LEN, INIT_ADMIN_PASSWORD_DEFAULT, INIT_ADMIN_PASSWORD_ENV, INIT_ADMIN_USER, + KEY_UKEY_PREFIX, PASSWORD_MIN_LEN, TEMP_GRANT_TTL, USERNAME_MAX_LEN, USERNAME_MIN_LEN, }; use crate::models::{User, UserTable}; use crate::state; +use crate::stats; use crate::store; use crate::util; @@ -36,6 +37,19 @@ fn valid_username(name: &str) -> bool { name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-') } +/// 展示名:允许中文/空格,但**不允许换行或制表等控制字符**—— +/// 它会被塞进管理台 HTML(已转义)与 JSON,控制字符只会造成排版错乱。 +fn check_display_name(raw: &str) -> Result { + let v = util::trim(raw).to_owned(); + if v.chars().count() > DISPLAY_NAME_MAX_LEN { + return Err(format!("展示名不能超过 {DISPLAY_NAME_MAX_LEN} 个字")); + } + if v.chars().any(|c| c.is_control()) { + return Err("展示名不能包含换行或控制字符".to_owned()); + } + Ok(v) +} + // =========================================================================== // 共享内存同步(Key 索引) // =========================================================================== @@ -108,11 +122,18 @@ pub fn find_by_key(key: &str) -> Option { // 写入 // =========================================================================== -fn build_user(username: &str, password: &str, role: &str, grant_temp: bool) -> User { +fn build_user( + username: &str, + display_name: &str, + password: &str, + role: &str, + grant_temp: bool, +) -> User { let salt = util::gen_salt(); let now = util::now(); User { username: username.to_owned(), + display_name: display_name.to_owned(), role: role.to_owned(), pwd_hash: util::hash_password(password, &salt), salt, @@ -137,7 +158,7 @@ pub fn seed_admin() -> Result { if !users.is_empty() { return Ok(()); } - let admin = build_user(INIT_ADMIN_USER, &password, "admin", false); + let admin = build_user(INIT_ADMIN_USER, "", &password, "admin", false); users.insert(admin.username.clone(), admin.clone()); created = Some(admin); Ok(()) @@ -157,6 +178,7 @@ pub fn seed_admin() -> Result { pub fn create( username: &str, + display_name: &str, password: &str, role: &str, grant_temp: bool, @@ -167,6 +189,7 @@ pub fn create( "账号名只能是 {USERNAME_MIN_LEN}-{USERNAME_MAX_LEN} 位字母、数字、下划线或短横线" )); } + let display_name = check_display_name(display_name)?; if password.len() < PASSWORD_MIN_LEN { return Err(format!("密码至少 {PASSWORD_MIN_LEN} 位")); } @@ -177,7 +200,7 @@ pub fn create( return Err(format!("账号 {username} 已存在")); } - let user = build_user(&username, password, role, grant_temp); + let user = build_user(&username, &display_name, password, role, grant_temp); let created = user.clone(); store::update_users(move |users| { if users.contains_key(&username) { @@ -191,6 +214,18 @@ pub fn create( Ok(created) } +/// 设置展示名(中文姓名等)。只影响管理台显示,不碰 Key / 口令 / 白名单。 +pub fn set_display_name(username: &str, display_name: &str) -> Result { + let display_name = check_display_name(display_name)?; + let updated = store::update_users(move |users: &mut UserTable| { + let user = users.get_mut(username).ok_or("账号不存在")?; + user.display_name = display_name; + Ok(user.clone()) + })?; + // 展示名不在 ukey payload 里(热路径不需要它),无需同步共享内存 + Ok(updated) +} + /// 重置 API Key,返回新 Key。 /// /// **必须同时摘掉旧索引**:LLM 热路径查的是 `ukey:`,若只加新的不删旧的, @@ -297,6 +332,7 @@ pub fn delete(username: &str, operator: &str) -> Result<(), String> { return Err("不能删除当前登录的账号".to_owned()); } let username = username.to_owned(); + let stats_name = username.clone(); let removed_key = store::update_users(move |users| { let user = users.get(&username).ok_or("账号不存在")?; @@ -312,6 +348,8 @@ pub fn delete(username: &str, operator: &str) -> Result<(), String> { if !removed_key.is_empty() { state::remove_ukey(&removed_key); } + // 用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上 + stats::forget(&stats_name); Ok(()) } @@ -327,6 +365,9 @@ pub fn view(user: &User) -> Value { json!({ "username": user.username, + "display_name": user.display_name, + // 前端统一用 name 渲染——展示名优先,没有就回落到账号名 + "name": if user.display_name.is_empty() { user.username.clone() } else { user.display_name.clone() }, "role": user.role, "api_key": user.api_key, "api_key_masked": util::mask_key(&user.api_key), diff --git a/tests/README.md b/tests/README.md index 4bce024..73f14f0 100644 --- a/tests/README.md +++ b/tests/README.md @@ -4,8 +4,8 @@ ```bash bash tests/run.sh # 全部(域名网关 + LLM 代理) -bash tests/run.sh gateway # 只跑域名网关(55 条断言) -bash tests/run.sh llm # 只跑 LLM 代理 +bash tests/run.sh gateway # 只跑域名网关(78 条断言) +bash tests/run.sh llm # 只跑 LLM 代理(75 条断言) ``` 脚本会自动 `cargo build`,起 nginx,跑断言,收尾停进程。**期望输出「失败 0」。** @@ -18,10 +18,10 @@ bash tests/run.sh llm # 只跑 LLM 代理 | `gateway/nginx.conf.in` | 域名网关测试配置**模板**(占位符 `@MODULE@` / `@REPO@` / `@RUN@`) | | `gateway/e2e.sh` | **55 条断言**:鉴权会话 / 账号 / 申请审核 / 免审 / 越权隔离 / Key 重置 / 清理 | | `gateway/backend/index.html` | 转发靶机内容(断言里检查 `"from":"backend"`) | -| `llm/nginx.conf.in` | LLM 代理测试配置模板(18090 网关) | -| `llm/upstream.py` | 假上游(18999):**记录它实际收到的 path / auth / host / body** | +| `llm/nginx.conf.in` | LLM 代理测试配置模板(18090 网关 + **18091 管理端口**,供账号态 `/api/v1/*` 断言) | +| `llm/upstream.py` | 假上游(18999):**记录它实际收到的 path / auth / host / body**;`//v1/models` 原样透传 | | `llm/sse_test.py` | 流式探针:输出 `CHUNKS` / `FIRST` / `TOTAL`,判断 SSE 有没有被缓冲 | -| `llm/e2e.sh` | LLM 侧断言:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接 / SSE | +| `llm/e2e.sh` | LLM 侧断言:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / **模型发现** / **账号态用量** / **管理员用量总览与删账号清用量** | | `llm/fixtures/*.json` | 固定账号与上游表(**合成数据**,见下) | | `.run/` | 运行目录(生成的 `nginx.conf`、`data/`、`logs/`、`cookie.jar`)—— 已 gitignore | @@ -47,10 +47,19 @@ sse_test.py → 首块 < 0.5s 到达(证明 proxy_buffering off 生效) ## fixtures 说明 `llm/fixtures/users.json` 与 `llm-upstreams.json` 是**合成夹具**: -`pwd_hash` 是占位、`api_key` 是 `aaaa…` / `bbbb…`、上游 `auth` 是 +`pwd_hash` 多为占位、`api_key` 是 `aaaa…` / `bbbb…`、上游 `auth` 是 `sk-UPSTREAM-REAL-SECRET` 这类明显假值。它们**不是**任何环境的真实凭据, 刻意入库,好让 LLM 侧回归在干净机器上一把跑通。 +两个例外值得知道: + +- `admin` 账号的 `pwd_hash` 是**按项目算法真算出来的**(口令 `123456`)—— + 【10】要真登录管理台才能查用量、删账号。算法见 `rust/src/util.rs::hash_password`: + `x = sha256(salt + ":" + pwd)`,再迭代 1000 轮 `x = sha256(x + salt)`。 + 改口令就照它重算,别写成占位(写错的表现是「登录 401」)。 +- `deepseeklike` 上游的 `base` **自带 `/v1`**,专测**版本段去重** + (少这一步会拼成 `/v1/v1/...` → 上游 404 且响应体为空)。 + 真实凭据只在仓库根的 `data/*.json`(已 gitignore,绝不入库)。 ## 写这类脚本的引号陷阱(曾因此假绿,浪费一轮排查) diff --git a/tests/gateway/e2e.sh b/tests/gateway/e2e.sh index 0804981..bf3f7d1 100755 --- a/tests/gateway/e2e.sh +++ b/tests/gateway/e2e.sh @@ -82,9 +82,11 @@ ck "口令长度不足登录(非管理员路径)→ 401" 401 "$(code -X POST echo echo "【2】账号管理" -BODY=$(jbody username alice password alice123 role user) +BODY=$(jbody username alice password alice123 role user display_name 爱丽丝) CREATE=$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/users/create -H 'Content-Type: application/json' -d "$BODY") ck "创建 alice → 200" 200 "$(echo "$CREATE" | jqv code)" +ck "★展示名(中文姓名)已保存" "爱丽丝" "$(echo "$CREATE" | jqv data.display_name)" +ck " name 回落到展示名" "爱丽丝" "$(echo "$CREATE" | jqv data.name)" ALICE_KEY=$(echo "$CREATE" | jqv data.api_key) if [ -n "${ALICE_KEY:-}" ] && [ "${ALICE_KEY#sk_}" != "$ALICE_KEY" ]; then KEYED=yes; else KEYED=no; fi ck "返回 api_key(sk_ 前缀)" yes "$KEYED" @@ -186,7 +188,56 @@ BODY=$(jbody username bob) ck "删除 bob → 200" 200 "$(code -b "$JAR" -X POST $ADMIN/api/admin/users/delete -H 'Content-Type: application/json' -d "$BODY")" echo -echo "【9】管理端与清理" +echo "【9】LLM 上游多模型 / 模型清单 / 用量" +BODY=$(jbody slot deepseek base https://api.deepseek.com/v1 auth 'Bearer sk-test-not-real' models 'deepseek-chat, deepseek-reasoner' note 测试上游) +UP=$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/upstreams/save -H 'Content-Type: application/json' -d "$BODY") +ck "保存上游(含模型清单)→ 200" 200 "$(echo "$UP" | jqv code)" +ck "★模型清单入库(2 个)" 2 "$(echo "$UP" | jqv data.model_count)" +ck " 上游列表回显模型名" yes \ + "$(curl -s -b "$JAR" $ADMIN/api/admin/upstreams | grep -q deepseek-reasoner && echo yes || echo no)" +ck " base_url 由域名常量拼出(不是写死占位)" "https://lm.mayishangshu.cn/deepseek/v1" "$(echo "$UP" | jqv data.base_url)" + +# 与 auth/note 同款语义:省略 models = 保持原清单 +BODY=$(jbody slot deepseek base https://api.deepseek.com/v1) +ck "★省略 models 保存 → 原清单不被清掉" 2 \ + "$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/upstreams/save -H 'Content-Type: application/json' -d "$BODY" | jqv data.model_count)" +# 显式传空串 = 清空(契约的另一半,必须与"省略"区分开) +BODY=$(jbody slot deepseek base https://api.deepseek.com/v1 models '') +ck "★显式传空 models → 清空" 0 \ + "$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/upstreams/save -H 'Content-Type: application/json' -d "$BODY" | jqv data.model_count)" +# 换行/顿号分隔也能吃(粘贴厂商文档的常见形态)。 +# 注意这里必须用 JSON 的 \n 转义:直接写**字面换行**会让 body 变成非法 JSON, +# 解析失败 → 参数全空 → 断言会因为"上游不存在/400"而假失败。 +BODY=$(jbody slot deepseek base https://api.deepseek.com/v1 models 'deepseek-chat\ndeepseek-reasoner、deepseek-coder') +ck "换行 + 顿号分隔解析出 3 个" 3 \ + "$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/upstreams/save -H 'Content-Type: application/json' -d "$BODY" | jqv data.model_count)" +ck "非法模型名(含空格)→ 400" 400 \ + "$(code -b "$JAR" -X POST $ADMIN/api/admin/upstreams/save -H 'Content-Type: application/json' -d "$(jbody slot deepseek base https://api.deepseek.com/v1 models 'bad model name')")" + +ck "无 Key 查可用模型 → 401" 401 "$(code $ADMIN/api/v1/models)" +ck "alice 查可用模型 → 200" 200 "$(code -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/models)" +ck " 含 deepseek-chat" yes \ + "$(curl -s -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/models | grep -q deepseek-chat && echo yes || echo no)" +ck " 带 OpenAI 口径的 base_url" yes \ + "$(curl -s -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/models | grep -q 'lm.mayishangshu.cn/deepseek/v1' && echo yes || echo no)" +ck "无 Key 查用量 → 401" 401 "$(code $ADMIN/api/v1/usage)" +ck "alice 查用量 → 200" 200 "$(code -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/usage)" +ck " 没调用过 → 累计 0" 0 "$(curl -s -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/usage | jqv data.total)" +ck " 回显限额" yes "$(curl -s -H "X-API-Key: $ALICE_KEY" $ADMIN/api/v1/usage | grep -q limits && echo yes || echo no)" +ck "管理员用量总览 → 200" 200 "$(code -b "$JAR" $ADMIN/api/admin/usage)" +ck " 含 users / models / total 三段" yes \ + "$(curl -s -b "$JAR" $ADMIN/api/admin/usage | grep -q '"models"' && echo yes || echo no)" + +BODY=$(jbody username alice display_name 爱丽丝改名) +D1=$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/users/display -H 'Content-Type: application/json' -d "$BODY") +ck "改展示名 → 200" 200 "$(echo "$D1" | jqv code)" +ck " 新展示名生效" "爱丽丝改名" "$(echo "$D1" | jqv data.display_name)" +BODY=$(jbody username alice display_name '') +ck "清空展示名 → name 回落账号名" alice \ + "$(curl -s -b "$JAR" -X POST $ADMIN/api/admin/users/display -H 'Content-Type: application/json' -d "$BODY" | jqv data.name)" + +echo +echo "【10】管理端与清理" ck "管理台页面 → 200" 200 "$(code -H 'Host: proxy-api.yourdomain.com' $ADMIN/admin)" ck "管理台页面返回 HTML" yes "$(curl -s -H 'Host: proxy-api.yourdomain.com' $ADMIN/admin | grep -qi '/dev/null +} +# 在 stdin 里找子串(命中输出 yes,否则 no) +has() { if grep -q "$1"; then echo yes; else echo no; fi; } +# 反向断言:**不**出现该子串才算过 +nhas() { if grep -q "$1"; then echo no; else echo yes; fi; } + echo "【1】鉴权(OpenAI 兼容错误体)" BODY=$(jbody model gpt-4o) ck "无 Key → 401" 401 "$(code -X POST $GW/openai/v1/chat/completions)" @@ -86,6 +105,14 @@ post "$BOB_KEY" /other/v1/chat/completions "$BODY" >/dev/null ck "★base=/llm + path 正确拼接" "/llm/v1/chat/completions" "$(up_field path)" ck "用的是该上游自己的 Key" "Bearer sk-OTHER-UPSTREAM" "$(up_field auth)" +# ★ 版本段去重(实测踩过的坑:厂商 base_url 自带 /v1,客户端也带 /v1 → /v1/v1 → 上游 404 空响应) +post "$BOB_KEY" /deepseeklike/v1/chat/completions "$BODY" >/dev/null +ck "★base 自带 /v1 + 客户端带 /v1 → 只保留一份" "/v1/chat/completions" "$(up_field path)" +post "$BOB_KEY" /deepseeklike/chat/completions "$BODY" >/dev/null +ck " 客户端不带 /v1 → 照常前缀上 base 的 /v1" "/v1/chat/completions" "$(up_field path)" +post "$BOB_KEY" /deepseeklike/v2/chat/completions "$BODY" >/dev/null +ck " 不同版本段不误判为重复" "/v1/v2/chat/completions" "$(up_field path)" + echo echo "【5】★ 流式(SSE 不被缓冲)" SSE=$(GW="$GW" KEY="$ALICE_KEY" "$PY" "$HERE/sse_test.py" 2>&1) @@ -129,6 +156,92 @@ else echo "【7】HTTPS:跳过(本机 nginx 无 http_ssl_module 或无 openssl)" fi +echo +echo "【8】★ 模型发现(网关本地应答,不去上游)" +M0=$(up_count) +ck "无 Key → 401" 401 "$(code $GW/v1/models)" +ck "alice GET /v1/models → 200" 200 "$(code -H "Authorization: Bearer $ALICE_KEY" $GW/v1/models)" +ck " 形状是 OpenAI 的 object=list" yes \ + "$(curl -s -H "Authorization: Bearer $ALICE_KEY" $GW/v1/models | has '"object":"list"')" +ck " 含白名单内上游的模型 gpt-4o" yes \ + "$(curl -s -H "Authorization: Bearer $ALICE_KEY" $GW/v1/models | has 'gpt-4o')" +ck " 不含白名单外上游的模型 claude-3-5-sonnet" yes \ + "$(curl -s -H "Authorization: Bearer $ALICE_KEY" $GW/v1/models | nhas 'claude-3-5-sonnet')" +ck " 不含已停用上游的模型 should-not-appear" yes \ + "$(curl -s -H "Authorization: Bearer $ALICE_KEY" $GW/v1/models | nhas 'should-not-appear')" +ck "bob(白名单为空=不限)能看到 other 的模型" yes \ + "$(curl -s -H "Authorization: Bearer $BOB_KEY" $GW/v1/models | has 'claude-3-5-sonnet')" +ck "GET /models 同样本地应答 → 200" 200 "$(code -H "Authorization: Bearer $ALICE_KEY" $GW/models)" +ck "★整个模型发现过程 0 次上游调用" 0 "$(( $(up_count) - M0 ))" + +# 带 slot 的 /v1/models 是**另一条路**:照常透传给厂商,取"那家厂商的"模型清单 +N0=$(up_count) +ck "★//v1/models 仍透传上游 → 200" 200 \ + "$(code -H "Authorization: Bearer $ALICE_KEY" $GW/openai/v1/models)" +ck " 上游确实收到了 1 次请求" 1 "$(( $(up_count) - N0 ))" +ck " 转发路径未剥错(/v1/models)" "/v1/models" "$(up_field path)" +ck " 响应体来自上游(不是网关本地那份)" yes \ + "$(curl -s -H "Authorization: Bearer $ALICE_KEY" $GW/openai/v1/models | has 'upstream-model')" + +echo +echo "【9】★ 账号态 API:可用模型 + 自己的用量" +ck "无 Key 查模型 → 401" 401 "$(code $API/api/v1/models)" +ck "无 Key 查用量 → 401" 401 "$(code $API/api/v1/usage)" +ck "alice 查模型 → 200" 200 "$(code -H "X-API-Key: $ALICE_KEY" $API/api/v1/models)" +ck " 模型清单里带 base_url(lm 域名 + slot)" yes \ + "$(curl -s -H "X-API-Key: $ALICE_KEY" $API/api/v1/models | has 'lm.mayishangshu.cn/openai')" +# ★ base_url 必须**保留上游 base 的路径**:openai 的 base 无路径 → 无;other 的 base 带 /llm → 带 /llm。 +# 搞错这一条会让"base 自带 /v1"的上游变成 /v1/v1/... → 上游 404 且响应体为空,极难排查。 +ck "★base_url 不凭空拼 /v1(base 无路径就不带)" yes \ + "$(curl -s -H "X-API-Key: $ALICE_KEY" $API/api/v1/models | nhas 'lm.mayishangshu.cn/openai/')" +ck "★base_url 保留上游 base 的路径 /llm" yes \ + "$(curl -s -H "X-API-Key: $BOB_KEY" $API/api/v1/models | has 'lm.mayishangshu.cn/other/llm')" + +ALICE_USAGE=$(curl -s -H "X-API-Key: $ALICE_KEY" $API/api/v1/usage) +ck "alice 查用量 → 200" 200 "$(code -H "X-API-Key: $ALICE_KEY" $API/api/v1/usage)" +ALICE_TOTAL=$(echo "$ALICE_USAGE" | jqv data.total) +ck "★alice 累计用量 > 0(前面真发过请求)" yes \ + "$(awk -v t="${ALICE_TOTAL:-0}" 'BEGIN{print (t>0)?"yes":"no"}')" +ck " 今日 = 累计(都是刚发的)" "$ALICE_TOTAL" "$(echo "$ALICE_USAGE" | jqv data.today)" +ck " 分上游明细含 openai" yes "$(echo "$ALICE_USAGE" | has '"slot": *"openai"')" +ck "★被拒的越权/未知上游不进明细(无 other/downstream)" yes \ + "$(echo "$ALICE_USAGE" | nhas '"slot": *"other"')" +ck " 回显限额供客户端自我节流" yes "$(echo "$ALICE_USAGE" | has '"limits"')" + +# ★ 关键语义:统计的是"真的转发出去"的请求 —— 超限被 429 的那一发不计 +CAROL_TOTAL=$(curl -s -H "X-API-Key: $CAROL_KEY" $API/api/v1/usage | jqv data.total) +ck "★carol 发了 3 次、第 3 次被限流 → 用量只记 2" 2 "${CAROL_TOTAL:-x}" +DAVE_TOTAL=$(curl -s -H "X-API-Key: $DAVE_KEY" $API/api/v1/usage | jqv data.total) +ck "★dave 同上(每日配额)→ 用量只记 2" 2 "${DAVE_TOTAL:-x}" +ck "bob 的明细含 other(他真调过)" yes \ + "$(curl -s -H "X-API-Key: $BOB_KEY" $API/api/v1/usage | has '"slot": *"other"')" + +echo +echo "【10】管理员用量总览 + 删账号清理用量键" +ck "无会话 → 401" 401 "$(code $API/api/admin/usage)" +ck "不是接口路径 → 404" 404 "$(code $API/api/v1/nope)" + +JAR=$RUN/cookie.jar +LOGIN=$(curl -s -c "$JAR" -X POST $API/api/admin/login -H 'Content-Type: application/json' \ + -d "$(jbody username admin password 123456)") +ck "管理员登录 → 200" 200 "$(echo "$LOGIN" | jqv code)" + +USAGE=$(curl -s -b "$JAR" $API/api/admin/usage) +ck "用量总览含 alice" yes "$(echo "$USAGE" | has '"username": *"alice"')" +ck " 总览含按上游分组(openai)" yes "$(echo "$USAGE" | has '"slot": *"openai"')" +ck " 全局合计 > 0" yes "$(echo "$USAGE" | jqv data.total.total | awk '{print ($1>0)?"yes":"no"}')" +ck "★删除前用量榜里有 bob(他真调过 other)" yes "$(echo "$USAGE" | has '"username": *"bob"')" + +# ★ 删除账号必须**连带清掉用量键**(`ust:` / `ums:`)——它们是按前缀扫出来出报表的, +# 不清就会让已删账号一直挂在用量榜上(与"删账号必须摘 ukey:"同类的正确性问题)。 +curl -s -b "$JAR" -X POST $API/api/admin/users/delete -H 'Content-Type: application/json' \ + -d "$(jbody username bob)" >/dev/null +ck "★bob 已被删除(他的 Key 立即失效 → 401)" 401 "$(code -H "X-API-Key: $BOB_KEY" $API/api/v1/usage)" + +USAGE2=$(curl -s -b "$JAR" $API/api/admin/usage) +ck "★删除后用量榜不再出现 bob" yes "$(echo "$USAGE2" | nhas 'bob')" +ck " 但 alice 仍在榜单上" yes "$(echo "$USAGE2" | has '"username": *"alice"')" + echo echo "============================================================" printf " 通过 \033[32m%d\033[0m 失败 \033[31m%d\033[0m\n" "$pass" "$fail" diff --git a/tests/llm/fixtures/llm-upstreams.json b/tests/llm/fixtures/llm-upstreams.json index 0ae0bc4..13aa3bd 100644 --- a/tests/llm/fixtures/llm-upstreams.json +++ b/tests/llm/fixtures/llm-upstreams.json @@ -1,6 +1,7 @@ { "openai": { "base": "http://127.0.0.1:18999", + "models": ["gpt-4o", "gpt-4o-mini"], "auth": "Bearer sk-UPSTREAM-REAL-SECRET", "enabled": true, "note": "本地靶机;auth 是占位值,不是真密钥", @@ -8,16 +9,26 @@ }, "other": { "base": "http://127.0.0.1:18999/llm", + "models": ["claude-3-5-sonnet"], "auth": "Bearer sk-OTHER-UPSTREAM", "enabled": true, - "note": "不在 alice 白名单内;base 带路径,用于验证路径拼接", + "note": "不在 alice 白名单内;base 带路径,用于验证路径拼接与模型发现过滤", "created_at": 1757500000 }, "downstream": { "base": "http://127.0.0.1:18999", + "models": ["should-not-appear"], "auth": "", "enabled": false, - "note": "已停用,用于验证「停用即从共享内存摘除」→ 404", + "note": "已停用,用于验证「停用即从共享内存摘除」→ 404,且其模型不应出现在模型发现里", + "created_at": 1757500000 + }, + "deepseeklike": { + "base": "http://127.0.0.1:18999/v1", + "models": ["ds-chat"], + "auth": "Bearer sk-DS-REAL", + "enabled": true, + "note": "base 自带 /v1(厂商文档的常见写法),用于验证版本段不重复拼接", "created_at": 1757500000 } } diff --git a/tests/llm/fixtures/users.json b/tests/llm/fixtures/users.json index 288b090..303aa4f 100644 --- a/tests/llm/fixtures/users.json +++ b/tests/llm/fixtures/users.json @@ -1,6 +1,17 @@ { + "admin": { + "username": "admin", + "role": "admin", + "salt": "5a1b2c3d4e5f60718293a4b5c6d7e8f9", + "pwd_hash": "062b45d8f3cbef3d30464859355401bb37193868dc42eb941de86855416ab5e8", + "api_key": "sk_admin_0000000000000000000000000000000000000000000000ab", + "allowed_models": [], + "temp_grant_until": 0, + "created_at": 1757500000 + }, "alice": { "username": "alice", + "display_name": "爱丽丝", "role": "user", "salt": "00112233445566778899aabbccddeeff", "pwd_hash": "00", diff --git a/tests/llm/nginx.conf.in b/tests/llm/nginx.conf.in index f6b2f8a..888f7bc 100644 --- a/tests/llm/nginx.conf.in +++ b/tests/llm/nginx.conf.in @@ -62,4 +62,20 @@ http { proxy_read_timeout 60s; } } + + # ---- 管理 server(只为在同一次回归里验账号态用量/模型接口)---- + # 端口 18091;与生产一样只暴露 /api/,账号态用 X-API-Key 鉴权。 + # 放在这里而不是另起一次 nginx:这样两个接口读的就是**同一块共享内存**, + # 「LLM 请求真的被计入用量」才是被验证到的事实,而不是各自独立的假象。 + server { + listen 18091; + server_name _; + + client_max_body_size 2m; + client_body_buffer_size 1m; + + location /api/ { + ipass_api on; + } + } } diff --git a/tests/llm/upstream.py b/tests/llm/upstream.py index be586d7..5eb2aae 100644 --- a/tests/llm/upstream.py +++ b/tests/llm/upstream.py @@ -21,11 +21,10 @@ PORT = int(os.environ.get("UPSTREAM_PORT", "18999")) class H(BaseHTTPRequestHandler): protocol_version = "HTTP/1.1" - def do_POST(self): - n = int(self.headers.get("Content-Length") or 0) - body = self.rfile.read(n) + def _record(self, body: bytes): rec = { "path": self.path, + "method": self.command, "auth": self.headers.get("Authorization", "-"), "host": self.headers.get("Host", "-"), "body": body.decode("utf-8", "replace"), @@ -33,6 +32,28 @@ class H(BaseHTTPRequestHandler): with open(LOG, "a") as f: f.write(json.dumps(rec, ensure_ascii=False) + "\n") + def do_GET(self): + """`GET //v1/models` 必须原样透传到上游——这里验的就是这条。 + + 网关自己的 `GET /v1/models`(无 slot 段)在本地应答、不会打到这里, + 两条路互不干扰。 + """ + self._record(b"") + payload = json.dumps({ + "object": "list", + "data": [{"id": "upstream-model", "object": "model"}], + }).encode() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(payload))) + self.end_headers() + self.wfile.write(payload) + + def do_POST(self): + n = int(self.headers.get("Content-Length") or 0) + body = self.rfile.read(n) + self._record(body) + if b'"stream"' in body and b"true" in body: self.send_response(200) self.send_header("Content-Type", "text/event-stream") diff --git a/tests/run.sh b/tests/run.sh index 6f29a0d..e55faf5 100755 --- a/tests/run.sh +++ b/tests/run.sh @@ -157,9 +157,11 @@ suite_llm() { echo "LLM 端口未就绪" >&2 ngx_stop "$RUN"; kill "$up_pid" 2>/dev/null; return 1 fi + wait_tcp 127.0.0.1 18091 || { echo "管理端口未就绪" >&2; ngx_stop "$RUN"; kill "$up_pid" 2>/dev/null; return 1; } echo - GW="http://127.0.0.1:18090" UPSTREAM_LOG="$RUN/upstream.log" RUN="$RUN" PY="$PY" HAVE_TLS="$HAVE_TLS" \ + GW="http://127.0.0.1:18090" API="http://127.0.0.1:18091" \ + UPSTREAM_LOG="$RUN/upstream.log" RUN="$RUN" PY="$PY" HAVE_TLS="$HAVE_TLS" \ bash "$HERE/llm/e2e.sh" local rc=$? diff --git a/www/admin.html b/www/admin.html index a1cd8b7..936f035 100644 --- a/www/admin.html +++ b/www/admin.html @@ -156,6 +156,9 @@
可用中
-
账号总数
-
LLM 上游
-
+
今日 LLM 调用
-
+
累计调用
-
+
可用模型
-
@@ -163,6 +166,7 @@ +
@@ -217,7 +221,8 @@

新建账号

每个账号自动生成一个随机 API Key,用于调用申请接口。勾选「临时授权权限」后,该账号申请临时域名可免审核直接放行,权限本身 6 小时后失效。
-
+
+
@@ -236,7 +241,7 @@
API Key 完整值在创建时展示一次;此处可复制或重置。
- +
账号角色API Key临时授权权限域名操作账号角色API KeyLLM 用量临时授权权限域名操作
@@ -247,12 +252,16 @@
+ + + @@ -277,7 +311,7 @@ (function () { "use strict"; - var state = { me: null, users: [], domains: [], upstreams: [], pending: 0 }; + var state = { me: null, users: [], domains: [], upstreams: [], usage: { total: {}, users: [], models: [] }, pending: 0 }; function arr(v) { return Array.isArray(v) ? v : []; } @@ -386,13 +420,18 @@ return Promise.all([ api("GET", "/api/admin/domains"), api("GET", "/api/admin/users"), - api("GET", "/api/admin/upstreams") + api("GET", "/api/admin/upstreams"), + api("GET", "/api/admin/usage").catch(function () { + // 老版本后端没有用量接口时不要让整个面板挂掉 + return { data: { total: {}, users: [], models: [] } }; + }) ]); }).then(function (res) { state.domains = arr(res[0].data.items); state.pending = res[0].data.pending || 0; state.users = arr(res[1].data.items); state.upstreams = arr(res[2].data.items); + state.usage = res[3].data || { total: {}, users: [], models: [] }; render(); }).catch(function (err) { toast(err.message, true); @@ -408,6 +447,20 @@ $("statUsers").textContent = state.users.length; $("statUpstreams").textContent = state.upstreams.length; + var tot = state.usage.total || {}; + $("statLlmtoday").textContent = tot.today || 0; + $("statLlmtotal").textContent = tot.total || 0; + + // 可用模型 = 全部(启用中的)上游登记模型去重后的条数 + var seen = {}; + arr(state.usage.models).forEach(function (m) { seen[m.slot] = true; }); + var distinct = {}; + state.upstreams.forEach(function (u) { + if (!u.enabled) return; + arr(u.models).forEach(function (m) { distinct[m] = true; }); + }); + $("statModels").textContent = Object.keys(distinct).length; + var pill = $("pillPending"); if (state.pending > 0) { pill.hidden = false; pill.textContent = state.pending; } else { pill.hidden = true; } @@ -416,6 +469,51 @@ renderDomains(); renderUsers(); renderUpstreams(); + renderUsage(); + } + + function renderUsage() { + var ub = $("usageUsersBody"); + var rows = arr(state.usage.users); + if (!rows.length) { + ub.innerHTML = '还没有任何 LLM 调用'; + } else { + ub.innerHTML = rows.map(function (u) { + var byModel = arr(u.models).length + ? arr(u.models).map(function (m) { + return "
" + esc(m.slot) + ":" + (m.today || 0) + " / " + (m.total || 0) + "
"; + }).join("") + : "-"; + return "" + + "" + esc(u.username) + "" + + "" + (u.today || 0) + "" + + "" + (u.total || 0) + "" + + "" + esc(u.last_ts_text || "-") + "" + + "" + byModel + "" + + ""; + }).join(""); + } + + var mb = $("usageModelsBody"); + var mrows = arr(state.usage.models); + if (!mrows.length) { + mb.innerHTML = '还没有任何 LLM 调用'; + return; + } + mb.innerHTML = mrows.map(function (m) { + var users = arr(m.users).length + ? arr(m.users).map(function (x) { + return "
" + esc(x.username) + ":" + (x.today || 0) + " / " + (x.total || 0) + "
"; + }).join("") + : "-"; + return "" + + "" + esc(m.slot) + "" + + "" + (m.today || 0) + "" + + "" + (m.total || 0) + "" + + "" + esc(m.last_ts_text || "-") + "" + + "" + users + "" + + ""; + }).join(""); } function renderReview() { @@ -482,7 +580,7 @@ function renderUsers() { var body = $("usersBody"); if (!state.users.length) { - body.innerHTML = '还没有账号'; + body.innerHTML = '还没有账号'; return; } @@ -497,23 +595,29 @@ var models = arr(u.allowed_models); var modelsInfo = models.length - ? "
LLM: " + esc(models.join(", ")) + "
" - : "
LLM: 不限
"; - var limitsInfo = "
LLM 今日 " + (u.llm_today || 0) + " 次 · 限 " + - (u.llm_rpm > 0 ? u.llm_rpm + "/分" : "不限") + " · " + + ? "
上游白名单:" + esc(models.join(", ")) + "
" + : "
上游白名单:不限
"; + + var lu = u.llm_usage || {}; + var usageCell = "" + (lu.today || 0) + " / " + (lu.total || 0) + "" + + "
" + (lu.last_ts_text ? esc(lu.last_ts_text) : "从未调用") + "
" + + "
限 " + (u.llm_rpm > 0 ? u.llm_rpm + "/分" : "不限") + " · " + (u.llm_daily > 0 ? u.llm_daily + "/日" : "不限") + "
"; + var displayName = u.display_name || ""; return "" + - "" + esc(u.username) + "
" + esc(u.created_at_text) + "
" + modelsInfo + limitsInfo + "" + + "" + esc(u.name || u.username) + "
@" + esc(u.username) + " · " + esc(u.created_at_text) + "
" + modelsInfo + "" + "" + (u.role === "admin" ? "管理员" : "普通") + "" + "
" + esc(u.api_key_masked) + "" + "" + "" + "
" + + "" + usageCell + "" + "" + grant + "" + "" + esc(u.domain_count) + "" + "
" + "" + + "" + grantBtn + "" + "" + @@ -526,7 +630,7 @@ var sel = $("cdOwner"); var keep = sel.value; sel.innerHTML = state.users.map(function (u) { - return ""; + return ""; }).join(""); if (keep) sel.value = keep; } @@ -534,7 +638,7 @@ function renderUpstreams() { var body = $("upstreamsBody"); if (!state.upstreams.length) { - body.innerHTML = '还没有配置任何 LLM 上游'; + body.innerHTML = '还没有配置任何 LLM 上游'; return; } @@ -546,14 +650,23 @@ var key = u.auth_set ? "" + esc(u.auth_mask) + "" : "未设置"; + + var models = arr(u.models); + var modelCell = models.length + ? "
" + models.map(esc).join("
") + "
" + : "未登记"; + return "" + "" + esc(u.slot) + "
/" + esc(u.slot) + "/v1/...
" + "" + esc(u.base) + "" + "" + key + "" + + "" + (models.length ? "" + models.length + " 个" + modelCell : modelCell) + "" + "" + esc(u.note || "-") + "" + "" + (enabled ? "启用中" : "已停用") + "" + "" + esc(u.created_at_text) + "" + - "
" + toggle + + "
" + + "" + + toggle + "" + "
" + ""; @@ -595,8 +708,8 @@ var slot = btn.getAttribute("data-slot"); if (act === "toggle-up") { - // 后端约定:save 省略 auth/note 即保留原值,enabled 缺省视为 true—— - // 所以启停必须显式带 enabled,auth/note 一律不传,避免误清密钥 + // 后端约定:save 省略 auth/note/models 即保留原值,enabled 缺省视为 true—— + // 所以启停必须显式带 enabled,其余一律不传,避免误清密钥/模型清单 btn.disabled = true; api("POST", "/api/admin/upstreams/save", { slot: slot, @@ -604,6 +717,16 @@ enabled: btn.getAttribute("data-enabled") === "1" }).then(function (r) { toast(r.msg); return loadAll(); }) .catch(function (err) { toast(err.message, true); btn.disabled = false; }); + } else if (act === "edit-up") { + var up = state.upstreams.filter(function (x) { return x.slot === slot; })[0]; + if (!up) return; + $("upSlot").value = up.slot; + $("upBase").value = up.base; + $("upModels").value = arr(up.models).join(", "); + $("upNote").value = up.note || ""; + $("upAuth").value = ""; + $("upAuth").focus(); + toast("已载入 " + slot + ",改完点「保存上游」;密钥留空表示不改"); } else if (act === "del-up") { if (!confirm("确认删除上游 " + slot + "?删除后指向它的调用将立即 404。")) return; btn.disabled = true; @@ -643,6 +766,11 @@ var pwd = prompt("为账号 " + user + " 设置新密码(至少 6 位):"); if (!pwd) return; req = api("POST", "/api/admin/users/password", { username: user, password: pwd }); + } else if (act === "set-display") { + var curDisplay = btn.getAttribute("data-display") || ""; + var dn = prompt("账号 " + user + " 的展示名(中文姓名,留空 = 清空):", curDisplay); + if (dn === null) return; + req = api("POST", "/api/admin/users/display", { username: user, display_name: dn.trim() }); } else if (act === "set-models") { var me = state.users.filter(function (x) { return x.username === user; })[0] || {}; var cur = arr(me.allowed_models).join(", "); @@ -692,12 +820,14 @@ e.preventDefault(); api("POST", "/api/admin/users/create", { username: $("cuName").value.trim(), + display_name: $("cuDisplay").value.trim(), password: $("cuPass").value, role: $("cuRole").value, grant_temp: $("cuGrant").checked }).then(function (r) { toast(r.msg + ",API Key:" + r.data.api_key); $("cuName").value = ""; + $("cuDisplay").value = ""; $("cuPass").value = ""; $("cuGrant").checked = false; return loadAll(); @@ -724,6 +854,8 @@ var payload = { slot: $("upSlot").value.trim(), base: $("upBase").value.trim(), + // 模型清单总是显式提交:编辑框里就是"当前值",清空即清空(可预期) + models: $("upModels").value, note: $("upNote").value.trim() }; // 密钥留空时不传该字段:后端对「缺省」保留旧值,对「空串」是清空 @@ -734,6 +866,7 @@ $("upSlot").value = ""; $("upBase").value = ""; $("upAuth").value = ""; + $("upModels").value = ""; $("upNote").value = ""; return loadAll(); }).catch(function (err) { toast(err.message, true); }); @@ -745,7 +878,7 @@ document.querySelectorAll(".tab").forEach(function (t) { t.classList.remove("active"); }); tab.classList.add("active"); - ["review", "domains", "users", "upstreams"].forEach(function (name) { + ["review", "domains", "users", "upstreams", "usage"].forEach(function (name) { $("tab-" + name).hidden = (name !== tab.getAttribute("data-tab")); }); });