Volcano-Engine-TTS-UI/README.md

# 字节火山引擎 TTS v3 → OpenAI 兼容接口

将火山引擎 TTS v3 API 封装为 OpenAI 兼容的 `/v1/audio/speech` 端点,自带引导式安装、WebUI 后台、SQLite 持久化、Prometheus 观测。单二进制,无外部服务依赖。

## 特性

- 完全兼容 OpenAI `/v1/audio/speech` API
- **引导式安装**: 首次启动自动进入 `/setup` 向导,无需手写 env
- **WebUI 后台** `/dashboard`: 音色管理 / 全局设置 / CORS 配置 / 鉴权
- **音色库**: 多 voice 动态路由,未知 / 禁用 voice 返回明确错误
- **多格式输出**: mp3 / ogg_opus / pcm / wav (内部转 pcm + 本地拼头) / aac / flac
- **鉴权 + 限流**: API Key 校验, IP 速率限制, 全局并发限制
- **凭证分离**(v0.3.0): 管理后台可配独立 `admin_key`,业务调用 Key 无法访问管理接口
- **观测**: Prometheus 文本格式 + 服务状态, **默认无匿名监控端点**(v0.3.0 起)
  - `/healthz` 匿名存活探针(不含任何字段)· `/api/admin/metrics` 与 `/api/admin/health` 需鉴权
  - 根路径 `/metrics` 默认 404,需 `METRICS_ALLOW_CIDR` 内网白名单才注册
- **跨平台**: Windows / Linux / macOS / Docker

## 快速开始

### 1. 编译

```bash
go build -o tts-api .
```

### 2. 启动

```bash
# 默认: 端口 8080, 监听 localhost
./tts-api
```

启动后浏览器打开 `http://localhost:8080/setup`,完成 4 步引导:

1. 凭证: 火山 API Key + OpenAI 端鉴权 key
2. 默认路由: 默认资源 ID (复刻 2.0 用 `seed-icl-2.0`) + 默认音色名
3. 音色列表: 每个 voice 的对外名 + 火山 speaker ID
4. 确认提交

完成后自动跳转到 `/dashboard`,从这里登录管理。

### 3. 调用

```bash
curl -X POST http://localhost:8080/v1/audio/speech \
  -H "Authorization: Bearer <装时设的 OpenAI key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"你好,世界","voice":"chun"}' \
  -o output.mp3
```

## 环境变量

**只需 4 个启动引导变量**(安装前 / DB 还不存在时必需):

| 变量 | 必设 | 用途 |
|---|---|---|
| `TTS_ADMIN_KEY` | ✓ (生产) | `/api/setup` 安装 token,首次安装时校验 |
| `TTS_DB_PATH` | ✗ | DB 路径,默认 `./tts.db` |
| `PORT` | ✗ | 监听端口,默认 `8080` |
| `OPENAI_TTS_API_KEY` | ✓ (生产) | 业务端鉴权 key;未设 `admin_key` 时**也用于管理后台登录** |

v0.3.0 新增(均可选):

| 变量 | 用途 |
|---|---|
| `METRICS_ALLOW_CIDR` | 根路径 `/metrics` 的内网 CIDR 白名单(逗号分隔)。不配则根路径完全不注册 |

> ⚠️ **v0.3.0 起,normal 模式下未配置任何管理凭证(DB `admin_key` / DB `auth_key` /
> env `OPENAI_TTS_API_KEY` 三者皆空)时服务将拒绝启动** —— 因为管理接口在无凭证时会拒绝
> 所有请求,启动一个进不去后台的实例没有意义。

**所有业务配置**(`api_key` / `default_resource_id` / `default_speaker` / `default_format` / `sample_rate` / `model` / `model_type` / `explicit_language` / `enable_subtitle` / `timeout` / `cors_origins` / `cors_allow_all` / `auth_key` / **`admin_key`** / `trusted_proxy_hops`) — 全部在 `/dashboard` 设置,持久化到 SQLite。

env 仍可作为 fallback 读(老用户兼容),但**新用户应通过 WebUI 配**。

## WebUI 使用

### `/setup` 首次安装

