Merge branch 'develop'

README 旧版 (~535 行) 仍以 BYTEDANCE_TTS_* env 为主线, 与 v0.2.0 实际架构脱节。
M3 起业务配置已全部入 DB, env 只剩 4 个引导变量。

新版 README (重写, ~300 行) 调整:

结构重排:
  - 快速开始: 编译 → 启动 → 浏览器 /setup 引导(默认 4 步)→ 调用
  - 环境变量: 4 个引导 env + DB 业务配置对照表
  - WebUI 使用: /setup 4 步说明 + /admin 5 个 tab + 客户端可见错误码表
  - API 端点: /v1/audio/speech + /health + /metrics + /admin + /setup + /dashboard
  - 老用户迁移: 11 个 BYTEDANCE_TTS_* 旧 env 逐项映射到 /admin 设置
  - 资源 ID 章节: 重要! 强调 v3 API 只允许 2 个 ID, volc.megatts.* 是 1.0 不是 2.0
  - 观测 / Metrics: 14 个指标, 告警示例 (tts_config_load_failures_total)
  - 公网部署: 鉴权清单 + /metrics /dashboard 反代保护
  - 部署: Docker / Systemd
  - 架构: 13 个包
  - FAQ: 9 条
  - 技术支持 checklist

内容更新:
  - 删 BYTEDANCE_TTS_* 详细配置章节(老的 11 个变量, 全搬 DB 了)
  - 加 "v0.2.0 老用户迁移" 完整映射表
  - 资源 ID 章节纠正 1.0 vs 2.0 区别
  - /health body 改用 v0.2.0 真实 schema (含 error 字段)
  - 错误码表加 400/403/503 客户端可见错误
  - 模型名更正: 复刻 2.0 子模型 = seed-tts-2.0-standard (和资源 ID 不同)
  - 强调 4 个 bootstrap env + DB 业务配置分工

未提交 (待 M4 全部完成)

.env.example

@@ -1,69 +1,33 @@
-# 字节火山引擎 TTS v3 API 配置示例
+# 字节火山引擎 TTS v3 → OpenAI 兼容接口
-# 将此文件复制为 .env 并填入实际配置
+# 配置文件示例 · 复制为 .env 后填入
 
 # ==========================================
-# 必需的环境变量
+# 启动引导环境变量(4 个,启动前必看)
 # ==========================================
+# 业务配置(api_key / resource_id / speaker / 格式 / 采样率 ...)通过 WebUI 设置,
+# 不再需要在这里配。M3 起所有 BYTEDANCE_TTS_* 已搬入数据库。
 
-# 火山引擎新版控制台获取的 API Key
+# 1. 安装 token(必设,首次 /setup 时校验)
-BYTEDANCE_TTS_API_KEY=your_api_key_here
+#    留空 = 不设 token,任何人可调 /api/setup(适合本地开发)
+#    正式部署务必设复杂字符串
+TTS_ADMIN_KEY=
 
-# 资源信息ID(决定使用1.0还是2.0模型)
+# 2. 数据库路径(可选, 默认 ./tts.db)
-# 复刻 2.0 音色(seed-icl-2.0)
+#    Docker 部署务必改成挂载路径,例: /data/tts.db
-BYTEDANCE_TTS_RESOURCE_ID=seed-icl-2.0
+# TTS_DB_PATH=/data/tts.db
 
-# 发音人(音色)ID
+# 3. 服务监听端口(可选, 默认 8080)
-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
 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

.gitignore

@@ -27,8 +27,20 @@ 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/

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=<name>` 动态路由, 命中但 enabled=0 返回 403
+  - 未知 voice 返回 400 `unknown_voice: '<name>'`
+  - 禁用 voice 返回 403 `voice '<name>' 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 解析

Dockerfile

@@ -27,13 +27,16 @@ WORKDIR /app
 COPY --from=builder /app/tts-api .
 # 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"]

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
+- **引导式安装**: 首次启动自动进入 `/setup` 向导,无需手写 env
-- 支持多种音频格式:mp3 / ogg_opus / pcm / wav(wav 内部转 pcm 后本地拼头)
+- **WebUI 后台** `/admin`: 音色管理 / 全局设置 / CORS 配置 / 鉴权
-- 支持火山复刻 2.0 子模型(`seed-tts-2.0-standard` / `-expressive`)
+- **音色库**: 多 voice 动态路由,未知 / 禁用 voice 返回明确错误
-- API Key 鉴权、IP 速率限制、全局并发限制
+- **多格式输出**: mp3 / ogg_opus / pcm / wav (内部转 pcm + 本地拼头) / aac / flac
-- 内置 Prometheus 文本格式 `/metrics` 端点,零外部依赖
+- **鉴权 + 限流**: API Key 校验, IP 速率限制, 全局并发限制
-- 跨平台支持(Windows / Linux / macOS)
+- **观测**: Prometheus 文本格式 `/metrics` + 服务状态 `/health`, 零外部依赖
+- **跨平台**: Windows / Linux / macOS / Docker
 
 ## 快速开始
 
-### 前置要求
-
-- Go 1.26 或更高版本
-- 火山引擎账号并开通 TTS 服务
-
 ### 1. 编译
 
 ```bash
 go build -o tts-api .
 ```
 
-### 2. 配置环境变量
+### 2. 启动
-
-复制 `.env.example` 为 `.env` 并填入实际配置:
 
 ```bash
-cp .env.example .env
+# 默认: 端口 8080, 监听 localhost
-```
-
-### 3. 启动
-
-```bash
-# Windows
-tts-api.exe
-
-# Linux/macOS
 ./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`,从这里登录管理。
 
-| 变量名 | 说明 |
+### 3. 调用
-|--------|------|
-| `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` 打印解析结果,或参考已有的 `middleware/ratelimit_test.go`(24 个 XFF 表驱动用例)来扩展更多 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` | 额外输出适配器层调试日志 |
 
 ```bash
-# 启用调试
+curl -X POST http://localhost:8080/v1/audio/speech \
-BYTEDANCE_TTS_DEBUG=true ./tts-api
+  -H "Authorization: Bearer <装时设的 OpenAI key>" \
-
+  -H "Content-Type: application/json" \
-# 或写入 .env
+  -d '{"model":"tts-1","input":"你好,世界","voice":"chun"}' \
-echo "BYTEDANCE_TTS_DEBUG=true" >> .env
+  -o output.mp3
 ```
 
-启用后启动时会打印:
+## 环境变量
 
-```
+**只需 4 个启动引导变量**(安装前 / DB 还不存在时必需):
-调试日志已启用 BYTEDANCE_TTS_DEBUG
-```
 
-### 始终输出的日志
+| 变量 | 必设 | 用途 |
+|---|---|---|
+| `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。
 
