docs: 更新README的日志查看文档

补充了完整的日志分类、示例和排查技巧,优化日志说明结构
This commit is contained in:
sun
2026-06-26 23:13:03 +08:00
parent 8592843bdf
commit bcbd796fa5
+43 -5
View File
@@ -244,11 +244,49 @@ curl.exe -v -X POST "https://your-app.zeabur.app/v1/audio/speech" -H "Content-Ty
另外 PowerShell 里 `{"foo":"bar"}` 不加单引号会被当成脚本块解析,body 被吃掉所有引号。**要么用单引号包 JSON**,要么把 body 写到文件用 `--data-binary "@file.json"`。 另外 PowerShell 里 `{"foo":"bar"}` 不加单引号会被当成脚本块解析,body 被吃掉所有引号。**要么用单引号包 JSON**,要么把 body 写到文件用 `--data-binary "@file.json"`。
### 6. 查看日志 ### 6. 查看日志
服务启动后会输出详细日志,包括: 服务启动后输出到 stdout/stderr。常见日志关键字:
- 服务启动信息
- 配置状态 **中间件层拒绝**(有专门日志):
- 请求统计信息
- 错误详情 ```
CORS拦截: 来源="https://..." 路径=/v1/audio/speech 方法=POST 客户端=...
警告: 已超过IP速率限制,拒绝请求 - 客户端IP: 1.2.3.4
警告: 已达到最大并发请求数限制,拒绝请求 - 客户端IP: 1.2.3.4
```
**Controller 层拒绝**(每条都带具体原因和客户端 IP):
```
警告: 错误的方法 - 方法=GET 期望=POST 路径=/v1/audio/speech 客户端=...
警告: API Key 鉴权失败 - 路径=/v1/audio/speech 客户端=... 远端=...
警告: TTS配置未就绪,拒绝请求 - 错误=缺少必需的环境变量: [BYTEDANCE_TTS_API_KEY] 路径=...
警告: 请求体过大 - 路径=... 限制=1048576字节
警告: 读取请求体失败 - 路径=... 错误=...
警告: JSON 解析失败 - 路径=... 错误=... body前200字节="..."
警告: Model 名过长 - 路径=... 长度=80 限制=64
警告: Model 名含非法字符 - 路径=... model前50字节="..."
警告: input 字段为空 - 路径=...
警告: input 文本过长 - 路径=... 长度=6000 限制=5000
警告: TTS 合成失败 - 路径=... 文本长度=50 耗时=114ms 错误=...
```
**请求结束通用日志**(每个请求都有,由 Logger 中间件输出):
```
POST /v1/audio/speech 1.2.3.4:56789 200 245ms
POST /v1/audio/speech 1.2.3.4:56789 400 1ms
```
**调试技巧**:
- 排查请求被拒:在 Zeabur 实时日志里搜 `警告:` 或 `CORS拦截:`
- 排查 CORS:搜 `CORS拦截:` 看具体被拒的 origin
- 排查 4xx/5xx:找对应路径的 `POST /v1/audio/speech ... 4xx` 行,再往上翻看 `警告:` 行
- 排查 55000000 等上游错误:搜 `TTS service error` 或 `TTS 合成失败`,看火山返回的 code/message
**静默路径(不会产生日志)**:
- CORS 预检成功的 `OPTIONS ... 204`:完全不打日志(设计如此,避免高频预检刷屏)。CORS 拒绝的 OPTIONS 仍会输出 `CORS拦截:` 日志
## 部署建议 ## 部署建议