Files
admin fea806eb33 chore: 本机路径迁到 ~/Documents/ipass,修正 ngxbuild 多余的 build/ 段
conf/nginx.conf 的 dev root/alias 与 tests/run.sh 的 NGINX_BIN/NGINX_BUILD_DIR
从 Desktop/workspace/iPass 迁到 Documents/ipass;ngxbuild 在仓顶层,
原写法 build/ngxbuild 指向不存在的路径,默认启动会找不到 nginx 二进制。
2026-11-04 10:43:05 +08:00

518 lines
26 KiB
Nginx Configuration File
Raw Permalink 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 动态模块
#
# * 共享内存由 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 ~^(?<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;
# 与 mdm / *.dm 一致:路由器 88 → .11:18098,nginx 默认 302 Location
# 会写绝对 URL + 实际 listen 端口,把外部用户踢出反代链。
absolute_redirect off;
port_in_redirect off;
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/<slug>?<参数>` → 外部 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 供应商不可达,请稍后重试或联系管理员"}';
}
# ---- API 代理透传出口:`/apixp/<slug>/<尾部>` → 内部 REST 服务 ----
#
# 与 `/apix/`(vendor 收口)分离成独立 location,是 passthrough 模式成立的
# 前提:vendor 的 `/apix/` 在 nginx 层强制了 `proxy_method POST` +
# `proxy_set_body` + `Content-Type: application/json`,这些 location 级指令
# 无法按请求级的 shm mode 动态切换。OCR / 文生图 / TTS 这类「多端点、多 body、
# 无 asset 市场」的内部服务必须原样转发方法/请求体/Content-Type,所以另起
# 这个不施加上述约束的 location。
#
# 鉴权仍走网关同一把 `sk_` Key + 配额 + 用量统计(过 iPass 的意义),
# 只是**不再由网关拼体**——客户端带什么方法/body 原样给上游。上游路径 =
# `base + /apixp/<slug> 之后的 URI 尾部`(由模块 `$apixp_target` 算出)。
location /apixp/ {
ipass_apix on;
# 变量形式的上游(已含 path + query)。不强制 proxy_method / proxy_set_body,
# 让 OCR 的 multipart/form-data 或任意 JSON 原样出去。
proxy_pass $apixp_target;
proxy_http_version 1.1;
# 与 /apix/ 同一套出站头策略:默认不放行 + 显式放行。
# 抹掉 x-api-key / Authorization 尤其重要——那是**调用方的网关 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 $apixp_host;
# 内部服务需要 Key 才下发(X-API-Key);空则不下发(nginx 空串 = 不发该头)。
# 下行那把 sk_ 到此为止,绝不外传。
proxy_set_header X-API-Key $apixp_key;
# ★ 原样透传客户端 Content-Type(OCR 的 multipart 必须带 boundary)
proxy_set_header Content-Type $http_content_type;
proxy_set_header Accept $http_accept;
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;
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 = /apixp_error;
}
location = /apixp_error {
default_type application/json;
return 502 '{"code":502,"msg":"内部服务不可达,请稍后重试或联系管理员"}';
}
# 只改写「连不上上游」这类由 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;
# 路由器把 88 反代到 .11:18098,nginx 默认 302 Location 会写绝对 URL
# + 实际 listen 端口(即 18098),把外部用户踢出反代链。两项都关掉 →
# Location 变成相对的 `/admin`,客户端浏览器**留在 88**。
absolute_redirect off;
port_in_redirect off;
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;
# 管理台(核心壳 + 插件管理页,Ruling 16:本仓 www/*.html 多页已删除)。
# 产物来源:scripts/collect-plugin-dist.sh 把 ipass-core www dist 收集为壳
# (build/shell,本机 dev 默认布局,build/ 已 gitignore),把各启用插件
# www dist 收集为 build/static-plugins/<name>/dist/<name>-admin.umd.js。
# dev 用法:bash scripts/collect-plugin-dist.sh 后再启动 nginx。
# ⚠️ 裸机/容器部署需把下方两处路径换成 ASSEMBLY_DIR 对应目录
# (sso 仓 21c0f6f 同构,容器化收口见 task 3.9)。
root /Users/xs/Documents/ipass/ipass-ssw/build/shell;
index index.html;
location = / {
return 302 /admin/;
}
location = /admin {
return 302 /admin/;
}
# SPA history 路由深链兜底:/admin/* 未命中文件一律回壳 index.html。
# **不发版不重启也能修好缓存**:壳 HTML 一律 no-store(assets 带 hash 可缓存)。
location /admin/ {
try_files $uri $uri/ /index.html;
add_header Cache-Control "no-store" always;
}
location = /index.html {
add_header Cache-Control "no-store" always;
}
location /assets/ { }
# 账号态 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 代理透传连通性探针(管理台「测试」按钮)——
# /api/admin/apix/test 对 passthrough 模式条目内部重定向到这里。走 GET 打
# 上游根地址验连通性(不执行任何资产),复用 $apixp_probe_target 变量。
# internal 挡住外部直连——这是绕过 ukey 鉴权直接触达内部服务的口子。
location /_apixp_probe/ {
internal;
proxy_pass $apixp_probe_target;
proxy_method GET;
proxy_http_version 1.1;
proxy_pass_request_headers off;
proxy_set_header Host $apixp_host;
proxy_set_header X-API-Key $apixp_key;
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_set_body:面板探测体本来就带「第一个登记
# 模型 + max_tokens=1」(见 www/assets/upstreams.js 的 probe),而
# nginx 的 proxy_set_body 是无条件覆盖。1.0.43 为当时的空 body 探测
# 注入过最小 dummy 体(绕智谱 model=null NPE),结果把严格校验模型名
# 的厂商(minimax:unknown model 'test' 2013)一律打成「不通」。
# e2e【11】有静态闸钉住这条,别加回来。
proxy_ssl_server_name on;
proxy_connect_timeout 5s;
proxy_send_timeout 15s;
proxy_read_timeout 15s;
}
# 插件管理页产物(壳按 ipass-core loader.ts 约定拉取
# /static/plugins/<name>/dist/<name>-admin.umd.js)。
# 由 scripts/collect-plugin-dist.sh 收集进本仓 build/static-plugins/。
# 严禁 alias 到 workspace 根——会连带暴露各仓 data/*.json 等全部兄弟仓文件
# (Ruling 16,同 ipass-sso 21c0f6f 修复)。
# ⚠️ 此处用了绝对路径,生产环境需替换为容器内路径或用 docker volume 挂载。
location /static/plugins/ {
alias /Users/xs/Documents/ipass/ipass-ssw/build/static-plugins/;
autoindex off;
}
}
# ==================================================================
# 企业域名 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$;
# 路由器把 88 反代到 .11:18098,nginx 默认 302 Location 会写绝对 URL
# + 实际 listen 端口(18098),把外部用户踢出反代链。两项都关掉 →
# Location 变成相对路径,客户端浏览器**留在 88**。企业域名实际不
# 触发 302(只转发),但保持与 mdm server 一致避免日后踩坑。
absolute_redirect off;
port_in_redirect off;
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":"无效的域名"}';
}
}