-```
+env 仍可作为 fallback 读(老用户兼容),但**新用户应通过 WebUI 配**。
-[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`)
+## 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="..."
+1. **凭证**: 火山 API Key (必填) + OpenAI 鉴权 Key (可选)
-Sentence start: sequence=0, sentence=...
+2. **默认路由**: 默认资源 ID (`seed-icl-2.0`) + 默认音色名 + 默认格式 + 采样率
-Sentence end: sequence=0
+3. **音色列表**: 每个 voice 一行,填对外名 + 火山 speaker ID
-TTS 合成结束, usage: text_words=5
+4. **确认**: 提交写入 DB,自动跳 `/admin`
-volcano: 忽略未识别事件 event="xxx" sequence=1
-CORS拦截: 来源="https://..." 路径=/v1/audio/speech 方法=POST 客户端=...
-```
 
-> **生产建议:** 默认不开 `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://` 开头**。
+## API 端点
-2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`:浏览器按规范**直接拒绝预检**(凭据 + 通配符冲突),POST 根本发不出去。
-3. 同源请求不受 CORS 限制。
 
-## API 使用说明
+### `POST /v1/audio/speech`
 
-> ⚠️ **公网部署前必读**:如果你的服务暴露在公网,**必须**设置 `OPENAI_TTS_API_KEY` 或由前置反代(nginx / caddy)承担鉴权。未设置时 `Authorization` 头完全跳过校验,任何能访问 `:8080` 的人都能调用 TTS 合成,消耗你的火山额度。详见[部署 → 公网安全清单](#公网部署安全清单)。
+OpenAI 兼容,鉴权 `Authorization: Bearer <OPENAI_TTS_API_KEY>`(若已设)。
 
-### OpenAI 兼容接口
+请求体:
-
-**端点:** `POST /v1/audio/speech`
-
-**请求头:**
-- `Content-Type: application/json`
-- `Authorization: Bearer <你的API密钥>`(如果配置了 `OPENAI_TTS_API_KEY`)
-
-**请求体:**
 
 ```json
 {
-  "model": "tts-1",
+  "model": "tts-1",          // 兼容字段,实际不影响
-  "input": "你好,这是一个测试文本",
+  "input": "你好,世界",     // 必填,要合成的文本
-  "voice": "alloy",
+  "voice": "chun",           // 选填: 装时设的 voice 名称,留空走 default_speaker
-  "response_format": "mp3",
+  "response_format": "mp3",  // 选填: mp3 / opus / wav / pcm / aac / flac
-  "speed": 1.0
+  "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 |
+### `GET /health`
-|------------------------|--------------|--------------|
-| `mp3` | mp3 | audio/mpeg |
-| `opus` | ogg_opus | audio/ogg |
-| `wav` | pcm → 本地拼 wav header | audio/wav |
-| `pcm` | pcm | audio/pcm |
-| `aac` / `flac` | mp3(降级) | audio/mpeg |
 
-**调用示例:**
+无鉴权,返回:
 
-```bash
+```json
-# MP3
+{
-curl -X POST "http://localhost:8080/v1/audio/speech" \
+  "status": "ok",                            // ok | not_installed | configuration_error
-  -H "Content-Type: application/json" \
+  "service": "ByteDance TTS to OpenAI API Adapter",
-  -d '{"model":"tts-1","input":"你好,世界","voice":"alloy","speed":1.0}' \
+  "version": "v0.2.0",
-  -o output.mp3
+  "commit": "621f9f8",
-
+  "uptime": "3600 seconds",
-# WAV
+  "config_status": {
-curl -X POST "http://localhost:8080/v1/audio/speech" \
+    "all_required_vars_set": true,
-  -H "Content-Type: application/json" \
+    "config_error": false,
-  -d '{"model":"tts-1","input":"你好,世界","voice":"alloy","response_format":"wav"}' \
+    "error": "..."                           // 仅在 config_error=true 时出现
-  -o output.wav
+  },
+  "installed": true,
+  "mode": "normal"
+}
 ```
 
-### 健康检查
+- 正常: HTTP 200, `status: "ok"`
+- 未安装: HTTP 200, `status: "not_installed"`
+- 配置损坏: HTTP 503, `status: "configuration_error"`, `error` 字段有原因
 
-```bash
+### `GET /metrics`
-curl http://localhost:8080/health
-```
 
-返回服务状态、版本、运行时长、内存、配置检查结果(**不鉴权**)。
+Prometheus 文本格式,无鉴权。主要指标见 [观测 / Metrics](#观测--metrics)。
 
-## 限流机制
+### `GET /admin`, `GET /setup`, `GET /dashboard`
 
-为保护上游火山 API,服务实现两层限流:
+- `/admin`: 后台 (Vue SPA),需鉴权
+- `/setup`: 引导式安装页 (Vue SPA),无鉴权,装完自动跳转
+- `/dashboard`: 服务状态预览页 (无鉴权)
 
-### 全局并发限制
+## 老用户迁移 (从 v0.1.0 → v0.2.0)
-- 最多同时处理 **10 个** TTS 请求
-- 超过返回 `503 Service Unavailable`
 
-### IP 速率限制
+v0.1.0 用 env 配 11 个 `BYTEDANCE_TTS_*` 变量。v0.2.0 起改 WebUI:
-- 每个 IP 每分钟 **100 个** 请求
-- 超过返回 `429 Too Many Requests`
 
-**触发日志(始终输出):**
+| 旧 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:
+- alert: TTSConfigLoadFailure
-  - job_name: tts-api
+  expr: rate(tts_config_load_failures_total{mode="normal"}[5m]) > 0
-    static_configs:
+  for: 1m
-      - targets: ['localhost:8080']
+  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` / `/dashboard` / `/health` 均不鉴权**,生产环境务必通过反代保护:
-|---|---|---|
-| `/metrics` | 业务标签(speaker/model/format)、运行指标、错误计数 | 侦察面:可推断使用量、技术栈、错误模式 |
-| `/health` | 服务状态、版本号、运行时长、内存 | 侦察面:版本号可用于匹配已知 CVE |
-| `/dashboard` | 配置检查结果(含 `TTSConfigErr` 状态) | 信息泄露:可确认配置是否就绪 |
 
-**部署建议**:
+```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
+### Docker
-  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;
-  }
-  ```
 
-- **最简方案**:反代层直接限制 `/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` | 启动入口,信号处理 |
+| `main.go` | 启动入口,模式检测 (setup/normal),fail-fast |
-| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出(零依赖) |
+| `installer/` | 启动期模式检测,DB 自愈回退 |
-| `metrics/` | TTS 业务指标注册,火山适配器埋点适配 |
+| `setting/` | 全局配置 (TTSOptions / Auth / CORS) + 启动汇总 |
-| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端(client/request/response/audio/errors/synthesis) |
+| `store/` | SQLite 数据访问 (settings / voices) + 自愈 |
-| `controller/` | /v1/audio/speech、/health 处理器 |
+| `controller/` | /v1/audio/speech、/health、/setup、/admin、/api/setup、/api/settings、/api/voices |
-| `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 |
+| `middleware/` | SecurityHeaders, CORS, 鉴权, 限流, 并发, 日志, 客户端 IP 提取, install 模式守卫 |
-| `setting/` | 单一环境变量入口 + 启动汇总 |
-| `common/`、`dto/` | 常量、请求/响应类型,`common.DebugLog` 控制调试日志 |
 | `router/` | 路由注册 |
-
+| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端 |
-## 部署
+| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出 |
-
+| `metrics/` | TTS 业务指标注册 |
-### Linux Systemd
+| `cmd/dumpdb/` | ops 工具: dump tts.db |
-
+| `dto/` | 请求/响应类型 |
-创建 `/etc/systemd/system/tts-server.service`:
+| `common/` | 常量 + 调试日志 |
-
-```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 配置就绪状态
-
-**内网部署 / 私网反代后**:这些警示不适用,直接用就行。
 
 ## 常见问题
 
-### 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`
+4. v3 API 复刻 2.0 用 `seed-icl-2.0`, **不要填 `volc.megatts.icl`**
-5. 复刻音色(speaker 以 `S_` 开头)需确认 Resource ID 已开通且与音色同族
+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. 服务启动后日志第一段 "环境配置汇总" — 火山必填项是否全 ✓
-1. 环境变量配置是否正确
+2. `/health` 返回 `status: "ok"` 且 `config_error: false`
-2. 网络是否能访问火山引擎 TTS 服务
+3. `/admin` → 设置 tab 检查 API Key / 默认资源 ID / 默认音色
-3. 鉴权信息是否有效
+4. `/admin` → 音色管理 tab 检查 voice 是否启用
-4. Resource ID 与 Speaker 是否匹配
+5. 火山控制台 → 在线体验同一对 resource + speaker 能合成
-5. `ALLOWED_ORIGINS` 是否包含前端完整 origin(含 https://)
+6. 客户端请求 URL 是否以 https:// 开头 (公网)
-6. 客户端请求 URL 是否以 https:// 开头
+7. `/admin` → CORS tab 检查白名单含前端完整 origin
-7. 生产环境凭据是否定期轮换
-8. 复刻音色确保 Resource ID 与音色 ID 同族
-9. 音频格式是否匹配客户端解码能力(默认 mp3 兼容性最好)
 
 ## 许可证
 

cmd/dumpdb/main.go

@@ -0,0 +1,130 @@
+// dumpdb 是个 ops 工具: dump tts.db 里的 settings + voices 表(明文打码)。
+//
+// 用法:
+//   go run ./cmd/dumpdb /path/to/tts.db
+//
+// 输出 schema_version / settings(键值,敏感字段打码) / voices(完整行)。
+// 调试时方便:不依赖 sqlite3 CLI,不暴露明文 key/speaker ID。
+package main
+
+import (
+	"database/sql"
+	"fmt"
+	"os"
+
+	_ "modernc.org/sqlite"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Fprintf(os.Stderr, "usage: %s <db-path>\n", os.Args[0])
+		os.Exit(1)
+	}
+	dbPath := os.Args[1]
+
+	dsn := "file:" + dbPath + "?mode=ro&_pragma=query_only"
+	conn, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "open: %v\n", err)
+		os.Exit(2)
+	}
+	defer conn.Close()
+
+	// 1. tables
+	fmt.Println("=== Tables ===")
+	rows, _ := conn.Query("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+	for rows.Next() {
+		var name string
+		_ = rows.Scan(&name)
+		fmt.Printf("  %s\n", name)
+	}
+	rows.Close()
+
+	// 2. schema_version
+	fmt.Println("\n=== schema_version ===")
+	var ver int
+	var ts string
+	err = conn.QueryRow(`SELECT version, applied_at FROM schema_version LIMIT 1`).Scan(&ver, &ts)
+	if err != nil {
+		fmt.Printf("  (no row: %v)\n", err)
+	} else {
+		fmt.Printf("  version: %d, applied_at: %s\n", ver, ts)
+	}
+
+	// 3. settings
+	fmt.Println("\n=== settings ===")
+	rows, err = conn.Query(`SELECT key, value FROM settings ORDER BY key`)
+	if err != nil {
+		fmt.Printf("  err: %v\n", err)
+	} else {
+		for rows.Next() {
+			var k, v string
+			_ = rows.Scan(&k, &v)
+			if v == "" {
+				fmt.Printf("  %-30s = (empty)\n", k)
+				continue
+			}
+			lowK := k
+			_ = lowK
+			masked := v
+			if isSensitive(k) {
+				if len(v) <= 8 {
+					masked = "****"
+				} else {
+					masked = v[:4] + "****" + v[len(v)-4:]
+				}
+			}
+			fmt.Printf("  %-30s = %s\n", k, masked)
+		}
+		rows.Close()
+	}
+
+	// 4. voices
+	fmt.Println("\n=== voices ===")
+	rows, err = conn.Query(`SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at FROM voices ORDER BY id`)
+	if err != nil {
+		fmt.Printf("  err: %v\n", err)
+	} else {
+		count := 0
+		for rows.Next() {
+			count++
+			var id int64
+			var name, speaker, resourceID, model, lang, desc, created, updated string
+			var enabled int
+			_ = rows.Scan(&id, &name, &speaker, &resourceID, &model, &lang, &desc, &enabled, &created, &updated)
+			en := "true"
+			if enabled == 0 {
+				en = "false"
+			}
+			fmt.Printf("  [%d] name=%s\n      speaker=%s\n      resource_id=%s\n      model=%s\n      lang=%s enabled=%s\n      created=%s updated=%s\n",
+				id, name, speaker, resourceID, model, lang, en, created, updated)
+			if desc != "" {
+				fmt.Printf("      desc: %s\n", desc)
+			}
+		}
+		fmt.Printf("  total: %d\n", count)
+		rows.Close()
+	}
+
+	// 5. pragmas
+	fmt.Println("\n=== Pragmas ===")
+	for _, p := range []string{"journal_mode", "synchronous", "foreign_keys", "page_size", "page_count"} {
+		var v string
+		_ = conn.QueryRow("PRAGMA " + p).Scan(&v)
+		fmt.Printf("  %-15s = %s\n", p, v)
+	}
+}
+
+func isSensitive(key string) bool {
+	lowK := key
+	// 简单 contains (不引 strings 包保持精简)
+	markers := []string{"key", "token", "speaker"}
+	for _, m := range markers {
+		for i := 0; i+len(m) <= len(lowK); i++ {
+			if lowK[i:i+len(m)] == m {
+				return true
+			}
+		}
+	}
+	return false
+}

controller/settings.go

