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