Files
ipass__ipass/conf/nginx.conf
T
admin db99ce1521 docs: 文档与注释系统性对齐插件化现状 + 清理前身实现引用
- readme §16 补 1.0.10-1.0.13 四条变更记录;§12.6 tag 表补 1.0.9-1.0.13
- readme §5 架构图更新为插件化结构(PLUGINS 注册表/四开关/四表)
- readme §11 补 api-proxies.json 数据模型小节;§8 管理台表格补 API 代理行
- readme/CLAUDE.md 测试断言数对齐 262(102+160);三个 JSON 改四个
- CLAUDE.md LLM 落点表改 crates/plugin-llm 路径;发版补 git push 前置教训
- 清理全部前身实现引用(readme 三处、CLAUDE.md 性能章节、util.rs 注释)
- PLUGIN_ARCHITECTURE.md 增补 1.0.13 sso 合流记录
2026-09-13 18:27:28 +08:00

403 lines
20 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 动态模块
#
# * 共享内存由 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;
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 供应商不可达,请稍后重试或联系管理员"}';
}
# 只改写「连不上上游」这类由 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 里有 <base href="/admin/">,因此挂在 /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 ~^(?<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":"无效的域名"}';
}
}