504 Gateway Timeout 表明网关放弃等待上游AI服务响应，需通过Developer Tools确认状态码及Server字段，再排查代理、网络、服务端状态、请求负载与缓存问题，并可调整超时或启用降级策略。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在使用 Fitten Code 插件时，代码补全突然卡住、光标悬停无反应、输入后长时间空白，且开发者工具 Network 面板中看到请求返回 504 Gateway Timeout，说明网关已放弃等待上游 AI 服务响应——这不是前端崩溃，而是请求链路在中途被截断。
确认是否真为网关层超时
打开 VS Code 的命令面板（Ctrl+Shift+P / Cmd+Shift+P），执行「Developer: Toggle Developer Tools」→ 切换到 Network 标签页 → 触发一次补全（如输入 const → 按 Ctrl+Space）→ 找到以 /v1/completions 或类似路径结尾的请求 → 点击查看响应头（Response Headers）→ 确认 Status 为 504，且 Server 字段含 nginx、cloudflare、aws-api-gateway 或 scdn 等网关标识。
⚠️ 如果状态码是 502、503 或直接报 connection refused，则问题不在网关超时，无需继续本流程。
检查本地网络与代理配置
方法一：绕过代理直连测试
在 VS Code 设置中搜索 fitten.httpProxy 或 http.proxy，临时清空该值 → 重启 VS Code → 再次触发补全。若此时 504 消失，说明本地代理（如 Clash、Surge、公司 Proxy）正在拦截或转发异常，需检查代理规则是否误将 api.fitten.dev 或对应域名标记为“直连”或“拒绝”。
方法二：用 curl 模拟请求验证链路
在终端执行：curl -v https://api.fitten.dev/v1/health → 观察是否返回 200，或卡在 * Connected to api.fitten.dev 后无响应。若卡住，证明 DNS 解析或 TLS 握手失败；若返回 504，说明网关本身不可达，问题出在公网路由或 CDN 节点。
定位上游服务延迟根因
第一步：确认当前服务端状态
访问 https://www.php.cn/link/a02f16dc538480b69d8b8e53ee8b3d26（如有）或其官方 Twitter/X @FittenCode → 查看是否有「AI inference queue high」、「Model endpoint degraded」等公告。若存在，说明是服务端模型推理队列积压，非本地问题，等待即可。
Fitten Code 1.0.3是一款由清华博士团队打造的AI编程助手，基于国产计图（Jittor）深度学习框架开发。它支持VS Code、JetBrains系列等主流IDE及80多种编程语言。核心功能包括智能代码补全、注释生成、代码解释、Bug检测、单元测试生成等，旨在全方位提升开发效率。该工具对个人用户免费开放。
第二步：检查请求负载是否超标
Fitten Code 默认对单次补全请求限制上下文长度。若你正在编辑一个超长的 .log 文件、未关闭的巨型 JSON 或嵌套 20 层的 JSX，插件可能将整文件内容作为 prompt 发送 → 上游服务需 tokenization + embedding + generate，耗时陡增 → 触发网关超时。此时可尝试：关闭大文件、在设置中启用 fitten.maxContextLines（设为 500 以内）、禁用 fitten.includeFullFile。
第三步：排除缓存失效风暴
若多个团队成员在同一分钟内首次启用 Fitten Code，且服务端未预热模型实例，冷启动 + 全量加载权重会导致首请求 >30s → Nginx 默认 proxy_read_timeout 60s 可能仍不够。此时日志中常出现连续数个 504 后突然恢复，属典型缓存未命中引发的雪崩前兆。
调整客户端超时容忍度（仅限高级用户）
打开 VS Code 的 settings.json（Ctrl+, → 右上角 {} 图标）→ 手动添加字段："fitten.requestTimeoutMs": 120000 → 保存并重启。该值会覆盖插件默认的 45s 超时，给网关更长等待窗口。
⚠️ 注意：此操作不能解决上游慢的问题，仅避免前端过早放弃请求。若上游实际响应需 150s，调至 120000 仍会 504。必须配合服务端优化才有意义。
临时降级补全行为
在设置中启用：
✔️ fitten.enableLocalCache（复用本地历史补全结果，跳过网络请求）
✔️ fitten.fallbackToSnippets（当 AI 补全超时时，自动退回到代码片段补全）
❌ 关闭 fitten.autoTrigger（改为手动 Ctrl+Enter 触发，避免高频试探加重网关压力）
这三步组合可让编辑器在 504 高发期保持基本可用性，不中断编码流。
