From bcbd796fa58e6623cbacefb09df3356609c61f0e Mon Sep 17 00:00:00 2001
From: sun <3371392206@qq.com>
Date: Fri, 26 Jun 2026 23:13:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0README=E7=9A=84?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97=E6=9F=A5=E7=9C=8B=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补充了完整的日志分类、示例和排查技巧，优化日志说明结构
---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3a82f9b..3fad183 100644
--- a/README.md
+++ b/README.md
@@ -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"`。
 ### 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拦截:` 日志
 
 ## 部署建议