From b4b8ec33ed465e87b73707a845031641bd888709 Mon Sep 17 00:00:00 2001
From: "3371392206@qq.com" <3371392206@qq.com>
Date: Sun, 16 Aug 2026 14:41:07 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99README,=E8=A1=A5?=
 =?UTF-8?q?=E5=85=85BYTEDANCE=5FTTS=5FDEBUG=E8=B0=83=E8=AF=95=E6=97=A5?=
 =?UTF-8?q?=E5=BF=97=E7=8B=AC=E7=AB=8B=E5=B0=8F=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 429 ++++++++++++++++++++++++------------------------------
 1 file changed, 193 insertions(+), 236 deletions(-)

diff --git a/README.md b/README.md
index 8e6cfe3..5ac04b1 100644
--- a/README.md
+++ b/README.md
@@ -2,28 +2,26 @@
 
 ## 项目简介
 
-本项目将字节跳动火山引擎TTS（文本转语音）v3 API封装为OpenAI兼容的TTS API接口，使原本调用OpenAI TTS服务的应用可以无缝切换到火山引擎TTS服务。
+本项目将字节跳动火山引擎TTS（文本转语音）v3 API 封装为 OpenAI 兼容的 TTS API 接口,使原本调用 OpenAI TTS 服务的应用可以无缝切换到火山引擎。
 
 ### 主要特性
 
-- 完全兼容OpenAI `/v1/audio/speech` API接口
-- 支持火山引擎TTS v3 API（HTTP Chunked单向流式）
-- 支持多种音频格式：mp3、ogg_opus、pcm、wav
-- 支持API Key鉴权方式
-- 支持多种发音人和模型版本
-- 内置速率限制和统计功能
-- 支持配置API密钥验证
-- 并发限制：最多同时处理10个请求（保护上游API）
-- 跨平台支持（Windows/Linux/macOS）
+- 完全兼容 OpenAI `/v1/audio/speech` API
+- 支持火山引擎 TTS v3 HTTP Chunked 单向流式 API
+- 支持多种音频格式:mp3 / ogg_opus / pcm / wav(wav 内部转 pcm 后本地拼头)
+- 支持火山复刻 2.0 子模型(`seed-tts-2.0-standard` / `-expressive`)
+- API Key 鉴权、IP 速率限制、全局并发限制
+- 内置 Prometheus 文本格式 `/metrics` 端点,零外部依赖
+- 跨平台支持(Windows / Linux / macOS)
 
 ## 快速开始
 
 ### 前置要求
 
 - Go 1.26 或更高版本
-- 火山引擎账号并开通TTS服务
+- 火山引擎账号并开通 TTS 服务
 
-### 1. 编译程序
+### 1. 编译
 
 ```bash
 go build -o tts-api .
@@ -31,15 +29,13 @@ go build -o tts-api .
 
 ### 2. 配置环境变量
 
-复制 `.env.example` 为 `.env` 并填入你的配置：
+复制 `.env.example` 为 `.env` 并填入实际配置:
 
 ```bash
 cp .env.example .env
 ```
 
-编辑 `.env` 文件，填入必要的配置参数。
-
-### 3. 启动服务
+### 3. 启动
 
 ```bash
 # Windows
