ci(docker): 修 workflow 非法表达式, secrets 改经 job env 透传

GitHub Actions 拒绝加载本 workflow, 报:
  Invalid workflow file: .github/workflows/docker.yml#L1
  (Line: 49, Col: 13): Unrecognized named-value: 'secrets'.
  Located at position 40 within expression:
  github.event_name != 'pull_request' && secrets.DOCKERHUB_USERNAME != ''

原因: secrets 上下文不允许在 step 的 if: 表达式里引用(GitHub 沙箱限制)。
secrets 只在 with: / env: / run: 等位置可用, if: 里必须走 env 中转。

修复:
  - 新增 job 级 env: DOCKERHUB_USERNAME / DOCKERHUB_TOKEN (值来自 secrets)
  - DockerHub login step: if 改 env.DOCKERHUB_USERNAME != ''
  - DockerHub login step: username/password 改读 env.*
  - metadata-action images: DockerHub 那行改 env.DOCKERHUB_USERNAME,
    enable 判断同样改 env 上下文

副作用: 无。secret 未配置时行为不变(跳过 login + 不渲染 DockerHub image)。
已用 js-yaml 校验 YAML 结构合法, 并扫描确认全部 step 的 if: 不含 secrets 引用。

.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

.github/workflows/docker.yml

@@ -1,10 +1,20 @@
 name: Docker Publish
 
+# 触发条件:
+#   - main 上的 semver tag(v*.*.*): 推 GHCR + DockerHub
+#   - 手动按钮(workflow_dispatch): 临时跑一次
+#
+# 注意:
+#   1. 需在 GitHub 仓库 Settings → Secrets 加 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN。
+#      没加之前, DockerHub login 步骤被 actions 自动跳过, 只推 GHCR。
+#   2. secrets.DOCKERHUB_USERNAME 用于 metadata-action 渲染 image 名, 不能空 — 留空会
+#      生成 "docker.io//ttshub" 这种非法 image。已加默认值保护(空时禁用 DockerHub image)。
+#   3. 暂不验 PR 编译;PR 合到 main 不会重跑本 workflow, 只在打 tag 时构建。
 on:
   push:
     tags:
-      - 'v*'
+      - 'v*.*.*'
-  workflow_dispatch:  # 允许手动触发测试
+  workflow_dispatch:
 
 env:
   REGISTRY: ghcr.io
@@ -15,6 +25,11 @@ jobs:
     permissions:
       contents: read
       packages: write
+    # secrets 不能在 step 的 if: 表达式里直接引用(GitHub 沙箱限制),
+    # 必须先经 job 级 env 透传,再用 env.XXX != '' 判断。
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -28,12 +43,20 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Login to GHCR
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Login to DockerHub
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@v3
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+
       - name: Extract version from git
         id: version
         run: |
@@ -44,20 +67,33 @@ jobs:
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: ${{ env.REGISTRY }}/${{ github.repository }}
+          # 多个 image base:metadata-action 会为每个 base 渲染完整 tag 列表。
+          # DockerHub image 用 enable 保护:username 未配置(secret 未设)时不渲染,
+          # 避免生成 "docker.io//ttshub" 这种非法 image 名导致 metadata 步骤报错。
+          images: |
+            name=${{ env.REGISTRY }}/${{ github.repository }}
+            name=docker.io/${{ env.DOCKERHUB_USERNAME }}/ttshub,enable=${{ env.DOCKERHUB_USERNAME != '' }}
           tags: |
             type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ github.ref_type == 'tag' }}
             type=sha,format=short
           labels: |
             org.opencontainers.image.version=${{ steps.version.outputs.version }}
             org.opencontainers.image.revision=${{ steps.version.outputs.commit }}
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64
-          push: true
+          # 当前触发器只有 push (tag) + workflow_dispatch, 无 pull_request, 所以 push 永远为 true。
+          # 保留 != 'pull_request' 表达式以兼容未来:若再加 PR 触发, 自动只 build 不 push。
+          push: ${{ github.event_name != 'pull_request' }}
+          # cache-from: 复用上次构建的层(github actions 内置缓存), 快 5-10x
+          # cache-to:   本次构建的层也推回缓存, 下次复用
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |

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` 可被互联网任意访问) 时,**至少满足以下两条之一**:
-
-### ⚠️ 公网部署:监控端点无鉴权
-
-`/metrics`、`/health`、`/dashboard` **均不鉴权**,这是对齐 Prometheus 抓取场景的设计权衡:
-
-| 端点 | 暴露内容 | 风险 |
-|---|---|---|
-| `/metrics` | 业务标签(speaker/model/format)、运行指标、错误计数 | 侦察面:可推断使用量、技术栈、错误模式 |
-| `/health` | 服务状态、版本号、运行时长、内存 | 侦察面:版本号可用于匹配已知 CVE |
-| `/dashboard` | 配置检查结果(含 `TTSConfigErr` 状态) | 信息泄露:可确认配置是否就绪 |
-
-**部署建议**:
-
-- **内网 / 反代后**:无影响,符合预期
-- **公网直接暴露**:在前置反代(nginx / caddy)上保护这些端点,示例 nginx 配置:
-
-  ```nginx
-  location /metrics {
-      auth_basic "metrics";
-      auth_basic_user_file /etc/nginx/.htpasswd;
-      allow 10.0.0.0/8;        # 仅允许 Prometheus 服务器网段
-      deny all;
-  }
-  location /dashboard {
-      auth_basic "admin";
-      auth_basic_user_file /etc/nginx/.htpasswd;
-  }
-  location /health {
-      allow 10.0.0.0/8;        # 或保留给监控系统访问
-      deny all;
-  }
-  ```
-
-- **最简方案**:反代层直接限制 `/metrics` 只能从 Prometheus 服务器 IP 访问,无需 basic auth
-
-## 架构
-
-| 包 | 职责 |
-|---|---|
-| `main.go` | 启动入口,信号处理 |
-| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出(零依赖) |
-| `metrics/` | TTS 业务指标注册,火山适配器埋点适配 |
-| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端(client/request/response/audio/errors/synthesis) |
-| `controller/` | /v1/audio/speech、/health 处理器 |
-| `middleware/` | SecurityHeaders、CORS、鉴权、限流、并发、日志、客户端 IP 提取 |
-| `setting/` | 单一环境变量入口 + 启动汇总 |
-| `common/`、`dto/` | 常量、请求/响应类型,`common.DebugLog` 控制调试日志 |
-| `router/` | 路由注册 |
-
-## 部署
-
-### Linux Systemd
-
-创建 `/etc/systemd/system/tts-server.service`:
-
-```ini
-[Unit]
-Description=ByteDance TTS to OpenAI API Adapter
-After=network.target
-
-[Service]
-Type=simple
-User=www-data
-WorkingDirectory=/www/wwwroot/tts-server
-EnvironmentFile=/www/wwwroot/tts-server/.env
-ExecStart=/www/wwwroot/tts-server/tts-api
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable tts-server
-sudo systemctl start tts-server
-```
-
-### Docker
-
-```bash
-docker compose up -d
-```
-
-环境变量通过 `.env` 或 `docker-compose.yml` 传入。
-
-### 公网部署安全清单
-
-公网直接暴露(`:8080` 可被互联网任意访问)时,**至少满足以下两条之一**,否则视为不安全的部署:
 
 1. **设置 `OPENAI_TTS_API_KEY`** (推荐, 最简单)
    ```bash
-   # .env
    OPENAI_TTS_API_KEY=<32+ 位随机字符串>
    ```
    客户端请求时带 `Authorization: Bearer <那个字符串>`。
 
 2. **前置反代承担鉴权** (nginx / caddy / Cloudflare Access)
-   - 反代层做 basic auth、mTLS、Cloudflare Access 等任一方案
+   - 反代层做 basic auth / mTLS / Cloudflare Access 等任一方案
-   - 反代**仅**把鉴权后的请求转发到 `:8080`,Go 服务本身保持"无鉴权"
+   - 反代**仅**把鉴权后的请求转发到 `:8080`
    - 此时 `OPENAI_TTS_API_KEY` 可不设
 
-**两个端点还需要单独保护**(无论上面哪种方案):
+**`/metrics` / `/dashboard` / `/health` 均不鉴权**,生产环境务必通过反代保护:
 
-- `/metrics`:暴露业务标签与运行指标,详见[观测 / Metrics → 公网部署](#公网部署监控端点无鉴权)
+```nginx
-- `/dashboard`:暴露配置检查结果,同上
+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 直接访问
+```
 
-**未做保护的典型风险**:
+## 部署
-- 任意人 curl `POST /v1/audio/speech` → 消耗你火山账号的字符额度
-- 任意人 `GET /metrics` → 推断你的使用量、技术栈、错误模式
-- 任意人 `GET /dashboard` → 确认你 TTS 配置就绪状态
 
-**内网部署 / 私网反代后**:这些警示不适用,直接用就行。
+### Docker
+
+```bash
+# .env 至少含 TTS_ADMIN_KEY, 公网再加 OPENAI_TTS_API_KEY
+docker compose up -d
+```
+
+`docker-compose.yml` 已配 named volume `tts-api-data` 挂载到容器 `/data`,DB 与 lock 文件持久化,容器重启不丢配置。
+
+### Linux Systemd
+
+参见 `v0.1.0 README`,**注意**:v0.2.0 启动前不需要 `EnvironmentFile` 含业务变量,只保留 `TTS_ADMIN_KEY`。
+
+## 架构
+
+| 包 | 职责 |
+|---|---|
+| `main.go` | 启动入口,模式检测 (setup/normal),fail-fast |
+| `installer/` | 启动期模式检测,DB 自愈回退 |
+| `setting/` | 全局配置 (TTSOptions / Auth / CORS) + 启动汇总 |
+| `store/` | SQLite 数据访问 (settings / voices) + 自愈 |
+| `controller/` | /v1/audio/speech、/health、/setup、/admin、/api/setup、/api/settings、/api/voices |
+| `middleware/` | SecurityHeaders, CORS, 鉴权, 限流, 并发, 日志, 客户端 IP 提取, install 模式守卫 |
+| `router/` | 路由注册 |
+| `adapter/volcano/` | 火山 v3 HTTP Chunked 客户端 |
+| `telemetry/` | Counter / Gauge / Histogram + Prometheus 文本导出 |
+| `metrics/` | TTS 业务指标注册 |
+| `cmd/dumpdb/` | ops 工具: dump tts.db |
+| `dto/` | 请求/响应类型 |
+| `common/` | 常量 + 调试日志 |
 
 ## 常见问题
 
-### 1. `code=55000000, 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 兼容性最好)
 
 ## 许可证
 

adapter/volcano/synthesis.go

@@ -84,7 +84,7 @@ func Synthesis(
 
 	if common.DebugLog {
 		log.Printf("TTS upstream: resource_id=%s speaker=%s model=%q format=%s sample_rate=%d speech_rate=%d additions=%q",
-			opts.ResourceID, telemetry.MaskSpeaker(opts.Speaker), opts.Model, opts.Format, opts.SampleRate, opts.SpeechRate, extractAdditionsForLog(body))
+			telemetry.MaskResourceID(opts.ResourceID), telemetry.MaskSpeaker(opts.Speaker), opts.Model, opts.Format, opts.SampleRate, opts.SpeechRate, extractAdditionsForLog(body))
 	}
 
 	resp, err := client.PostStream(ctx, "https://openspeech.bytedance.com/api/v3/tts/unidirectional", headers, body)

cmd/dumpdb/main.go

@@ -11,6 +11,7 @@ import (
 	"database/sql"
 	"fmt"
 	"os"
+	"strings"
 
 	_ "modernc.org/sqlite"
 )
