调试模式
调试模式会记录每次出站请求、响应头和每个 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() 记录完整响应体。