Volcano-Engine-TTS-UI

v0.2.4 1328705f65

v0.2.4 — 路由鉴权架构升级 · 健康/指标端点收口 · 管理入口迁移

CI / build-and-test (push) Canceled after 0s

Details

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

sun released this 2026-10-04 16:44:46 +08:00 | 0 commits to main since this release

v0.2.4 把默认对外的监控面收窄到只有一个匿名存活探针，并把管理凭证与业务调用凭证拆开，同时把管理入口统一到 /dashboard。业务接口 /v1/audio/speech 行为不变。

⚠️ 本版本为破坏性变更版本（以 0.2.4 发布、按补丁号连续，但语义是破坏性的），升级前请务必阅读下方 Breaking Changes。

⚠️ Breaking Changes（升级前必读）

1. 监控端点不再匿名可读

端点	v0.2.3	v0.2.4
`/healthz`	不存在	匿名可读，只回 `200 ok`（不含任何字段）
`/health`	匿名，返回完整健康数据	需管理凭证，否则 401
`/metrics`（根路径）	匿名	默认 404；需配置 `METRICS_ALLOW_CIDR` 才注册
`/dashboard`	匿名（服务状态预览页）	需鉴权（且已成为管理看板，见第 3 条）
`/api/setup/status`	匿名	需管理凭证

你需要做的：

K8s 探针 / Docker HEALTHCHECK 改指 /healthz。继续指向 /health 会一律 401 → Pod 反复重启 / 容器被判 unhealthy。（本仓库的 docker-compose.yml 与 Dockerfile 已同步修改。）
Prometheus 二选一：
- 改用鉴权版 /api/admin/metrics，并在 scrape_configs 配 authorization: { credentials: <管理凭证> }；
- 或配置 METRICS_ALLOW_CIDR 走根路径白名单。⚠️ Docker 中不要填 127.0.0.1/32（那是容器自身回环），请填容器内网网段，例如 172.16.0.0/12。

2. 未配置管理凭证时服务拒绝启动

RequireAdmin 此前在凭证列表为空时直接放行（等于管理接口完全裸奔）。现在该情况返回 401；并且 normal 模式下若 admin_key / auth_key / OPENAI_TTS_API_KEY 三者皆为空，服务将 fail-fast 拒绝启动。

你需要做的：升级前确认三者至少配置一个，否则服务起不来。

3. 管理入口从 `/admin` 迁至 `/dashboard`

/dashboard、/dashboard/voices、/dashboard/settings 为新入口
详细服务状态页迁至 /dashboard/status（原 /dashboard 是状态预览页）
/admin 及子路径 301 永久重定向到对应新路径，书签与脚本请尽快迁移

4. 管理 API 正式路径改为 `/api/admin/*`

新：/api/admin/voices、/api/admin/settings（含 api-key / auth-key / admin-key）
旧：/api/voices、/api/settings 仍可用（别名，不是重定向），计划后续版本移除

✨ 新特性

独立管理凭证 `admin_key`

管理后台登录凭证与业务调用凭证分离。取值优先级：

admin_key（DB） → auth_key（DB） → OPENAI_TTS_API_KEY（env）

不配置：回退使用 auth_key，行为与 v0.2.3 完全一致
配置后：业务调用方持有的 auth_key 无法访问管理接口（返回 401）

配置方式：PUT /api/admin/settings/admin-key，或在 /dashboard → 设置 中操作。凭证只写不读 —— GET /api/admin/settings 只返回打码值与来源标记。

内网 CIDR 白名单 `METRICS_ALLOW_CIDR`

逗号分隔，支持裸 IP 自动补掩码。非白名单来源返回 404（而非 403，避免向扫描者确认端点存在）。未配置时根路径 /metrics 完全不注册。

匿名存活探针 `/healthz`

刻意不返回任何字段（无版本、无内存、无配置状态、无模式），只回答"进程还在不在"。运维要细节请走鉴权后的 /health 或 /api/admin/health。