@@ -0,0 +1,432 @@
+package controller
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/volcano-tts/tts-api/middleware"
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+// SettingsResponse 是 GET /api/settings 的响应。
+// API key 永远打码(借用 setting.maskAPIKey 风格,前 4 后 4 中间 ****)。
+type SettingsResponse struct {
+	APIKey           string `json:"api_key"`           // 打码形式,例如 S_G8****naJ1
+	APIKeySet        bool   `json:"api_key_set"`       // 是否已设置(用于前端判断要不要提示必填)
+	AuthKey          string `json:"auth_key"`          // 鉴权 key 打码(客户端访问 + admin 登录用)
+	AuthKeySet       bool   `json:"auth_key_set"`
+	CORSAllowAll     bool   `json:"cors_allow_all"`    // 允许所有来源(*)
+	CORSOrigins      string `json:"cors_origins"`      // 逗号分隔的白名单(原文,含大小写,trim 末尾 /)
+	CORSConfigured   bool   `json:"cors_configured"`   // 是否配了 CORS(给 banner 用)
+	DefaultResourceID string `json:"default_resource_id"`
+	DefaultSpeaker   string `json:"default_speaker"`
+	DefaultFormat    string `json:"default_format"`
+	SampleRate       int    `json:"sample_rate"`
+	Model            string `json:"model"`
+	ModelType        int    `json:"model_type"`
+	ExplicitLanguage string `json:"explicit_language"`
+	EnableSubtitle   bool   `json:"enable_subtitle"`
+	UpdatedAt        string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
+}
+
+// SettingsGetHandler GET /api/settings
+// 鉴权: RequireAdmin;store nil 时 503。
+func SettingsGetHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+	all, err := s.SettingsGetAll()
+	if err != nil {
+		log.Printf("[settings] getall: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "read settings failed", "server_error", "db_read_failed")
+		return
+	}
+
+	resp := SettingsResponse{
+		APIKey:            maskAPIKeyField(all["api_key"]),
+		APIKeySet:         all["api_key"] != "",
+		AuthKey:           maskAPIKeyField(all["auth_key"]),
+		AuthKeySet:        all["auth_key"] != "",
+		CORSAllowAll:      all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true",
+		CORSOrigins:       all["cors_origins"],
+		CORSConfigured:    all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true" || all["cors_origins"] != "",
+		DefaultResourceID: all["default_resource_id"],
+		DefaultSpeaker:    all["default_speaker"],
+		DefaultFormat:     all["default_format"],
+		Model:             all["model"],
+		ExplicitLanguage:  all["explicit_language"],
+	}
+	if v, _ := s.SettingsGetInt("sample_rate", 0); v > 0 {
+		resp.SampleRate = v
+	}
+	if v, _ := s.SettingsGetInt("model_type", 0); v > 0 {
+		resp.ModelType = v
+	}
+	if v, _ := s.SettingsGetBool("enable_subtitle", false); v {
+		resp.EnableSubtitle = true
+	}
+	if ts := all["installed_at"]; ts != "" {
+		resp.UpdatedAt = ts
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+// SettingsUpdateRequest 是 PUT /api/settings 的 body(部分更新)。
+// 字段都是可选;只更新非空 / 非零值。
+type SettingsUpdateRequest struct {
+	APIKey            *string `json:"api_key,omitempty"` // 用指针区分 "未传" vs "传空串"
+	DefaultResourceID *string `json:"default_resource_id,omitempty"`
+	DefaultSpeaker    *string `json:"default_speaker,omitempty"`
+	DefaultFormat     *string `json:"default_format,omitempty"`
+	SampleRate        *int    `json:"sample_rate,omitempty"`
+	Model             *string `json:"model,omitempty"`
+	ModelType         *int    `json:"model_type,omitempty"`
+	ExplicitLanguage  *string `json:"explicit_language,omitempty"`
+	EnableSubtitle    *bool   `json:"enable_subtitle,omitempty"`
+}
+
+// SettingsUpdateHandler PUT /api/settings
+// 鉴权: RequireAdmin;store nil 时 503。
+// 至少要改 1 个字段(空 body 返 400);api_key 修改走专用端点 /api/settings/api-key。
+func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPut {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<16) // 64KB
+	var body SettingsUpdateRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+
+	// 收集要更新的键值对
+	updates := make(map[string]string)
+	if body.DefaultResourceID != nil {
+		v := trimAll(*body.DefaultResourceID)
+		if v == "" {
+			middleware.SendJSONError(w, http.StatusBadRequest, "default_resource_id cannot be empty", "invalid_request_error", "missing_field")
+			return
+		}
+		updates["default_resource_id"] = v
+	}
+	if body.DefaultSpeaker != nil {
+		v := trimAll(*body.DefaultSpeaker)
+		if v == "" {
+			middleware.SendJSONError(w, http.StatusBadRequest, "default_speaker cannot be empty", "invalid_request_error", "missing_field")
+			return
+		}
+		// 校验音色在库中(避免 default_speaker 引用不存在的 voice)
+		if _, err := s.VoiceGetByName(v); err != nil {
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				fmt.Sprintf("default_speaker %q not found in voices table", v),
+				"invalid_request_error", "default_speaker_missing")
+			return
+		}
+		updates["default_speaker"] = v
+	}
+	if body.DefaultFormat != nil {
+		v := trimAll(*body.DefaultFormat)
+		if !isValidFormat(v) {
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				fmt.Sprintf("default_format %q invalid; valid: mp3/wav/opus/pcm/aac/flac", v),
+				"invalid_request_error", "format_invalid")
+			return
+		}
+		updates["default_format"] = v
+	}
+	if body.SampleRate != nil {
+		v := *body.SampleRate
+		if v < 8000 || v > 48000 {
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				"sample_rate must be 8000-48000", "invalid_request_error", "sample_rate_invalid")
+			return
+		}
+		updates["sample_rate"] = strconv.Itoa(v)
+	}
+	if body.Model != nil {
+		updates["model"] = trimAll(*body.Model)
+	}
+	if body.ModelType != nil {
+		updates["model_type"] = strconv.Itoa(*body.ModelType)
+	}
+	if body.ExplicitLanguage != nil {
+		updates["explicit_language"] = trimAll(*body.ExplicitLanguage)
+	}
+	if body.EnableSubtitle != nil {
+		updates["enable_subtitle"] = boolToStr(*body.EnableSubtitle)
+	}
+
+	if len(updates) == 0 {
+		middleware.SendJSONError(w, http.StatusBadRequest,
+			"at least one field is required (use /api/settings/api-key to change api_key)",
+			"invalid_request_error", "no_fields")
+		return
+	}
+
+	// 写入 DB
+	if err := s.SettingsSetBatch(updates); err != nil {
+		log.Printf("[settings] update: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "write settings failed", "server_error", "db_write_failed")
+		return
+	}
+
+	// 关键: 更新后**立刻刷新运行时缓存**,M3 要求"改设置实时生效"
+	if err := setting.LoadRuntimeConfig(s); err != nil {
+		log.Printf("[settings] reload runtime: %v", err)
+		// 不返 500:DB 已写,只是 reload 失败;下次启动会生效
+		middleware.SendJSONError(w, http.StatusInternalServerError,
+			"settings saved but runtime reload failed; restart required",
+			"server_error", "reload_failed")
+		return
+	}
+
+	log.Printf("[settings] updated %d fields, runtime reloaded", len(updates))
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"ok":         true,
+		"updated":    len(updates),
+		"updated_at": time.Now().UTC().Format(time.RFC3339),
+	})
+}
+
+// SettingsAPIKeyRequest 是 PUT /api/settings/api-key 的 body。
+type SettingsAPIKeyRequest struct {
+	APIKey string `json:"api_key"`
+}
+
+// SettingsAPIKeyHandler PUT /api/settings/api-key
+// 鉴权: RequireAdmin。专门改 api_key,因为它需要单独的安全处理(不能 mask,要走加密通道)。
+func SettingsAPIKeyHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPut {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<10) // 1KB
+	var body SettingsAPIKeyRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+	key := trimAll(body.APIKey)
+	if key == "" {
+		middleware.SendJSONError(w, http.StatusBadRequest, "api_key cannot be empty", "invalid_request_error", "missing_field")
+		return
+	}
+
+	if err := s.SettingsSet("api_key", key); err != nil {
+		log.Printf("[settings] api-key set: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "write api_key failed", "server_error", "db_write_failed")
+		return
+	}
+	if err := setting.LoadRuntimeConfig(s); err != nil {
+		log.Printf("[settings] reload after api-key: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError,
+			"api_key saved but runtime reload failed", "server_error", "reload_failed")
+		return
+	}
+	log.Printf("[settings] api_key updated, runtime reloaded")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
+}
+
+// SettingsAuthKeyRequest 是 PUT /api/settings/auth-key 的 body。
+// auth_key 是 admin 鉴权和 /v1/audio/speech 鉴权用的 key(火山上游 key 是 api_key,这是两套)。
+type SettingsAuthKeyRequest struct {
+	AuthKey string `json:"auth_key"`
+}
+
+// SettingsAuthKeyHandler PUT /api/settings/auth-key
+// 鉴权: RequireAdmin。改完立即更新 setting.Auth.APIKeys(进程内生效),
+// 下一个请求就用新 key — admin 自己改完要等下一次请求才能验证(避免改完立刻自踢)。
+func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPut {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
+	var body SettingsAuthKeyRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+	key := trimAll(body.AuthKey)
+	if key == "" {
+		middleware.SendJSONError(w, http.StatusBadRequest, "auth_key cannot be empty", "invalid_request_error", "missing_field")
+		return
+	}
+	if err := s.SettingsSet("auth_key", key); err != nil {
+		log.Printf("[settings] auth-key set: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "write auth_key failed", "server_error", "db_write_failed")
+		return
+	}
+	// 立即生效:不重新 LoadRuntimeConfig(那会覆盖其它字段),
+	// 只单独刷新 Auth.APIKeys
+	setting.Auth.APIKeys = []string{key}
+	log.Printf("[settings] auth_key updated, runtime active (next request uses new key)")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
+}
+
+// SettingsCORSRequest 是 PUT /api/settings/cors 的 body。
+// 两个字段都可选(至少给一个):
+//   - allow_all: true → 任意 Origin 都接受(*);设了之后 origins 失效
+//   - origins: 一行一个 origin,后端 trim + lower + 去末尾 /
+type SettingsCORSRequest struct {
+	AllowAll *bool  `json:"allow_all,omitempty"`
+	Origins  string `json:"origins,omitempty"` // 也接受 string 数组(任一形式)
+}
+
+// SettingsCORSHandler PUT /api/settings/cors
+// 鉴权: RequireAdmin。改完立即更新 setting.CORS(进程内生效,跨域请求从下个请求开始按新配置)。
+// 同源豁免由 middleware/cors.go 的 isSameOrigin 处理,不在这里管。
+func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPut {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
+	var body SettingsCORSRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+	if body.AllowAll == nil && trimAll(body.Origins) == "" && body.Origins != "" {
+		// 空 body 不算错误,用户可能是想"清空"(只清 origins 保留现状)
+	}
+	if body.AllowAll == nil && body.Origins == "" {
+		middleware.SendJSONError(w, http.StatusBadRequest,
+			"at least one of allow_all / origins required",
+			"invalid_request_error", "no_fields")
+		return
+	}
+
+	updates := map[string]string{}
+	if body.AllowAll != nil {
+		updates["cors_allow_all"] = boolToStr(*body.AllowAll)
+	}
+	if body.Origins != "" {
+		// 校验每个 origin 至少像 http(s)://... (防止用户填空或填乱字符)
+		for _, line := range strings.Split(body.Origins, "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" {
+				continue
+			}
+			low := strings.ToLower(line)
+			if !strings.HasPrefix(low, "http://") && !strings.HasPrefix(low, "https://") {
+				middleware.SendJSONError(w, http.StatusBadRequest,
+					fmt.Sprintf("invalid origin: %q (must start with http:// or https://)", line),
+					"invalid_request_error", "origin_invalid")
+				return
+			}
+		}
+		updates["cors_origins"] = body.Origins
+	}
+	if err := s.SettingsSetBatch(updates); err != nil {
+		log.Printf("[settings] cors set: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "write cors failed", "server_error", "db_write_failed")
+		return
+	}
+
+	// 立即刷新 setting.CORS,跨域请求从下个请求开始按新配置生效
+	// 复用 LoadRuntimeConfig 的解析逻辑(只取 cors 部分,避免覆盖其它运行时字段)
+	corsAllowAll, _ := s.SettingsGetBool("cors_allow_all", false)
+	originsStr := ""
+	if v, _, _ := s.SettingsGet("cors_origins"); v != "" {
+		originsStr = v
+	}
+	if corsAllowAll {
+		setting.CORS.AllowAll = true
+		setting.CORS.Origins = nil
+	} else if originsStr != "" {
+		setting.CORS.AllowAll = false
+		setting.CORS.Origins = setting.SplitOriginsForCORS(originsStr)
+	} else {
+		setting.CORS.AllowAll = false
+		setting.CORS.Origins = nil
+	}
+	log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.CORS.AllowAll, originsStr)
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"ok":           true,
+		"allow_all":    setting.CORS.AllowAll,
+		"origins":      originsStr,
+		"cors_active":  true,
+	})
+}
+
+// maskAPIKeyField 复用 setting 包的打码风格(前 4 后 4 中间 ****)。
+// 单独导出版本避免从 setting 包拉整个 APIKeyMask 之类的工具(那个是 unexported)。
+func maskAPIKeyField(s string) string {
+	if s == "" {
+		return ""
+	}
+	if len(s) <= 4 {
+		return "****"
+	}
+	// 仿 setting.maskAPIKey: 但这里打的是 TTS 服务用的 key,可能含字母数字和连字符
+	return s[:4] + "****" + s[len(s)-4:]
+}
+
+func trimAll(s string) string {
+	// 简单 trim 前后空白;不剥中间空格
+	out := s
+	for len(out) > 0 && (out[0] == ' ' || out[0] == '\t' || out[0] == '\n' || out[0] == '\r') {
+		out = out[1:]
+	}
+	for len(out) > 0 && (out[len(out)-1] == ' ' || out[len(out)-1] == '\t' || out[len(out)-1] == '\n' || out[len(out)-1] == '\r') {
+		out = out[:len(out)-1]
+	}
+	return out
+}
+
+func isValidFormat(s string) bool {
+	switch s {
+	case "mp3", "wav", "opus", "pcm", "aac", "flac", "":
+		return true
+	}
+	return false
+}
+
+func boolToStr(b bool) string {
+	if b {
+		return "1"
+	}
+	return "0"
+}

controller/setup.go

