Files
ipass__ipass/conf/nginx.conf
T
admin 1b0bde9f72 feat(llm): 上游健康自动标记 + 管理台连通性测试 + 可复制 API 地址
- 健康标记(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)。
2026-09-12 14:42:32 +08:00

317 lines
15 KiB
Nginx Configuration File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ============================================================================
# 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":"无效的域名"}';
}
}