鉴权版详细健康数据 `/api/admin/health`

与 /api/admin/metrics 风格一致，供管理面板与运维使用。

🔧 修复

指标空指针崩溃：metrics 包的全局指标（UpstreamTotal 等）默认是 nil，只有 main 调过 metrics.Init() 后才有值。任何不经过 main 的调用路径（直接调 handler、复用为库）都会在 telemetry 埋点处 nil 解引用 panic。现在 Counter.Add / Gauge.Set / Gauge.Add / Histogram.Observe 一律空接收者安全（nil 静默忽略，与 noop 语义一致）。
上游 client 空指针：volcano.(*HTTPClient).PostStream 在 client 未初始化时 panic。现在返回错误，由 controller 归一成 5xx 并记日志——装配错误不该拖垮进程。
RequireAdmin 空凭证放行（安全缺口，见 Breaking Change 第 2 条）
/api/setup/status 在 normal 模式下仍匿名暴露 {installed, mode}（见第 1 条）
docker-compose.yml / Dockerfile 健康检查端点随鉴权改动失效（见第 1 条）

📋 其他变更

新增 CI 质量门（.github/workflows/ci.yml）：push / PR 到 develop、main 时跑 go build + go vet + go test -count=1。
测试源码不再入库：.gitignore 恢复整体屏蔽 *_test.go。测试文件保留在本地磁盘，由开发者自行执行 go test ./... -count=1。⚠️ 仓库内不提供自动化测试，CI 只能守住"编译通过 + 静态检查通过"，守不住行为回归。
文档订正：docs/UI_HANDOFF.md 标注为历史文档，补上当前真实文件结构与验收清单。
新增上游适配器开发指南：docs/UPSTREAM_ADAPTER_GUIDE.md——逐行核对现有火山适配器的真实契约，并给出 Provider 抽象的目标设计与分阶段实施计划。

✅ 验证方式

go build ./...
go vet ./...
go test ./... -count=1

端到端实测结果（真实服务器）：

检查	结果
`/healthz` 匿名	`200` + 字面量 `ok`
`/health` 无凭证 / 带凭证	`401` / `200`
根 `/metrics` 未配 CIDR	`404`（不注册）
`/admin` 系列路径	全部 `301` 至对应 `/dashboard/*`
`/dashboard*` 浏览器请求 / 脚本请求	`200` 页面外壳 / `401`
`/api/admin/` 与 `/api/` 别名	均 `200`（无 301/308）
配独立 `admin_key` 后业务 key 访问管理接口	`401`
业务接口 `/v1/audio/speech`	行为不变

📦 升级步骤

确认已配置 admin_key / auth_key / OPENAI_TTS_API_KEY 至少一个
更新探针指向 /healthz
更新 Prometheus 抓取配置（鉴权版或 METRICS_ALLOW_CIDR）
替换镜像 / 二进制并重启
访问 /dashboard 登录验证；确认旧 /admin 书签仍能自动跳转
按需在 /dashboard → 设置 配置独立 admin_key

无需数据库迁移 —— 旧的 tts.db 可直接复用。

Downloads

v0.2.3 21e1fd1fbb

v0.2.3 — 稳定性/安全加固/构建收尾

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

sun released this 2026-09-28 23:35:08 +08:00 | 9 commits to main since this release

v0.2.2 之后的稳定性与安全收尾补发（15 commits，23 文件，+1900 / -1258）。

稳定性 & 并发安全

fix(setting): runtime config 全局变量加 sync.RWMutex 保护，避免半写状态
fix(setup): settings + voices 改为事务原子提交，失败整体回滚不再半残
fix(ratelimit): 强制清理按最旧活跃时间排序，避免随机删活跃用户
fix(store): VoiceUpdate 同步 settings.default_speaker，防潜在 stale ref
fix(tts): OpenaiTTSHandler 响应 Write 错误不再吞，记日志排查客户端断开

