# ============================================================================ # iPass 山海关(ipass-gateway)—— vanilla nginx + Rust 动态模块 # # * 共享内存由 ipass_state 指令创建,模块内部管理 # * 管理 API 由 ipass_api 指令开启(content 阶段) # * 转发热路径由 ipass_proxy 指令开启(access 阶段) # * LLM 代理由 ipass_llm / API 代理由 ipass_apix(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; # ========== 共享内存(一张表,前缀区分用途)========== # 一张表同时承载:转发映射 / 管理会话 / 登录失败计数。 # 容量实测约 124 B/条,10m 足够放约 8 万条。 ipass_state state 10m; ipass_data_dir /usr/local/nginx/data; # ================================================================== # 转发 server:承载全部 *.yourdomain.com 业务流量 # ================================================================== server { listen 80; server_name ~^(?.+)\.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/ # # 鉴权用**与域名接口同一套** 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; # 对话审计(docs/llm/AUDIT_LOG.md):强制请求体落临时文件,log 阶段 # 由模块复制进审计目录(audit/)。不落盘的话,大请求体只存在于 # 内存缓冲链里,请求结束即释放,事后无从审计。代价 = 每个转发请求 # 多一次磁盘写(含 2KB 的小请求);审计是旁路功能,写失败不影响转发。 client_body_in_file_only clean; # 变量形式的上游。$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 = 上游 chunk 边到边发(SSE 的生命线); # proxy_cache off = 不缓存响应。 # ⚠️ **不再**开 proxy_request_buffering off:它管的是**请求体**方向, # 与响应流式无关;而它与对话审计的 client_body_in_file_only 互斥 # (no_buffering 模式 body 全程流式推给上游,nginx 不落临时文件, # 实测踩过:审计文件永远不出现)。请求体是小 JSON,缓冲上传零损失。 proxy_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; } # ---- API 代理出口:`/apix/?<参数>` → 外部 API 供应商 ---- # # 与 LLM 代理同一把 `sk_` Key、同一份限流与用量统计,差别在上游形态: # 供应商只有一个收口 `POST /api/v1/ai/request`,资产由**请求体里的 asset_id** # 决定。所以这里不能像 LLM 那样原样透传请求体——网关必须自己拼, # 否则「只暴露免费资产」这条管理策略形同虚设(调用方自己挑最贵的刷)。 # # 参数只能走 query string:转发决策在 access 阶段,请求体那时还读不到。 # 靠 proxy_method + proxy_set_body 把 GET 变成带体的 POST。 location /apix/ { ipass_apix on; proxy_pass $apix_target; proxy_method POST; proxy_set_body $apix_body; proxy_http_version 1.1; # 与 LLM 同一套出站头策略:默认不放行 + 显式放行。 # 抹掉 x-api-key 尤其重要——那是**调用方的网关 Key**, # 原样带出去等于把网关的身份送给供应商。 proxy_pass_request_headers off; proxy_set_header x-api-key ""; proxy_set_header api-key ""; proxy_set_header Authorization ""; # 变量形式不会推导 Host,必须显式设 proxy_set_header Host $apix_host; # 换上供应商真 Key。下行那把 sk_ 到此为止 proxy_set_header X-API-Key $apix_key; proxy_set_header Content-Type application/json; proxy_set_header Accept application/json; proxy_set_header User-Agent $http_user_agent; proxy_set_header Connection ""; proxy_ssl_server_name on; proxy_connect_timeout 10s; proxy_send_timeout 120s; proxy_read_timeout 120s; error_page 502 503 504 = /apix_error; } location = /apix_error { default_type application/json; return 502 '{"code":502,"msg":"API 供应商不可达,请稍后重试或联系管理员"}'; } # 只改写「连不上上游」这类由 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/ 拉取) # 拆分后每页一个 HTML:/admin 直接进「数据总览」,其余页面与静态资源都在 # /admin/ 下(overview.html / users.html / assets/*)。 # 每页 head 里有 ,因此挂在 /admin 还是 /admin/x.html # 都用同一套相对路径,资源与 /api/ 不会错位。 location = /admin { default_type text/html; alias /usr/local/nginx/www/overview.html; } location = /admin/ { default_type text/html; alias /usr/local/nginx/www/overview.html; } location /admin/ { alias /usr/local/nginx/www/; } # 账号态 API(X-API-Key)+ 管理员态 API(登录会话),统一由模块路由 location /api/ { ipass_api on; } # —— API 代理连通性/余额探测(管理台「测试」按钮)—— # /api/admin/apix/test 校验 slug 后内部重定向到这里。走供应商的**免费** # 预估接口,不执行资产、不扣费,响应里带供应商余额 current_balance_usd。 # internal 挡住外部直连——这是绕过 ukey 鉴权直接花供应商钱的口子。 location /_apix_probe/ { internal; proxy_pass $apix_probe_target; proxy_method POST; proxy_set_body $apix_probe_body; proxy_http_version 1.1; proxy_pass_request_headers off; proxy_set_header Host $apix_host; proxy_set_header X-API-Key $apix_key; proxy_set_header Content-Type application/json; proxy_set_header Accept application/json; proxy_ssl_server_name on; proxy_connect_timeout 5s; proxy_send_timeout 15s; proxy_read_timeout 15s; } # —— 上游连通性测试(管理台「测试」按钮)—— # /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 ~^(?.+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":"无效的域名"}'; } }