@@ -49,289 +45,210 @@ tts-api.exe
 ./tts-api
 ```
 
-服务默认监听 `8080` 端口。
+服务默认监听 `8080` 端口,可通过 `PORT` 环境变量修改。
 
 ## 环境变量配置
 
 ### 必需参数
 
-| 变量名 | 说明 | 示例 |
-|--------|------|------|
-| `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key | `your_api_key_here` |
-| `BYTEDANCE_TTS_RESOURCE_ID` | 资源ID，决定模型版本 | `seed-tts-1.0` |
-| `BYTEDANCE_TTS_SPEAKER` | 发音人（音色）ID | `zh_female_qingxin` |
+| 变量名 | 说明 |
+|--------|------|
+| `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key |
+| `BYTEDANCE_TTS_RESOURCE_ID` | 资源 ID,决定模型版本与计费(`seed-tts-1.0` / `seed-icl-2.0` 等) |
+| `BYTEDANCE_TTS_SPEAKER` | 发音人(音色)ID,复刻音色以 `S_` 开头 |
 
-### 可选参数
+### TTS 行为参数
 
 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
-| `BYTEDANCE_TTS_TIMEOUT` | 请求超时时间 | `30s` |
-| `BYTEDANCE_TTS_FORMAT` | 上游实际请求的音频格式（mp3 / pcm / ogg_opus）；客户端要求 wav 时内部自动转 pcm + 本地拼 WAV 头 | `mp3` |
-| `BYTEDANCE_TTS_SAMPLE_RATE` | 上游采样率（8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000） | `24000` |
-| `BYTEDANCE_TTS_BIT_RATE` | MP3 比特率，仅 mp3 格式生效 | 无 |
-| `BYTEDANCE_TTS_MODEL` | 复刻 2.0 子模型（如 `seed-tts-2.0-standard`、`seed-tts-2.0-expressive`） | 控制台默认 |
-| `BYTEDANCE_TTS_MODEL_TYPE` | 复刻 2.0 模型类型（4=ICL V2, 5=ICL V3） | 无 |
-| `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` | 非中文/英文合成时指定语种（zh-cn / en / ja / es-mx / id / pt-br / ko） | 无 |
-| `BYTEDANCE_TTS_ENABLE_SUBTITLE` | 复刻 2.0 启用字级时间戳 | `false` |
-| `BYTEDANCE_TTS_DEBUG` | 设为 `true` 启用调试日志（sentence 事件、上游请求详情、CORS 拦截等） | `false` |
-| `OPENAI_TTS_API_KEY` | OpenAI兼容接口的API密钥（逗号分隔支持多个） | 无 |
+| `BYTEDANCE_TTS_TIMEOUT` | 单次合成超时 | `30s` |
+| `BYTEDANCE_TTS_FORMAT` | 上游实际请求的音频格式(mp3 / pcm / ogg_opus);客户端要求 wav 时内部自动转 pcm + 本地拼 WAV 头 | `mp3` |
+| `BYTEDANCE_TTS_SAMPLE_RATE` | 上游采样率(8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000) | `24000` |
+| `BYTEDANCE_TTS_BIT_RATE` | MP3 比特率,仅 mp3 生效 | 无 |
+
+### 复刻 2.0 扩展参数
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `BYTEDANCE_TTS_MODEL` | 复刻 2.0 子模型(`seed-tts-2.0-standard` / `seed-tts-2.0-expressive`) | 控制台默认 |
+| `BYTEDANCE_TTS_MODEL_TYPE` | 模型类型(4=ICL V2, 5=ICL V3),推荐显式指定 | 无 |
+| `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` | 非中英文合成时指定语种(zh-cn / en / ja / es-mx / id / pt-br / ko) | 无 |
+| `BYTEDANCE_TTS_ENABLE_SUBTITLE` | 启用字级时间戳(复刻 2.0 生效) | `false` |
+
+### 运行时 / 服务参数
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `OPENAI_TTS_API_KEY` | OpenAI 兼容接口的 API Key(逗号分隔支持多个) | 无(不鉴权) |
 | `PORT` | 服务监听端口 | `8080` |
-| `ALLOWED_ORIGINS` | 允许跨域请求的来源（多个用英文逗号分隔；调试可设为 `*`） | 无（不设则拒绝所有跨域） |
+| `ALLOWED_ORIGINS` | CORS 跨域白名单(逗号分隔,调试可设 `*`;空则拒绝所有跨域) | 无 |
 
 ### Resource ID 说明
 
 | Resource ID | 模型说明 |
 |-------------|----------|
-| `seed-tts-1.0` | 豆包语音合成模型1.0字符版 |
-| `seed-tts-1.0-concurr` | 豆包语音合成模型1.0并发版 |
-| `seed-tts-2.0` | 豆包语音合成模型2.0字符版 |
-| `seed-icl-2.0` | 声音复刻2.0字符版 |
+| `seed-tts-1.0` | 豆包语音合成模型 1.0 字符版 |
+| `seed-tts-1.0-concurr` | 豆包语音合成模型 1.0 并发版 |
+| `seed-tts-2.0` | 豆包语音合成模型 2.0 字符版 |
+| `seed-icl-2.0` | 声音复刻 2.0 字符版 |
 
-> 上表为通用模型名。火山控制台实际显示的资源 ID 字符串格式通常是 `volc.megatts.default`、`volc.megatts.icl` 等（带版本号会形如 `volc.megatts.icl.2_0`），**以控制台资源管理页面显示的字符串为准**。资源 ID 与音色必须**同时在控制台开通**才能组合使用，否则 API 会返回 `code=55000000, message=resource ID is mismatched with speaker related resource`。
+> 上表为通用模型名。火山控制台实际显示的资源 ID 字符串通常是 `volc.megatts.default`、`volc.megatts.icl` 等(带版本号形如 `volc.megatts.icl.2_0`),**以控制台资源管理页面显示的字符串为准**。资源 ID 与音色必须**同时在控制台开通**才能组合使用,否则 API 返回 `code=55000000, message=resource ID is mismatched with speaker related resource`。
 
-**注意：** 复刻音色（speaker 以 `S_` 开头）必须搭配对应的 Resource ID 使用，否则 API 会返回 resource mismatched 错误。
+**注意:** 复刻音色(speaker 以 `S_` 开头)必须搭配对应族的 Resource ID,否则 API 返回 resource mismatched 错误。
 
-### 音频格式说明
+## 调试日志
 
-上游请求格式由 `BYTEDANCE_TTS_FORMAT` 控制（默认 `mp3`），采样率由 `BYTEDANCE_TTS_SAMPLE_RATE` 控制（默认 `24000`）。客户端要求 `wav` 时，内部自动请求 `pcm` 格式并本地拼装 WAV 文件头。HTTP 响应 `Content-Type` 根据最终输出格式动态设置（`audio/mpeg`、`audio/wav`、`audio/ogg` 等）。
+### BYTEDANCE_TTS_DEBUG
 
-### v3 API 调用说明
+服务运行期日志分为**始终输出**和**调试模式才输出**两类。通过 `BYTEDANCE_TTS_DEBUG` 环境变量控制调试日志开关。
 
-本项目按火山 v3 HTTP Chunked 单向流式 TTS API 实现（[官方文档](https://www.volcengine.com/docs/6561/1598757)），相比 v1/v2 有以下关键差异：
+| 值 | 行为 |
+|----|------|
+| 不设置 / `false` | 仅输出错误、警告、启动摘要、成功日志(默认,生产环境推荐) |
+| `true` | 额外输出适配器层调试日志 |
 
-- **协议**：HTTP Chunked 流式，请求路径 `https://openspeech.bytedance.com/api/v3/tts/unidirectional`
-- **不再使用业务集群**（`cluster` 字段在 v3 已废弃），改用 `X-Api-Resource-Id` HTTP header 路由模型
-- **鉴权 header 只有** `X-Api-Key` 一个，无 `Authorization`，无 app 对象
+```bash
+# 启用调试
+BYTEDANCE_TTS_DEBUG=true ./tts-api
+
+# 或写入 .env
+echo "BYTEDANCE_TTS_DEBUG=true" >> .env
+```
+
+启用后启动时会打印:
+
+```
+调试日志已启用 BYTEDANCE_TTS_DEBUG
+```
+
+### 始终输出的日志
+
+启动摘要、错误警告、合成成功/失败、访问日志(Logger 中间件):
+
+```
+[TTS-Server] config.go:238: === 环境配置汇总 ===
+[TTS-Server] config.go:239: 服务端口: 8080
+...
+警告: TTS 合成失败 - 路径=/v1/audio/speech 客户端=... 文本长度=50 耗时=114ms 错误=...
+TTS 合成成功 - 音色=zh_female_qingxin 格式=mp3 文本=50字 音频=12345字节 分片=3 耗时=1.2s
+POST /v1/audio/speech 1.2.3.4:56789 200 1.2s
+```
+
+### 调试模式才输出的日志(`BYTEDANCE_TTS_DEBUG=true`)
+
+适配器层与 CORS 拦截详情:
+
+```
+TTS upstream: resource_id=seed-icl-2.0 speaker=zh_female_qingxin model="seed-tts-2.0-standard" format=mp3 sample_rate=24000 speech_rate=0 additions="..."
+Sentence start: sequence=0, sentence=...
+Sentence end: sequence=0
+TTS 合成结束, usage: text_words=5
+volcano: 忽略未识别事件 event="xxx" sequence=1
+CORS拦截: 来源="https://..." 路径=/v1/audio/speech 方法=POST 客户端=...
+```
+
+> **生产建议:** 默认不开 `BYTEDANCE_TTS_DEBUG`,需要排查问题时再临时开启,避免 sentence 级别日志刷屏。
 
 ## CORS 跨域配置
 