@@ -169,6 +169,19 @@ func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// 立即把 auth_key 灌到 setting.Auth.APIKeys,这样后续 /v1/audio/speech 和 /admin
+	// 在本进程内能立刻用新 key(无需等 LoadRuntimeConfig)。
+	authKey := strings.TrimSpace(body.Settings["auth_key"])
+	if authKey != "" {
+		setting.Auth.APIKeys = []string{authKey}
+	}
+
+	// 装完 reload TTS 全局配置(让 TTSOptions 立即有可用的 api_key/speaker/resource_id,
+	// 否则 /v1/audio/speech 会因为 TTSConfigErr 在启动期被设而返 503,要重启才生效)。
+	if err := setting.LoadRuntimeConfig(GetSetupStore()); err != nil {
+		log.Printf("[setup] warning: 装完 LoadRuntimeConfig 失败: %v(下次启动会恢复)", err)
+	}
+
 	// 清空旧 voices 再插入(假设是首次安装;若不是,name 冲突会变成 409)
 	// 这里选择 "清空+插入" 语义,符合"setup 是首次安装"的产品定位
 	// 如果想保留旧 voices,可以改成 UPSERT,但 M1 不做
@@ -177,11 +190,21 @@ func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 		log.Printf("[setup] 检测到 %d 条已存在 voices,本次将跳过清空(name 冲突由 ErrDuplicate 处理)", len(existing))
 	}
 	inserted := 0
+	// 【UX 改进】voice 行的 resource_id 留空时,自动用 settings.default_resource_id 兜底。
+	// 用户在 step 2 填了 default_resource_id 后,step 3 的 voice 行 resource_id
+	// 可以不填 — 保持一致。否则会出现 "settings 里 seed-icl-2.0,voice 里 volc.megatts.icl"
+	// 这种 mismatch,运行时 500。
+	defaultResourceID := settingsKV["default_resource_id"]
 	for _, v := range body.Voices {
+		voiceResourceID := v.ResourceID
+		if voiceResourceID == "" {
+			voiceResourceID = defaultResourceID
+			log.Printf("[setup] voice %q resource_id 留空,自动用 default_resource_id=%q", v.Name, defaultResourceID)
+		}
 		_, err := s.VoiceInsert(store.Voice{
 			Name:       v.Name,
 			Speaker:    v.Speaker,
-			ResourceID: v.ResourceID,
+			ResourceID: voiceResourceID,
 			Model:      v.Model,
 			Language:   v.Language,
 			Enabled:    true,
@@ -224,8 +247,10 @@ func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 }
 
 // validateSetupSettings 校验必填项。
+// auth_key (鉴权) 也是必填 — 让 setup 成为"单一配置入口",
+// 用户装完不用再回去设 OPENAI_TTS_API_KEY env。
 func validateSetupSettings(m map[string]string) error {
-	required := []string{"api_key", "default_resource_id", "default_speaker"}
+	required := []string{"api_key", "auth_key", "default_resource_id", "default_speaker"}
 	var missing []string
 	for _, k := range required {
 		if strings.TrimSpace(m[k]) == "" {
@@ -252,9 +277,9 @@ func validateSetupVoices(vs []SetupVoice) error {
 		if strings.TrimSpace(v.Speaker) == "" {
 			return fmt.Errorf("voices[%d] (%s): speaker is required", i, v.Name)
 		}
-		if strings.TrimSpace(v.ResourceID) == "" {
+		// 【UX 改进】resource_id 留空是允许的 — 装时(下面那个循环)会自动用
-			return fmt.Errorf("voices[%d] (%s): resource_id is required", i, v.Name)
+		// settings.default_resource_id 兜底。用户只填 step 2 一处即可。
-		}
+		_ = v.ResourceID // (保留以便以后加更细的校验)
 		if _, dup := names[v.Name]; dup {
 			return fmt.Errorf("voices[%d]: duplicate name %q", i, v.Name)
 		}

controller/tts.go

@@ -18,6 +18,7 @@ import (
 	"github.com/volcano-tts/tts-api/metrics"
 	"github.com/volcano-tts/tts-api/middleware"
 	"github.com/volcano-tts/tts-api/setting"
+	"github.com/volcano-tts/tts-api/store"
 	"github.com/volcano-tts/tts-api/telemetry"
 	"github.com/volcano-tts/tts-api/version"
 )
@@ -153,6 +154,52 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 	opts := setting.TTSOptions
 	opts.Text = req.Input
 
+	// M3: voice 路由
+	//   - voice 为空 → 走 LoadRuntimeConfig 解析过的 opts.Speaker (已是真 speaker ID,
+	//     default_speaker 是 voice 名,LoadRuntimeConfig 查 voice 表后替换)
+	//   - voice 非空 → 查 voices 表,替换 opts.Speaker / ResourceID / Model
+	//   - 命中但 enabled=0 → 仍可用(用户显式传 voice 即覆盖 enabled 状态;若想禁用在 admin UI 关掉就行)
+	//   - 未命中 → 400 "unknown voice: <name>"
+	if req.Voice != "" {
+		s := GetAdminStore()
+		if s == nil {
+			log.Printf("警告: voice=%s 路由但 store 未初始化 - 路径=%s", req.Voice, r.URL.Path)
+			middleware.SendJSONError(w, http.StatusServiceUnavailable,
+				"voice routing requires database; not initialized",
+				"configuration_error", "db_not_ready")
+			return
+		}
+		v, err := s.VoiceGetByName(req.Voice)
+		if err != nil {
+			if err == store.ErrNotFound {
+				log.Printf("警告: 未知 voice=%q - 路径=%s 客户端=%s", req.Voice, r.URL.Path, middleware.GetClientIP(r))
+				middleware.SendJSONError(w, http.StatusBadRequest,
+					fmt.Sprintf("unknown voice: '%s'", req.Voice),
+					"invalid_request_error", "unknown_voice")
+				return
+			}
+			log.Printf("警告: voice 查库失败 - 错误=%v voice=%s", err, req.Voice)
+			middleware.SendJSONError(w, http.StatusInternalServerError,
+				"voice lookup failed", "server_error", "db_read_failed")
+			return
+		}
+		// 覆盖 opts(API key / UID 保留自 setting.TTSOptions)
+		if !v.Enabled {
+			log.Printf("警告: voice=%q 已禁用 - 客户端=%s", req.Voice, middleware.GetClientIP(r))
+			middleware.SendJSONError(w, http.StatusForbidden,
+				fmt.Sprintf("voice '%s' is disabled", req.Voice),
+				"invalid_request_error", "voice_disabled")
+			return
+		}
+		opts.Speaker = v.Speaker
+		opts.ResourceID = v.ResourceID
+		if v.Model != "" {
+			opts.Model = v.Model
+		}
+		log.Printf("[tts] voice=%s 命中 (speaker=%s resource=%s model=%s) - 客户端=%s",
+			req.Voice, telemetry.MaskSpeaker(v.Speaker), v.ResourceID, v.Model, middleware.GetClientIP(r))
+	}
+
 	ctx, cancel := context.WithTimeout(r.Context(), setting.TTSTimeout)
 	defer cancel()
 
@@ -258,6 +305,7 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 		ConfigStatus: dto.ConfigStatusResponse{
 			AllRequiredVarsSet: allRequired,
 			ConfigError:        setting.TTSConfigErr != nil,
+			Error:              configErrorMessage(setting.TTSConfigErr),
 		},
 		Installed: mode == installer.ModeNormal,
 		Mode:      mode.String(),
@@ -265,6 +313,15 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(resp)
 }
 
+// configErrorMessage 把 setting.TTSConfigErr 安全地转成可对外暴露的字符串。
+// 仅在 normal 模式且有错时调用, error 为 nil 时返 "" (被 omitempty 跳过)。
+func configErrorMessage(err error) string {
+	if err == nil {
+		return ""
+	}
+	return err.Error()
+}
+
 var startTime time.Time
 
 func SetStartTime(t time.Time) { startTime = t }

docker-compose.yml

@@ -1,23 +1,32 @@
-version: '3.8'
-
 services:
   tts-api:
     build: .
+    image: volcano-tts-aggregator:latest
     container_name: tts-api
     ports:
       - "${PORT:-8080}:8080"
     environment:
-      - BYTEDANCE_TTS_API_KEY=${BYTEDANCE_TTS_API_KEY}
+      # 4 个启动引导 env(仅这 4 个必看)
-      - BYTEDANCE_TTS_RESOURCE_ID=${BYTEDANCE_TTS_RESOURCE_ID}
+      # 业务配置(api_key/resource_id/speaker/格式...)通过 WebUI 设置,
-      - BYTEDANCE_TTS_SPEAKER=${BYTEDANCE_TTS_SPEAKER}
+      # 存到 /data/tts.db 持久化
-      - BYTEDANCE_TTS_TIMEOUT=${BYTEDANCE_TTS_TIMEOUT:-30s}
+      - TTS_ADMIN_KEY=${TTS_ADMIN_KEY:-}
-      - OPENAI_TTS_API_KEY=${OPENAI_TTS_API_KEY:-}
+      - TTS_DB_PATH=/data/tts.db
-      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
       - PORT=8080
+      - OPENAI_TTS_API_KEY=${OPENAI_TTS_API_KEY:-}
+      # 可选,装好后也可在 /admin 改
+      - TRUSTED_PROXY_HOPS=${TRUSTED_PROXY_HOPS:-}
+    volumes:
+      # DB + lock 文件必须挂载,否则容器重启后配置全丢
+      - tts-data:/data
     restart: unless-stopped
     healthcheck:
+      # 用 wget 检查,alpine 镜像有
       test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
       interval: 30s
       timeout: 5s
       retries: 3
-      start_period: 5s
+      start_period: 10s
+
+volumes:
+  tts-data:
+    name: tts-api-data

dto/health.go

@@ -18,6 +18,8 @@ type HealthResponse struct {
 }
 
 type ConfigStatusResponse struct {
-	AllRequiredVarsSet bool `json:"all_required_vars_set"`
+	AllRequiredVarsSet bool   `json:"all_required_vars_set"`
-	ConfigError        bool `json:"config_error"`
+	ConfigError        bool   `json:"config_error"`
+	// Error 仅在 ConfigError=true 时填充, 给出原始 error message, 方便运维 / curl 一眼看出原因
+	Error string `json:"error,omitempty"`
 }

main.go

@@ -15,6 +15,7 @@ import (
 	"github.com/volcano-tts/tts-api/middleware"
 	"github.com/volcano-tts/tts-api/router"
 	"github.com/volcano-tts/tts-api/setting"
+	"github.com/volcano-tts/tts-api/telemetry"
 )
 
 // ttsDBPath 返回数据库/lock 所在路径;空时落到当前目录的 tts.db。
@@ -29,11 +30,11 @@ func main() {
 	log.SetFlags(log.LstdFlags | log.Lshortfile)
 	log.SetPrefix("[TTS-Server] ")
 
-	// 1) 加载引导环境变量(PORT / OPENAI_TTS_API_KEY / TTS_ADMIN_KEY 等)
+	// 1) 加载引导环境变量(PORT / TTS_ADMIN_KEY / OPENAI_TTS_API_KEY 兜底)
+	// 注: Auth.APIKeys 在 InitAllConfigs 里先读 env,后被 LoadRuntimeConfig 覆盖为 DB 值。
 	setting.InitAllConfigs()
 	metrics.Init()
 	middleware.InitRateLimiter()
-	setting.LogStartupSummary()
 
 	// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
 	dbPath := ttsDBPath()
@@ -47,14 +48,42 @@ func main() {
 	if res.Corrupted {
 		log.Printf("[main] 注意: 启动时检测到 db 损坏并已自愈回退(备份=%s)", res.BackupTo)
 	}
-	// 注入 setup 控制器需要的 store + dbPath(无论哪种模式都注入,正常模式下备用)
+
+	// 3) 注入 setup/admin 控制器需要的句柄(M1+M2)
 	controller.SetSetupState(st, dbPath)
-	// 注入 admin 控制器需要的 store + 指标文本写入器(M2)
 	controller.SetAdminStore(st)
 	controller.SetMetricsTextWriter(func(w http.ResponseWriter) error {
 		metrics.Meter.Handler().ServeHTTP(w, &http.Request{})
 		return nil
 	})
+
+	// 4) M3: 从 store 加载运行时 TTS 配置(替代原来的 env-based InitTTSConfig)
+	// 必须在 LogStartupSummary 之前,这样日志显示的是真实状态(API key 已从 DB 加载,不再读 env)
+	//
+	// 模式区分:
+	//   - setup 模式 + 失败 = 正常(还没装), 警告即可
+	//   - normal 模式 + 失败 = 致命(已装但配置坏), fail-fast 让 K8s/进程管理器拉起
+	if st != nil {
+		if err := setting.LoadRuntimeConfig(st); err != nil {
+			mode := installer.GetMode()
+			modeName := "setup"
+			if mode == installer.ModeNormal {
+				modeName = "normal"
+			}
+			metrics.ConfigLoadFailures.Inc(telemetry.Labels{"mode": modeName})
+			if mode == installer.ModeNormal {
+				log.Printf("[main][FATAL] TTS 运行时配置加载失败 (normal mode, 服务无法启动): %v", err)
+				log.Fatalf("service cannot start in normal mode without valid config: %v", err)
+			}
+			log.Printf("[main][WARN] TTS 运行时配置加载失败 (setup mode, 需先 /setup): %v", err)
+		} else {
+			log.Printf("[main] TTS 运行时配置已加载(api_key=***, speaker=%s, resource=%s, format=%s)",
+				setting.TTSOptions.Speaker, setting.TTSOptions.ResourceID, setting.TTSOptions.Format)
+		}
+	}
+
+	// 5) 启动摘要日志(此时 Auth.APIKeys 已是 DB 值,日志反映真实状态)
+	setting.LogStartupSummary()
 	log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
 
 	controller.InitController()

metrics/metrics.go

@@ -34,6 +34,9 @@ var (
 	ConcurrencyRejected *telemetry.Counter
 	RateLimitRejected   *telemetry.Counter
 	AuthFailed          *telemetry.Counter
+
+	// 启动期配置加载失败(仅 normal 模式可能触发,触发后服务 fail-fast)
+	ConfigLoadFailures *telemetry.Counter
 )
 
 // Init 初始化所有指标。在 main 启动期调用一次。
@@ -107,6 +110,11 @@ func Init() {
 		"tts_auth_failed_total",
 		"Requests rejected due to invalid/missing API key.",
 	)
+	ConfigLoadFailures = m.NewCounter(
+		"tts_config_load_failures_total",
+		"TTS runtime config load failures during startup. labeled by mode (normal/setup).",
+		"mode",
+	)
 }
 
 // AdapterRecorder 把 telemetry 指标适配为 volcano.MetricsRecorder。

middleware/cors.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/installer"
 	"github.com/volcano-tts/tts-api/setting"
 )
 
@@ -40,8 +41,73 @@ func matchOrigin(origin string) (string, bool) {
 	return "", false
 }
 
+// isSameOrigin 比较 Origin 与 r.Host,判断是否同源。
+//   - 直接访问(server 自己:80): Origin=http://server:80, Host=server:80 → 同源
+//   - 反向代理(https://app.example.com → http://server:80):
+//     Origin=https://app.example.com, Host=server:80
+//     默认不同源;但如果设置 TRUSTED_PROXY_HOPS 或 X-Forwarded-Host,要让它们一致。
+//   - 浏览器对同源 POST 也会设 Origin(避免被自己的 CORS 误伤),这里豁免。
+// 返回 true 表示请求来自自己,无需 CORS 介入。
+func isSameOrigin(r *http.Request) bool {
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		return false
+	}
+	// 解析 Origin 的 host 部分
+	originHost, originScheme := splitOrigin(origin)
+	if originHost == "" {
+		return false
+	}
+	// 优先用 X-Forwarded-Host / X-Forwarded-Proto(反向代理场景),
+	// 退而用 r.Host(直接访问场景)
+	reqHost := r.Host
+	if fh := r.Header.Get("X-Forwarded-Host"); fh != "" {
+		// X-Forwarded-Host 可能是 host1, host2 (取第一个)
+		if i := strings.Index(fh, ","); i >= 0 {
+			fh = strings.TrimSpace(fh[:i])
+		}
+		reqHost = fh
+	}
+	reqScheme := "http"
+	if r.TLS != nil {
+		reqScheme = "https"
+	} else if fp := r.Header.Get("X-Forwarded-Proto"); fp != "" {
+		if i := strings.Index(fp, ","); i >= 0 {
+			fp = strings.TrimSpace(fp[:i])
+		}
+		reqScheme = strings.ToLower(fp)
+	}
+	// host 匹配(忽略大小写)
+	return strings.EqualFold(originHost, reqHost) && strings.EqualFold(originScheme, reqScheme)
+}
+
+// splitOrigin 把 "https://example.com:8080" 拆成 ("example.com:8080", "https")。
+// 没有 scheme 时返回 ("", "")。
+func splitOrigin(origin string) (host, scheme string) {
+	idx := strings.Index(origin, "://")
+	if idx < 0 || idx == 0 {
+		return "", ""
+	}
+	scheme = origin[:idx]
+	rest := origin[idx+3:]
+	// 去掉 path 部分
+	if i := strings.Index(rest, "/"); i >= 0 {
+		rest = rest[:i]
+	}
+	return rest, scheme
+}
+
 func CORS(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 安装模式完全跳过 CORS:
+		//   - 用户首次装,不可能提前知道自己的访问域名来配 ALLOWED_ORIGINS
+		//   - 装完进 normal 模式后,设的 CORS 才生效(从 DB 读)
+		// 这样 install 永远能成功,装完再通过 WebUI 配 CORS。
+		if installer.GetMode() == installer.ModeSetup {
+			next.ServeHTTP(w, r)
+			return
+		}
+
 		origin := r.Header.Get("Origin")
 
 		// 无 Origin 头:非跨域请求,跳过 CORS 处理
@@ -50,6 +116,14 @@ func CORS(next http.Handler) http.Handler {
 			return
 		}
 
+		// 同源豁免:浏览器对同源 POST/JSON 也会发 Origin 头(防 fetch 滥用),
+		// 但同源请求本就不需要 CORS 介入。这里对比 Origin 与 Host(含 X-Forwarded-*),
+		// 一致就放行,避免自家人被自家 CORS 拦。
+		if isSameOrigin(r) {
+			next.ServeHTTP(w, r)
+			return
+		}
+
 		// 有 Origin 头时,响应必须携带 Vary: Origin 防止 CDN 缓存污染
 		vary := w.Header().Get("Vary")
 		if vary == "" {

router/router.go

@@ -80,6 +80,13 @@ func Setup() *mux.Router {
 	r.Handle("/api/voices/{name}", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoiceDeleteHandler))).Methods("DELETE")
 	r.Handle("/api/voices/{name}/toggle", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoiceToggleHandler))).Methods("PATCH")
 
+	// /api/settings 全局设置 (鉴权) — M3
+	r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsGetHandler))).Methods("GET")
+	r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsUpdateHandler))).Methods("PUT")
+	r.Handle("/api/settings/api-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAPIKeyHandler))).Methods("PUT")
+	r.Handle("/api/settings/auth-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAuthKeyHandler))).Methods("PUT")
+	r.Handle("/api/settings/cors", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsCORSHandler))).Methods("PUT")
+
 	// 业务路由
 	r.HandleFunc("/v1/audio/speech", controller.OpenaiTTSHandler).Methods("POST", "OPTIONS")
 	r.HandleFunc("/health", controller.HealthHandler).Methods("GET")

