docs: 补充上游慢速流式传输与三层超时判读 (#62)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Troubleshooting
-wiki_revision: 77dbfc1946d599f06a69afc204297dbe198a0cff
-synchronized_at: 2026-08-25T07:01:14Z
+wiki_revision: 22f9502779d019edbf433d632905eddcb41f648b
+synchronized_at: 2026-08-25T15:08:13Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -69,7 +69,15 @@ LIMIT 10;
 5. 环境代理是否绕开安全 Dial；
 6. 上游返回的结果 URL 是否复用相同客户端。
 
-若 attempt latency 精确接近 Provider HTTP timeout，先检查 `portal/config/settings.yml` 的 `provider.http_timeout_seconds`；同时保证 `worker.lease_seconds` 比它大 5 秒以上。修改后必须重启 Portal，页面中的 ProviderModel timeout 不能突破更短的全局 HTTP timeout。
+若 attempt latency 精确接近 Provider HTTP timeout，说明请求被本地切断，**不能据此判断上游无响应**。`provider.http_timeout_seconds` 作用于 `http.Client.Timeout`，是从发起请求到读完 body 的绝对总时长；上游可能先长时间不返回任何字节（生成阶段），再以低速流式传输大响应体，两段都计入其中。按以下顺序确认：
+
+1. `portal/config/settings.yml` 的 `provider.http_timeout_seconds`，以及 `worker.lease_seconds` 是否比它大 5 秒以上，否则 Portal 拒绝启动；
+2. 管理端的 ProviderModel timeout 不能突破更短的全局 HTTP timeout；
+3. 仍无法判断时，经授权对上游发一次不设客户端上限的受控请求，记录 ttfb、总时长和响应体大小，据此定值；不要靠反复上调超时试错。
+
+修改任何一层后必须重启 Portal。
+
+参考基线（2026-08-25 实测，自定义 Provider 的 `gpt-image-2` 文生图）：生成阶段约 160 秒无任何数据，随后以 17–25 KB/s 流式传输，单次总时长 385–465 秒，响应体 3.4–4.9 MB。同类任务报超时前，先用 `attempts` 中的 `latency_ms` 与该基线比较。
 
 拦截私网是正确行为，不能为联调关闭。需要访问内部 mock 时把 mock 与测试进程放在专用测试网络，并使用测试专用注入点，不在生产配置放行私网。