跳到主要内容

调试模式

调试模式会记录每次出站请求、响应头和每个 SSE 块,用来定位上游、协议转换和流式问题。

开启方式​

调试模式是运行层配置 debug.stream_log,保存后立即生效,不需要重启。

管理台目前没有这个表单项,可以通过 REST API 或直接改数据库开启。

REST API​

curl -X PUT http://127.0.0.1:17777/api/settings \
-H "Authorization: Bearer <session-token>" \
-H "Content-Type: application/json" \
-d '{"debug.stream_log": "true"}'

直接改数据库(服务停止时)​

sqlite3 ~/.omnigate/omnigate.db \
"INSERT INTO app_config(key,value) VALUES('debug.stream_log','true')
ON CONFLICT(key) DO UPDATE SET value='true'"
omnigate restart

远程数据库用对应客户端执行等价 SQL。

会记录什么​

阶段内容
出站请求提供商、模型、密钥 ID、协议、端点、超时、是否流式、请求体
请求头已脱敏的头,Authorization 截断,包含 auth/key 的头会处理
响应状态状态码、响应头
流式块每个 SSE 块的大小与内容
流式结束EOF、读取错误、是否已提交
缓冲响应状态码、响应体大小、前 500 字符预览
请求失败错误、是否超时、模型

示例:

[DEBUG] Outbound request to upstream
provider: LLM Proxy
model: glm-5
key_id: 1
protocol: openai
endpoint: http://127.0.0.1:33391/v1/chat/completions
timeout_ms: 120000
is_stream: true
request_body: {"messages":[...], "model":"glm-5", ...}

查看日志​

tail -f ~/.omnigate/omnigate.log
tail -f ~/.omnigate/omnigate.log | grep DEBUG
tail -100 ~/.omnigate/omnigate.log | grep DEBUG

安全注意​

  • 请求体会完整记录,生产环境不要长期开启
  • 认证头会被截断/脱敏,但请求体里可能仍有敏感业务数据
  • 排查完及时关闭

典型用途​

  • 上游异常:确认请求是否真的到达提供商、上游返回了什么
  • 协议转换:观察 OpenAI / Anthropic / Responses / Gemini 之间的字段变化
  • 流式中断:逐块定位在哪一个 chunk 断开或损坏
  • 「成功但记成错误」:查看真实状态码、响应头、流式块和错误判定逻辑

性能影响​

调试日志主要增加字符串格式化和磁盘 I/O。高流量时建议:

  • 只在排查期间开启
  • 用日志过滤减少存储
  • 更频繁地轮转日志

实现位置在 internal/proxy/proxy.go:attempt() 记录出站请求与响应,streamResponse() 记录 SSE 块,bufferedResponse() 记录完整响应体。