四步表单:
1. **凭证**: 火山 API Key (必填) + OpenAI 鉴权 Key (可选)
2. **默认路由**: 默认资源 ID (`seed-icl-2.0`) + 默认音色名 + 默认格式 + 采样率
3. **音色列表**: 每个 voice 一行,填对外名 + 火山 speaker ID
4. **确认**: 提交写入 DB,自动跳 `/dashboard`

### `/dashboard` 日常管理

| Tab | 用途 |
|---|---|
| 仪表盘 | 进程状态 / 内存 / 启动时长 / 配置检查 |
| 音色管理 | CRUD 音色: 名称 / speaker / 资源 ID / 模型 / 语言 / 启用 / 描述 |
| 设置 | 全局设置: API Key / 默认资源 ID / 默认音色 / 格式 / 采样率 / 子模型 / 鉴权 key |
| CORS | 白名单 (逗号分隔) 或 `*` 模式 |
| 退出 | 清除 session |

修改设置后**自动 reload**,不需重启服务。

### 客户端可见错误

| 场景 | HTTP | Body code | message |
|---|---|---|---|
| 缺少 Authorization | 401 | `invalid_api_key` | Invalid API key provided. |
| 音色不存在 | 400 | `unknown_voice` | `unknown voice: 'alloy'` |
| 音色被 admin 禁用 | 403 | `voice_disabled` | `voice 'chun' is disabled` |
| 服务未就绪 (DB 配置损坏) | 503 | `service_unavailable` | TTS service configuration error... |

## API 端点

### `POST /v1/audio/speech`

OpenAI 兼容,鉴权 `Authorization: Bearer <OPENAI_TTS_API_KEY>`(若已设)。

请求体:

```json
{
  "model": "tts-1",          // 兼容字段,实际不影响
  "input": "你好,世界",     // 必填,要合成的文本
  "voice": "chun",           // 选填: 装时设的 voice 名称,留空走 default_speaker
  "response_format": "mp3",  // 选填: mp3 / opus / wav / pcm / aac / flac
  "speed": 1.0               // 选填: 0.25 ~ 4.0,实际 0.5 ~ 2.0 生效
}
```

格式映射:

| OpenAI `response_format` | 上游实际 | Content-Type |
|---|---|---|
| `mp3` (默认) | mp3 | `audio/mpeg` |
| `opus` | ogg_opus | `audio/ogg` |
| `wav` | pcm → 本地拼 wav header | `audio/wav` |
| `pcm` | pcm | `audio/pcm` |
| `aac` / `flac` | mp3 (降级) | `audio/mpeg` |

### `GET /healthz`

**无鉴权**。存活探针,**只返回 `200` 与字面量 `ok`,不含任何字段**。

供 K8s `livenessProbe`/`readinessProbe`、Docker `HEALTHCHECK`、负载均衡健康检查使用 ——
这些探针默认不带 `Authorization`,不能指向需要鉴权的 `/health`。

```bash
curl http://localhost:8080/healthz
# ok
```

### `GET /health`(v0.3.0 起需鉴权)

**需管理凭证**(`Authorization: Bearer <admin_key>`)。返回完整健康数据:

```json
{
  "status": "ok",                            // ok | not_installed | configuration_error
  "service": "ByteDance TTS to OpenAI API Adapter",
  "version": "v0.3.0",
  "commit": "abc1234",
  "uptime": "3600 seconds",
  "start_time": "2026-10-04T00:00:00Z",
  "memory": { "heap_alloc": 0, "heap_inuse": 0, "goroutines": 0 },
  "config_status": {
    "all_required_vars_set": true,
    "config_error": false,
    "error": "..."                           // 仅在 config_error=true 时出现
  },
  "installed": true,
  "mode": "normal"
}
```

- 正常: HTTP 200, `status: "ok"`
- 未安装: HTTP 200, `status: "not_installed"`
- 配置损坏: HTTP 503, `status: "configuration_error"`, `error` 字段有原因
- 无凭证: HTTP **401**

> v0.3.0 之前本端点是匿名的,会泄漏版本、commit、运行时长、内存与配置错误文本,现已收口。
> 管理面板内使用鉴权版 **`GET /api/admin/health`**(返回同样的数据)。

### `GET /metrics`

**默认不注册**(访问 404)。两种使用方式:

1. **配置 `METRICS_ALLOW_CIDR`**(内网 CIDR 白名单,逗号分隔):
   根路径 `/metrics` 仅对白名单来源开放,**非白名单返回 404**(不是 403,避免确认端点存在)。
   ```bash
   METRICS_ALLOW_CIDR=10.0.0.0/8,172.16.0.0/12
   ```
   ⚠️ Docker 部署请填**容器内网网段**,不要填 `127.0.0.1/32`(那是容器自身回环)。
2. **使用鉴权版 `GET /api/admin/metrics`**,带 `Authorization: Bearer <管理凭证>`。
   Prometheus 侧需配 `authorization: { credentials: <管理凭证> }`。

Prometheus 文本格式。主要指标见 [观测 / Metrics](#观测--metrics)。

### 管理页面与安装页

| 路径 | 说明 | 鉴权 |
|---|---|---|
| `GET /dashboard` | 管理看板 | 需鉴权(浏览器请求返回页面外壳,数据走 API) |
| `GET /dashboard/voices` | 音色管理 | 同上 |
| `GET /dashboard/settings` | 全局设置 | 同上 |
| `GET /dashboard/status` | 详细服务状态(健康 + 指标看板) | 同上 |
| `GET /dashboard/login` | 登录页 | **公开**(否则无法登录) |
| `GET /setup` | 引导式安装页 | 无鉴权,装完自动跳转 |
| `GET /admin` 等旧路径 | 301 永久重定向到对应 `/dashboard/*` | — |

> **为什么页面是"需鉴权"却又能直接打开?** 浏览器的 `Accept` 含 `text/html` 时返回页面外壳,
> 由前端根据 `sessionStorage` 里的凭证决定显示登录视图;非 HTML 请求(脚本、抓取工具)
> 无凭证一律 401。页面外壳不含任何数据,数据全部来自鉴权后的 `/api/admin/*` 接口。

## 老用户迁移 (从 v0.1.0 → v0.2.0)

v0.1.0 用 env 配 11 个 `BYTEDANCE_TTS_*` 变量。v0.2.0 起改 WebUI:

| 旧 env | v0.2.0 配置入口 |
|---|---|
| `BYTEDANCE_TTS_API_KEY` | `/dashboard` 设置 → API Key |
| `BYTEDANCE_TTS_RESOURCE_ID` | `/dashboard` 设置 → 默认资源 ID |
| `BYTEDANCE_TTS_SPEAKER` | `/dashboard` 设置 → 默认音色 (填 voice **名字**,不是 speaker ID) |
| `BYTEDANCE_TTS_FORMAT` | `/dashboard` 设置 → 默认格式 |
| `BYTEDANCE_TTS_SAMPLE_RATE` | `/dashboard` 设置 → 采样率 |
| `BYTEDANCE_TTS_BIT_RATE` | `/dashboard` 设置 → MP3 比特率 |
| `BYTEDANCE_TTS_MODEL` | `/dashboard` 设置 → 子模型 |
| `BYTEDANCE_TTS_MODEL_TYPE` | `/dashboard` 设置 → 模型类型 |
| `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` | `/dashboard` 设置 → 显式语言 |
| `BYTEDANCE_TTS_ENABLE_SUBTITLE` | `/dashboard` 设置 → 启用字级时间戳 |
| `BYTEDANCE_TTS_TIMEOUT` | (保留 env 暂未搬 DB) |
| `ALLOWED_ORIGINS` | `/dashboard` → CORS → 跨域白名单 |
| `OPENAI_TTS_API_KEY` | `/dashboard` 设置 → OpenAI 端鉴权 key |

**逐步迁移建议**:

1. 装 v0.2.0,启动时**不**带任何 `BYTEDANCE_TTS_*` env
2. 浏览器 `/setup`, 把原 env 里的值填到对应字段
3. 验证 `/v1/audio/speech` 正常
4. 下次部署可彻底删 env

**临时兼容**: 老 env 仍可作为 DB 缺失时的 fallback(为 0 重启零配置启动保留),但**不推荐生产用**。

## 资源 ID (重要)

V3 API **只允许两个资源 ID**:

| Resource ID | 说明 |
|---|---|
| `seed-tts-2.0` | 豆包语音合成大模型 2.0 (普通 TTS) |
| `seed-icl-2.0` | 豆包声音复刻大模型 2.0 (复刻 2.0) |

`volc.megatts.icl` / `volc.megatts.default` 等是 **1.0 API** 的资源 / 服务品类编码,**不是 v3 API 2.0 的合法资源 ID**。本项目用复刻 2.0,应填 `seed-icl-2.0`。

复刻音色(speaker 以 `S_` 开头,例如 `S_G8tEKnaJ1`)必须搭配 `seed-icl-2.0`,否则返回 `code=55000000 resource ID is mismatched`。

模型名: `seed-tts-2.0-standard` (这是**复刻 2.0 唯一的子模型名**,**和资源 ID 不同**)。

## 观测 / Metrics

Prometheus 文本格式,无鉴权。可直接被 Prometheus 抓取或浏览器查看。

主要指标:

| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
| `tts_request_total` | counter | status, format, speaker, model | /v1/audio/speech 请求数 |
| `tts_request_duration_seconds` | histogram | status, format | 端到端延迟 |
| `tts_upstream_total` | counter | status, format, model, speaker | 上游调用数 |
| `tts_upstream_duration_seconds` | histogram | status, format | 上游调用耗时 |
| `tts_upstream_first_byte_seconds` | histogram | format | TTFB |
| `tts_upstream_chunks_total` | counter | format | 收到的音频 chunk 数 |
| `tts_upstream_audio_bytes_total` | counter | format | 实际返回字节数 |
| `tts_upstream_errors_total` | counter | code | 上游错误 (聚合到 transport/client/server/upstream) |
| `tts_usage_text_words_total` | counter | model | 上游计费字符数 |
| `tts_concurrency_active` | gauge |  | 当前在飞请求数 |
| `tts_concurrency_rejected_total` | counter |  | 并发上限拒绝数 |
| `tts_ratelimit_rejected_total` | counter |  | 速率限制拒绝数 |
| `tts_auth_failed_total` | counter |  | API Key 鉴权失败数 |
| `tts_config_load_failures_total` | counter | mode | TTS 启动配置加载失败数 (告警用) |

**注意**: `speaker` 标签是 `sha1(speaker)[:8]` 哈希值,不是明文,保护火山复刻音色 ID 隐私。

### 告警示例

```yaml
- alert: TTSConfigLoadFailure
  expr: rate(tts_config_load_failures_total{mode="normal"}[5m]) > 0
  for: 1m
  labels: { severity: critical }
  annotations:
    summary: TTS service cannot start due to invalid config
```

## 公网部署安全清单

公网直接暴露 (`:8080` 可被互联网任意访问) 时,**至少满足以下两条之一**:

1. **设置 `OPENAI_TTS_API_KEY`** (推荐, 最简单)
   ```bash
   OPENAI_TTS_API_KEY=<32+ 位随机字符串>
   ```
   客户端请求时带 `Authorization: Bearer <那个字符串>`。

2. **前置反代承担鉴权** (nginx / caddy / Cloudflare Access)
   - 反代层做 basic auth / mTLS / Cloudflare Access 等任一方案
   - 反代**仅**把鉴权后的请求转发到 `:8080`
   - 此时 `OPENAI_TTS_API_KEY` 可不设

### v0.3.0 起各端点的暴露面

v0.3.0 已把健康与指标端点收口,**默认不再有匿名可读的监控端点**:

| 端点 | 默认状态 | 说明 |
|---|---|---|
| `/healthz` | **匿名可读** | 只回 `200 ok`,**不含任何字段**,专供探针 |
| `/health` | 需鉴权 | 完整健康数据 |
| `/metrics`(根路径) | **默认 404** | 需 `METRICS_ALLOW_CIDR` 才注册 |
| `/dashboard/*` | 需鉴权 | 管理面板(HTML 请求返回外壳,数据走 API) |
| `/api/admin/*` | 需鉴权 | 管理 API(含 `/api/admin/health`、`/api/admin/metrics`) |
| `/api/public/*` | 无鉴权 | 预留空壳,当前无业务 |

因此反代**只需**确保业务与管理接口不被匿名滥用;监控端点已由应用自身把关:

```nginx
# 若未配 METRICS_ALLOW_CIDR,根路径 /metrics 本就 404,无需额外规则。
# 若希望 Prometheus 走根路径,建议在应用侧配 METRICS_ALLOW_CIDR,而不是在反代做白名单。
location /dashboard { auth_basic "admin"; auth_basic_user_file /etc/nginx/.htpasswd; }
```

> ⚠️ **探针必须指向 `/healthz`**。K8s `livenessProbe`/`readinessProbe`、Docker `HEALTHCHECK`
> 默认不带 `Authorization`,若仍指向 `/health` 会一律 401,导致 Pod 反复重启 / 容器被判不健康。

## 部署

### Docker

```bash
# .env 至少含 TTS_ADMIN_KEY, 公网再加 OPENAI_TTS_API_KEY
docker compose up -d
```

`docker-compose.yml` 已配 named volume `tts-api-data` 挂载到容器 `/data`,DB 与 lock 文件持久化,容器重启不丢配置。
其 `healthcheck` 已使用 `/healthz`。

### Linux Systemd

参见 `v0.1.0 README`,**注意**:v0.2.0 启动前不需要 `EnvironmentFile` 含业务变量,只保留 `TTS_ADMIN_KEY`。

## 架构

| 包 | 职责 |
|---|---|
| `main.go` | 启动入口,模式检测 (setup/normal),fail-fast |
| `installer/` | 启动期模式检测,DB 自愈回退 |
| `setting/` | 全局配置 (TTSOptions / Auth / CORS) + 启动汇总 |
| `store/` | SQLite 数据访问 (settings / voices) + 自愈 |
| `controller/` | /v1/audio/speech、/healthz、/health、/setup、/dashboard、/api/setup、/api/admin/* |
| `middleware/` | SecurityHeaders, CORS, 鉴权, 限流, 并发, 日志, 客户端 IP 提取, install 模式守卫 |
| `router/` | 路由注册 |
| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端 |
| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出 |
| `metrics/` | TTS 业务指标注册 |
| `cmd/dumpdb/` | ops 工具: dump tts.db |
| `dto/` | 请求/响应类型 |
| `common/` | 常量 + 调试日志 |

## 常见问题

### 1. `code=55000000 resource ID is mismatched`

资源 / 音色不匹配。修复:
1. 火山控制台 → 语音技术 → 你的应用 → 资源管理
2. 用控制台在线体验/调试同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色
3. 控制台能合成的组合才是正确的
4. v3 API 复刻 2.0 用 `seed-icl-2.0`, **不要填 `volc.megatts.icl`**
5. 复刻音色 (speaker `S_` 开头) 需确认 Resource ID 已开通

### 2. `code=45000030 requested resource not granted`

账号未开通该资源。控制台 → 资源管理 → 申请开通。

### 3. 资源 ID 该填什么

v3 API 复刻 2.0 项目: **`seed-icl-2.0`** (固定)

`volc.megatts.icl` 是 1.0 服务品类编码,本项目用不了。

### 4. WAV 格式音频播放异常

流式场景下火山 API 的 wav 格式每个 chunk 都返回完整 wav header,拼接后损坏。本项目已自动处理:选择 wav 输出时,内部用 pcm 格式请求 API,本地拼装标准 wav header。如仍有问题,改用 `mp3`。

### 5. PowerShell 下 `curl` 解释错

PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名。**必须写 `curl.exe`**:

```powershell
curl.exe -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" --data-binary "@body.json"
```

JSON 用单引号包,或写到文件用 `--data-binary "@file.json"`。

### 6. 修改端口

```bash
PORT=8081 ./tts-api
```

或 `.env` 里改 `PORT=8081`。

## 技术支持

如有问题,请检查:
1. 服务启动后日志第一段 "环境配置汇总" — 火山必填项是否全 ✓
2. `/healthz` 返回 `ok`(存活);详细状态用鉴权接口 `/api/admin/health`,应返回 `status: "ok"` 且 `config_error: false`
3. `/dashboard` → 设置 tab 检查 API Key / 默认资源 ID / 默认音色
4. `/dashboard` → 音色 tab 检查 voice 是否启用
5. 火山控制台 → 在线体验同一对 resource + speaker 能合成
6. 客户端请求 URL 是否以 https:// 开头 (公网)
7. `/dashboard` → 设置 → CORS 检查白名单含前端完整 origin

## 许可证

本项目采用非商业用途许可协议。详细条款请参阅 [LICENSE](LICENSE) 文件。