AI流式消息踩坑记录-nginx缓存导致SSE效果异常

问题背景

在使用Nginx反向代理Agent服务时，如果配置不当，会导致服务器推送事件（SSE，即Server-Sent Events）无法实时传输。具体表现为：客户端看不到逐字打印的流式效果，而是一段一段地接收文本，严重影响了用户体验。

根本原因

Nginx默认会对后端响应进行缓冲，以提高性能。但对于SSE流式传输场景，这种缓冲机制会破坏实时性——Nginx会等待累积足够数据后才一次性转发给客户端，而不是收到数据立即转发。

解决方案

使用以下Nginx配置来正确代理Agent服务：

location /axim-agent {
    # 基础代理配置
    proxy_redirect off;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # SSE 流式传输必需配置
    proxy_http_version 1.1;          # HTTP/1.1 支持长连接
    proxy_set_header Connection '';   # 保持连接活性
    proxy_buffering off;              # 🔥 关键：禁用缓冲
    proxy_cache off;                  # 禁用缓存
    proxy_read_timeout 3600s;         # 读取超时：1小时
    proxy_send_timeout 3600s;         # 发送超时：1小时
    proxy_connect_timeout 75s;        # 连接超时：75秒
    proxy_set_header X-Accel-Buffering no;  # 明确告诉Nginx不要缓冲
    add_header Cache-Control no-cache;      # 客户端不缓存
    chunked_transfer_encoding on;           # 启用分块传输

    proxy_pass http://127.0.0.1:8008;
}

配置项解析

核心配置（缺一不可）

超时配置

• proxy_read_timeout 3600s：如果Agent处理SSE流式响应耗时较长（例如大模型生成内容），需要设置足够长的读取超时时间，防止连接被Nginx提前关闭。
• proxy_send_timeout 3600s：发送数据到客户端的超时时间。
• proxy_connect_timeout 75s：与后端建立连接的超时时间。

客户端缓存控制

• add_header Cache-Control no-cache：告诉客户端不要缓存响应内容，确保实时性。
• chunked_transfer_encoding on：启用分块传输编码，适合流式数据传输。

验证方法

配置生效后，可以通过以下方式验证：

1. 浏览器开发者工具：观察Network面板中SSE请求的响应，应该看到数据持续、实时地到达，而不是一次性全部接收。

2. 用户体验：前端应呈现逐字打印的打字效果，而非段落式输出。

3. 日志检查：查看Nginx访问日志和错误日志，确认没有超时或缓冲相关警告。

常见问题

Q1：为什么加了这些配置还是不行？

• 检查是否有其他location或全局配置覆盖了这些设置
• 确认后端服务是否正确设置了SSE响应头（如Content-Type: text/event-stream）
• 检查防火墙或负载均衡器是否干扰了长连接

Q2：超时时间设置多长合适？

• 根据业务场景调整，大模型生成内容建议设置较长时间（如3600s）
• 如果Agent处理速度较快，可以适当缩短

Q3：会影响其他非SSE请求吗？

• 此配置仅对/axim-agent路径生效，不影响其他location
• 如果全局配置了proxy_buffering off，可能影响普通请求的性能，建议按需配置

总结

配置Nginx代理SSE流式服务时，禁用缓冲是核心，同时需要配合HTTP/1.1长连接、超时控制和缓存禁用等配套设置。以上配置经过实践验证，可以有效解决SSE流式传输的缓冲问题，实现真正的实时打字效果。

如果您在配置过程中遇到其他问题，欢迎在评论区交流讨论！