-跨域请求由 `ALLOWED_ORIGINS` 环境变量控制，按**完整 origin**（含协议 + 域名 + 端口）精确匹配：
+跨域请求由 `ALLOWED_ORIGINS` 控制,按**完整 origin**(协议 + 域名 + 端口)精确匹配:
 
 - `https://app.example.com` — 精确匹配一个来源
-- `https://a.com,https://b.com` — 多个来源英文逗号分隔
-- `*` — 允许所有来源（**不可与凭据请求共存**，需同时去掉 `Authorization` 头）
-- `app.example.com` — 缺协议头，**永远不会匹配**（服务端强制校验 `http://` / `https://` 开头）
+- `https://a.com,https://b.com` — 多个来源逗号分隔
+- `*` — 允许所有来源(**不可与凭据请求共存**)
+- `app.example.com` — 缺协议头,**永远不会匹配**(强制校验 `http://` / `https://` 开头)
 
-**典型坑**：
+**典型坑:**
 
-1. 客户端 URL 是 `http://` 但服务端是 `https://`：浏览器按 `http://...` 的 origin 发请求，白名单里的 `https://...` 不会匹配 → 403。**客户端必须用 `https://` 开头**。
-2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`：浏览器按规范会**直接拒绝预检**（凭据 + 通配符冲突），POST 根本发不出去。
-3. 同源请求（前端和 TTS 服务同域名）不受 CORS 限制，`ALLOWED_ORIGINS` 怎么配都不影响。
+1. 客户端是 `http://` 但服务端是 `https://`:浏览器按 `http://...` 的 origin 发请求,白名单里的 `https://...` 不会匹配 → 403。**客户端必须用 `https://` 开头**。
+2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`:浏览器按规范**直接拒绝预检**(凭据 + 通配符冲突),POST 根本发不出去。
+3. 同源请求不受 CORS 限制。
 
 ## API 使用说明
 
 ### OpenAI 兼容接口
 
-**端点：** `POST /v1/audio/speech`
+**端点:** `POST /v1/audio/speech`
 
-**请求头：**
+**请求头:**
 - `Content-Type: application/json`
-- `Authorization: Bearer <你的API密钥>`（如果配置了OPENAI_TTS_API_KEY）
+- `Authorization: Bearer <你的API密钥>`(如果配置了 `OPENAI_TTS_API_KEY`)
+
+**请求体:**
 
-**请求体：**
 ```json
 {
   "model": "tts-1",
-  "input": "你好，这是一个测试文本",
+  "input": "你好,这是一个测试文本",
   "voice": "alloy",
   "response_format": "mp3",
   "speed": 1.0
 }
 ```
 
-**参数说明：**
-- `model` - 模型名称（OpenAI兼容，实际不影响）
-- `input` - 要合成的文本
-- `voice` - 发音人（OpenAI兼容，实际使用配置的BYTEDANCE_TTS_SPEAKER）
-- `response_format` - 输出格式：`mp3`（默认）、`opus`（映射到ogg_opus）、`wav`、`pcm`、`aac`/`flac`（降级到mp3）
-- `speed` - 语速：0.25 ~ 4.0
+**参数说明:**
+- `model` — 模型名(OpenAI 兼容,实际不影响,火山侧用 `BYTEDANCE_TTS_MODEL`)
+- `input` — 要合成的文本
+- `voice` — 发音人(OpenAI 兼容,实际用 `BYTEDANCE_TTS_SPEAKER`)
+- `response_format` — 输出格式:`mp3`(默认)/ `opus`(映射 ogg_opus)/ `wav` / `pcm` / `aac` / `flac`(降级到 mp3)
+- `speed` — 语速,0.25 ~ 4.0(火山侧转换为 speech_rate [-50, 100])
 
-**格式映射（OpenAI → 火山）：**
+**格式映射:**
 
 | OpenAI response_format | 火山 API 格式 | Content-Type |
 |------------------------|--------------|--------------|
 | `mp3` | mp3 | audio/mpeg |
 | `opus` | ogg_opus | audio/ogg |
-| `wav` | pcm → 封装wav header | audio/wav |
+| `wav` | pcm → 本地拼 wav header | audio/wav |
 | `pcm` | pcm | audio/pcm |
-| `aac` / `flac` | mp3（降级） | audio/mpeg |
+| `aac` / `flac` | mp3(降级) | audio/mpeg |
 
-**示例调用：**
+**调用示例:**
 
 ```bash
