反向代理
XSI 本身只提供 HTTP,HTTPS 由前置反向代理负责。API 入口对代理有三项要求:
- 不缓冲流式响应:SSE 需要逐块转发。
- 支持 WebSocket 升级:Responses WebSocket、Realtime、Live 与 DeepSeek 语音合成都依赖它。
- 足够长的超时:长推理与长连接可持续数十分钟。
此外,代理需要把真实客户端 IP 传给 XSI,用于 IP 白名单、认证失败封禁与注册防刷。
真实客户端 IP
XSI 只在连接来自 TRUSTED_PROXY_CIDRS(默认回环地址与 RFC 1918 私网)时才读取转发头:先从 X-Forwarded-For 自右向左取第一个不受信任的地址,再依次查看 CF-Connecting-IP、True-Client-IP、X-Real-IP。来自其他地址的连接直接使用对端 IP。
- 代理与 XSI 同机或位于同一私网时,保持默认值即可。
- 代理位于公网其他地址时,把它的地址加入
TRUSTED_PROXY_CIDRS。 - 不要把任意公网网段加入受信列表,否则客户端可以伪造 IP。
XSI 在转发到上游前会删除全部客户端 IP 相关的头,上游看不到终端用户的地址。
Nginx
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}
upstream xsi_api {
server 127.0.0.1:5443;
keepalive 256;
}
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/nginx/certs/api.example.com.crt;
ssl_certificate_key /etc/nginx/certs/api.example.com.key;
client_max_body_size 200m;
underscores_in_headers on; # 保留 session_id、conversation_id 等粘性会话请求头
location / {
# CORS:控制台与浏览器应用跨域调用 API 时需要
if ($request_method = 'OPTIONS') {
add_header Access-Control-Allow-Origin '*';
add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key';
add_header Access-Control-Max-Age 1728000;
add_header Content-Length 0;
return 204;
}
add_header Access-Control-Allow-Origin '*' always;
add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key' always;
proxy_pass http://xsi_api;
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;
# WebSocket
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# 流式响应
proxy_buffering off;
proxy_request_buffering off;
# 长推理与长连接
proxy_connect_timeout 10s;
proxy_send_timeout 3600s;
proxy_read_timeout 3600s;
}
}
server {
listen 443 ssl;
http2 on;
server_name admin.example.com;
ssl_certificate /etc/nginx/certs/admin.example.com.crt;
ssl_certificate_key /etc/nginx/certs/admin.example.com.key;
location / {
proxy_pass http://127.0.0.1:5080;
proxy_set_header Host $host;
}
}
server {
listen 443 ssl;
http2 on;
server_name manage.example.com;
ssl_certificate /etc/nginx/certs/manage.example.com.crt;
ssl_certificate_key /etc/nginx/certs/manage.example.com.key;
location / {
proxy_pass http://127.0.0.1:5081;
proxy_set_header Host $host;
}
}要点:
- CORS 由代理提供。XSI 不发送
Access-Control-Allow-*响应头,除/x-pricing外也不处理OPTIONS预检;控制台运行在独立域名上,必须由代理直接以204应答预检并附加 CORS 头,否则控制台无法登录。分页响应头的暴露(Access-Control-Expose-Headers)由 XSI 自行设置。如需收紧,可把Access-Control-Allow-Origin改为控制台域名。 client_max_body_size应不小于REQUEST_BODY_LIMIT_BYTES(默认 200 MiB)。- 若为不同路径拆分了多个
location,每个承载 WebSocket 的路径(/v1/responses、/v1/realtime、/v1/live/、/v1/tools/tts)都需要带上Upgrade与Connection头。 Connection头使用 map 写法:有Upgrade时转发 WebSocket 升级,没有时发送空值,保持与上游的 keep-alive 连接复用。underscores_in_headers on不可省略。Nginx 默认丢弃名称带下划线的请求头,session_id、conversation_id会因此丢失,粘性会话与提示缓存命中率随之下降。
Caddy
api.example.com {
reverse_proxy 127.0.0.1:5443 {
flush_interval -1
transport http {
read_timeout 3600s
write_timeout 3600s
}
}
}
admin.example.com {
reverse_proxy 127.0.0.1:5080
}
manage.example.com {
reverse_proxy 127.0.0.1:5081
}Caddy 自动申请证书、透传 WebSocket,并默认设置 X-Forwarded-For。控制台跨域访问所需的 CORS 头与 OPTIONS 预检应答,请参照上面的 Nginx 示例用 header 与 respond 指令补充。
CDN 与 Cloudflare
- 经过 Cloudflare 等 CDN 时,确保 CDN 回源地址或其网段在
TRUSTED_PROXY_CIDRS内(或由同机代理统一处理),XSI 会读取CF-Connecting-IP。 - CDN 的响应超时可能短于长推理所需时间(例如 Cloudflare 免费套餐的 100 秒),超过时客户端会收到
524。长时间请求建议使用流式响应,或让 API 域名绕过 CDN 代理。 - 不要在 CDN 上缓存 API 响应。
控制台
两个控制台是纯静态站点,容器内的 Nginx 已配置好缓存策略(HTML 与 config.js 不缓存,带版本号的 JS/CSS 缓存一年),前置代理只需透传。控制台在浏览器中直接调用 API 域名,因此 API 入口必须提供上文的 CORS 配置。
验证
# 流式:应逐块输出,而非最后一次性返回
curl -N "https://api.example.com/v1/chat/completions" \
-H "Authorization: Bearer $XSI_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"gpt-6.2-sol","stream":true,"messages":[{"role":"user","content":"数到 20"}]}'
# WebSocket:应返回 101 Switching Protocols
curl -i -N "https://api.example.com/v1/responses" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: $(openssl rand -base64 16)"