安全加固

fix(security): 启动 / 路由 / 上游 log 对 resource_id 一并打码，补 telemetry.MaskResourceID

CORS

fix(cors): 预检 Allow-Methods 补 PUT/PATCH/DELETE，修 admin 改设置/删音色跨域失败
fix(cors): SettingsCORSRequest.Origins 改 *string，支持显式清空

管理后台

refactor(admin): 把单文件 admin.html (1075 行) 拆成多页 SPA，URL 路由切换
fix(admin): VoiceInsert 错误按客户端/服务端分流，400/500 不再混淆

构建 / CI

ci(docker): 合并为单一 GHCR + DockerHub 双推送 workflow，加 GHA 缓存
ci(docker): 修 workflow 非法表达式，secrets 改经 job env 透传

其他

refactor: 删 trimAll + 修 isSensitive，统一用 stdlib

Downloads

tts-api.exe
11 MiB
2026-10-04 09:08:13 +08:00
Source Code (ZIP)
Source Code (TAR.GZ)

v0.2.2 2ea33d7572

v0.2.2 — 安装引导 + Admin 管理后台 + 全局设置

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

sun released this 2026-09-05 00:37:02 +08:00 | 24 commits to main since this release

将 develop 合入 main。本次发布把 v0.1.0 纯环境变量配置方案，升级为 WebUI 全流程管理。

新增

M0 — SQLite 存储层

modernc.org/sqlite (无 CGO) 接管所有运行时配置
store/ 包：settings / voices 两表，PRAGMA WAL + foreign_keys
启动期自动检测 DB 完整性，损坏时备份为 .corrupt-<时间戳> 并回退到 setup 模式

M1 — 安装引导

首次启动（无 installed.lock）进入 setup 模式
/setup 页面 4 步表单：凭证 → 默认路由 → 音色列表 → 确认
Vue 3.4 + axios 1.6 via bootcdn，//go:embed 进 binary
装完写 installed.lock 锁定，后续访问 /setup 302 跳 /admin

M2 — Admin 管理后台

/admin 单页 SPA：仪表盘 / 音色管理 / 全局设置 / CORS
音色 CRUD：新增 / 删除 / 启用切换
鉴权复用 OpenAI API key（DB 里 auth_key）
浏览器安装模式完全跳过 CORS

M3 — 全局设置 + 声音路由

default_speaker 是 voice 名字（如 chun），路由时查 voice 表拿真 speaker ID
POST /v1/audio/speech 支持 voice=<name> 动态路由
未知 voice 返 400 unknown voice: '<name>'
禁用 voice 返 403 voice '<name>' is disabled
改设置后下一个请求立即生效（不需重启）

M4 — 文档 + 工程收敛

README 重写：聚焦 WebUI 引导 + 老用户迁移 + 资源 ID 1.0/2.0 区别
新增 CHANGELOG.md / PROJECT_BOOK.md
.env.example 收敛到 4 个引导 env
docker-compose 加 named volume tts-data 持久化 tts.db
Dockerfile 准备 /data 目录并开放 appuser 写权限
4 个集成测试（lock / setup / voices / tts_voice）

运维工具

cmd/dumpdb：dump tts.db 的 settings + voices，敏感字段自动打码

配置迁移

v0.1.0 用 env 配 11 个 BYTEDANCE_TTS_* 变量。v0.2.2 起改 WebUI 持久化到 SQLite。

配置	v0.1.0 (env)	v0.2.2 (DB)
API Key	`BYTEDANCE_TTS_API_KEY`	`/setup` 或 `/admin`
默认音色	`BYTEDANCE_TTS_SPEAKER`	同上（填 voice 名字，非 speaker ID）
资源 ID	`BYTEDANCE_TTS_RESOURCE_ID`	同上
CORS	`ALLOWED_ORIGINS`	`/admin` CORS tab
OpenAI key	`OPENAI_TTS_API_KEY`	`/setup` 或 `/admin`

