TOOL 02 // INTERACTIVE TROUBLESHOOTER TREES
交互式部署与流式 API 排障诊断树
简单的 HTTP 状态码列表不足以覆盖运行中的失败。选择你遇到的故障场景，按终端探测结果逐步点击分支，快速定位根本原因、修复代码与恢复边界。
[核心实测结论 / TL;DR]Tinker AI 实测工坊的交互式排障诊断台内置 13 棵有向无环决策树，覆盖四大核心方向：容器访问宿主机 11434 报 ECONNREFUSED/超时、模型静默回退 CPU 掉速 80%、HTTP 200 后 SSE 流中途断流、n8n 节点超时与 JSON 解析失败、浏览器插件 403 CORS 跨域拒绝、DeepSeek-R1 <think> 思考死循环、树莓派 5 欠压/NPU/声卡报错、本地 RAG 向量维度冲突 (1024 vs 768)、AMD Strix Halo 15.5GB 显存锁死 / Arc B580 / DGX Spark 统一内存页缓存挤压，以及 n8n + MCP 工具调用失败。每个叶节点均提供根因分析、可直接复制的修复配置与一行式终端验收命令。
容器连不上宿主机本地模型（Connection Refused / Timeout）
第 1 步：检查宿主机模型服务的监听网卡地址
在宿主机终端执行以下命令，查看 11434 端口绑定的是 127.0.0.1 还是 *:11434 (0.0.0.0)？
终端验证命令 (在对应环境执行)
lsof -nP -iTCP:11434 -sTCP:LISTEN || ss -tlnp | grep 11434
若显示 127.0.0.1:11434，来自 Docker 网桥容器的任何请求都会直接返回 Connection Refused。
选择你看到的实际输出或症状：
TERMINAL DIAGNOSTIC CHEAT SHEET // 终端一行式快速排障命令速查表
本地 AI 与容器部署 6 大高频探测命令
遇到故障不确定从哪棵决策树开始？先在宿主机终端运行以下只读探测命令，根据输出特征直接锁定病灶。
| 排查层级 | 终端一行式探测命令 | 健康基线预期 | 异常特征与对应故障树 |
|---|---|---|---|
| 1. GPU 层卸载比例 | ollama ps | 100% GPU | 显示 65% CPU / 35% GPU → 显存溢出与掉速树 |
| 2. 宿主机监听地址 | ss -tlnp | grep 11434 (or lsof -iTCP:11434) | *:11434 / 0.0.0.0:11434 | 仅 127.0.0.1:11434 → 容器报 ECONNREFUSED 树 |
| 3. CORS 跨域预检 | curl -i -X OPTIONS http://127.0.0.1:11434/api/tags -H "Origin: chrome-extension://test" | HTTP/1.1 204 / 200 | 返回 HTTP 403 Forbidden → 403 CORS 与反代树 |
| 4. 向量维度探测 | curl -s http://127.0.0.1:11434/api/embeddings -d '{"model":"bge-m3","prompt":"a"}' | jq '.embedding|length' | 1024 (bge-m3) / 768 (nomic) | 与向量库表维度不符 → RAG 维度冲突与空检索树 |
| 5. 树莓派欠压与降频 | vcgencmd get_throttled && lspci | throttled=0x0 | 0x50000 或无 Hailo 设备 → 树莓派供电与 NPU 树 |
| 6. 释放常驻显存 | curl -s http://127.0.0.1:11434/api/generate -d '{"model":"qwen2.5:14b","keep_alive":0}' | done_reason: "unload" | 显存仍满 → 运行 nvidia-smi 排查僵死 python/runner |
ALL VERIFIED FIXES IN THIS TREE // 本树涵盖的全部根因与修复方案一览
「容器连不上宿主机本地模型（Connection Refused / Timeout）」包含的 4 类根因与验收命令
修复方案：将宿主机 Ollama 监听地址设为 0.0.0.0
Ollama 默认仅绑定 127.0.0.1:11434。来自 Docker 网桥虚拟网卡（172.17.0.x）的数据包会被宿主机内核直接拒绝。
- macOS 环境：通过 launchctl 设置 OLLAMA_HOST 环境变量，并彻底重启 Ollama 客户端。
- Linux systemd 环境：使用 systemctl edit ollama.service 写入 OLLAMA_HOST=0.0.0.0:11434 并重启服务。
- 安全边界提醒：开放 0.0.0.0 后，请确保云服务器安全组或局域网防火墙未将 11434 暴露至公网。
验证命令：
lsof -nP -iTCP:11434 -sTCP:LISTEN修复方案：将容器内的 localhost 替换为 host.docker.internal
在容器独立的网络命名空间内，localhost / 127.0.0.1 指向容器自身，而不是运行本地模型的宿主机。
- 将容器环境变量 OLLAMA_BASE_URL 或工作流请求地址改为 http://host.docker.internal:11434。
- 在 docker-compose.yml 中补充 extra_hosts: ["host.docker.internal:host-gateway"]。
验证命令：
docker exec tinker-open-webui wget -qO- http://host.docker.internal:11434/api/version修复方案：在 Linux Docker 中显式映射 host-gateway
与 Mac/Windows 的 Docker Desktop 不同，原生 Linux Docker 默认不会往容器 /etc/hosts 注入 host.docker.internal。
- 在 docker-compose.yml 对应服务下添加 extra_hosts: ["host.docker.internal:host-gateway"]。
- 执行 docker compose up -d --force-recreate 重建容器使 hosts 映射生效。
验证命令：
docker exec tinker-open-webui getent hosts host.docker.internal修复方案：在宿主机防火墙放行 Docker 网桥子网请求
Linux 宿主机的 UFW 或 firewalld 拦截了来自 docker0 / 自定义网桥（172.16.0.0/12）发往宿主机 11434 端口的数据包。
- 仅针对 Docker 私有网段（172.16.0.0/12）放行宿主机 11434 TCP 端口，避免对公网敞开。
- 重载防火墙规则并重新在容器内执行探测。
验证命令：
docker exec tinker-open-webui wget -qO- --timeout=5 http://host.docker.internal:11434/api/version