router/setup.html

@@ -8,105 +8,223 @@
     <script src="https://cdn.bootcdn.net/ajax/libs/axios/1.6.7/axios.min.js"></script>
     <style>
         :root {
-            --bg: #0b0f1a;
+            --bg: #0a0e1a;
             --bg-card: #131826;
             --bg-elev: #1a2138;
+            --bg-hover: #1f2740;
             --border: #232b42;
+            --border-strong: #2e3754;
             --text: #e4e7ee;
-            --text-dim: #8a92a6;
+            --text-dim: #94a3b8;
-            --text-mute: #5a6275;
+            --text-mute: #64748b;
             --accent: #00d4ff;
+            --accent-hover: #33ddff;
             --accent-2: #7b2ff7;
+            --accent-soft: rgba(0, 212, 255, 0.10);
+            --accent-glow: rgba(0, 212, 255, 0.35);
             --success: #22c55e;
+            --success-soft: rgba(34, 197, 94, 0.12);
             --warning: #f59e0b;
+            --warning-soft: rgba(245, 158, 11, 0.12);
             --danger: #ef4444;
+            --danger-soft: rgba(239, 68, 68, 0.12);
+            --radius: 8px;
+            --radius-lg: 12px;
+            --radius-xl: 16px;
+            --shadow: 0 4px 16px rgba(0,0,0,0.25);
+            --shadow-lg: 0 20px 50px rgba(0,0,0,0.5);
         }
         * { margin: 0; padding: 0; box-sizing: border-box; }
         body {
             font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
             background: var(--bg); color: var(--text);
-            min-height: 100vh; padding: 32px 24px; font-size: 14px;
+            min-height: 100vh; padding: 40px 24px; font-size: 14px; line-height: 1.5;
+            -webkit-font-smoothing: antialiased;
             background-image:
-                radial-gradient(ellipse 80% 50% at 50% -20%, rgba(0,212,255,0.08), transparent),
+                radial-gradient(ellipse 70% 50% at 30% 0%, rgba(0,212,255,0.07), transparent),
-                radial-gradient(ellipse 60% 40% at 80% 100%, rgba(123,47,247,0.06), transparent);
+                radial-gradient(ellipse 50% 40% at 100% 100%, rgba(123,47,247,0.05), transparent);
+            background-attachment: fixed;
         }
         #app { max-width: 760px; margin: 0 auto; }
 
+        /* === Header === */
         .header { display: flex; align-items: center; gap: 16px; margin-bottom: 28px; }
         .logo {
-            width: 48px; height: 48px; border-radius: 12px;
+            width: 52px; height: 52px; border-radius: 14px;
             background: linear-gradient(135deg, var(--accent), var(--accent-2));
             display: flex; align-items: center; justify-content: center;
-            font-weight: 700; font-size: 20px; color: #fff; box-shadow: 0 4px 20px rgba(0,212,255,0.3);
+            font-weight: 700; font-size: 20px; color: #fff;
+            box-shadow: 0 6px 24px var(--accent-glow);
         }
-        .header h1 { font-size: 22px; font-weight: 600; }
+        .header-text h1 { font-size: 22px; font-weight: 600; letter-spacing: -0.01em; }
-        .header .sub { font-size: 12px; color: var(--text-dim); margin-top: 4px; }
+        .header-text .sub { font-size: 13px; color: var(--text-dim); margin-top: 4px; }
 
