diff --git a/.env.example b/.env.example index b44a3c9..e8a21d2 100644 --- a/.env.example +++ b/.env.example @@ -1,69 +1,33 @@ -# 字节火山引擎 TTS v3 API 配置示例 -# 将此文件复制为 .env 并填入实际配置 +# 字节火山引擎 TTS v3 → OpenAI 兼容接口 +# 配置文件示例 · 复制为 .env 后填入 # ========================================== -# 必需的环境变量 +# 启动引导环境变量(4 个,启动前必看) # ========================================== +# 业务配置(api_key / resource_id / speaker / 格式 / 采样率 ...)通过 WebUI 设置, +# 不再需要在这里配。M3 起所有 BYTEDANCE_TTS_* 已搬入数据库。 -# 火山引擎新版控制台获取的 API Key -BYTEDANCE_TTS_API_KEY=your_api_key_here +# 1. 安装 token(必设,首次 /setup 时校验) +# 留空 = 不设 token,任何人可调 /api/setup(适合本地开发) +# 正式部署务必设复杂字符串 +TTS_ADMIN_KEY= -# 资源信息ID(决定使用1.0还是2.0模型) -# 复刻 2.0 音色(seed-icl-2.0) -BYTEDANCE_TTS_RESOURCE_ID=seed-icl-2.0 +# 2. 数据库路径(可选, 默认 ./tts.db) +# Docker 部署务必改成挂载路径,例: /data/tts.db +# TTS_DB_PATH=/data/tts.db -# 发音人(音色)ID -BYTEDANCE_TTS_SPEAKER=your_speaker_id_here - -# ========================================== -# 可选的环境变量 -# ========================================== - -# 单次合成超时,默认30s -BYTEDANCE_TTS_TIMEOUT=30s - -# 上游实际请求的音频格式:mp3 / pcm / ogg_opus -# 客户端要求 wav 时,内部自动转 pcm 上游 + 本地拼 WAV 头 -BYTEDANCE_TTS_FORMAT=mp3 - -# 上游采样率:8000/16000/22050/24000/32000/44100/48000 -BYTEDANCE_TTS_SAMPLE_RATE=24000 - -# MP3 比特率(可选),仅 MP3 生效 -# BYTEDANCE_TTS_BIT_RATE=128000 - -# 复刻 2.0 子模型(可选),留空则使用控制台默认值 -# seed-tts-2.0-standard:标准版,延时更优 -# seed-tts-2.0-expressive:表现力增强版,支持 QA / Cot -# BYTEDANCE_TTS_MODEL=seed-tts-2.0-standard - -# 复刻 2.0 模型类型(可选,推荐显式指定) -# 4 = ICL V2,5 = ICL V3 -# BYTEDANCE_TTS_MODEL_TYPE=4 - -# 非中文/英文合成时指定语种(可选) -# zh-cn / en / ja / es-mx / id / pt-br / ko -# BYTEDANCE_TTS_EXPLICIT_LANGUAGE=zh-cn - -# 复刻 2.0 启用字级时间戳(可选) -# BYTEDANCE_TTS_ENABLE_SUBTITLE=false - -# OpenAI兼容接口的API密钥(可选,多个用逗号分隔) -OPENAI_TTS_API_KEY=your_openai_compatible_key_here - -# 反代拓扑配置(0-10)。控制 X-Forwarded-For 解析方式,影响 IP 限流的 key。 -# 不设置 / 0:启发式模式(默认)—— 从 XFF 链尾扫描,跳过私有 IP,返回第一个公网 IP -# 适合 90% 部署(单跳/多跳/直出),无需了解精确跳数 -# N (N>0) :精确模式 —— 精准到真实 client IP,需要正确配置跳数 -# N=1:单跳反代(client → nginx → 本服务) -# N=2:双跳反代(client → CDN → nginx → 本服务,如 Cloudflare + nginx) -# N=3:三跳,以此类推 -# 直出部署(无反代):无需配置,XFF 分支不会执行 -# 详见 README "反代拓扑与 X-Forwarded-For 解析"章节 -# TRUSTED_PROXY_HOPS= - -# CORS 跨域白名单(逗号分隔;开发环境可设 *;空则拒绝所有跨域) -# ALLOWED_ORIGINS=https://example.com,https://app.example.com - -# 服务监听端口,默认8080 +# 3. 服务监听端口(可选, 默认 8080) PORT=8080 + +# 4. OpenAI 兼容接口的鉴权 key(可选) +# 不设 = 不鉴权,任何人能调 /v1/audio/speech(适合内网/反代后) +# 多个 key 用逗号分隔 +# 公网部署必设,见 README "公网部署安全清单" +OPENAI_TTS_API_KEY= + +# ========================================== +# 装完后可改(也支持环境变量作为 DB 缺失时的 fallback) +# ========================================== +# X-Forwarded-For 解析跳数(可选, 0=启发式默认, N>0=精确 N 跳反代) +# 装好后推荐到 /admin 改 trusted_proxy_hops +# TRUSTED_PROXY_HOPS=2 diff --git a/.gitignore b/.gitignore index 0ecf443..354c378 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ *.test *.out +# Go test sources (prevent accidental commit; tests live outside the repo by policy) +*_test.go + # Editor / OS .vscode/ .idea/ @@ -19,4 +22,25 @@ Thumbs.db !.env.example # Local-only working notes (use task board for shared tracking) -TODO.md \ No newline at end of file +TODO.md + +# Release artifacts (build output) +release/ + +# Local build output (start-local.ps1 builds to bin/) +bin/ + +# Local dev scripts (per-user; not part of repo) +start-local.ps1 + +# Runtime database artifacts (created by M1 installer flow) +tts.db +tts.db-* +tts.db.* +installed.lock + +# UI handoff bundle (for external AI redesign work; not deployed) +ui-handoff/ + +# Docs (本地草稿,不入库) +docs/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..563c7cd --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,48 @@ +# Changelog + +本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。 + +## [0.2.0] - 2026-08-30 + +### 新增 + +- **M0 · SQLite + store 包**: 引入 `modernc.org/sqlite` (无 CGO), 所有运行时配置 (settings + voices) 持久化到 SQLite +- **M1 · 安装流程**: 首次启动进入 `/setup` 向导, 通过 4 步表单收集凭证 + 默认音色 + 音色列表, 完成后写 `installed.lock` 锁定 + - 引导页无外部依赖: Vue 3.4 + axios 1.6 via bootcdn, `//go:embed` 进 binary + - **自愈回退**: 检测到 DB 损坏自动备份 + 转 setup 模式 (不丢数据) +- **M2 · WebUI 后台**: `/admin` 单页 SPA, 含登录 / 仪表盘 / 音色管理 / 设置 / CORS 配置 + - 默认鉴权基于 `auth_key` (DB), 失败计数 + 限流 + - 浏览器安装修复: 同源请求跳过 CORS 校验, install 模式完全跳过 CORS +- **M3 · 全局设置 + 声音路由**: + - `default_speaker` 是 voice **名字** (如 `chun`), 路由时查 voice 表拿到真 speaker ID (如 `S_G8tEKnaJ1`) + - `/v1/audio/speech` 支持 `voice=` 动态路由, 命中但 enabled=0 返回 403 + - 未知 voice 返回 400 `unknown_voice: ''` + - 禁用 voice 返回 403 `voice '' is disabled` +- **OpenAI 端 key 走 DB**: `auth_key` 设置项, 不再依赖 `OPENAI_TTS_API_KEY` env +- **CORS 全 DB 化**: `cors_origins` / `cors_allow_all` 走 `/admin` 设置, install 模式跳过 +- **CORS 修复**: 同源请求跳过 CORS 校验 (避免浏览器自家人拦自家人) +- **运营工具**: `cmd/dumpdb` — 离线 dump tts.db 的 settings + voices +- **fail-fast**: normal 模式下 TTS 配置损坏 → `log.Fatalf` 退出, 触发 K8s / Docker 重启 + - 配套 metric `tts_config_load_failures_total{mode="normal"}` 便于告警 + - `/health` body 加 `error` 字段直接展示失败原因 +- **speaker ID 隐私保护**: 日志里 `telemetry.MaskSpeaker` (`S_G8****naJ1`); `/metrics` 标签用 `telemetry.SpeakerLabel` (sha1[:8]) + +### 修复 + +- **resource_id 覆盖**: `LoadRuntimeConfig` 之前用 voice 行的 `resource_id` 覆盖 settings 里的, 导致用户设的 `default_resource_id` 永远没机会生效。现在 settings 优先, voice 行的 resource_id 仅在 `voice=` 显式传时使用 +- **默认值修正**: 把过时的 `volc.megatts.icl` / `volc.megatts.default` 全部改成 v3 API 2.0 复刻项目唯一合法的 `seed-icl-2.0`; 模型名统一 `seed-tts-2.0-standard` +- **log 格式一致**: voice 命中 log 跟合成 log 同样打码 +- **setup UX 改进**: voice 行 `resource_id` 留空时, 自动用 settings 里的 `default_resource_id` 兜底, 避免 settings / voice 资源 ID 不一致导致 500 +- **/admin dashboard banner 误报**: `reloadAll()` 加 `loadSettings()`, 避免 "CORS 未配置" 黄条永远显示 + +### 变更 + +- **.env.example 收敛**: 移除 `BYTEDANCE_TTS_*` 业务 env, 只留 4 个引导 env (`TTS_ADMIN_KEY` / `TTS_DB_PATH` / `PORT` / `OPENAI_TTS_API_KEY`); 业务配置走 WebUI +- **docker-compose**: 加 `tts-data` named volume 持久化 tts.db +- **Dockerfile**: 准备 `/data` 目录, appuser 可写, 解决 tts.db 落盘权限 + +## [0.1.0] - 初版 + +- 火山 TTS v3 → OpenAI 兼容 `/v1/audio/speech` 单二进制 +- 配置全 env 驱动 (`BYTEDANCE_TTS_*` 11 个) +- 限流 / 鉴权 / Prometheus metrics / CORS / 反代 XFF 解析 diff --git a/Dockerfile b/Dockerfile index 95f50e1..a7b965c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -25,15 +25,18 @@ RUN apk --no-cache add ca-certificates tzdata \ WORKDIR /app COPY --from=builder /app/tts-api . -COPY --from=builder /app/health.html . +# health.html 已通过 //go:embed 嵌入 binary,无需单独复制 -RUN chown -R appuser:appgroup /app +# 准备 /data 目录存 SQLite (tts.db + installed.lock) +# appuser 必须可写,否则启动后无法创建 DB +RUN mkdir -p /data \ + && chown -R appuser:appgroup /app /data USER appuser EXPOSE 8080 -HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \ +HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ CMD wget -qO- http://localhost:8080/health || exit 1 ENTRYPOINT ["./tts-api"] diff --git a/PROJECT_BOOK.md b/PROJECT_BOOK.md new file mode 100644 index 0000000..9bce488 --- /dev/null +++ b/PROJECT_BOOK.md @@ -0,0 +1,391 @@ +# 火山 TTS 聚合平台 · 项目书（v0.1） + +> 定位：个人自用（无甲方）· 单机部署 · 单二进制分发 +> 基线代码：Volcano-Engine-TTS-UI（develop 分支，Go，约 2900 行） + +--- + +## 1. 项目概述 + +### 1.1 背景与动机 + +现有 `Volcano-Engine-TTS-UI` 是一个"火山引擎 TTS v3 → OpenAI 兼容接口"的适配器，已具备 `/v1/audio/speech`、多格式输出、鉴权限流、Prometheus 观测等能力。当前存在三个核心问题： + +1. **配置全部堆在环境变量里**：API Key、资源 ID、音色、采样率……随音色增长会持续"溢出"，无法维护。 +2. **音色是静态的**：`voice`/`model` 请求字段被接收但忽略，只支持 env 里配死的单音色。 +3. **首次启动没有入口**：无 UI、无数据库，配置只能靠手写 env。 + +### 1.2 项目目标 + +把该项目升级为**自用聚合平台**： + +- 用 **SQLite** 接管所有运行时可变配置（全局设置 + 音色库），环境变量只保留 3 个左右引导参数； +- 提供**引导式安装 UI**：首次启动（未安装）进入 `/setup` 向导收集配置，写入数据库后即完成安装； +- 采用 **lock 文件**作为安装状态判据，支持"损坏自动回退、可重置安装"； +- `/v1/audio/speech` 的 `voice` 参数**按数据库路由**，实现多音色动态切换； +- 保持**单二进制分发**（SQLite 用纯 Go 驱动，`//go:embed` 嵌入引导页）。 + +### 1.3 设计原则 + +| 原则 | 说明 | +|---|---| +| 数据库为唯一配置源 | 运行时的全局参数、音色全部读库，不做"库 + env 双轨" | +| 环境变量只做引导 | 仅保留 DB 路径、端口、初始化凭证 | +| lock 是安装门卫 | 存在 = 已安装；不存在 = 安装模式；损坏 = 备份 + 删 lock + 回退 | +| 损坏可自愈 | 库异常自动备份留档并回退安装模式，不裸奔 | +| 先内核后 UI | 本期只做"引导页"（安装必需），完整管理后台后置 | + +--- + +## 2. 需求范围 + +### 2.1 本期（MVP）范围 + +| 编号 | 需求 | 说明 | +|---|---|---| +| R1 | SQLite 接入 | `modernc.org/sqlite`（纯 Go、无 CGO），自动建表、轻量迁移 | +| R2 | 全局配置入库 | `settings` 表接管现有全部 TTS 全局环境变量 | +| R3 | 音色库 | `voices` 表：name → speaker/resource_id/model/…，支持增删改查 | +| R4 | 安装状态检测 | `installed.lock` 判据 + 启动判定流程 | +| R5 | 引导式安装 UI | `/setup` 引导页（首次启动数据收集）+ `POST /api/setup` | +| R6 | 安装模式路由守卫 | 未安装时全站只开放 `/setup`，其余返回 503/跳转 | +| R7 | voice 动态路由 | `/v1/audio/speech` 按 `voice` 查库路由到火山 | +| R8 | 音色管理 API | `GET/POST /api/voices`、`PUT/DELETE /api/voices/:id`（带鉴权） | +| R9 | 损坏回退 | 库校验失败 → 备份 `.corrupt-` → 删 lock → 重新安装 | +| R10 | 环境变量收敛 | 迁移后 env 仅剩：`TTS_DB_PATH`、`PORT`、初始化凭证 | + +### 2.2 后置（不在本期） + +- 完整管理后台（音色列表/用量图表/配置管理） +- 多服务商聚合（火山 / OpenAI / 微软统一适配） +- 流式实时输出（SSE/WebSocket） +- TTS 结果缓存、长文本自动分片、字幕透出 +- ASR 转写端点（`/v1/audio/transcriptions`） + +--- + +## 3. 总体架构 + +``` +┌───────────────────────────── 单二进制 tts-api ─────────────────────────────┐ +│ │ +│ main.go ── 启动：初始化 DB → 安装状态检测 → 加载配置 → 路由 → 监听 │ +│ │ +│ ┌────────────┐ ┌─────────────┐ ┌────────────────────────────────────┐ │ +│ │ installer/ │──▶│ store/ │ │ router/ │ │ +│ │ lock 检测 │ │ SQLite 访问 │ │ /setup(引导页·embed) /api/setup │ │ +│ │ 安装模式 │ │ settings │ │ /api/voices* /v1/audio/speech│ │ +│ └────────────┘ │ voices │ │ /health /metrics /dashboard │ │ +│ └─────────────┘ └────────────────────────────────────┘ │ +│ │ +│ controller/ ── 语音合成(查库路由) · setup · voices CRUD │ +│ middleware/ ── 鉴权 · 限流 · 并发 · 安装守卫 │ +│ setting/ ── 仅保留引导参数(DB路径/端口/凭证) + 启动汇总 │ +│ adapter/volcano/ ── 火山 v3 客户端（不改，仅入参来源变为 DB） │ +└──────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 4. 技术选型 + +| 项 | 选型 | 理由 | +|---|---|---| +| 语言 | Go（沿用） | 现有项目基线，无迁移成本 | +| 数据库 | SQLite（`modernc.org/sqlite`） | 纯 Go 无 CGO，保持 `CGO_ENABLED=0` 单二进制；单文件零运维 | +| 前端 | Vue3 + axios（沿用 dashboard 技术栈） | 复用现有 `//go:embed` 模式，`setup.html` 嵌入二进制 | +| 路由 | gorilla/mux（沿用） | 现有实现 | +| 构建 | 保持单二进制 | `//go:embed` 内嵌引导页与监控页 | + +> 依赖注意：`modernc.org/sqlite` 体积较大（约 30-40MB 二进制），如介意可换 `mattn/go-sqlite3`（需 CGO，破坏单二进制），**本项目选前者**。 + +--- + +## 5. 数据模型设计 + +### 5.1 `settings` 表（全局配置） + +```sql +CREATE TABLE IF NOT EXISTS settings ( + key TEXT PRIMARY KEY, -- 配置键名 + value TEXT NOT NULL, -- 配置值（统一存字符串，读取时按需转换） + updated_at TEXT NOT NULL DEFAULT (datetime('now')) +); +``` + +初始化后必填的键： + +| key | 说明 | 来源（原环境变量） | +|---|---|---| +| `api_key` | 火山 API Key | `BYTEDANCE_TTS_API_KEY` | +| `default_resource_id` | 默认资源 ID | `BYTEDANCE_TTS_RESOURCE_ID` | +| `default_speaker` | 默认音色 | `BYTEDANCE_TTS_SPEAKER` | +| `initialized` | 安装完成标记 `"1"` | —（双保险，配合 lock） | + +可选键（读取时带默认值）： + +| key | 默认值 | 来源 | +|---|---|---| +| `default_format` | `mp3` | `BYTEDANCE_TTS_FORMAT` | +| `sample_rate` | `24000` | `BYTEDANCE_TTS_SAMPLE_RATE` | +| `timeout` | `30s` | `BYTEDANCE_TTS_TIMEOUT` | +| `model` | 空 | `BYTEDANCE_TTS_MODEL` | +| `model_type` | 空 | `BYTEDANCE_TTS_MODEL_TYPE` | +| `explicit_language` | 空 | `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` | +| `enable_subtitle` | `false` | `BYTEDANCE_TTS_ENABLE_SUBTITLE` | + +> 迁移建议：首次安装时若检测到旧的对应环境变量仍存在，可作为引导页**预填默认值**（仅预填，不替代库），便于老用户平滑迁移。 + +### 5.2 `voices` 表（音色库） + +```sql +CREATE TABLE IF NOT EXISTS voices ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL UNIQUE, -- 对外 voice 名，请求里 voice 字段查它 + speaker TEXT NOT NULL, -- 火山音色 ID（复刻音色以 S_ 开头） + resource_id TEXT NOT NULL, -- 对应火山资源 ID（决定计费/模型族） + model TEXT DEFAULT '', -- 子模型 seed-tts-2.0-standard / -expressive + language TEXT DEFAULT '', -- 显式语种（可选） + description TEXT DEFAULT '', -- 备注 + enabled INTEGER NOT NULL DEFAULT 1, -- 0/1 启用 + created_at TEXT NOT NULL DEFAULT (datetime('now')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')) +); +CREATE UNIQUE INDEX IF NOT EXISTS idx_voices_name ON voices(name); +``` + +> 默认音色：`settings.default_speaker` 表示请求**未传 voice** 时用的音色；也可以约定默认 voice 名为 `default` 的行，二选一，建议用 settings 字段（更直观）。 + +--- + +## 6. 安装与启动流程设计 + +### 6.1 lock 判据 + +- lock 文件：`/installed.lock`（与 `tts.db` 同目录）。 +- **存在 = 已成功完成过安装**；不存在 = 未安装。 +- lock 内容：一行文本 `version <版本号> <初始化时间>`，便于未来判断是否需要重装/迁移。 +- 写入时机：**先写库、后写 lock**（`/api/setup` 成功后、且通过完整性校验后才原子创建 lock），避免"lock 在、库是半成品"。 +- **不用 `.db` 文件是否存在作为安装判据**（建表会自动创建 db 文件，无法区分"从未安装"和"已安装"）。 + +### 6.2 启动判定流程 + +``` +main 启动 + ├─ 解析引导环境变量（TTS_DB_PATH / PORT / 初始化凭证） + ├─ store.Open()（打开/创建 SQLite，自动建表） + │ + ├─ installed.lock 不存在？ + │ └─ YES → 进入【安装模式】：仅开放 /setup（静态资源 + 引导页 + POST /api/setup） + │ 其余路由（/v1/audio/speech、/api/voices 等）→ 503 + 跳转 /setup + │ └─ NO → 尝试读库 + PRAGMA integrity_check + │ ├─ 通过 → 加载 settings/voices 到内存缓存 → 【正常模式】 + │ └─ 失败 → 备份 tts.db → tts.db.corrupt-<时间戳> + │ → 删除 installed.lock → 进入【安装模式】 + │ + └─ 打印启动摘要（模式 / DB路径 / lock状态 / 音色数） +``` + +### 6.3 损坏回退规则 + +1. 只在 lock 存在但库打不开 / `integrity_check` 失败时触发回退； +2. **先备份**：损坏的 `.db` 改名 `tts.db.corrupt-` 留档，不直接删除； +3. 删除 `installed.lock`，进入安装模式； +4. 日志明确打印回退原因（文件损坏 / 权限 / 磁盘 / 版本等），便于排查； +5. 回退后用户重新走 `/setup` 即可恢复。 + +### 6.4 setup 劫持防护（必须） + +安装模式是"谁先访问谁配置"，公网暴露时存在被抢先初始化的风险。防护方案（至少一项）： + +- **A（推荐）初始化凭证**：启动时打印一次性 setup token（或从环境变量 `TTS_ADMIN_KEY` 指定），引导页提交时必须带 token，校验通过才写入； +- **B 回环限制**：安装模式下 `/setup` 仅允许本机回环地址访问（`127.0.0.1`），初始化完成后即失效； +- 二者可叠加。初始化完成后 `/api/setup` 永久关闭。 + +--- + +## 7. 接口设计 + +### 7.1 安装相关 + +| 方法 | 路径 | 说明 | 鉴权 | +|---|---|---|---| +| GET | `/setup` | 引导页 HTML（`//go:embed`） | 安装模式开放 | +| GET | `/api/setup/status` | 返回 `{installed: bool}`，供引导页判断 | 无 | +| POST | `/api/setup` | 提交初始配置（全局 + 音色列表 + token）→ 写库 → 写 lock | 初始化凭证 | + +`POST /api/setup` 请求体示例： + +```json +{ + "token": "一次性凭证", + "settings": { + "api_key": "xxx", + "default_resource_id": "volc.megatts.default", + "default_speaker": "zh_female_qingxin", + "default_format": "mp3", + "sample_rate": 24000 + }, + "voices": [ + { "name": "qian", "speaker": "S_xxx", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-standard" }, + { "name": "xun", "speaker": "S_yyy", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-expressive" } + ] +} +``` + +响应：`200 {ok:true, message:"installed"}` 或 `400/401/409`。 + +### 7.2 音色管理（正常模式） + +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/voices` | 列表（可分页/过滤 enabled） | +| POST | `/api/voices` | 新增音色（name 唯一冲突返回 409） | +| PUT | `/api/voices/:id` | 更新音色 | +| DELETE | `/api/voices/:id` | 删除音色（`default_speaker` 引用的音色禁止删除） | + +鉴权：复用现有 `OPENAI_TTS_API_KEY`（Bearer）。若安装后用户未配置管理 Key，可提示在 settings 中配置。 + +### 7.3 语音合成（改造点） + +`/v1/audio/speech` 改造逻辑： + +``` +收到请求 + ├─ voice 为空 → 用 settings.default_speaker（无默认 → 400 "no default voice"） + ├─ voice 非空 → 查 voices 表 + │ ├─ 命中 → 用该行 speaker/resource_id/model/language 覆盖 opts + │ └─ 未命中 → 400 "unknown voice: " + ├─ model 非空 → 查库/映射（本期：model 仅校验长度，不做映射，或按 settings 默认） + └─ 其余逻辑不变（格式解析、speed、鉴权、限流、埋点） +``` + +### 7.4 现有端点（不变） + +`/health`、`/metrics`、`/dashboard`、`/` 行为保持；但**安装模式下**除 `/setup` 外统一返回 503（`/health` 可返回 `installed:false` 便于部署探针识别未初始化）。 + +--- + +## 8. 模块划分与代码改动清单 + +### 8.1 新增包 + +| 包 | 职责 | 关键文件 | +|---|---|---| +| `store/` | SQLite 访问层：打开/建表/迁移、settings CRUD、voices CRUD、integrity_check | `db.go`、`settings.go`、`voices.go`、`migrate.go` | +| `installer/` | 安装状态：lock 检测/创建/删除、安装模式判定、损坏回退 | `lock.go`、`bootstrap.go` | + +### 8.2 改造文件 + +| 文件 | 改动 | +|---|---| +| `router/router.go` | 新增 `/setup`、`/api/setup/*`、`/api/voices`；安装模式路由守卫 | +| `controller/` | 新增 `setup.go`（安装提交）、`voices.go`（CRUD）；改造 `tts.go`（voice 查库路由） | +| `middleware/` | 新增 `installguard.go`（安装模式拦截，未安装非 `/setup` → 503） | +| `setting/config.go` | 收敛：仅读 `TTS_DB_PATH`、`PORT`、初始化凭证；启动汇总展示"模式/lock/音色数" | +| `main.go` | 启动流程：初始化 DB → 安装检测 → 模式分支 | +| `router/setup.html` | 新增引导页（Vue3 + axios，`//go:embed`） | +| `go.mod` | 新增 `modernc.org/sqlite` | +| `.env.example` / `README.md` / `docker-compose.yml` | 更新为新的引导参数与首次安装说明 | + +### 8.3 环境变量收敛表 + +**迁移前（现状，会持续膨胀）：** + +``` +BYTEDANCE_TTS_API_KEY +BYTEDANCE_TTS_RESOURCE_ID +BYTEDANCE_TTS_SPEAKER +BYTEDANCE_TTS_FORMAT +BYTEDANCE_TTS_SAMPLE_RATE +BYTEDANCE_TTS_BIT_RATE +BYTEDANCE_TTS_MODEL +BYTEDANCE_TTS_MODEL_TYPE +BYTEDANCE_TTS_EXPLICIT_LANGUAGE +BYTEDANCE_TTS_ENABLE_SUBTITLE +BYTEDANCE_TTS_TIMEOUT +BYTEDANCE_TTS_DEBUG +OPENAI_TTS_API_KEY +ALLOWED_ORIGINS +TRUSTED_PROXY_HOPS +PORT +``` + +**迁移后（仅引导参数，其余进库）：** + +``` +TTS_DB_PATH # 数据库/lock 目录（默认 ./） +PORT # 监听端口 +TTS_ADMIN_KEY # 安装初始化凭证（可选，不设则启动打印一次性 token） +OPENAI_TTS_API_KEY # 管理 API / 合成 API 鉴权（可选，迁移进 settings 或保留） +ALLOWED_ORIGINS # CORS（可保留，属运行环境而非业务配置） +TRUSTED_PROXY_HOPS # 反代拓扑参数（保留，属部署环境） +``` + +> `BYTEDANCE_TTS_DEBUG`、`TRUSTED_PROXY_HOPS`、`ALLOWED_ORIGINS` 属"部署/运维环境"而非"业务配置"，可留在 env；其余 TTS 业务配置全部进库。 + +--- + +## 9. 安全设计 + +| 项 | 措施 | +|---|---| +| Setup 劫持 | 初始化凭证（`TTS_ADMIN_KEY` 或一次性 token）+ 可选回环限制；完成后 `/api/setup` 永久关闭 | +| 合成/管理鉴权 | 复用 `OPENAI_TTS_API_KEY`（Bearer）；voice 路由不绕过鉴权 | +| 敏感信息 | API Key 在引导页只进不出；日志/`/health` 不回显明文 Key（沿用 `maskAPIKey`） | +| 输入校验 | voice 名白名单（字母数字 `_-`）、长度限制；SQL 全部参数化，防注入 | +| lock/DB 写入 | 先写库后写 lock；lock 原子创建；损坏先备份再回退 | +| 默认音色保护 | 删除被 `default_speaker` 引用的音色时拒绝（409） | + +--- + +## 10. 开发计划与里程碑 + +| 里程碑 | 内容 | 验收标准 | +|---|---|---| +| M1 存储层 | `store/` 包：SQLite 接入、两表建表、迁移、settings/voices CRUD、`integrity_check` | `go build` 通过；单测覆盖 CRUD | +| M2 安装流程 | `installer/`：lock 检测/创建/删除、安装模式判定、损坏回退；`middleware/installguard` | 无 lock → 安装模式；有 lock → 正常模式；损坏库 → 备份+回退 | +| M3 引导 UI | `/setup` 引导页 + `POST /api/setup`（token 校验、写库、写 lock） | 首次访问可完成安装；重复安装被拒；token 错误 401 | +| M4 音色路由 | `/api/voices` CRUD + `/v1/audio/speech` voice 查库路由 | 新增音色后 voice 生效；未知 voice 400；默认音色兜底 | +| M5 收敛与文档 | `setting/` 收敛、`.env.example`/README/部署更新、启动摘要展示模式与音色数 | 迁移后仅引导 env；文档与行为一致 | +| M6 测试收尾 | 覆盖 lock 判定、setup 流程、voice 路由、损坏回退的集成测试 | 关键路径有自动化测试 | + +建议 M1→M2 连续做（安装流程是主链路），M3 与 M2 可并行；M4 依赖 M1 完成。 + +--- + +## 11. 风险与对策 + +| 风险 | 影响 | 对策 | +|---|---|---| +| `modernc.org/sqlite` 体积增大 | 单二进制从 ~7MB 增至 ~40MB | 接受；如不可接受改 CGO 版（牺牲单文件） | +| Setup 劫持（公网部署） | 他人抢先配置 | 初始化凭证 + 回环限制 + 完成后关闭端点（见 6.4） | +| 库损坏导致服务不可用 | 服务起不来 | 自愈回退：备份 + 删 lock + 重新安装（见 6.3） | +| 老用户迁移 | 现有 env 用户升级后无库 | 引导页预填旧 env 值；README 给出迁移步骤 | +| voice 名冲突/默认引用 | 删除默认音色致不可用 | 唯一约束 + 默认音色删除保护（409） | +| 并发写库 | 数据竞争 | 单写锁（`database/sql` 默认 + 业务层互斥），单用户场景风险低 | +| 表结构未来升级 | 旧库不兼容 | lock 内容带版本号；`migrate.go` 预留版本迁移 | + +--- + +## 12. 验收标准（本期 MVP） + +1. 删除所有业务 env 后，首次启动进入 `/setup` 引导页，可完成安装（全局 + ≥1 音色）； +2. 安装完成后有 `installed.lock`，重启进入正常模式，`/v1/audio/speech` 可用； +3. 通过 `/api/voices` 新增音色后，请求带该 `voice` 能正常合成；未知 voice 返回 400； +4. 未传 `voice` 时使用默认音色； +5. 手动制造损坏库 → 自动备份 `.corrupt-*` 并删 lock 回退安装模式； +6. 安装模式下 `/v1/audio/speech` 返回 503 或跳转 `/setup`； +7. 单二进制运行，无外部文件依赖（引导页已 embed）。 + +--- + +## 13. 非目标（明确不做） + +- 本期不做多服务商聚合、流式输出、缓存、字幕透出、ASR； +- 不做完整的运营管理后台（仅引导页，管理 API 先行）； +- 不做多租户/多用户体系（个人自用，单管理员）。 + +--- + +*文档版本：v0.1 · 状态：待评审 · 配套代码基线：Volcano-Engine-TTS-UI @ develop* diff --git a/README.md b/README.md index c46c6e4..ae111ea 100644 --- a/README.md +++ b/README.md @@ -1,337 +1,212 @@ -# 字节跳动火山引擎TTS v3 API 转 OpenAI 兼容接口 +# 字节火山引擎 TTS v3 → OpenAI 兼容接口 -## 项目简介 +将火山引擎 TTS v3 API 封装为 OpenAI 兼容的 `/v1/audio/speech` 端点,自带引导式安装、WebUI 后台、SQLite 持久化、Prometheus 观测。单二进制,无外部服务依赖。 -本项目将字节跳动火山引擎TTS（文本转语音）v3 API 封装为 OpenAI 兼容的 TTS API 接口,使原本调用 OpenAI TTS 服务的应用可以无缝切换到火山引擎。 - -### 主要特性 +## 特性 - 完全兼容 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) +- **引导式安装**: 首次启动自动进入 `/setup` 向导,无需手写 env +- **WebUI 后台** `/admin`: 音色管理 / 全局设置 / CORS 配置 / 鉴权 +- **音色库**: 多 voice 动态路由,未知 / 禁用 voice 返回明确错误 +- **多格式输出**: mp3 / ogg_opus / pcm / wav (内部转 pcm + 本地拼头) / aac / flac +- **鉴权 + 限流**: API Key 校验, IP 速率限制, 全局并发限制 +- **观测**: Prometheus 文本格式 `/metrics` + 服务状态 `/health`, 零外部依赖 +- **跨平台**: Windows / Linux / macOS / Docker ## 快速开始 -### 前置要求 - -- Go 1.26 或更高版本 -- 火山引擎账号并开通 TTS 服务 - ### 1. 编译 ```bash go build -o tts-api . ``` -### 2. 配置环境变量 - -复制 `.env.example` 为 `.env` 并填入实际配置: +### 2. 启动 ```bash -cp .env.example .env -``` - -### 3. 启动 - -```bash -# Windows -tts-api.exe - -# Linux/macOS +# 默认: 端口 8080, 监听 localhost ./tts-api ``` -服务默认监听 `8080` 端口,可通过 `PORT` 环境变量修改。 +启动后浏览器打开 `http://localhost:8080/setup`,完成 4 步引导: -## 环境变量配置 +1. 凭证: 火山 API Key + OpenAI 端鉴权 key +2. 默认路由: 默认资源 ID (复刻 2.0 用 `seed-icl-2.0`) + 默认音色名 +3. 音色列表: 每个 voice 的对外名 + 火山 speaker ID +4. 确认提交 -### 必需参数 +完成后自动跳转到 `/admin`,从这里登录管理。 -| 变量名 | 说明 | -|--------|------| -| `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);**此值直接写入 WAV 头,需与上游实际 PCM 采样率一致,否则音频变速变调** | `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(逗号分隔支持多个);**未设置时鉴权完全关闭** | 无(不鉴权) | -| `TRUSTED_PROXY_HOPS` | X-Forwarded-For 解析模式(0=启发式/默认,>0=精确 N 跳) | `0`(启发式) | -| `PORT` | 服务监听端口 | `8080` | -| `ALLOWED_ORIGINS` | CORS 跨域白名单(逗号分隔,调试可设 `*`;空则拒绝所有跨域) | 无 | - -### 反代拓扑与 X-Forwarded-For 解析 - -当服务部署在反代(nginx / caddy / CDN)后面时,反代会通过 `X-Forwarded-For`(XFF)头传递真实客户端 IP。本服务通过 `TRUSTED_PROXY_HOPS` 环境变量控制 XFF 解析方式,支持两种模式。 - -#### 何时需要关心这个配置 - -| 部署方式 | 是否需要配置 | -|---|---| -| 服务直接暴露公网 IP(无反代)| ❌ 不适用,跳过本节 | -| 服务前有 1 个反代(nginx / caddy)| ❌ 不必配置,启发式模式自动处理 | -| 服务前有 2 跳以上反代(CDN + 自建反代)| ⚠️ 启发式模式"够用",需要精准按真实 client 限流时再设 | - -> **直出部署(无反代)的用户**:本节不适用,跳过阅读。`TRUSTED_PROXY_HOPS` 在你的部署下不会被读取。 - -#### 启发式模式(默认 / `TRUSTED_PROXY_HOPS=0`) - -从 XFF 链尾向前扫描,**跳过私有 IP,返回第一个公网 IP**。 - -适用场景:单跳反代(最常见)、多跳含公网代理(CDN + nginx)。 - -**行为示例**: - -| XFF 链 | 启发式返回 | 备注 | -|---|---|---| -| `1.2.3.4` | `1.2.3.4` | 单跳,真实 client | -| `fake, 1.2.3.4` | `1.2.3.4` | 攻击者伪造首值,跳过 fake | -| `1.2.3.4, 5.6.7.8, 10.0.0.1` | `5.6.7.8` | 多跳,返回最末公网 IP(CDN 边缘) | -| `1.2.3.4, 192.168.1.1` | `1.2.3.4` | 链尾是私有 IP,跳过 | - -**优点**:零配置,大多数部署自动正确。 - -**限制**:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"而非"按真实 client"。攻击者填满某 CDN 边缘配额可能影响该 CDN 下的其他用户——但无法伪造身份、无法越权。 - -#### 精确模式(`TRUSTED_PROXY_HOPS=N`,N > 0) - -从 XFF 链尾倒数第 N+1 个位置取值,即"信任最近 N 跳反代,取该信任链之前那一跳的 IP"。 - -适用场景:多跳 CDN + 反代,且需要精准按真实 client 限流。 - -**N 的确定方法**:统计客户端到本服务之间的反代跳数。 - -| 拓扑 | 跳数 | 配置 | -|---|---|---| -| `client → nginx → 本服务` | 1 | `TRUSTED_PROXY_HOPS=1` | -| `client → Cloudflare → nginx → 本服务` | 2 | `TRUSTED_PROXY_HOPS=2` | -| `client → CDN → WAF → nginx → 本服务` | 3 | `TRUSTED_PROXY_HOPS=3` | - -**行为对比**(以 `client(1.2.3.4) → CDN(203.0.113.5) → nginx(10.0.0.1) → 本服务` 为例,XFF 链 = `1.2.3.4, 203.0.113.5`): - -| `TRUSTED_PROXY_HOPS` | 返回 | 评价 | -|---|---|---| -| 0(默认启发式)| `203.0.113.5` | CDN 边缘 IP,限流粒度粗 | -| 1(数到 nginx,未穿透)| `203.0.113.5` | 配置不当,与默认相同 | -| 2(穿透到真实 client)| `1.2.3.4` | 精准到真实 client ✓ | -| 3(超出实际跳数)| `directIP`(链长不足保护)| 配置错误,需修正 | - -#### 为什么两种模式都从链尾扫描 - -XFF 链的第一个值是**客户端可控**的:攻击者可以发送任意 `X-Forwarded-For: 1.2.3.4`,若反代用追加模式(如 nginx 默认的 `$proxy_add_x_forwarded_for`),链尾才会追加真实 IP。 - -若代码取首值,攻击者每次换伪造 IP 即可绕过 IP 限流,也可伪装成受害 IP 把其配额耗尽(间接 DoS)。两种模式都从链尾扫描,天然免疫这种攻击。 - -#### 验证当前模式 - -启动期日志会显示当前模式: - -``` -TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP) -# 或 -已配置 TRUSTED_PROXY_HOPS=0(启发式模式,等同默认) -# 或 -已配置 TRUSTED_PROXY_HOPS=2(精确模式,信任 2 跳反代) -``` - -也可在 `GetClientIP` 临时加 `log.Printf` 打印解析结果,或写一个 Go 测试用例(参见 DEBT-1 单元测试任务)来覆盖不同 XFF 链场景。生产环境不要保留 debug 日志。 - -### 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 字符版 | - -> 上表为通用模型名。火山控制台实际显示的资源 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 错误。 - -## 调试日志 - -### BYTEDANCE_TTS_DEBUG - -服务运行期日志分为**始终输出**和**调试模式才输出**两类。通过 `BYTEDANCE_TTS_DEBUG` 环境变量控制调试日志开关。 - -| 值 | 行为 | -|----|------| -| 不设置 / `false` | 仅输出错误、警告、启动摘要、成功日志(默认,生产环境推荐) | -| `true` | 额外输出适配器层调试日志 | +### 3. 调用 ```bash -# 启用调试 -BYTEDANCE_TTS_DEBUG=true ./tts-api - -# 或写入 .env -echo "BYTEDANCE_TTS_DEBUG=true" >> .env +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 ``` -启用后启动时会打印: +## 环境变量 -``` -调试日志已启用 BYTEDANCE_TTS_DEBUG -``` +**只需 4 个启动引导变量**(安装前 / DB 还不存在时必需): -### 始终输出的日志 +| 变量 | 必设 | 用途 | +|---|---|---| +| `TTS_ADMIN_KEY` | ✓ (生产) | `/api/setup` 安装 token,首次安装时校验 | +| `TTS_DB_PATH` | ✗ | DB 路径,默认 `./tts.db` | +| `PORT` | ✗ | 监听端口,默认 `8080` | +| `OPENAI_TTS_API_KEY` | ✗ (生产) | OpenAI 端鉴权 key,可不设(内网) | -启动摘要、错误警告、合成成功/失败、访问日志(Logger 中间件): +**所有业务配置**(`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` / `trusted_proxy_hops`) — 全部在 `/admin` 设置,持久化到 SQLite。 -``` -[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 -``` +env 仍可作为 fallback 读(老用户兼容),但**新用户应通过 WebUI 配**。 -### 调试模式才输出的日志(`BYTEDANCE_TTS_DEBUG=true`) +## WebUI 使用 -适配器层与 CORS 拦截详情: +### `/setup` 首次安装 -``` -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 客户端=... -``` +四步表单: +1. **凭证**: 火山 API Key (必填) + OpenAI 鉴权 Key (可选) +2. **默认路由**: 默认资源 ID (`seed-icl-2.0`) + 默认音色名 + 默认格式 + 采样率 +3. **音色列表**: 每个 voice 一行,填对外名 + 火山 speaker ID +4. **确认**: 提交写入 DB,自动跳 `/admin` -> **生产建议:** 默认不开 `BYTEDANCE_TTS_DEBUG`,需要排查问题时再临时开启,避免 sentence 级别日志刷屏。 +### `/admin` 日常管理 -## CORS 跨域配置 +| Tab | 用途 | +|---|---| +| 仪表盘 | 进程状态 / 内存 / 启动时长 / 配置检查 | +| 音色管理 | CRUD 音色: 名称 / speaker / 资源 ID / 模型 / 语言 / 启用 / 描述 | +| 设置 | 全局设置: API Key / 默认资源 ID / 默认音色 / 格式 / 采样率 / 子模型 / 鉴权 key | +| CORS | 白名单 (逗号分隔) 或 `*` 模式 | +| 退出 | 清除 session | -跨域请求由 `ALLOWED_ORIGINS` 控制,按**完整 origin**(协议 + 域名 + 端口)精确匹配: +修改设置后**自动 reload**,不需重启服务。 -- `https://app.example.com` — 精确匹配一个来源 -- `https://a.com,https://b.com` — 多个来源逗号分隔 -- `*` — 允许所有来源(**不可与凭据请求共存**) -- `app.example.com` — 缺协议头,**永远不会匹配**(强制校验 `http://` / `https://` 开头) +### 客户端可见错误 -**典型坑:** +| 场景 | 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... | -1. 客户端是 `http://` 但服务端是 `https://`:浏览器按 `http://...` 的 origin 发请求,白名单里的 `https://...` 不会匹配 → 403。**客户端必须用 `https://` 开头**。 -2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`:浏览器按规范**直接拒绝预检**(凭据 + 通配符冲突),POST 根本发不出去。 -3. 同源请求不受 CORS 限制。 +## API 端点 -## API 使用说明 +### `POST /v1/audio/speech` -> ⚠️ **公网部署前必读**:如果你的服务暴露在公网,**必须**设置 `OPENAI_TTS_API_KEY` 或由前置反代(nginx / caddy)承担鉴权。未设置时 `Authorization` 头完全跳过校验,任何能访问 `:8080` 的人都能调用 TTS 合成,消耗你的火山额度。详见[部署 → 公网安全清单](#公网部署安全清单)。 +OpenAI 兼容,鉴权 `Authorization: Bearer `(若已设)。 -### OpenAI 兼容接口 - -**端点:** `POST /v1/audio/speech` - -**请求头:** -- `Content-Type: application/json` -- `Authorization: Bearer <你的API密钥>`(如果配置了 `OPENAI_TTS_API_KEY`) - -**请求体:** +请求体: ```json { - "model": "tts-1", - "input": "你好,这是一个测试文本", - "voice": "alloy", - "response_format": "mp3", - "speed": 1.0 + "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 生效 } ``` -**参数说明:** -- `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;**火山实际生效范围 0.5 ~ 2.0**(speech_rate [-50, 100]),超出范围会被静默截断,客户端无感反馈 +格式映射: -**格式映射:** +| 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` | -| OpenAI response_format | 火山 API 格式 | 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 /health` -**调用示例:** +无鉴权,返回: -```bash -# 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}' \ - -o output.mp3 - -# 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"}' \ - -o output.wav +```json +{ + "status": "ok", // ok | not_installed | configuration_error + "service": "ByteDance TTS to OpenAI API Adapter", + "version": "v0.2.0", + "commit": "621f9f8", + "uptime": "3600 seconds", + "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` 字段有原因 -```bash -curl http://localhost:8080/health -``` +### `GET /metrics` -返回服务状态、版本、运行时长、内存、配置检查结果(**不鉴权**)。 +Prometheus 文本格式,无鉴权。主要指标见 [观测 / Metrics](#观测--metrics)。 -## 限流机制 +### `GET /admin`, `GET /setup`, `GET /dashboard` -为保护上游火山 API,服务实现两层限流: +- `/admin`: 后台 (Vue SPA),需鉴权 +- `/setup`: 引导式安装页 (Vue SPA),无鉴权,装完自动跳转 +- `/dashboard`: 服务状态预览页 (无鉴权) -### 全局并发限制 -- 最多同时处理 **10 个** TTS 请求 -- 超过返回 `503 Service Unavailable` +## 老用户迁移 (从 v0.1.0 → v0.2.0) -### IP 速率限制 -- 每个 IP 每分钟 **100 个** 请求 -- 超过返回 `429 Too Many Requests` +v0.1.0 用 env 配 11 个 `BYTEDANCE_TTS_*` 变量。v0.2.0 起改 WebUI: -**触发日志(始终输出):** +| 旧 env | v0.2.0 配置入口 | +|---|---| +| `BYTEDANCE_TTS_API_KEY` | `/admin` 设置 → API Key | +| `BYTEDANCE_TTS_RESOURCE_ID` | `/admin` 设置 → 默认资源 ID | +| `BYTEDANCE_TTS_SPEAKER` | `/admin` 设置 → 默认音色 (填 voice **名字**,不是 speaker ID) | +| `BYTEDANCE_TTS_FORMAT` | `/admin` 设置 → 默认格式 | +| `BYTEDANCE_TTS_SAMPLE_RATE` | `/admin` 设置 → 采样率 | +| `BYTEDANCE_TTS_BIT_RATE` | `/admin` 设置 → MP3 比特率 | +| `BYTEDANCE_TTS_MODEL` | `/admin` 设置 → 子模型 | +| `BYTEDANCE_TTS_MODEL_TYPE` | `/admin` 设置 → 模型类型 | +| `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` | `/admin` 设置 → 显式语言 | +| `BYTEDANCE_TTS_ENABLE_SUBTITLE` | `/admin` 设置 → 启用字级时间戳 | +| `BYTEDANCE_TTS_TIMEOUT` | (保留 env 暂未搬 DB) | +| `ALLOWED_ORIGINS` | `/admin` → CORS → 跨域白名单 | +| `OPENAI_TTS_API_KEY` | `/admin` 设置 → OpenAI 端鉴权 key | -``` -警告: 已达到最大并发请求数限制,拒绝请求 - 客户端IP: 1.2.3.4 -警告: 已超过IP速率限制,拒绝请求 - 客户端IP: 1.2.3.4 -``` +**逐步迁移建议**: + +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 文本格式的 `/metrics` 端点,**不鉴权**(与 `/health` 一致),可直接被 Prometheus 抓取或浏览器查看。Go 进程内埋点,零外部依赖,实现位于 `telemetry/` 与 `metrics/` 包。 +Prometheus 文本格式,无鉴权。可直接被 Prometheus 抓取或浏览器查看。 -### 主要指标 +主要指标: -| 指标名 | 类型 | 标签 | 说明 | +| 指标 | 类型 | 标签 | 说明 | |---|---|---|---| | `tts_request_total` | counter | status, format, speaker, model | /v1/audio/speech 请求数 | | `tts_request_duration_seconds` | histogram | status, format | 端到端延迟 | @@ -340,195 +215,136 @@ curl http://localhost:8080/health | `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 | 上游错误(code 聚合到 transport/client/server/upstream) | +| `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 启动配置加载失败数 (告警用) | -### Prometheus 抓取示例 +**注意**: `speaker` 标签是 `sha1(speaker)[:8]` 哈希值,不是明文,保护火山复刻音色 ID 隐私。 + +### 告警示例 ```yaml -scrape_configs: - - job_name: tts-api - static_configs: - - targets: ['localhost:8080'] +- 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 ``` -### 仪表盘 +## 公网部署安全清单 -`/dashboard` 展示服务状态 + 内存 + 配置信息,并内嵌 `/metrics` 预览;Grafana 等工具可直接基于上面指标做面板。 +公网直接暴露 (`:8080` 可被互联网任意访问) 时,**至少满足以下两条之一**: -### ⚠️ 公网部署:监控端点无鉴权 +1. **设置 `OPENAI_TTS_API_KEY`** (推荐, 最简单) + ```bash + OPENAI_TTS_API_KEY=<32+ 位随机字符串> + ``` + 客户端请求时带 `Authorization: Bearer <那个字符串>`。 -`/metrics`、`/health`、`/dashboard` **均不鉴权**,这是对齐 Prometheus 抓取场景的设计权衡: +2. **前置反代承担鉴权** (nginx / caddy / Cloudflare Access) + - 反代层做 basic auth / mTLS / Cloudflare Access 等任一方案 + - 反代**仅**把鉴权后的请求转发到 `:8080` + - 此时 `OPENAI_TTS_API_KEY` 可不设 -| 端点 | 暴露内容 | 风险 | -|---|---|---| -| `/metrics` | 业务标签(speaker/model/format)、运行指标、错误计数 | 侦察面:可推断使用量、技术栈、错误模式 | -| `/health` | 服务状态、版本号、运行时长、内存 | 侦察面:版本号可用于匹配已知 CVE | -| `/dashboard` | 配置检查结果(含 `TTSConfigErr` 状态) | 信息泄露:可确认配置是否就绪 | +**`/metrics` / `/dashboard` / `/health` 均不鉴权**,生产环境务必通过反代保护: -**部署建议**: +```nginx +location /metrics { allow 10.0.0.0/8; deny all; } # 仅 Prometheus 服务器 +location /dashboard { auth_basic "admin"; auth_basic_user_file /etc/nginx/.htpasswd; } +location /health { allow 10.0.0.0/8; deny all; } # 或 K8s liveness probe 直接访问 +``` -- **内网 / 反代后**:无影响,符合预期 -- **公网直接暴露**:在前置反代(nginx / caddy)上保护这些端点,示例 nginx 配置: +## 部署 - ```nginx - location /metrics { - auth_basic "metrics"; - auth_basic_user_file /etc/nginx/.htpasswd; - allow 10.0.0.0/8; # 仅允许 Prometheus 服务器网段 - deny all; - } - location /dashboard { - auth_basic "admin"; - auth_basic_user_file /etc/nginx/.htpasswd; - } - location /health { - allow 10.0.0.0/8; # 或保留给监控系统访问 - deny all; - } - ``` +### Docker -- **最简方案**:反代层直接限制 `/metrics` 只能从 Prometheus 服务器 IP 访问,无需 basic auth +```bash +# .env 至少含 TTS_ADMIN_KEY, 公网再加 OPENAI_TTS_API_KEY +docker compose up -d +``` + +`docker-compose.yml` 已配 named volume `tts-api-data` 挂载到容器 `/data`,DB 与 lock 文件持久化,容器重启不丢配置。 + +### Linux Systemd + +参见 `v0.1.0 README`,**注意**:v0.2.0 启动前不需要 `EnvironmentFile` 含业务变量,只保留 `TTS_ADMIN_KEY`。 ## 架构 | 包 | 职责 | |---|---| -| `main.go` | 启动入口,信号处理 | -| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出(零依赖) | -| `metrics/` | TTS 业务指标注册,火山适配器埋点适配 | -| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端(client/request/response/audio/errors/synthesis) | -| `controller/` | /v1/audio/speech、/health 处理器 | -| `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 | -| `setting/` | 单一环境变量入口 + 启动汇总 | -| `common/`、`dto/` | 常量、请求/响应类型,`common.DebugLog` 控制调试日志 | +| `main.go` | 启动入口,模式检测 (setup/normal),fail-fast | +| `installer/` | 启动期模式检测,DB 自愈回退 | +| `setting/` | 全局配置 (TTSOptions / Auth / CORS) + 启动汇总 | +| `store/` | SQLite 数据访问 (settings / voices) + 自愈 | +| `controller/` | /v1/audio/speech、/health、/setup、/admin、/api/setup、/api/settings、/api/voices | +| `middleware/` | SecurityHeaders, CORS, 鉴权, 限流, 并发, 日志, 客户端 IP 提取, install 模式守卫 | | `router/` | 路由注册 | - -## 部署 - -### Linux Systemd - -创建 `/etc/systemd/system/tts-server.service`: - -```ini -[Unit] -Description=ByteDance TTS to OpenAI API Adapter -After=network.target - -[Service] -Type=simple -User=www-data -WorkingDirectory=/www/wwwroot/tts-server -EnvironmentFile=/www/wwwroot/tts-server/.env -ExecStart=/www/wwwroot/tts-server/tts-api -Restart=always -RestartSec=10 - -[Install] -WantedBy=multi-user.target -``` - -```bash -sudo systemctl daemon-reload -sudo systemctl enable tts-server -sudo systemctl start tts-server -``` - -### Docker - -```bash -docker compose up -d -``` - -环境变量通过 `.env` 或 `docker-compose.yml` 传入。 - -### 公网部署安全清单 - -公网直接暴露(`:8080` 可被互联网任意访问)时,**至少满足以下两条之一**,否则视为不安全的部署: - -1. **设置 `OPENAI_TTS_API_KEY`**(推荐,最简单) - ```bash - # .env - OPENAI_TTS_API_KEY=<32+ 位随机字符串> - ``` - 客户端请求时带 `Authorization: Bearer <那个字符串>`。 - -2. **前置反代承担鉴权**(nginx / caddy / Cloudflare Access) - - 反代层做 basic auth、mTLS、Cloudflare Access 等任一方案 - - 反代**仅**把鉴权后的请求转发到 `:8080`,Go 服务本身保持"无鉴权" - - 此时 `OPENAI_TTS_API_KEY` 可不设 - -**两个端点还需要单独保护**(无论上面哪种方案): - -- `/metrics`:暴露业务标签与运行指标,详见[观测 / Metrics → 公网部署](#公网部署监控端点无鉴权) -- `/dashboard`:暴露配置检查结果,同上 - -**未做保护的典型风险**: -- 任意人 curl `POST /v1/audio/speech` → 消耗你火山账号的字符额度 -- 任意人 `GET /metrics` → 推断你的使用量、技术栈、错误模式 -- 任意人 `GET /dashboard` → 确认你 TTS 配置就绪状态 - -**内网部署 / 私网反代后**:这些警示不适用,直接用就行。 +| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端 | +| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出 | +| `metrics/` | TTS 业务指标注册 | +| `cmd/dumpdb/` | ops 工具: dump tts.db | +| `dto/` | 请求/响应类型 | +| `common/` | 常量 + 调试日志 | ## 常见问题 -### 1. `code=55000000, message=resource ID is mismatched with speaker related resource` +### 1. `code=55000000 resource ID is mismatched` -资源/音色不匹配。修复: - -1. 火山控制台 → 语音技术 → 你的应用 → 资源管理或音色库 +资源 / 音色不匹配。修复: +1. 火山控制台 → 语音技术 → 你的应用 → 资源管理 2. 用控制台在线体验/调试同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色 3. 控制台能合成的组合才是正确的 -4. 把控制台实际显示的资源 ID 字符串(通常是 `volc.megatts.*` 格式)填到 `BYTEDANCE_TTS_RESOURCE_ID` -5. 复刻音色(speaker 以 `S_` 开头)需确认 Resource ID 已开通且与音色同族 +4. v3 API 复刻 2.0 用 `seed-icl-2.0`, **不要填 `volc.megatts.icl`** +5. 复刻音色 (speaker `S_` 开头) 需确认 Resource ID 已开通 -### 2. PowerShell 下 `curl` 解释错 +### 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 -v -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" --data-binary "@body.json" +curl.exe -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 ``` +或 `.env` 里改 `PORT=8081`。 + ## 技术支持 如有问题,请检查: - -1. 环境变量配置是否正确 -2. 网络是否能访问火山引擎 TTS 服务 -3. 鉴权信息是否有效 -4. Resource ID 与 Speaker 是否匹配 -5. `ALLOWED_ORIGINS` 是否包含前端完整 origin(含 https://) -6. 客户端请求 URL 是否以 https:// 开头 -7. 生产环境凭据是否定期轮换 -8. 复刻音色确保 Resource ID 与音色 ID 同族 -9. 音频格式是否匹配客户端解码能力(默认 mp3 兼容性最好) +1. 服务启动后日志第一段 "环境配置汇总" — 火山必填项是否全 ✓ +2. `/health` 返回 `status: "ok"` 且 `config_error: false` +3. `/admin` → 设置 tab 检查 API Key / 默认资源 ID / 默认音色 +4. `/admin` → 音色管理 tab 检查 voice 是否启用 +5. 火山控制台 → 在线体验同一对 resource + speaker 能合成 +6. 客户端请求 URL 是否以 https:// 开头 (公网) +7. `/admin` → CORS tab 检查白名单含前端完整 origin ## 许可证 diff --git a/VULNERABILITY_REPORT.md b/VULNERABILITY_REPORT.md deleted file mode 100644 index ff232fb..0000000 --- a/VULNERABILITY_REPORT.md +++ /dev/null @@ -1,197 +0,0 @@ -# 漏洞报告 — Volcano-Engine-TTS-UI - -## 元信息 - -| 项目 | 内容 | -|---|---| -| 目标 | ByteDance TTS v3 → OpenAI 兼容接口适配器(Go) | -| 审查范围 | 全部 12 个包、约 2400 行源码(不含 health.html 前端静态页) | -| 审查方式 | 人工代码审查 + `go build` / `go vet`(均通过) | -| 分支/提交 | develop @ 78c7200 | -| 报告日期 | 2026 年 8 月 25 日 | -| 严重度分级 | 🔴 高(必须修复)/ 🟠 中(建议修复)/ 🟡 低(视部署环境)/ ⚪ 信息(记录备查) | - ---- - -## 漏洞清单(按严重度) - -| 编号 | 严重度 | 标题 | 位置 | 一句话影响 | -|---|---|---|---|---| -| VUL-004 | 🔴 高 | `.env` 未被 `.gitignore` 忽略,凭据可能入库/入镜像 | `.gitignore` | API Key 随 git 提交或 Docker 镜像层泄露 | -| VUL-001 | 🟠 中 | aac/flac 响应 Content-Type 与数据不一致 | controller/tts.go、adapter/volcano/synthesis.go | 客户端按 AAC 解码 MP3 数据,播放失败 | -| VUL-003 | 🟠 中 | `X-Forwarded-For` 信任链可伪造 IP 绕过限流 | middleware/ratelimit.go | 反代追加模式下限流失效 | -| VUL-002 | 🟡 低 | transport 层错误不进入 `UpstreamErrors` 指标 | metrics/metrics.go、adapter/volcano/synthesis.go | 网络故障在监控上不可见 | -| VUL-005 | 🟡 低 | 日志注入:客户端可控内容原样写入日志 | middleware/logger.go、controller/tts.go | 可伪造日志行 | -| VUL-006 | 🟡 低 | `/metrics`、`/health`、`/dashboard` 无鉴权 | router/router.go | 公网暴露时泄漏运行细节(设计权衡) | -| VUL-007 | 🟡 低 | `OPENAI_TTS_API_KEY` 未设置时鉴权完全关闭 | middleware/auth.go | 公网直连即无访问控制(设计权衡) | -| VUL-008 | ⚪ 信息 | speed 超范围静默截断 | adapter/volcano/request.go | 0.25~0.5x、2.0~4.0x 实际被 clamp,无提示 | -| VUL-009 | ⚪ 信息 | WAV 输出采样率依赖配置而非上游实际值 | adapter/volcano/audio.go | 配置错误导致音频变速 | - ---- - -## VUL-004 🔴 高 — `.env` 未被忽略,凭据可能入库/入镜像 - -**位置**: `.gitignore`(全文件仅忽略构建产物与编辑器文件) - -**描述**: README 与 `.env.example` 均指导用户执行 `cp .env.example .env` 后填入火山 API Key。但 `.gitignore` **没有包含 `.env`**。任何按此流程操作并执行 `git add .` / `git commit` 的用户,都会把含 `BYTEDANCE_TTS_API_KEY`、`OPENAI_TTS_API_KEY` 的文件提交进仓库历史(即使之后删除,历史中仍可找回)。Dockerfile 第 8 行 `COPY . .` 同样会把 `.env` 拷入镜像层。 - -**影响**: 火山账号 API Key 泄露 → 冒用额度、产生费用、音色资源被盗用。密钥一旦进入 git 历史或镜像层即视为已泄露,只能吊销重建。 - -**修复建议**: -```gitignore -# Secrets -.env -.env.* -!.env.example -``` - -**验证**: 当前工作区无 `.env` 文件,仓库历史也未发现已提交的 `.env`(已核查 `git log` 提交列表无该文件),属"配置隐患"而非"已泄露"。 - ---- - -## VUL-001 🟠 中 — aac/flac 响应 Content-Type 与真实数据不一致 - -**位置**: controller/tts.go:196-212(`contentTypeFor`)、adapter/volcano/synthesis.go:59-63、118-119 - -**描述**: 客户端请求 `response_format: "aac"`(或 `flac`)时,调用链为: - -``` -resolveClientFormat("aac") → "aac"(白名单放行) -synthesis: opts.Format = "mp3"(上游降级,正确) -synthesis: finalFormat = clientFormat = "aac"(错误,保留客户端格式) -controller: Content-Type = contentTypeFor("aac") = "audio/aac"(错误) -``` - -实际响应字节是 **MP3**,但 `Content-Type` 是 `audio/aac`。 - -**影响**: 客户端(浏览器 `