- 健康标记(log 阶段):真实转发的上游状态码写入 uh:<slot>(4xx=活着,
5xx/502/504=失效,下次成功自动自愈),数据来源就是真实流量本身,
无需常驻探测进程。状态码读 $upstream_status 变量(r->upstream 在
上游 finalize 时已置空,log 阶段读不到——access log 同款手法)。
- 管理台「测试」按钮:POST /api/admin/upstreams/test?slot=X,校验后
ngx_http_internal_redirect 到管理 server 内部 location /_upstream_test,
复用 LLM 链路的取 slot / 拼路径 / 换真 Key 逻辑,上游原话透传给面板。
⚠️ 内部重定向只浅拷贝 ngx_str_t,URI 必须拷进请求池——否则函数返回
即悬垂,log 阶段 r->uri 全是 NUL,健康标记静默失效(实测踩坑)。
- 上游列表每行 slot 旁 OpenAI / Anthropic 两枚点击复制地址按钮,
模型发现(/v1/models 与 /api/v1/models、/api/v1/upstreams)附
anthropic_base_url 与健康状态;anthropic_base_url 统一收口
upstreams::anthropic_base_url(),base 已钉 /anthropic 时不重复追加。
- 统计卡片挪进独立「数据总览」tab 并设为默认页。
- 回归 +12 条(第 12 节健康标记断言),LLM 111 + 网关 78,失败 0。
- 测试卫生:run.sh 启动靶机前 pkill 残留进程(占 18999 会造成假 200)。
317 lines
15 KiB
Nginx Configuration File
317 lines
15 KiB
Nginx Configuration File
# ============================================================================
|
||
# iPass 山海关(ipass-gateway)—— vanilla nginx + Rust 动态模块
|
||
#
|
||
# 与旧 OpenResty 版的差异:
|
||
# * 不再需要 lua_package_path / lua_shared_dict / init_worker_by_lua
|
||
# * 共享内存由 ipass_state 指令创建,模块内部管理
|
||
# * 管理 API 由 ipass_api 指令开启(content 阶段)
|
||
# * 转发热路径由 ipass_proxy 指令开启(access 阶段)
|
||
#
|
||
# 阶段处理器是 http 级的,所以**必须**靠上面两个开关按 location 收敛,
|
||
# 否则管理台自己也会被转发逻辑 404 掉。
|
||
# ============================================================================
|
||
|
||
load_module /usr/local/nginx/modules/libipass_gateway.so;
|
||
|
||
worker_processes auto; # 单 worker 曾是全局瓶颈;实测 4 worker 热路径吞吐 +98%
|
||
error_log /usr/local/nginx/logs/error.log info;
|
||
pid /usr/local/nginx/logs/nginx.pid;
|
||
|
||
# 供模块读取初始管理员口令(不声明则会被 nginx 从环境中剥离)
|
||
env ADMIN_INIT_PASSWORD;
|
||
|
||
events {
|
||
worker_connections 2048;
|
||
}
|
||
|
||
http {
|
||
include mime.types;
|
||
default_type application/json; # 业务侧默认返回 JSON,HTML 在对应 location 单独覆盖
|
||
|
||
# ========== WebSocket 升级变量 ==========
|
||
# 转发 location 里的 `proxy_set_header Connection $connection_upgrade` 依赖此变量;
|
||
# 缺它 nginx -t 直接报 unknown "connection_upgrade" variable,服务起不来。
|
||
map $http_upgrade $connection_upgrade {
|
||
default upgrade;
|
||
'' close;
|
||
}
|
||
|
||
# ========== 日志 ==========
|
||
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
|
||
'$status $body_bytes_sent "$http_referer" '
|
||
'"$http_user_agent" "$http_x_forwarded_for" '
|
||
'"$upstream_addr" "$upstream_status" "$upstream_response_time" '
|
||
'subdomain=$subdomain backend=$proxy_backend_addr';
|
||
|
||
access_log /usr/local/nginx/logs/access.log main;
|
||
|
||
sendfile on;
|
||
keepalive_timeout 65;
|
||
|
||
# 内网后端常用 hostname,需要 resolver;纯 IP:port 后端不依赖它
|
||
resolver 223.5.5.5 119.29.29.29 valid=30s;
|
||
|
||
# ========== 可选 TLS(HTTPS)==========
|
||
# conf/tls/ 下放任意 *.conf(完整的 443 server 块)即启用对应域名的 HTTPS;
|
||
# 目录为空或不存在时 include 空匹配,不影响启动。
|
||
# 模板见 conf/tls/llm.conf.example,说明见 conf/tls/README.md
|
||
include /usr/local/nginx/conf/tls/*.conf;
|
||
|
||
# ========== 共享内存(替代旧版的 lua_shared_dict 三件套)==========
|
||
# 一张表同时承载:转发映射 / 管理会话 / 登录失败计数。
|
||
# 容量实测约 124 B/条,10m 足够放约 8 万条。
|
||
ipass_state state 10m;
|
||
ipass_data_dir /usr/local/nginx/data;
|
||
|
||
# ==================================================================
|
||
# 转发 server:承载全部 *.yourdomain.com 业务流量
|
||
# ==================================================================
|
||
server {
|
||
listen 80;
|
||
server_name ~^(?<subdomain>.+)\.yourdomain\.com$;
|
||
|
||
client_max_body_size 100m; # 网关直通大文件,避免默认 1MB 限制误伤上传
|
||
|
||
location / {
|
||
# 开启后由模块在 access 阶段查共享内存;查不到直接 404
|
||
ipass_proxy on;
|
||
|
||
proxy_pass http://$proxy_backend_addr;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection $connection_upgrade;
|
||
|
||
proxy_connect_timeout 5s;
|
||
proxy_send_timeout 300s; # 长轮询 / SSE / 大文件回源
|
||
proxy_read_timeout 300s;
|
||
}
|
||
|
||
error_page 404 502 503 504 = /proxy_error;
|
||
location = /proxy_error {
|
||
return 404 '{"code":404,"msg":"子域名未配置、已过期或后端服务不可达"}';
|
||
}
|
||
}
|
||
|
||
# ==================================================================
|
||
# LLM 代理 server:客户端把 base_url 指向 https://lm.mayishangshu.cn/<slot>
|
||
#
|
||
# 鉴权用**与域名接口同一套** API Key(users.json 里的 sk_...),
|
||
# 由模块在 access 阶段换成上游真实密钥后转发。
|
||
# 上游由 URL 第一段决定(/openai/v1/... → slot=openai),**不是**按
|
||
# 请求体里的 model 字段——access 阶段拿不到请求体(见 CLAUDE.md)。
|
||
# 与管理/企业 server 同端口 18098,共用通配符 *.mayishangshu.cn 证书。
|
||
# ==================================================================
|
||
server {
|
||
listen 18098 ssl;
|
||
server_name lm.mayishangshu.cn;
|
||
|
||
ssl_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/fullchain.cer;
|
||
ssl_certificate_key /usr/local/nginx/conf/tls/*.shangshuwang.cn/*.shangshuwang.cn.key;
|
||
ssl_trusted_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/ca.cer;
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
|
||
# 多模态请求会内联 base64 图片,几 MB 是常态
|
||
client_max_body_size 100m;
|
||
|
||
location / {
|
||
# access 阶段:查 ukey: 鉴权 → 查 up: 校验上游 → 校验白名单
|
||
ipass_llm on;
|
||
|
||
# 变量形式的上游。$llm_target 由模块算出,已含 path 与 query
|
||
# (变量形式不会自动追加原始 args,所以 query 必须由模块拼好)
|
||
proxy_pass $llm_target;
|
||
|
||
proxy_http_version 1.1;
|
||
|
||
# ================================================================
|
||
# 出站请求头策略:默认不放行(allowlist)
|
||
#
|
||
# 这是 LiteLLM / one-api / Higress 的共同做法——**不把客户端带了什么
|
||
# 头当成上游该收什么头**,而是网关自己按「上游需要什么」重新构造。
|
||
# nginx 里对应的开关就是 proxy_pass_request_headers off(只发下面
|
||
# 显式声明的头)。调研与实测:docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md
|
||
#
|
||
# 不这么做的后果(本机靶机 + .11 生产双确认):nginx 默认透传全部
|
||
# 客户端头,而本块只覆写了 Authorization —— 客户端放在 x-api-key 里的
|
||
# **网关自己的 Key** 会被原样送给上游厂商,厂商可拿它反调本网关挂的
|
||
# **全部**上游(横向越权)。宽松厂商(MiniMax 两处都认)会把这个缺陷
|
||
# 掩盖成 200,换到只认 x-api-key 的严格厂商才变成 401。
|
||
# ================================================================
|
||
proxy_pass_request_headers off;
|
||
|
||
# ── 第一层:凭据头显式抹空(nginx 空串语义 = 不发该头)──
|
||
# 与 off 叠加是刻意的冗余:将来谁把 off 改回 on,这层仍然兜底。
|
||
# 名单取自「主流 SDK 把凭据放在哪个头里」。
|
||
proxy_set_header x-api-key "";
|
||
proxy_set_header api-key "";
|
||
proxy_set_header x-goog-api-key "";
|
||
|
||
# ── 第二层:显式放行上游真正需要的头 ──
|
||
# ★ 漏一条的后果都是实测过的:
|
||
# Content-Type → 所有 POST 直接废(上游收到无 content-type 的 body)
|
||
# anthropic-version → Anthropic 协议必填,缺失即被拒
|
||
# anthropic-beta → Claude Code 的 prompt caching 等扩展静默失效
|
||
# Accept → SSE 流式协商受影响
|
||
# 将来厂商新增扩展头(如新的 openai-beta 值)**必须同步加到这里**,
|
||
# 漏掉的表现是「静默功能缺失」而不是报错。
|
||
#
|
||
# 变量形式的 proxy_pass 不会推导 Host,必须显式设;
|
||
# 上游多为 Cloudflare 前端,Host 不符会被直接拒
|
||
proxy_set_header Host $llm_host;
|
||
# 换上上游真实密钥。下行那把 sk_ 到此为止,不往上游传
|
||
proxy_set_header Authorization $llm_auth;
|
||
proxy_set_header Content-Type $http_content_type;
|
||
proxy_set_header Accept $http_accept;
|
||
proxy_set_header anthropic-version $http_anthropic_version;
|
||
proxy_set_header anthropic-beta $http_anthropic_beta;
|
||
proxy_set_header openai-beta $http_openai_beta;
|
||
# 客户端身份,便于厂商侧排障(非语义必需,但丢了就查不动账)
|
||
proxy_set_header User-Agent $http_user_agent;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
# 置空才能与上游复用长连接(这是 API 调用,不是 WebSocket)
|
||
proxy_set_header Connection "";
|
||
|
||
# —— SSE 三件套:缺一条,流式就会退化成「攒完一次性返回」——
|
||
proxy_buffering off;
|
||
proxy_request_buffering off;
|
||
proxy_cache off;
|
||
chunked_transfer_encoding on;
|
||
|
||
# 上游是 HTTPS 时必须开 SNI,否则握手到的证书对不上
|
||
proxy_ssl_server_name on;
|
||
|
||
proxy_connect_timeout 10s;
|
||
proxy_send_timeout 600s; # 推理可能很慢,且流式期间连接一直挂着
|
||
proxy_read_timeout 600s;
|
||
}
|
||
|
||
# 只改写「连不上上游」这类由 nginx 自己产生的错误。
|
||
# 404 等一律透传上游响应——那可能是模型名不存在的正常业务错误,
|
||
# 覆盖掉反而让客户端拿不到有用信息。
|
||
error_page 502 503 504 = /llm_error;
|
||
location = /llm_error {
|
||
default_type application/json;
|
||
# 错误体必须是 OpenAI 兼容形状,否则客户端 SDK 会报「无法解析响应」
|
||
return 502 '{"error":{"message":"上游不可达","type":"api_error","code":"upstream_unavailable"}}';
|
||
}
|
||
}
|
||
|
||
# ==================================================================
|
||
# 管理 server:管理页面(mdm.mayishangshu.cn)+ 全部 API
|
||
# 与管理域名分离:企业流量走 *.dm、LLM 走 lm,三者同端口 18098,
|
||
# 共用通配符 *.mayishangshu.cn 证书(目录带字面 * 是存储介质原名)。
|
||
# ==================================================================
|
||
server {
|
||
listen 18098 ssl;
|
||
server_name mdm.mayishangshu.cn;
|
||
|
||
ssl_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/fullchain.cer;
|
||
ssl_certificate_key /usr/local/nginx/conf/tls/*.shangshuwang.cn/*.shangshuwang.cn.key;
|
||
ssl_trusted_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/ca.cer;
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
|
||
client_max_body_size 2m;
|
||
# API 请求体都是几百字节的小 JSON;调大缓冲区让它始终留在内存里,
|
||
# 避免被刷到临时文件(模块当前只从内存 buf 读体)
|
||
client_body_buffer_size 1m;
|
||
|
||
location = / {
|
||
return 302 /admin;
|
||
}
|
||
|
||
# 管理台单页(静态文件,数据全部通过 /api/ 拉取)
|
||
location = /admin {
|
||
default_type text/html;
|
||
alias /usr/local/nginx/www/admin.html;
|
||
}
|
||
location = /admin/ {
|
||
default_type text/html;
|
||
alias /usr/local/nginx/www/admin.html;
|
||
}
|
||
|
||
# 账号态 API(X-API-Key)+ 管理员态 API(登录会话),统一由模块路由
|
||
location /api/ {
|
||
ipass_api on;
|
||
}
|
||
|
||
# —— 上游连通性测试(管理台「测试」按钮)——
|
||
# /api/admin/upstreams/test 校验 slot 后由模块内部重定向到这里。
|
||
# proxy_pass 复用 LLM 的 $llm_* 变量(getter 从 URI 第一段取 slot,
|
||
# 前缀 /_upstream_test 由模块剥掉);已读入的探测请求体由 proxy
|
||
# 原样转发;上游真实状态码与响应体直接透传给面板。
|
||
# internal 挡住外部直连——这是唯一不经过 ukey 鉴权就能触达上游的口,
|
||
# 必须只能由模块自己的 admin 会话校验后才可达。
|
||
location /_upstream_test/ {
|
||
internal;
|
||
proxy_pass $llm_target;
|
||
proxy_http_version 1.1;
|
||
proxy_pass_request_headers off;
|
||
proxy_set_header Host $llm_host;
|
||
proxy_set_header Authorization $llm_auth;
|
||
proxy_set_header Content-Type $http_content_type;
|
||
proxy_set_header Accept $http_accept;
|
||
proxy_ssl_server_name on;
|
||
proxy_connect_timeout 5s;
|
||
proxy_send_timeout 15s;
|
||
proxy_read_timeout 15s;
|
||
}
|
||
}
|
||
|
||
# ==================================================================
|
||
# 企业域名 server:承载 *.dm.mayishangshu.cn(标签以 dm 结尾,如
|
||
# a2777888dm.mayishangshu.cn)。证书为通配符 *.mayishangshu.cn,
|
||
# 目录带字面 * 是存储介质原名。监听 18098(路由器 18098 → 本机 18098),
|
||
# 与转发 server 同构,复用 ipass_proxy。
|
||
# ==================================================================
|
||
server {
|
||
listen 18098 ssl;
|
||
server_name ~^(?<subdomain>.+dm)\.mayishangshu\.cn$;
|
||
|
||
ssl_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/fullchain.cer;
|
||
ssl_certificate_key /usr/local/nginx/conf/tls/*.shangshuwang.cn/*.shangshuwang.cn.key;
|
||
ssl_trusted_certificate /usr/local/nginx/conf/tls/*.shangshuwang.cn/ca.cer;
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
|
||
client_max_body_size 100m;
|
||
|
||
location / {
|
||
# 开启后由模块在 access 阶段查共享内存;查不到直接 404
|
||
ipass_proxy on;
|
||
|
||
proxy_pass http://$proxy_backend_addr;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection $connection_upgrade;
|
||
|
||
proxy_connect_timeout 5s;
|
||
proxy_send_timeout 300s; # 长轮询 / SSE / 大文件回源
|
||
proxy_read_timeout 300s;
|
||
}
|
||
|
||
error_page 404 502 503 504 = /proxy_error;
|
||
location = /proxy_error {
|
||
return 404 '{"code":404,"msg":"子域名未配置、已过期或后端服务不可达"}';
|
||
}
|
||
}
|
||
|
||
# ==================================================================
|
||
# 默认 server:不在 *.yourdomain.com 下的请求一律拒绝
|
||
# ==================================================================
|
||
server {
|
||
listen 80 default_server;
|
||
server_name _;
|
||
|
||
return 403 '{"code":403,"msg":"无效的域名"}';
|
||
}
|
||
}
|