---
id: devops.nginx.scenario.ai-gateway-sse-canary
title: AI 应用网关：流式输出不卡顿、按用户灰度新版本
type: scenario
domain: devops
stack: [nginx, fastapi]
tags: [SSE, 流式输出, 灰度发布, 限流, 网关]
level: intermediate
prerequisites: [devops.nginx.https-stream-limit]
est_hours: 2
related: [devops.nginx.interview, devops.docker.scenario.compose-dev-env]
week: [7, 13, 14]
---

# AI 应用网关：流式输出不卡顿、按用户灰度新版本

## 业务背景与问题

企业内部的 AI 问答助手：前端单页应用，后端 Python FastAPI 调用大模型并以 SSE 流式返回。上线后遇到三个问题：

1. 经过 Nginx 后，回答不再逐字出现，而是等十几秒后整段出现；长回答偶尔 504。
2. 新版本的检索策略想先给内部 20 个同事试用，没有灰度手段，只能全量发布。
3. 有人写脚本刷接口，模型调用费用突增。

## 约束

- 只有一台入口服务器上的 Nginx，不引入新的网关产品。
- 灰度要能按用户指定，也要能随时关闭。
- 正常用户的体验不能受限流影响。

## 方案设计

```mermaid
flowchart LR
  B[浏览器] --> N[Nginx]
  N -->|/ 静态资源| S[dist/]
  N -->|/api/ 限流 + 按 Cookie 选择| ST[AI 服务 稳定版]
  N -->|canary=1| CA[AI 服务 灰度版]
  N -->|/ai/stream 关闭缓冲| ST
```

1. **流式**：`/ai/stream` 单独一个 location，`proxy_buffering off`、`proxy_cache off`、`proxy_read_timeout 300s`；后端每 15 秒发一条 `: ping` 心跳，防止中间设备断开空闲连接。
2. **灰度**：`map $cookie_canary $api_backend`，内部同事访问一个“加入体验”页面，由后端为其设置 `canary=1` 的 Cookie；关闭灰度只需把 map 默认值都指向稳定版并 reload。也可以用 `split_clients` 按比例放量。
3. **限流**：Nginx 按 IP 做第一道粗粒度限流（`limit_req`，返回 429）；后端再按用户 / 租户做精细的配额（Redis，见 [Redis 限流](../../../backend/redis/03-lock-ratelimit.md)），并记录每个用户的模型调用量。

## 关键代码

完整配置模板和自动化测试见 [examples/gateway](../examples/gateway/)：

```nginx
map $cookie_canary $api_backend {
    default api_stable;
    "1"     api_canary;
}

location /api/ {
    limit_req zone=api_limit burst=5 nodelay;
    proxy_pass http://$api_backend;
}

location /ai/stream {
    proxy_pass http://api_stable;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
}
```

FastAPI 端的 SSE 响应头和心跳（示意）：

```python
from fastapi.responses import StreamingResponse


async def event_stream(chunks):
    async for text in chunks:            # chunks：大模型返回的增量文本
        yield f"data: {text}\n\n"
    yield "data: [DONE]\n\n"


def sse(chunks) -> StreamingResponse:
    return StreamingResponse(event_stream(chunks), media_type="text/event-stream",
                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
```

测试用真实 Nginx 验证了四点：SPA 回退、反向代理并传递 `X-Forwarded-For`、带 `canary=1` Cookie 的请求进入灰度后端、SSE 第一条事件不被缓冲、超过限流返回 429。

## 取舍

| 方案 | 优点 | 缺点 |
| --- | --- | --- |
| **Nginx map / split_clients（本方案）** | 无新组件，配置简单 | 规则复杂时难维护；改规则要 reload |
| API 网关产品（APISIX、Kong 等） | 动态配置、插件丰富 | 多一套系统要运维 |
| 应用内特性开关 | 粒度最细（按功能） | 需要改代码，新旧逻辑并存 |
| Kubernetes + 服务网格 | 按权重、按头部灰度都很方便 | 需要 K8s 和网格基础设施 |

## 易错点

- 只在 `/api/` 关了缓冲，SSE 走的其实是另一个 location。
- 开了 gzip 且把 `text/event-stream` 加进 `gzip_types`，流式又被攒起来。
- `proxy_read_timeout` 理解成总时长：它是两次读之间的最大间隔，心跳能避免超时。
- 灰度 Cookie 由前端随意设置：任何人都能进灰度。应由后端校验身份后设置。
- 限流只在 Nginx 按 IP：公司出口是同一个 IP，所有同事一起被限。内部系统应按用户维度在后端限流。

## 面试怎么讲

> “AI 助手经过 Nginx 后流式输出变成整段，原因是 Nginx 默认缓冲代理响应。我给流式接口单独配了 location，关闭缓冲、放宽读超时，后端加心跳；用 map 按 Cookie 把内部同事路由到灰度版本；在 Nginx 做按 IP 的粗限流、后端按用户做配额。我还写了自动化测试，用真实 Nginx 验证第一条事件不被缓冲、灰度和限流生效。”