本地部署 NewAPI 流式响应中断？排查与解决办法

最近在捣鼓自建 AI 服务的中转项目，有个问题挺让人头秃：不管是部署在本地还是小服务器上，访问自己的 NewAPI 总是莫名其妙地报错，提示 stream disconnected before completion: stream closed before response.completed。

简单来说，就是流式输出（打字机效果）还没完事儿呢，连接就断了。这种问题大多不是代码本身的大 Bug，而是环境配置和网络层面的“幺蛾子”。今天就把这个坑的填法整理一下，希望能帮到同样遇到这个问题的朋友。

一、 先搞清问题出在哪

遇到这个问题，首先要分清楚是“谁”断的连接。通常有以下几种情况：

1. 客户端主动断开：比如浏览器或者调用你的 API 的脚本超时了。
2. 反向代理（Nginx/Caddy）超时：这是最常见的原因。代理服务器觉得后端处理太慢，直接切断了连接。
3. NewAPI 本身或上游 API 问题：NewAPI 与上游模型（如 OpenAI）之间的连接断了，或者 NewAPI 进程崩了。

二、 排查步骤与解决方案

1. 检查反向代理配置（重灾区）

如果你用了 Nginx 或者 Caddy 做 Web 服务器，默认的超时时间通常很短（比如 60 秒）。现在的 AI 模型生成速度若是不快，或者 Context 很长，很容易超过这个时间。

Nginx 用户请检查： 在你的 server 或 location 块中增加或修改以下配置：

proxy_connect_timeout 600s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;

解释一下：

• proxy_read_timeout 是最关键的，它决定了 Nginx 等待后端响应多久。如果不设置或者设得太短，大模型还没“憋”完字，Nginx 就以为后端挂了，直接断开。
• 如果你用的是 Nginx 反向代理 WebSocket 或者 SSE（Server-Sent Events），有些版本还需要注意 buffer 的设置，尽量关闭 buffer 以保证实时性：

  proxy_buffering off;
  

Caddy 用户请检查： Caddy 的默认超时处理比较智能，但为了保险，可以在 Caddyfile 中显式设置：

reverse_proxy localhost:3000 {
    transport http {
        read_timeout 600s
        write_timeout 600s
    }
}

2. 检查 NewAPI 的渠道设置

很多时候，NewAPI 只是中间商，真正干活的是后面接的“渠道”（Channels）。

• 超时设置：进入 NewAPI 后台，检查你配置的那个渠道的超时时间。有些上游 API 响应确实慢，如果渠道的超时设短了，NewAPI 会主动断开与上游的连接，自然也就无法完整返回给客户端了。建议将超时时间设为 120 秒或更长。
• 通道稳定性：如果你接的是一些三方的中转 API，或者网络环境不佳（比如国内服务器直连 OpenAI），这种连接中断几乎是常态。建议尝试：
  • 更换上游节点。
  • 使用代理中转。

3. 进程与日志排查

如果配置改了还是不行，就得看日志了。

• 查看 NewAPI 日志：不要只看客户端报错。去服务器上跑 NewAPI 的终端或者日志文件里看。如果报的是 context deadline exceeded 或者 EOF，通常就是网络或上游的问题。如果是 NewAPI 自己 Panic 了，那就是 Bug 或者内存不足了。
• 系统资源：用 top 或者 htop 看看服务器内存是不是爆了。流式传输虽然不占大内存，但如果并发上来或者模型很大，OOM（Out of Memory）杀进程也是会秒断连接的。

三、 一个小技巧：命令行模拟测试

为了排除是前端（网页/客户端）的问题，推荐在服务器上用 curl 命令直接测试本地端口：

curl -N http://127.0.0.1:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

（注意替换端口和 Key）。

如果这个命令能完整输出流，但在浏览器里不行，那 100% 是你的反向代理配置有问题；如果 curl 本身也断，那就去查 NewAPI 的日志和网络吧。

总结

stream closed before response.completed 这个报错虽然看着吓人，但其实就是“没耐心”导致的。要么是代理服务器没耐心，要么是上游信道没耐心。按照上面的顺序，先把超时时间拉长，再排查网络，基本就能解决问题了。

如果你还有其他更奇葩的情况，欢迎在评论区交流，大家一起避坑！