-# MP3格式（默认）
+# MP3
 curl -X POST "http://localhost:8080/v1/audio/speech" \
   -H "Content-Type: application/json" \
-  -d '{"model":"tts-1","input":"你好，世界","voice":"alloy","speed":1.0}' \
+  -d '{"model":"tts-1","input":"你好,世界","voice":"alloy","speed":1.0}' \
   -o output.mp3
 
-# WAV格式
+# WAV
 curl -X POST "http://localhost:8080/v1/audio/speech" \
   -H "Content-Type: application/json" \
-  -d '{"model":"tts-1","input":"你好，世界","voice":"alloy","response_format":"wav","speed":1.0}' \
+  -d '{"model":"tts-1","input":"你好,世界","voice":"alloy","response_format":"wav"}' \
   -o output.wav
 ```
 
-### 健康检查（含统计信息）
+### 健康检查
 
 ```bash
 curl http://localhost:8080/health
 ```
 
-返回包含：服务状态、请求统计、错误记录、配置检查结果
+返回服务状态、版本、运行时长、内存、配置检查结果(**不鉴权**)。
 
 ## 限流机制
 
-为保护上游火山引擎API，服务实现了两层限流保护：
+为保护上游火山 API,服务实现两层限流:
 
-### 1. 全局并发限制
-- **限制**：最多同时处理 **10个** TTS请求
-- **触发**：超过10个并发请求时
-- **错误码**：`503 Service Unavailable`
-- **说明**：确保不超过上游API的并发限制
+### 全局并发限制
+- 最多同时处理 **10 个** TTS 请求
+- 超过返回 `503 Service Unavailable`
 
-### 2. IP速率限制
-- **限制**：每个IP每分钟 **100个** 请求
-- **触发**：单个IP调用过于频繁
-- **错误码**：`429 Too Many Requests`
-- **说明**：防止单个客户端滥用服务
+### IP 速率限制
+- 每个 IP 每分钟 **100 个** 请求
+- 超过返回 `429 Too Many Requests`
 
-### 触发限流时的响应
-```json
-{
-  "error": {
-    "message": "Server is busy, maximum concurrent requests reached.",
-    "type": "concurrency_limit_error",
-    "code": "max_concurrent_requests"
-  }
-}
-```
-
-### 服务器日志
-触发限流时服务器会输出中文警告日志：
-- `警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: x.x.x.x`
-- `警告: 已超过IP速率限制，拒绝请求 - 客户端IP: x.x.x.x`
-
-## 支持的发音人
-
-具体发音人列表请参考火山引擎官方文档：
-- 1.0音色：https://www.volcengine.com/docs/6561/97454
-- 2.0音色：https://www.volcengine.com/docs/6561/1340515
-
-## 常见问题
-
-### 1. 如何获取鉴权信息？
-
-- 登录火山引擎新版控制台
-- 进入"语音合成"服务
-- 创建应用并获取API Key
-
-### 2. 端口被占用怎么办？
-
-通过环境变量修改端口：
-
-```bash
-# Windows
-set PORT=8081 && tts-api.exe
-
-# Linux/macOS
-PORT=8081 ./tts-api
-```
-
-### 3. 如何配置多个API密钥？
-
-使用逗号分隔：
-
-```bash
-OPENAI_TTS_API_KEY=sk-key1,sk-key2,sk-key3
-```
-
-### 4. 出现 `code=55000000, message=resource ID is mismatched with speaker related resource` 怎么办？
-
-这是火山引擎 v3 API 返回的**资源/音色不匹配**错误，不是网络或超时问题。修复方法：
-
-1. 去**火山控制台** → 语音技术 → 你的应用 → 资源管理或音色库
-2. 用控制台的在线体验/调试试一下同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色
-3. 控制台能合成的组合才是正确的
-4. 把控制台显示的**实际资源 ID 字符串**（通常是 `volc.megatts.*` 格式）填到 `BYTEDANCE_TTS_RESOURCE_ID`
-5. 如果你用的是**声音复刻**音色（speaker 以 `S_` 开头），确认 `BYTEDANCE_TTS_RESOURCE_ID` 已在火山控制台开通，并且和音色 ID 在同一个资源族下。55000000 通常是资源族不匹配
-
-### 5. PowerShell 下 `curl` 命令被解释错
-
-PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名，参数完全不同。**必须写 `curl.exe`**：
-
-```powershell
-curl.exe -v -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_KEY" --data-binary "@body.json"
-```
-
-另外 PowerShell 里 `{"foo":"bar"}` 不加单引号会被当成脚本块解析。**要么用单引号包 JSON**，要么把 body 写到文件用 `--data-binary "@file.json"`。
-
-### 6. WAV 格式音频播放异常？
-
-流式场景下火山 API 的 wav 格式会每个 chunk 都返回完整的 wav header，拼接后音频损坏。本项目已自动处理：选择 wav 输出时，内部用 pcm 格式请求 API，最后拼装标准 wav header。如仍有问题，建议改用 `mp3` 格式。
-
-### 7. 查看日志
-
-服务启动后输出到 stdout/stderr。常见日志关键字：
-
-**中间件层拒绝**（速率/并发警告始终可见；CORS 拦截需 BYTEDANCE_TTS_DEBUG=true）：
+**触发日志(始终输出):**
 
 ```