启动引导只需 4 个 env（DB 不存在时必需）：

TTS_ADMIN_KEY     安装 token
TTS_DB_PATH       DB 路径（默认 ./tts.db）
PORT              监听端口（默认 8080）
OPENAI_TTS_API_KEY  OpenAI 接口鉴权（可选）

向后兼容：老 env 仍可作为 DB 缺失时的 fallback，不强制迁移。

安全修复

编号	等级	问题	修复
SEC-001	中	speaker ID（用户付费资产）在日志 / metrics / admin API 响应中明文暴露	日志打码 `S_G8****naJ1`；metrics label 用 sha1[:8] 不可逆哈希；admin API 只回前 4 + 后 4
SEC-002	中	`enabled=0` 字段不生效，禁用音色仍可调用	禁用时返 403 `voice_disabled`，与 `unknown_voice` (400) 形成清晰区分
SEC-003	低	安装 token 比较用普通 `==`，存在计时攻击风险	改 `subtle.ConstantTimeCompare` / `common.SecureEqualString`
SEC-004	低	normal 模式配置加载失败后服务继续跑，所有请求 503 但用户无感	改 fail-fast：`log.Fatalf` 退出 + `/health` body 加 `configuration_error` 字段 + metric `tts_config_load_failures_total{mode="normal"}` 供告警

行为变化

启动

首次启动（无 DB）→ 监听端口，浏览器 /setup 引导
正常启动（已有 DB）→ 直接加载，访问 /admin
DB 损坏 → 自愈回退到 setup 模式
normal + 配置坏 → fail-fast 退出（K8s 拉起会循环触发，便于告警）

CORS

安装模式完全跳过 CORS
同源请求自动豁免
预检不消耗限流配额
配置全 DB 化

资源 ID

V3 API 复刻 2.0 项目应填 seed-icl-2.0（不是 volc.megatts.icl）
模型名 seed-tts-2.0-standard（不复用 resource id）

下载

平台	文件
Windows x64	`tts-api.exe`
Docker	`ghcr.io/Blue-Ink-Studio/Volcano-Engine-TTS-UI:v0.2.2`
源码	`Source code (zip) / (tar.gz)`

升级步骤

拉取最新代码或镜像
备份旧 env（API Key / speaker ID / 资源 ID），安装时重新输入
启动服务（首次进 setup 模式）
浏览器 /setup 完成配置
验证：/health 无 configuration_error，/admin 可登录
客户端测试 /v1/audio/speech 合成正常

统计

本次新 commit：22（M0-M4 全在 develop）+ 1 反向合并 = 23
总 commit（远端 main）：含 VUL 修复 + CI workflow 共 106
变更文件：33
新增代码：+4763 行（Go ~2952，UI ~1503，文档 + 配置 + 测试 ~300）
新增包：store / installer / cmd/dumpdb / middleware/installguard / middleware/admin_auth

已知 / 后续

ui-arch-debt：admin.html 当前是单文件 ~60KB，M5 拆分（按需加载，CDN 分片缓存）
/dashboard 合并到 /admin：避免"两个状态页"用户困惑
集成测试目前 gitignore（按本地策略），未来挪到 CI

致谢

23 个独立 commit 来自本仓库维护者（3371392206@qq.com）。

Downloads

tts-api.exe
11 MiB
2026-09-05 00:44:09 +08:00
Source Code (ZIP)
Source Code (TAR.GZ)

v0.2.1 0d3517eb5c

🎉 v0.2.1 — 安全加固 & 可观测性补全

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

sun released this 2026-08-27 14:52:11 +08:00 | 49 commits to main since this release

对全 12 个包、约 2400 行代码完成系统性安全审计，修复 9 项漏洞（高 1 / 中 2 / 低 4 / 信息 2），补全传输层错误监控，修复音频格式响应头不一致问题，并将版本号从硬编码改为构建时注入。

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