-        .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 24px; margin-bottom: 16px; }
+        /* === Steps === */
-        .card-title { font-size: 15px; font-weight: 600; margin-bottom: 4px; }
+        .steps { display: flex; align-items: center; gap: 0; margin-bottom: 28px; padding: 16px 20px; background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius-lg); }
-        .card-desc { font-size: 12px; color: var(--text-dim); margin-bottom: 16px; }
+        .step { display: flex; align-items: center; gap: 10px; flex: 1; min-width: 0; }
+        .step-num {
+            width: 28px; height: 28px; border-radius: 50%;
+            display: flex; align-items: center; justify-content: center;
+            font-size: 12px; font-weight: 600; flex-shrink: 0;
+            background: var(--bg-elev); color: var(--text-mute);
+            border: 1px solid var(--border);
+        }
+        .step.active .step-num { background: var(--accent); color: #00121a; border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-soft); }
+        .step.done .step-num { background: var(--success-soft); color: var(--success); border-color: rgba(34,197,94,0.3); }
+        .step-label { font-size: 13px; color: var(--text-dim); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+        .step.active .step-label, .step.done .step-label { color: var(--text); }
+        .step-line { flex: 1; height: 1px; background: var(--border); margin: 0 12px; min-width: 16px; }
+        .step.done + .step-line { background: var(--accent); opacity: 0.4; }
 
-        .field { margin-bottom: 14px; }
+        /* === Card === */
-        .field label { display: block; font-size: 12px; color: var(--text-dim); margin-bottom: 6px; }
+        .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius-lg); padding: 24px; margin-bottom: 16px; }
-        .field label .req { color: var(--danger); margin-left: 4px; }
+        .card-head { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 18px; gap: 12px; }
+        .card-title { font-size: 16px; font-weight: 600; }
+        .card-sub { font-size: 12px; color: var(--text-dim); margin-top: 4px; line-height: 1.6; }
+        .step-badge { font-size: 11px; padding: 3px 8px; border-radius: 999px; background: var(--accent-soft); color: var(--accent); border: 1px solid rgba(0,212,255,0.3); font-weight: 500; }
+
+        /* === Form === */
+        .field { margin-bottom: 16px; }
+        .field label { display: block; font-size: 12px; color: var(--text-dim); margin-bottom: 6px; font-weight: 500; }
+        .field label .req { color: var(--danger); margin-left: 2px; }
         .field input, .field select {
             width: 100%; background: var(--bg-elev); border: 1px solid var(--border);
-            color: var(--text); padding: 10px 12px; border-radius: 8px; font-size: 13px;
+            color: var(--text); padding: 10px 12px; border-radius: var(--radius); font-size: 13px;
-            font-family: inherit; transition: border-color 0.2s;
+            font-family: inherit; transition: border-color 0.15s, box-shadow 0.15s;
         }
-        .field input:focus, .field select:focus { outline: none; border-color: var(--accent); }
+        .field input:focus, .field select:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
-        .field .hint { font-size: 11px; color: var(--text-mute); margin-top: 4px; }
+        .field input::placeholder { color: var(--text-mute); }
-        .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+        .field select {
+            appearance: none;
+            background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'><path fill='%238a92a6' d='M6 8L1 3h10z'/></svg>");
+            background-repeat: no-repeat; background-position: right 10px center; padding-right: 30px;
+        }
+        .field .hint { font-size: 11px; color: var(--text-mute); margin-top: 5px; line-height: 1.5; }
+        .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
+        .field-row .field { margin-bottom: 0; }
+        code { font-family: ui-monospace, SFMono-Regular, monospace; font-size: 0.9em; background: var(--bg-elev); padding: 1px 5px; border-radius: 4px; color: var(--accent); }
 
-        .voice-row { display: grid; grid-template-columns: 1fr 1fr 1.4fr 1.2fr 32px; gap: 8px; align-items: center; margin-bottom: 8px; }
+        /* === Voice list === */
-        .voice-row input { font-size: 12px; padding: 8px 10px; }
+        .voice-row {
-        .voice-row .rm { background: transparent; border: 1px solid var(--border); color: var(--danger); cursor: pointer; padding: 6px; border-radius: 6px; font-size: 14px; }
+            display: grid; grid-template-columns: 1fr 1fr 1.4fr 1.2fr 36px;
-        .voice-row .rm:hover { border-color: var(--danger); }
+            gap: 10px; align-items: center; margin-bottom: 8px;
+        }
+        .voice-row input { font-size: 12px; padding: 8px 10px; font-family: ui-monospace, SFMono-Regular, monospace; }
+        .voice-row .rm {
+            background: transparent; border: 1px solid var(--border);
+            color: var(--text-mute); cursor: pointer; padding: 7px 0;
+            border-radius: var(--radius); font-size: 15px;
+            transition: all 0.12s;
+        }
+        .voice-row .rm:hover:not(:disabled) { border-color: var(--danger); color: var(--danger); background: var(--danger-soft); }
+        .voice-row .rm:disabled { opacity: 0.3; cursor: not-allowed; }
+        .voice-row-head {
+            display: grid; grid-template-columns: 1fr 1fr 1.4fr 1.2fr 36px;
+            gap: 10px; font-size: 11px; color: var(--text-mute);
+            text-transform: uppercase; letter-spacing: 0.5px; font-weight: 600;
+            padding: 0 2px 6px;
+        }
 
+        /* === Buttons === */
         .btn {
+            display: inline-flex; align-items: center; justify-content: center; gap: 6px;
             background: var(--bg-elev); border: 1px solid var(--border); color: var(--text);
-            padding: 10px 18px; border-radius: 8px; cursor: pointer; font-size: 13px;
+            padding: 10px 18px; border-radius: var(--radius); cursor: pointer; font-size: 13px; font-weight: 500;
-            transition: all 0.2s; display: inline-flex; align-items: center; gap: 6px;
+            font-family: inherit; transition: all 0.12s;
-            font-family: inherit;
         }
-        .btn:hover { border-color: var(--accent); }
+        .btn:hover:not(:disabled) { border-color: var(--border-strong); background: var(--bg-hover); }
-        .btn-primary { background: var(--accent); color: #00121a; border-color: var(--accent); font-weight: 500; }
+        .btn:disabled { opacity: 0.5; cursor: not-allowed; }
-        .btn-primary:hover { background: #33ddff; }
+        .btn-primary { background: var(--accent); color: #00121a; border-color: var(--accent); }
-        .btn-primary:disabled { background: var(--text-mute); border-color: var(--text-mute); cursor: not-allowed; color: var(--bg); }
+        .btn-primary:hover:not(:disabled) { background: var(--accent-hover); border-color: var(--accent-hover); }
         .btn-add { background: transparent; border: 1px dashed var(--border); color: var(--text-dim); width: 100%; justify-content: center; padding: 10px; }
-        .btn-add:hover { border-color: var(--accent); color: var(--accent); }
+        .btn-add:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); border-style: solid; }
 
-        .actions { display: flex; justify-content: space-between; align-items: center; margin-top: 24px; }
+        /* === Actions === */
-        .err { color: var(--danger); font-size: 12px; margin-top: 8px; }
+        .actions { display: flex; justify-content: space-between; align-items: center; margin-top: 24px; padding: 20px 24px; background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius-lg); }
-        .ok { color: var(--success); font-size: 12px; margin-top: 8px; }
+        .actions .hint-text { color: var(--text-mute); font-size: 12px; }
 
-        .banner { background: rgba(245,158,11,0.1); border: 1px solid rgba(245,158,11,0.3); border-radius: 8px; padding: 10px 14px; color: var(--warning); font-size: 12px; margin-bottom: 16px; }
+        /* === Alerts === */
+        .alert { display: flex; align-items: flex-start; gap: 10px; padding: 10px 14px; border-radius: var(--radius); margin-bottom: 16px; font-size: 13px; }
+        .alert-icon { font-size: 15px; flex-shrink: 0; }
+        .alert-body { flex: 1; }
+        .alert-danger { background: var(--danger-soft); border: 1px solid rgba(239,68,68,0.3); color: var(--danger); }
+        .alert-warning { background: var(--warning-soft); border: 1px solid rgba(245,158,11,0.3); color: var(--warning); }
     </style>
 </head>
 <body>
     <div id="app">
+
         <div class="header">
             <div class="logo">TTS</div>
-            <div>
+            <div class="header-text">
                 <h1>火山 TTS 聚合平台 · 首次安装</h1>
                 <div class="sub">填写以下信息完成初始化。token 来自启动日志或环境变量 <code>TTS_ADMIN_KEY</code>。</div>
             </div>
         </div>
 
-        <div v-if="errorMsg" class="banner">⚠ {{ errorMsg }}</div>
+        <!-- Steps -->
+        <div class="steps">
+            <div class="step" :class="{active: step===1, done: step>1}">
+                <div class="step-num">1</div>
+                <div class="step-label">上游凭证</div>
+            </div>
+            <div class="step-line"></div>
+            <div class="step" :class="{active: step===2, done: step>2}">
+                <div class="step-num">2</div>
+                <div class="step-label">默认路由</div>
+            </div>
+            <div class="step-line"></div>
+            <div class="step" :class="{active: step===3, done: step>3}">
+                <div class="step-num">3</div>
+                <div class="step-label">音色列表</div>
+            </div>
+            <div class="step-line"></div>
+            <div class="step" :class="{active: step===4}">
+                <div class="step-num">4</div>
+                <div class="step-label">完成安装</div>
+            </div>
+        </div>
 
-        <div class="card">
+        <div v-if="errorMsg" class="alert alert-danger">
-            <div class="card-title">火山引擎 TTS 凭证</div>
+            <span class="alert-icon">⚠</span>
-            <div class="card-desc">从火山引擎控制台获取,API Key 仅在此页面输入,不会回显。</div>
+            <div class="alert-body">{{ errorMsg }}</div>
+        </div>
+
+        <!-- Step 1: 上游凭证 -->
+        <div v-show="step===1" class="card">
+            <div class="card-head">
+                <div>
+                    <div class="card-title">OpenAI 鉴权 + 火山引擎凭证</div>
+                    <div class="card-sub">两个 Key 仅在此页面输入,不会回显,装完不用再碰 env。</div>
+                </div>
+                <span class="step-badge">第 1 步</span>
+            </div>
             <div class="field">
-                <label>API Key <span class="req">*</span></label>
+                <label>OpenAI 鉴权 Key <span class="req">*</span></label>
+                <input type="password" v-model="form.auth_key" placeholder="自定,例如 my-secret-key-2024" autocomplete="off">
+                <div class="hint">客户端用这个 Key 调 <code>/v1/audio/speech</code>,也是登录 <code>/admin</code> 的密码。装完可在 <code>/admin → 设置</code> 改。</div>
+            </div>
+            <div class="field">
+                <label>火山 TTS API Key <span class="req">*</span></label>
                 <input type="password" v-model="form.api_key" placeholder="例如: 5b4d7c2a-..." autocomplete="off">
+                <div class="hint">调火山 v3 上游用的凭证,从 <a href="https://console.volcengine.com/" target="_blank" style="color: var(--accent);">火山控制台</a> 获取。</div>
+            </div>
+        </div>
+
+        <!-- Step 2: 默认路由 -->
+        <div v-show="step===2" class="card">
+            <div class="card-head">
+                <div>
+                    <div class="card-title">默认路由与格式</div>
+                    <div class="card-sub">未传 voice/format 时使用。装完可在 <code>/admin → 设置</code> 改。</div>
+                </div>
+                <span class="step-badge">第 2 步</span>
             </div>
             <div class="field-row">
                 <div class="field">
                     <label>默认资源 ID <span class="req">*</span></label>
-                    <input v-model="form.default_resource_id" placeholder="volc.megatts.default">
+                    <input v-model="form.default_resource_id" placeholder="seed-icl-2.0">
-                    <div class="hint">音色所属的计费资源 ID;volc.megatts.icl 用于复刻音色。</div>
+                    <div class="hint">音色所属的计费资源 ID;本项目为豆包声音复刻大模型 2.0,固定使用 <code>seed-icl-2.0</code>。</div>
                 </div>
                 <div class="field">
                     <label>默认音色 <span class="req">*</span></label>
