反向代理

XSI 本身只提供 HTTP,HTTPS 由前置反向代理负责。API 入口对代理有三项要求:

  1. 不缓冲流式响应:SSE 需要逐块转发。
  2. 支持 WebSocket 升级:Responses WebSocket、Realtime、Live 与 DeepSeek 语音合成都依赖它。
  3. 足够长的超时:长推理与长连接可持续数十分钟。

此外,代理需要把真实客户端 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)"

相关文档