sun/Volcano-Engine-TTS-UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

docs: 重写README,补充BYTEDANCE_TTS_DEBUG调试日志独立小节

Browse Source
This commit is contained in:
sun
2026-08-16 14:41:07 +08:00
parent cdd143f7e2
commit b4b8ec33ed
1 changed files with 193 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+193 -236
View File
@@ -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接口 - 完全兼容 OpenAI `/v1/audio/speech` API
- 支持火山引擎TTS v3 API（HTTP Chunked单向流式） - 支持火山引擎 TTS v3 HTTP Chunked 单向流式 API
- 支持多种音频格式：mp3、ogg_opus、pcm、wav - 支持多种音频格式:mp3 / ogg_opus / pcm / wav(wav 内部转 pcm 后本地拼头)
- 支持API Key鉴权方式 - 支持火山复刻 2.0 子模型(`seed-tts-2.0-standard` / `-expressive`)
- 支持多种发音人和模型版本 - API Key 鉴权、IP 速率限制、全局并发限制
- 内置速率限制和统计功能 - 内置 Prometheus 文本格式 `/metrics` 端点,零外部依赖
- 支持配置API密钥验证 - 跨平台支持(Windows / Linux / macOS)
- 并发限制：最多同时处理10个请求（保护上游API）
- 跨平台支持（Windows/Linux/macOS）
## 快速开始 ## 快速开始
### 前置要求 ### 前置要求
- Go 1.26 或更高版本 - Go 1.26 或更高版本
- 火山引擎账号并开通TTS服务 - 火山引擎账号并开通 TTS 服务
### 1. 编译程序 ### 1. 编译
```bash ```bash
go build -o tts-api . go build -o tts-api .
@@ -31,15 +29,13 @@ go build -o tts-api .
### 2. 配置环境变量 ### 2. 配置环境变量
复制 `.env.example` 为 `.env` 并填入你的配置： 复制 `.env.example` 为 `.env` 并填入实际配置:
```bash ```bash
cp .env.example .env cp .env.example .env
``` ```
编辑 `.env` 文件，填入必要的配置参数。 ### 3. 启动
### 3. 启动服务
```bash ```bash
# Windows # Windows
@@ -49,289 +45,210 @@ tts-api.exe
./tts-api ./tts-api
``` ```
服务默认监听 `8080` 端口。 服务默认监听 `8080` 端口,可通过 `PORT` 环境变量修改。
## 环境变量配置 ## 环境变量配置
### 必需参数 ### 必需参数
| 变量名 | 说明 | 示例 | | 变量名 | 说明 |
|--------|------|------| |--------|------|
| `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key | `your_api_key_here` | | `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key |
| `BYTEDANCE_TTS_RESOURCE_ID` | 资源ID，决定模型版本 | `seed-tts-1.0` | | `BYTEDANCE_TTS_RESOURCE_ID` | 资源 ID,决定模型版本与计费(`seed-tts-1.0` / `seed-icl-2.0` 等) |
| `BYTEDANCE_TTS_SPEAKER` | 发音人（音色）ID | `zh_female_qingxin` | | `BYTEDANCE_TTS_SPEAKER` | 发音人(音色)ID,复刻音色以 `S_` 开头 |
### 可选参数 ### TTS 行为参数
| 变量名 | 说明 | 默认值 | | 变量名 | 说明 | 默认值 |
|--------|------|--------| |--------|------|--------|
| `BYTEDANCE_TTS_TIMEOUT` | 请求超时时间 | `30s` | | `BYTEDANCE_TTS_TIMEOUT` | 单次合成超时 | `30s` |
| `BYTEDANCE_TTS_FORMAT` | 上游实际请求的音频格式（mp3 / pcm / ogg_opus）；客户端要求 wav 时内部自动转 pcm + 本地拼 WAV 头 | `mp3` | | `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_SAMPLE_RATE` | 上游采样率(8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000) | `24000` |
| `BYTEDANCE_TTS_BIT_RATE` | MP3 比特率，仅 mp3 格式生效 | 无 | | `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） | 无 | ### 复刻 2.0 扩展参数
| `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_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` | | `PORT` | 服务监听端口 | `8080` |
| `ALLOWED_ORIGINS` | 允许跨域请求的来源（多个用英文逗号分隔；调试可设为 `*`） | 无（不设则拒绝所有跨域） | | `ALLOWED_ORIGINS` | CORS 跨域白名单(逗号分隔,调试可设 `*`;空则拒绝所有跨域) | 无 |
### Resource ID 说明 ### Resource ID 说明
| Resource ID | 模型说明 | | Resource ID | 模型说明 |
|-------------|----------| |-------------|----------|
| `seed-tts-1.0` | 豆包语音合成模型1.0字符版 | | `seed-tts-1.0` | 豆包语音合成模型 1.0 字符版 |
| `seed-tts-1.0-concurr` | 豆包语音合成模型1.0并发版 | | `seed-tts-1.0-concurr` | 豆包语音合成模型 1.0 并发版 |
| `seed-tts-2.0` | 豆包语音合成模型2.0字符版 | | `seed-tts-2.0` | 豆包语音合成模型 2.0 字符版 |
| `seed-icl-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` ```bash
- **不再使用业务集群**（`cluster` 字段在 v3 已废弃），改用 `X-Api-Resource-Id` HTTP header 路由模型 # 启用调试
- **鉴权 header 只有** `X-Api-Key` 一个，无 `Authorization`，无 app 对象 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 跨域配置 ## CORS 跨域配置
跨域请求由 `ALLOWED_ORIGINS` 环境变量控制，按**完整 origin**（含协议 + 域名 + 端口）精确匹配： 跨域请求由 `ALLOWED_ORIGINS` 控制,按**完整 origin**(协议 + 域名 + 端口)精确匹配:
- `https://app.example.com` — 精确匹配一个来源 - `https://app.example.com` — 精确匹配一个来源
- `https://a.com,https://b.com` — 多个来源英文逗号分隔 - `https://a.com,https://b.com` — 多个来源逗号分隔
- `*` — 允许所有来源（**不可与凭据请求共存**，需同时去掉 `Authorization` 头） - `*` — 允许所有来源(**不可与凭据请求共存**)
- `app.example.com` — 缺协议头，**永远不会匹配**（服务端强制校验 `http://` / `https://` 开头） - `app.example.com` — 缺协议头,**永远不会匹配**(强制校验 `http://` / `https://` 开头)
**典型坑**： **典型坑:**
1. 客户端 URL 是 `http://` 但服务端是 `https://`：浏览器按 `http://...` 的 origin 发请求，白名单里的 `https://...` 不会匹配 → 403。**客户端必须用 `https://` 开头**。 1. 客户端是 `http://` 但服务端是 `https://`:浏览器按 `http://...` 的 origin 发请求,白名单里的 `https://...` 不会匹配 → 403。**客户端必须用 `https://` 开头**。
2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`：浏览器按规范会**直接拒绝预检**（凭据 + 通配符冲突），POST 根本发不出去。 2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`:浏览器按规范**直接拒绝预检**(凭据 + 通配符冲突),POST 根本发不出去。
3. 同源请求（前端和 TTS 服务同域名）不受 CORS 限制，`ALLOWED_ORIGINS` 怎么配都不影响。 3. 同源请求不受 CORS 限制。
## API 使用说明 ## API 使用说明
### OpenAI 兼容接口 ### OpenAI 兼容接口
**端点：** `POST /v1/audio/speech` **端点:** `POST /v1/audio/speech`
**请求头：** **请求头:**
- `Content-Type: application/json` - `Content-Type: application/json`
- `Authorization: Bearer <你的API密钥>`（如果配置了OPENAI_TTS_API_KEY） - `Authorization: Bearer <你的API密钥>`(如果配置了 `OPENAI_TTS_API_KEY`)
**请求体:**
**请求体：**
```json ```json
{ {
"model": "tts-1", "model": "tts-1",
"input": "你好，这是一个测试文本", "input": "你好,这是一个测试文本",
"voice": "alloy", "voice": "alloy",
"response_format": "mp3", "response_format": "mp3",
"speed": 1.0 "speed": 1.0
} }
``` ```
**参数说明：** **参数说明:**
- `model` - 模型名称（OpenAI兼容，实际不影响） - `model` — 模型名(OpenAI 兼容,实际不影响,火山侧用 `BYTEDANCE_TTS_MODEL`)
- `input` - 要合成的文本 - `input` — 要合成的文本
- `voice` - 发音人（OpenAI兼容，实际使用配置的BYTEDANCE_TTS_SPEAKER） - `voice` — 发音人(OpenAI 兼容,实际用 `BYTEDANCE_TTS_SPEAKER`)
- `response_format` - 输出格式：`mp3`（默认）、`opus`（映射到ogg_opus）、`wav`、`pcm`、`aac`/`flac`（降级到mp3） - `response_format` — 输出格式:`mp3`(默认)/ `opus`(映射 ogg_opus)/ `wav` / `pcm` / `aac` / `flac`(降级到 mp3)
- `speed` - 语速：0.25 ~ 4.0 - `speed` — 语速,0.25 ~ 4.0(火山侧转换为 speech_rate [-50, 100])
**格式映射（OpenAI → 火山）：** **格式映射:**
| OpenAI response_format | 火山 API 格式 | Content-Type | | OpenAI response_format | 火山 API 格式 | Content-Type |
|------------------------|--------------|--------------| |------------------------|--------------|--------------|
| `mp3` | mp3 | audio/mpeg | | `mp3` | mp3 | audio/mpeg |
| `opus` | ogg_opus | audio/ogg | | `opus` | ogg_opus | audio/ogg |
| `wav` | pcm → 封装wav header | audio/wav | | `wav` | pcm → 本地拼 wav header | audio/wav |
| `pcm` | pcm | audio/pcm | | `pcm` | pcm | audio/pcm |
| `aac` / `flac` | mp3（降级） | audio/mpeg | | `aac` / `flac` | mp3(降级) | audio/mpeg |
**示例调用：** **调用示例:**
```bash ```bash
# MP3格式（默认） # MP3
curl -X POST "http://localhost:8080/v1/audio/speech" \ curl -X POST "http://localhost:8080/v1/audio/speech" \
-H "Content-Type: application/json" \ -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 -o output.mp3
# WAV格式 # WAV
curl -X POST "http://localhost:8080/v1/audio/speech" \ curl -X POST "http://localhost:8080/v1/audio/speech" \
-H "Content-Type: application/json" \ -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 -o output.wav
``` ```
### 健康检查（含统计信息） ### 健康检查
```bash ```bash
curl http://localhost:8080/health curl http://localhost:8080/health
``` ```
返回包含：服务状态、请求统计、错误记录、配置检查结果 返回服务状态、版本、运行时长、内存、配置检查结果(**不鉴权**)。
## 限流机制 ## 限流机制
为保护上游火山引擎API，服务实现了两层限流保护： 为保护上游火山 API,服务实现两层限流:
### 1. 全局并发限制 ### 全局并发限制
- **限制**：最多同时处理 **10个** TTS请求 - 最多同时处理 **10 个** TTS 请求
- **触发**：超过10个并发请求时 - 超过返回 `503 Service Unavailable`
- **错误码**：`503 Service Unavailable`
- **说明**：确保不超过上游API的并发限制
### 2. IP速率限制 ### IP 速率限制
- **限制**：每个IP每分钟 **100个** 请求 - 每个 IP 每分钟 **100 个** 请求
- **触发**：单个IP调用过于频繁 - 超过返回 `429 Too Many Requests`
- **错误码**：`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: 1.2.3.4
警告: 已超过IP速率限制，拒绝请求 - 客户端IP: 1.2.3.4 警告: 已超过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 错误=...
```
**适配器层日志**（默认静默，设置 `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 ## 观测 / Metrics
服务内置 Prometheus 文本格式的 `/metrics` 端点,**不鉴权**(与 `/health` 一致), 服务内置 Prometheus 文本格式的 `/metrics` 端点,**不鉴权**(与 `/health` 一致),可直接被 Prometheus 抓取或浏览器查看。Go 进程内埋点,零外部依赖,实现位于 `telemetry/` 与 `metrics/` 包。
可直接被 Prometheus 抓取或浏览器查看。Go 进程内埋点,零外部依赖,实现位于 `telemetry/` 与 `metrics/` 包。
### 主要指标 ### 主要指标
@@ -362,8 +279,7 @@ scrape_configs:
### 仪表盘 ### 仪表盘
`/dashboard` 仍展示服务状态 + 内存 + 配置信息,并内嵌 `/metrics` 的预览; `/dashboard` 展示服务状态 + 内存 + 配置信息,并内嵌 `/metrics` 预览;Grafana 等工具可直接基于上面指标做面板。
Grafana 等工具可直接基于上面指标做面板。
## 架构 ## 架构
@@ -376,14 +292,14 @@ Grafana 等工具可直接基于上面指标做面板。
| `controller/` | /v1/audio/speech、/health 处理器 | | `controller/` | /v1/audio/speech、/health 处理器 |
| `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 | | `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 |
| `setting/` | 单一环境变量入口 + 启动汇总 | | `setting/` | 单一环境变量入口 + 启动汇总 |
| `common/`、`dto/` | 常量、请求/响应类型 | | `common/`、`dto/` | 常量、请求/响应类型,`common.DebugLog` 控制调试日志 |
| `router/` | 路由注册 | | `router/` | 路由注册 |
## 部署建议 ## 部署
### Linux Systemd 服务 ### Linux Systemd
创建 `/etc/systemd/system/tts-server.service`： 创建 `/etc/systemd/system/tts-server.service`:
```ini ```ini
[Unit] [Unit]
@@ -403,35 +319,76 @@ RestartSec=10
WantedBy=multi-user.target WantedBy=multi-user.target
``` ```
启动服务：
```bash ```bash
sudo systemctl daemon-reload sudo systemctl daemon-reload
sudo systemctl enable tts-server sudo systemctl enable tts-server
sudo systemctl start tts-server sudo systemctl start tts-server
``` ```
### Docker 部署 ### Docker
```bash ```bash
docker compose up -d 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. 环境变量配置是否正确 1. 环境变量配置是否正确
2. 网络是否能访问火山引擎TTS服务 2. 网络是否能访问火山引擎 TTS 服务
3. 鉴权信息是否有效 3. 鉴权信息是否有效
4. Resource ID与Speaker是否匹配 4. Resource ID 与 Speaker 是否匹配
5. ALLOWED_ORIGINS 是否包含前端完整 origin（含 https://） 5. `ALLOWED_ORIGINS` 是否包含前端完整 origin(含 https://)
6. 客户端请求 URL 是否以 https:// 开头 6. 客户端请求 URL 是否以 https:// 开头
7. 生产环境凭据是否定期轮换（API Key 明文出现在日志/对话中时立刻重置） 7. 生产环境凭据是否定期轮换
8. 复刻音色（speaker 以 `S_` 开头）确保 `BYTEDANCE_TTS_RESOURCE_ID` 在控制台和音色 ID 同族（参考 `seed-icl-2.0` 等表） 8. 复刻音色确保 Resource ID 与音色 ID 同族
9. 音频格式是否匹配客户端解码能力（默认 mp3 兼容性最好） 9. 音频格式是否匹配客户端解码能力(默认 mp3 兼容性最好)
## 许可证
本项目采用非商业用途许可协议。详细条款请参阅 [LICENSE](LICENSE) 文件。