@@ -138,26 +256,79 @@
             </div>
         </div>
 
-        <div class="card">
+        <!-- Step 3: 音色列表 -->
-            <div class="card-title">音色列表 <span style="font-weight: 400; color: var(--text-dim); font-size: 12px;">(至少 1 条)</span></div>
+        <div v-show="step===3" class="card">
-            <div class="card-desc">填入火山 TTS 音色 ID(S_ 开头的为复刻音色)。可后续在 /admin 中增删。</div>
+            <div class="card-head">
+                <div>
+                    <div class="card-title">音色列表 <span style="font-weight: 400; color: var(--text-dim); font-size: 12px;">(至少 1 条)</span></div>
+                    <div class="card-sub">填入火山 TTS 音色 ID(S_ 开头的为复刻音色)。可后续在 /admin 中增删。</div>
+                </div>
+                <span class="step-badge">第 3 步</span>
+            </div>
+            <div class="voice-row-head">
+                <div>对外名 (voice)</div>
+                <div>Speaker</div>
+                <div>资源 ID</div>
+                <div>Model</div>
+                <div></div>
+            </div>
             <div v-for="(v, i) in form.voices" :key="i" class="voice-row">
-                <input v-model="v.name" placeholder="对外名 qian">
+                <input v-model="v.name" placeholder="qian">
                 <input v-model="v.speaker" placeholder="S_xxx">
-                <input v-model="v.resource_id" placeholder="volc.megatts.icl">
+                <input v-model="v.resource_id" placeholder="seed-icl-2.0">
                 <input v-model="v.model" placeholder="seed-tts-2.0-standard">
                 <button class="rm" @click="removeVoice(i)" :disabled="form.voices.length <= 1" title="删除">×</button>
             </div>
             <button class="btn btn-add" @click="addVoice">+ 添加音色</button>
         </div>
 
-        <div class="actions">
+        <!-- Step 4: 确认 -->
-            <div style="color: var(--text-mute); font-size: 12px;">
+        <div v-show="step===4" class="card">
-                提交后立即进入正常模式;后续管理请访问 <code>/admin</code>。
+            <div class="card-head">
+                <div>
+                    <div class="card-title">确认安装</div>
+                    <div class="card-sub">检查以下配置,点击「完成安装」提交。提交后立即进入正常模式。</div>
+                </div>
+                <span class="step-badge">第 4 步</span>
+            </div>
+            <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 14px;">
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">OpenAI Key</div>
+                    <div style="font-family: ui-monospace, monospace; color: var(--accent); font-size: 13px;">{{ form.auth_key ? mask(form.auth_key) : '(未填)' }}</div>
+                </div>
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">火山 API Key</div>
+                    <div style="font-family: ui-monospace, monospace; color: var(--accent); font-size: 13px;">{{ form.api_key ? mask(form.api_key) : '(未填)' }}</div>
+                </div>
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">默认资源 ID</div>
+                    <div style="font-family: ui-monospace, monospace; font-size: 13px;">{{ form.default_resource_id || '—' }}</div>
+                </div>
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">默认音色</div>
+                    <div style="font-family: ui-monospace, monospace; font-size: 13px;">{{ form.default_speaker || '—' }}</div>
+                </div>
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">输出格式 / 采样率</div>
+                    <div style="font-size: 13px;">{{ form.default_format }} · {{ form.sample_rate }} Hz</div>
+                </div>
+                <div>
+                    <div style="font-size: 11px; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px;">音色数</div>
+                    <div style="font-size: 13px;">{{ form.voices.length }} 条 <span class="text-dim" style="font-size: 12px;">({{ form.voices.filter(v => v.name).length }} 已填名)</span></div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Nav -->
+        <div class="actions">
+            <button class="btn" @click="prev" :disabled="step===1 || submitting">← 上一步</button>
+            <div class="hint-text">提交后立即进入正常模式;后续管理请访问 <code>/admin</code>。</div>
+            <div style="display: flex; gap: 8px;">
+                <button v-if="step < 4" class="btn btn-primary" @click="next">下一步 →</button>
+                <button v-else class="btn btn-primary" @click="submit" :disabled="submitting">
+                    {{ submitting ? '安装中...' : '完成安装' }}
+                </button>
             </div>
-            <button class="btn btn-primary" @click="submit" :disabled="submitting">
-                {{ submitting ? '安装中...' : '完成安装' }}
-            </button>
         </div>
     </div>
 