X-Forwarded-For 默认行为变化

TRUSTED_PROXY_HOPS 默认值从 1（精确模式）改为 0（启发式模式）。

部署方式	影响
单跳反代（client → nginx → 本服务）	行为完全相同，无需任何改动
多跳 CDN（client → CDN → nginx → 本服务）	限流粒度从"真实 client IP"变为"CDN 边缘 IP"。如需精准按真实 client 限流，请显式设置 `TRUSTED_PROXY_HOPS=2`
直出部署（无反代）	无影响，XFF 分支不执行

启动日志会显示当前 XFF 解析模式，可用于验证。

🔒 安全修复

编号	等级	问题	修复方式
VUL-004	🔴 高	`.gitignore` 未忽略 `.env`，`git add .` 会将火山 API Key 提交进 git 历史	`.gitignore` / `.dockerignore` 新增 Secrets 规则，拦截 `.env` 及 `.env.*` 变体，保留 `.env.example` 模板
VUL-001	🟡 中	请求 `aac`/`flac` 格式时，响应 `Content-Type` 为 `audio/aac`/`audio/flac`，但实际字节流是降级后的 MP3，客户端解码失败	`finalFormat` 改为反映真实输出格式，非 wav 时取上游实际格式
VUL-003	🟡 中	`X-Forwarded-For` 取首值，攻击者可伪造 IP 绕过 IP 限流	重写为启发式/精确双模式，两种模式均从链尾扫描，天然免疫伪造。默认启发式模式零配置适配 90% 部署场景
VUL-002	🟢 低	transport 层错误（DNS/连接/TLS 失败、WAV 头拼装失败等）不进入 `UpstreamErrors` 指标，网络故障在监控上完全不可见	错误判断从 `errCode != 0` 改为 `status != "ok"`，transport / request / wrap / stream 错误首次进入监控
VUL-005	🟢 低	攻击者可在请求 URL 或上游错误响应中注入 `\n`/`\r` 伪造日志行	访问日志 `RequestURI` 和上游错误体均转义换行符
VUL-006	🟢 低	`/metrics` `/health` `/dashboard` 无鉴权，公网部署暴露业务指标和配置状态	文档新增「公网部署：监控端点无鉴权」章节，含三端点风险表 + nginx basic auth 配置示例
VUL-007	🟢 低	未设置 `OPENAI_TTS_API_KEY` 时鉴权完全关闭，公网部署任何人可调用消耗火山额度	文档三处强化：环境变量表加 🔴 公网必设标记、API 使用说明顶部警示、新增「公网部署安全清单」章节
VUL-008	⚪ 信息	`speed` 参数超火山实际范围（0.5~2.0）时被静默截断，客户端无感知	文档修正为「客户端接受 0.25~~4.0，火山实际生效 0.5~~2.0，超出静默截断」
VUL-009	⚪ 信息	WAV 头的采样率直接取配置值，若与上游实际 PCM 采样率不一致会导致音频变速变调	文档给 `BYTEDANCE_TTS_SAMPLE_RATE` 加风险提示

✨ 功能改进

构建时版本号注入

/health 端点的 version 字段不再硬编码，改为通过 ldflags 在构建时注入：

Release 构建：显示干净 semver（如 v0.2.1）
开发构建：显示 git describe 输出 + commit hash（如 v0.2.0-5-g4abcd5）
本地默认：dev

Dockerfile 已配套 ARG VERSION / ARG COMMIT，CI/CD 可直接传入。

新增 `TRUSTED_PROXY_HOPS` 环境变量

控制 XFF 解析模式：

值	模式	说明
不设置 / `0`	启发式（默认）	从 XFF 链尾扫描，跳过私有 IP，返回第一个公网 IP。适合 90% 部署
`N`（N > 0）	精确模式	从 XFF 链尾倒数第 N+1 个位置取值，精准到真实 client IP。N=1 单跳反代，N=2 CDN+反代，以此类推

