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