-CORS拦截: 来源="https://..." 路径=/v1/audio/speech 方法=POST 客户端=...
-警告: 已超过IP速率限制，拒绝请求 - 客户端IP: 1.2.3.4
-警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: 1.2.3.4
+警告: 已达到最大并发请求数限制,拒绝请求 - 客户端IP: 1.2.3.4
+警告: 已超过IP速率限制,拒绝请求 - 客户端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 错误=...
-```
-
-**适配器层日志**（默认静默，设置 `BYTEDANCE_TTS_DEBUG=true` 后可见）：
-
-```
-TTS upstream: resource_id=... speaker=... model=... format=... sample_rate=... speech_rate=... additions=...
-Sentence start: sequence=0, sentence=...
-Sentence end: sequence=0
-TTS 合成结束, usage: text_words=5
-volcano: 忽略未识别事件 event=... sequence=...
-```
-
-**合成结果日志**（每个请求都有）：
-
-```
-TTS 合成成功 - 音色=... 格式=mp3 文本=50字 音频=12345字节 分片=3 耗时=1.2s
-```
-
-或失败时：
-
-```
-警告: TTS 合成失败 - 路径=/v1/audio/speech 客户端=... 文本长度=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
-```
-
-
 ## 观测 / Metrics
 
-服务内置 Prometheus 文本格式的 `/metrics` 端点,**不鉴权**(与 `/health` 一致),
-可直接被 Prometheus 抓取或浏览器查看。Go 进程内埋点,零外部依赖,实现位于 `telemetry/` 与 `metrics/` 包。
+服务内置 Prometheus 文本格式的 `/metrics` 端点,**不鉴权**(与 `/health` 一致),可直接被 Prometheus 抓取或浏览器查看。Go 进程内埋点,零外部依赖,实现位于 `telemetry/` 与 `metrics/` 包。
 
 ### 主要指标
 
@@ -362,8 +279,7 @@ scrape_configs:
 
 ### 仪表盘
 
-`/dashboard` 仍展示服务状态 + 内存 + 配置信息,并内嵌 `/metrics` 的预览;
-Grafana 等工具可直接基于上面指标做面板。
+`/dashboard` 展示服务状态 + 内存 + 配置信息,并内嵌 `/metrics` 预览;Grafana 等工具可直接基于上面指标做面板。
 
 ## 架构
 
@@ -376,14 +292,14 @@ Grafana 等工具可直接基于上面指标做面板。
 | `controller/` | /v1/audio/speech、/health 处理器 |
 | `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 |
 | `setting/` | 单一环境变量入口 + 启动汇总 |