🧪 测试 & 代码质量

新增 24 个表驱动测试用例（middleware/ratelimit_test.go），覆盖直出/单跳/多跳/伪造/畸形/精确 N 边界，全部通过
清理死代码约 30 行（7 个文件），含从未被引用的 ratelimit_middleware.go、空初始化函数、未使用类型和常量
新增 VULNERABILITY_REPORT.md，完整记录 9 项漏洞详情、8 条已核查无风险项、工程债务记录和安全加固建议

📦 下载

平台	文件	说明
Windows x64	`tts-api.exe`	由 release 维护者上传，直接双击或命令行运行
Docker	`ghcr.io/Blue-Ink-Studio/Volcano-Engine-TTS-UI:v0.2.1`	推荐，amd64/arm64 双架构
源码	`Source code (zip)` / `(tar.gz)`	服务器 `git pull` 后 `go build` 即可

🚀 升级步骤

拉取最新代码或镜像
检查反代拓扑：如果是多跳 CDN 部署且需要精准按真实 client 限流，设置 TRUSTED_PROXY_HOPS=2（或对应跳数）；单跳/直出无需改动
确认 .env 未被提交：执行 git status 检查，如有 .env 请加入 .gitignore 并从 git 历史移除
重启服务，查看启动日志中的 XFF 模式提示和版本号
验证：访问 /health 确认 version 显示为 v0.2.1

📊 变更统计

Commits：11
变更文件：22
新增代码：+738 行
删除代码：-118 行
新增测试：24 个用例

Downloads

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

v0.1.0 ac614be190

v0.1.0 - 首发：ByteDance TTS → OpenAI API 适配服务

Go CI/CD Deploy to Baota / build-and-deploy (push) Has been cancelled

Details

Stable

sun released this 2026-05-19 18:36:26 +08:00 | 118 commits to main since this release

🎉 首个正式版本 v0.1.0

将字节跳动豆包 TTS v3 API封装为 OpenAI 兼容接口的轻量级 HTTP 适配服务，可直接替换 OpenAI /v1/audio/speech 接入到任意支持 OpenAI TTS 的客户端（如 LobeChat、NextChat、Open WebUI 等）。

✨ 核心特性

🔌 OpenAI 兼容：完全兼容 POST /v1/audio/speech，无需修改客户端代码
🚀 独立可执行文件：单个 tts_server.exe（约 6.7 MB），无需 Go 环境，开箱即用
🎚️ 语速调节：支持 speed 参数（0.25 ~ 4.0），自动映射到字节跳动 speech_rate
🔐 API Key 鉴权：可选的 Bearer Token 鉴权，支持多 Key 配置
🛡️ 限流保护：基于客户端 IP 的速率限制（默认 100 次/分钟）+ 最大并发数限制（默认 10）
📊 健康检查：/health 端点提供运行时统计、内存信息、错误率等监控数据
🌐 CORS 支持：开箱即用的跨域支持
⚡ 流式解析：底层使用流式读取字节跳动响应，内存占用低
🪶 零外部依赖：纯 Go 静态编译，无需 CGO、无需 DLL

📦 下载

平台	文件	说明
Windows x64	`tts_server.exe`	直接双击或命令行运行

🚀 快速开始

下载 tts_server.exe
设置环境变量（参考 .env.example）：

$env:BYTEDANCE_TTS_API_KEY="你的火山引擎 API Key"
$env:BYTEDANCE_TTS_RESOURCE_ID="seed-tts-1.0"
$env:BYTEDANCE_TTS_SPEAKER="你的音色 ID"
.\tts_server.exe

