[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"blog-strapi-article:zh:openrouter-proxy-connection-troubleshooting":3,"blog-article:\u002Fblog\u002Fopenrouter-proxy-connection-troubleshooting":687,"blog-related:\u002Fblog\u002Fopenrouter-proxy-connection-troubleshooting":688,"blog-translations:\u002Fblog\u002Fopenrouter-proxy-connection-troubleshooting":689},{"available":4,"article":5,"relatedArticles":163,"translations":585},true,{"source":6,"id":7,"documentId":8,"translationKey":8,"locale":9,"slug":10,"path":11,"_path":11,"title":12,"description":13,"excerpt":13,"image":14,"publishedAt":15,"updatedAt":16,"author":17,"tags":18,"featured":19,"sortOrder":20,"readingTime":21,"bodyType":22,"bodyBlocks":23,"bodyHtml":162},"strapi",3490,"fffsyc8j0en3qy4lo6kzrae6","zh","openrouter-proxy-connection-troubleshooting","\u002Fblog\u002Fopenrouter-proxy-connection-troubleshooting","OpenRouter 连接失败怎么排查：从 401 到 429 的分层检查","OpenRouter 请求失败时，结合 HTTP 响应、错误体、请求 ID、流阶段和账户状态定位；429、超时或上游错误不能只凭状态码归因。","https:\u002F\u002Fcms.quanqiudaili.com\u002Fuploads\u002Flarge_openrouter_cover_a85707d158.webp","2026-10-21T08:22:13.416Z","2026-10-21T08:22:13.395Z","Global Proxies Team",[],false,0,3,"blocks",[24,30,36,40,44,48,52,57,61,65,69,73,77,81,102,106,110,114,118,122,126,130,134,138,142,146,150,154,158],{"type":25,"children":26},"paragraph",[27],{"text":28,"type":29},"OpenRouter 把多个模型供应商放在一个接口后面，报错也继承了这个结构：有的是你自己的 key 或余额问题，有的是上游供应商限流，有的才是网络。判断的第一步不是换代理 IP，而是拿到确切的 HTTP 状态码。下面按状态码分四层排查，每层给一个检查动作和一条记录字段。","text",{"type":31,"level":32,"children":33},"heading",2,[34],{"text":35,"type":29},"先记录状态码和响应头，再判断故障位置",{"type":25,"children":37},[38],{"text":39,"type":29},"客户端弹的\"请求失败\"没有信息量。用一条最小请求把真实状态码逼出来：",{"type":25,"children":41},[42],{"text":43,"type":29},"```bash\ncurl -i https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n-H \"Authorization: Bearer $OPENROUTER_API_KEY\" \\\n-H \"Content-Type: application\u002Fjson\" \\\n-d '{\"model\":\"你的模型名\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}'\n```",{"type":25,"children":45},[46],{"text":47,"type":29},"记录 HTTP 状态、响应头、响应体中的 `error` 字段及请求 ID（若返回）。没有 HTTP 响应可能是 DNS、连接、TLS 或超时阶段的问题；拿到 HTTP 响应也不代表故障已定位。通用连接检查可用[智能检测助手](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002FSmart-check)。",{"type":31,"level":32,"children":49},[50],{"text":51,"type":29},"根据 401、402 和 403 检查密钥、余额与权限",{"type":53,"children":54},"code",[55],{"text":56,"type":29},"| 状态码 | 含义 | 先查什么 |\n|---|---|---|\n| 401 | key 无效或未带 | key 是否过期、是否带 `Bearer` 前缀 |\n| 402 | 账户或请求额度相关错误的可能表现 | 对照响应体、账户状态和模型计费信息 |\n| 403 | 权限或内容策略拒绝 | 模型是否需要额外授权、请求是否触发审核 |\n| 429 | 速率或供应商限制等可能原因 | 对照错误体、请求 ID、账户状态及 `Retry-After`（若有） |",{"type":25,"children":58},[59],{"text":60,"type":29},"状态码本身不足以证明请求在哪一层失败。查看 OpenRouter 返回的错误内容和请求 ID，并将 407（代理认证响应）与 API 凭据错误分开记录。代理认证方式见[代理白名单和账号密码怎么选](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-whitelist-vs-username-password)。",{"type":31,"level":32,"children":62},[63],{"text":64,"type":29},"遇到 429 时区分速率限制与免费模型额度",{"type":25,"children":66},[67],{"text":68,"type":29},"429 可能与平台速率限制、模型供应商限制或账户\u002F模型条件有关。若响应含 `Retry-After`，按其指示等待；没有该头时不要据此判定额度耗尽，应检查错误体、请求 ID、账户状态和模型信息。错误码见 [OpenRouter 错误文档](https:\u002F\u002Fopenrouter.ai\u002Fdocs\u002Fapi-reference\u002Ferrors)，并可核对服务状态页。",{"type":25,"children":70},[71],{"text":72,"type":29},"若响应提示速率限制或额度问题，应按账户规则降低请求或等待恢复；不以更换 IP 绕过平台限制。代理连接类错误另按网络阶段排查，参见[代理错误排查说明](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-403-429-captcha-troubleshooting)。",{"type":31,"level":32,"children":74},[75],{"text":76,"type":29},"认证和额度正常后，再排查超时、TLS 与 DNS",{"type":25,"children":78},[79],{"text":80,"type":29},"排除前两层后，剩下的才轮到网络：",{"type":82,"format":83,"children":84},"list","unordered",[85,90,94,98],{"type":86,"children":87},"list-item",[88],{"text":89,"type":29},"连接超时：可能在本机网络、代理连接、上游服务或等待响应阶段",{"type":86,"children":91},[92],{"text":93,"type":29},"TLS 握手失败：核对证书链、客户端信任配置和中间层日志",{"type":86,"children":95},[96],{"text":97,"type":29},"DNS 解析失败：记录由哪一侧解析及实际查询结果",{"type":86,"children":99},[100],{"text":101,"type":29},"连接重置：结合发生阶段、请求 ID（如有）和客户端\u002F代理\u002F服务端日志判断",{"type":25,"children":103},[104],{"text":105,"type":29},"按实际失败阶段查看 DNS、TCP 连接、TLS、HTTP 响应和流式响应；`curl -v` 可提供单次终端请求的线索，但不能替代 OpenRouter 请求 ID、错误体及服务端\u002F代理日志。没有相应证据时，不把某种现象归结为唯一原因。",{"type":31,"level":32,"children":107},[108],{"text":109,"type":29},"遇到 403 时核对模型权限、区域策略和服务状态",{"type":25,"children":111},[112],{"text":113,"type":29},"网络或地区变化可以作为排查时记录的环境信息，但当前文档没有证据支持将多账号共用出口直接判定为 403 或风控原因。遇到 403 时应查看响应体、请求 ID、模型权限与区域策略，并核对 [OpenRouter 状态页](https:\u002F\u002Fstatus.openrouter.ai\u002F)；如怀疑网络影响，用受控对照和日志验证，不预设平台规则。",{"type":25,"children":115},[116],{"text":117,"type":29},"排查记录可包含请求时间、状态码、响应头、错误体、请求 ID、模型、流阶段及网络路径；分享前移除 API Key、个人数据和其他敏感字段：",{"type":53,"children":119},[120],{"text":121,"type":29},"| 字段 | 取值示例 |\n|---|---|\n| 时间 | 2026-10-20 14:32 |\n| 状态码 | 429 |\n| 响应头 Retry-After | 20 |\n| 网络路径（如需） | 代理\u002F直连及大致地区，避免公开完整敏感标识 |\n| 请求模型 | 具体模型标识 |",{"type":25,"children":123},[124],{"text":125,"type":29},"该记录用于区分网络、账户、模型和上游问题，不单独证明某一原因。",{"type":31,"level":32,"children":127},[128],{"text":129,"type":29},"FAQ",{"type":31,"level":21,"children":131},[132],{"text":133,"type":29},"429 要等多久",{"type":25,"children":135},[136],{"text":137,"type":29},"有 `Retry-After` 时按其指示等待。没有该头时查看错误体、账户状态和模型限制，再依据服务文档控制重试；连续出现 429 不能单独证明配额耗尽。",{"type":31,"level":21,"children":139},[140],{"text":141,"type":29},"同一个 key 在别的网络能用说明什么",{"type":25,"children":143},[144],{"text":145,"type":29},"说明该 key 在另一条网络下可用，但当前失败仍可能来自网络路径、区域策略、请求差异或服务状态。比较两次请求的错误体、请求 ID、模型参数和服务端日志，不据此单独判断 IP 信誉。",{"type":31,"level":21,"children":147},[148],{"text":149,"type":29},"换网络能解决 401 吗",{"type":25,"children":151},[152],{"text":153,"type":29},"通常应先检查 API 凭据、响应体和权限；更换网络不能修复无效密钥。结合请求返回判断，不将 401 当作代理故障。",{"type":25,"children":155},[156],{"text":157,"type":29},"---",{"type":25,"children":159},[160],{"text":161,"type":29},"若受控测试显示网络路径影响连接稳定性，可按实际需求评估[静态住宅代理 IP](https:\u002F\u002Fwww.quanqiudaili.com\u002Fproduct\u002Fstatic-residential-standard)；它不能解决账户、模型权限或额度问题，也不能据此保证 403 消失。","",[164,290,433],{"source":6,"id":165,"documentId":166,"translationKey":166,"locale":9,"slug":167,"path":168,"_path":168,"title":169,"description":170,"excerpt":170,"image":171,"publishedAt":172,"updatedAt":173,"author":17,"tags":174,"featured":19,"sortOrder":20,"readingTime":32,"bodyType":22,"bodyBlocks":175,"bodyHtml":162},3496,"z40ct6quyyvnlh8ux8zdik0g","proxy-pool-ip-count-sizing","\u002Fblog\u002Fproxy-pool-ip-count-sizing","代理池需要多少 IP：按并发、目标站点和失败率倒推","代理池规模要同时看连接并发、请求速率、目标站限制和账号配额。用实测负载估算容量，再根据出口故障和恢复时间校准冗余。","https:\u002F\u002Fcms.quanqiudaili.com\u002Fuploads\u002Flarge_ip_cover_81e9cdb74b.webp","2026-10-21T08:23:49.934Z","2026-10-21T08:23:49.923Z",[],[176,180,184,188,192,196,200,204,208,212,216,220,224,228,232,236,240,244,248,252,255,259,263,267,271,275,279,282,286],{"type":25,"children":177},[178],{"text":179,"type":29},"代理池规模不能只用同时并发除以单 IP 并发来估算，还要看请求速率、响应时间、目标站限制、账号或 API Key 配额，以及是否需要为账号保留专属出口。本文给出拆分估算方法和记录模板；示例数字只用于演示，最终容量要用获准业务的实测负载校准。",{"type":31,"level":32,"children":181},[182],{"text":183,"type":29},"按峰值并发和单 IP 并发估算所需 IP 数",{"type":25,"children":185},[186],{"text":187,"type":29},"核心只有一个式子：",{"type":25,"children":189},[190],{"text":191,"type":29},"**连接容量所需 IP 数 = ceil（峰值并发 ÷ 实测单 IP 并发）**",{"type":25,"children":193},[194],{"text":195,"type":29},"这里的单 IP 并发应按相同目标、请求类型和观察时段实测。它只给出连接容量约束，不能代表目标站允许的请求速率，也不能解决绑定在账号或 API Key 上的配额。代理接入参数见帮助中心的[参数说明](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002Fintro)。",{"type":31,"level":32,"children":197},[198],{"text":199,"type":29},"目标站频控和响应速度如何影响单 IP 并发",{"type":25,"children":201},[202],{"text":203,"type":29},"请求速率约束要单独估算。稳定负载下，可用请求率（QPS）× 平均响应时间估算平均在途请求数；再与实测单 IP 允许的并发和目标站允许的请求速率比较。突发请求另留余量，并以服务端限额和实际响应为边界。连接数上限与 QPS 上限不是同一个指标，不能互相替代。",{"type":25,"children":205},[206],{"text":207,"type":29},"账号或 API Key 配额触顶时，增加 IP 通常不能解决问题；目标站返回 429 时，应按其响应指示退避并降低请求，不以增加 IP 绕过限制。失败率和延迟只是线索，需结合状态码、失败阶段及代理侧容量记录判断原因。延迟和可用率的记录方法见[代理 IP 可用率、延迟和稳定性怎么测试](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-ip-availability-latency-stability-test)。",{"type":31,"level":32,"children":209},[210],{"text":211,"type":29},"采集、登录和 API 调用各需要多少 IP",{"type":53,"children":213},[214],{"text":215,"type":29},"| 示例场景 | 峰值在途请求 | 实测单 IP 并发假设 | 连接容量估算 | 还需单独确认 |\n|---|---:|---:|---:|---|\n| 公开页面请求 | 50 | 2 | 25 | 允许 QPS、授权范围、请求间隔 |\n| 登录态任务 | 20 | 1 | 20 | 是否需要账号专属且持续保留的出口 |\n| 多账号后台 | 10 | 1 | 10 | 实际同时在线数、平台规则和账号权限 |\n| API 批量调用 | 100 | 5 | 20 | 账号\u002FAPI Key 配额及服务端速率上限 |",{"type":25,"children":217},[218],{"text":219,"type":29},"表内是简化的连接容量算例，没有计入请求速率约束、突发余量和出口故障，因此不是采购数量建议。账号如需持续绑定出口，应按实际需要保留的出口数单独计算，不能直接用同时在线数代替。",{"type":25,"children":221},[222],{"text":223,"type":29},"这张表仅演示连接容量的计算，不是建议采购数量。真实业务应使用获准的请求集测量；代理接入方式见帮助中心的[代理设置](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002Fproxy-Settings)，产品切换、测试和续费见[代理 IP 测试、续费、更换和子账号 FAQ](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-ip-testing-renewal-replacement-subaccount-faq)。",{"type":31,"level":32,"children":225},[226],{"text":227,"type":29},"失败率和延迟升高时，先扩容还是降速",{"type":25,"children":229},[230],{"text":231,"type":29},"可观察失败率、状态码分布、P95 延迟、请求速率和代理侧连接占用。本文不设通用阈值；应先用获准的请求集建立基线，并区分目标站限流、账号配额、网络故障和代理资源耗尽。",{"type":25,"children":233},[234],{"text":235,"type":29},"只有证据指向代理资源瓶颈（例如代理侧连接容量耗尽或出口故障率异常）时，扩容才是候选方案。若平台返回 429，应先按响应要求等待并降低请求；若是账号配额不足，应检查账户限额。对照不同请求速率下的状态码、延迟和代理侧占用，再决定是否需要增加代理资源。",{"type":31,"level":32,"children":237},[238],{"text":239,"type":29},"记录并发、成功率和延迟，判断是否需要扩容",{"type":25,"children":241},[242],{"text":243,"type":29},"一周一行，看趋势不看单日：",{"type":53,"children":245},[246],{"text":247,"type":29},"| 日期 | 峰值并发 | 在用 IP 数 | 成功率 | 429 占比 | P95 延迟 |\n|---|---|---|---|---|---|\n| 2026-10-13 | 42 | 30 | 96.2% | 1.1% | 820ms |\n| 2026-10-14 | 55 | 30 | 91.4% | 3.8% | 1.4s |",{"type":25,"children":249},[250],{"text":251,"type":29},"这是假设案例，不是实测或推荐阈值：并发从 42 增至 55，约增加 31%；成功率从 96.2% 降至 91.4%，下降 4.8 个百分点。它只能提示需要进一步排查，不能单凭两天数据断定 IP 不足。实测应固定请求集、地区和时段，并同时记录状态码、请求速率、出口故障和恢复时间；据此校准冗余和容量。动态住宅的计费及时长口径见帮助中心的[动态住宅 FAQ](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002FFaq\u002FDynamic-Residence-Faq)。",{"type":31,"level":32,"children":253},[254],{"text":129,"type":29},{"type":31,"level":21,"children":256},[257],{"text":258,"type":29},"IP 买得越多越稳吗",{"type":25,"children":260},[261],{"text":262,"type":29},"不是。IP 超过实际并发需要后，单个 IP 的请求密度下降，成本却线性上升。更常见的问题是调度没做好，新 IP 一上线就被打到同一个目标站，等于没扩容。",{"type":31,"level":21,"children":264},[265],{"text":266,"type":29},"动态住宅和静态住宅怎么配比",{"type":25,"children":268},[269],{"text":270,"type":29},"按业务会话要求评估：短时、多地区任务可核对动态住宅代理 IP 的会话和地区规格；需要长期同一出口时核对静态住宅代理 IP 的固定时长与更换条件。账号专属出口需求另行核算，不把两类资源混用当作通用要求。",{"type":31,"level":21,"children":272},[273],{"text":274,"type":29},"池子多大才需要做调度",{"type":25,"children":276},[277],{"text":278,"type":29},"是否需要调度取决于出口数量、任务类型和维护能力，没有适用于所有业务的固定 IP 数门槛。出现出口表现差异或需要按健康状态分配时，可先建立检查、记录和暂停分配规则，再按实际规模决定自动化程度。",{"type":25,"children":280},[281],{"text":162,"type":29},{"type":25,"children":283},[284],{"text":285,"type":29},"--",{"type":25,"children":287},[288],{"text":289,"type":29},"如果你的并发集中在公开页面采集，可以先用[动态住宅代理 IP](https:\u002F\u002Fwww.quanqiudaili.com\u002Fproduct\u002Fdynamic-residential) 跑一轮容量测试，用实测成功率再定最终数量。",{"source":6,"id":291,"documentId":292,"translationKey":292,"locale":9,"slug":293,"path":294,"_path":294,"title":295,"description":296,"excerpt":296,"image":297,"publishedAt":298,"updatedAt":299,"author":17,"tags":300,"featured":19,"sortOrder":20,"readingTime":301,"bodyType":22,"bodyBlocks":302,"bodyHtml":162},3495,"s72p6uye6i8b0jr2mlb0l97b","caddy-nginx-websocket-proxy-configuration","\u002Fblog\u002Fcaddy-nginx-websocket-proxy-configuration","Caddy 与 Nginx 的 WebSocket 代理配置有什么区别：升级头与超时","对比 Caddy 与 Nginx 的 WebSocket 反向代理配置，说明 HTTP\u002F1.1 Upgrade、空闲超时和版本差异，并给出断连排查方法。","https:\u002F\u002Fcms.quanqiudaili.com\u002Fuploads\u002Flarge_caddy_nginx_websocket_cover_7b9d0db2cc.webp","2026-10-21T08:23:34.532Z","2026-10-21T08:23:34.515Z",[],4,[303,307,311,315,319,323,327,331,335,339,343,347,351,355,359,363,367,371,375,379,383,387,391,395,399,402,406,410,414,418,422,426,429],{"type":25,"children":304},[305],{"text":306,"type":29},"两者都能代理 WebSocket。本文示例采用传统 HTTP\u002F1.1 Upgrade：Nginx 需要正确转发升级头；Caddy 的 `reverse_proxy` 会处理升级。连接建立后是否断开，还要看读空闲超时、连接总时长和中间层策略。下面给出配置示例与版本边界。",{"type":25,"children":308},[309],{"text":310,"type":29},"排查时先看握手是否成功，再看连接建立后的断开时间和各层日志。客户端出网代理的协议选择见[HTTP、HTTPS、SOCKS5 代理怎么选](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fhttp-https-socks5-proxy-selection)。",{"type":31,"level":32,"children":312},[313],{"text":314,"type":29},"Nginx 如何配置 WebSocket 升级头和读超时",{"type":25,"children":316},[317],{"text":318,"type":29},"```nginx\nlocation \u002Fws\u002F {\nproxy_pass http:\u002F\u002F127.0.0.1:8080;\nproxy_http_version 1.1;\nproxy_set_header Upgrade $http_upgrade;\nproxy_set_header Connection \"upgrade\";\nproxy_read_timeout 3600s;\nproxy_buffering off;\n}\n```",{"type":25,"children":320},[321],{"text":322,"type":29},"`Upgrade` 与 `Connection` 用于传统 HTTP\u002F1.1 握手；`proxy_read_timeout` 控制两次上游读取之间允许的空闲时间，长空闲连接应按应用心跳和实际链路设置。Nginx 官方文档对 HTTP\u002F1.1 默认值有版本说明：1.29.7 之前需显式设置；示例保留显式配置以兼容较旧版本。升级后的连接按隧道工作，不能把普通 HTTP 响应缓冲直接当作握手条件。长连接保活见[WebSocket 代理如何保持长连接](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fwebsocket-proxy-long-lived-connection)。",{"type":31,"level":32,"children":324},[325],{"text":326,"type":29},"Caddy 如何用 reverse_proxy 转发 WebSocket",{"type":25,"children":328},[329],{"text":330,"type":29},"```caddyfile\nexample.com {\nreverse_proxy 127.0.0.1:8080\n}\n```",{"type":25,"children":332},[333],{"text":334,"type":29},"这就够了。Caddy 会在转发时处理升级，不需要手写 `Upgrade` 和 `Connection`。只有业务需要限制整条流连接的最长存活时间时才设置 `stream_timeout`；它不是空闲超时，达到上限时活动连接也会关闭。外层 `example.com { }` 与上面相同：",{"type":25,"children":336},[337],{"text":338,"type":29},"```caddyfile\nreverse_proxy 127.0.0.1:8080 {\nstream_timeout 24h\n}\n```",{"type":25,"children":340},[341],{"text":342,"type":29},"`stream_timeout` 限制流连接总时长，默认不设此上限；不要用它代替心跳或空闲检测。配置重载时的 `stream_close_delay` 是另一项行为。`transport http` 的读写超时也应按对应文档和应用行为核实。配置项见 [Caddy reverse_proxy 文档](https:\u002F\u002Fcaddyserver.com\u002Fdocs\u002Fcaddyfile\u002Fdirectives\u002Freverse_proxy)。",{"type":25,"children":344},[345],{"text":346,"type":29},"代理本身的主机、端口和鉴权写法，见帮助中心的[代理设置](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002Fproxy-Settings)。",{"type":31,"level":32,"children":348},[349],{"text":350,"type":29},"升级头、空闲超时和响应缓冲会怎样影响连接",{"type":53,"children":352},[353],{"text":354,"type":29},"| 对比项 | Nginx | Caddy | 实际影响 |\n|---|---|---|---|\n| HTTP\u002F1.1 Upgrade | 通常需显式转发升级头；HTTP\u002F1.1 默认值受版本影响 | `reverse_proxy` 处理升级 | 配置与版本不匹配可能导致握手失败 |\n| 空闲读超时 | `proxy_read_timeout` 控制上游读取空闲间隔 | 依据具体传输配置 | 按心跳和链路实际空闲策略判断 |\n| 流连接总时长 | 由具体配置决定 | `stream_timeout` 可设总时长上限 | 到时会关闭活动连接 |\n| 响应缓冲 | Upgrade 后是双向隧道；按实际数据路径排查 | 流式转发 | 不作为握手成功的必备条件 |\n| 证书 | 需另配 certbot | 自动申请续期 | 部署步骤数量不同 |\n| HTTP\u002F2 | 取决于客户端与服务器实现 | 取决于实现 | RFC 8441 定义扩展 CONNECT，支持情况需逐端核实 |",{"type":25,"children":356},[357],{"text":358,"type":29},"若使用传统 Upgrade，按 HTTP\u002F1.1 握手流程排查；HTTP\u002F2 扩展 CONNECT 是否可用取决于客户端、代理和上游实现。若只有特定目标失败，比较该目标的响应和代理日志，不要直接归因于出口。",{"type":31,"level":32,"children":360},[361],{"text":362,"type":29},"如何设置 WebSocket 保活间隔并定位断连",{"type":31,"level":21,"children":364},[365],{"text":366,"type":29},"按链路最短空闲超时设置 ping 间隔",{"type":25,"children":368},[369],{"text":370,"type":29},"链路上任一层的空闲策略都可能关闭连接，实际时限需查对应 CDN、负载均衡和应用配置，并用边缘及后端日志测量。不要把未经核实的固定秒数当作通用默认值。应用层心跳间隔应依据实测到的最短空闲时限设置，并留出网络抖动余量。",{"type":31,"level":21,"children":372},[373],{"text":374,"type":29},"握手失败或连接中断时按四步排查",{"type":25,"children":376},[377],{"text":378,"type":29},"排障按这个顺序走，不要跳步：",{"type":25,"children":380},[381],{"text":382,"type":29},"1. `curl -i -N -H \"Connection: Upgrade\" -H \"Upgrade: websocket\" -H \"Sec-WebSocket-Version: 13\" -H \"Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==\" http:\u002F\u002F你的域名\u002Fws\u002F`，看是否返回 `101 Switching Protocols`\n2. 没有 101 就查 Nginx 的头和 `proxy_pass` 路径\n3. 有 101 但很快断，记录断开间隔并对照各层实际超时配置与日志\n4. 断得没有规律，结合代理、CDN 和后端日志检查连接限制或异常关闭原因",{"type":31,"level":21,"children":384},[385],{"text":386,"type":29},"根据 400、502、504 和固定时长断连定位故障层",{"type":25,"children":388},[389],{"text":390,"type":29},"出现下面这些现象时，先查对应的一层，不要先改代理：",{"type":53,"children":392},[393],{"text":394,"type":29},"| 现象 | 先查哪一层 | 判断动作 |\n|---|---|---|\n| 握手返回 400 或 426 | Nginx 升级头 | 核对 `Upgrade`、`Connection` 和 HTTP\u002F1.1 |\n| 返回 502 | 后端 | 后端进程、端口、路径是否与 `proxy_pass` 一致 |\n| 返回 504 | Nginx 读超时 | 看后端处理耗时，再调 `proxy_read_timeout` |\n| 101 之后 60 秒整断 | Nginx | `proxy_read_timeout` 仍是默认值 |\n| 101 后固定时长断开 | CDN、负载均衡或应用 | 对照该层配置及日志确认空闲策略 |\n| 消息延迟或成批到达 | 应用写入、代理或中间层 | 检查数据流和缓冲行为，不据此判断握手失败 |",{"type":25,"children":396},[397],{"text":398,"type":29},"超时、连接被拒和 TLS 证书错误是三组不同原因：超时多半卡在链路或上游，连接被拒说明端口那头没在听，证书错误说明中间有人在拦截或替换证书。先按 curl 报出的类型分开，再决定动哪一端。",{"type":31,"level":32,"children":400},[401],{"text":129,"type":29},{"type":31,"level":21,"children":403},[404],{"text":405,"type":29},"Caddy 还要不要显式写 Upgrade 头",{"type":25,"children":407},[408],{"text":409,"type":29},"不用。v2 的 reverse_proxy 会自动处理升级，手写反而可能覆盖掉它自己的逻辑。只有当你需要改写头内容时才用 `header_up`。",{"type":31,"level":21,"children":411},[412],{"text":413,"type":29},"Nginx 报 502 和 504 分别查什么",{"type":25,"children":415},[416],{"text":417,"type":29},"502 是后端拒绝或崩溃，查后端进程和端口；504 是后端在超时内没响应，查 `proxy_read_timeout` 和后端处理耗时。两者都不指向代理 IP 本身。",{"type":31,"level":21,"children":419},[420],{"text":421,"type":29},"HTTP\u002F2 下 WebSocket 还能用吗",{"type":25,"children":423},[424],{"text":425,"type":29},"RFC 8441 定义了 HTTP\u002F2 的扩展 CONNECT；是否可用取决于客户端、代理及服务端实现。本文配置示例采用传统 HTTP\u002F1.1 Upgrade，部署时应核实整条链路支持的方式。",{"type":25,"children":427},[428],{"text":157,"type":29},{"type":25,"children":430},[431],{"text":432,"type":29},"如果长连接主要面向需要稳定出口的业务后台，用[静态住宅代理 IP](https:\u002F\u002Fwww.quanqiudaili.com\u002Fproduct\u002Fstatic-residential-standard) 比频繁更换出口更省事，出口固定之后，超时和缓冲问题也更容易复现。",{"source":6,"id":434,"documentId":435,"translationKey":435,"locale":9,"slug":436,"path":437,"_path":437,"title":438,"description":439,"excerpt":439,"image":440,"publishedAt":441,"updatedAt":442,"author":17,"tags":443,"featured":19,"sortOrder":20,"readingTime":21,"bodyType":22,"bodyBlocks":444,"bodyHtml":162},3494,"wr2sddq3u4r8i6w15lxd9ofv","deepseek-cursor-proxy-setup","\u002Fblog\u002Fdeepseek-cursor-proxy-setup","DeepSeek 在 Cursor 中怎么配置：API 地址、代理和排障","在 Cursor 中配置 DeepSeek 自定义 API Key 和 Base URL 后，分别验证本机网络、Cursor 请求及服务端响应；实际路径和模型名称需按当前版本核对。","https:\u002F\u002Fcms.quanqiudaili.com\u002Fuploads\u002Flarge_deepseek_cursor_cover_6b15e6639b.webp","2026-10-21T08:23:18.321Z","2026-10-21T08:23:18.310Z",[],[445,449,453,457,461,465,469,473,477,481,495,499,503,507,511,515,519,523,527,531,535,539,543,547,551,554,558,562,566,570,574,578,581],{"type":25,"children":446},[447],{"text":448,"type":29},"在 Cursor 使用 DeepSeek 自定义 API Key 时，需要配置服务地址和凭据，并分别检查本机网络、Cursor 的请求路径及模型服务端响应。Cursor BYOK 请求不一定与本机 `curl` 走同一条端到端链路，因此终端测试不能单独证明 Cursor 请求成功。具体界面和路径应按当前 Cursor 与 DeepSeek 文档核实。",{"type":31,"level":32,"children":450},[451],{"text":452,"type":29},"用状态码和终端请求区分模型配置与代理故障",{"type":25,"children":454},[455],{"text":456,"type":29},"模型接入错了，表现是 401、404 或\"model not found\"；网络出口错了，表现是超时、连接被重置、流式输出卡住。前者看 key 和地址，后者看代理和兼容模式，混着查只会来回改配置。顺带说清一个常见混淆：业务场景里代理和 VPN 的差别决定了你要的是固定出口还是临时改道。",{"type":25,"children":458},[459],{"text":460,"type":29},"本机 `curl` 可用于检查本机到 API 端点的连通性及该请求的凭据响应；Cursor 内失败时，还要核对 Cursor 的请求记录和服务端日志，不能据此排除 Cursor 到模型服务之间的问题。",{"type":31,"level":32,"children":462},[463],{"text":464,"type":29},"在 Cursor 中填写 DeepSeek API Key 和 Base URL",{"type":25,"children":466},[467],{"text":468,"type":29},"打开 Cursor Settings > Models，在 OpenAI API Key 一栏填入 DeepSeek 的 key（不是 Cursor 自己的 key），再打开 **Override OpenAI Base URL** 填 `https:\u002F\u002Fapi.deepseek.com\u002Fv1`。",{"type":25,"children":470},[471],{"text":472,"type":29},"基础地址可使用 `https:\u002F\u002Fapi.deepseek.com`；是否在 Base URL 中包含 `\u002Fv1`，取决于当前 Cursor 版本如何拼接最终请求路径。配置前核对最终 URL，避免路径重复或缺失导致 404。模型名称也应以 DeepSeek 当前模型目录及 Cursor 实际请求为准，不要仅凭旧别名判断接入成功。",{"type":31,"level":32,"children":474},[475],{"text":476,"type":29},"让 Cursor 通过系统代理发送模型请求",{"type":25,"children":478},[479],{"text":480,"type":29},"Cursor 没有单独的\"代理地址\"输入框，它跟随系统代理或环境变量（`HTTPS_PROXY`）。在需要经过代理的网络里，还要处理流式传输：",{"type":82,"format":83,"children":482},[483,487,491],{"type":86,"children":484},[485],{"text":486,"type":29},"Cursor 默认用 HTTP\u002F2 双向流拿响应，部分代理会缓冲这种流，表现为回复长时间空白然后一次性出现",{"type":86,"children":488},[489],{"text":490,"type":29},"遇到这种情况，去 Cursor Settings > Network，把 HTTP Compatibility Mode 切到 HTTP\u002F1.1，重启 Cursor",{"type":86,"children":492},[493],{"text":494,"type":29},"官方会在 HTTP\u002F2 不通时自动回退到 HTTP\u002F1.1 的 SSE，但回退不是瞬时的，手动切换更快",{"type":25,"children":496},[497],{"text":498,"type":29},"以上行为以 [Cursor 网络配置文档](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fenterprise\u002Fnetwork-configuration) 为准；界面文案和默认值会随版本变化，以当前设置页为准。",{"type":25,"children":500},[501],{"text":502,"type":29},"代理本身的接入方式（主机、端口、账号密码）见帮助中心的[代理设置](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002Fproxy-Settings) 页面，各客户端写法不同，但出口是同一个。",{"type":31,"level":32,"children":504},[505],{"text":506,"type":29},"从 API 连通性到 Cursor 对话逐步验证",{"type":31,"level":21,"children":508},[509],{"text":510,"type":29},"依次检查 API 凭据、代理出口和 Cursor 对话",{"type":25,"children":512},[513],{"text":514,"type":29},"按顺序做，每一步都能独立判断：",{"type":25,"children":516},[517],{"text":518,"type":29},"1. 在终端请求当前 DeepSeek 文档列出的端点，记录最终 URL、状态码和响应体；这只验证该终端请求。\n2. 如需测试代理，可对同一条终端请求添加代理参数，并记录连接阶段、状态码和响应；这不能代表 Cursor 使用了相同链路。\n3. 在 Cursor 内发起一次请求，记录 Cursor 版本、设置项、时间及界面错误；不要把逐字输出或 UI 模型标签当作服务提供方证明。\n4. 如能查看自定义服务端日志，使用脱敏 request ID、时间戳、实际 model 字段和用量核对是否收到 Cursor 请求。",{"type":31,"level":21,"children":520},[521],{"text":522,"type":29},"对照返回结果确认每一步是否通过",{"type":25,"children":524},[525],{"text":526,"type":29},"每一步的通过标准可以对照下表，避免\"看起来能连\"就往下走：",{"type":53,"children":528},[529],{"text":530,"type":29},"| 步骤 | 要确认的东西 | 通过标准 |\n|---|---|---|\n| 终端验 key | key 是否有效、端点路径是否正确 | 返回 JSON 模型列表，无 401\u002F404 |\n| 终端验代理 | 代理能否到 `api.deepseek.com` | 与直连结果一致，延迟稳定 |\n| Cursor 请求 | Cursor 是否成功提交并收到响应 | 记录实际错误、时间和请求 ID（如可用） |\n| 服务端核对 | 自定义服务是否收到请求 | 对照脱敏 request ID、实际 model 字段及用量 |\n| 网络路径 | 哪一段连接失败 | 分开记录本机网络、Cursor 到服务端和服务端上游日志 |",{"type":25,"children":532},[533],{"text":534,"type":29},"主机、端口和出口 IP 不是一回事，三者的对应关系见[代理主机、端口和出口 IP 有什么区别](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-host-port-exit-ip-difference)。",{"type":25,"children":536},[537],{"text":538,"type":29},"如怀疑网络变化与连接重置有关，记录对应请求时间、连接阶段及代理日志，再检查 Cursor 与服务端各自的链路；仅看到出口 IP 变化不能证明故障由此造成。代理认证方式见[代理白名单和账号密码怎么选](https:\u002F\u002Fwww.quanqiudaili.com\u002Fblog\u002Fproxy-whitelist-vs-username-password)。",{"type":31,"level":32,"children":540},[541],{"text":542,"type":29},"根据 401、404、超时和流式输出异常排查",{"type":53,"children":544},[545],{"text":546,"type":29},"| 现象 | 最可能原因 | 检查动作 |\n|---|---|---|\n| 401 Unauthorized | 凭据无效、权限或请求配置问题 | 检查服务端错误体、凭据来源和权限；勿在日志暴露密钥 |\n| 404 Not Found | 最终路径、模型或端点不匹配 | 记录实际请求 URL，并按客户端文档核对路径拼接 |\n| 402 或额度报错 | 余额、额度或模型计费条件 | 查看账户状态和响应体的具体错误字段 |\n| 请求超时 | 可能发生在本机、Cursor 或上游链路 | 对照请求阶段、Cursor 诊断信息、服务端日志和代理日志 |\n| 回复延迟或中断 | 流式协议、网络、中间层或服务端处理 | 比较兼容模式并查看对应阶段日志，不预设唯一原因 |\n| 偶发连接重置 | 连接路径或服务端\u002F中间层异常 | 记录时间、request ID、连接阶段和相关日志 |",{"type":25,"children":548},[549],{"text":550,"type":29},"超时、连接被拒和证书错误要分开判断：前者看链路，后两者看端口和中间设备。只想确认链路通不通，可以打开帮助中心的[智能检测助手](https:\u002F\u002Fhelp.quanqiudaili.com\u002Fdocs\u002FSmart-check)。",{"type":31,"level":32,"children":552},[553],{"text":129,"type":29},{"type":31,"level":21,"children":555},[556],{"text":557,"type":29},"Base URL 到底要不要带 \u002Fv1",{"type":25,"children":559},[560],{"text":561,"type":29},"不一定。按当前 Cursor 版本确认它会如何拼接路径，并以最终请求 URL 为准；若客户端已自动添加 `\u002Fv1`，Base URL 再包含它可能造成重复路径。",{"type":31,"level":21,"children":563},[564],{"text":565,"type":29},"代理开着，Cursor 还是报错怎么办",{"type":25,"children":567},[568],{"text":569,"type":29},"终端 `curl` 只能验证该终端请求。记录 Cursor 的错误和版本，并核对代理日志、Cursor 诊断信息及自定义服务端是否收到请求；各段结果对照后再定位故障。",{"type":31,"level":21,"children":571},[572],{"text":573,"type":29},"自定义 key 和 Cursor 订阅额度是什么关系",{"type":25,"children":575},[576],{"text":577,"type":29},"两套计费：用自定义 key 时走 DeepSeek 账户余额，Cursor 的请求额度不参与；反过来，Cursor 自带模型的额度也抵扣不了 DeepSeek 的费用。",{"type":25,"children":579},[580],{"text":157,"type":29},{"type":25,"children":582},[583],{"text":584,"type":29},"若日志确认出口切换造成连接中断，可按实际会话要求评估[静态住宅代理 IP](https:\u002F\u002Fwww.quanqiudaili.com\u002Fproduct\u002Fstatic-residential-standard)；这不能解决 Cursor 服务端、API 地址或鉴权问题。",[586],{"source":6,"id":7,"documentId":8,"translationKey":8,"locale":9,"slug":10,"path":11,"_path":11,"title":12,"description":13,"excerpt":13,"image":14,"publishedAt":15,"updatedAt":16,"author":17,"tags":587,"featured":19,"sortOrder":20,"readingTime":21,"bodyType":22,"bodyBlocks":588,"bodyHtml":162},[],[589,592,595,598,601,604,607,610,613,616,619,622,625,628,642,645,648,651,654,657,660,663,666,669,672,675,678,681,684],{"type":25,"children":590},[591],{"text":28,"type":29},{"type":31,"level":32,"children":593},[594],{"text":35,"type":29},{"type":25,"children":596},[597],{"text":39,"type":29},{"type":25,"children":599},[600],{"text":43,"type":29},{"type":25,"children":602},[603],{"text":47,"type":29},{"type":31,"level":32,"children":605},[606],{"text":51,"type":29},{"type":53,"children":608},[609],{"text":56,"type":29},{"type":25,"children":611},[612],{"text":60,"type":29},{"type":31,"level":32,"children":614},[615],{"text":64,"type":29},{"type":25,"children":617},[618],{"text":68,"type":29},{"type":25,"children":620},[621],{"text":72,"type":29},{"type":31,"level":32,"children":623},[624],{"text":76,"type":29},{"type":25,"children":626},[627],{"text":80,"type":29},{"type":82,"format":83,"children":629},[630,633,636,639],{"type":86,"children":631},[632],{"text":89,"type":29},{"type":86,"children":634},[635],{"text":93,"type":29},{"type":86,"children":637},[638],{"text":97,"type":29},{"type":86,"children":640},[641],{"text":101,"type":29},{"type":25,"children":643},[644],{"text":105,"type":29},{"type":31,"level":32,"children":646},[647],{"text":109,"type":29},{"type":25,"children":649},[650],{"text":113,"type":29},{"type":25,"children":652},[653],{"text":117,"type":29},{"type":53,"children":655},[656],{"text":121,"type":29},{"type":25,"children":658},[659],{"text":125,"type":29},{"type":31,"level":32,"children":661},[662],{"text":129,"type":29},{"type":31,"level":21,"children":664},[665],{"text":133,"type":29},{"type":25,"children":667},[668],{"text":137,"type":29},{"type":31,"level":21,"children":670},[671],{"text":141,"type":29},{"type":25,"children":673},[674],{"text":145,"type":29},{"type":31,"level":21,"children":676},[677],{"text":149,"type":29},{"type":25,"children":679},[680],{"text":153,"type":29},{"type":25,"children":682},[683],{"text":157,"type":29},{"type":25,"children":685},[686],{"text":161,"type":29},null,[],[]]