-| `common/`、`dto/` | 常量、请求/响应类型 |
+| `common/`、`dto/` | 常量、请求/响应类型,`common.DebugLog` 控制调试日志 |
 | `router/` | 路由注册 |
 
-## 部署建议
+## 部署
 
-### Linux Systemd 服务
+### Linux Systemd
 
-创建 `/etc/systemd/system/tts-server.service`：
+创建 `/etc/systemd/system/tts-server.service`:
 
 ```ini
 [Unit]
@@ -403,35 +319,76 @@ RestartSec=10
 WantedBy=multi-user.target
 ```
 
-启动服务：
-
 ```bash
 sudo systemctl daemon-reload
 sudo systemctl enable tts-server
 sudo systemctl start tts-server
 ```
 
-### Docker 部署
+### Docker
 
 ```bash
 docker compose up -d
 ```
 
-环境变量通过 `.env` 文件或 docker-compose.yml 传入。
+环境变量通过 `.env` 或 `docker-compose.yml` 传入。
 
-## 许可证
+## 常见问题
 
-本项目采用非商业用途许可协议。您可以免费使用本软件用于非商业目的，但禁止用于任何商业活动。详细条款请参阅 [LICENSE](LICENSE) 文件。
+### 1. `code=55000000, message=resource ID is mismatched with speaker related resource`
+
+资源/音色不匹配。修复:
+
+1. 火山控制台 → 语音技术 → 你的应用 → 资源管理或音色库
+2. 用控制台在线体验/调试同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色
+3. 控制台能合成的组合才是正确的
+4. 把控制台实际显示的资源 ID 字符串(通常是 `volc.megatts.*` 格式)填到 `BYTEDANCE_TTS_RESOURCE_ID`
+5. 复刻音色(speaker 以 `S_` 开头)需确认 Resource ID 已开通且与音色同族
+
+### 2. PowerShell 下 `curl` 解释错
+
+PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名。**必须写 `curl.exe`**:
+
+```powershell
+curl.exe -v -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" --data-binary "@body.json"
+```
+
+JSON 用单引号包,或写到文件用 `--data-binary "@file.json"`。
+
+### 3. WAV 格式音频播放异常
+
+流式场景下火山 API 的 wav 格式每个 chunk 都返回完整 wav header,拼接后损坏。本项目已自动处理:选择 wav 输出时,内部用 pcm 格式请求 API,本地拼装标准 wav header。如仍有问题,改用 `mp3`。
+
+### 4. 调试时如何看详细日志
+
+设置 `BYTEDANCE_TTS_DEBUG=true` 后重启服务,会额外输出上游请求参数、sentence 事件、CORS 拦截等。详见上文「调试日志」一节。
+
+### 5. 多 API Key 配置
+
+```bash
+OPENAI_TTS_API_KEY=sk-key1,sk-key2,sk-key3
+```
+
+### 6. 修改端口
+
+```bash
+PORT=8081 ./tts-api
+```
 
 ## 技术支持
 
