- 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 合流记录
403 lines
20 KiB
Nginx Configuration File
403 lines
20 KiB
Nginx Configuration File
# ============================================================================
|
||
# 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":"无效的域名"}';
|
||
}
|
||
}
|