Volcano-Engine-TTS-UI

v0.2.0 4a8c563b32

🎉 v0.2.0 — 架构重构 & 可观测性首版 Stable

sun released this 2026-08-27 14:51:22 +08:00 | 63 commits to main since this release

将 51 个 develop 分支提交以合并提交形式合入 main,完成从单体 tts_server.go (778 行) 到模块化架构的全面重构,首次落地完整可观测性。

✨ 核心特性

🏗️ 模块化架构: 代码拆分为 adapter / controller / dto / middleware / router / setting / telemetry / metrics 八大模块,职责清晰
🔌 OpenAI 兼容: 完全兼容 POST /v1/audio/speech,LobeChat / NextChat / Open WebUI 等客户端零改造接入
🚀 独立可执行文件: 单个 tts-api.exe (Windows 约 6.96 MB),无需 Go 环境,CGO 关闭,纯静态编译
🎚️ 语速调节: speed 参数 (0.25 ~ 4.0) 自动映射到字节跳动 speech_rate
🔐 API Key 鉴权: 可选 Bearer Token,支持多 Key 逗号分隔配置
🛡️ 限流 & 并发: 基于 IP 的速率限制 + 最大并发数控制,中间件仅统计 /v1/ 路由避免监控路径污染
📊 可观测性: 自研轻量 telemetry 库 (counter / gauge / histogram),暴露 Prometheus 格式 /metrics 端点
🖥️ 健康监控面板: health.html 分组展示请求量、延迟、限流、字节数,无外部前端依赖
🌐 CORS 白名单: ALLOWED_ORIGINS 支持精确来源控制
🎵 多音频格式: 支持 mp3 / pcm / ogg_opus,请求 wav 时自动拼 WAV 头
🪶 零外部依赖: 单一静态二进制,无 DLL、无 CGO

⚠️ 重大变更 (升级必读)

二进制名变更: tts_server.exe → tts-api.exe(与 Dockerfile / 镜像名对齐)
入口变更: main.go 取代 tts_server.go 作为唯一入口,启动流程由集中式 setting.InitAllConfigs() 驱动
配置聚合: 启动时打印完整配置摘要,便于排查
限流范围: 限流与并发中间件只作用于 /v1/ 前缀路由,/health / /metrics 不再消耗配额

⚠️ CORS 行为变化 (高危): ALLOWED_ORIGINS 默认值从「允许所有」改为「拒绝所有跨域」。0.1.0 用户直接升级会立刻遇到前端跨域报错,务必在升级前显式设置该变量,例如:
ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
开发环境可设 *(不可与 OPENAI_TTS_API_KEY 鉴权共用)。

📦 下载

平台	文件	说明
Windows x64	`tts-api.exe`	由 release 维护者上传,直接双击或命令行运行
源码	`Source code (zip)` / `(tar.gz)`	服务器 `git pull` 后 `go build` 即可

🚀 快速开始

下载 tts-api.exe(或拉取源码编译)

设置环境变量(参考 .env.example):

$env:BYTEDANCE_TTS_API_KEY="你的火山引擎 API Key"
$env:BYTEDANCE_TTS_RESOURCE_ID="seed-icl-2.0"
$env:BYTEDANCE_TTS_SPEAKER="你的音色 ID"
$env:ALLOWED_ORIGINS="https://你的前端域名"   # 0.2.0 起必填,否则跨域被拒

启动服务:
```
.\tts-api.exe
```
访问 http://localhost:8080/health 查看监控面板,/metrics 查看 Prometheus 指标

客户端调用(同 0.1.0):

curl -X POST http://localhost:8080/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"你好,世界","voice":"alloy","speed":1.0}' \
  --output hello.wav

⚙️ 环境变量

变量	必需	默认值	说明
`BYTEDANCE_TTS_API_KEY`	✅	—	火山引擎 API Key
`BYTEDANCE_TTS_RESOURCE_ID`	✅	—	资源 ID(决定 1.0 / 2.0 模型)
`BYTEDANCE_TTS_SPEAKER`	✅	—	发音人 ID
`BYTEDANCE_TTS_TIMEOUT`	❌	`30s`	单次合成超时
`BYTEDANCE_TTS_FORMAT`	❌	`mp3`	上游音频格式:`mp3` / `pcm` / `ogg_opus`,请求 `wav` 时自动转 pcm + 拼头
`BYTEDANCE_TTS_SAMPLE_RATE`	❌	`24000`	上游采样率:8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000
`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`	❌	—	模型类型:`4` = ICL V2,`5` = ICL V3
`BYTEDANCE_TTS_EXPLICIT_LANGUAGE`	❌	—	非中英语种:`zh-cn` / `en` / `ja` / `es-mx` / `id` / `pt-br` / `ko`
`BYTEDANCE_TTS_ENABLE_SUBTITLE`	❌	`false`	复刻 2.0 是否返回字级时间戳
`BYTEDANCE_TTS_DEBUG`	❌	`false`	启用上游请求 / 响应诊断日志(排障用,会打印完整 payload)
`OPENAI_TTS_API_KEY`	❌	—	OpenAI 兼容接口鉴权 Key,多个用逗号分隔
`ALLOWED_ORIGINS`	❌	(拒绝所有)	CORS 白名单,逗号分隔;开发可设 `*`(不可与鉴权共用)
`PORT`	❌	`8080`	监听端口

📋 限制

单次输入文本最大 5000 字符
请求体最大 1 MB
上游默认音频格式:MP3,采样率 24000 Hz;客户端请求 WAV 时本地拼头
限流与并发默认值:100 次/分钟(单 IP),最大并发 10

🔧 构建说明

自行编译:

go mod tidy
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o tts-api.exe

Docker 镜像(推荐生产部署):

docker compose up -d

🐛 已知问题

middleware/ratelimit_middleware.go.tmp 临时文件残留,将在 0.2.1 清理
监控面板 health.html 暂未拆分为独立服务,需与主服务同进程

📝 完整变更

41 文件变更,+3742 / -934
新增模块:adapter/volcano / controller / dto / middleware / router / setting / telemetry / metrics
适配器拆分:request.go / response.go / synthesis.go / audio.go / client.go / options.go / errors.go
修复:响应体过大处理、CORS 校验逻辑、日志乱码、BOM 头
升级 Go 1.23 → 1.26,新增 Dockerfile / docker-compose.yml / .dockerignore

🔗 Full Changelog

View full diff

Downloads

6 Releases 6 Tags