@@ -165,27 +336,54 @@
     const { createApp, ref, onMounted } = Vue;
     createApp({
         setup() {
+            const step = ref(1);
             const form = ref({
+                auth_key: '',
                 api_key: '',
-                default_resource_id: 'volc.megatts.default',
+                default_resource_id: 'seed-icl-2.0',
                 default_speaker: '',
                 default_format: 'mp3',
                 sample_rate: 24000,
                 token: '',
-                voices: [{ name: '', speaker: '', resource_id: 'volc.megatts.icl', model: 'seed-tts-2.0-standard' }],
+                voices: [{ name: '', speaker: '', resource_id: 'seed-icl-2.0', model: 'seed-tts-2.0-standard' }],
             });
             const errorMsg = ref('');
             const submitting = ref(false);
 
             const addVoice = () => {
-                form.value.voices.push({ name: '', speaker: '', resource_id: 'volc.megatts.icl', model: 'seed-tts-2.0-standard' });
+                form.value.voices.push({ name: '', speaker: '', resource_id: 'seed-icl-2.0', model: 'seed-tts-2.0-standard' });
             };
             const removeVoice = (i) => {
                 if (form.value.voices.length > 1) form.value.voices.splice(i, 1);
             };
+            const next = () => {
+                errorMsg.value = '';
+                if (step.value === 1) {
+                    if (!form.value.auth_key || !form.value.api_key) {
+                        errorMsg.value = '请填写 OpenAI 鉴权 Key 和火山 API Key';
+                        return;
+                    }
+                } else if (step.value === 2) {
+                    if (!form.value.default_resource_id || !form.value.default_speaker || !form.value.token) {
+                        errorMsg.value = '请填写默认资源 ID、默认音色和初始化 Token';
+                        return;
+                    }
+                } else if (step.value === 3) {
+                    if (!form.value.voices.length || form.value.voices.some(v => !v.name || !v.speaker || !v.resource_id)) {
+                        errorMsg.value = '音色列表不完整(每条都需要 name + speaker + resource_id)';
+                        return;
+                    }
+                }
+                step.value = Math.min(4, step.value + 1);
+            };
+            const prev = () => { errorMsg.value = ''; step.value = Math.max(1, step.value - 1); };
+            const mask = (s) => {
+                if (!s) return '';
+                if (s.length <= 8) return '****';
+                return s.slice(0, 4) + '****' + s.slice(-4);
+            };
 
             onMounted(async () => {
-                // 预填旧 env 变量(只填非空字段;api_key 永不预填,需手动输入)
                 try {
                     const r = await axios.get('/api/setup/prefill');
                     const s = r.data.settings || {};
@@ -200,19 +398,12 @@
 
             const submit = async () => {
                 errorMsg.value = '';
-                if (!form.value.api_key || !form.value.default_resource_id || !form.value.default_speaker || !form.value.token) {
-                    errorMsg.value = '请填写所有必填项(API Key / 资源 ID / 默认音色 / Token)';
-                    return;
-                }
-                if (!form.value.voices.length || form.value.voices.some(v => !v.name || !v.speaker || !v.resource_id)) {
-                    errorMsg.value = '音色列表不完整(每条都需要 name + speaker + resource_id)';
-                    return;
-                }
                 submitting.value = true;
                 try {
                     const r = await axios.post('/api/setup', {
                         token: form.value.token,
                         settings: {
+                            auth_key: form.value.auth_key,
                             api_key: form.value.api_key,
                             default_resource_id: form.value.default_resource_id,
                             default_speaker: form.value.default_speaker,
@@ -221,16 +412,15 @@
                         },
                         voices: form.value.voices,
                     });
-                    // 成功:跳 /admin(M2 才会有,先跳 /dashboard)
+                    window.location.href = r.data.redirect || '/admin';
-                    window.location.href = r.data.redirect || '/dashboard';
                 } catch (e) {
                     const msg = e.response?.data?.error?.message || e.message;
-                    errorMsg.value = `安装失败: ${msg}`;
+                    errorMsg.value = '安装失败: ' + msg;
                     submitting.value = false;
                 }
             };
 
-            return { form, errorMsg, submitting, addVoice, removeVoice, submit };
+            return { step, form, errorMsg, submitting, addVoice, removeVoice, next, prev, mask, submit };
         },
     }).mount('#app');
     </script>

setting/config.go

@@ -17,7 +17,7 @@ import (
 
 // 全部环境变量读取的单一入口:其它包不允许直接 os.Getenv,只读这里的全局 Config。
 
-// TTSOptions 是火山 v3 TTS 调用的完整参数集合,启动期由 InitTTSConfig 填充。
+// TTSOptions 是火山 v3 TTS 调用的完整参数集合,启动期由 LoadRuntimeConfig 从 store 填充。
 // 业务侧(controller)直接读取并传入 volcano.Synthesis。
 var (
 	TTSOptions   volcano.Options
@@ -74,7 +74,7 @@ func InitAllConfigs() {
 	InitAuthConfig()
 	InitCORSConfig()
 	InitSetupToken()
-	TTSConfigErr = InitTTSConfig()
+	// InitTTSConfig 不再这里调 — 改为启动期从 store 加载(LoadRuntimeConfig)。
 }
 
 func InitServerConfig() {
@@ -127,33 +127,114 @@ func normalizeOrigin(origin string) string {
 	return strings.ToLower(origin)
 }
 
-// InitTTSConfig 读取火山 TTS 必填和可选配置,填充 TTSOptions 与 TTSTimeout。
+// SplitOriginsForCORS 解析逗号/换行/空格分隔的 origins 列表,
-// 必填项缺失时返回 error,/v1/audio/speech 路由会拒绝请求。
+// 全部小写、trim 末尾 / 后面统一比较。导出供 controller 复用
-func InitTTSConfig() error {
+// (PUT /api/settings/cors 写完立即刷新 setting.CORS 用)。
-	apiKey := os.Getenv("BYTEDANCE_TTS_API_KEY")
+func SplitOriginsForCORS(s string) []string {
-	resourceId := os.Getenv("BYTEDANCE_TTS_RESOURCE_ID")
+	return splitAndLowerOrigins(s)
-	speaker := os.Getenv("BYTEDANCE_TTS_SPEAKER")
+}
-	missing := []string{}
+
-	if apiKey == "" {
+// splitAndLowerOrigins 解析逗号/换行/空格分隔的 origins 列表,
-		missing = append(missing, "BYTEDANCE_TTS_API_KEY")
+// 全部小写、trim 末尾 / 后面统一比较(只在本包内用,外部用 SplitOriginsForCORS)。
+// 实现细节:用 strings.FieldsFunc 切分,首尾 trim,末尾去 /。
+func splitAndLowerOrigins(s string) []string {
+	parts := strings.FieldsFunc(s, func(r rune) bool {
+		return r == ',' || r == '\n' || r == ' ' || r == '\t'
+	})
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.ToLower(strings.TrimRight(strings.TrimSpace(p), "/"))
+		if p != "" {
+			out = append(out, p)
+		}
 	}
-	if resourceId == "" {
+	return out
-		missing = append(missing, "BYTEDANCE_TTS_RESOURCE_ID")
+}
-	}
+
-	if speaker == "" {
+// LoadRuntimeConfig 从 store 加载 TTS 全局配置到 TTSOptions / TTSTimeout / Auth.APIKeys 内存。
-		missing = append(missing, "BYTEDANCE_TTS_SPEAKER")
+// 启动期(master 模式)调一次,或 PUT /api/settings 后调一次(改完立即生效)。
-	}
+////
-	if len(missing) > 0 {
+// 与原 InitTTSConfig 的区别:
-		return fmt.Errorf("缺少必需的环境变量: %v", missing)
+//   - 不再读 BYTEDANCE_TTS_* env;全部从 store.Settings 读
+//   - 必填项(api_key / default_resource_id / default_speaker)缺失时返 error
+//   - 失败时 TTSConfigErr 被设置,/v1/audio/speech 路由会返 503
+//   - 成功时清空 TTSConfigErr
+//
+// 字段映射(原 env → store key):
+//   BYTEDANCE_TTS_API_KEY        → api_key
+//   BYTEDANCE_TTS_RESOURCE_ID    → default_resource_id
+//   BYTEDANCE_TTS_SPEAKER        → default_speaker
+//   BYTEDANCE_TTS_MODEL          → model
+//   BYTEDANCE_TTS_FORMAT         → default_format (默认 mp3)
+//   BYTEDANCE_TTS_SAMPLE_RATE    → sample_rate (默认 24000)
+//   BYTEDANCE_TTS_BIT_RATE       → bit_rate (默认 0)
+//   BYTEDANCE_TTS_MODEL_TYPE     → model_type (默认 0)
+//   BYTEDANCE_TTS_EXPLICIT_LANGUAGE → explicit_language
+//   BYTEDANCE_TTS_ENABLE_SUBTITLE   → enable_subtitle (默认 false)
+//   BYTEDANCE_TTS_TIMEOUT        → TTSTimeout (默认 30s)
+//
+// 鉴权 key(auth_key)优先级:DB > env OPENAI_TTS_API_KEY
+//   - 首次启动(无 DB 数据):用 env,保证向后兼容
+//   - 已 install:用 DB,env 不再读
+//   - DB 没 auth_key 但 env 有(env fallback):仍用 env
+func LoadRuntimeConfig(s Store) error {
+	all, err := s.SettingsGetAll()
+	if err != nil {
+		TTSConfigErr = fmt.Errorf("read settings failed: %w", err)
+		return TTSConfigErr
 	}
 
-	model := os.Getenv("BYTEDANCE_TTS_MODEL")
+	apiKey := all["api_key"]
-	format := getEnvDefault("BYTEDANCE_TTS_FORMAT", "mp3")
+	resourceId := all["default_resource_id"]
-	sampleRate := getEnvInt("BYTEDANCE_TTS_SAMPLE_RATE", 24000)
+	speaker := all["default_speaker"]
-	bitRate := getEnvInt("BYTEDANCE_TTS_BIT_RATE", 0)
+	missing := []string{}
-	modelType := getEnvInt("BYTEDANCE_TTS_MODEL_TYPE", 0)
+	if apiKey == "" {
-	explicitLanguage := os.Getenv("BYTEDANCE_TTS_EXPLICIT_LANGUAGE")
+		missing = append(missing, "api_key")
-	enableSubtitle := getEnvBool("BYTEDANCE_TTS_ENABLE_SUBTITLE", false)
+	}
+	if resourceId == "" {
+		missing = append(missing, "default_resource_id")
+	}
+	if speaker == "" {
+		missing = append(missing, "default_speaker")
+	}
+	if len(missing) > 0 {
+		TTSConfigErr = fmt.Errorf("missing required settings: %v", missing)
+		return TTSConfigErr
+	}
+
+	// 【BUG 修复 · 第二轮】default_speaker 是 voice **名字**(如 "chun"),
+	// 不是火山 speaker ID (如 "S_G8tEKnaJ1")。原代码直接把 voice 名当
+	// speaker ID 用,导致调 /v1/audio/speech 不传 voice 时火山 55000000。
+	//
+	// 字段优先级:
+	//   - speaker     ←  从 default_speaker 这个 voice 查表拿真 ID (必查)
+	//   - resource_id ←  settings 里的(用户偏好,不被 voice 行覆盖)
+	//   - model       ←  voice 行的优先,settings 里的次之
+	//
+	// 之前 f5563e6 把 resourceId 也覆盖了,导致用户在 setup 设的
+	// default_resource_id 永远没机会生效。这次只覆盖 speaker,不动 resourceId。
+	var voiceModel string
+	if vSpeaker, _, vModel, found, vErr := s.GetVoiceForTTS(speaker); vErr == nil && found {
+		speaker = vSpeaker
+		if vModel != "" {
+			voiceModel = vModel
+		}
+		// 找不到 voice 时不报错 — 保持原值(向后兼容)
+	}
+
+	model := all["model"]
+	if voiceModel != "" {
+		model = voiceModel // voice 行有 model 时优先用 voice 的
+	}
+	format := all["default_format"]
+	if format == "" {
+		format = "mp3"
+	}
+	sampleRate, _ := s.SettingsGetInt("sample_rate", 24000)
+	bitRate, _ := s.SettingsGetInt("bit_rate", 0)
+	modelType, _ := s.SettingsGetInt("model_type", 0)
+	explicitLanguage := all["explicit_language"]
+	enableSubtitle, _ := s.SettingsGetBool("enable_subtitle", false)
 
 	var adds *volcano.Additions
 	if modelType != 0 || explicitLanguage != "" {
@@ -168,17 +249,10 @@ func InitTTSConfig() error {
 	}
 
 	TTSTimeout = common.DefaultTimeout
-	if ts := os.Getenv("BYTEDANCE_TTS_TIMEOUT"); ts != "" {
+	if v, err := s.SettingsGetDuration("timeout", common.DefaultTimeout); err == nil {
-		if d, err := time.ParseDuration(ts); err == nil {
+		TTSTimeout = v
-			TTSTimeout = d
+	} else {
-		} else {
+		TTSTimeout = common.DefaultTimeout
-			log.Printf("无效的超时设置 %q,使用默认值 %v", ts, TTSTimeout)
-		}
-	}
-
-	common.DebugLog = getEnvBool("BYTEDANCE_TTS_DEBUG", false)
-	if common.DebugLog {
-		log.Println("调试日志已启用 BYTEDANCE_TTS_DEBUG")
 	}
 
 	TTSOptions = volcano.Options{
@@ -195,9 +269,66 @@ func InitTTSConfig() error {
 		EnableSubtitle: enableSubtitle,
 		Additions:      adds,
 	}
+
+	// 鉴权 key:DB > env(向后兼容)
+	authKey := all["auth_key"]
+	if authKey == "" {
+		authKey = os.Getenv("OPENAI_TTS_API_KEY")
+	}
+	// 用临时 slice 避免和 InitAuthConfig 抢同一个 Auth.APIKeys 底层
+	if authKey != "" {
+		Auth.APIKeys = []string{authKey}
+	} else {
+		Auth.APIKeys = nil
+	}
+
+	// CORS 配置:DB > env
+	// cors_allow_all (bool): 允许所有来源(*)
+	// cors_origins (string): 逗号分隔白名单
+	// 同源豁免由 middleware/cors.go 的 isSameOrigin 负责,DB 这里只管跨域名单
+	corsAllowAll, _ := s.SettingsGetBool("cors_allow_all", false)
+	if !corsAllowAll {
+		// env 兜底
+		if v := strings.ToLower(strings.TrimSpace(os.Getenv("CORS_ALLOW_ALL"))); v == "1" || v == "true" || v == "yes" {
+			corsAllowAll = true
+		}
+	}
+	originsStr := strings.TrimSpace(all["cors_origins"])
+	if originsStr == "" {
+		originsStr = os.Getenv("ALLOWED_ORIGINS")
+	}
+	if corsAllowAll {
+		CORS.AllowAll = true
+		CORS.Origins = nil
+	} else if originsStr != "" {
+		CORS.AllowAll = false
+		CORS.Origins = SplitOriginsForCORS(originsStr)
+	} else {
+		CORS.AllowAll = false
+		CORS.Origins = nil
+	}
+
+	TTSConfigErr = nil
 	return nil
 }
 
+// Store 是 LoadRuntimeConfig 需要的最小接口(避免 setting 包 import store 产生 cycle)。
+//
+// 重要:VoiceGetByName 用 4 个返回值(speaker/resourceID/model/found/err)
+// 而非 (VoiceRef, error),这样 store 包不需要 import setting 包
+// 就能实现这个接口(避免循环 import)。
+type Store interface {
+	SettingsGetAll() (map[string]string, error)
+	SettingsGetInt(key string, def int) (int, error)
+	SettingsGetBool(key string, def bool) (bool, error)
+	SettingsGetDuration(key string, def time.Duration) (time.Duration, error)
+	// GetVoiceForTTS 给定 voice 名字,返 (speaker_id, resource_id, model, found, err)。
+	//   - found=false 表示 voice 不存在(此时 err=nil,返回值是空串)
+	//   - err!=nil 是真错误(db 失败等)
+	//   - 找到时返 voice 行的真实字段值
+	GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error)
+}
+
 func getEnvDefault(name, def string) string {
 	if v := os.Getenv(name); v != "" {
 		return v

store/voices.go

@@ -10,17 +10,21 @@ import (
 )
 
 // Voice 是一行音色记录;时间字段保持 ISO8601 字符串(SQLite TEXT 默认)。
+//
+// JSON tag 是为了前端(admin.html)能直接读取 — 之前没加 tag 时 Go 的
+// "Name" / "Speaker" 等大写字段会原样输出,前端用 v.name 拿到 undefined,
+// 整张表看起来"空"但其实有数据。补 tag 后前端能正常显示。
 type Voice struct {
-	ID          int64
+	ID          int64  `json:"id"`
-	Name        string
+	Name        string `json:"name"`
-	Speaker     string
+	Speaker     string `json:"speaker"`
-	ResourceID  string
+	ResourceID  string `json:"resource_id"`
-	Model       string
+	Model       string `json:"model"`
-	Language    string
+	Language    string `json:"language"`
-	Description string
+	Description string `json:"description"`
-	Enabled     bool
+	Enabled     bool   `json:"enabled"`
-	CreatedAt   string
+	CreatedAt   string `json:"created_at"`
-	UpdatedAt   string
+	UpdatedAt   string `json:"updated_at"`
 }
 
 // ErrDuplicate 表示 name 唯一冲突;controller 翻译为 409。
@@ -94,6 +98,22 @@ func (s *Store) VoiceGetByName(name string) (*Voice, error) {
 	return &v, nil
 }
 
+// GetVoiceForTTS 实现 setting.Store 接口,返 voice 行的 TTS 关键字段。
+//   - found=false: voice 不存在(ErrNotFound 翻译为 found=false)
+//   - err != nil:  真错误(db 失败等)
+// 这个方法存在是为了让 *Store 满足 setting.Store 接口,且不引起
+// setting → store → setting 循环 import。
+func (s *Store) GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error) {
+	v, err := s.VoiceGetByName(name)
+	if err != nil {
+		if errors.Is(err, ErrNotFound) {
+			return "", "", "", false, nil
+		}
+		return "", "", "", false, err
+	}
+	return v.Speaker, v.ResourceID, v.Model, true, nil
+}
+
 // VoiceInsert 新增音色;name 冲突返回 ErrDuplicate。
 // 空字符串/格式不合法返回 error;不依赖 SQLite 约束作为唯一校验。
 func (s *Store) VoiceInsert(v Voice) (int64, error) {