服务启动后访问：http://localhost:8080/health 查看状态
客户端调用：

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`	请求超时时间
`OPENAI_TTS_API_KEY`	❌	-	OpenAI 兼容鉴权 Key（多个用逗号分隔）
`PORT`	❌	`8080`	监听端口

📋 限制

单次输入文本最大 5000 字符
请求体最大 1 MB
默认音频格式：WAV，采样率 24000 Hz

🔧 构建说明

如果想自行编译：

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

Full Changelog: 这是首个版本 🎊

---

Downloads

tts_server.exe
6.7 MiB
2026-05-23 09:31:22 +08:00
Source Code (ZIP)
Source Code (TAR.GZ)

6 Releases 6 Tags

v0.2.4 — 路由鉴权架构升级 · 健康/指标端点收口 · 管理入口迁移 CI / build-and-test (push) Canceled after 0s Details Docker Publish / build-and-push (push) Canceled after 0s Details Stable

⚠️ Breaking Changes（升级前必读）

1. 监控端点不再匿名可读

2. 未配置管理凭证时服务拒绝启动

3. 管理入口从 /admin 迁至 /dashboard

4. 管理 API 正式路径改为 /api/admin/*

✨ 新特性

独立管理凭证 admin_key

内网 CIDR 白名单 METRICS_ALLOW_CIDR

匿名存活探针 /healthz

鉴权版详细健康数据 /api/admin/health

🔧 修复

📋 其他变更

✅ 验证方式

📦 升级步骤

v0.2.3 — 稳定性/安全加固/构建收尾 Docker Publish / build-and-push (push) Canceled after 0s Details Stable

稳定性 & 并发安全

安全加固

CORS

管理后台

构建 / CI

其他

v0.2.2 — 安装引导 + Admin 管理后台 + 全局设置 Docker Publish / build-and-push (push) Canceled after 0s Details Stable

新增

M0 — SQLite 存储层

M1 — 安装引导

M2 — Admin 管理后台

M3 — 全局设置 + 声音路由

M4 — 文档 + 工程收敛

运维工具

配置迁移

安全修复

行为变化

启动

CORS

资源 ID

下载

升级步骤

统计

已知 / 后续

致谢

🎉 v0.2.1 — 安全加固 & 可观测性补全 Docker Publish / build-and-push (push) Canceled after 0s Details Stable

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

X-Forwarded-For 默认行为变化

🔒 安全修复

✨ 功能改进

构建时版本号注入

新增 TRUSTED_PROXY_HOPS 环境变量

🧪 测试 & 代码质量

📦 下载

🚀 升级步骤

📊 变更统计

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

✨ 核心特性

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

📦 下载

🚀 快速开始

⚙️ 环境变量

📋 限制

🔧 构建说明

🐛 已知问题

📝 完整变更

🔗 Full Changelog

v0.1.0 - 首发：ByteDance TTS → OpenAI API 适配服务 Go CI/CD Deploy to Baota / build-and-deploy (push) Has been cancelled Details Stable

🎉 首个正式版本 v0.1.0

✨ 核心特性

📦 下载

🚀 快速开始

⚙️ 环境变量

📋 限制

🔧 构建说明

v0.2.4 — 路由鉴权架构升级 · 健康/指标端点收口 · 管理入口迁移

CI / build-and-test (push) Canceled after 0s

Details

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

3. 管理入口从 `/admin` 迁至 `/dashboard`

4. 管理 API 正式路径改为 `/api/admin/*`

独立管理凭证 `admin_key`

内网 CIDR 白名单 `METRICS_ALLOW_CIDR`

匿名存活探针 `/healthz`

鉴权版详细健康数据 `/api/admin/health`

v0.2.3 — 稳定性/安全加固/构建收尾

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

v0.2.2 — 安装引导 + Admin 管理后台 + 全局设置

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

🎉 v0.2.1 — 安全加固 & 可观测性补全

Docker Publish / build-and-push (push) Canceled after 0s

Details

Stable

新增 `TRUSTED_PROXY_HOPS` 环境变量

v0.1.0 - 首发：ByteDance TTS → OpenAI API 适配服务

Go CI/CD Deploy to Baota / build-and-deploy (push) Has been cancelled

Details

Stable