@@ -116,15 +117,14 @@ func main() {
 }
 
 func isSensitive(key string) bool {
-	lowK := key
+	// 标记 key 名包含 "key" / "token" / "speaker" 即视为敏感,值打码。
-	// 简单 contains (不引 strings 包保持精简)
+	// 大小写不敏感: API_KEY / Auth_Token 等大写 key 也会被命中
-	markers := []string{"key", "token", "speaker"}
+	// (避免漏打码)。
-	for _, m := range markers {
+	low := strings.ToLower(key)
-		for i := 0; i+len(m) <= len(lowK); i++ {
+	for _, m := range []string{"key", "token", "speaker"} {
-			if lowK[i:i+len(m)] == m {
+		if strings.Contains(low, m) {
 			return true
 		}
 	}
-	}
 	return false
 }

controller/admin.go

@@ -2,9 +2,11 @@ package controller
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log"
 	"net/http"
+	"strings"
 	"sync"
 	"time"
 
@@ -191,14 +193,23 @@ func AdminVoiceCreateHandler(w http.ResponseWriter, r *http.Request) {
 	}
 	id, err := s.VoiceInsert(v)
 	if err != nil {
-		switch err {
+		switch {
-		case store.ErrDuplicate:
+		case err == store.ErrDuplicate:
 			middleware.SendJSONError(w, http.StatusConflict,
 				fmt.Sprintf("voice name %q already exists", v.Name),
 				"invalid_request_error", "voice_duplicate")
+		case errors.Is(err, store.ErrInvalid):
+			// 客户端输入不合法(name 格式 / speaker / resource_id 缺失):400。
+			// 走 ErrInvalid 哨兵 + 原始 detail,前端可以直接显示。
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				stripInvalidPrefix(err.Error()),
+				"invalid_request_error", "voice_invalid")
 		default:
+			// 兜底:DB 连接失败 / Exec 错误 / LastInsertId 失败等都是服务端问题,
+			// 返 500 + 通用 message,详细 err 走日志(不直接暴露给前端,避免信息泄漏)。
 			log.Printf("[admin] voice insert: %v", err)
-			middleware.SendJSONError(w, http.StatusBadRequest, err.Error(), "invalid_request_error", "voice_invalid")
+			middleware.SendJSONError(w, http.StatusInternalServerError,
+				"failed to insert voice", "server_error", "voice_insert_failed")
 		}
 		return
 	}
@@ -299,3 +310,14 @@ func AdminVoiceToggleHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	_ = json.NewEncoder(w).Encode(updated)
 }
+
+// stripInvalidPrefix 把 wrap 后的 ErrInvalid 错误字符串中的 "store: voice invalid: " 前缀剥掉,
+// 只保留底层 detail(例如 "speaker is required"),让前端能直接展示用户友好文案。
+// 如果上游 wrap 形态变化(没匹配到前缀),原样返回,避免误删关键信息。
+func stripInvalidPrefix(s string) string {
+	const prefix = "store: voice invalid: "
+	if strings.HasPrefix(s, prefix) {
+		return s[len(prefix):]
+	}
+	return s
+}

controller/settings.go

@@ -121,7 +121,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 	// 收集要更新的键值对
 	updates := make(map[string]string)
 	if body.DefaultResourceID != nil {
-		v := trimAll(*body.DefaultResourceID)
+		v := strings.TrimSpace(*body.DefaultResourceID)
 		if v == "" {
 			middleware.SendJSONError(w, http.StatusBadRequest, "default_resource_id cannot be empty", "invalid_request_error", "missing_field")
 			return
@@ -129,7 +129,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["default_resource_id"] = v
 	}
 	if body.DefaultSpeaker != nil {
-		v := trimAll(*body.DefaultSpeaker)
+		v := strings.TrimSpace(*body.DefaultSpeaker)
 		if v == "" {
 			middleware.SendJSONError(w, http.StatusBadRequest, "default_speaker cannot be empty", "invalid_request_error", "missing_field")
 			return
@@ -144,7 +144,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["default_speaker"] = v
 	}
 	if body.DefaultFormat != nil {
-		v := trimAll(*body.DefaultFormat)
+		v := strings.TrimSpace(*body.DefaultFormat)
 		if !isValidFormat(v) {
 			middleware.SendJSONError(w, http.StatusBadRequest,
 				fmt.Sprintf("default_format %q invalid; valid: mp3/wav/opus/pcm/aac/flac", v),
@@ -163,13 +163,13 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["sample_rate"] = strconv.Itoa(v)
 	}
 	if body.Model != nil {
-		updates["model"] = trimAll(*body.Model)
+		updates["model"] = strings.TrimSpace(*body.Model)
 	}
 	if body.ModelType != nil {
 		updates["model_type"] = strconv.Itoa(*body.ModelType)
 	}
 	if body.ExplicitLanguage != nil {
-		updates["explicit_language"] = trimAll(*body.ExplicitLanguage)
+		updates["explicit_language"] = strings.TrimSpace(*body.ExplicitLanguage)
 	}
 	if body.EnableSubtitle != nil {
 		updates["enable_subtitle"] = boolToStr(*body.EnableSubtitle)
@@ -232,7 +232,7 @@ func SettingsAPIKeyHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	key := trimAll(body.APIKey)
+	key := strings.TrimSpace(body.APIKey)
 	if key == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest, "api_key cannot be empty", "invalid_request_error", "missing_field")
 		return
@@ -261,7 +261,7 @@ type SettingsAuthKeyRequest struct {
 }
 
 // SettingsAuthKeyHandler PUT /api/settings/auth-key
-// 鉴权: RequireAdmin。改完立即更新 setting.Auth.APIKeys(进程内生效),
+// 鉴权: RequireAdmin。改完立即刷新鉴权 key 列表(setting.SetAuthAPIKeys,进程内生效),
 // 下一个请求就用新 key — admin 自己改完要等下一次请求才能验证(避免改完立刻自踢)。
 func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPut {
@@ -280,7 +280,7 @@ func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	key := trimAll(body.AuthKey)
+	key := strings.TrimSpace(body.AuthKey)
 	if key == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest, "auth_key cannot be empty", "invalid_request_error", "missing_field")
 		return
@@ -292,23 +292,24 @@ func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 	}
 	// 立即生效:不重新 LoadRuntimeConfig(那会覆盖其它字段),
 	// 只单独刷新 Auth.APIKeys
-	setting.Auth.APIKeys = []string{key}
+	setting.SetAuthAPIKeys([]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 失效
+//   - allow_all 指针: nil=未传(不动)  *true=开 *false=关
-//   - origins: 一行一个 origin,后端 trim + lower + 去末尾 /
+//   - origins  字符串: nil=未传(不动)  ""=传空串(清空)  "url1\nurl2"=覆盖
+// 这样用户能精确表达意图(保留 / 改 / 清空),不会被 0/"" 歧义坑死。
 type SettingsCORSRequest struct {
 	AllowAll *bool   `json:"allow_all,omitempty"`
-	Origins  string `json:"origins,omitempty"` // 也接受 string 数组(任一形式)
+	Origins  *string `json:"origins,omitempty"` // *string 区分"未传(nil)"和"传空串"
 }
 
 // SettingsCORSHandler PUT /api/settings/cors
-// 鉴权: RequireAdmin。改完立即更新 setting.CORS(进程内生效,跨域请求从下个请求开始按新配置)。
+// 鉴权: RequireAdmin。改完立即刷新 CORS(setting.SetCORS,进程内生效,跨域请求从下个请求开始按新配置)。
 // 同源豁免由 middleware/cors.go 的 isSameOrigin 处理,不在这里管。
 func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPut {
@@ -327,10 +328,9 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	if body.AllowAll == nil && trimAll(body.Origins) == "" && body.Origins != "" {
+	// 至少要给一个字段(allow_all 或 origins)
-		// 空 body 不算错误,用户可能是想"清空"(只清 origins 保留现状)
+	// 指针为 nil 表示"未传",不计入
-	}
+	if body.AllowAll == nil && body.Origins == nil {
-	if body.AllowAll == nil && body.Origins == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest,
 			"at least one of allow_all / origins required",
 			"invalid_request_error", "no_fields")
@@ -341,9 +341,12 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 	if body.AllowAll != nil {
 		updates["cors_allow_all"] = boolToStr(*body.AllowAll)
 	}
-	if body.Origins != "" {
+	if body.Origins != nil {
-		// 校验每个 origin 至少像 http(s)://... (防止用户填空或填乱字符)
+		// *Origins == "" 表示用户要清空(保留 nil 表示"不动")
-		for _, line := range strings.Split(body.Origins, "\n") {
+		origins := *body.Origins
+		if origins != "" {
+			// 校验每个 origin 至少像 http(s)://... (防止用户填乱字符)
+			for _, line := range strings.Split(origins, "\n") {
 				line = strings.TrimSpace(line)
 				if line == "" {
 					continue
@@ -356,7 +359,9 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 					return
 				}
 			}
-		updates["cors_origins"] = body.Origins
+		}
+		// 空串也能存(表示"清空");trim/lower 在 LoadRuntimeConfig 那侧做
+		updates["cors_origins"] = origins
 	}
 	if err := s.SettingsSetBatch(updates); err != nil {
 		log.Printf("[settings] cors set: %v", err)
@@ -364,7 +369,7 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// 立即刷新 setting.CORS,跨域请求从下个请求开始按新配置生效
+	// 立即刷新 CORS(setting.SetCORS),跨域请求从下个请求开始按新配置生效
 	// 复用 LoadRuntimeConfig 的解析逻辑(只取 cors 部分,避免覆盖其它运行时字段)
 	corsAllowAll, _ := s.SettingsGetBool("cors_allow_all", false)
 	originsStr := ""
@@ -372,20 +377,17 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		originsStr = v
 	}
 	if corsAllowAll {
-		setting.CORS.AllowAll = true
+		setting.SetCORS(true, nil)
-		setting.CORS.Origins = nil
 	} else if originsStr != "" {
-		setting.CORS.AllowAll = false
+		setting.SetCORS(false, setting.SplitOriginsForCORS(originsStr))
-		setting.CORS.Origins = setting.SplitOriginsForCORS(originsStr)
 	} else {
-		setting.CORS.AllowAll = false
+		setting.SetCORS(false, nil)
-		setting.CORS.Origins = nil
 	}
-	log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.CORS.AllowAll, originsStr)
+	log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.GetCORSAllowAll(), 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,
+		"allow_all":    setting.GetCORSAllowAll(),
 		"origins":      originsStr,
 		"cors_active":  true,
 	})
@@ -404,18 +406,6 @@ func maskAPIKeyField(s string) string {
 	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", "":

controller/setup.go

@@ -2,6 +2,7 @@ package controller
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log"
 	"net/http"
@@ -163,17 +164,62 @@ func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 	}
 	settingsKV["initialized"] = "1"
 	settingsKV["installed_at"] = time.Now().UTC().Format(time.RFC3339)
-	if err := s.SettingsSetBatch(settingsKV); err != nil {
+
-		log.Printf("[setup] 写 settings 失败: %v", err)
+	// 【修复】原版先写 settings 再循环插 voice,任一 voice 失败时已写入的
-		middleware.SendJSONError(w, http.StatusInternalServerError, "failed to write settings", "server_error", "db_write_failed")
+	// settings 不回滚 → db 处于半残状态(用户重启还要踩"已装但配置不完整"的坑)。
+	// 改用 store.SetupApply 一次性事务:settings + voices 任一失败整体回滚,
+	// db 保持 setup 前的状态(无脏数据)。
+	//
+	// 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。
+	voices := make([]store.Voice, 0, len(body.Voices))
+	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)
+		}
+		voices = append(voices, store.Voice{
+			Name:       v.Name,
+			Speaker:    v.Speaker,
+			ResourceID: voiceResourceID,
+			Model:      v.Model,
+			Language:   v.Language,
+			Enabled:    true,
+		})
+	}
+
+	// 预检 voices 数量(避免空提交也走事务);setup 校验已要求至少 1 条,
+	// 防御性兜底。
+	if len(voices) == 0 {
+		middleware.SendJSONError(w, http.StatusBadRequest,
+			"at least one voice is required", "invalid_request_error", "no_voices")
 		return
 	}
 
-	// 立即把 auth_key 灌到 setting.Auth.APIKeys,这样后续 /v1/audio/speech 和 /admin
+	inserted, err := s.SetupApply(settingsKV, voices)
-	// 在本进程内能立刻用新 key(无需等 LoadRuntimeConfig)。
+	if err != nil {
+		log.Printf("[setup] 提交失败,事务回滚 - 错误=%v", err)
+		// 区分客户端/服务端错误,沿用 admin.go 的 400/500 模式
+		if errors.Is(err, store.ErrInvalid) {
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				err.Error(), "invalid_request_error", "voice_invalid")
+			return
+		}
+		middleware.SendJSONError(w, http.StatusInternalServerError,
+			fmt.Sprintf("failed to apply setup: %v", err),
+			"server_error", "db_write_failed")
+		return
+	}
+
+	// 立即把 auth_key 灌到鉴权 key 列表(setting.SetAuthAPIKeys),这样后续
+	// /v1/audio/speech 和 /admin 在本进程内能立刻用新 key(无需等 LoadRuntimeConfig)。
 	authKey := strings.TrimSpace(body.Settings["auth_key"])
 	if authKey != "" {
-		setting.Auth.APIKeys = []string{authKey}
+		setting.SetAuthAPIKeys([]string{authKey})
 	}
 
 	// 装完 reload TTS 全局配置(让 TTSOptions 立即有可用的 api_key/speaker/resource_id,
@@ -182,49 +228,7 @@ func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 		log.Printf("[setup] warning: 装完 LoadRuntimeConfig 失败: %v(下次启动会恢复)", err)
 	}
 
-	// 清空旧 voices 再插入(假设是首次安装;若不是,name 冲突会变成 409)
+	log.Printf("[setup] 写入 settings=%d, voices=%d/%d (事务原子提交)", len(settingsKV), inserted, len(voices))
-	// 这里选择 "清空+插入" 语义,符合"setup 是首次安装"的产品定位
-	// 如果想保留旧 voices,可以改成 UPSERT,但 M1 不做
-	if existing, _ := s.VoiceList(true); len(existing) > 0 {
-		// 留作未来:如果是非首次 setup(M2 加 reset 功能),这里需要更精细处理
-		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: voiceResourceID,
-			Model:      v.Model,
-			Language:   v.Language,
-			Enabled:    true,
-		})
-		if err != nil {
-			log.Printf("[setup] 插入 voice %q 失败: %v", v.Name, err)
-			// 不回滚 settings(用户重启后会重新 setup)
-			// 但已插入的 voices 会留着,下次 setup 会撞 ErrDuplicate
-			// 安全:把 ErrDuplicate 视作可继续(用户重复 setup 同一组 voice)
-			if err == store.ErrDuplicate {
-				continue
-			}
-			middleware.SendJSONError(w, http.StatusInternalServerError,
-				fmt.Sprintf("failed to insert voice %q: %v", v.Name, err),
-				"server_error", "voice_insert_failed")
-			return
-		}
-		inserted++
-	}
-	log.Printf("[setup] 写入 settings=%d, voices=%d/%d", len(settingsKV), inserted, len(body.Voices))
 
 	// 写 lock(原子):从这一刻起,/api/setup 永久关闭
 	if err := installer.CreateLock(GetSetupDBPath()); err != nil {

controller/tts.go

@@ -40,7 +40,7 @@ func truncateForLog(b []byte, max int) string {
 }
 
 // resolveClientFormat 把 OpenAI 风格的 response_format 映射为最终输出格式;
-// 不识别或未指定时回退到 setting.TTSOptions.Format。
+// 不识别或未指定时回退到 setting.GetTTSOptions().Format。
 func resolveClientFormat(reqFmt string) string {
 	switch strings.ToLower(reqFmt) {
 	case "mp3", "wav", "opus", "pcm", "aac", "flac":
@@ -49,7 +49,7 @@ func resolveClientFormat(reqFmt string) string {
 		}
 		return strings.ToLower(reqFmt)
 	}
-	return setting.TTSOptions.Format
+	return setting.GetTTSOptions().Format
 }
 
 // OpenaiTTSHandler 是 /v1/audio/speech 的入口。
@@ -81,9 +81,9 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if setting.TTSConfigErr != nil {
+	if err := setting.GetTTSConfigErr(); err != nil {
 		log.Printf("警告: TTS配置未就绪,拒绝请求 - 错误=%v 路径=%s 客户端=%s",
-			setting.TTSConfigErr, r.URL.Path, middleware.GetClientIP(r))
+			err, r.URL.Path, middleware.GetClientIP(r))
 		middleware.SendJSONError(w, http.StatusServiceUnavailable, "TTS service configuration error. Please check environment variables and restart the service.", "configuration_error", "service_unavailable")
 		return
 	}
@@ -151,7 +151,7 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 
 	clientFormat := resolveClientFormat(req.ResponseFormat)
 
-	opts := setting.TTSOptions
+	opts := setting.GetTTSOptions()
 	opts.Text = req.Input
 
 	// M3: voice 路由
@@ -172,9 +172,9 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 		v, err := s.VoiceGetByName(req.Voice)
 		if err != nil {
 			if err == store.ErrNotFound {
-				log.Printf("警告: 未知 voice=%s - 路径=%s 客户端=%s", req.Voice, r.URL.Path, middleware.GetClientIP(r))
+				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),
+					fmt.Sprintf("unknown voice: '%s'", req.Voice),
 					"invalid_request_error", "unknown_voice")
 				return
 			}
@@ -183,17 +183,24 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 				"voice lookup failed", "server_error", "db_read_failed")
 			return
 		}
-		// 覆盖 opts(API key / UID 保留自 setting.TTSOptions)
+		// 覆盖 opts(API key / UID 保留自 setting.GetTTSOptions 快照)
+		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))
+			req.Voice, telemetry.MaskSpeaker(v.Speaker), telemetry.MaskResourceID(v.ResourceID), v.Model, middleware.GetClientIP(r))
 	}
 
-	ctx, cancel := context.WithTimeout(r.Context(), setting.TTSTimeout)
+	ctx, cancel := context.WithTimeout(r.Context(), setting.GetTTSTimeout())
 	defer cancel()
 
 	result, err := volcano.Synthesis(ctx, volcanoClient, opts, req.Input, clientFormat, speed, adapterRec)