-如有问题，请检查：
+如有问题,请检查:
+
 1. 环境变量配置是否正确
-2. 网络是否能访问火山引擎TTS服务
+2. 网络是否能访问火山引擎 TTS 服务
 3. 鉴权信息是否有效
-4. Resource ID与Speaker是否匹配
-5. ALLOWED_ORIGINS 是否包含前端完整 origin（含 https://）
+4. Resource ID 与 Speaker 是否匹配
+5. `ALLOWED_ORIGINS` 是否包含前端完整 origin(含 https://)
 6. 客户端请求 URL 是否以 https:// 开头
-7. 生产环境凭据是否定期轮换（API Key 明文出现在日志/对话中时立刻重置）
-8. 复刻音色（speaker 以 `S_` 开头）确保 `BYTEDANCE_TTS_RESOURCE_ID` 在控制台和音色 ID 同族（参考 `seed-icl-2.0` 等表）
-9. 音频格式是否匹配客户端解码能力（默认 mp3 兼容性最好）
+7. 生产环境凭据是否定期轮换
+8. 复刻音色确保 Resource ID 与音色 ID 同族
+9. 音频格式是否匹配客户端解码能力(默认 mp3 兼容性最好)
+
+## 许可证
+
+本项目采用非商业用途许可协议。详细条款请参阅 [LICENSE](LICENSE) 文件。