K8s Ingress 路由下的前端静态资源与 AI 流式 API 统一网关
在云原生架构中构建现代 AI 应用时，很多团队经常采用“前后端分离部署在两个不同域名”的架构模式：前端静态页面部署在 app.example.com，大模型推理服务或 BFF 部署在 api.example.com。
这种跨域分离架构在接入流式 AI 响应（SSE / Server-Sent Events）与企业级安全鉴权时，会带来一系列棘手的工程麻烦：
通过 Kubernetes Ingress-Nginx 的路径统一路由规约（Path-based Routing），将前端静态 SPA 与后端 AI 流式 API 收敛至同一个域名下，并针对性调优 SSE 代理参数，是构建高性能 AI 应用网关的标准最佳实践。
统一网关架构设计
[用户浏览器访问: https://ai.example.com]
│
▼
[Kubernetes Ingress-Nginx 网关]
│
┌───────────────────────────┴───────────────────────────┐
▼ ▼
[路径 / (默认全部静态页面)] [路径 /api/v1/ai/ (流式推理 API)]
│ │
▼ ▼
[Frontend Pod (Nginx 托管静态 Bundle)] [AI Inference Service Pod (vLLM / FastAPI)]
– 强缓存 (Cache-Control: max-age=31536000) – 禁用代理缓冲 (proxy_buffering off)
– 开启 Gzip / Brotli 压缩 – 超时时间延长至 300s (proxy_read_timeout)
生产级 Ingress-Nginx YAML 配置实现
为了在同一个 Ingress 资源中同时支持“静态资源高吞吐缓存”与“AI 流式响应零缓冲实时推送”，我们利用 Ingress-Nginx 的高级注解（Annotations）进行精细化配置：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ai-unified-ingress
namespace: ai-production
annotations:
kubernetes.io/ingress.class: "nginx"
# SSL 与安全协议配置
cert-manager.io/cluster-issuer: "letsencrypt-prod"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
# 核心流式调优：彻底关闭 Nginx 代理缓冲，确保 SSE Token 秒级直达前端
nginx.ingress.kubernetes.io/proxy-buffering: "off"
# 延长长连接读取超时时间至 5 分钟，防止大模型长思考时连接被 Nginx 中断
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
# 启用分块传输编码支持
nginx.ingress.kubernetes.io/proxy-http-version: "1.1"
nginx.ingress.kubernetes.io/configuration-snippet: |
# 针对 API 路由禁用客户端缓存与代理缓存
proxy_set_header Connection '';
chunked_transfer_encoding on;
spec:
tls:
– hosts:
– ai.company.internal
secretName: ai-tls-cert
rules:
– host: ai.company.internal
http:
paths:
# 路由 1：AI 流式 API 接口转发
– path: /api/v1/ai
pathType: Prefix
backend:
service:
name: ai-inference-service
port:
number: 8000
# 路由 2：前端静态资源托管服务
– path: /
pathType: Prefix
backend:
service:
name: frontend-spa-service
port:
number: 80
前端 Nginx 静态服务容器配置（SPA 路由兜底）
在前端容器内部的 nginx.conf 中，配置标准的前端 SPA History 路由回退与静态资源长期缓存：
server {
listen 80;
server_name localhost;
root /usr/share/nginx/html;
index index.html;
# 静态资源强缓存（带有构建 Hash 的 JS/CSS/图片）
location ~* \\.(js|css|png|jpg|jpeg|gif|svg|woff2)$ {
expires 1y;
add_header Cache-Control "public, max-age=31536000, immutable";
access_log off;
}
# index.html 永不缓存，确保版本发布秒级生效
location = /index.html {
expires -1;
add_header Cache-Control "no-store, no-cache, must-revalidate";
}
# SPA 前端路由兜底重定向
location / {
try_files $uri $uri/ /index.html;
}
}