@@ -225,7 +232,11 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Length", fmt.Sprintf("%d", len(result.AudioData)))
 	w.Header().Set("X-Request-Id", result.ReqID)
 	w.WriteHeader(http.StatusOK)
-	w.Write(result.AudioData)
+	if n, err := w.Write(result.AudioData); err != nil {
+		// header 已发,无法改 status code;只记日志供排查(常见:客户端中途断开 → broken pipe / connection reset)
+		log.Printf("警告: 响应写入失败 - 路径=%s 客户端=%s 已写=%d/%d 错误=%v",
+			r.URL.Path, middleware.GetClientIP(r), n, len(result.AudioData), err)
+	}
 }
 
 func classifyStatus(err error) string {
@@ -271,7 +282,7 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	mode := installer.GetMode()
 	if mode == installer.ModeSetup {
 		w.WriteHeader(http.StatusOK) // 200,因为进程活着,只是还没初始化
-	} else if setting.TTSConfigErr != nil {
+	} else if setting.GetTTSConfigErr() != nil {
 		w.WriteHeader(http.StatusServiceUnavailable)
 	} else {
 		w.WriteHeader(http.StatusOK)
@@ -297,7 +308,8 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 		Memory:    collectMemorySnapshot(),
 		ConfigStatus: dto.ConfigStatusResponse{
 			AllRequiredVarsSet: allRequired,
-			ConfigError:        setting.TTSConfigErr != nil,
+			ConfigError:        setting.GetTTSConfigErr() != nil,
+			Error:              configErrorMessage(setting.GetTTSConfigErr()),
 		},
 		Installed: mode == installer.ModeNormal,
 		Mode:      mode.String(),
@@ -305,6 +317,15 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(resp)
 }
 
+// configErrorMessage 把运行时配置错误(setting.GetTTSConfigErr())安全地转成可对外暴露的字符串。
+// 仅在 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

@@ -20,4 +20,6 @@ type HealthResponse struct {
 type ConfigStatusResponse struct {
 	AllRequiredVarsSet bool   `json:"all_required_vars_set"`
 	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。
@@ -58,12 +59,27 @@ func main() {
 
 	// 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 {
-			log.Printf("[main] TTS 运行时配置加载失败:%v", err)
+			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 {
+			opts := setting.GetTTSOptions()
 			log.Printf("[main] TTS 运行时配置已加载(api_key=***, speaker=%s, resource=%s, format=%s)",
-				setting.TTSOptions.Speaker, setting.TTSOptions.ResourceID, setting.TTSOptions.Format)
+				telemetry.MaskSpeaker(opts.Speaker), telemetry.MaskResourceID(opts.ResourceID), opts.Format)
 		}
 	}
 

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/admin_auth.go

@@ -15,7 +15,7 @@ import (
 //   - Authorization 头 Bearer token 在列表中 → 放行
 //   - 其它 → 401 + JSON {error: 'unauthorized', code: 'admin_auth_failed'}
 //
-// 设计: 与现有 /v1/audio/speech 用的 setting.Auth 共享同一份 keys,
+// 设计: 与现有 /v1/audio/speech 用的鉴权 key 列表(setting.GetAuthAPIKeys)共享同一份 keys,
 // 用户只用管一个 env 变量(OPENAI_TTS_API_KEY)。
 func RequireAdmin(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -25,7 +25,7 @@ func RequireAdmin(next http.Handler) http.Handler {
 			return
 		}
 
-		keys := setting.Auth.APIKeys
+		keys := setting.GetAuthAPIKeys()
 		if len(keys) == 0 {
 			// 没配 admin key,等同无鉴权
 			next.ServeHTTP(w, r)

middleware/auth.go

@@ -10,7 +10,8 @@ import (
 )
 
 func ValidateAPIKey(r *http.Request) bool {
-	if len(setting.Auth.APIKeys) == 0 {
+	keys := setting.GetAuthAPIKeys()
+	if len(keys) == 0 {
 		return true
 	}
 
@@ -24,7 +25,7 @@ func ValidateAPIKey(r *http.Request) bool {
 	}
 
 	token := strings.TrimPrefix(authHeader, "Bearer ")
-	for _, validKey := range setting.Auth.APIKeys {
+	for _, validKey := range keys {
 		if subtle.ConstantTimeCompare([]byte(token), []byte(validKey)) == 1 {
 			return true
 		}

middleware/cors.go

@@ -29,11 +29,11 @@ func matchOrigin(origin string) (string, bool) {
 	if !isValidOrigin(origin) {
 		return "", false
 	}
-	if setting.CORS.AllowAll {
+	if setting.GetCORSAllowAll() {
 		return "*", true
 	}
 	normalized := strings.ToLower(strings.TrimRight(strings.TrimSpace(origin), "/"))
-	for _, allowed := range setting.CORS.Origins {
+	for _, allowed := range setting.GetCORSOrigins() {
 		if allowed == normalized {
 			return origin, true
 		}
@@ -148,7 +148,7 @@ func CORS(next http.Handler) http.Handler {
 
 		// Origin 匹配:设置 CORS 响应头
 		w.Header().Set("Access-Control-Allow-Origin", allowOrigin)
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
 		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
 		w.Header().Set("Access-Control-Expose-Headers", "X-Request-Id")
 		w.Header().Set("Access-Control-Max-Age", corsMaxAgeHeader)

middleware/ratelimit.go

@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -128,11 +129,32 @@ func (rl *RateLimiter) cleanup() {
 
 	if len(rl.requests) > common.MaxRateLimiterEntries {
 		log.Printf("警告: 限流器条目数 %d 超过上限 %d，触发强制清理", len(rl.requests), common.MaxRateLimiterEntries)
-		for k := range rl.requests {
+		// 【修复】原版用 `for k := range rl.requests` 删,Go map 遍历顺序随机,
+		// 会随机删掉活跃用户(其条目 timestamp 仍在窗口内),导致该用户下次请求
+		// 拿到新配额 — 攻击者可用大量伪造 IP 撑爆 map 触发清理,反而"清洗"
+		// 自己留的活跃条目,绕过限流。
+		// 修复:按"最近一次请求时间(lastTs)"升序排序,删最旧的(最可能已离开/低频),
+		// 保留最活跃用户,语义符合"限流器只淘汰冷条目"的预期。
+		// 排序复杂度 O(n log n),但只在超 10w 条目时触发,代价可接受。
+		type entry struct {
+			key    string
+			lastTs time.Time
+		}
+		entries := make([]entry, 0, len(rl.requests))
+		for k, v := range rl.requests {
+			// 走到这里 v 一定非空(cleanup 第一阶段会把空 timestamps 删掉),
+			// 取最后一个 timestamp 作为"最近活跃时间"。
+			lastTs := v[len(v)-1]
+			entries = append(entries, entry{key: k, lastTs: lastTs})
+		}
+		sort.Slice(entries, func(i, j int) bool {
+			return entries[i].lastTs.Before(entries[j].lastTs)
+		})
+		for _, e := range entries {
 			if len(rl.requests) <= common.MaxRateLimiterEntries/2 {
 				break
 			}
-			delete(rl.requests, k)
+			delete(rl.requests, e.key)
 		}
 	}
 }

router/admin-login.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>管理后台 · 登录</title>
+    <script src="https://cdn.bootcdn.net/ajax/libs/vue/3.4.21/vue.global.prod.js"></script>
+    <script src="https://cdn.bootcdn.net/ajax/libs/axios/1.6.7/axios.min.js"></script>
+    <link rel="stylesheet" href="/admin/admin.css">
+</head>
+<body>
+    <div id="app">
+        <div class="login-screen">
+            <div class="login-card">
+                <div class="login-logo">TTS</div>
+                <h1>管理后台</h1>
+                <div class="sub">输入 OPENAI_TTS_API_KEY 登录</div>
+                <input v-model="keyInput" type="password" placeholder="API Key" @keyup.enter="onLogin" autofocus class="login-input">
+                <button class="btn btn-primary btn-lg" @click="onLogin" :disabled="!keyInput" style="width: 100%;">登 录</button>
+                <div v-if="loginErr" class="login-err">⚠ {{ loginErr }}</div>
+            </div>
+        </div>
+    </div>
+
+    <script src="/admin/admin-shell.js"></script>
+    <script>
+    const { createApp, ref } = Vue;
+    const { http, setKey, clearKey, getKey } = window.admin;
+    createApp({
+        setup() {
+            const keyInput = ref('');
+            const loginErr = ref('');
+
+            // 已登录则直接跳 dashboard
+            if (getKey()) {
+                http.get('/admin/overview').then(() => {
+                    location.href = '/admin';
+                }).catch(() => { clearKey(); });
+            }
+
+            const onLogin = async () => {
+                loginErr.value = '';
+                try {
+                    await window.admin.login(keyInput.value);
+                    location.href = '/admin';
+                } catch (e) {
+                    loginErr.value = '鉴权失败: ' + (e.response?.data?.error?.message || e.message);
+                }
+            };
+
+            return { keyInput, loginErr, onLogin };
+        },
+    }).mount('#app');
+    </script>
+</body>
+</html>

router/admin-settings.html

@@ -0,0 +1,270 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>火山 TTS · 系统设置</title>
+    <script src="https://cdn.bootcdn.net/ajax/libs/vue/3.4.21/vue.global.prod.js"></script>
+    <script src="https://cdn.bootcdn.net/ajax/libs/axios/1.6.7/axios.min.js"></script>
+    <link rel="stylesheet" href="/admin/admin.css">
+</head>
+<body>
+    <div id="app">
+        <div class="app-shell">
+            <aside id="admin-sidebar"></aside>
+
+            <main class="main">
+                <header class="page-head">
+                    <div>
+                        <h1 class="page-title">系统设置</h1>
+                        <p class="page-sub">鉴权、上游凭证、默认路由与跨域</p>
+                    </div>
+                </header>
+
+                <div v-if="settings && !settings.cors_configured" class="alert alert-warning">
+                    <span class="alert-icon">⚠</span>
+                    <div class="alert-body">
+                        <div class="alert-title">跨域 CORS 未配置</div>
+                        <div class="alert-desc">同源可用,跨域请求会被 403。在下方「跨域 CORS」卡片中配置允许的来源。</div>
+                    </div>
+                </div>
+
+                <div class="settings-grid">
+                    <div class="card">
+                        <div class="card-head">
+                            <div>
+                                <div class="card-title">鉴权 Key</div>
+                                <div class="card-sub">客户端调用 <code>/v1/audio/speech</code> 与登录 /admin 共用</div>
+                            </div>
+                            <span class="pill pill-accent">敏感</span>
+                        </div>
+                        <div class="field">
+                            <label>当前 Key</label>
+                            <div class="input-static">{{ settings.auth_key || '(未设置)' }}</div>
+                        </div>
+                        <div class="field">
+                            <label>替换为新 Key</label>
+                            <div class="input-group">
+                                <input type="password" v-model="authKeyInput" :placeholder="settings.auth_key_set ? '不改留空' : '输入新 Key'">
+                                <button class="btn btn-primary" @click="saveAuthKey" :disabled="!authKeyInput">更新</button>
+                            </div>
+                            <div class="hint">改了之后,你的浏览器 401 自动跳回登录页,用新 Key 重登。</div>
+                        </div>
+                    </div>
+
+                    <div class="card">
+                        <div class="card-head">
+                            <div>
+                                <div class="card-title">火山 TTS 上游凭证</div>
+                                <div class="card-sub">调火山 v3 上游用的凭证与默认路由</div>
+                            </div>
+                        </div>
+                        <div class="field">
+                            <label>当前 API Key</label>
+                            <div class="input-static">{{ settings.api_key || '(未设置)' }}</div>
+                        </div>
+                        <div class="field">
+                            <label>替换为新 API Key</label>
+                            <div class="input-group">
+                                <input type="password" v-model="apiKeyInput" :placeholder="settings.api_key_set ? '不改留空' : '输入新 API Key'">
+                                <button class="btn btn-primary" @click="saveApiKey" :disabled="!apiKeyInput">更新</button>
+                            </div>
+                            <div class="hint">独立端点 PUT /api/settings/api-key,与其他字段分开传输</div>
+                        </div>
+                        <div class="divider"></div>
+                        <div class="grid-2">
+                            <div class="field">
+                                <label>默认资源 ID</label>
+                                <input v-model="settingsForm.default_resource_id" placeholder="seed-icl-2.0">
+                            </div>
+                            <div class="field">
+                                <label>默认音色 (name)</label>
+                                <select v-model="settingsForm.default_speaker">
+                                    <option value="">— 选择 —</option>
+                                    <option v-for="v in voices" :key="v.name" :value="v.name">{{ v.name }}</option>
+                                </select>
+                                <div class="hint">必须是「音色」tab 里存在的 name</div>
+                            </div>
+                            <div class="field">
+                                <label>默认输出格式</label>
+                                <select v-model="settingsForm.default_format">
+                                    <option value="mp3">mp3</option>
+                                    <option value="wav">wav</option>
+                                    <option value="opus">opus (ogg_opus)</option>
+                                    <option value="pcm">pcm</option>
+                                    <option value="aac">aac</option>
+                                    <option value="flac">flac</option>
+                                </select>
+                            </div>
+                            <div class="field">
+                                <label>采样率 (Hz)</label>
+                                <input type="number" v-model.number="settingsForm.sample_rate" min="8000" max="48000" step="1000">
+                            </div>
+                            <div class="field" style="grid-column: 1 / -1;">
+                                <label>Model (可选)</label>
+                                <input v-model="settingsForm.model" placeholder="seed-tts-2.0-standard">
+                            </div>
+                        </div>
+                        <div class="actions">
+                            <button class="btn" @click="resetSettingsForm">重置</button>
+                            <button class="btn btn-primary" @click="saveSettings" :disabled="savingSettings">{{ savingSettings ? '保存中...' : '保存设置' }}</button>
+                        </div>
+                    </div>
+
+                    <div class="card">
+                        <div class="card-head">
+                            <div>
+                                <div class="card-title">跨域 CORS</div>
+                                <div class="card-sub">控制哪些前端域名能跨域调 <code>/v1/audio/speech</code></div>
+                            </div>
+                            <span class="pill" :class="settings.cors_configured ? 'pill-success' : 'pill-mute'">
+                                <span class="pill-dot"></span>
+                                {{ settings.cors_configured ? '已配置' : '未配置' }}
+                            </span>
+                        </div>
+                        <div class="field">
+                            <label class="check">
+                                <input type="checkbox" v-model="corsForm.allow_all">
+                                <span>允许所有来源 (<code>*</code>)</span>
+                            </label>
+                            <div class="hint">勾上后下面白名单失效。仅测试用</div>
+                        </div>
+                        <div class="field" v-if="!corsForm.allow_all">
+                            <label>允许的来源</label>
+                            <textarea v-model="corsForm.origins" rows="4" placeholder="https://app.example.com&#10;https://admin.example.com" class="textarea"></textarea>
+                            <div class="hint">一行一个。当前: <span class="text-accent mono">{{ corsCurrentLabel }}</span></div>
+                        </div>
+                        <div class="actions">
+                            <button class="btn btn-primary" @click="saveCors" :disabled="savingCors">{{ savingCors ? '保存中...' : '保存 CORS' }}</button>
+                        </div>
+                    </div>
+                </div>
+            </main>
+        </div>
+    </div>
+
+    <script src="/admin/admin-shell.js"></script>
+    <script>
+    const { createApp, ref, computed, onMounted } = Vue;
+    const { http, getKey, setKey, clearKey, toast, mountShell } = window.admin;
+    createApp({
+        setup() {
+            const overview = ref({});
+            const voices = ref([]);
+            const settings = ref({});
+            const settingsForm = ref({ default_resource_id: '', default_speaker: '', default_format: 'mp3', sample_rate: 24000, model: '' });
+            const apiKeyInput = ref('');
+            const authKeyInput = ref('');
+
+            const corsForm = ref({ allow_all: false, origins: '' });
+            const savingCors = ref(false);
+            const corsCurrentLabel = computed(() => {
+                if (!settings.value) return '未配置';
+                if (settings.value.cors_allow_all) return '允许所有来源(*)';
+                if (settings.value.cors_origins) return settings.value.cors_origins;
+                return '未配置(同源可用,跨域会被 403)';
+            });
+
+            const savingSettings = ref(false);
+
+            const loadSettings = async () => {
+                const r = await http.get('/settings');
+                settings.value = r.data;
+                settingsForm.value = {
+                    default_resource_id: r.data.default_resource_id || '',
+                    default_speaker: r.data.default_speaker || '',
+                    default_format: r.data.default_format || 'mp3',
+                    sample_rate: r.data.sample_rate || 24000,
+                    model: r.data.model || '',
+                };
+                corsForm.value = {
+                    allow_all: !!r.data.cors_allow_all,
+                    origins: r.data.cors_origins || '',
+                };
+            };
+            const loadVoices = async () => {
+                const r = await http.get('/voices');
+                voices.value = r.data.voices || [];
+            };
+            const loadOverview = async () => {
+                overview.value = (await http.get('/admin/overview')).data;
+            };
+            const reloadAll = () => { loadSettings(); loadVoices(); loadOverview(); };
+
+            const saveCors = async () => {
+                savingCors.value = true;
+                try {
+                    await http.put('/settings/cors', { allow_all: corsForm.value.allow_all, origins: corsForm.value.origins });
+                    await loadSettings();
+                    toast('ok', 'CORS 配置已保存');
+                } catch (e) {
+                    toast('err', '保存 CORS 失败: ' + (e.response?.data?.error?.message || e.message));
+                } finally { savingCors.value = false; }
+            };
+            const saveSettings = async () => {
+                savingSettings.value = true;
+                try {
+                    await http.put('/settings', {
+                        default_resource_id: settingsForm.value.default_resource_id,
+                        default_speaker: settingsForm.value.default_speaker,
+                        default_format: settingsForm.value.default_format,
+                        sample_rate: settingsForm.value.sample_rate,
+                        model: settingsForm.value.model,
+                    });
+                    await loadSettings();
+                    await loadOverview();
+                    toast('ok', '设置已保存');
+                } catch (e) {
+                    toast('err', '保存失败: ' + (e.response?.data?.error?.message || e.message));
+                } finally { savingSettings.value = false; }
+            };
+            const saveApiKey = async () => {
+                if (!apiKeyInput.value) return;
+                try {
+                    await http.put('/settings/api-key', { api_key: apiKeyInput.value });
+                    apiKeyInput.value = '';
+                    await loadSettings();
+                    toast('ok', 'API Key 已更新');
+                } catch (e) {
+                    toast('err', '更新失败: ' + (e.response?.data?.error?.message || e.message));
+                }
+            };
+            const saveAuthKey = async () => {
+                if (!authKeyInput.value) return;
+                try {
+                    await http.put('/settings/auth-key', { auth_key: authKeyInput.value });
+                    authKeyInput.value = '';
+                    setTimeout(() => {
+                        clearKey();
+                        location.href = '/admin/login';
+                    }, 200);
+                    toast('ok', 'Auth Key 已更新,请用新 Key 重新登录');
+                } catch (e) {
+                    toast('err', '更新失败: ' + (e.response?.data?.error?.message || e.message));
+                }
+            };
+            const resetSettingsForm = () => { loadSettings(); };
+
+            onMounted(() => {
+                if (!getKey()) { location.href = '/admin/login'; return; }
+                mountShell({
+                    activeNav: 'settings',
+                    overview: overview.value,
+                    corsConfigured: !!(settings.value && settings.value.cors_configured),
+                    onReload: reloadAll,
+                });
+                reloadAll();
+            });
+
+            return {
+                overview, voices, settings, settingsForm, apiKeyInput, authKeyInput,
+                savingSettings, savingCors,
+                corsForm, corsCurrentLabel, saveCors,
+                saveSettings, saveApiKey, saveAuthKey, resetSettingsForm,
+                reloadAll,
+            };
+        },
+    }).mount('#app');
+    </script>
+</body>
+</html>

router/admin-shell.js

@@ -0,0 +1,170 @@
+/* admin 共享脚本 — 多个 admin-* 页面共用
+   加载方式: <script src="/admin/admin-shell.js"></script>
+   暴露到 window.admin: { http, getKey, setKey, clearKey, toast, dismissToast, mountShell,
+                           formatUptime, shortPath, formatBytes, formatStart, logout }
+   用法:
+     const { http, toast, mountShell } = window.admin;
+     const { apiKey, overview } = mountShell({ activeNav: 'voices' });
+*/
+(function () {
+    const KEY_STORAGE = 'ttsAdminKey';
+
+    // === Key 持久化(sessionStorage,跨页面同标签页共享)===
+    const getKey = () => sessionStorage.getItem(KEY_STORAGE) || '';
+    const setKey = (k) => { if (k) sessionStorage.setItem(KEY_STORAGE, k); else sessionStorage.removeItem(KEY_STORAGE); };
+    const clearKey = () => sessionStorage.removeItem(KEY_STORAGE);
+
+    // === HTTP client(401 自动清 key,业务层 redirect 到登录)===
+    const http = axios.create({ baseURL: '/api' });
+    http.interceptors.request.use(c => {
+        const k = getKey();
+        if (k) c.headers.Authorization = 'Bearer ' + k;
+        return c;
+    });
+    http.interceptors.response.use(r => r, err => {
+        if (err.response && err.response.status === 401) {
+            clearKey();
+        }
+        return Promise.reject(err);
+    });
+
+    // === Toasts(全局单例)===
+    let toasts = [];
+    let toastSeq = 0;
+    let toastStackEl = null;
+    const ensureToastStack = () => {
+        if (toastStackEl) return toastStackEl;
+        toastStackEl = document.createElement('div');
+        toastStackEl.className = 'toast-stack';
+        document.body.appendChild(toastStackEl);
+        return toastStackEl;
+    };
+    const renderToasts = () => {
+        const stack = ensureToastStack();
+        stack.innerHTML = toasts.map(t => `
+            <div class="toast toast-${t.type}">
+                <span class="toast-icon">${t.type === 'ok' ? '✓' : t.type === 'err' ? '!' : '⚠'}</span>
+                <span class="toast-msg">${escapeHTML(t.msg)}</span>
+                <button class="toast-close" data-id="${t.id}">×</button>
+            </div>
+        `).join('');
+        stack.querySelectorAll('.toast-close').forEach(btn => {
+            btn.addEventListener('click', () => dismissToast(Number(btn.dataset.id)));
+        });
+    };
+    const toast = (type, msg, ttl) => {
+        const id = ++toastSeq;
+        toasts.push({ id, type, msg });
+        renderToasts();
+        if (ttl !== 0) setTimeout(() => dismissToast(id), ttl || 3200);
+    };
+    const dismissToast = (id) => {
+        toasts = toasts.filter(t => t.id !== id);
+        renderToasts();
+    };
+
+    // === HTML escape(toast msg 兜底)===
+    const escapeHTML = (s) => String(s).replace(/[&<>"']/g, c => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+
+    // === format helpers ===
+    const formatUptime = (s) => {
+        if (!s) return '—';
+        const h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60);
+        return h > 0 ? `${h}h ${m}m` : `${m}m`;
+    };
+    const shortPath = (p) => p ? p.split(/[\\/]/).pop() : '';
+    const formatBytes = (n) => {
+        if (n === null || n === undefined) return '—';
+        if (n < 1024) return n + ' B';
+        if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
+        return (n / 1024 / 1024).toFixed(2) + ' MB';
+    };
+    const formatStart = (iso) => {
+        if (!iso) return '—';
+        try {
+            const d = new Date(iso);
+            const pad = (n) => String(n).padStart(2, '0');
+            return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+        } catch (e) { return '—'; }
+    };
+
+    // === Sidebar 渲染(每个 admin-* 页面共用)===
+    // 占位符 <aside id="admin-sidebar"></aside> 由 shell 填入。
+    // options: { activeNav: 'dashboard' | 'voices' | 'settings', overview, voiceCount, corsConfigured, onReload, onLogout }
+    const mountShell = (options = {}) => {
+        const slot = document.getElementById('admin-sidebar');
+        if (!slot) return {};
+        const activeNav = options.activeNav || '';
+        const ov = options.overview || {};
+        const voiceCount = options.voiceCount != null ? options.voiceCount : '';
+        const corsConfigured = !!options.corsConfigured;
+        slot.outerHTML = `
+<aside class="sidebar">
+    <div class="brand">
+        <div class="brand-logo">TTS</div>
+        <div>
+            <div class="brand-name">控制台</div>
+            <div class="brand-version">v${escapeHTML(ov.version || '—')} · ${escapeHTML(ov.mode || '...')}</div>
+        </div>
+    </div>
+    <nav class="nav">
+        <div class="nav-group">
+            <div class="nav-label">概览</div>
+            <a class="nav-item${activeNav === 'dashboard' ? ' active' : ''}" href="/admin">
+                <span class="nav-icon">▦</span><span>仪表盘</span>
+            </a>
+        </div>
+        <div class="nav-group">
+            <div class="nav-label">管理</div>
+            <a class="nav-item${activeNav === 'voices' ? ' active' : ''}" href="/admin/voices">
+                <span class="nav-icon">♪</span><span>音色</span>
+                <span class="nav-badge">${voiceCount}</span>
+            </a>
+            <a class="nav-item${activeNav === 'settings' ? ' active' : ''}" href="/admin/settings">
+                <span class="nav-icon">⚙</span><span>设置</span>
+                ${corsConfigured ? '' : '<span class="nav-dot" title="CORS 未配置"></span>'}
+            </a>
+        </div>
+    </nav>
+    <div class="sidebar-foot">
+        <button class="btn-icon" id="btn-reload" title="刷新">↻ 刷新</button>
+        <button class="btn-icon" id="btn-logout" title="登出">⏻ 登出</button>
+    </div>
+</aside>`;
+        const btnReload = document.getElementById('btn-reload');
+        const btnLogout = document.getElementById('btn-logout');
+        if (btnReload) btnReload.addEventListener('click', () => {
+            if (typeof options.onReload === 'function') options.onReload();
+            else location.reload();
+        });
+        if (btnLogout) btnLogout.addEventListener('click', () => {
+            clearKey();
+            if (typeof options.onLogout === 'function') options.onLogout();
+            else location.href = '/admin/login';
+        });
+        return {};
+    };
+
+    // === Login helper(login 页用)===
+    const login = async (key) => {
+        setKey(key);
+        try {
+            await http.get('/admin/overview');
+            return true;
+        } catch (e) {
+            clearKey();
+            throw e;
+        }
+    };
+
+    // 暴露
+    window.admin = {
+        http, getKey, setKey, clearKey,
+        toast, dismissToast,
+        mountShell, login,
+        formatUptime, shortPath, formatBytes, formatStart,
+        escapeHTML,
+    };
+})();

router/admin-voices.html

@@ -0,0 +1,260 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>火山 TTS · 音色管理</title>
+    <script src="https://cdn.bootcdn.net/ajax/libs/vue/3.4.21/vue.global.prod.js"></script>
+    <script src="https://cdn.bootcdn.net/ajax/libs/axios/1.6.7/axios.min.js"></script>
+    <link rel="stylesheet" href="/admin/admin.css">
+</head>
+<body>
+    <div id="app">
+        <div class="app-shell">
+            <aside id="admin-sidebar"></aside>
+
+            <main class="main">
+                <header class="page-head">
+                    <div>
+                        <h1 class="page-title">音色管理</h1>
+                        <p class="page-sub">管理火山 TTS 音色及其启用状态</p>
+                    </div>
+                    <div class="page-actions">
+                        <button class="btn btn-primary" @click="openAdd">+ 新增音色</button>
+                    </div>
+                </header>
+
+                <div class="toolbar">
+                    <div class="toolbar-left">
+                        <div class="search">
+                            <span class="search-icon">⌕</span>
+                            <input v-model="voiceSearch" placeholder="搜索名称、Speaker、资源 ID...">
+                        </div>
+                        <div class="seg">
+                            <button class="seg-btn" :class="{active: voiceFilter===null}" @click="voiceFilter=null">全部</button>
+                            <button class="seg-btn" :class="{active: voiceFilter==='on'}" @click="voiceFilter='on'">启用</button>
+                            <button class="seg-btn" :class="{active: voiceFilter==='off'}" @click="voiceFilter='off'">停用</button>
+                        </div>
+                    </div>
+                    <div class="toolbar-right">
+                        <span v-if="voiceSearch || voiceFilter !== null">{{ filteredVoices.length }} / {{ voices.length }}</span>
+                        <span v-else>共 {{ voices.length }} 条</span>
+                    </div>
+                </div>
+
+                <div v-if="actionErr" class="alert alert-danger">
+                    <span class="alert-icon">⚠</span>
+                    <div class="alert-body">
+                        <div class="alert-title">操作失败</div>
+                        <div class="alert-desc">{{ actionErr }}</div>
+                    </div>
+                </div>
+
+                <div class="data-card">
+                    <table class="data-table" v-if="filteredVoices.length">
+                        <thead>
+                            <tr>
+                                <th>名称</th>
+                                <th>Speaker</th>
+                                <th>资源 ID</th>
+                                <th>Model</th>
+                                <th>状态</th>
+                                <th class="th-actions">操作</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <tr v-for="v in filteredVoices" :key="v.name">
+                                <td>
+                                    <div class="cell-name">{{ v.name }}</div>
+                                    <div v-if="v.description" class="cell-sub">{{ v.description }}</div>
+                                </td>
+                                <td><span class="mono text-dim">{{ v.speaker }}</span></td>
+                                <td><span class="mono text-dim">{{ v.resource_id }}</span></td>
+                                <td><span class="mono text-dim">{{ v.model || '—' }}</span></td>
+                                <td>
+                                    <span class="pill" :class="v.enabled ? 'pill-success' : 'pill-mute'">
+                                        <span class="pill-dot"></span>
+                                        {{ v.enabled ? '启用' : '停用' }}
+                                    </span>
+                                </td>
+                                <td class="th-actions">
+                                    <label class="switch" :title="v.enabled ? '点击停用' : '点击启用'" style="margin-right: 12px;">
+                                        <input type="checkbox" :checked="v.enabled" @change="toggle(v)">
+                                        <span class="switch-track"></span>
+                                    </label>
+                                    <button class="btn btn-sm btn-danger-ghost" @click="remove(v)">删除</button>
+                                </td>
+                            </tr>
+                        </tbody>
+                    </table>
+
+                    <div v-else-if="voices.length === 0" class="empty">
+                        <div class="empty-icon">♪</div>
+                        <div class="empty-title">还没有音色</div>
+                        <div class="empty-desc">点击右上角「+ 新增音色」开始添加第一个火山 TTS 音色</div>
+                        <button class="btn btn-primary" @click="openAdd">+ 新增音色</button>
+                    </div>
+
+                    <div v-else class="empty">
+                        <div class="empty-icon">⌕</div>
+                        <div class="empty-title">没有匹配的音色</div>
+                        <div class="empty-desc">尝试调整搜索词或筛选条件</div>
+                        <button class="btn" @click="voiceSearch=''; voiceFilter=null">清除筛选</button>
+                    </div>
+                </div>
+            </main>
+        </div>
+
+        <!-- Add modal -->
+        <teleport to="body">
+            <transition name="modal">
+                <div v-if="showAdd" class="modal-backdrop" @click.self="showAdd=false">
+                    <div class="modal" @click.stop>
+                        <div class="modal-head">
+                            <h2>新增音色</h2>
+                            <button class="btn-icon" @click="showAdd=false" title="关闭" style="flex: 0; padding: 4px 10px;">×</button>
+                        </div>
+                        <div class="modal-body">
+                            <div class="grid-2">
+                                <div class="field">
+                                    <label>对外名 (voice) <span class="req">*</span></label>
+                                    <input v-model="form.name" placeholder="qian" class="mono">
+                                </div>
+                                <div class="field">
+                                    <label>Speaker (火山音色 ID) <span class="req">*</span></label>
+                                    <input v-model="form.speaker" placeholder="S_xxx" class="mono">
+                                </div>
+                                <div class="field">
+                                    <label>资源 ID <span class="req">*</span></label>
+                                    <input v-model="form.resource_id" placeholder="seed-icl-2.0" class="mono">
+                                </div>
+                                <div class="field">
+                                    <label>Model</label>
+                                    <input v-model="form.model" placeholder="seed-tts-2.0-standard" class="mono">
+                                </div>
+                                <div class="field">
+                                    <label>Language</label>
+                                    <input v-model="form.language" placeholder="zh" class="mono">
+                                </div>
+                                <div class="field">
+                                    <label>Description</label>
+                                    <input v-model="form.description" placeholder="可选">
+                                </div>
+                            </div>
+                            <div v-if="addErr" class="alert alert-danger" style="margin-top: 14px;">
+                                <span class="alert-icon">⚠</span>
+                                <div class="alert-body">
+                                    <div class="alert-title">提交失败</div>
+                                    <div class="alert-desc">{{ addErr }}</div>
+                                </div>
+                            </div>
+                        </div>
+                        <div class="modal-foot">
+                            <button class="btn" @click="showAdd=false">取消</button>
+                            <button class="btn btn-primary" @click="submitAdd" :disabled="adding">{{ adding ? '提交中...' : '提交' }}</button>
+                        </div>
+                    </div>
+                </div>
+            </transition>
+        </teleport>
+    </div>
+
+    <script src="/admin/admin-shell.js"></script>
+    <script>
+    const { createApp, ref, computed, onMounted } = Vue;
+    const { http, getKey, toast, mountShell } = window.admin;
+    createApp({
+        setup() {
+            const overview = ref({});
+            const voices = ref([]);
+            const actionErr = ref('');
+
+            const voiceSearch = ref('');
+            const voiceFilter = ref(null);
+            const filteredVoices = computed(() => {
+                const q = voiceSearch.value.trim().toLowerCase();
+                return voices.value.filter(v => {
+                    if (voiceFilter.value === 'on' && !v.enabled) return false;
+                    if (voiceFilter.value === 'off' && v.enabled) return false;
+                    if (!q) return true;
+                    return (v.name || '').toLowerCase().includes(q)
+                        || (v.speaker || '').toLowerCase().includes(q)
+                        || (v.resource_id || '').toLowerCase().includes(q);
+                });
+            });
+
+            const showAdd = ref(false);
+            const adding = ref(false);
+            const addErr = ref('');
+            const form = ref({ name: '', speaker: '', resource_id: 'seed-icl-2.0', model: 'seed-tts-2.0-standard', language: '', description: '' });
+
+            const loadOverview = async () => {
+                try { overview.value = (await http.get('/admin/overview')).data; }
+                catch (e) { actionErr.value = '加载概览失败: ' + e.message; }
+            };
+            const loadVoices = async () => {
+                try { const r = await http.get('/voices'); voices.value = r.data.voices || []; }
+                catch (e) { actionErr.value = '加载音色失败: ' + e.message; }
+            };
+            const reloadAll = () => { loadOverview(); loadVoices(); };
+
+            const openAdd = () => {
+                form.value = { name: '', speaker: '', resource_id: 'seed-icl-2.0', model: 'seed-tts-2.0-standard', language: '', description: '' };
+                addErr.value = '';
+                showAdd.value = true;
+            };
+            const submitAdd = async () => {
+                addErr.value = '';
+                if (!form.value.name || !form.value.speaker || !form.value.resource_id) {
+                    addErr.value = '请填写名称、Speaker、资源 ID';
+                    return;
+                }
+                adding.value = true;
+                try {
+                    await http.post('/voices', form.value);
+                    showAdd.value = false;
+                    await loadVoices();
+                    await loadOverview();
+                    toast('ok', '音色已添加');
+                } catch (e) {
+                    addErr.value = e.response?.data?.error?.message || e.message;
+                } finally { adding.value = false; }
+            };
+            const toggle = async (v) => {
+                try { await http.patch(`/voices/${v.name}/toggle`, { enabled: !v.enabled }); await loadVoices(); }
+                catch (e) {
+                    actionErr.value = '切换失败: ' + (e.response?.data?.error?.message || e.message);
+                    toast('err', actionErr.value);
+                }
+            };
+            const remove = async (v) => {
+                if (!confirm(`确定删除音色 "${v.name}" 吗?`)) return;
+                try { await http.delete(`/voices/${v.name}`); await loadVoices(); await loadOverview(); toast('ok', '音色已删除'); }
+                catch (e) {
+                    actionErr.value = '删除失败: ' + (e.response?.data?.error?.message || e.message);
+                    toast('err', actionErr.value);
+                }
+            };
+
+            onMounted(() => {
+                if (!getKey()) { location.href = '/admin/login'; return; }
+                mountShell({
+                    activeNav: 'voices',
+                    overview: overview.value,
+                    voiceCount: voices.value.length,
+                    onReload: reloadAll,
+                });
+                reloadAll();
+            });
+
+            return {
+                overview, voices, actionErr,
+                voiceSearch, voiceFilter, filteredVoices,
+                showAdd, form, addErr, adding, openAdd, submitAdd, toggle, remove,
+                reloadAll,
+            };
+        },
+    }).mount('#app');
+    </script>
+</body>
+</html>

router/admin.css

@@ -0,0 +1,415 @@
+/* admin 共享样式 — 多个 admin-* 页面共用
+   加载方式: <link rel="stylesheet" href="/admin/admin.css">
+*/
+
+:root {
+    --bg: #0a0e1a;
+    --bg-sidebar: #0c111e;
+    --bg-card: #131826;
+    --bg-elev: #1a2138;
+    --bg-hover: #1f2740;
+    --border: #232b42;
+    --border-strong: #2e3754;
+    --text: #e4e7ee;
+    --text-dim: #94a3b8;
+    --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-sm: 0 1px 2px rgba(0,0,0,0.4);
+    --shadow: 0 4px 16px rgba(0,0,0,0.25);
+    --shadow-lg: 0 20px 50px rgba(0,0,0,0.5);
+    --sidebar-w: 240px;
+}
+* { margin: 0; padding: 0; box-sizing: border-box; }
+html, body { height: 100%; }
+body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    font-size: 14px;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+    background-image:
+        radial-gradient(ellipse 70% 50% at 20% 0%, rgba(0,212,255,0.05), transparent),
+        radial-gradient(ellipse 50% 40% at 100% 100%, rgba(123,47,247,0.04), transparent);
+    background-attachment: fixed;
+}
+#app { min-height: 100vh; }
+
+/* === Login === */
+.login-screen {
+    min-height: 100vh;
+    display: flex; align-items: center; justify-content: center;
+    padding: 24px; position: relative;
+}
+.login-screen::before {
+    content: ''; position: absolute; inset: 0;
+    background:
+        radial-gradient(circle at 30% 20%, rgba(0,212,255,0.12), transparent 40%),
+        radial-gradient(circle at 70% 80%, rgba(123,47,247,0.10), transparent 40%);
+    pointer-events: none;
+}
+.login-card {
+    position: relative;
+    width: 100%; max-width: 400px;
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-xl);
+    padding: 36px 32px;
+    box-shadow: var(--shadow-lg);
+}
+.login-logo {
+    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: 18px; color: #fff;
+    margin: 0 auto 20px;
+    box-shadow: 0 6px 24px var(--accent-glow);
+}
+.login-card h1 { font-size: 22px; font-weight: 600; text-align: center; margin-bottom: 6px; }
+.login-card .sub { color: var(--text-dim); font-size: 13px; text-align: center; margin-bottom: 24px; }
+.login-input {
+    width: 100%; padding: 12px 14px; margin-bottom: 14px;
+    background: var(--bg-elev); border: 1px solid var(--border);
+    color: var(--text); border-radius: var(--radius); font-size: 14px;
+    font-family: inherit; transition: border-color 0.15s, box-shadow 0.15s;
+}
+.login-input:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+.login-err {
+    margin-top: 12px; padding: 10px 12px;
+    background: var(--danger-soft); border: 1px solid rgba(239,68,68,0.3);
+    color: var(--danger); border-radius: var(--radius); font-size: 12px;
+}
+
+/* === App shell === */
+.app-shell { display: flex; min-height: 100vh; }
+.sidebar {
+    width: var(--sidebar-w);
+    background: var(--bg-sidebar);
+    border-right: 1px solid var(--border);
+    display: flex; flex-direction: column;
+    position: sticky; top: 0; height: 100vh;
+    flex-shrink: 0;
+}
+.brand { display: flex; align-items: center; gap: 12px; padding: 20px 18px; border-bottom: 1px solid var(--border); }
+.brand-logo {
+    width: 36px; height: 36px; border-radius: 10px;
+    background: linear-gradient(135deg, var(--accent), var(--accent-2));
+    display: flex; align-items: center; justify-content: center;
+    font-weight: 700; font-size: 13px; color: #fff;
+    box-shadow: 0 2px 12px var(--accent-glow);
+}
+.brand-name { font-size: 14px; font-weight: 600; }
+.brand-version { font-size: 11px; color: var(--text-mute); margin-top: 2px; font-family: ui-monospace, monospace; }
+
+.nav { flex: 1; padding: 16px 12px; overflow-y: auto; }
+.nav-group { margin-bottom: 20px; }
+.nav-label {
+    font-size: 10px; font-weight: 600; color: var(--text-mute);
+    text-transform: uppercase; letter-spacing: 0.8px;
+    padding: 0 10px 8px;
+}
+.nav-item {
+    display: flex; align-items: center; gap: 10px;
+    padding: 9px 10px; border-radius: var(--radius);
+    color: var(--text-dim); font-size: 13px;
+    cursor: pointer; user-select: none;
+    margin-bottom: 2px;
+    transition: background 0.12s, color 0.12s;
+    position: relative;
+    text-decoration: none;
+}
+.nav-item:hover { background: var(--bg-hover); color: var(--text); }
+.nav-item.active {
+    background: var(--accent-soft);
+    color: var(--accent);
+    font-weight: 500;
+}
+.nav-item.active::before {
+    content: ''; position: absolute; left: 0; top: 50%; transform: translateY(-50%);
+    width: 3px; height: 16px; background: var(--accent); border-radius: 0 2px 2px 0;
+}
+.nav-icon { font-size: 16px; width: 18px; text-align: center; flex-shrink: 0; }
+.nav-badge {
+    margin-left: auto; padding: 1px 7px; border-radius: 10px;
+    background: var(--bg-hover); font-size: 11px; font-weight: 500;
+    color: var(--text-dim);
+}
+.nav-item.active .nav-badge { background: rgba(0,212,255,0.2); color: var(--accent); }
+.nav-dot {
+    margin-left: auto; width: 6px; height: 6px; border-radius: 50%;
+    background: var(--warning); box-shadow: 0 0 0 3px rgba(245,158,11,0.2);
+}
+
+.sidebar-foot {
+    display: flex; gap: 4px; padding: 12px;
+    border-top: 1px solid var(--border);
+}
+.btn-icon {
+    flex: 1; padding: 8px; background: transparent;
+    border: 1px solid transparent; border-radius: var(--radius);
+    color: var(--text-dim); cursor: pointer; font-size: 13px;
+    font-family: inherit;
+    transition: all 0.12s;
+}
+.btn-icon:hover { background: var(--bg-hover); color: var(--text); border-color: var(--border); }
+
+/* === Main === */
+.main { flex: 1; min-width: 0; padding: 28px 32px; max-width: 1200px; }
+.page-head {
+    display: flex; justify-content: space-between; align-items: flex-end;
+    margin-bottom: 24px; gap: 16px; flex-wrap: wrap;
+}
+.page-title { font-size: 22px; font-weight: 600; letter-spacing: -0.01em; }
+.page-sub { color: var(--text-dim); font-size: 13px; margin-top: 4px; }
+.page-actions { display: flex; gap: 8px; align-items: center; }
+
+/* === Buttons === */
+.btn {
+    display: inline-flex; align-items: center; justify-content: center; gap: 6px;
+    padding: 8px 14px; background: var(--bg-elev); border: 1px solid var(--border);
+    color: var(--text); border-radius: var(--radius); cursor: pointer;
+    font-size: 13px; font-weight: 500; font-family: inherit;
+    transition: all 0.12s;
+    white-space: nowrap;
+}
+.btn:hover:not(:disabled) { border-color: var(--border-strong); background: var(--bg-hover); }
+.btn:disabled { opacity: 0.5; cursor: not-allowed; }
+.btn-primary { background: var(--accent); color: #00121a; border-color: var(--accent); }
+.btn-primary:hover:not(:disabled) { background: var(--accent-hover); border-color: var(--accent-hover); }
+.btn-danger { color: var(--danger); border-color: var(--border); }
+.btn-danger:hover:not(:disabled) { background: var(--danger-soft); border-color: var(--danger); color: var(--danger); }
+.btn-danger-ghost { color: var(--text-mute); border-color: transparent; background: transparent; padding: 5px 10px; }
+.btn-danger-ghost:hover:not(:disabled) { background: var(--danger-soft); color: var(--danger); border-color: transparent; }
+.btn-sm { padding: 6px 10px; font-size: 12px; }
+.btn-lg { padding: 11px 16px; font-size: 14px; }
+
+/* === Card === */
+.card {
+    background: var(--bg-card); border: 1px solid var(--border);
+    border-radius: var(--radius-lg); padding: 20px; margin-bottom: 16px;
+}
+.card-head { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 16px; gap: 12px; }
+.card-title { font-size: 15px; font-weight: 600; }
+.card-sub { font-size: 12px; color: var(--text-dim); margin-top: 2px; }
+
+/* === Stat grid === */
+.stat-grid {
+    display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    gap: 14px; margin-bottom: 20px;
+}
+.stat-card {
+    background: var(--bg-card); border: 1px solid var(--border);
+    border-radius: var(--radius-lg); padding: 18px 20px;
+    transition: border-color 0.15s;
+    position: relative; overflow: hidden;
+}
+.stat-card::before {
+    content: ''; position: absolute; top: 0; left: 0; right: 0; height: 1px;
+    background: linear-gradient(90deg, transparent, var(--border-strong), transparent);
+}
+.stat-card:hover { border-color: var(--border-strong); }
+.stat-top { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }
+.stat-label { font-size: 11px; color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.5px; font-weight: 500; }
+.stat-value { font-size: 26px; font-weight: 700; letter-spacing: -0.02em; line-height: 1.1; }
+.stat-value .stat-unit { font-size: 14px; color: var(--text-mute); font-weight: 500; margin-left: 4px; }
+.stat-foot { font-size: 11px; color: var(--text-dim); margin-top: 6px; }
+
+.pill {
+    display: inline-flex; align-items: center; gap: 5px;
+    padding: 2px 8px; border-radius: 999px;
+    font-size: 11px; font-weight: 500;
+    background: var(--bg-elev); color: var(--text-dim);
+    border: 1px solid var(--border);
+}
+.pill-dot { width: 5px; height: 5px; border-radius: 50%; background: currentColor; }
+.pill-success { background: var(--success-soft); color: var(--success); border-color: rgba(34,197,94,0.3); }
+.pill-accent { background: var(--accent-soft); color: var(--accent); border-color: rgba(0,212,255,0.3); }
+.pill-warning { background: var(--warning-soft); color: var(--warning); border-color: rgba(245,158,11,0.3); }
+.pill-mute { background: var(--bg-elev); color: var(--text-mute); }
+
+/* === KV list === */
+.kv { display: grid; grid-template-columns: 1fr 1fr; gap: 0; }
+.kv-row { display: contents; }
+.kv-row > dt { padding: 10px 16px 10px 0; font-size: 12px; color: var(--text-dim); border-bottom: 1px solid var(--border); }
+.kv-row > dd { padding: 10px 0; font-size: 13px; border-bottom: 1px solid var(--border); word-break: break-all; }
+.kv-row:last-child > dt, .kv-row:last-child > dd { border-bottom: none; }
+
+/* === Toolbar === */
+.toolbar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px; gap: 12px; flex-wrap: wrap; }
+.toolbar-left { display: flex; align-items: center; gap: 10px; flex: 1; min-width: 0; }
+.toolbar-right { font-size: 12px; color: var(--text-dim); }
+
+.search { position: relative; flex: 0 0 280px; max-width: 100%; }
+.search input {
+    width: 100%; padding: 8px 12px 8px 32px;
+    background: var(--bg-card); border: 1px solid var(--border);
+    color: var(--text); border-radius: var(--radius); font-size: 13px;
+    font-family: inherit; transition: border-color 0.15s;
+}
+.search input::placeholder { color: var(--text-mute); }
+.search input:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+.search-icon { position: absolute; left: 10px; top: 50%; transform: translateY(-50%); color: var(--text-mute); font-size: 14px; pointer-events: none; }
+
+.seg { display: inline-flex; background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius); padding: 2px; }
+.seg-btn {
+    padding: 5px 12px; background: transparent; border: none;
+    color: var(--text-dim); cursor: pointer; font-size: 12px; font-family: inherit;
+    border-radius: 6px; transition: all 0.12s;
+}
+.seg-btn:hover { color: var(--text); }
+.seg-btn.active { background: var(--bg-elev); color: var(--accent); }
+
+/* === Data table === */
+.data-card { background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius-lg); overflow: hidden; }
+.data-table { width: 100%; border-collapse: collapse; }
+.data-table th {
+    text-align: left; padding: 12px 16px; font-size: 11px; font-weight: 600;
+    color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.5px;
+    background: var(--bg-elev); border-bottom: 1px solid var(--border);
+    white-space: nowrap;
+}
+.data-table td {
+    padding: 14px 16px; font-size: 13px;
+    border-bottom: 1px solid var(--border); vertical-align: middle;
+}
+.data-table tbody tr { transition: background 0.1s; }
+.data-table tbody tr:hover { background: rgba(255,255,255,0.02); }
+.data-table tbody tr:last-child td { border-bottom: none; }
+.th-actions { text-align: right; width: 1%; white-space: nowrap; }
+.data-table td.th-actions { text-align: right; }
+.cell-name { font-weight: 500; }
+.cell-sub { font-size: 11px; color: var(--text-mute); margin-top: 2px; }
+
+.empty { padding: 64px 24px; text-align: center; color: var(--text-dim); }
+.empty-icon { font-size: 36px; opacity: 0.3; margin-bottom: 12px; }
+.empty-title { font-size: 15px; font-weight: 500; color: var(--text); margin-bottom: 6px; }
+.empty-desc { font-size: 13px; margin-bottom: 16px; }
+
+/* === Switch === */
+.switch { position: relative; display: inline-block; width: 36px; height: 20px; cursor: pointer; vertical-align: middle; }
+.switch input { opacity: 0; width: 0; height: 0; }
+.switch-track {
+    position: absolute; inset: 0;
+    background: var(--bg-elev); border: 1px solid var(--border);
+    border-radius: 999px; transition: all 0.18s;
+}
+.switch-track::before {
+    content: ''; position: absolute; top: 2px; left: 2px;
+    width: 14px; height: 14px; border-radius: 50%;
+    background: var(--text-dim); transition: all 0.18s;
+}
+.switch input:checked + .switch-track { background: var(--accent); border-color: var(--accent); }
+.switch input:checked + .switch-track::before { transform: translateX(16px); background: #00121a; }
+
+/* === Forms === */
+.field { margin-bottom: 14px; }
+.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, .field textarea, .input-static, .textarea {
+    width: 100%; padding: 9px 12px;
+    background: var(--bg-elev); border: 1px solid var(--border);
+    color: var(--text); border-radius: var(--radius); font-size: 13px;
+    font-family: inherit; transition: border-color 0.15s, box-shadow 0.15s;
+}
+.field input:focus, .field select:focus, .field textarea:focus, .textarea:focus {
+    outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft);
+}
+.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;
+}
+.input-static { font-family: ui-monospace, SFMono-Regular, monospace; color: var(--accent); padding: 8px 12px; }
+.textarea { font-family: ui-monospace, SFMono-Regular, monospace; font-size: 12px; line-height: 1.6; resize: vertical; }
+.input-group { display: flex; gap: 8px; }
+.input-group input { flex: 1; }
+.hint { font-size: 11px; color: var(--text-mute); margin-top: 5px; line-height: 1.5; }
+.check { display: flex; align-items: center; gap: 8px; cursor: pointer; font-size: 13px; color: var(--text); }
+.check input[type=checkbox] { width: 16px; height: 16px; accent-color: var(--accent); cursor: pointer; }
+.divider { height: 1px; background: var(--border); margin: 20px 0; }
+.grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
+.grid-2 .field { margin-bottom: 0; }
+.actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 20px; padding-top: 16px; border-top: 1px solid var(--border); }
+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); }
+.mono { font-family: ui-monospace, SFMono-Regular, monospace; }
+
+/* === Settings grid === */
+.settings-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(420px, 1fr)); gap: 16px; align-items: start; }
+.settings-grid .card { margin-bottom: 0; }
+
+/* === Alert / Banner === */
+.alert { display: flex; align-items: center; gap: 12px; padding: 12px 16px; border-radius: var(--radius); margin-bottom: 16px; font-size: 13px; }
+.alert-icon { font-size: 16px; flex-shrink: 0; }
+.alert-body { flex: 1; }
+.alert-title { font-weight: 500; }
+.alert-desc { font-size: 12px; color: var(--text-dim); margin-top: 2px; }
+.alert-warning { background: var(--warning-soft); border: 1px solid rgba(245,158,11,0.3); color: var(--warning); }
+.alert-warning .alert-title { color: var(--warning); }
+.alert-danger { background: var(--danger-soft); border: 1px solid rgba(239,68,68,0.3); color: var(--danger); }
+
+/* === Toasts === */
+.toast-stack { position: fixed; top: 16px; right: 16px; z-index: 9999; display: flex; flex-direction: column; gap: 8px; pointer-events: none; }
+.toast {
+    display: flex; align-items: center; gap: 10px;
+    padding: 10px 14px; min-width: 240px; max-width: 380px;
+    background: var(--bg-card); border: 1px solid var(--border-strong);
+    border-radius: var(--radius); box-shadow: var(--shadow-lg);
+    font-size: 13px; pointer-events: auto;
+    border-left-width: 3px;
+}
+.toast-ok { border-left-color: var(--success); }
+.toast-err { border-left-color: var(--danger); }
+.toast-warn { border-left-color: var(--warning); }
+.toast-icon { font-size: 14px; font-weight: 700; }
+.toast-ok .toast-icon { color: var(--success); }
+.toast-err .toast-icon { color: var(--danger); }
+.toast-warn .toast-icon { color: var(--warning); }
+.toast-msg { flex: 1; }
+.toast-close { background: none; border: none; color: var(--text-mute); cursor: pointer; font-size: 16px; padding: 0 4px; font-family: inherit; }
+.toast-close:hover { color: var(--text); }
+.toast-enter-active, .toast-leave-active { transition: all 0.22s ease; }
+.toast-enter-from { opacity: 0; transform: translateX(20px); }
+.toast-leave-to { opacity: 0; transform: translateX(20px); }
+
+/* === Modal === */
+.modal-backdrop {
+    position: fixed; inset: 0; z-index: 100;
+    background: rgba(5, 8, 16, 0.7); backdrop-filter: blur(4px);
+    display: flex; align-items: center; justify-content: center;
+    padding: 24px;
+}
+.modal {
+    background: var(--bg-card); border: 1px solid var(--border-strong);
+    border-radius: var(--radius-lg); box-shadow: var(--shadow-lg);
+    width: 100%; max-width: 540px; max-height: 90vh; overflow: auto;
+    display: flex; flex-direction: column;
+}
+.modal-head { display: flex; justify-content: space-between; align-items: center; padding: 20px 24px; border-bottom: 1px solid var(--border); }
+.modal-head h2 { font-size: 16px; font-weight: 600; }
+.modal-body { padding: 20px 24px; }
+.modal-foot { display: flex; justify-content: flex-end; gap: 8px; padding: 16px 24px; border-top: 1px solid var(--border); background: var(--bg-elev); border-bottom-left-radius: var(--radius-lg); border-bottom-right-radius: var(--radius-lg); }
+.modal-enter-active, .modal-leave-active { transition: opacity 0.2s; }
+.modal-enter-active .modal, .modal-leave-active .modal { transition: transform 0.2s, opacity 0.2s; }
+.modal-enter-from, .modal-leave-to { opacity: 0; }
+.modal-enter-from .modal, .modal-leave-to .modal { transform: scale(0.95) translateY(-10px); opacity: 0; }
+
+/* === Utility === */
+.text-dim { color: var(--text-dim); }
+.text-mute { color: var(--text-mute); }
+.text-accent { color: var(--accent); }
+.text-success { color: var(--success); }
+.text-danger { color: var(--danger); }

router/router.go

@@ -21,6 +21,21 @@ var setupHTML []byte
 //go:embed admin.html
 var adminHTML []byte
 
+//go:embed admin-login.html
+var adminLoginHTML []byte
+
+//go:embed admin-voices.html
+var adminVoicesHTML []byte
+
+//go:embed admin-settings.html
+var adminSettingsHTML []byte
+
+//go:embed admin.css
+var adminCSS []byte
+
+//go:embed admin-shell.js
+var adminShellJS []byte
+
 // Setup 返回主路由。
 // 中间件顺序(由外向内):
 //   SecurityHeaders → InstallGuard → RateLimit → ConcurrencyLimit → Logger → handler
@@ -64,9 +79,21 @@ func Setup() *mux.Router {
 	// /admin 管理后台(M2);HTML 本身公开,鉴权由前端 JS 拦截
 	// (sessionStorage 没 key 就显示登录页;有 key 调 /api/admin/overview 触发 401 跳登录)
 	// API 端点(/api/admin/* /api/voices*)才需要 RequireAdmin。
-	r.HandleFunc("/admin", func(w http.ResponseWriter, req *http.Request) {
+	//
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	// 拆分后 admin.html / admin-login.html / admin-voices.html / admin-settings.html
-		_, _ = w.Write(adminHTML)
+	// 各自独立,URL 路由切换;共享 admin.css + admin-shell.js 由 adminStatic 提供。
+	r.HandleFunc("/admin", serveAdmin(adminHTML)).Methods("GET")
+	r.HandleFunc("/admin/login", serveAdmin(adminLoginHTML)).Methods("GET")
+	r.HandleFunc("/admin/voices", serveAdmin(adminVoicesHTML)).Methods("GET")
+	r.HandleFunc("/admin/settings", serveAdmin(adminSettingsHTML)).Methods("GET")
+	// admin 静态资源
+	r.HandleFunc("/admin/admin.css", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/css; charset=utf-8")
+		_, _ = w.Write(adminCSS)
+	}).Methods("GET")
+	r.HandleFunc("/admin/admin-shell.js", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/javascript; charset=utf-8")
+		_, _ = w.Write(adminShellJS)
 	}).Methods("GET")
 
 	// /api/admin/overview (鉴权)
@@ -132,3 +159,12 @@ func acceptsHTML(accept string) bool {
 	}
 	return false
 }
+
+// serveAdmin 返回一个把 embed 的 HTML bytes 以 text/html 写出的 handler。
+// 抽出来只为让 /admin/voices 等多条路由的注册保持单行,避免重复 4 段。
+func serveAdmin(body []byte) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write(body)
+	}
+}

setting/config.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/volcano-tts/tts-api/adapter/volcano"
@@ -16,30 +17,129 @@ import (
 )
 
 // 全部环境变量读取的单一入口:其它包不允许直接 os.Getenv,只读这里的全局 Config。
-
+//
-// TTSOptions 是火山 v3 TTS 调用的完整参数集合,启动期由 LoadRuntimeConfig 从 store 填充。
+// 并发模型:
-// 业务侧(controller)直接读取并传入 volcano.Synthesis。
+//   - TTSOptions / TTSTimeout / TTSConfigErr / Auth.APIKeys / CORS 是运行期可被
+//     LoadRuntimeConfig(由 PUT /api/settings 触发)整体替换的"运行时配置快照"。
+//     struct 整体赋值不是原子的,若 TTS 请求正在读,可能拿到半写状态。
+//   - 解决: 用 ttsMu(RWMutex)统一保护这些字段;读路径用 Get* 拿快照(RLock),
+//     写路径用 Set* 整体替换(Lock)。读多写少,RWMutex 读不互斥,不会显著拖慢热路径。
+//   - Server.Port / TrustedProxyHops / SetupToken 仅启动期写、运行期读,无并发修改,
+//     保持原样不加锁。
 var (
-	TTSOptions   volcano.Options
+	ttsMu       sync.RWMutex
-	TTSConfigErr error
+	ttsOptions  volcano.Options
-	// TTSTimeout 单次合成请求的超时;controller 用来派生 context。
+	ttsTimeout  time.Duration = common.DefaultTimeout
-	TTSTimeout time.Duration = common.DefaultTimeout
+	ttsConfigErr error
+	authAPIKeys []string
+	// corsAllowAll / corsOrigins 拆成两个独立字段,各自在 RLock 下读取,
+	// 避免 CORSConfig 整体读时被 Lock 阻塞热路径。
+	corsAllowAll bool
+	corsOrigins  []string
 )
 
-// AuthConfig OpenAI 兼容接口的客户端 API Key 鉴权配置。
+// GetTTSOptions 读 TTSOptions 快照(值类型,使用方可以放心使用,不会被并发写破坏)。
-type AuthConfig struct {
+// 提供给业务侧(controller)的统一读取入口;LoadRuntimeConfig 写入时用 SetTTSOptions 整体替换。
-	APIKeys []string
+// 业务侧不要缓存这个值跨 goroutine 使用(应该每次调用时重新拿)。
+func GetTTSOptions() volcano.Options {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	return ttsOptions
 }
 
-var Auth AuthConfig
+// SetTTSOptions 整体替换 TTSOptions。LoadRuntimeConfig 写路径专用。
-
+func SetTTSOptions(o volcano.Options) {
-// CORSConfig 跨域白名单配置。
+	ttsMu.Lock()
-type CORSConfig struct {
+	defer ttsMu.Unlock()
-	Origins  []string
+	ttsOptions = o
-	AllowAll bool
 }
 
-var CORS CORSConfig
+// GetTTSTimeout 读当前超时;controller 用它派生 context。
+func GetTTSTimeout() time.Duration {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	return ttsTimeout
+}
+
+// SetTTSTimeout 整体替换超时。
+func SetTTSTimeout(d time.Duration) {
+	ttsMu.Lock()
+	defer ttsMu.Unlock()
+	ttsTimeout = d
+}
+
+// GetTTSConfigErr 读运行时配置错误;nil 表示就绪。
+func GetTTSConfigErr() error {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	return ttsConfigErr
+}
+
+// SetTTSConfigErr 设运行时配置错误;nil 表示清错。
+func SetTTSConfigErr(err error) {
+	ttsMu.Lock()
+	defer ttsMu.Unlock()
+	ttsConfigErr = err
+}
+
+// GetAuthAPIKeys 读鉴权 key 列表;返回拷贝防止业务侧持有底层 slice 后被并发写破坏。
+// 外部不应直接读 Auth.APIKeys,统一走 Get*。
+func GetAuthAPIKeys() []string {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	if len(authAPIKeys) == 0 {
+		return nil
+	}
+	out := make([]string, len(authAPIKeys))
+	copy(out, authAPIKeys)
+	return out
+}
+
+// SetAuthAPIKeys 整体替换鉴权 key 列表;入参被复制以防外部后续修改影响内部状态。
+func SetAuthAPIKeys(keys []string) {
+	ttsMu.Lock()
+	defer ttsMu.Unlock()
+	if len(keys) == 0 {
+		authAPIKeys = nil
+		return
+	}
+	out := make([]string, len(keys))
+	copy(out, keys)
+	authAPIKeys = out
+}
+
+// GetCORSAllowAll 读 CORS 是否放行所有来源。
+func GetCORSAllowAll() bool {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	return corsAllowAll
+}
+
+// GetCORSOrigins 读 CORS 白名单;返回拷贝防止业务侧持有后被并发写破坏。
+func GetCORSOrigins() []string {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	if len(corsOrigins) == 0 {
+		return nil
+	}
+	out := make([]string, len(corsOrigins))
+	copy(out, corsOrigins)
+	return out
+}
+
+// SetCORS 整体替换 CORS 配置;LoadRuntimeConfig 和 PUT /api/settings/cors 写路径专用。
+func SetCORS(allowAll bool, origins []string) {
+	ttsMu.Lock()
+	defer ttsMu.Unlock()
+	corsAllowAll = allowAll
+	if len(origins) == 0 {
+		corsOrigins = nil
+		return
+	}
+	out := make([]string, len(origins))
+	copy(out, origins)
+	corsOrigins = out
+}
 
 // ServerConfig HTTP 服务监听配置。
 type ServerConfig struct {
@@ -52,6 +152,8 @@ var Server ServerConfig
 // 表示当前 XFF 解析模式:0=启发式,N>0=精确 N 跳。
 // setting.LogStartupSummary 读这个字段以展示运行期配置,
 // 不直接调用 middleware(避免循环 import)。
+//
+// 【并发】仅启动期被 InitRateLimiter 写一次,运行期只读,无并发问题,不加锁。
 var TrustedProxyHops int
 
 // SetupToken 是安装模式下的初始化凭证。
@@ -60,6 +162,8 @@ var TrustedProxyHops int
 //     打印到日志(/api/setup 提交时必须带这个 token)
 //
 // 安装完成后,/api/setup 端点永久关闭,SetupToken 失去意义但保留在内存。
+//
+// 【并发】仅 setup 阶段使用,运行期不会再写,无并发问题,不加锁。
 var SetupToken string
 
 // SetupTokenSource 标记 SetupToken 的来源,便于日志区分。
@@ -87,7 +191,7 @@ func InitServerConfig() {
 func InitAuthConfig() {
 	raw := os.Getenv("OPENAI_TTS_API_KEY")
 	if raw == "" {
-		Auth.APIKeys = nil
+		SetAuthAPIKeys(nil)
 		return
 	}
 	parts := strings.Split(raw, ",")
@@ -98,28 +202,28 @@ func InitAuthConfig() {
 			keys = append(keys, k)
 		}
 	}
-	Auth.APIKeys = keys
+	SetAuthAPIKeys(keys)
 }
 
 func InitCORSConfig() {
 	raw := os.Getenv("ALLOWED_ORIGINS")
-	CORS.Origins = nil
+	allowAll := false
-	CORS.AllowAll = false
+	var origins []string
-	if raw == "" {
+	if raw != "" {
-		return
-	}
 		for _, p := range strings.Split(raw, ",") {
 			o := strings.TrimSpace(p)
 			if o == "" {
 				continue
 			}
 			if o == "*" {
-			CORS.AllowAll = true
+				allowAll = true
 				continue
 			}
-		CORS.Origins = append(CORS.Origins, normalizeOrigin(o))
+			origins = append(origins, normalizeOrigin(o))
 		}
 	}
+	SetCORS(allowAll, origins)
+}
 
 func normalizeOrigin(origin string) string {
 	origin = strings.TrimSpace(origin)
@@ -129,7 +233,7 @@ func normalizeOrigin(origin string) string {
 
 // SplitOriginsForCORS 解析逗号/换行/空格分隔的 origins 列表,
 // 全部小写、trim 末尾 / 后面统一比较。导出供 controller 复用
-// (PUT /api/settings/cors 写完立即刷新 setting.CORS 用)。
+// (PUT /api/settings/cors 写完立即刷新 CORS 用)。
 func SplitOriginsForCORS(s string) []string {
 	return splitAndLowerOrigins(s)
 }
@@ -160,6 +264,9 @@ func splitAndLowerOrigins(s string) []string {
 //   - 失败时 TTSConfigErr 被设置,/v1/audio/speech 路由会返 503
 //   - 成功时清空 TTSConfigErr
 //
+// 【并发】所有写都走 Set* 系列函数,在 ttsMu.Lock 下完成;运行中的 TTS 请求
+// 用 Get* 拿快照不会读到半写状态。
+//
 // 字段映射(原 env → store key):
 //   BYTEDANCE_TTS_API_KEY        → api_key
 //   BYTEDANCE_TTS_RESOURCE_ID    → default_resource_id
@@ -180,8 +287,9 @@ func splitAndLowerOrigins(s string) []string {
 func LoadRuntimeConfig(s Store) error {
 	all, err := s.SettingsGetAll()
 	if err != nil {
-		TTSConfigErr = fmt.Errorf("read settings failed: %w", err)
+		wrapped := fmt.Errorf("read settings failed: %w", err)
-		return TTSConfigErr
+		SetTTSConfigErr(wrapped)
+		return wrapped
 	}
 
 	apiKey := all["api_key"]
@@ -198,8 +306,9 @@ func LoadRuntimeConfig(s Store) error {
 		missing = append(missing, "default_speaker")
 	}
 	if len(missing) > 0 {
-		TTSConfigErr = fmt.Errorf("missing required settings: %v", missing)
+		wrapped := fmt.Errorf("missing required settings: %v", missing)
-		return TTSConfigErr
+		SetTTSConfigErr(wrapped)
+		return wrapped
 	}
 
 	// 【BUG 修复 · 第二轮】default_speaker 是 voice **名字**(如 "chun"),
@@ -248,14 +357,15 @@ func LoadRuntimeConfig(s Store) error {
 		}
 	}
 
-	TTSTimeout = common.DefaultTimeout
+	timeout := common.DefaultTimeout
 	if v, err := s.SettingsGetDuration("timeout", common.DefaultTimeout); err == nil {
-		TTSTimeout = v
+		timeout = v
 	} else {
-		TTSTimeout = common.DefaultTimeout
+		timeout = common.DefaultTimeout
 	}
+	SetTTSTimeout(timeout)
 
-	TTSOptions = volcano.Options{
+	SetTTSOptions(volcano.Options{
 		APIKey:         apiKey,
 		ResourceID:     resourceId,
 		UID:            "uid",
@@ -268,18 +378,17 @@ func LoadRuntimeConfig(s Store) error {
 		LoudnessRate:   0,
 		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}
+		SetAuthAPIKeys([]string{authKey})
 	} else {
-		Auth.APIKeys = nil
+		SetAuthAPIKeys(nil)
 	}
 
 	// CORS 配置:DB > env
@@ -298,17 +407,14 @@ func LoadRuntimeConfig(s Store) error {
 		originsStr = os.Getenv("ALLOWED_ORIGINS")
 	}
 	if corsAllowAll {
-		CORS.AllowAll = true
+		SetCORS(true, nil)
-		CORS.Origins = nil
 	} else if originsStr != "" {
-		CORS.AllowAll = false
+		SetCORS(false, SplitOriginsForCORS(originsStr))
-		CORS.Origins = SplitOriginsForCORS(originsStr)
 	} else {
-		CORS.AllowAll = false
+		SetCORS(false, nil)
-		CORS.Origins = nil
 	}
 
-	TTSConfigErr = nil
+	SetTTSConfigErr(nil)
 	return nil
 }
 
@@ -388,10 +494,16 @@ func InitSetupToken() {
 
 // CheckEnvironmentVariables 返回 /health 用的环境变量状态快照。
 func CheckEnvironmentVariables() map[string]interface{} {
+	// 一次性拿所有需要的快照,缩短锁占用窗口;后续只读本地变量。
+	opts := GetTTSOptions()
+	authKeys := GetAuthAPIKeys()
+	allowAll := GetCORSAllowAll()
+	origins := GetCORSOrigins()
+
 	required := map[string]bool{
-		"BYTEDANCE_TTS_API_KEY":     TTSOptions.APIKey != "",
+		"BYTEDANCE_TTS_API_KEY":     opts.APIKey != "",
-		"BYTEDANCE_TTS_RESOURCE_ID": TTSOptions.ResourceID != "",
+		"BYTEDANCE_TTS_RESOURCE_ID": opts.ResourceID != "",
-		"BYTEDANCE_TTS_SPEAKER":     TTSOptions.Speaker != "",
+		"BYTEDANCE_TTS_SPEAKER":     opts.Speaker != "",
 	}
 	missing := []string{}
 	for k, ok := range required {
@@ -400,12 +512,12 @@ func CheckEnvironmentVariables() map[string]interface{} {
 		}
 	}
 	optional := map[string]bool{
-		"BYTEDANCE_TTS_MODEL":             TTSOptions.Model != "",
+		"BYTEDANCE_TTS_MODEL":             opts.Model != "",
-		"BYTEDANCE_TTS_FORMAT":            TTSOptions.Format != "mp3",
+		"BYTEDANCE_TTS_FORMAT":            opts.Format != "mp3",
-		"BYTEDANCE_TTS_SAMPLE_RATE":       TTSOptions.SampleRate != 24000,
+		"BYTEDANCE_TTS_SAMPLE_RATE":       opts.SampleRate != 24000,
-		"BYTEDANCE_TTS_EXPLICIT_LANGUAGE": TTSOptions.Additions != nil && TTSOptions.Additions.ExplicitLanguage != "",
+		"BYTEDANCE_TTS_EXPLICIT_LANGUAGE": opts.Additions != nil && opts.Additions.ExplicitLanguage != "",
-		"OPENAI_TTS_API_KEY":              len(Auth.APIKeys) > 0,
+		"OPENAI_TTS_API_KEY":              len(authKeys) > 0,
-		"ALLOWED_ORIGINS":                 CORS.AllowAll || len(CORS.Origins) > 0,
+		"ALLOWED_ORIGINS":                 allowAll || len(origins) > 0,
 		"PORT":                            Server.Port != common.DefaultPort,
 	}
 	return map[string]interface{}{
@@ -421,18 +533,21 @@ func LogStartupSummary() {
 	log.Printf("=== 环境配置汇总 ===")
 	log.Printf("服务端口: %s", Server.Port)
 
-	if len(Auth.APIKeys) == 0 {
+	authKeys := GetAuthAPIKeys()
+	if len(authKeys) == 0 {
 		log.Printf("OPENAI_TTS_API_KEY: 未设置(所有请求无需鉴权)")
 	} else {
-		log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(Auth.APIKeys))
+		log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(authKeys))
 	}
 
-	if CORS.AllowAll {
+	allowAll := GetCORSAllowAll()
+	origins := GetCORSOrigins()
+	if allowAll {
 		log.Printf("ALLOWED_ORIGINS: *(允许所有跨域;不可与鉴权共用)")
-	} else if len(CORS.Origins) == 0 {
+	} else if len(origins) == 0 {
 		log.Printf("ALLOWED_ORIGINS: 未设置(跨域请求将被拒绝)")
 	} else {
-		log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(CORS.Origins))
+		log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(origins))
 	}
 
 	if h := TrustedProxyHops; h == 0 {
@@ -441,6 +556,9 @@ func LogStartupSummary() {
 		log.Printf("TRUSTED_PROXY_HOPS: 精确模式,信任 %d 跳反代", h)
 	}
 
+	// 一次性拿 TTSOptions 快照;后续只读本地变量,避免在多个 log.Printf 调用之间
+	// 被 LoadRuntimeConfig 整体替换导致打印出不连贯的数据。
+	opts := GetTTSOptions()
 	log.Printf("火山 TTS 必填项状态:")
 	type ttsCheck struct {
 		name  string
@@ -448,10 +566,10 @@ func LogStartupSummary() {
 		ok    bool
 	}
 	checks := []ttsCheck{
-		{"BYTEDANCE_TTS_API_KEY", maskAPIKey(TTSOptions.APIKey), TTSOptions.APIKey != ""},
+		{"BYTEDANCE_TTS_API_KEY", maskAPIKey(opts.APIKey), opts.APIKey != ""},
-		{"BYTEDANCE_TTS_RESOURCE_ID", TTSOptions.ResourceID, TTSOptions.ResourceID != ""},
+		{"BYTEDANCE_TTS_RESOURCE_ID", telemetry.MaskResourceID(opts.ResourceID), opts.ResourceID != ""},
 		// speaker 是火山复刻音色 ID(用户付费资产),日志里打码,避免明文落盘
-		{"BYTEDANCE_TTS_SPEAKER", telemetry.MaskSpeaker(TTSOptions.Speaker), TTSOptions.Speaker != ""},
+		{"BYTEDANCE_TTS_SPEAKER", telemetry.MaskSpeaker(opts.Speaker), opts.Speaker != ""},
 	}
 	missingCount := 0
 	for _, c := range checks {
@@ -467,7 +585,7 @@ func LogStartupSummary() {
 		log.Printf("  %s %s: %s", mark, c.name, val)
 	}
 
-	if TTSConfigErr != nil {
+	if err := GetTTSConfigErr(); err != nil {
 		log.Printf("火山 TTS 整体: 初始化失败(%d 个必填项缺失),/v1/audio/speech 路由将全部返回 500", missingCount)
 	} else {
 		log.Printf("火山 TTS 整体: 初始化成功")

store/setup.go

@@ -0,0 +1,132 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// SetupApply 原子提交:settings 批量写入 + voices 全部插入,任一失败整体回滚,
+// 保证 db 不会留下半残状态(原 controller 直接调 SettingsSetBatch + 循环
+// VoiceInsert 时,voice 第 3 条失败 → settings 已写、voice 1/2 已落、voice 4
+// 没了,db 处于"装了一半"的脏状态,只能靠重启救)。
+//
+// 行为契约:
+//   - settingsKV 全部写入(settings 白名单校验复用 SettingsSetBatch 逻辑);
+//   - voices 逐条插入;ErrInvalid 校验错误 → 整体回滚,errors.Is(err, ErrInvalid) 仍可用;
+//   - voices 中已存在的 name 命中 ErrDuplicate → 静默跳过(不计 inserted,事务继续),
+//     兼容"重复 setup 同一组 voice"场景;
+//   - 其它 voice 错误 → 整体回滚;
+//   - 全部成功 → tx.Commit,返回 inserted count(不含被 ErrDuplicate 跳过的)。
+//
+// 不动 lock 文件:lock 由 controller 层(installer.CreateLock)管理,
+// 失败/成功都不应影响 db 事务(事务外)。
+func (s *Store) SetupApply(settingsKV map[string]string, voices []Voice) (inserted int, err error) {
+	tx, err := s.db.Begin()
+	if err != nil {
+		return 0, fmt.Errorf("store: setup apply begin: %w", err)
+	}
+	// defer Rollback:Commit 成功时 Rollback 返 sql.ErrTxDone,无害。
+	defer func() {
+		_ = tx.Rollback()
+	}()
+
+	// 1) 写 settings(同事务)
+	if len(settingsKV) > 0 {
+		if err := settingsSetBatchTx(tx, settingsKV); err != nil {
+			return 0, err
+		}
+	}
+
+	// 2) 逐条插 voice;ErrDuplicate 跳过,ErrInvalid/其它整体回滚
+	for i, v := range voices {
+		// trim 各字段,跟 VoiceInsert 保持一致(防止 controller 已经 trim 过但
+		// 未来调用方不 trim 时行为不一致)
+		v.Name = strings.TrimSpace(v.Name)
+		v.Speaker = strings.TrimSpace(v.Speaker)
+		v.ResourceID = strings.TrimSpace(v.ResourceID)
+		v.Model = strings.TrimSpace(v.Model)
+		v.Language = strings.TrimSpace(v.Language)
+		v.Description = strings.TrimSpace(v.Description)
+		// Enabled 走 setup 语义:用户主动配置时保留(允许 admin 预设 disabled);
+		// 但 controller.SetupSubmitHandler 走的是用户首次安装,统一 enabled=true。
+		// 这里不强制覆盖,保持原值(等同 VoiceInsert 行为)。
+
+		id, err := voiceInsertTx(tx, v)
+		if err != nil {
+			if errors.Is(err, ErrDuplicate) {
+				// 已存在,跳过(不计 inserted)
+				continue
+			}
+			// ErrInvalid / DB 错误等:整体回滚,把原始 error 透传(已 wrap ErrInvalid)
+			return 0, fmt.Errorf("store: setup apply voice[%d] %q: %w", i, v.Name, err)
+		}
+		_ = id // id 当前用不到,后续如果 controller 需要可加返回值
+		inserted++
+	}
+
+	if err := tx.Commit(); err != nil {
+		return 0, fmt.Errorf("store: setup apply commit: %w", err)
+	}
+	return inserted, nil
+}
+
+// settingsSetBatchTx 在已有 tx 上写 settings;逻辑跟 SettingsSetBatch 一致
+// 但用 tx 代替 s.db。失败时**不**回滚(交给 caller 决定);caller 拿 err 后
+// defer Rollback 兜底。
+func settingsSetBatchTx(tx *sql.Tx, kv map[string]string) error {
+	if len(kv) == 0 {
+		return nil
+	}
+	stmt, err := tx.Prepare(`
+		INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
+		ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
+	if err != nil {
+		return fmt.Errorf("store: settings setbatch prepare: %w", err)
+	}
+	defer stmt.Close()
+
+	for k, v := range kv {
+		if k == "" {
+			return fmt.Errorf("store: settings setbatch: empty key")
+		}
+		if !isAllowedSettingsKey(k) {
+			return fmt.Errorf("store: settings setbatch: key %q not in whitelist", k)
+		}
+		if _, err := stmt.Exec(k, v); err != nil {
+			return fmt.Errorf("store: settings setbatch exec %q: %w", k, err)
+		}
+	}
+	return nil
+}
+
+// voiceInsertTx 在已有 tx 上插 voice;跟 VoiceInsert 逻辑一致。
+// 校验(name 格式 / speaker / resource_id)用 ErrInvalid wrap;
+// 唯一冲突返 ErrDuplicate;其它错误返 wrap 的 db error。
+func voiceInsertTx(tx *sql.Tx, v Voice) (int64, error) {
+	if err := validateVoiceName(v.Name); err != nil {
+		return 0, fmt.Errorf("%w: %s", ErrInvalid, err.Error())
+	}
+	if v.Speaker == "" {
+		return 0, fmt.Errorf("%w: speaker is required", ErrInvalid)
+	}
+	if v.ResourceID == "" {
+		return 0, fmt.Errorf("%w: resource_id is required", ErrInvalid)
+	}
+	res, err := tx.Exec(`
+		INSERT INTO voices (name, speaker, resource_id, model, language, description, enabled, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))`,
+		v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled))
+	if err != nil {
+		if isUniqueViolation(err) {
+			return 0, ErrDuplicate
+		}
+		return 0, fmt.Errorf("store: voice insert: %w", err)
+	}
+	id, err := res.LastInsertId()
+	if err != nil {
+		return 0, fmt.Errorf("store: voice insert lastid: %w", err)
+	}
+	return id, nil
+}

store/voices.go

@@ -36,6 +36,11 @@ var ErrInUse = errors.New("store: voice is referenced by default_speaker")
 // ErrNotFound 表示按 id/name 找不到;controller 翻译为 404。
 var ErrNotFound = errors.New("store: voice not found")
 
+// ErrInvalid 表示客户端输入不合法(name 格式 / 必填字段缺失);
+// controller 用 errors.Is(err, ErrInvalid) 翻译为 400。
+// 服务端错误(DB 失败等)不会被 wrap,controller 应翻译为 500。
+var ErrInvalid = errors.New("store: voice invalid")
+
 // voiceNameRe 限制 voice 名为 [a-zA-Z0-9_-]{1,64};SQL 注入 + 路径穿越防护。
 var voiceNameRe = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
 
@@ -115,7 +120,9 @@ func (s *Store) GetVoiceForTTS(name string) (speaker, resourceID, model string,
 }
 
 // VoiceInsert 新增音色;name 冲突返回 ErrDuplicate。
-// 空字符串/格式不合法返回 error;不依赖 SQLite 约束作为唯一校验。
+// 客户端输入错误(name 格式 / 必填字段缺失)返回 wrap ErrInvalid 的 error;
+// 服务端错误(DB 失败等)不被 wrap,controller 用 errors.Is 区分。
+// 不依赖 SQLite 约束作为唯一校验。
 func (s *Store) VoiceInsert(v Voice) (int64, error) {
 	v.Name = strings.TrimSpace(v.Name)
 	v.Speaker = strings.TrimSpace(v.Speaker)
@@ -125,13 +132,14 @@ func (s *Store) VoiceInsert(v Voice) (int64, error) {
 	v.Description = strings.TrimSpace(v.Description)
 
 	if err := validateVoiceName(v.Name); err != nil {
-		return 0, err
+		// validateVoiceName 返纯文本;这里 wrap 进 ErrInvalid 让 controller 用 errors.Is 判定。
+		return 0, fmt.Errorf("%w: %s", ErrInvalid, err.Error())
 	}
 	if v.Speaker == "" {
-		return 0, fmt.Errorf("store: voice insert: speaker is required")
+		return 0, fmt.Errorf("%w: speaker is required", ErrInvalid)
 	}
 	if v.ResourceID == "" {
-		return 0, fmt.Errorf("store: voice insert: resource_id is required")
+		return 0, fmt.Errorf("%w: resource_id is required", ErrInvalid)
 	}
 
 	res, err := s.db.Exec(`
@@ -153,6 +161,12 @@ func (s *Store) VoiceInsert(v Voice) (int64, error) {
 
 // VoiceUpdate 整行替换;name 仍需保持唯一。
 // 不允许把 name 改成空/不合法。
+//
+// 同步 default_speaker:
+//   - 改 name 前,先查旧记录
+//   - 若 settings.default_speaker == 旧 name,把它改成新 name
+//   - 整个 voice UPDATE + settings UPDATE 在同一事务里,
+//     失败回滚,避免"声音改了但 default_speaker 还指向旧名"导致火山查不到
 func (s *Store) VoiceUpdate(v Voice) error {
 	v.Name = strings.TrimSpace(v.Name)
 	v.Speaker = strings.TrimSpace(v.Speaker)
@@ -171,7 +185,47 @@ func (s *Store) VoiceUpdate(v Voice) error {
 		return fmt.Errorf("store: voice update: resource_id is required")
 	}
 
-	res, err := s.db.Exec(`
+	// 整段事务: 读旧名 → 同步 settings → UPDATE voice
+	tx, err := s.db.Begin()
+	if err != nil {
+		return fmt.Errorf("store: voice update begin: %w", err)
+	}
+	defer func() {
+		// commit 成功时 Rollback 返回 sql.ErrTxDone,无害
+		_ = tx.Rollback()
+	}()
+
+	// 1. 读旧名(同事务,避免并发改)
+	var oldName string
+	if err := tx.QueryRow(`SELECT name FROM voices WHERE id = ?`, v.ID).Scan(&oldName); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		return fmt.Errorf("store: voice update read old name id=%d: %w", v.ID, err)
+	}
+
+	// 2. 若 name 变了 + 是默认音色 → 同步 default_speaker
+	if oldName != v.Name {
+		var defVal string
+		err := tx.QueryRow(`SELECT value FROM settings WHERE key = 'default_speaker'`).Scan(&defVal)
+		switch {
+		case errors.Is(err, sql.ErrNoRows):
+			// 没设 default_speaker,无事可做
+		case err != nil:
+			return fmt.Errorf("store: voice update read default_speaker: %w", err)
+		case defVal == oldName:
+			// 同步改名为新名
+			if _, err := tx.Exec(`
+				INSERT INTO settings (key, value, updated_at) VALUES ('default_speaker', ?, datetime('now'))
+				ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+				v.Name); err != nil {
+				return fmt.Errorf("store: voice update sync default_speaker: %w", err)
+			}
+		}
+	}
+
+	// 3. UPDATE voice
+	res, err := tx.Exec(`
 		UPDATE voices SET name=?, speaker=?, resource_id=?, model=?, language=?, description=?, enabled=?, updated_at=datetime('now')
 		WHERE id = ?`,
 		v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled), v.ID)
@@ -185,6 +239,11 @@ func (s *Store) VoiceUpdate(v Voice) error {
 	if n == 0 {
 		return ErrNotFound
 	}
+
+	// 4. 提交
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("store: voice update commit: %w", err)
+	}
 	return nil
 }
 

telemetry/labels.go

@@ -41,14 +41,29 @@ func SpeakerLabel(s string) string {
 //   - 其它 → 前 4 + **** + 后 4 (保留前缀便于肉眼区分 "S_xx 开头" vs "BV001_...")
 // 例子: "S_G8tEKnaJ1" → "S_G8****naJ1"
 func MaskSpeaker(s string) string {
+	return maskWithAffix(s, "(未设置)")
+}
+
+// MaskResourceID 把火山 TTS 资源 ID 部分打码用于日志输出。
+// 资源 ID 同样属于用户付费/敏感资产(指向 V3 复刻项目),与 speaker 走同一规则。
+//   - 空 → "(未设置)"
+//   - 长度 ≤ 4 → 全打码
+//   - 其它 → 前 4 + **** + 后 4
+// 例子: "volc.megatts.icl" → "volc****.icl"; "seed-icl-2.0" → "seed****2.0"
+func MaskResourceID(s string) string {
+	return maskWithAffix(s, "(未设置)")
+}
+
+// maskWithAffix 共用的"前 4 + **** + 后 4"打码逻辑,空串返回 emptyLabel。
+func maskWithAffix(s, emptyLabel string) string {
 	if s == "" {
-		return "(未设置)"
+		return emptyLabel
 	}
 	if len(s) <= 4 {
 		return strings.Repeat("*", len(s))
 	}
 	// 找前 4 字符中第一个非 [A-Za-z0-9_] 字符做截断,避免截到奇怪位置
-	// (虽然火山 ID 实际都是 S_xxx 字母数字组合,这里保险)
+	// (虽然火山 ID 实际都是字母数字组合,这里保险)
 	prefix := s[:4]
 	suffix := s[len(s)-4:]
 	return prefix + "****" + suffix