DeepSeek API 报错 504 响应超时排查指南：网关超时配置实战避坑指南，手把手步骤拆解

调用 DeepSeek API 时碰到 504 Gateway Timeout，本质上是请求在网关或反向代理层等待上游响应超时，而不是模型本身返回了错误码。很多站长第一反应是去改模型参数，结果白白浪费排查时间。这篇指南从网络链路、代理配置、客户端超时、并发控制四个层面，按顺序拆解排查动作，每一步都给出可直接复制的命令和配置，尽量让你少走弯路。

一、先确认 504 出现在哪一层

504 是网关超时，通常由 Nginx、负载均衡、CDN 或你本地的 HTTP 代理返回。排查第一步不是改代码，而是拿到完整响应头，确认超时来源。

curl -v -X POST https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}],"stream":false}' \
  --max-time 120 2>&1 | tee /tmp/deepseek_504.log

重点看返回头里有没有 Server: nginx、Via、X-Cache 这类字段。如果 Server 是你自己的 Nginx，说明超时发生在你的反向代理；如果没有任何中间层标识，才可能是官方网关侧超时。站长建议先把这条命令跑通，再动配置。

二、前置依赖与基础环境检查

在排查超时前，先排除基础环境问题，否则后面所有配置都是白做。

# 检查 DNS 解析是否稳定
dig api.deepseek.com +short

# 检查 TLS 握手耗时
curl -o /dev/null -s -w "dns:%{time_namelookup} connect:%{time_connect} tls:%{time_appconnect} total:%{time_total}\n" https://api.deepseek.com

# 检查本机出口 IP 是否被限流或封禁
curl -s https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY" -w "\nhttp_code:%{http_code}\n"

如果 time_namelookup 超过 1 秒，先换 DNS；如果 time_appconnect 异常大，检查是否走了不稳定的代理。站长遇到过不少案例，504 其实是本地 DNS 污染导致请求打到了错误节点，换一个干净的解析就恢复了。

三、Nginx 反向代理超时配置实战

💡 关联延伸阅读：如果你在配置过程中遇到相关报错，请参阅站长之前的解决教程：DeepSeek-R1 多模型接入与路由配置教程：接入后调用报错、路由无法保存如何解决？

如果你在 Nginx 后面调用 DeepSeek API，默认的 proxy_read_timeout 是 60 秒。流式输出或长上下文请求很容易超过这个值，直接触发 504。

location /deepseek/ {
    proxy_pass https://api.deepseek.com/;
    proxy_http_version 1.1;
    proxy_set_header Host api.deepseek.com;
    proxy_set_header Connection "";
    proxy_set_header Authorization $http_authorization;
    proxy_set_header Content-Type application/json;

    # 核心超时参数，按业务调整
    proxy_connect_timeout 30s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 关闭缓冲，流式响应必须
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

踩坑要点：proxy_read_timeout 必须大于你客户端设置的最大等待时间，否则客户端还在等，Nginx 已经先返回 504。另外 proxy_buffering off 对流式接口是必须的，开启缓冲会导致数据被攒着不发，表现为长时间无响应后超时。

四、客户端超时与重试策略

客户端侧最常见的坑是超时时间设得太短，或者重试逻辑写错导致雪崩。

# Python requests 示例，显式设置连接和读取超时
python3 - <<'PY'
import requests, os

url = "https://api.deepseek.com/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
    "Content-Type": "application/json"
}
payload = {
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "写一段测试文本"}],
    "stream": False
}

# (连接超时, 读取超时)，读取超时给足 180 秒
try:
    r = requests.post(url, headers=headers, json=payload, timeout=(10, 180))
    print(r.status_code, r.text[:200])
except requests.exceptions.ReadTimeout:
    print("读取超时，检查网络或降低请求复杂度")
PY

重试策略上，站长建议只对 502/503/504 做指数退避重试，最多 2 次，且要加 jitter。不要对所有错误无脑重试，否则并发一上来，504 会变成大面积超时。

五、并发与连接池踩坑要点

高并发场景下，504 往往不是单次请求慢，而是连接池耗尽或后端限流。

# 查看当前到 api.deepseek.com 的连接数
ss -tnp | grep api.deepseek.com | wc -l

# 查看 TIME_WAIT 数量，过高说明连接复用没做好
ss -s | grep -i timewait

要点一：使用 HTTP 长连接和连接池，避免每次请求重新握手。要点二：限制单机并发数，建议从 10 到 20 起步压测，观察 504 比例。要点三：如果使用云厂商 NAT 网关，注意 SNAT 端口耗尽也会表现为超时，需要扩大端口范围或增加出口 IP。

六、流式响应与心跳保活

流式接口如果中间长时间没有数据，中间层会认为连接空闲而断开，表现为 504 或连接重置。

curl -N -X POST https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"讲个长故事"}],"stream":true}' \
  --no-buffer --max-time 600

使用 -N 和 --no-buffer 确保数据实时输出。服务端如果自己封装了 SSE，要记得定期发送注释行作为心跳，防止代理层判定空闲。站长提醒：Nginx 的 proxy_read_timeout 是等待两次数据之间的间隔，不是整个请求的总时长，所以心跳间隔必须小于这个值。

七、日志与监控定位法

没有日志的排查都是猜。至少要在三个位置打点：客户端请求开始与结束、Nginx 的 upstream_response_time、以及应用层的错误码统计。

# Nginx 日志格式中加入 upstream 耗时
log_format deepseek '$remote_addr - $request '
                    'status=$status '
                    'upstream_status=$upstream_status '
                    'upstream_time=$upstream_response_time '
                    'request_time=$request_time';

access_log /var/log/nginx/deepseek_access.log deepseek;

当 upstream_status 为 504 且 upstream_time 接近你设置的超时阈值，说明是上游慢；如果 upstream_time 很小但客户端仍报 504，则要检查客户端到 Nginx 这一段的网络。通过这个区分，能快速锁定是代理配置问题还是上游服务问题。

八、总结与最小排查清单

遇到 DeepSeek API 报错 504，按下面顺序走一遍，基本能覆盖九成场景：

第一，用 curl 带 -v 和 --max-time 确认超时来源；第二，检查 DNS 和 TLS 握手耗时；第三，Nginx 侧把 proxy_read_timeout 调到 300 秒并关闭缓冲；第四，客户端显式设置连接与读取超时，重试只针对 5xx 且加退避；第五，控制并发和连接池，关注 TIME_WAIT 和 SNAT 端口；第六，流式接口加心跳，确保间隔小于代理读超时；第七，日志里记录 upstream 耗时，用数据定位而不是靠感觉。

站长经验：504 本身不可怕，可怕的是不知道它从哪一层冒出来。把上面这些配置和命令固化到你的部署脚本里，下次再遇到超时，五分钟内就能定位到具体环节。