ci(docker): 合并为单一 GHCR+DockerHub 双推送 workflow,加 GHA 缓存

原 .github/workflows/docker.yml:
  - 触发: v* tag + 手动
  - 仅推 GHCR
  - 无 build 缓存
  - buildx action v5

新版本:
  - 触发: v*.*.* tag (限定 semver, 避免 vtest 误触发) + 手动按钮
  - 双 registry 推送: GHCR (默认) + DockerHub (blueink05/ttshub,需 secrets)
  - GHA buildx cache (cache-from + cache-to, mode=max): 首次 ~3-5 min, 后续 30-60s
  - buildx action v6
  - multi-arch (amd64+arm64, 不变)
  - tag 策略: semver + major.minor + tag->latest + short sha
  - 安全网: secrets.DOCKERHUB_USERNAME 空时自动跳过 DockerHub login + image name 渲染,
    避免生成 'docker.io//ttshub' 这种非法 image 名
  - 不验 PR 编译(合到 main 不重跑, 只在打 tag 时构建)
  - workflow_dispatch 推镜像: push 表达式保留 '!= pull_request' 兼容未来扩展

需要 GitHub repo 配置的 secrets:
  - DOCKERHUB_USERNAME = blueink05
  - DOCKERHUB_TOKEN    = (hub.docker.com/settings/security 拿 access token)
没加之前,DockerHub login 步骤被 actions 自动跳过,只推 GHCR 一份。

Dockerfile / docker-compose.yml / .dockerignore 不动(Dockerfile 1.26-alpine
base image 已确认存在,tags list 拉到 tip-20260920)。

.dockerignore

@@ -0,0 +1,10 @@
+*.exe
+*.md
+.env
+.env.*
+!.env.example
+.git
+.gitignore
+tts_api_architecture.html
+代码审查报告.md
+fix_list.md

.env.example

@@ -1,39 +1,33 @@
-# ByteDance 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)
-# 语音合成模型：
+#    Docker 部署务必改成挂载路径,例: /data/tts.db
-#   - seed-tts-1.0: 豆包语音合成模型1.0字符版
+# TTS_DB_PATH=/data/tts.db
-#   - seed-tts-1.0-concurr: 豆包语音合成模型1.0并发版
-#   - seed-tts-2.0: 豆包语音合成模型2.0字符版
-# 声音复刻模型：
-#   - seed-icl-1.0: 声音复刻1.0字符版
-#   - seed-icl-1.0-concurr: 声音复刻1.0并发版
-#   - seed-icl-2.0: 声音复刻2.0字符版
-BYTEDANCE_TTS_RESOURCE_ID=seed-tts-1.0
 
-# 发音人（音色）ID，具体参考火山引擎音色列表
+# 3. 服务监听端口(可选, 默认 8080)
-# 注意：1.0音色只能搭配 seed-tts-1.0 Resource ID
-#       2.0音色只能搭配 seed-tts-2.0 Resource ID
-BYTEDANCE_TTS_SPEAKER=your_speaker_id_here
-
-# ==========================================
-# 可选的环境变量
-# ==========================================
-
-# 请求超时时间，默认30秒
-BYTEDANCE_TTS_TIMEOUT=30s
-
-# OpenAI兼容接口的API密钥（可选）
-# 配置后，客户端请求需要携带 Authorization: Bearer <OPENAI_TTS_API_KEY>
-OPENAI_TTS_API_KEY=your_openai_compatible_key_here
-
-# 服务监听端口，默认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

.gitea/workflows/deploy.yml

@@ -1,36 +0,0 @@
-name: Go CI/CD Deploy to Baota
-
-on:
-  push:
-    branches: [ main, master ]
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: 拉取代码
-        uses: actions/checkout@v4
-
-      - name: 安装 Go 环境
-        uses: actions/setup-go@v5
-        with:
-          go-version: 1.22
-
-      - name: 编译 Go 项目
-        run: |
-          # 静态编译，无依赖，适合 Linux 部署
-          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app main.go
-
-      - name: 部署到宝塔项目目录并重启服务
-        run: |
-          # 1. 停止旧进程
-          pkill -f Volcano-Engine-TTS-UI || true
-          
-          # 2. 复制新程序到项目目录
-          cp ./app /www/wwwroot/Volcano-Engine-TTS-UI/
-          
-          # 3. 赋予执行权限
-          chmod +x /www/wwwroot/Volcano-Engine-TTS-UI/app
-          
-          # 4. 启动新进程（后台运行）
-          nohup /www/wwwroot/Volcano-Engine-TTS-UI/app > /www/wwwroot/Volcano-Engine-TTS-UI/app.log 2>&1 &

.github/workflows/docker.yml

@@ -0,0 +1,95 @@
+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*.*.*'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 拉完整历史,git describe 能取到 tag
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        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: github.event_name != 'pull_request' && secrets.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version from git
+        id: version
+        run: |
+          echo "version=$(git describe --tags --always --dirty)" >> "$GITHUB_OUTPUT"
+          echo "commit=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          # 多个 image base:metadata-action 会为每个 base 渲染完整 tag 列表。
+          # DockerHub image 用 enable 保护:username secret 没设时不渲染,避免非法 image 名。
+          images: |
+            name=${{ env.REGISTRY }}/${{ github.repository }}
+            name=docker.io/${{ secrets.DOCKERHUB_USERNAME }}/ttshub,enable=${{ secrets.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@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          # 当前触发器只有 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: |
+            VERSION=${{ steps.version.outputs.version }}
+            COMMIT=${{ steps.version.outputs.commit }}

.gitignore

@@ -0,0 +1,46 @@
+# Go build cache
+.gocache/
+*.exe
+*.test
+*.out
+
+# Go test sources (prevent accidental commit; tests live outside the repo by policy)
+*_test.go
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Secrets (do NOT commit local .env files; keep .env.example tracked as template)
+.env
+.env.*
+!.env.example
+
+# Local-only working notes (use task board for shared tracking)
+TODO.md
+
+# Release artifacts (build output)
+release/
+
+# Local build output (start-local.ps1 builds to bin/)
+bin/
+
+# Local dev scripts (per-user; not part of repo)
+start-local.ps1
+
+# Runtime database artifacts (created by M1 installer flow)
+tts.db
+tts.db-*
+tts.db.*
+installed.lock
+
+# UI handoff bundle (for external AI redesign work; not deployed)
+ui-handoff/
+
+# Docs (本地草稿,不入库)
+docs/

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。
+
+## [0.2.0] - 2026-08-30
+
+### 新增
+
+- **M0 · SQLite + store 包**: 引入 `modernc.org/sqlite` (无 CGO), 所有运行时配置 (settings + voices) 持久化到 SQLite
+- **M1 · 安装流程**: 首次启动进入 `/setup` 向导, 通过 4 步表单收集凭证 + 默认音色 + 音色列表, 完成后写 `installed.lock` 锁定
+  - 引导页无外部依赖: Vue 3.4 + axios 1.6 via bootcdn, `//go:embed` 进 binary
+  - **自愈回退**: 检测到 DB 损坏自动备份 + 转 setup 模式 (不丢数据)
+- **M2 · WebUI 后台**: `/admin` 单页 SPA, 含登录 / 仪表盘 / 音色管理 / 设置 / CORS 配置
+  - 默认鉴权基于 `auth_key` (DB), 失败计数 + 限流
+  - 浏览器安装修复: 同源请求跳过 CORS 校验, install 模式完全跳过 CORS
+- **M3 · 全局设置 + 声音路由**:
+  - `default_speaker` 是 voice **名字** (如 `chun`), 路由时查 voice 表拿到真 speaker ID (如 `S_G8tEKnaJ1`)
+  - `/v1/audio/speech` 支持 `voice=<name>` 动态路由, 命中但 enabled=0 返回 403
+  - 未知 voice 返回 400 `unknown_voice: '<name>'`
+  - 禁用 voice 返回 403 `voice '<name>' is disabled`
+- **OpenAI 端 key 走 DB**: `auth_key` 设置项, 不再依赖 `OPENAI_TTS_API_KEY` env
+- **CORS 全 DB 化**: `cors_origins` / `cors_allow_all` 走 `/admin` 设置, install 模式跳过
+- **CORS 修复**: 同源请求跳过 CORS 校验 (避免浏览器自家人拦自家人)
+- **运营工具**: `cmd/dumpdb` — 离线 dump tts.db 的 settings + voices
+- **fail-fast**: normal 模式下 TTS 配置损坏 → `log.Fatalf` 退出, 触发 K8s / Docker 重启
+  - 配套 metric `tts_config_load_failures_total{mode="normal"}` 便于告警
+  - `/health` body 加 `error` 字段直接展示失败原因
+- **speaker ID 隐私保护**: 日志里 `telemetry.MaskSpeaker` (`S_G8****naJ1`); `/metrics` 标签用 `telemetry.SpeakerLabel` (sha1[:8])
+
+### 修复
+
+- **resource_id 覆盖**: `LoadRuntimeConfig` 之前用 voice 行的 `resource_id` 覆盖 settings 里的, 导致用户设的 `default_resource_id` 永远没机会生效。现在 settings 优先, voice 行的 resource_id 仅在 `voice=` 显式传时使用
+- **默认值修正**: 把过时的 `volc.megatts.icl` / `volc.megatts.default` 全部改成 v3 API 2.0 复刻项目唯一合法的 `seed-icl-2.0`; 模型名统一 `seed-tts-2.0-standard`
+- **log 格式一致**: voice 命中 log 跟合成 log 同样打码
+- **setup UX 改进**: voice 行 `resource_id` 留空时, 自动用 settings 里的 `default_resource_id` 兜底, 避免 settings / voice 资源 ID 不一致导致 500
+- **/admin dashboard banner 误报**: `reloadAll()` 加 `loadSettings()`, 避免 "CORS 未配置" 黄条永远显示
+
+### 变更
+
+- **.env.example 收敛**: 移除 `BYTEDANCE_TTS_*` 业务 env, 只留 4 个引导 env (`TTS_ADMIN_KEY` / `TTS_DB_PATH` / `PORT` / `OPENAI_TTS_API_KEY`); 业务配置走 WebUI
+- **docker-compose**: 加 `tts-data` named volume 持久化 tts.db
+- **Dockerfile**: 准备 `/data` 目录, appuser 可写, 解决 tts.db 落盘权限
+
+## [0.1.0] - 初版
+
+- 火山 TTS v3 → OpenAI 兼容 `/v1/audio/speech` 单二进制
+- 配置全 env 驱动 (`BYTEDANCE_TTS_*` 11 个)
+- 限流 / 鉴权 / Prometheus metrics / CORS / 反代 XFF 解析

Dockerfile

@@ -0,0 +1,42 @@
+FROM golang:1.26-alpine AS builder
+
+WORKDIR /app
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# VERSION 由 CI/CD 传入,通常为 `git describe --tags --always --dirty` 的输出
+# COMMIT 为 `git rev-parse --short HEAD`
+# 本地默认 dev
+ARG VERSION=dev
+ARG COMMIT=dev
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags "-X github.com/volcano-tts/tts-api/version.Version=${VERSION} \
+              -X github.com/volcano-tts/tts-api/version.Commit=${COMMIT}" \
+    -o tts-api .
+
+FROM alpine:3.21
+
+RUN apk --no-cache add ca-certificates tzdata \
+    && addgroup -S appgroup && adduser -S appuser -G appgroup
+
+WORKDIR /app
+
+COPY --from=builder /app/tts-api .
+# health.html 已通过 //go:embed 嵌入 binary,无需单独复制
+
+# 准备 /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=10s --retries=3 \
+    CMD wget -qO- http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["./tts-api"]

PROJECT_BOOK.md

@@ -0,0 +1,391 @@
+# 火山 TTS 聚合平台 · 项目书（v0.1）
+
+> 定位：个人自用（无甲方）· 单机部署 · 单二进制分发
+> 基线代码：Volcano-Engine-TTS-UI（develop 分支，Go，约 2900 行）
+
+---
+
+## 1. 项目概述
+
+### 1.1 背景与动机
+
+现有 `Volcano-Engine-TTS-UI` 是一个"火山引擎 TTS v3 → OpenAI 兼容接口"的适配器，已具备 `/v1/audio/speech`、多格式输出、鉴权限流、Prometheus 观测等能力。当前存在三个核心问题：
+
+1. **配置全部堆在环境变量里**：API Key、资源 ID、音色、采样率……随音色增长会持续"溢出"，无法维护。
+2. **音色是静态的**：`voice`/`model` 请求字段被接收但忽略，只支持 env 里配死的单音色。
+3. **首次启动没有入口**：无 UI、无数据库，配置只能靠手写 env。
+
+### 1.2 项目目标
+
+把该项目升级为**自用聚合平台**：
+
+- 用 **SQLite** 接管所有运行时可变配置（全局设置 + 音色库），环境变量只保留 3 个左右引导参数；
+- 提供**引导式安装 UI**：首次启动（未安装）进入 `/setup` 向导收集配置，写入数据库后即完成安装；
+- 采用 **lock 文件**作为安装状态判据，支持"损坏自动回退、可重置安装"；
+- `/v1/audio/speech` 的 `voice` 参数**按数据库路由**，实现多音色动态切换；
+- 保持**单二进制分发**（SQLite 用纯 Go 驱动，`//go:embed` 嵌入引导页）。
+
+### 1.3 设计原则
+
+| 原则 | 说明 |
+|---|---|
+| 数据库为唯一配置源 | 运行时的全局参数、音色全部读库，不做"库 + env 双轨" |
+| 环境变量只做引导 | 仅保留 DB 路径、端口、初始化凭证 |
+| lock 是安装门卫 | 存在 = 已安装；不存在 = 安装模式；损坏 = 备份 + 删 lock + 回退 |
+| 损坏可自愈 | 库异常自动备份留档并回退安装模式，不裸奔 |
+| 先内核后 UI | 本期只做"引导页"（安装必需），完整管理后台后置 |
+
+---
+
+## 2. 需求范围
+
+### 2.1 本期（MVP）范围
+
+| 编号 | 需求 | 说明 |
+|---|---|---|
+| R1 | SQLite 接入 | `modernc.org/sqlite`（纯 Go、无 CGO），自动建表、轻量迁移 |
+| R2 | 全局配置入库 | `settings` 表接管现有全部 TTS 全局环境变量 |
+| R3 | 音色库 | `voices` 表：name → speaker/resource_id/model/…，支持增删改查 |
+| R4 | 安装状态检测 | `installed.lock` 判据 + 启动判定流程 |
+| R5 | 引导式安装 UI | `/setup` 引导页（首次启动数据收集）+ `POST /api/setup` |
+| R6 | 安装模式路由守卫 | 未安装时全站只开放 `/setup`，其余返回 503/跳转 |
+| R7 | voice 动态路由 | `/v1/audio/speech` 按 `voice` 查库路由到火山 |
+| R8 | 音色管理 API | `GET/POST /api/voices`、`PUT/DELETE /api/voices/:id`（带鉴权） |
+| R9 | 损坏回退 | 库校验失败 → 备份 `.corrupt-<ts>` → 删 lock → 重新安装 |
+| R10 | 环境变量收敛 | 迁移后 env 仅剩：`TTS_DB_PATH`、`PORT`、初始化凭证 |
+
+### 2.2 后置（不在本期）
+
+- 完整管理后台（音色列表/用量图表/配置管理）
+- 多服务商聚合（火山 / OpenAI / 微软统一适配）
+- 流式实时输出（SSE/WebSocket）
+- TTS 结果缓存、长文本自动分片、字幕透出
+- ASR 转写端点（`/v1/audio/transcriptions`）
+
+---
+
+## 3. 总体架构
+
+```
+┌───────────────────────────── 单二进制 tts-api ─────────────────────────────┐
+│                                                                              │
+│  main.go ── 启动：初始化 DB → 安装状态检测 → 加载配置 → 路由 → 监听            │
+│                                                                              │
+│  ┌────────────┐   ┌─────────────┐   ┌────────────────────────────────────┐   │
+│  │ installer/ │──▶│   store/    │   │             router/                │   │
+│  │ lock 检测  │   │ SQLite 访问 │   │  /setup(引导页·embed)  /api/setup  │   │
+│  │ 安装模式   │   │ settings    │   │  /api/voices*        /v1/audio/speech│ │
+│  └────────────┘   │ voices      │   │  /health /metrics /dashboard        │   │
+│                   └─────────────┘   └────────────────────────────────────┘   │
+│                                                                              │
+│  controller/ ── 语音合成(查库路由) · setup · voices CRUD                      │
+│  middleware/ ── 鉴权 · 限流 · 并发 · 安装守卫                                 │
+│  setting/    ── 仅保留引导参数(DB路径/端口/凭证) + 启动汇总                    │
+│  adapter/volcano/ ── 火山 v3 客户端（不改，仅入参来源变为 DB）                 │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. 技术选型
+
+| 项 | 选型 | 理由 |
+|---|---|---|
+| 语言 | Go（沿用） | 现有项目基线，无迁移成本 |
+| 数据库 | SQLite（`modernc.org/sqlite`） | 纯 Go 无 CGO，保持 `CGO_ENABLED=0` 单二进制；单文件零运维 |
+| 前端 | Vue3 + axios（沿用 dashboard 技术栈） | 复用现有 `//go:embed` 模式，`setup.html` 嵌入二进制 |
+| 路由 | gorilla/mux（沿用） | 现有实现 |
+| 构建 | 保持单二进制 | `//go:embed` 内嵌引导页与监控页 |
+
+> 依赖注意：`modernc.org/sqlite` 体积较大（约 30-40MB 二进制），如介意可换 `mattn/go-sqlite3`（需 CGO，破坏单二进制），**本项目选前者**。
+
+---
+
+## 5. 数据模型设计
+
+### 5.1 `settings` 表（全局配置）
+
+```sql
+CREATE TABLE IF NOT EXISTS settings (
+    key        TEXT PRIMARY KEY,      -- 配置键名
+    value      TEXT NOT NULL,          -- 配置值（统一存字符串，读取时按需转换）
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+初始化后必填的键：
+
+| key | 说明 | 来源（原环境变量） |
+|---|---|---|
+| `api_key` | 火山 API Key | `BYTEDANCE_TTS_API_KEY` |
+| `default_resource_id` | 默认资源 ID | `BYTEDANCE_TTS_RESOURCE_ID` |
+| `default_speaker` | 默认音色 | `BYTEDANCE_TTS_SPEAKER` |
+| `initialized` | 安装完成标记 `"1"` | —（双保险，配合 lock） |
+
+可选键（读取时带默认值）：
+
+| key | 默认值 | 来源 |
+|---|---|---|
+| `default_format` | `mp3` | `BYTEDANCE_TTS_FORMAT` |
+| `sample_rate` | `24000` | `BYTEDANCE_TTS_SAMPLE_RATE` |
+| `timeout` | `30s` | `BYTEDANCE_TTS_TIMEOUT` |
+| `model` | 空 | `BYTEDANCE_TTS_MODEL` |
+| `model_type` | 空 | `BYTEDANCE_TTS_MODEL_TYPE` |
+| `explicit_language` | 空 | `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` |
+| `enable_subtitle` | `false` | `BYTEDANCE_TTS_ENABLE_SUBTITLE` |
+
+> 迁移建议：首次安装时若检测到旧的对应环境变量仍存在，可作为引导页**预填默认值**（仅预填，不替代库），便于老用户平滑迁移。
+
+### 5.2 `voices` 表（音色库）
+
+```sql
+CREATE TABLE IF NOT EXISTS voices (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT NOT NULL UNIQUE,   -- 对外 voice 名，请求里 voice 字段查它
+    speaker     TEXT NOT NULL,          -- 火山音色 ID（复刻音色以 S_ 开头）
+    resource_id TEXT NOT NULL,          -- 对应火山资源 ID（决定计费/模型族）
+    model       TEXT DEFAULT '',        -- 子模型 seed-tts-2.0-standard / -expressive
+    language    TEXT DEFAULT '',        -- 显式语种（可选）
+    description TEXT DEFAULT '',        -- 备注
+    enabled     INTEGER NOT NULL DEFAULT 1,  -- 0/1 启用
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_voices_name ON voices(name);
+```
+
+> 默认音色：`settings.default_speaker` 表示请求**未传 voice** 时用的音色；也可以约定默认 voice 名为 `default` 的行，二选一，建议用 settings 字段（更直观）。
+
+---
+
+## 6. 安装与启动流程设计
+
+### 6.1 lock 判据
+
+- lock 文件：`<DB目录>/installed.lock`（与 `tts.db` 同目录）。
+- **存在 = 已成功完成过安装**；不存在 = 未安装。
+- lock 内容：一行文本 `version <版本号> <初始化时间>`，便于未来判断是否需要重装/迁移。
+- 写入时机：**先写库、后写 lock**（`/api/setup` 成功后、且通过完整性校验后才原子创建 lock），避免"lock 在、库是半成品"。
+- **不用 `.db` 文件是否存在作为安装判据**（建表会自动创建 db 文件，无法区分"从未安装"和"已安装"）。
+
+### 6.2 启动判定流程
+
+```
+main 启动
+  ├─ 解析引导环境变量（TTS_DB_PATH / PORT / 初始化凭证）
+  ├─ store.Open()（打开/创建 SQLite，自动建表）
+  │
+  ├─ installed.lock 不存在？
+  │    └─ YES → 进入【安装模式】：仅开放 /setup（静态资源 + 引导页 + POST /api/setup）
+  │            其余路由（/v1/audio/speech、/api/voices 等）→ 503 + 跳转 /setup
+  │    └─ NO  → 尝试读库 + PRAGMA integrity_check
+  │              ├─ 通过 → 加载 settings/voices 到内存缓存 → 【正常模式】
+  │              └─ 失败 → 备份 tts.db → tts.db.corrupt-<时间戳>
+  │                        → 删除 installed.lock → 进入【安装模式】
+  │
+  └─ 打印启动摘要（模式 / DB路径 / lock状态 / 音色数）
+```
+
+### 6.3 损坏回退规则
+
+1. 只在 lock 存在但库打不开 / `integrity_check` 失败时触发回退；
+2. **先备份**：损坏的 `.db` 改名 `tts.db.corrupt-<ts>` 留档，不直接删除；
+3. 删除 `installed.lock`，进入安装模式；
+4. 日志明确打印回退原因（文件损坏 / 权限 / 磁盘 / 版本等），便于排查；
+5. 回退后用户重新走 `/setup` 即可恢复。
+
+### 6.4 setup 劫持防护（必须）
+
+安装模式是"谁先访问谁配置"，公网暴露时存在被抢先初始化的风险。防护方案（至少一项）：
+
+- **A（推荐）初始化凭证**：启动时打印一次性 setup token（或从环境变量 `TTS_ADMIN_KEY` 指定），引导页提交时必须带 token，校验通过才写入；
+- **B 回环限制**：安装模式下 `/setup` 仅允许本机回环地址访问（`127.0.0.1`），初始化完成后即失效；
+- 二者可叠加。初始化完成后 `/api/setup` 永久关闭。
+
+---
+
+## 7. 接口设计
+
+### 7.1 安装相关
+
+| 方法 | 路径 | 说明 | 鉴权 |
+|---|---|---|---|
+| GET | `/setup` | 引导页 HTML（`//go:embed`） | 安装模式开放 |
+| GET | `/api/setup/status` | 返回 `{installed: bool}`，供引导页判断 | 无 |
+| POST | `/api/setup` | 提交初始配置（全局 + 音色列表 + token）→ 写库 → 写 lock | 初始化凭证 |
+
+`POST /api/setup` 请求体示例：
+
+```json
+{
+  "token": "一次性凭证",
+  "settings": {
+    "api_key": "xxx",
+    "default_resource_id": "volc.megatts.default",
+    "default_speaker": "zh_female_qingxin",
+    "default_format": "mp3",
+    "sample_rate": 24000
+  },
+  "voices": [
+    { "name": "qian",  "speaker": "S_xxx", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-standard" },
+    { "name": "xun",   "speaker": "S_yyy", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-expressive" }
+  ]
+}
+```
+
+响应：`200 {ok:true, message:"installed"}` 或 `400/401/409`。
+
+### 7.2 音色管理（正常模式）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/voices` | 列表（可分页/过滤 enabled） |
+| POST | `/api/voices` | 新增音色（name 唯一冲突返回 409） |
+| PUT | `/api/voices/:id` | 更新音色 |
+| DELETE | `/api/voices/:id` | 删除音色（`default_speaker` 引用的音色禁止删除） |
+
+鉴权：复用现有 `OPENAI_TTS_API_KEY`（Bearer）。若安装后用户未配置管理 Key，可提示在 settings 中配置。
+
+### 7.3 语音合成（改造点）
+
+`/v1/audio/speech` 改造逻辑：
+
+```
+收到请求
+  ├─ voice 为空 → 用 settings.default_speaker（无默认 → 400 "no default voice"）
+  ├─ voice 非空 → 查 voices 表
+  │    ├─ 命中 → 用该行 speaker/resource_id/model/language 覆盖 opts
+  │    └─ 未命中 → 400 "unknown voice: <name>"
+  ├─ model 非空 → 查库/映射（本期：model 仅校验长度，不做映射，或按 settings 默认）
+  └─ 其余逻辑不变（格式解析、speed、鉴权、限流、埋点）
+```
+
+### 7.4 现有端点（不变）
+
+`/health`、`/metrics`、`/dashboard`、`/` 行为保持；但**安装模式下**除 `/setup` 外统一返回 503（`/health` 可返回 `installed:false` 便于部署探针识别未初始化）。
+
+---
+
+## 8. 模块划分与代码改动清单
+
+### 8.1 新增包
+
+| 包 | 职责 | 关键文件 |
+|---|---|---|
+| `store/` | SQLite 访问层：打开/建表/迁移、settings CRUD、voices CRUD、integrity_check | `db.go`、`settings.go`、`voices.go`、`migrate.go` |
+| `installer/` | 安装状态：lock 检测/创建/删除、安装模式判定、损坏回退 | `lock.go`、`bootstrap.go` |
+
+### 8.2 改造文件
+
+| 文件 | 改动 |
+|---|---|
+| `router/router.go` | 新增 `/setup`、`/api/setup/*`、`/api/voices`；安装模式路由守卫 |
+| `controller/` | 新增 `setup.go`（安装提交）、`voices.go`（CRUD）；改造 `tts.go`（voice 查库路由） |
+| `middleware/` | 新增 `installguard.go`（安装模式拦截，未安装非 `/setup` → 503） |
+| `setting/config.go` | 收敛：仅读 `TTS_DB_PATH`、`PORT`、初始化凭证；启动汇总展示"模式/lock/音色数" |
+| `main.go` | 启动流程：初始化 DB → 安装检测 → 模式分支 |
+| `router/setup.html` | 新增引导页（Vue3 + axios，`//go:embed`） |
+| `go.mod` | 新增 `modernc.org/sqlite` |
+| `.env.example` / `README.md` / `docker-compose.yml` | 更新为新的引导参数与首次安装说明 |
+
+### 8.3 环境变量收敛表
+
+**迁移前（现状，会持续膨胀）：**
+
+```
+BYTEDANCE_TTS_API_KEY
+BYTEDANCE_TTS_RESOURCE_ID
+BYTEDANCE_TTS_SPEAKER
+BYTEDANCE_TTS_FORMAT
+BYTEDANCE_TTS_SAMPLE_RATE
+BYTEDANCE_TTS_BIT_RATE
+BYTEDANCE_TTS_MODEL
+BYTEDANCE_TTS_MODEL_TYPE
+BYTEDANCE_TTS_EXPLICIT_LANGUAGE
+BYTEDANCE_TTS_ENABLE_SUBTITLE
+BYTEDANCE_TTS_TIMEOUT
+BYTEDANCE_TTS_DEBUG
+OPENAI_TTS_API_KEY
+ALLOWED_ORIGINS
+TRUSTED_PROXY_HOPS
+PORT
+```
+
+**迁移后（仅引导参数，其余进库）：**
+
+```
+TTS_DB_PATH        # 数据库/lock 目录（默认 ./）
+PORT               # 监听端口
+TTS_ADMIN_KEY      # 安装初始化凭证（可选，不设则启动打印一次性 token）
+OPENAI_TTS_API_KEY # 管理 API / 合成 API 鉴权（可选，迁移进 settings 或保留）
+ALLOWED_ORIGINS    # CORS（可保留，属运行环境而非业务配置）
+TRUSTED_PROXY_HOPS # 反代拓扑参数（保留，属部署环境）
+```
+
+> `BYTEDANCE_TTS_DEBUG`、`TRUSTED_PROXY_HOPS`、`ALLOWED_ORIGINS` 属"部署/运维环境"而非"业务配置"，可留在 env；其余 TTS 业务配置全部进库。
+
+---
+
+## 9. 安全设计
+
+| 项 | 措施 |
+|---|---|
+| Setup 劫持 | 初始化凭证（`TTS_ADMIN_KEY` 或一次性 token）+ 可选回环限制；完成后 `/api/setup` 永久关闭 |
+| 合成/管理鉴权 | 复用 `OPENAI_TTS_API_KEY`（Bearer）；voice 路由不绕过鉴权 |
+| 敏感信息 | API Key 在引导页只进不出；日志/`/health` 不回显明文 Key（沿用 `maskAPIKey`） |
+| 输入校验 | voice 名白名单（字母数字 `_-`）、长度限制；SQL 全部参数化，防注入 |
+| lock/DB 写入 | 先写库后写 lock；lock 原子创建；损坏先备份再回退 |
+| 默认音色保护 | 删除被 `default_speaker` 引用的音色时拒绝（409） |
+
+---
+
+## 10. 开发计划与里程碑
+
+| 里程碑 | 内容 | 验收标准 |
+|---|---|---|
+| M1 存储层 | `store/` 包：SQLite 接入、两表建表、迁移、settings/voices CRUD、`integrity_check` | `go build` 通过；单测覆盖 CRUD |
+| M2 安装流程 | `installer/`：lock 检测/创建/删除、安装模式判定、损坏回退；`middleware/installguard` | 无 lock → 安装模式；有 lock → 正常模式；损坏库 → 备份+回退 |
+| M3 引导 UI | `/setup` 引导页 + `POST /api/setup`（token 校验、写库、写 lock） | 首次访问可完成安装；重复安装被拒；token 错误 401 |
+| M4 音色路由 | `/api/voices` CRUD + `/v1/audio/speech` voice 查库路由 | 新增音色后 voice 生效；未知 voice 400；默认音色兜底 |
+| M5 收敛与文档 | `setting/` 收敛、`.env.example`/README/部署更新、启动摘要展示模式与音色数 | 迁移后仅引导 env；文档与行为一致 |
+| M6 测试收尾 | 覆盖 lock 判定、setup 流程、voice 路由、损坏回退的集成测试 | 关键路径有自动化测试 |
+
+建议 M1→M2 连续做（安装流程是主链路），M3 与 M2 可并行；M4 依赖 M1 完成。
+
+---
+
+## 11. 风险与对策
+
+| 风险 | 影响 | 对策 |
+|---|---|---|
+| `modernc.org/sqlite` 体积增大 | 单二进制从 ~7MB 增至 ~40MB | 接受；如不可接受改 CGO 版（牺牲单文件） |
+| Setup 劫持（公网部署） | 他人抢先配置 | 初始化凭证 + 回环限制 + 完成后关闭端点（见 6.4） |
+| 库损坏导致服务不可用 | 服务起不来 | 自愈回退：备份 + 删 lock + 重新安装（见 6.3） |
+| 老用户迁移 | 现有 env 用户升级后无库 | 引导页预填旧 env 值；README 给出迁移步骤 |
+| voice 名冲突/默认引用 | 删除默认音色致不可用 | 唯一约束 + 默认音色删除保护（409） |
+| 并发写库 | 数据竞争 | 单写锁（`database/sql` 默认 + 业务层互斥），单用户场景风险低 |
+| 表结构未来升级 | 旧库不兼容 | lock 内容带版本号；`migrate.go` 预留版本迁移 |
+
+---
+
+## 12. 验收标准（本期 MVP）
+
+1. 删除所有业务 env 后，首次启动进入 `/setup` 引导页，可完成安装（全局 + ≥1 音色）；
+2. 安装完成后有 `installed.lock`，重启进入正常模式，`/v1/audio/speech` 可用；
+3. 通过 `/api/voices` 新增音色后，请求带该 `voice` 能正常合成；未知 voice 返回 400；
+4. 未传 `voice` 时使用默认音色；
+5. 手动制造损坏库 → 自动备份 `.corrupt-*` 并删 lock 回退安装模式；
+6. 安装模式下 `/v1/audio/speech` 返回 503 或跳转 `/setup`；
+7. 单二进制运行，无外部文件依赖（引导页已 embed）。
+
+---
+
+## 13. 非目标（明确不做）
+
+- 本期不做多服务商聚合、流式输出、缓存、字幕透出、ASR；
+- 不做完整的运营管理后台（仅引导页，管理 API 先行）；
+- 不做多租户/多用户体系（个人自用，单管理员）。
+
+---
+
+*文档版本：v0.1 · 状态：待评审 · 配套代码基线：Volcano-Engine-TTS-UI @ develop*

README.md

@@ -1,251 +1,351 @@
-# 字节跳动火山引擎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服务的应用可以无缝切换到火山引擎TTS服务。
+## 特性
 
-### 主要特性
+- 完全兼容 OpenAI `/v1/audio/speech` API
-
+- **引导式安装**: 首次启动自动进入 `/setup` 向导,无需手写 env
-- ✅ 完全兼容OpenAI `/v1/audio/speech` API接口
+- **WebUI 后台** `/admin`: 音色管理 / 全局设置 / CORS 配置 / 鉴权
-- ✅ 支持火山引擎TTS v3 API（单向流式）
+- **音色库**: 多 voice 动态路由,未知 / 禁用 voice 返回明确错误
-- ✅ 支持API Key鉴权方式
+- **多格式输出**: mp3 / ogg_opus / pcm / wav (内部转 pcm + 本地拼头) / aac / flac
-- ✅ 支持多种发音人和模型版本
+- **鉴权 + 限流**: API Key 校验, IP 速率限制, 全局并发限制
-- ✅ 内置速率限制和统计功能
+- **观测**: Prometheus 文本格式 `/metrics` + 服务状态 `/health`, 零外部依赖
-- ✅ 支持配置API密钥验证
+- **跨平台**: Windows / Linux / macOS / Docker
-- ✅ 并发限制：最多同时处理10个请求（保护上游API）
-- ✅ 跨平台支持（Windows/Linux/macOS）
-
-## 文件说明
-
-- `tts_server.go` - 主程序源码
-- `.env.example` - 环境变量配置示例
-- `go.mod` / `go.sum` - Go模块依赖
 
 ## 快速开始
 
-### 前置要求
+### 1. 编译
-
-- Go 1.19 或更高版本
-- 火山引擎账号并开通TTS服务
-
-### 1. 编译程序
 
 ```bash
-go build -o tts_server tts_server.go
+go build -o tts-api .
 ```
 
-### 2. 配置环境变量
+### 2. 启动
-
-复制 `.env.example` 为 `.env` 并填入你的配置：
 
 ```bash
-cp .env.example .env
+# 默认: 端口 8080, 监听 localhost
+./tts-api
 ```
 
-编辑 `.env` 文件，填入必要的配置参数。
+启动后浏览器打开 `http://localhost:8080/setup`,完成 4 步引导:
 
-### 3. 启动服务
+1. 凭证: 火山 API Key + OpenAI 端鉴权 key
+2. 默认路由: 默认资源 ID (复刻 2.0 用 `seed-icl-2.0`) + 默认音色名
+3. 音色列表: 每个 voice 的对外名 + 火山 speaker ID
+4. 确认提交
+
+完成后自动跳转到 `/admin`,从这里登录管理。
+
+### 3. 调用
 
 ```bash
-# Windows
+curl -X POST http://localhost:8080/v1/audio/speech \
-tts_server.exe
+  -H "Authorization: Bearer <装时设的 OpenAI key>" \
-
-# Linux/macOS
-./tts_server
-```
-
-服务默认监听 `8080` 端口。
-
-## 环境变量配置
-
-### 必需参数
-
-| 变量名 | 说明 | 示例 |
-|--------|------|------|
-| `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key | `your_api_key_here` |
-| `BYTEDANCE_TTS_RESOURCE_ID` | 资源ID，决定模型版本 | `seed-tts-1.0` |
-| `BYTEDANCE_TTS_SPEAKER` | 发音人（音色）ID | `zh_female_qingxin` |
-
-### 可选参数
-
-| 变量名 | 说明 | 默认值 |
-|--------|------|--------|
-| `BYTEDANCE_TTS_TIMEOUT` | 请求超时时间 | `30s` |
-| `OPENAI_TTS_API_KEY` | OpenAI兼容接口的API密钥（逗号分隔支持多个） | 无 |
-| `PORT` | 服务监听端口 | `8080` |
-
-### 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-1.0` | 声音复刻1.0字符版 |
-| `seed-icl-1.0-concurr` | 声音复刻1.0并发版 |
-| `seed-icl-2.0` | 声音复刻2.0字符版 |
-
-**注意：** 1.0音色只能搭配 `seed-tts-1.0` Resource ID，2.0音色只能搭配 `seed-tts-2.0` Resource ID。
-
-## API 使用说明
-
-### OpenAI 兼容接口
-
-**端点：** `POST /v1/audio/speech`
-
-**请求头：**
-- `Content-Type: application/json`
-- `Authorization: Bearer <你的API密钥>`（如果配置了OPENAI_TTS_API_KEY）
-
-**请求体：**
-```json
-{
-  "model": "tts-1",
-  "input": "你好，这是一个测试文本",
-  "voice": "alloy",
-  "response_format": "wav",
-  "speed": 1.0
-}
-```
-
-**参数说明：**
-- `model` - 模型名称（OpenAI兼容，实际不影响）
-- `input` - 要合成的文本
-- `voice` - 发音人（OpenAI兼容，实际不影响）
-- `response_format` - 输出格式：仅支持 `wav`
-- `speed` - 语速：0.25 ~ 4.0
-
-**示例调用：**
-
-```bash
-curl -X POST "http://localhost:8080/v1/audio/speech" \
   -H "Content-Type: application/json" \
-  -d '{"model":"tts-1","input":"你好，世界","voice":"alloy","speed":1.0}' \
+  -d '{"model":"tts-1","input":"你好,世界","voice":"chun"}' \
-  -o output.wav
+  -o output.mp3
 ```
 
-### 健康检查（含统计信息）
+## 环境变量
 
-```bash
+**只需 4 个启动引导变量**(安装前 / DB 还不存在时必需):
-curl http://localhost:8080/health
-```
 
-返回包含：服务状态、请求统计、错误记录、配置检查结果
+| 变量 | 必设 | 用途 |
+|---|---|---|
+| `TTS_ADMIN_KEY` | ✓ (生产) | `/api/setup` 安装 token,首次安装时校验 |
+| `TTS_DB_PATH` | ✗ | DB 路径,默认 `./tts.db` |
+| `PORT` | ✗ | 监听端口,默认 `8080` |
+| `OPENAI_TTS_API_KEY` | ✗ (生产) | OpenAI 端鉴权 key,可不设(内网) |
 
-## 限流机制
+**所有业务配置**(`api_key` / `default_resource_id` / `default_speaker` / `default_format` / `sample_rate` / `model` / `model_type` / `explicit_language` / `enable_subtitle` / `timeout` / `cors_origins` / `cors_allow_all` / `auth_key` / `trusted_proxy_hops`) — 全部在 `/admin` 设置,持久化到 SQLite。
 
-为保护上游火山引擎API，服务实现了两层限流保护：
+env 仍可作为 fallback 读(老用户兼容),但**新用户应通过 WebUI 配**。
 
-### 1. 全局并发限制
+## WebUI 使用
-- **限制**：最多同时处理 **10个** TTS请求
-- **触发**：超过10个并发请求时
-- **错误码**：`503 Service Unavailable`
-- **说明**：确保不超过上游API的并发限制
 
-### 2. IP速率限制
+### `/setup` 首次安装
-- **限制**：每个IP每分钟 **100个** 请求
+
-- **触发**：单个IP调用过于频繁
+四步表单:
-- **错误码**：`429 Too Many Requests`
+1. **凭证**: 火山 API Key (必填) + OpenAI 鉴权 Key (可选)
-- **说明**：防止单个客户端滥用服务
+2. **默认路由**: 默认资源 ID (`seed-icl-2.0`) + 默认音色名 + 默认格式 + 采样率
+3. **音色列表**: 每个 voice 一行,填对外名 + 火山 speaker ID
+4. **确认**: 提交写入 DB,自动跳 `/admin`
+
+### `/admin` 日常管理
+
+| Tab | 用途 |
+|---|---|
+| 仪表盘 | 进程状态 / 内存 / 启动时长 / 配置检查 |
+| 音色管理 | CRUD 音色: 名称 / speaker / 资源 ID / 模型 / 语言 / 启用 / 描述 |
+| 设置 | 全局设置: API Key / 默认资源 ID / 默认音色 / 格式 / 采样率 / 子模型 / 鉴权 key |
+| CORS | 白名单 (逗号分隔) 或 `*` 模式 |
+| 退出 | 清除 session |
+
+修改设置后**自动 reload**,不需重启服务。
+
+### 客户端可见错误
+
+| 场景 | HTTP | Body code | message |
+|---|---|---|---|
+| 缺少 Authorization | 401 | `invalid_api_key` | Invalid API key provided. |
+| 音色不存在 | 400 | `unknown_voice` | `unknown voice: 'alloy'` |
+| 音色被 admin 禁用 | 403 | `voice_disabled` | `voice 'chun' is disabled` |
+| 服务未就绪 (DB 配置损坏) | 503 | `service_unavailable` | TTS service configuration error... |
+
+## API 端点
+
+### `POST /v1/audio/speech`
+
+OpenAI 兼容,鉴权 `Authorization: Bearer <OPENAI_TTS_API_KEY>`(若已设)。
+
+请求体:
 
-### 触发限流时的响应
 ```json
 {
-  "error": {
+  "model": "tts-1",          // 兼容字段,实际不影响
-    "message": "Server is busy, maximum concurrent requests reached.",
+  "input": "你好,世界",     // 必填,要合成的文本
-    "type": "concurrency_limit_error",
+  "voice": "chun",           // 选填: 装时设的 voice 名称,留空走 default_speaker
-    "code": "max_concurrent_requests"
+  "response_format": "mp3",  // 选填: mp3 / opus / wav / pcm / aac / flac
-  }
+  "speed": 1.0               // 选填: 0.25 ~ 4.0,实际 0.5 ~ 2.0 生效
 }
 ```
 
-### 服务器日志
+格式映射:
-触发限流时服务器会输出中文警告日志：
-- `警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: x.x.x.x`
-- `警告: 已超过IP速率限制，拒绝请求 - 客户端IP: x.x.x.x`
 
-## 支持的发音人
+| OpenAI `response_format` | 上游实际 | Content-Type |
+|---|---|---|
+| `mp3` (默认) | mp3 | `audio/mpeg` |
+| `opus` | ogg_opus | `audio/ogg` |
+| `wav` | pcm → 本地拼 wav header | `audio/wav` |
+| `pcm` | pcm | `audio/pcm` |
+| `aac` / `flac` | mp3 (降级) | `audio/mpeg` |
 
-具体发音人列表请参考火山引擎官方文档：
+### `GET /health`
-- 1.0音色：https://www.volcengine.com/docs/6561/97454
+
-- 2.0音色：https://www.volcengine.com/docs/6561/1340515
+无鉴权,返回:
+
+```json
+{
+  "status": "ok",                            // ok | not_installed | configuration_error
+  "service": "ByteDance TTS to OpenAI API Adapter",
+  "version": "v0.2.0",
+  "commit": "621f9f8",
+  "uptime": "3600 seconds",
+  "config_status": {
+    "all_required_vars_set": true,
+    "config_error": false,
+    "error": "..."                           // 仅在 config_error=true 时出现
+  },
+  "installed": true,
+  "mode": "normal"
+}
+```
+
+- 正常: HTTP 200, `status: "ok"`
+- 未安装: HTTP 200, `status: "not_installed"`
+- 配置损坏: HTTP 503, `status: "configuration_error"`, `error` 字段有原因
+
+### `GET /metrics`
+
+Prometheus 文本格式,无鉴权。主要指标见 [观测 / Metrics](#观测--metrics)。
+
+### `GET /admin`, `GET /setup`, `GET /dashboard`
+
+- `/admin`: 后台 (Vue SPA),需鉴权
+- `/setup`: 引导式安装页 (Vue SPA),无鉴权,装完自动跳转
+- `/dashboard`: 服务状态预览页 (无鉴权)
+
+## 老用户迁移 (从 v0.1.0 → v0.2.0)
+
+v0.1.0 用 env 配 11 个 `BYTEDANCE_TTS_*` 变量。v0.2.0 起改 WebUI:
+
+| 旧 env | v0.2.0 配置入口 |
+|---|---|
+| `BYTEDANCE_TTS_API_KEY` | `/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 |
+
+**逐步迁移建议**:
+
+1. 装 v0.2.0,启动时**不**带任何 `BYTEDANCE_TTS_*` env
+2. 浏览器 `/setup`, 把原 env 里的值填到对应字段
+3. 验证 `/v1/audio/speech` 正常
+4. 下次部署可彻底删 env
+
+**临时兼容**: 老 env 仍可作为 DB 缺失时的 fallback(为 0 重启零配置启动保留),但**不推荐生产用**。
+
+## 资源 ID (重要)
+
+V3 API **只允许两个资源 ID**:
+
+| Resource ID | 说明 |
+|---|---|
+| `seed-tts-2.0` | 豆包语音合成大模型 2.0 (普通 TTS) |
+| `seed-icl-2.0` | 豆包声音复刻大模型 2.0 (复刻 2.0) |
+
+`volc.megatts.icl` / `volc.megatts.default` 等是 **1.0 API** 的资源 / 服务品类编码,**不是 v3 API 2.0 的合法资源 ID**。本项目用复刻 2.0,应填 `seed-icl-2.0`。
+
+复刻音色(speaker 以 `S_` 开头,例如 `S_G8tEKnaJ1`)必须搭配 `seed-icl-2.0`,否则返回 `code=55000000 resource ID is mismatched`。
+
+模型名: `seed-tts-2.0-standard` (这是**复刻 2.0 唯一的子模型名**,**和资源 ID 不同**)。
+
+## 观测 / Metrics
+
+Prometheus 文本格式,无鉴权。可直接被 Prometheus 抓取或浏览器查看。
+
+主要指标:
+
+| 指标 | 类型 | 标签 | 说明 |
+|---|---|---|---|
+| `tts_request_total` | counter | status, format, speaker, model | /v1/audio/speech 请求数 |
+| `tts_request_duration_seconds` | histogram | status, format | 端到端延迟 |
+| `tts_upstream_total` | counter | status, format, model, speaker | 上游调用数 |
+| `tts_upstream_duration_seconds` | histogram | status, format | 上游调用耗时 |
+| `tts_upstream_first_byte_seconds` | histogram | format | TTFB |
+| `tts_upstream_chunks_total` | counter | format | 收到的音频 chunk 数 |
+| `tts_upstream_audio_bytes_total` | counter | format | 实际返回字节数 |
+| `tts_upstream_errors_total` | counter | code | 上游错误 (聚合到 transport/client/server/upstream) |
+| `tts_usage_text_words_total` | counter | model | 上游计费字符数 |
+| `tts_concurrency_active` | gauge |  | 当前在飞请求数 |
+| `tts_concurrency_rejected_total` | counter |  | 并发上限拒绝数 |
+| `tts_ratelimit_rejected_total` | counter |  | 速率限制拒绝数 |
+| `tts_auth_failed_total` | counter |  | API Key 鉴权失败数 |
+| `tts_config_load_failures_total` | counter | mode | TTS 启动配置加载失败数 (告警用) |
+
+**注意**: `speaker` 标签是 `sha1(speaker)[:8]` 哈希值,不是明文,保护火山复刻音色 ID 隐私。
+
+### 告警示例
+
+```yaml
+- alert: TTSConfigLoadFailure
+  expr: rate(tts_config_load_failures_total{mode="normal"}[5m]) > 0
+  for: 1m
+  labels: { severity: critical }
+  annotations:
+    summary: TTS service cannot start due to invalid config
+```
+
+## 公网部署安全清单
+
+公网直接暴露 (`:8080` 可被互联网任意访问) 时,**至少满足以下两条之一**:
+
+1. **设置 `OPENAI_TTS_API_KEY`** (推荐, 最简单)
+   ```bash
+   OPENAI_TTS_API_KEY=<32+ 位随机字符串>
+   ```
+   客户端请求时带 `Authorization: Bearer <那个字符串>`。
+
+2. **前置反代承担鉴权** (nginx / caddy / Cloudflare Access)
+   - 反代层做 basic auth / mTLS / Cloudflare Access 等任一方案
+   - 反代**仅**把鉴权后的请求转发到 `:8080`
+   - 此时 `OPENAI_TTS_API_KEY` 可不设
+
+**`/metrics` / `/dashboard` / `/health` 均不鉴权**,生产环境务必通过反代保护:
+
+```nginx
+location /metrics { allow 10.0.0.0/8; deny all; }  # 仅 Prometheus 服务器
+location /dashboard { auth_basic "admin"; auth_basic_user_file /etc/nginx/.htpasswd; }
+location /health { allow 10.0.0.0/8; deny all; }  # 或 K8s liveness probe 直接访问
+```
+
+## 部署
+
+### 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. 如何获取鉴权信息？
+### 1. `code=55000000 resource ID is mismatched`
 
-- 登录火山引擎新版控制台
+资源 / 音色不匹配。修复:
-- 进入"语音合成"服务
+1. 火山控制台 → 语音技术 → 你的应用 → 资源管理
-- 创建应用并获取API Key
+2. 用控制台在线体验/调试同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色
+3. 控制台能合成的组合才是正确的
+4. v3 API 复刻 2.0 用 `seed-icl-2.0`, **不要填 `volc.megatts.icl`**
+5. 复刻音色 (speaker `S_` 开头) 需确认 Resource ID 已开通
 
-### 2. 端口被占用怎么办？
+### 2. `code=45000030 requested resource not granted`
 
-通过环境变量修改端口：
+账号未开通该资源。控制台 → 资源管理 → 申请开通。
+
+### 3. 资源 ID 该填什么
+
+v3 API 复刻 2.0 项目: **`seed-icl-2.0`** (固定)
+
+`volc.megatts.icl` 是 1.0 服务品类编码,本项目用不了。
+
+### 4. WAV 格式音频播放异常
+
+流式场景下火山 API 的 wav 格式每个 chunk 都返回完整 wav header,拼接后损坏。本项目已自动处理:选择 wav 输出时,内部用 pcm 格式请求 API,本地拼装标准 wav header。如仍有问题,改用 `mp3`。
+
+### 5. PowerShell 下 `curl` 解释错
+
+PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名。**必须写 `curl.exe`**:
+
+```powershell
+curl.exe -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" --data-binary "@body.json"
+```
+
+JSON 用单引号包,或写到文件用 `--data-binary "@file.json"`。
+
+### 6. 修改端口
 
 ```bash
-# Windows
+PORT=8081 ./tts-api
-set PORT=8081 && tts_server.exe
-
-# Linux/macOS
-PORT=8081 ./tts_server
 ```
 
-### 3. 如何配置多个API密钥？
+或 `.env` 里改 `PORT=8081`。
-
-使用逗号分隔：
-
-```bash
-OPENAI_TTS_API_KEY=sk-key1,sk-key2,sk-key3
-```
-
-### 4. 查看日志
-
-服务启动后会输出详细日志，包括：
-- 服务启动信息
-- 配置状态
-- 请求统计信息
-- 错误详情
-
-## 部署建议
-
-### 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_server
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-启动服务：
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable tts-server
-sudo systemctl start tts-server
-```
-
-## 许可证
-
-本项目采用非商业用途许可协议。您可以免费使用本软件用于非商业目的，但禁止用于任何商业活动。详细条款请参阅 [LICENSE](LICENSE) 文件。
 
 ## 技术支持
 
-如有问题，请检查：
+如有问题,请检查:
-1. 环境变量配置是否正确
+1. 服务启动后日志第一段 "环境配置汇总" — 火山必填项是否全 ✓
-2. 网络是否能访问火山引擎TTS服务
+2. `/health` 返回 `status: "ok"` 且 `config_error: false`
-3. 鉴权信息是否有效
+3. `/admin` → 设置 tab 检查 API Key / 默认资源 ID / 默认音色
-4. Resource ID与Speaker是否匹配
+4. `/admin` → 音色管理 tab 检查 voice 是否启用
+5. 火山控制台 → 在线体验同一对 resource + speaker 能合成
+6. 客户端请求 URL 是否以 https:// 开头 (公网)
+7. `/admin` → CORS tab 检查白名单含前端完整 origin
+
+## 许可证
+
+本项目采用非商业用途许可协议。详细条款请参阅 [LICENSE](LICENSE) 文件。

adapter/volcano/audio.go

@@ -0,0 +1,74 @@
+package volcano
+
+import (
+	"encoding/binary"
+	"fmt"
+)
+
+// 标准 PCM WAV 头(44 字节)。
+// 文档 3.3 节:流式场景不推荐 wav(会多次返回 wav header),
+// 本项目策略:上游走 pcm,本地拼一次标准头,避免拼接过个 header。
+type wavHeader struct {
+	// RIFF chunk descriptor
+	ChunkID   [4]byte // "RIFF"
+	ChunkSize uint32  // 36 + SubChunk2Size
+	Format    [4]byte // "WAVE"
+	// fmt sub-chunk
+	Subchunk1ID   [4]byte // "fmt "
+	Subchunk1Size uint32  // 16 for PCM
+	AudioFormat   uint16  // 1 = PCM
+	NumChannels   uint16
+	SampleRate    uint32
+	ByteRate      uint32
+	BlockAlign    uint16
+	BitsPerSample uint16
+	// data sub-chunk
+	Subchunk2ID   [4]byte // "data"
+	Subchunk2Size uint32
+}
+
+// WrapWAVHeader 把 PCM 原始字节封装成完整的 WAV 字节流。
+// sampleRate 决定 WAV 头里的采样率字段;pcm 视为 16-bit 单声道 little-endian。
+func WrapWAVHeader(pcm []byte, sampleRate int) ([]byte, error) {
+	if sampleRate <= 0 {
+		return nil, fmt.Errorf("invalid sample rate %d", sampleRate)
+	}
+	const channels uint16 = 1
+	const bitsPerSample uint16 = 16
+	blockAlign := channels * bitsPerSample / 8
+	byteRate := uint32(sampleRate) * uint32(blockAlign)
+	dataSize := uint32(len(pcm))
+
+	hdr := wavHeader{
+		ChunkID:       [4]byte{'R', 'I', 'F', 'F'},
+		ChunkSize:     36 + dataSize,
+		Format:        [4]byte{'W', 'A', 'V', 'E'},
+		Subchunk1ID:   [4]byte{'f', 'm', 't', ' '},
+		Subchunk1Size: 16,
+		AudioFormat:   1,
+		NumChannels:   channels,
+		SampleRate:    uint32(sampleRate),
+		ByteRate:      byteRate,
+		BlockAlign:    blockAlign,
+		BitsPerSample: bitsPerSample,
+		Subchunk2ID:   [4]byte{'d', 'a', 't', 'a'},
+		Subchunk2Size: dataSize,
+	}
+
+	out := make([]byte, 0, 44+len(pcm))
+	out = append(out, hdr.ChunkID[:]...)
+	out = binary.LittleEndian.AppendUint32(out, hdr.ChunkSize)
+	out = append(out, hdr.Format[:]...)
+	out = append(out, hdr.Subchunk1ID[:]...)
+	out = binary.LittleEndian.AppendUint32(out, hdr.Subchunk1Size)
+	out = binary.LittleEndian.AppendUint16(out, hdr.AudioFormat)
+	out = binary.LittleEndian.AppendUint16(out, hdr.NumChannels)
+	out = binary.LittleEndian.AppendUint32(out, hdr.SampleRate)
+	out = binary.LittleEndian.AppendUint32(out, hdr.ByteRate)
+	out = binary.LittleEndian.AppendUint16(out, hdr.BlockAlign)
+	out = binary.LittleEndian.AppendUint16(out, hdr.BitsPerSample)
+	out = append(out, hdr.Subchunk2ID[:]...)
+	out = binary.LittleEndian.AppendUint32(out, hdr.Subchunk2Size)
+	out = append(out, pcm...)
+	return out, nil
+}

adapter/volcano/client.go

@@ -0,0 +1,44 @@
+package volcano
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+// HTTPClient 持有共享的 http.Client 以便复用连接(v3 keep-alive 1 分钟)。
+type HTTPClient struct {
+	client *http.Client
+}
+
+// NewHTTPClient 构造默认配置的 HTTPClient。
+func NewHTTPClient() *HTTPClient {
+	return &HTTPClient{
+		client: &http.Client{
+			Transport: &http.Transport{
+				MaxIdleConns:        100,
+				MaxIdleConnsPerHost: 20,
+				IdleConnTimeout:     90 * time.Second,
+				TLSHandshakeTimeout: 10 * time.Second,
+			},
+		},
+	}
+}
+
+// PostStream 发送一次流式请求,返回带上下文的 *http.Response。
+// 调用方负责关闭 resp.Body。
+func (h *HTTPClient) PostStream(ctx context.Context, url string, headers map[string]string, body []byte) (*http.Response, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	return h.client.Do(req)
+}

adapter/volcano/errors.go

@@ -0,0 +1,27 @@
+package volcano
+
+import "fmt"
+
+// UpstreamError 表示火山 v3 返回的 业务错误(code != 0 且 != 20000000)或传输错误。
+// 包含上游错误码,便于 telemetry 把它作为 label。
+type UpstreamError struct {
+	Code    int
+	Message string
+	Stage   string // "request"/"stream"/"http" - 出错阶段
+	Wrapped error
+}
+
+func (e *UpstreamError) Error() string {
+	if e.Wrapped != nil {
+		return fmt.Sprintf("volcano %s: code=%d %s: %v", e.Stage, e.Code, e.Message, e.Wrapped)
+	}
+	return fmt.Sprintf("volcano %s: code=%d %s", e.Stage, e.Code, e.Message)
+}
+
+func (e *UpstreamError) Unwrap() error { return e.Wrapped }
+
+// IsAuth 当上游返回认证/权限类错误时返回 true。
+func (e *UpstreamError) IsAuth() bool {
+	return e.Code == 45000000 || e.Code == 55000000 ||
+		e.Code == 401 || e.Code == 403
+}

adapter/volcano/options.go

@@ -0,0 +1,63 @@
+package volcano
+
+// Options 是火山 v3 TTS 适配器的完整调用参数集合。
+// 由 setting 包从环境变量构造,controller 直接透传,不做 OpenAI 侧映射。
+//
+// 字段顺序与文档 3.x 节一致,便于对照。
+type Options struct {
+	// --- 鉴权 / 路由 ---
+	APIKey     string // X-Api-Key
+	ResourceID string // X-Api-Resource-Id,决定模型版本与计费,如 seed-icl-2.0
+
+	// --- req_params 核心字段 ---
+	Text    string
+	Speaker string
+	Model   string // 可空,仅复刻 2.0 生效;env 默认 seed-tts-2.0-standard
+	UID     string // user.uid,默认 "uid"
+
+	// --- audio_params ---
+	Format          string // 上游实际请求的 format:mp3 / pcm / ogg_opus
+	SampleRate      int    // 8000/16000/22050/24000/32000/44100/48000
+	BitRate         int    // 可选,仅 MP3 生效
+	SpeechRate      int    // [-50, 100]
+	LoudnessRate    int    // [-50, 100]
+	EnableSubtitle  bool   // 复刻 2.0 生效,返回 TTSSubtitle
+	EnableTimestamp bool   // 复刻 1.0 生效,内嵌字级时间戳
+
+	// --- additions(扩展参数,JSON 字符串承载)---
+	// 文档明确 additions 在请求体里必须是 string,内容是 JSON。
+	// 这里直接存结构体,序列化时由 MarshalJSON 输出为 string。
+	Additions *Additions
+}
+
+// Additions 对应文档 3.4 节的扩展参数。
+// 注意:在请求体里 additions 是 JSON 字符串,所以 MarshalJSON 序列化为 string。
+type Additions struct {
+	ModelType                  *int     `json:"model_type,omitempty"`               // 复刻 2.0 推荐显式指定,4=ICL V2、5=ICL V3
+	ContextTexts               []string `json:"context_texts,omitempty"`            // 语音指令
+	UseTagParser               *bool    `json:"use_tag_parser,omitempty"`           // 复刻 2.0 expressive 启用语音标签 Cot
+	ExplicitLanguage           string   `json:"explicit_language,omitempty"`        // 明确语种
+	ContextLanguage            string   `json:"context_language,omitempty"`         // 参考语种
+	SilenceDuration            *int     `json:"silence_duration,omitempty"`         // 0~30000ms
+	EnableLanguageDetector     *bool    `json:"enable_language_detector,omitempty"` // 自动识别语种
+	DisableMarkdownFilter      *bool    `json:"disable_markdown_filter,omitempty"`  // 是否解析 markdown
+	DisableEmojiFilter         *bool    `json:"disable_emoji_filter,omitempty"`     // 是否过滤 emoji
+	MaxLengthFilterParenthesis *int     `json:"max_length_to_filter_parenthesis,omitempty"`
+	UnsupportedCharRatio       *float64 `json:"unsupported_char_ratio_thresh,omitempty"`
+	AIGCWatermark              *bool    `json:"aigc_watermark,omitempty"`
+	AIGCMetadata               any      `json:"aigc_metadata,omitempty"`
+	CacheConfig                any      `json:"cache_config,omitempty"`
+	PostProcess                any      `json:"post_process,omitempty"`
+}
+
+// IsZero 报告 Additions 是否为空(没有任何字段设置),用于在序列化前跳过 additions。
+func (a *Additions) IsZero() bool {
+	if a == nil {
+		return true
+	}
+	return a.ModelType == nil && a.ContextTexts == nil && a.UseTagParser == nil &&
+		a.ExplicitLanguage == "" && a.ContextLanguage == "" && a.SilenceDuration == nil &&
+		a.EnableLanguageDetector == nil && a.DisableMarkdownFilter == nil && a.DisableEmojiFilter == nil &&
+		a.MaxLengthFilterParenthesis == nil && a.UnsupportedCharRatio == nil &&
+		a.AIGCWatermark == nil && a.AIGCMetadata == nil && a.CacheConfig == nil && a.PostProcess == nil
+}

adapter/volcano/request.go

@@ -0,0 +1,113 @@
+package volcano
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// requestBody 是真正发到上游 v3 端点的 JSON 顶层结构。
+type requestBody struct {
+	User      ttsUser      `json:"user"`
+	Namespace string       `json:"namespace"`
+	ReqParams ttsReqParams `json:"req_params"`
+}
+
+type ttsUser struct {
+	UID string `json:"uid"`
+}
+
+type ttsReqParams struct {
+	Text        string         `json:"text"`
+	Speaker     string         `json:"speaker"`
+	Model       string         `json:"model,omitempty"`
+	AudioParams ttsAudioParams `json:"audio_params"`
+	Additions   string         `json:"additions,omitempty"` // 注意:字符串
+}
+
+type ttsAudioParams struct {
+	Format          string `json:"format"`
+	SampleRate      int    `json:"sample_rate"`
+	BitRate         int    `json:"bit_rate,omitempty"`
+	SpeechRate      int    `json:"speech_rate"`
+	LoudnessRate    int    `json:"loudness_rate,omitempty"`
+	EnableSubtitle  bool   `json:"enable_subtitle,omitempty"`
+	EnableTimestamp bool   `json:"enable_timestamp,omitempty"`
+}
+
+// buildRequest 把 Options 序列化为上游请求体 JSON。
+func buildRequest(opts Options) ([]byte, error) {
+	if opts.Text == "" {
+		return nil, fmt.Errorf("volcano: text is required")
+	}
+	if opts.Speaker == "" {
+		return nil, fmt.Errorf("volcano: speaker is required")
+	}
+	if opts.ResourceID == "" {
+		return nil, fmt.Errorf("volcano: resource id is required")
+	}
+	if opts.APIKey == "" {
+		return nil, fmt.Errorf("volcano: api key is required")
+	}
+
+	body := requestBody{
+		User:      ttsUser{UID: opts.UID},
+		Namespace: "UnidirectionalTTS",
+		ReqParams: ttsReqParams{
+			Text:    opts.Text,
+			Speaker: opts.Speaker,
+			Model:   opts.Model,
+			AudioParams: ttsAudioParams{
+				Format:          opts.Format,
+				SampleRate:      opts.SampleRate,
+				BitRate:         opts.BitRate,
+				SpeechRate:      opts.SpeechRate,
+				LoudnessRate:    opts.LoudnessRate,
+				EnableSubtitle:  opts.EnableSubtitle,
+				EnableTimestamp: opts.EnableTimestamp,
+			},
+		},
+	}
+
+	if opts.Additions != nil && !opts.Additions.IsZero() {
+		// 文档明确 additions 字段为 JSON 字符串。
+		raw, err := json.Marshal(opts.Additions)
+		if err != nil {
+			return nil, fmt.Errorf("marshal additions: %w", err)
+		}
+		body.ReqParams.Additions = string(raw)
+	}
+
+	raw, err := json.Marshal(body)
+	if err != nil {
+		return nil, fmt.Errorf("marshal request: %w", err)
+	}
+	return raw, nil
+}
+
+// convertSpeedToSpeechRate 把 OpenAI 风格的 speed(倍率)转换为 speech_rate(百分比)。
+// speech_rate 范围 [-50, 100],对应 0.5x ~ 2.0x。
+func convertSpeedToSpeechRate(speed float64) int {
+	if speed <= 0 {
+		speed = 1.0
+	}
+	rate := int((speed - 1.0) * 100)
+	if rate < -50 {
+		rate = -50
+	}
+	if rate > 100 {
+		rate = 100
+	}
+	return rate
+}
+
+// resolveUpstreamFormat 决定上游实际请求的 format。
+//   - 客户端要求 wav -> 上游走 pcm,我们本地拼 header
+//   - 其他 -> 直接用 clientFormat
+//
+// sampleRate 在 wav 走 pcm 的情况下也按原样传给上游(影响 PCM 的实际采样率)。
+func resolveUpstreamFormat(clientFormat string) string {
+	if clientFormat == "wav" {
+		return "pcm"
+	}
+	return clientFormat
+}

adapter/volcano/response.go

@@ -0,0 +1,152 @@
+package volcano
+
+import (
+	"bufio"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"time"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/dto"
+)
+
+// ParsedStream 是一次流式响应的累计结果。
+type ParsedStream struct {
+	AudioData  []byte
+	Chunks     int
+	TextWords  int
+	FirstChunk time.Duration // 从请求发起到收到第一个 sentence chunk 的耗时
+	HasUsage   bool
+	Subtitles  []dto.SubtitleEntry
+}
+
+// ParseStream 读取 v3 chunked NDJSON 响应,按文档 5.1 节的 event 取值分类处理。
+//
+// 关键修复(对比原实现):只有 event == "sentence" 才是音频帧;
+// TTSSubtitle 单独收集,不会污染音频字节流。
+func ParseStream(body io.Reader, started time.Time) (*ParsedStream, error) {
+	out := &ParsedStream{}
+	scanner := bufio.NewScanner(body)
+	scanner.Buffer(make([]byte, 1024*1024), 8*1024*1024)
+
+	gotFirstChunk := false
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		var resp dto.V3TTSResponse
+		if err := json.Unmarshal(line, &resp); err != nil {
+			if common.DebugLog {
+				log.Printf("volcano: 解析响应行失败: %v, line=%q", err, truncateForLog(line, 200))
+			}
+			continue
+		}
+
+		if resp.Code != 0 && resp.Code != 20000000 {
+			return nil, &UpstreamError{
+				Code:    resp.Code,
+				Message: resp.Message,
+				Stage:   "stream",
+			}
+		}
+
+		if resp.Code == 20000000 {
+			if resp.Usage != nil {
+				out.TextWords = resp.Usage.TextWords
+				out.HasUsage = true
+				if common.DebugLog {
+					log.Printf("TTS 合成结束, usage: text_words=%d", out.TextWords)
+				}
+			}
+			for scanner.Scan() {
+			}
+			break
+		}
+
+		// 事件分发:显式匹配已知事件,绝不把未知事件当作音频。
+		switch resp.Event {
+		case "TTSSentenceStart":
+			if common.DebugLog {
+				log.Printf("Sentence start: sequence=%d, sentence=%s", resp.Sequence, resp.SentenceText())
+			}
+		case "TTSSentenceEnd":
+			if common.DebugLog {
+				log.Printf("Sentence end: sequence=%d", resp.Sequence)
+			}
+		case "TTSSubtitle":
+			if resp.Data != "" {
+				out.Subtitles = append(out.Subtitles, dto.SubtitleEntry{
+					Text:     resp.SentenceText(),
+					Sequence: resp.Sequence,
+				})
+			}
+		case "sentence", "":
+			// HTTP 单向协议下,音频帧的 event 字段可能是空也可能是 "sentence";
+			// 两种都当音频处理。
+			if resp.Data == "" {
+				continue
+			}
+			chunk, err := base64.StdEncoding.DecodeString(resp.Data)
+			if err != nil {
+				return nil, &UpstreamError{
+					Code:    resp.Code,
+					Message: fmt.Sprintf("decode audio chunk: %v", err),
+					Stage:   "stream",
+					Wrapped: err,
+				}
+			}
+			out.AudioData = append(out.AudioData, chunk...)
+			out.Chunks++
+			if !gotFirstChunk {
+				out.FirstChunk = time.Since(started)
+				gotFirstChunk = true
+			}
+		default:
+			if common.DebugLog {
+				log.Printf("volcano: 忽略未识别事件 event=%q sequence=%d sentence=%s data_len=%d", resp.Event, resp.Sequence, resp.SentenceText(), len(resp.Data))
+			}
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, &UpstreamError{
+			Code:    0,
+			Message: fmt.Sprintf("read stream: %v", err),
+			Stage:   "stream",
+			Wrapped: err,
+		}
+	}
+
+	if len(out.AudioData) == 0 {
+		return nil, &UpstreamError{
+			Code:    0,
+			Message: "no audio data received from TTS service",
+			Stage:   "stream",
+		}
+	}
+
+	return out, nil
+}
+
+// ReadErrorBody 把非 200 响应的 body 读出来用于日志。
+func ReadErrorBody(body io.Reader) string {
+	const max = 2048
+	buf := make([]byte, max)
+	n, err := io.ReadFull(body, buf)
+	if err != nil && !errors.Is(err, io.ErrUnexpectedEOF) && !errors.Is(err, io.EOF) {
+		return fmt.Sprintf("read body fail: %v", err)
+	}
+	return string(buf[:n])
+}
+
+func truncateForLog(b []byte, max int) string {
+	if len(b) > max {
+		return string(b[:max]) + fmt.Sprintf("...(truncated, total %d bytes)", len(b))
+	}
+	return string(b)
+}

adapter/volcano/synthesis.go

@@ -0,0 +1,199 @@
+package volcano
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/dto"
+	"github.com/volcano-tts/tts-api/telemetry"
+)
+
+// MetricsRecorder 是适配器向上报告埋点的接口。
+// 适配器本身不依赖 telemetry 包,controller 在 main 启动时把 Meter 适配成实现;
+// 这样测试可以注入 mock,生产可以无侵入替换成 OTel。
+type MetricsRecorder interface {
+	UpstreamStarted(speaker, model, format string)
+	UpstreamFinished(speaker, model, format, status string, duration, ttfb time.Duration, chunks, audioBytes, errCode int)
+	UpstreamUsage(model string, textWords int)
+}
+
+// nopMetrics 是 MetricsRecorder 的 no-op 默认值。
+type nopMetrics struct{}
+
+func (nopMetrics) UpstreamStarted(string, string, string) {}
+func (nopMetrics) UpstreamFinished(string, string, string, string, time.Duration, time.Duration, int, int, int) {
+}
+func (nopMetrics) UpstreamUsage(string, int) {}
+
+// Synthesis 调用火山 v3 一次,返回组装好的结果。
+//
+// 入参:
+//   - ctx:超时控制
+//   - client:复用的 HTTPClient
+//   - opts:从 setting 构造的完整参数(text 字段会被 text 覆盖)
+//   - text:本次合成的实际文本
+//   - clientFormat:客户端期望的最终格式,"wav" 内部转 pcm 后本地拼 wav 头
+//   - speed:OpenAI 风格的 speed(倍率,0.5~2.0)
+//   - mtr:可选埋点;传 nil 等价于 nopMetrics
+func Synthesis(
+	ctx context.Context,
+	client *HTTPClient,
+	opts Options,
+	text string,
+	clientFormat string,
+	speed float64,
+	mtr MetricsRecorder,
+) (*dto.SynthesisResult, error) {
+	if mtr == nil {
+		mtr = nopMetrics{}
+	}
+	opts.Text = text
+	opts.SpeechRate = convertSpeedToSpeechRate(speed)
+
+	reqID := newRequestID()
+
+	upstreamFormat := resolveUpstreamFormat(clientFormat)
+	opts.Format = upstreamFormat
+	if upstreamFormat != "pcm" && upstreamFormat != "mp3" && upstreamFormat != "ogg_opus" {
+		opts.Format = "mp3"
+	}
+
+	started := time.Now()
+	mtr.UpstreamStarted(opts.Speaker, opts.Model, opts.Format)
+
+	body, err := buildRequest(opts)
+	if err != nil {
+		mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, "request_error", time.Since(started), 0, 0, 0, 0)
+		return nil, &UpstreamError{Code: 0, Message: err.Error(), Stage: "request", Wrapped: err}
+	}
+
+	headers := map[string]string{
+		"Content-Type":                          "application/json",
+		"Connection":                            "keep-alive",
+		"X-Api-Resource-Id":                     opts.ResourceID,
+		"X-Api-Request-Id":                      reqID,
+		"X-Api-Key":                             opts.APIKey,
+		"X-Control-Require-Usage-Tokens-Return": "*",
+	}
+
+	if common.DebugLog {
+		log.Printf("TTS upstream: resource_id=%s speaker=%s model=%q format=%s sample_rate=%d speech_rate=%d additions=%q",
+			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)
+	if err != nil {
+		mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, "transport_error", time.Since(started), 0, 0, 0, 0)
+		return nil, &UpstreamError{Code: 0, Message: err.Error(), Stage: "request", Wrapped: err}
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		rawBody := ReadErrorBody(resp.Body)
+		// rawBody 来自上游响应体,可能是攻击者控制的恶意内容(例如包含
+		// \n 伪造日志行)。转义后再嵌入错误消息。
+		safeBody := strings.NewReplacer("\n", "\\n", "\r", "\\r").Replace(rawBody)
+		mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, fmt.Sprintf("http_%d", resp.StatusCode), time.Since(started), 0, 0, 0, resp.StatusCode)
+		return nil, &UpstreamError{
+			Code:    resp.StatusCode,
+			Message: fmt.Sprintf("upstream http %d: %s", resp.StatusCode, safeBody),
+			Stage:   "http",
+		}
+	}
+
+	parsed, err := ParseStream(resp.Body, started)
+	if err != nil {
+		ue, _ := err.(*UpstreamError)
+		code := 0
+		if ue != nil {
+			code = ue.Code
+		}
+		mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, "stream_error", time.Since(started), 0, 0, 0, code)
+		return nil, err
+	}
+
+	duration := time.Since(started)
+
+	finalData := parsed.AudioData
+	// finalFormat 反映真实输出格式(用于 controller 写 Content-Type):
+	//   - wav 走 pcm 上游 + 本地拼头,对外仍是 wav
+	//   - aac/flac 在上方已被上游降级为 mp3,真实输出也是 mp3
+	//   - 其余与 clientFormat 一致
+	finalFormat := clientFormat
+	if clientFormat != "wav" {
+		finalFormat = opts.Format
+	}
+	sampleRate := opts.SampleRate
+	if clientFormat == "wav" {
+		wav, wrapErr := WrapWAVHeader(parsed.AudioData, opts.SampleRate)
+		if wrapErr != nil {
+			mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, "wrap_error", duration, parsed.FirstChunk, parsed.Chunks, len(parsed.AudioData), 0)
+			return nil, &UpstreamError{Code: 0, Message: wrapErr.Error(), Stage: "wrap", Wrapped: wrapErr}
+		}
+		finalData = wav
+	}
+
+	if parsed.HasUsage {
+		mtr.UpstreamUsage(opts.Model, parsed.TextWords)
+	}
+	mtr.UpstreamFinished(opts.Speaker, opts.Model, opts.Format, "ok", duration, parsed.FirstChunk, parsed.Chunks, len(finalData), 0)
+
+	log.Printf("TTS 合成成功 - 音色=%s 格式=%s 文本=%d字 音频=%d字节 分片=%d 耗时=%v",
+		telemetry.MaskSpeaker(opts.Speaker), clientFormat, len(text), len(finalData), parsed.Chunks, duration)
+
+	return &dto.SynthesisResult{
+		AudioData:  finalData,
+		Format:     finalFormat,
+		SampleRate: sampleRate,
+		ReqID:      reqID,
+		TextWords:  parsed.TextWords,
+		Chunks:     parsed.Chunks,
+		AudioBytes: len(finalData),
+		TTFB:       parsed.FirstChunk,
+		Duration:   duration,
+	}, nil
+}
+
+// newRequestID 16 字节随机 ID(hex 编码),无外部依赖。
+func newRequestID() string {
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	return hex.EncodeToString(b[:])
+}
+
+// extractAdditionsForLog 从已编码的请求体里取 additions 字段值,便于日志展示。
+func extractAdditionsForLog(body []byte) string {
+	const key = "\"additions\":\""
+	idx := bytesIndex(body, key)
+	if idx < 0 {
+		return ""
+	}
+	rest := body[idx+len(key):]
+	end := bytesIndex(rest, "\"")
+	if end < 0 {
+		return ""
+	}
+	return string(rest[:end])
+}
+
+func bytesIndex(haystack []byte, needle string) int {
+	if len(needle) == 0 {
+		return 0
+	}
+outer:
+	for i := 0; i+len(needle) <= len(haystack); i++ {
+		for j := 0; j < len(needle); j++ {
+			if haystack[i+j] != needle[j] {
+				continue outer
+			}
+		}
+		return i
+	}
+	return -1
+}

cmd/dumpdb/main.go

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

common/constants.go

@@ -0,0 +1,41 @@
+package common
+
+import "time"
+
+// DebugLog 控制非必要日志输出;由 setting 包在启动时通过 BYTEDANCE_TTS_DEBUG 环境变量设置。
+var DebugLog bool
+
+const (
+	DefaultPort           = "8080"
+	DefaultTimeout        = 30 * time.Second
+	MaxTextLength         = 5000
+	MinSpeed              = 0.25
+	MaxSpeed              = 4.0
+	DefaultSpeed          = 1.0
+	MaxRequestBodySize    = 1024 * 1024
+	RateLimitRequests     = 100
+	RateLimitWindow       = time.Minute
+	MaxConcurrentRequests = 10
+	CleanupInterval       = time.Hour
+	MaxModelNameLength    = 64
+	MaxRateLimiterEntries = 100000
+)
+
+// SecureEqualString 是常量时间字符串比较,防 token 计时攻击。
+// 长度先比对(避免短串早返回时泄漏长度信息),再遍历每个字节做 XOR 累加;
+// diff 为 0 才返 true。用于 Bearer token、setup token 等敏感比较场景。
+func SecureEqualString(a, b string) bool {
+	if len(a) != len(b) {
+		// 先比对长度(避免短串早返回时泄漏长度信息)
+		// 但仍要遍历一遍避免优化器消除分支
+		if len(a) > 0 {
+			_ = a[0]
+		}
+		return false
+	}
+	var diff byte
+	for i := 0; i < len(a); i++ {
+		diff |= a[i] ^ b[i]
+	}
+	return diff == 0
+}

controller/admin.go

@@ -0,0 +1,323 @@
+package controller
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/mux"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/middleware"
+	"github.com/volcano-tts/tts-api/store"
+	"github.com/volcano-tts/tts-api/version"
+)
+
+// SetAdminStore 注入 admin 控制器需要的 store;main 启动期调一次。
+// store 可能在自愈回退后为 nil,GetAdminStore 返 nil 时 controller 应返 503。
+var adminStore *store.Store
+
+// SetAdminStore 在 main 启动期调,设置 admin 用的 store 句柄。
+func SetAdminStore(s *store.Store) { adminStore = s }
+
+// GetAdminStore admin 控制器用,获取已注入的 store;nil 表示服务在 setup 模式。
+func GetAdminStore() *store.Store { return adminStore }
+
+// metricsTextWriter 是 admin 端点写 Prometheus 文本的回调,
+// 由 main 启动期注入(避免 controller → metrics → controller 循环)。
+type metricsTextWriter func(w http.ResponseWriter) error
+
+var (
+	metricsTextWriterMu sync.RWMutex
+	metricsTextWriterFn metricsTextWriter
+)
+
+// SetMetricsTextWriter 注入 Prometheus 文本写入函数;main 启动期调一次。
+func SetMetricsTextWriter(fn metricsTextWriter) {
+	metricsTextWriterMu.Lock()
+	metricsTextWriterFn = fn
+	metricsTextWriterMu.Unlock()
+}
+
+// AdminOverviewResponse 是 GET /api/admin/overview 的响应体。
+type AdminOverviewResponse struct {
+	Mode              string                 `json:"mode"`
+	Installed         bool                   `json:"installed"`
+	DBPath            string                 `json:"db_path"`
+	LockPath          string                 `json:"lock_path"`
+	Version           string                 `json:"version"`
+	Commit            string                 `json:"commit"`
+	UptimeSeconds     int64                  `json:"uptime_seconds"`
+	StartTime         string                 `json:"start_time"`
+	VoiceCount        int                    `json:"voice_count"`
+	VoiceEnabledCount int                    `json:"voice_enabled_count"`
+	Memory            map[string]interface{} `json:"memory"`
+}
+
+// AdminOverviewHandler GET /api/admin/overview
+// 鉴权: RequireAdmin;store 为 nil 时仍可服务,但 voice 字段为 0。
+func AdminOverviewHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	resp := AdminOverviewResponse{
+		Mode:          installer.GetMode().String(),
+		Installed:     installer.GetMode() == installer.ModeNormal,
+		Version:       version.Version,
+		Commit:        version.Commit,
+		StartTime:     startTime.Format(time.RFC3339),
+		UptimeSeconds: int64(time.Since(startTime).Seconds()),
+		Memory:        collectMemorySnapshot(),
+	}
+
+	if s := GetAdminStore(); s != nil {
+		if p, err := s.Path(); err == nil {
+			resp.DBPath = p
+		}
+		resp.LockPath = installer.LockPath(resp.DBPath)
+		if n, err := s.VoiceCount(); err == nil {
+			resp.VoiceCount = n
+		}
+		if n, err := s.VoiceCountEnabled(); err == nil {
+			resp.VoiceEnabledCount = n
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		log.Printf("[admin] overview encode failed: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "encode failed", "server_error", "encode_failed")
+	}
+}
+
+// AdminMetricsHandler GET /api/admin/metrics
+// 鉴权: RequireAdmin;返 Prometheus 文本。
+func AdminMetricsHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	metricsTextWriterMu.RLock()
+	fn := metricsTextWriterFn
+	metricsTextWriterMu.RUnlock()
+	if fn == nil {
+		// 启动期没注入,返 503 + 提示(不应该发生)
+		middleware.SendJSONError(w, http.StatusServiceUnavailable,
+			"metrics writer not initialized", "configuration_error", "metrics_not_ready")
+		return
+	}
+	w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+	if err := fn(w); err != nil {
+		log.Printf("[admin] metrics write: %v", err)
+	}
+}
+
+// AdminVoicesListResponse 是 GET /api/voices 的响应。
+type AdminVoicesListResponse struct {
+	Voices []store.Voice `json:"voices"`
+	Total  int           `json:"total"`
+}
+
+// AdminVoicesListHandler GET /api/voices
+// 鉴权: RequireAdmin;返所有 voice(包含 disabled)。
+func AdminVoicesListHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+	vs, err := s.VoiceList(true)
+	if err != nil {
+		log.Printf("[admin] voice list: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "list voices failed", "server_error", "db_read_failed")
+		return
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(AdminVoicesListResponse{Voices: vs, Total: len(vs)})
+}
+
+// AdminVoiceCreateRequest 是 POST /api/voices 的 body。
+type AdminVoiceCreateRequest struct {
+	Name        string `json:"name"`
+	Speaker     string `json:"speaker"`
+	ResourceID  string `json:"resource_id"`
+	Model       string `json:"model"`
+	Language    string `json:"language"`
+	Description string `json:"description"`
+	Enabled     *bool  `json:"enabled,omitempty"`
+}
+
+// AdminVoiceCreateHandler POST /api/voices
+// 鉴权: RequireAdmin;store nil 时 503。
+func AdminVoiceCreateHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<16)
+	var body AdminVoiceCreateRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+
+	enabled := true
+	if body.Enabled != nil {
+		enabled = *body.Enabled
+	}
+
+	v := store.Voice{
+		Name:        body.Name,
+		Speaker:     body.Speaker,
+		ResourceID:  body.ResourceID,
+		Model:       body.Model,
+		Language:    body.Language,
+		Description: body.Description,
+		Enabled:     enabled,
+	}
+	id, err := s.VoiceInsert(v)
+	if err != nil {
+		switch {
+		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.StatusInternalServerError,
+				"failed to insert voice", "server_error", "voice_insert_failed")
+		}
+		return
+	}
+	created, _ := s.VoiceGet(id)
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(http.StatusCreated)
+	_ = json.NewEncoder(w).Encode(created)
+}
+
+// AdminVoiceDeleteHandler DELETE /api/voices/{name}
+func AdminVoiceDeleteHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodDelete {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+	name := mux.Vars(r)["name"]
+	if name == "" {
+		middleware.SendJSONError(w, http.StatusBadRequest, "missing voice name", "invalid_request_error", "bad_request")
+		return
+	}
+
+	v, err := s.VoiceGetByName(name)
+	if err != nil {
+		if err == store.ErrNotFound {
+			http.Error(w, "voice not found", http.StatusNotFound)
+			return
+		}
+		log.Printf("[admin] voice lookup: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "lookup failed", "server_error", "db_read_failed")
+		return
+	}
+	if err := s.VoiceDelete(v.ID); err != nil {
+		switch err {
+		case store.ErrInUse:
+			middleware.SendJSONError(w, http.StatusConflict,
+				fmt.Sprintf("voice %q is referenced by default_speaker; remove the default first", name),
+				"invalid_request_error", "voice_in_use")
+		case store.ErrNotFound:
+			http.Error(w, "voice not found", http.StatusNotFound)
+		default:
+			log.Printf("[admin] voice delete: %v", err)
+			middleware.SendJSONError(w, http.StatusInternalServerError, "delete failed", "server_error", "db_write_failed")
+		}
+		return
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "deleted": name})
+}
+
+// AdminVoiceToggleRequest 是 PATCH /api/voices/{name}/toggle 的 body。
+type AdminVoiceToggleRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+// AdminVoiceToggleHandler PATCH /api/voices/{name}/toggle
+func AdminVoiceToggleHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPatch {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	s := GetAdminStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
+		return
+	}
+	name := mux.Vars(r)["name"]
+	if name == "" {
+		middleware.SendJSONError(w, http.StatusBadRequest, "missing voice name", "invalid_request_error", "bad_request")
+		return
+	}
+	v, err := s.VoiceGetByName(name)
+	if err != nil {
+		if err == store.ErrNotFound {
+			http.Error(w, "voice not found", http.StatusNotFound)
+			return
+		}
+		log.Printf("[admin] voice lookup: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "lookup failed", "server_error", "db_read_failed")
+		return
+	}
+	var body AdminVoiceToggleRequest
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+	if err := s.VoiceToggleEnabled(v.ID, body.Enabled); err != nil {
+		log.Printf("[admin] voice toggle: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "toggle failed", "server_error", "db_write_failed")
+		return
+	}
+	updated, _ := s.VoiceGet(v.ID)
+	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

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

controller/setup.go

@@ -0,0 +1,296 @@
+package controller
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/middleware"
+	"github.com/volcano-tts/tts-api/setting"
+	"github.com/volcano-tts/tts-api/store"
+)
+
+// SetupAPIState 是 setup 控制器需要的状态:
+//   - Store:  db 访问,可能为 nil(自愈回退后 store 已关闭,等待重新 setup)
+//   - DBPath: 用于安装完成时写 lock
+type SetupAPIState struct {
+	Store  *store.Store
+	DBPath string
+	Token  string
+}
+
+// 全局 setup 状态,在 main.go 启动时通过 SetSetupState 注入。
+// 进程内只有一个二进制实例,全局变量是合适的。
+var setupState SetupAPIState
+
+// SetSetupState 注入 setup 控制器所需的 store + dbPath,启动期调用一次。
+func SetSetupState(s *store.Store, dbPath string) {
+	setupState.Store = s
+	setupState.DBPath = dbPath
+}
+
+// GetSetupStore 供 router/main 注入的 store 访问函数。
+func GetSetupStore() *store.Store { return setupState.Store }
+
+// GetSetupDBPath 供 router/main 注入的 dbPath 访问函数。
+func GetSetupDBPath() string { return setupState.DBPath }
+
+// SetupStatusHandler GET /api/setup/status
+// 始终返回当前模式,无论安装与否;用于部署探针 + 引导页判断。
+func SetupStatusHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	resp := map[string]any{
+		"installed": installer.GetMode() == installer.ModeNormal,
+		"mode":      installer.GetMode().String(),
+	}
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+// SetupPrefillHandler GET /api/setup/prefill
+// 仅在安装模式有响应;返回旧 env 变量值,便于引导页预填,实现平滑迁移。
+func SetupPrefillHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	if installer.GetMode() != installer.ModeSetup {
+		http.Error(w, "not in setup mode", http.StatusNotFound)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	resp := map[string]any{
+		"settings": prefillFromEnv(),
+	}
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+// prefillFromEnv 读 BYTEDANCE_TTS_* 等旧 env,作为引导页预填值。
+// 读不到就返回空串,前端会用默认值。
+func prefillFromEnv() map[string]string {
+	get := func(k string) string { return os.Getenv(k) }
+	return map[string]string{
+		"api_key":            "", // API key 永不回显,即便 env 里有;必须让用户重新输入
+		"default_resource_id": get("BYTEDANCE_TTS_RESOURCE_ID"),
+		"default_speaker":    get("BYTEDANCE_TTS_SPEAKER"),
+		"default_format":     get("BYTEDANCE_TTS_FORMAT"),
+		"sample_rate":        get("BYTEDANCE_TTS_SAMPLE_RATE"),
+		"model":              get("BYTEDANCE_TTS_MODEL"),
+		"model_type":         get("BYTEDANCE_TTS_MODEL_TYPE"),
+		"explicit_language":  get("BYTEDANCE_TTS_EXPLICIT_LANGUAGE"),
+		"enable_subtitle":    get("BYTEDANCE_TTS_ENABLE_SUBTITLE"),
+		"timeout":            get("BYTEDANCE_TTS_TIMEOUT"),
+	}
+}
+
+// SetupRequestBody 是 POST /api/setup 的请求体结构。
+type SetupRequestBody struct {
+	Token    string            `json:"token"`
+	Settings map[string]string `json:"settings"`
+	Voices   []SetupVoice      `json:"voices"`
+}
+
+// SetupVoice 是 POST /api/setup 里 voices 数组的条目。
+type SetupVoice struct {
+	Name       string `json:"name"`
+	Speaker    string `json:"speaker"`
+	ResourceID string `json:"resource_id"`
+	Model      string `json:"model"`
+	Language   string `json:"language"`
+}
+
+// SetupSubmitHandler POST /api/setup
+// 校验 token → 校验字段 → 写 settings → 写 voices → 写 lock。
+// 必须在安装模式才接受;装完后永久 404。
+func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	// 安装完成后此端点永久关闭(防止被误触)
+	if installer.GetMode() != installer.ModeSetup {
+		http.NotFound(w, r)
+		return
+	}
+
+	// 解析 body
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1MB
+	var body SetupRequestBody
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
+		return
+	}
+
+	// token 校验(常量时间比较防计时攻击)
+	if setting.SetupToken == "" || !secureEqualString(body.Token, setting.SetupToken) {
+		log.Printf("[setup] token 校验失败 - 客户端=%s", middleware.GetClientIP(r))
+		middleware.SendJSONError(w, http.StatusUnauthorized, "invalid setup token", "authentication_error", "invalid_token")
+		return
+	}
+
+	// 校验 settings 必填项
+	if err := validateSetupSettings(body.Settings); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, err.Error(), "invalid_request_error", "missing_field")
+		return
+	}
+
+	// 校验 voices
+	if err := validateSetupVoices(body.Voices); err != nil {
+		middleware.SendJSONError(w, http.StatusBadRequest, err.Error(), "invalid_request_error", "invalid_voice")
+		return
+	}
+
+	// 取 store:必须为非 nil(自愈回退后 store 是 nil,这种状态下不接 setup,要求重启)
+	s := GetSetupStore()
+	if s == nil {
+		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready, please restart service", "configuration_error", "db_not_ready")
+		return
+	}
+
+	// 写 settings(包含 initialized=1)
+	settingsKV := make(map[string]string, len(body.Settings)+1)
+	for k, v := range body.Settings {
+		settingsKV[k] = v
+	}
+	settingsKV["initialized"] = "1"
+	settingsKV["installed_at"] = time.Now().UTC().Format(time.RFC3339)
+
+	// 【修复】原版先写 settings 再循环插 voice,任一 voice 失败时已写入的
+	// 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
+	}
+
+	inserted, err := s.SetupApply(settingsKV, voices)
+	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.SetAuthAPIKeys([]string{authKey})
+	}
+
+	// 装完 reload TTS 全局配置(让 TTSOptions 立即有可用的 api_key/speaker/resource_id,
+	// 否则 /v1/audio/speech 会因为 TTSConfigErr 在启动期被设而返 503,要重启才生效)。
+	if err := setting.LoadRuntimeConfig(GetSetupStore()); err != nil {
+		log.Printf("[setup] warning: 装完 LoadRuntimeConfig 失败: %v(下次启动会恢复)", err)
+	}
+
+	log.Printf("[setup] 写入 settings=%d, voices=%d/%d (事务原子提交)", len(settingsKV), inserted, len(voices))
+
+	// 写 lock(原子):从这一刻起,/api/setup 永久关闭
+	if err := installer.CreateLock(GetSetupDBPath()); err != nil {
+		log.Printf("[setup] 写 lock 失败: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "failed to create install lock", "server_error", "lock_write_failed")
+		return
+	}
+	// 切到正常模式(本进程内)
+	installer.SetMode(installer.ModeNormal)
+	log.Printf("[setup] 安装完成!后续请求将进入正常模式")
+
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"ok":       true,
+		"message":  "installed",
+		"redirect": "/admin",
+		"settings": len(settingsKV),
+		"voices":   inserted,
+	})
+}
+
+// validateSetupSettings 校验必填项。
+// auth_key (鉴权) 也是必填 — 让 setup 成为"单一配置入口",
+// 用户装完不用再回去设 OPENAI_TTS_API_KEY env。
+func validateSetupSettings(m map[string]string) error {
+	required := []string{"api_key", "auth_key", "default_resource_id", "default_speaker"}
+	var missing []string
+	for _, k := range required {
+		if strings.TrimSpace(m[k]) == "" {
+			missing = append(missing, k)
+		}
+	}
+	if len(missing) > 0 {
+		return fmt.Errorf("missing required fields: %v", missing)
+	}
+	return nil
+}
+
+// validateSetupVoices 校验音色列表;至少 1 条。
+// 详细合法性(白名单、speaker 非空)由 store.VoiceInsert 负责。
+func validateSetupVoices(vs []SetupVoice) error {
+	if len(vs) == 0 {
+		return fmt.Errorf("at least one voice is required")
+	}
+	names := make(map[string]struct{}, len(vs))
+	for i, v := range vs {
+		if strings.TrimSpace(v.Name) == "" {
+			return fmt.Errorf("voices[%d]: name is required", i)
+		}
+		if strings.TrimSpace(v.Speaker) == "" {
+			return fmt.Errorf("voices[%d] (%s): speaker is required", i, v.Name)
+		}
+		// 【UX 改进】resource_id 留空是允许的 — 装时(下面那个循环)会自动用
+		// settings.default_resource_id 兜底。用户只填 step 2 一处即可。
+		_ = v.ResourceID // (保留以便以后加更细的校验)
+		if _, dup := names[v.Name]; dup {
+			return fmt.Errorf("voices[%d]: duplicate name %q", i, v.Name)
+		}
+		names[v.Name] = struct{}{}
+	}
+	return nil
+}
+
+// secureEqualString wraps common.SecureEqualString 保持向后兼容(原文件内已有调用)。
+func secureEqualString(a, b string) bool { return common.SecureEqualString(a, b) }

controller/tts.go

@@ -0,0 +1,341 @@
+package controller
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/volcano-tts/tts-api/adapter/volcano"
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/dto"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/metrics"
+	"github.com/volcano-tts/tts-api/middleware"
+	"github.com/volcano-tts/tts-api/setting"
+	"github.com/volcano-tts/tts-api/store"
+	"github.com/volcano-tts/tts-api/telemetry"
+	"github.com/volcano-tts/tts-api/version"
+)
+
+var (
+	volcanoClient *volcano.HTTPClient
+	adapterRec    volcano.MetricsRecorder = metrics.AdapterRecorder{}
+)
+
+func InitController() {
+	volcanoClient = volcano.NewHTTPClient()
+}
+
+func truncateForLog(b []byte, max int) string {
+	if len(b) > max {
+		return string(b[:max]) + fmt.Sprintf("...(truncated, total %d bytes)", len(b))
+	}
+	return string(b)
+}
+
+// resolveClientFormat 把 OpenAI 风格的 response_format 映射为最终输出格式;
+// 不识别或未指定时回退到 setting.GetTTSOptions().Format。
+func resolveClientFormat(reqFmt string) string {
+	switch strings.ToLower(reqFmt) {
+	case "mp3", "wav", "opus", "pcm", "aac", "flac":
+		if reqFmt == "opus" {
+			return "ogg_opus"
+		}
+		return strings.ToLower(reqFmt)
+	}
+	return setting.GetTTSOptions().Format
+}
+
+// OpenaiTTSHandler 是 /v1/audio/speech 的入口。
+func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
+	start := time.Now()
+
+	if r.Method != http.MethodPost {
+		log.Printf("警告: 错误的方法 - 方法=%s 期望=POST 路径=%s 客户端=%s",
+			r.Method, r.URL.Path, middleware.GetClientIP(r))
+		metrics.RequestTotal.Inc(telemetry.Labels{"status": "method_not_allowed", "format": "", "speaker": "", "model": ""})
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// 安装模式双保险:即使 InstallGuard 中间件没拦住,这里也 503 + 引导跳转
+	if installer.GetMode() == installer.ModeSetup {
+		log.Printf("[tts] 安装模式下拒绝 /v1/audio/speech - 客户端=%s", middleware.GetClientIP(r))
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		w.WriteHeader(http.StatusServiceUnavailable)
+		_, _ = w.Write([]byte(`{"error":"not installed","code":"install_required","redirect":"/setup"}`))
+		return
+	}
+
+	if !middleware.ValidateAPIKey(r) {
+		metrics.AuthFailed.Inc(telemetry.Labels{})
+		log.Printf("警告: API Key 鉴权失败 - 路径=%s 客户端=%s 远端=%s",
+			r.URL.Path, middleware.GetClientIP(r), r.RemoteAddr)
+		middleware.SendJSONError(w, http.StatusUnauthorized, "Invalid API key provided.", "invalid_request_error", "invalid_api_key")
+		return
+	}
+
+	if err := setting.GetTTSConfigErr(); err != nil {
+		log.Printf("警告: TTS配置未就绪,拒绝请求 - 错误=%v 路径=%s 客户端=%s",
+			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
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, common.MaxRequestBodySize)
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		if strings.Contains(err.Error(), "request body too large") {
+			log.Printf("警告: 请求体过大 - 路径=%s 客户端=%s 限制=%d字节",
+				r.URL.Path, middleware.GetClientIP(r), common.MaxRequestBodySize)
+			http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
+			return
+		}
+		log.Printf("警告: 读取请求体失败 - 路径=%s 客户端=%s 错误=%v",
+			r.URL.Path, middleware.GetClientIP(r), err)
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+
+	var req dto.OpenAITTSRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		log.Printf("警告: JSON 解析失败 - 路径=%s 客户端=%s 错误=%v body前200字节=%q",
+			r.URL.Path, middleware.GetClientIP(r), err, truncateForLog(body, 200))
+		http.Error(w, "Invalid JSON", http.StatusBadRequest)
+		return
+	}
+
+	if req.Model != "" {
+		if len(req.Model) > common.MaxModelNameLength {
+			log.Printf("警告: Model 名过长 - 路径=%s 客户端=%s 长度=%d 限制=%d",
+				r.URL.Path, middleware.GetClientIP(r), len(req.Model), common.MaxModelNameLength)
+			http.Error(w, fmt.Sprintf("Model name too long (max %d characters)", common.MaxModelNameLength), http.StatusBadRequest)
+			return
+		}
+		if strings.ContainsAny(req.Model, "\x00\n\r\t") {
+			log.Printf("警告: Model 名含非法字符 - 路径=%s 客户端=%s model前50字节=%q",
+				r.URL.Path, middleware.GetClientIP(r), truncateForLog([]byte(req.Model), 50))
+			http.Error(w, "Model name contains invalid characters", http.StatusBadRequest)
+			return
+		}
+	}
+
+	if req.Input == "" {
+		log.Printf("警告: input 字段为空 - 路径=%s 客户端=%s", r.URL.Path, middleware.GetClientIP(r))
+		http.Error(w, "Input text is required", http.StatusBadRequest)
+		return
+	}
+	if len(req.Input) > common.MaxTextLength {
+		log.Printf("警告: input 文本过长 - 路径=%s 客户端=%s 长度=%d 限制=%d",
+			r.URL.Path, middleware.GetClientIP(r), len(req.Input), common.MaxTextLength)
+		http.Error(w, fmt.Sprintf("Input text too long (max %d characters)", common.MaxTextLength), http.StatusBadRequest)
+		return
+	}
+
+	speed := req.Speed
+	if speed <= 0 {
+		speed = common.DefaultSpeed
+	}
+	if speed < common.MinSpeed {
+		speed = common.MinSpeed
+	}
+	if speed > common.MaxSpeed {
+		speed = common.MaxSpeed
+	}
+
+	clientFormat := resolveClientFormat(req.ResponseFormat)
+
+	opts := setting.GetTTSOptions()
+	opts.Text = req.Input
+
+	// M3: voice 路由
+	//   - voice 为空 → 走 LoadRuntimeConfig 解析过的 opts.Speaker (已是真 speaker ID,
+	//     default_speaker 是 voice 名,LoadRuntimeConfig 查 voice 表后替换)
+	//   - voice 非空 → 查 voices 表,替换 opts.Speaker / ResourceID / Model
+	//   - 命中但 enabled=0 → 仍可用(用户显式传 voice 即覆盖 enabled 状态;若想禁用在 admin UI 关掉就行)
+	//   - 未命中 → 400 "unknown voice: <name>"
+	if req.Voice != "" {
+		s := GetAdminStore()
+		if s == nil {
+			log.Printf("警告: voice=%s 路由但 store 未初始化 - 路径=%s", req.Voice, r.URL.Path)
+			middleware.SendJSONError(w, http.StatusServiceUnavailable,
+				"voice routing requires database; not initialized",
+				"configuration_error", "db_not_ready")
+			return
+		}
+		v, err := s.VoiceGetByName(req.Voice)
+		if err != nil {
+			if err == store.ErrNotFound {
+				log.Printf("警告: 未知 voice=%q - 路径=%s 客户端=%s", req.Voice, r.URL.Path, middleware.GetClientIP(r))
+				middleware.SendJSONError(w, http.StatusBadRequest,
+					fmt.Sprintf("unknown voice: '%s'", req.Voice),
+					"invalid_request_error", "unknown_voice")
+				return
+			}
+			log.Printf("警告: voice 查库失败 - 错误=%v voice=%s", err, req.Voice)
+			middleware.SendJSONError(w, http.StatusInternalServerError,
+				"voice lookup failed", "server_error", "db_read_failed")
+			return
+		}
+		// 覆盖 opts(API key / UID 保留自 setting.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), telemetry.MaskResourceID(v.ResourceID), v.Model, middleware.GetClientIP(r))
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), setting.GetTTSTimeout())
+	defer cancel()
+
+	result, err := volcano.Synthesis(ctx, volcanoClient, opts, req.Input, clientFormat, speed, adapterRec)
+	duration := time.Since(start)
+
+	finalLabels := telemetry.Labels{
+		"format":  clientFormat,
+		// speaker 是火山复刻音色 ID(用户付费资产),不能直接出现在 /metrics label 里
+		//(无鉴权可枚举)。用 sha1[:8] 替代:同 speaker 同 label 保留 per-voice 观测,
+		//但反推不出原值。Admin UI 想要看原名通过 /api/voices 拿 name 字段。
+		"speaker": telemetry.SpeakerLabel(opts.Speaker),
+		"model":   opts.Model,
+	}
+	if err != nil {
+		finalLabels["status"] = classifyStatus(err)
+		metrics.RequestTotal.Inc(finalLabels)
+		metrics.RequestDuration.Observe(duration.Seconds(), telemetry.Labels{"status": finalLabels["status"], "format": clientFormat})
+		log.Printf("警告: TTS 合成失败 - 路径=%s 客户端=%s 文本长度=%d 耗时=%v 错误=%v",
+			r.URL.Path, middleware.GetClientIP(r), len(req.Input), duration, err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "TTS synthesis failed.", "server_error", "synthesis_failed")
+		return
+	}
+
+	finalLabels["status"] = "ok"
+	metrics.RequestTotal.Inc(finalLabels)
+	metrics.RequestDuration.Observe(duration.Seconds(), telemetry.Labels{"status": "ok", "format": clientFormat})
+
+	w.Header().Set("Content-Type", contentTypeFor(result.Format))
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", len(result.AudioData)))
+	w.Header().Set("X-Request-Id", result.ReqID)
+	w.WriteHeader(http.StatusOK)
+	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 {
+	if ue, ok := err.(*volcano.UpstreamError); ok {
+		switch ue.Stage {
+		case "request":
+			return "request_error"
+		case "http":
+			return fmt.Sprintf("http_%d", ue.Code)
+		case "stream":
+			return "upstream_error"
+		case "wrap":
+			return "wrap_error"
+		}
+	}
+	return "internal_error"
+}
+
+func contentTypeFor(format string) string {
+	switch strings.ToLower(format) {
+	case "wav":
+		return "audio/wav"
+	case "mp3":
+		return "audio/mpeg"
+	case "ogg_opus", "opus":
+		return "audio/ogg"
+	case "pcm":
+		return "audio/L16"
+	case "aac":
+		return "audio/aac"
+	case "flac":
+		return "audio/flac"
+	}
+	return "application/octet-stream"
+}
+
+// HealthHandler 暴露运行期状态;无鉴权。
+func HealthHandler(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+
+	// 安装模式下 /health 仍然 200,但通过 installed 字段让探针/运维识别
+	// (Kubernetes readiness probe 可以用 installed=false 决定是否放流量)
+	mode := installer.GetMode()
+	if mode == installer.ModeSetup {
+		w.WriteHeader(http.StatusOK) // 200,因为进程活着,只是还没初始化
+	} else if setting.GetTTSConfigErr() != nil {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	} else {
+		w.WriteHeader(http.StatusOK)
+	}
+
+	env := setting.CheckEnvironmentVariables()
+	allRequired := env["all_required_vars_set"].(bool)
+
+	status := "ok"
+	if mode == installer.ModeSetup {
+		status = "not_installed"
+	} else if !allRequired {
+		status = "configuration_error"
+	}
+
+	resp := dto.HealthResponse{
+		Status:    status,
+		Service:   "ByteDance TTS to OpenAI API Adapter",
+		Version:   version.Version,
+		Commit:    version.Commit,
+		Uptime:    fmt.Sprintf("%.0f seconds", time.Since(startTime).Seconds()),
+		StartTime: startTime.Format(time.RFC3339),
+		Memory:    collectMemorySnapshot(),
+		ConfigStatus: dto.ConfigStatusResponse{
+			AllRequiredVarsSet: allRequired,
+			ConfigError:        setting.GetTTSConfigErr() != nil,
+			Error:              configErrorMessage(setting.GetTTSConfigErr()),
+		},
+		Installed: mode == installer.ModeNormal,
+		Mode:      mode.String(),
+	}
+	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 }
+
+func collectMemorySnapshot() map[string]interface{} {
+	var ms runtime.MemStats
+	runtime.ReadMemStats(&ms)
+	return map[string]interface{}{
+		"heap_alloc": ms.HeapAlloc,
+		"heap_inuse": ms.HeapInuse,
+		"goroutines": runtime.NumGoroutine(),
+	}
+}

docker-compose.yml

@@ -0,0 +1,32 @@
+services:
+  tts-api:
+    build: .
+    image: volcano-tts-aggregator:latest
+    container_name: tts-api
+    ports:
+      - "${PORT:-8080}:8080"
+    environment:
+      # 4 个启动引导 env(仅这 4 个必看)
+      # 业务配置(api_key/resource_id/speaker/格式...)通过 WebUI 设置,
+      # 存到 /data/tts.db 持久化
+      - TTS_ADMIN_KEY=${TTS_ADMIN_KEY:-}
+      - TTS_DB_PATH=/data/tts.db
+      - 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: 10s
+
+volumes:
+  tts-data:
+    name: tts-api-data

dto/health.go

@@ -0,0 +1,25 @@
+package dto
+
+// HealthResponse 是 /health 端点的 JSON 响应。
+// 数值类信息(请求统计、错误)迁移到 /metrics 端点,
+// 这里只保留运行期最关键的状态。
+type HealthResponse struct {
+	Status       string                 `json:"status"`
+	Service      string                 `json:"service"`
+	Version      string                 `json:"version"`
+	Commit       string                 `json:"commit"`
+	Uptime       string                 `json:"uptime"`
+	StartTime    string                 `json:"start_time"`
+	Memory       map[string]interface{} `json:"memory"`
+	ConfigStatus ConfigStatusResponse   `json:"config_status"`
+	// M1 新增:反映 installer 模式,便于部署探针/运维识别未初始化状态
+	Installed bool   `json:"installed"`
+	Mode      string `json:"mode"`
+}
+
+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"`
+}

dto/tts.go

@@ -0,0 +1,82 @@
+package dto
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// OpenAITTSRequest 是 /v1/audio/speech 接收的请求体。
+// 仅 input / speed / response_format 实际影响火山侧;
+// voice / model 当前保留接收但不做映射,详见 controller。
+type OpenAITTSRequest struct {
+	Model          string  `json:"model"`
+	Input          string  `json:"input"`
+	Voice          string  `json:"voice"`
+	ResponseFormat string  `json:"response_format,omitempty"`
+	Speed          float64 `json:"speed,omitempty"`
+}
+
+// V3TTSResponse 是火山 v3 HTTP Chunked 流式响应中每一行的 JSON 结构。
+// Sentence 字段上游有时返回字符串(TTSSentenceStart 里的句文本),有时返回对象
+// ({"phonemes":[...],"text":"...","words":[...]}),用 json.RawMessage 兼容两种形态,
+// 避免任意一种上游变更都导致整行解析失败。
+type V3TTSResponse struct {
+	ReqID    string          `json:"reqid"`
+	Code     int             `json:"code"`
+	Message  string          `json:"message"`
+	Event    string          `json:"event"`
+	Sequence int             `json:"sequence"`
+	Data     string          `json:"data"`
+	Sentence json.RawMessage `json:"sentence,omitempty"`
+	IsFinal  bool            `json:"is_final"`
+	Usage    *V3Usage        `json:"usage,omitempty"`
+}
+
+// SentenceText 从 Sentence 提取可读文本:
+//   - 字符串直接返回
+//   - 对象尝试取 .text 字段
+//   - 其它情况返回原始 JSON
+func (r *V3TTSResponse) SentenceText() string {
+	if len(r.Sentence) == 0 {
+		return ""
+	}
+	var s string
+	if err := json.Unmarshal(r.Sentence, &s); err == nil {
+		return s
+	}
+	var obj struct {
+		Text string `json:"text"`
+	}
+	if err := json.Unmarshal(r.Sentence, &obj); err == nil && obj.Text != "" {
+		return obj.Text
+	}
+	return string(r.Sentence)
+}
+
+// V3Usage 由 X-Control-Require-Usage-Tokens-Return 触发,包含计费字符数。
+type V3Usage struct {
+	TextWords int `json:"text_words"`
+}
+
+// SynthesisResult 是火山适配器向 controller 返回的最终结果。
+// Format 与 AudioData 的实际编码一致;controller 据此设置响应 Content-Type。
+type SynthesisResult struct {
+	AudioData  []byte
+	Format     string
+	SampleRate int
+	ReqID      string
+	TextWords  int           // 来自 V3Usage,无 usage 时为 0
+	Chunks     int           // 实际收到的音频 chunk 数
+	AudioBytes int           // 解码后总字节数
+	TTFB       time.Duration // 收到首个音频 chunk 的耗时
+	Duration   time.Duration // 整体合成耗时
+}
+
+// SubtitleEntry 描述一个字级时间戳条目(当 enable_subtitle / enable_timestamp 启用时返回)。
+type SubtitleEntry struct {
+	Text     string
+	StartMs  int
+	EndMs    int
+	Sequence int
+	// 原始事件可能为不同形态,这里只保留通用字段
+}

go.mod

@@ -1,8 +1,18 @@
-module bytedance-tts-openai-adapter
+module github.com/volcano-tts/tts-api
 
-go 1.19
+go 1.26
+
+require github.com/gorilla/mux v1.8.1
 
 require (
-	github.com/google/uuid v1.6.0
+	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/gorilla/mux v1.8.1
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	modernc.org/libc v1.74.4 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.57.0 // indirect
 )

go.sum

@@ -1,4 +1,22 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
 github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k=
+modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/sqlite v1.57.0 h1:qNQP6xnx5M0ISNtlnxoOX0+cD5bJ0/gr9aMmndFczzg=
+modernc.org/sqlite v1.57.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=

installer/bootstrap.go

@@ -0,0 +1,191 @@
+package installer
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/volcano-tts/tts-api/store"
+)
+
+// Mode 表示服务当前的运行模式。
+// 启动期由 Detect 确定,运行期不变。
+type Mode int
+
+const (
+	// ModeSetup 未安装,只放行 /setup + /api/setup/*。
+	ModeSetup Mode = iota
+	// ModeNormal 已安装,全部路由可用。
+	ModeNormal
+)
+
+func (m Mode) String() string {
+	switch m {
+	case ModeSetup:
+		return "setup"
+	case ModeNormal:
+		return "normal"
+	}
+	return "unknown"
+}
+
+// CurrentMode 是 Detect 确定的运行期模式;供 controller/middleware 双保险使用。
+// 进程内只有一个二进制实例,所以全局变量是合适的;不必走 DI。
+var CurrentMode Mode = ModeSetup // 默认 setup,Detect 后会被覆盖
+
+// SetMode 在 Detect 完成后调用,设置进程级模式。
+func SetMode(m Mode) { CurrentMode = m }
+
+// GetMode 返回进程级模式;Controller 双保险用。
+func GetMode() Mode { return CurrentMode }
+
+// Result 是 Detect 的完整输出;调用方关心 Mode + 一些诊断信息。
+type Result struct {
+	Mode      Mode
+	DBPath    string // 实际打开的 db 路径
+	LockPath  string
+	Corrupted bool   // 这次启动是否从损坏回退
+	BackupTo  string // 损坏回退时备份文件路径
+}
+
+// ErrInUse 标识在 Detect 期间发现 db 正在被另一个进程占用;
+// 这种情况下不应该自动 rename,会破坏另一个进程的运行。
+// 上层应记录日志并按"装模式"启动,等下次重启再处理。
+var ErrInUse = errors.New("installer: database is locked by another process")
+
+// Detect 是启动期的总入口:打开/创建 db、判定 lock、检测损坏并自愈。
+//
+// 流程:
+//  1. Open db(可能新建)
+//  2. 检查 lock:
+//     - 不存在 → ModeSetup
+//     - 存在 → 跑 IntegrityCheck
+//     - 通过 → ModeNormal
+//     - 不通过 → 备份 db.corrupt-<ts> + 删 lock + ModeSetup(并标记 Corrupted=true)
+//
+// 返回的 *store.Store 必须由调用方在进程退出时 Close。
+func Detect(dbPath string) (*store.Store, Result, error) {
+	if dbPath == "" {
+		return nil, Result{}, fmt.Errorf("installer: db path is empty")
+	}
+
+	res := Result{
+		DBPath:   dbPath,
+		LockPath: LockPath(dbPath),
+	}
+
+	s, err := store.Open(dbPath)
+	if err != nil {
+		// 打开失败通常意味着文件损坏;走自愈回退。
+		// 重要:不要区分"不存在"和"损坏"——SQLite 第一次 Open 会自动建空库,
+		// 如果"不存在"能走到这里说明更严重的系统错误,也不该贸然启动。
+		if backup, ok := tryBackupCorrupt(dbPath, err); ok {
+			res.Corrupted = true
+			res.BackupTo = backup
+			log.Printf("[installer] 检测到损坏 db,已备份到 %q,删除 lock,回退到安装模式", backup)
+		} else {
+			return nil, res, fmt.Errorf("installer: open db %q failed: %w", dbPath, err)
+		}
+	}
+
+	// lock 状态判定
+	exists, err := LockExists(dbPath)
+	if err != nil {
+		if s != nil {
+			_ = s.Close()
+		}
+		return nil, res, fmt.Errorf("installer: lock check failed: %w", err)
+	}
+	if !exists {
+		res.Mode = ModeSetup
+		SetMode(ModeSetup)
+		if !res.Corrupted {
+			log.Printf("[installer] 启动模式: 安装模式(无 lock 文件)")
+		}
+		return s, res, nil
+	}
+
+	// lock 在,跑完整性检查
+	if s == nil {
+		// 自愈回退已经走完,应该删了 lock;但保险起见再删一次
+		if err := DeleteLock(dbPath); err != nil {
+			return nil, res, fmt.Errorf("installer: delete lock after fallback: %w", err)
+		}
+		res.Mode = ModeSetup
+		SetMode(ModeSetup)
+		return nil, res, nil
+	}
+
+	check, err := s.IntegrityCheck()
+	if err != nil {
+		_ = s.Close()
+		// integrity_check 自身报错,等同损坏,走自愈
+		backup, ok := tryBackupCorrupt(dbPath, err)
+		if !ok {
+			return nil, res, fmt.Errorf("installer: integrity_check failed: %w", err)
+		}
+		_ = DeleteLock(dbPath)
+		res.Corrupted = true
+		res.BackupTo = backup
+		res.Mode = ModeSetup
+		SetMode(ModeSetup)
+		log.Printf("[installer] integrity_check 错误,已备份到 %q,删除 lock,回退到安装模式", backup)
+		return nil, res, nil
+	}
+	if check != "ok" {
+		_ = s.Close()
+		backup, ok := tryBackupCorrupt(dbPath, fmt.Errorf("integrity_check returned: %s", check))
+		if !ok {
+			return nil, res, fmt.Errorf("installer: integrity_check = %q (not ok)", check)
+		}
+		_ = DeleteLock(dbPath)
+		res.Corrupted = true
+		res.BackupTo = backup
+		res.Mode = ModeSetup
+		SetMode(ModeSetup)
+		log.Printf("[installer] 库不完整(integrity_check=%q),已备份到 %q,删除 lock,回退到安装模式", check, backup)
+		return nil, res, nil
+	}
+
+	res.Mode = ModeNormal
+	SetMode(ModeNormal)
+	log.Printf("[installer] 启动模式: 正常模式(lock=%s)", res.LockPath)
+	return s, res, nil
+}
+
+// tryBackupCorrupt 尝试把损坏的 db 文件 rename 为 .corrupt-<unix-ms>;
+// 成功返回 (新路径, true),失败 (任何原因) 返回 ("", false)。
+// 注意:这里不返回 error,因为 "无法备份" 不应阻止回退(可以后续人工排查)。
+func tryBackupCorrupt(dbPath string, reason error) (string, bool) {
+	if dbPath == "" {
+		return "", false
+	}
+	// 不存在的话没法 rename(也没必要)
+	if _, err := os.Stat(dbPath); err != nil {
+		return "", false
+	}
+	ts := time.Now().UnixMilli()
+	backup := fmt.Sprintf("%s.corrupt-%d", dbPath, ts)
+	if err := os.Rename(dbPath, backup); err != nil {
+		log.Printf("[installer] 备份损坏 db 失败: %v(将直接重建空库)", err)
+		return "", false
+	}
+	log.Printf("[installer] 损坏原因: %v", reason)
+	return backup, true
+}
+
+// EnsureDBDir 确保 dbPath 所在目录存在(对首次安装很有用;
+// 当 dbDir 是新目录时 store.Open 之前需要先 mkdir)。
+func EnsureDBDir(dbPath string) error {
+	if dbPath == "" {
+		return nil
+	}
+	dir := filepath.Dir(dbPath)
+	if dir == "" || dir == "." {
+		return nil
+	}
+	return os.MkdirAll(dir, 0o755)
+}

installer/lock.go

@@ -0,0 +1,121 @@
+// Package installer 负责安装状态判定:lock 文件检测/创建/删除、
+// 启动期 Detect 流程、损坏自愈回退。
+//
+// 设计要点:
+//   - lock 文件路径: <dbDir>/installed.lock,与 tts.db 同目录
+//   - lock 不存在 = 未安装(进入安装模式)
+//   - lock 存在 + 库 OK = 已安装(正常模式)
+//   - lock 存在 + 库损坏 = 自动备份 + 删 lock + 回到安装模式
+//   - 写顺序: 先写库,后写 lock(避免 lock 在、库是半成品)
+//   - 写锁用临时文件 + 原子 rename,避免崩溃中途留半成品 lock
+package installer
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// lockFileName 是 lock 文件名;固定不变,所有部署共用。
+const lockFileName = "installed.lock"
+
+// schemaVersion 是 lock 内容里的 schema 版本号;留作未来版本兼容判断。
+// 未来若有破坏性升级,可读这个值决定是否要重装/迁移。
+const schemaVersion = "1"
+
+// LockPath 返回给定 db 路径下 lock 文件的绝对路径。
+// dbPath 通常是 .db 文件路径(不是目录);若传入目录则直接拼 lockFileName。
+func LockPath(dbPath string) string {
+	if dbPath == "" {
+		return lockFileName
+	}
+	// 如果 dbPath 是已存在的目录,直接拼文件名
+	if info, err := os.Stat(dbPath); err == nil && info.IsDir() {
+		return filepath.Join(dbPath, lockFileName)
+	}
+	dir := filepath.Dir(dbPath)
+	return filepath.Join(dir, lockFileName)
+}
+
+// ErrLockExists 表示 lock 已存在;CreateLock 会返回这个,提醒上层别覆盖。
+var ErrLockExists = errors.New("installer: lock already exists")
+
+// LockExists 检测 lock 文件是否存在;不存在不算错误(常见的"未安装"状态)。
+func LockExists(dbPath string) (bool, error) {
+	p := LockPath(dbPath)
+	_, err := os.Stat(p)
+	if err == nil {
+		return true, nil
+	}
+	if errors.Is(err, os.ErrNotExist) {
+		return false, nil
+	}
+	return false, fmt.Errorf("installer: stat lock %q: %w", p, err)
+}
+
+// CreateLock 原子写入 lock 文件;lock 已存在返回 ErrLockExists。
+// 内容: "version <schemaVersion> <RFC3339 时间戳>"
+func CreateLock(dbPath string) error {
+	exists, err := LockExists(dbPath)
+	if err != nil {
+		return err
+	}
+	if exists {
+		return ErrLockExists
+	}
+
+	p := LockPath(dbPath)
+	content := fmt.Sprintf("version %s %s\n", schemaVersion, time.Now().UTC().Format(time.RFC3339))
+
+	// 原子写入:先写临时文件,再 rename
+	dir := filepath.Dir(p)
+	tmp, err := os.CreateTemp(dir, ".installed.lock.*.tmp")
+	if err != nil {
+		return fmt.Errorf("installer: create lock tmp: %w", err)
+	}
+	tmpName := tmp.Name()
+	// 确保临时文件最终被清理(出错时)
+	defer func() {
+		_ = os.Remove(tmpName)
+	}()
+
+	if _, err := tmp.WriteString(content); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("installer: write lock tmp: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("installer: close lock tmp: %w", err)
+	}
+	if err := os.Rename(tmpName, p); err != nil {
+		return fmt.Errorf("installer: rename lock tmp: %w", err)
+	}
+	return nil
+}
+
+// DeleteLock 删 lock;不存在不报错。
+// 主要用于损坏自愈流程和测试清理。
+func DeleteLock(dbPath string) error {
+	p := LockPath(dbPath)
+	err := os.Remove(p)
+	if err == nil || errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	return fmt.Errorf("installer: remove lock %q: %w", p, err)
+}
+
+// ReadLock 读 lock 内容;主要用于诊断日志和未来版本兼容判断。
+// 不存在返回 ("", nil)。
+func ReadLock(dbPath string) (string, error) {
+	p := LockPath(dbPath)
+	b, err := os.ReadFile(p)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return "", nil
+		}
+		return "", fmt.Errorf("installer: read lock %q: %w", p, err)
+	}
+	return strings.TrimSpace(string(b)), nil
+}

main.go

@@ -0,0 +1,140 @@
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/volcano-tts/tts-api/controller"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/metrics"
+	"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。
+func ttsDBPath() string {
+	if p := os.Getenv("TTS_DB_PATH"); p != "" {
+		return p
+	}
+	return "tts.db"
+}
+
+func main() {
+	log.SetFlags(log.LstdFlags | log.Lshortfile)
+	log.SetPrefix("[TTS-Server] ")
+
+	// 1) 加载引导环境变量(PORT / TTS_ADMIN_KEY / OPENAI_TTS_API_KEY 兜底)
+	// 注: Auth.APIKeys 在 InitAllConfigs 里先读 env,后被 LoadRuntimeConfig 覆盖为 DB 值。
+	setting.InitAllConfigs()
+	metrics.Init()
+	middleware.InitRateLimiter()
+
+	// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
+	dbPath := ttsDBPath()
+	if err := installer.EnsureDBDir(dbPath); err != nil {
+		log.Fatalf("FATAL: cannot create db dir: %v", err)
+	}
+	st, res, err := installer.Detect(dbPath)
+	if err != nil {
+		log.Fatalf("FATAL: installer detect failed: %v", err)
+	}
+	if res.Corrupted {
+		log.Printf("[main] 注意: 启动时检测到 db 损坏并已自愈回退(备份=%s)", res.BackupTo)
+	}
+
+	// 3) 注入 setup/admin 控制器需要的句柄(M1+M2)
+	controller.SetSetupState(st, dbPath)
+	controller.SetAdminStore(st)
+	controller.SetMetricsTextWriter(func(w http.ResponseWriter) error {
+		metrics.Meter.Handler().ServeHTTP(w, &http.Request{})
+		return nil
+	})
+
+	// 4) M3: 从 store 加载运行时 TTS 配置(替代原来的 env-based InitTTSConfig)
+	// 必须在 LogStartupSummary 之前,这样日志显示的是真实状态(API key 已从 DB 加载,不再读 env)
+	//
+	// 模式区分:
+	//   - setup 模式 + 失败 = 正常(还没装), 警告即可
+	//   - normal 模式 + 失败 = 致命(已装但配置坏), fail-fast 让 K8s/进程管理器拉起
+	if st != nil {
+		if err := setting.LoadRuntimeConfig(st); err != nil {
+			mode := installer.GetMode()
+			modeName := "setup"
+			if mode == installer.ModeNormal {
+				modeName = "normal"
+			}
+			metrics.ConfigLoadFailures.Inc(telemetry.Labels{"mode": modeName})
+			if mode == installer.ModeNormal {
+				log.Printf("[main][FATAL] TTS 运行时配置加载失败 (normal mode, 服务无法启动): %v", err)
+				log.Fatalf("service cannot start in normal mode without valid config: %v", err)
+			}
+			log.Printf("[main][WARN] TTS 运行时配置加载失败 (setup mode, 需先 /setup): %v", err)
+		} else {
+			opts := setting.GetTTSOptions()
+			log.Printf("[main] TTS 运行时配置已加载(api_key=***, speaker=%s, resource=%s, format=%s)",
+				telemetry.MaskSpeaker(opts.Speaker), telemetry.MaskResourceID(opts.ResourceID), opts.Format)
+		}
+	}
+
+	// 5) 启动摘要日志(此时 Auth.APIKeys 已是 DB 值,日志反映真实状态)
+	setting.LogStartupSummary()
+	log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
+
+	controller.InitController()
+	controller.SetStartTime(time.Now())
+
+	r := router.Setup()
+
+	server := &http.Server{
+		Addr:         ":" + setting.Server.Port,
+		Handler:      middleware.CORS(r),
+		ReadTimeout:  30 * time.Second,
+		WriteTimeout: 120 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	go func() {
+		if installer.GetMode() == installer.ModeSetup {
+			log.Printf("Starting TTS Server in SETUP mode")
+			log.Printf("Open browser to http://localhost:%s/setup to install", setting.Server.Port)
+		} else {
+			log.Printf("Starting ByteDance TTS to OpenAI API Adapter Server")
+			log.Printf("Listening on port: %s", setting.Server.Port)
+			log.Printf("OpenAI TTS endpoint: http://localhost:%s/v1/audio/speech", setting.Server.Port)
+			log.Printf("Admin WebUI: http://localhost:%s/admin", setting.Server.Port)
+		}
+		log.Printf("Health check: http://localhost:%s/health", setting.Server.Port)
+		log.Printf("Metrics: http://localhost:%s/metrics", setting.Server.Port)
+
+		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("Server failed to start: %v", err)
+		}
+	}()
+
+	<-quit
+	log.Println("Shutting down server...")
+
+	// 关闭 db 连接(仅当 st 非 nil 时)
+	if st != nil {
+		_ = st.Close()
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err := server.Shutdown(ctx); err != nil {
+		log.Printf("Server forced to shutdown: %v", err)
+	} else {
+		log.Println("Server exited gracefully")
+	}
+}

metrics/metrics.go

@@ -0,0 +1,172 @@
+// Package metrics 集中声明本服务所有埋点指标,并提供 telemetry.Meter 的全局访问入口。
+//
+// 设计:
+//   - 启动期 Init() 一次性注册所有指标;Panic 表示有重名 bug,应立即暴露。
+//   - 上游适配器通过 AdapterRecorder 接入,无需直接 import telemetry。
+//   - 控制器 / 中间件通过本包的全局变量直接 Inc/Observe/Set。
+package metrics
+
+import (
+	"time"
+
+	"github.com/volcano-tts/tts-api/telemetry"
+)
+
+var (
+	// Meter 全局 telemetry Meter。
+	Meter telemetry.Meter = telemetry.NoopMeter{}
+
+	// HTTP 请求侧
+	RequestTotal    *telemetry.Counter
+	RequestDuration *telemetry.Histogram
+
+	// 上游 TTS 调用侧
+	UpstreamTotal    *telemetry.Counter
+	UpstreamDuration *telemetry.Histogram
+	UpstreamTTFB     *telemetry.Histogram
+	UpstreamChunks   *telemetry.Counter
+	UpstreamBytes    *telemetry.Counter
+	UpstreamErrors   *telemetry.Counter
+	UpstreamUsage    *telemetry.Counter
+
+	// 限流 / 并发 / 鉴权
+	ConcurrencyActive   *telemetry.Gauge
+	ConcurrencyRejected *telemetry.Counter
+	RateLimitRejected   *telemetry.Counter
+	AuthFailed          *telemetry.Counter
+
+	// 启动期配置加载失败(仅 normal 模式可能触发,触发后服务 fail-fast)
+	ConfigLoadFailures *telemetry.Counter
+)
+
+// Init 初始化所有指标。在 main 启动期调用一次。
+func Init() {
+	m := telemetry.NewMeter()
+	Meter = m
+
+	RequestTotal = m.NewCounter(
+		"tts_request_total",
+		"Total /v1/audio/speech requests, labeled by status and chosen format/speaker/model.",
+		"status", "format", "speaker", "model",
+	)
+	RequestDuration = m.NewHistogram(
+		"tts_request_duration_seconds",
+		"End-to-end /v1/audio/speech latency in seconds.",
+		telemetry.DefaultLatencyBuckets,
+		"status", "format",
+	)
+
+	UpstreamTotal = m.NewCounter(
+		"tts_upstream_total",
+		"Total upstream TTS calls, labeled by status.",
+		"status", "format", "model", "speaker",
+	)
+	UpstreamDuration = m.NewHistogram(
+		"tts_upstream_duration_seconds",
+		"Upstream TTS call duration in seconds.",
+		telemetry.DefaultLatencyBuckets,
+		"status", "format",
+	)
+	UpstreamTTFB = m.NewHistogram(
+		"tts_upstream_first_byte_seconds",
+		"Time from request send to first audio chunk, in seconds.",
+		telemetry.DefaultLatencyBuckets,
+		"format",
+	)
+	UpstreamChunks = m.NewCounter(
+		"tts_upstream_chunks_total",
+		"Total audio chunks received from upstream.",
+		"format",
+	)
+	UpstreamBytes = m.NewCounter(
+		"tts_upstream_audio_bytes_total",
+		"Total audio bytes (post-wrap) returned to clients.",
+		"format",
+	)
+	UpstreamErrors = m.NewCounter(
+		"tts_upstream_errors_total",
+		"Upstream TTS errors, labeled by error code family.",
+		"code",
+	)
+	UpstreamUsage = m.NewCounter(
+		"tts_usage_text_words_total",
+		"Text words charged by upstream, per model.",
+		"model",
+	)
+
+	ConcurrencyActive = m.NewGauge(
+		"tts_concurrency_active",
+		"Current in-flight request count.",
+	)
+	ConcurrencyRejected = m.NewCounter(
+		"tts_concurrency_rejected_total",
+		"Requests rejected due to concurrency limit.",
+	)
+	RateLimitRejected = m.NewCounter(
+		"tts_ratelimit_rejected_total",
+		"Requests rejected due to per-IP rate limit.",
+	)
+	AuthFailed = m.NewCounter(
+		"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。
+type AdapterRecorder struct{}
+
+// UpstreamStarted 满足 volcano.MetricsRecorder 接口。
+func (AdapterRecorder) UpstreamStarted(speaker, model, format string) {
+	// speaker 用 sha1[:8] 替代,保护火山复刻音色 ID
+	// (无鉴权 /metrics 端点可枚举,这是 P0 隐私问题)
+	UpstreamTotal.Inc(telemetry.Labels{"status": "started", "format": format, "model": model, "speaker": telemetry.SpeakerLabel(speaker)})
+}
+
+// UpstreamFinished 满足 volcano.MetricsRecorder 接口。
+func (AdapterRecorder) UpstreamFinished(speaker, model, format, status string, duration, ttfb time.Duration, chunks, audioBytes, errCode int) {
+	labels := telemetry.Labels{"status": status, "format": format, "model": model, "speaker": telemetry.SpeakerLabel(speaker)}
+	UpstreamTotal.Inc(labels)
+	UpstreamDuration.Observe(duration.Seconds(), telemetry.Labels{"status": status, "format": format})
+	if ttfb > 0 {
+		UpstreamTTFB.Observe(ttfb.Seconds(), telemetry.Labels{"format": format})
+	}
+	if chunks > 0 {
+		UpstreamChunks.Add(float64(chunks), telemetry.Labels{"format": format})
+	}
+	if audioBytes > 0 {
+		UpstreamBytes.Add(float64(audioBytes), telemetry.Labels{"format": format})
+	}
+	// 上游调用只要 status != "ok" 即视为错误。原版 if errCode != 0 会漏掉
+	// errCode=0 的 request_error / transport_error / wrap_error / stream_error
+	// (code=0 的流错误) 等场景,导致 transport 类错误在 /metrics 上完全不可见。
+	if status != "ok" {
+		UpstreamErrors.Inc(telemetry.Labels{"code": codeLabel(errCode)})
+	}
+}
+
+// UpstreamUsage 满足 volcano.MetricsRecorder 接口。
+func (AdapterRecorder) UpstreamUsage(model string, textWords int) {
+	if textWords <= 0 {
+		return
+	}
+	UpstreamUsage.Add(float64(textWords), telemetry.Labels{"model": model})
+}
+
+// codeLabel 把整数错误码格式化为 label value,聚合到 4 类便于仪表盘展示。
+func codeLabel(code int) string {
+	switch {
+	case code == 0:
+		return "transport"
+	case code >= 400 && code < 500:
+		return "client"
+	case code >= 500 && code < 600:
+		return "server"
+	default:
+		return "upstream"
+	}
+}

middleware/admin_auth.go

@@ -0,0 +1,73 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"strings"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+// RequireAdmin 是 /admin 路由的鉴权中间件,复用 OPENAI_TTS_API_KEY。
+// 行为:
+//   - Auth.APIKeys 为空 → 所有请求放行(等同无鉴权)
+//   - Authorization 头 Bearer token 在列表中 → 放行
+//   - 其它 → 401 + JSON {error: 'unauthorized', code: 'admin_auth_failed'}
+//
+// 设计: 与现有 /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) {
+		// 预检: 跨域/OPTIONS 直接放行(让浏览器能发 preflight)
+		if r.Method == http.MethodOptions {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		keys := setting.GetAuthAPIKeys()
+		if len(keys) == 0 {
+			// 没配 admin key,等同无鉴权
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		auth := r.Header.Get("Authorization")
+		const prefix = "Bearer "
+		if !strings.HasPrefix(auth, prefix) {
+			denyAdmin(w, r)
+			return
+		}
+		token := strings.TrimSpace(auth[len(prefix):])
+		if !inAPIKeyList(token, keys) {
+			denyAdmin(w, r)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// inAPIKeyList 用常量时间比较,防 token 计时攻击。
+// 单个 key 也走同一条路径,无差别处理。
+func inAPIKeyList(token string, keys []string) bool {
+	if token == "" {
+		return false
+	}
+	match := false
+	for _, k := range keys {
+		if common.SecureEqualString(token, k) {
+			match = true
+			// 不 break,继续遍历,保持时间恒定
+		}
+	}
+	return match
+}
+
+// denyAdmin 写 401 + JSON 错误体,记录客户端 IP。
+func denyAdmin(w http.ResponseWriter, r *http.Request) {
+	log.Printf("[admin_auth] 鉴权失败 - 路径=%s 客户端=%s", r.URL.Path, GetClientIP(r))
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.Header().Set("WWW-Authenticate", `Bearer realm="tts-admin"`)
+	w.WriteHeader(http.StatusUnauthorized)
+	_, _ = w.Write([]byte(`{"error":{"code":"admin_auth_failed","message":"unauthorized","type":"authentication_error"}}`))
+}

middleware/auth.go

@@ -0,0 +1,46 @@
+package middleware
+
+import (
+	"crypto/subtle"
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+func ValidateAPIKey(r *http.Request) bool {
+	keys := setting.GetAuthAPIKeys()
+	if len(keys) == 0 {
+		return true
+	}
+
+	authHeader := r.Header.Get("Authorization")
+	if authHeader == "" {
+		return false
+	}
+
+	if !strings.HasPrefix(authHeader, "Bearer ") {
+		return false
+	}
+
+	token := strings.TrimPrefix(authHeader, "Bearer ")
+	for _, validKey := range keys {
+		if subtle.ConstantTimeCompare([]byte(token), []byte(validKey)) == 1 {
+			return true
+		}
+	}
+	return false
+}
+
+func SendJSONError(w http.ResponseWriter, statusCode int, message string, errType string, code string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	json.NewEncoder(w).Encode(map[string]interface{}{
+		"error": map[string]interface{}{
+			"message": message,
+			"type":    errType,
+			"code":    code,
+		},
+	})
+}

middleware/cors.go

@@ -0,0 +1,168 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"strings"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+var (
+	corsMaxAgeHeader = "86400"
+)
+
+func isValidOrigin(origin string) bool {
+	if origin == "" || origin == "null" || origin == "nil" {
+		return false
+	}
+	lowerOrigin := strings.ToLower(origin)
+	if !strings.HasPrefix(lowerOrigin, "http://") && !strings.HasPrefix(lowerOrigin, "https://") {
+		return false
+	}
+	return true
+}
+
+func matchOrigin(origin string) (string, bool) {
+	if !isValidOrigin(origin) {
+		return "", false
+	}
+	if setting.GetCORSAllowAll() {
+		return "*", true
+	}
+	normalized := strings.ToLower(strings.TrimRight(strings.TrimSpace(origin), "/"))
+	for _, allowed := range setting.GetCORSOrigins() {
+		if allowed == normalized {
+			return origin, true
+		}
+	}
+	return "", false
+}
+
+// isSameOrigin 比较 Origin 与 r.Host,判断是否同源。
+//   - 直接访问(server 自己:80): Origin=http://server:80, Host=server:80 → 同源
+//   - 反向代理(https://app.example.com → http://server:80):
+//     Origin=https://app.example.com, Host=server:80
+//     默认不同源;但如果设置 TRUSTED_PROXY_HOPS 或 X-Forwarded-Host,要让它们一致。
+//   - 浏览器对同源 POST 也会设 Origin(避免被自己的 CORS 误伤),这里豁免。
+// 返回 true 表示请求来自自己,无需 CORS 介入。
+func isSameOrigin(r *http.Request) bool {
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		return false
+	}
+	// 解析 Origin 的 host 部分
+	originHost, originScheme := splitOrigin(origin)
+	if originHost == "" {
+		return false
+	}
+	// 优先用 X-Forwarded-Host / X-Forwarded-Proto(反向代理场景),
+	// 退而用 r.Host(直接访问场景)
+	reqHost := r.Host
+	if fh := r.Header.Get("X-Forwarded-Host"); fh != "" {
+		// X-Forwarded-Host 可能是 host1, host2 (取第一个)
+		if i := strings.Index(fh, ","); i >= 0 {
+			fh = strings.TrimSpace(fh[:i])
+		}
+		reqHost = fh
+	}
+	reqScheme := "http"
+	if r.TLS != nil {
+		reqScheme = "https"
+	} else if fp := r.Header.Get("X-Forwarded-Proto"); fp != "" {
+		if i := strings.Index(fp, ","); i >= 0 {
+			fp = strings.TrimSpace(fp[:i])
+		}
+		reqScheme = strings.ToLower(fp)
+	}
+	// host 匹配(忽略大小写)
+	return strings.EqualFold(originHost, reqHost) && strings.EqualFold(originScheme, reqScheme)
+}
+
+// splitOrigin 把 "https://example.com:8080" 拆成 ("example.com:8080", "https")。
+// 没有 scheme 时返回 ("", "")。
+func splitOrigin(origin string) (host, scheme string) {
+	idx := strings.Index(origin, "://")
+	if idx < 0 || idx == 0 {
+		return "", ""
+	}
+	scheme = origin[:idx]
+	rest := origin[idx+3:]
+	// 去掉 path 部分
+	if i := strings.Index(rest, "/"); i >= 0 {
+		rest = rest[:i]
+	}
+	return rest, scheme
+}
+
+func CORS(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 安装模式完全跳过 CORS:
+		//   - 用户首次装,不可能提前知道自己的访问域名来配 ALLOWED_ORIGINS
+		//   - 装完进 normal 模式后,设的 CORS 才生效(从 DB 读)
+		// 这样 install 永远能成功,装完再通过 WebUI 配 CORS。
+		if installer.GetMode() == installer.ModeSetup {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		origin := r.Header.Get("Origin")
+
+		// 无 Origin 头:非跨域请求,跳过 CORS 处理
+		if origin == "" {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		// 同源豁免:浏览器对同源 POST/JSON 也会发 Origin 头(防 fetch 滥用),
+		// 但同源请求本就不需要 CORS 介入。这里对比 Origin 与 Host(含 X-Forwarded-*),
+		// 一致就放行,避免自家人被自家 CORS 拦。
+		if isSameOrigin(r) {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		// 有 Origin 头时,响应必须携带 Vary: Origin 防止 CDN 缓存污染
+		vary := w.Header().Get("Vary")
+		if vary == "" {
+			w.Header().Set("Vary", "Origin")
+		} else if !strings.Contains(vary, "Origin") {
+			w.Header().Set("Vary", vary+", Origin")
+		}
+
+		isPreflight := r.Method == http.MethodOptions
+
+		allowOrigin, matched := matchOrigin(origin)
+		if !matched {
+			// Origin 不在白名单:拒绝请求(预检和非预检均拒绝),
+			// 防止不匹配的请求穿透到后端浪费 TTS 资源
+			if common.DebugLog {
+				log.Printf("CORS拦截: 来源=%q 路径=%s 方法=%s 客户端=%s",
+					origin, r.URL.Path, r.Method, GetClientIP(r))
+			}
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+
+		// Origin 匹配:设置 CORS 响应头
+		w.Header().Set("Access-Control-Allow-Origin", allowOrigin)
+		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)
+		if allowOrigin != "*" {
+			w.Header().Set("Access-Control-Allow-Credentials", "true")
+		}
+
+		// 预检请求:直接返回 204,不进入内层中间件链,
+		// 避免消耗速率限制配额和并发槽位
+		if isPreflight {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}

middleware/installguard.go

@@ -0,0 +1,81 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"strings"
+
+	"github.com/volcano-tts/tts-api/installer"
+)
+
+// InstallGuard 拦截所有非白名单路由,在安装模式下按 Accept 头做内容协商:
+//
+//   - text/html 类(浏览器) → 302 重定向到 /setup
+//   - 其它(API 客户端、curl 等) → 503 + JSON
+//
+// 设计:放行白名单路径前缀,其余一律拦截。
+// 中间件顺序:必须装在 RateLimit / ConcurrencyLimit / Logger 之前,
+// 避免安装模式下被限流计数污染(参考 M1 风险点 #2)。
+func InstallGuard(currentMode func() installer.Mode, allowPrefixes ...string) func(http.Handler) http.Handler {
+	defaults := []string{
+		"/setup",          // 安装引导页
+		"/api/setup",      // 安装相关 API
+		"/health",         // 部署探针要能识别未安装状态
+		"/metrics",        // Prometheus 拉取
+		"/static/",        // 引导页静态资源(留口子)
+	}
+	allow := append(defaults, allowPrefixes...)
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if currentMode() != installer.ModeSetup {
+				next.ServeHTTP(w, r)
+				return
+			}
+			// 安装模式:仅放行白名单
+			path := r.URL.Path
+			for _, p := range allow {
+				if strings.HasPrefix(path, p) {
+					next.ServeHTTP(w, r)
+					return
+				}
+			}
+			log.Printf("[installguard] 安装模式下拒绝非白名单请求 - 路径=%s 客户端=%s accept=%q",
+				path, GetClientIP(r), r.Header.Get("Accept"))
+			// 内容协商:浏览器自动跳 /setup,API 客户端拿 JSON。
+			// / 不在白名单里,所以这里同时覆盖"敲域名根路径"和"敲其他路径"两种场景。
+			if acceptsHTML(r.Header.Get("Accept")) {
+				w.Header().Set("Location", "/setup")
+				w.WriteHeader(http.StatusFound) // 302
+				return
+			}
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			w.WriteHeader(http.StatusServiceUnavailable)
+			_, _ = w.Write([]byte(`{"error":"not installed","code":"install_required","redirect":"/setup"}`))
+		})
+	}
+}
+
+// acceptsHTML 判断客户端是否接受 HTML 响应。
+// 严格匹配:Accept 必须显式包含 text/html 或 text/*,避免通配 */*(curl/API 默认)
+// 走 302 路径影响 API 行为。
+func acceptsHTML(accept string) bool {
+	if accept == "" {
+		return false
+	}
+	for _, part := range strings.Split(accept, ",") {
+		mt := strings.TrimSpace(part)
+		if mt == "" {
+			continue
+		}
+		// 去掉 q= 等参数
+		if idx := strings.Index(mt, ";"); idx >= 0 {
+			mt = strings.TrimSpace(mt[:idx])
+		}
+		mt = strings.ToLower(mt)
+		if mt == "text/html" || mt == "text/*" {
+			return true
+		}
+	}
+	return false
+}

middleware/logger.go

@@ -0,0 +1,32 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type statusRecorder struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+func (rec *statusRecorder) WriteHeader(code int) {
+	rec.statusCode = code
+	rec.ResponseWriter.WriteHeader(code)
+}
+
+func Logger(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		rec := &statusRecorder{ResponseWriter: w, statusCode: http.StatusOK}
+		next.ServeHTTP(rec, r)
+		duration := time.Since(start)
+
+		// r.RequestURI 是未经解析的原始请求行,攻击者可在 URL 中注入
+		// \n / \r 伪造日志行。转义为可见字符后再记录。
+		uri := strings.NewReplacer("\n", "\\n", "\r", "\\r").Replace(r.RequestURI)
+		log.Printf("%s %s %s %d %v", r.Method, uri, r.RemoteAddr, rec.statusCode, duration)
+	})
+}

middleware/ratelimit.go

@@ -0,0 +1,244 @@
+package middleware
+
+import (
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/metrics"
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+type RateLimiter struct {
+	requests    map[string][]time.Time
+	mutex       sync.Mutex
+	limit       int
+	window      time.Duration
+	lastCleanup time.Time
+}
+
+var (
+	GlobalRateLimiter *RateLimiter
+	ConcurrencySem    chan struct{}
+	// trustedProxyHops controls how X-Forwarded-For (XFF) is parsed when the
+	// direct connection comes from a private IP (i.e., we're behind a reverse
+	// proxy). Two modes are supported, switched by this single value:
+	//
+	//   HEURISTIC MODE (trustedProxyHops == 0, the default):
+	//     Walk XFF from the end, return the first PUBLIC IP. Skips private
+	//     and loopback hops automatically. Works for ~90% of deployments
+	//     without the operator needing to know the exact number of proxy
+	//     hops. Trade-off in multi-hop: rate limiting is per-CDN-edge rather
+	//     than per-real-client, which is "good enough" for abuse protection
+	//     but not for fine-grained per-user quotas.
+	//
+	//   PRECISE MODE (trustedProxyHops > 0):
+	//     Count back N hops from the end of XFF and return that value. Gives
+	//     precise per-real-client rate limiting even in multi-hop setups
+	//     (e.g., Cloudflare + nginx). Operator MUST set this to the number
+	//     of trusted reverse proxies between this service and the client.
+	//
+	// Both modes walk from the END of the XFF chain. The first value is
+	// client-controllable; trusting it would let attackers bypass IP rate
+	// limiting by sending a forged X-Forwarded-For header.
+	trustedProxyHops = 0
+)
+
+func InitRateLimiter() {
+	switch v := os.Getenv("TRUSTED_PROXY_HOPS"); {
+	case v == "":
+		log.Printf("TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP)")
+	default:
+		n, err := strconv.Atoi(v)
+		switch {
+		case err != nil || n < 0 || n > 10:
+			log.Printf("警告: TRUSTED_PROXY_HOPS=%q 无效(需 0-10 的整数),回退到默认启发式模式", v)
+		case n == 0:
+			// "0" 或 "00" 等被 Atoi 解析为 0 的形式都归到启发式模式,
+			// 避免日志出现"精确模式, 信任 0 跳"这种自相矛盾的输出。
+			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(启发式模式,等同默认)", n)
+		default:
+			trustedProxyHops = n
+			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(精确模式,信任 %d 跳反代)", n, n)
+		}
+	}
+	GlobalRateLimiter = &RateLimiter{
+		requests: make(map[string][]time.Time),
+		limit:    common.RateLimitRequests,
+		window:   common.RateLimitWindow,
+	}
+	ConcurrencySem = make(chan struct{}, common.MaxConcurrentRequests)
+
+	// 同步到 setting 包,供 LogStartupSummary 展示
+	setting.TrustedProxyHops = trustedProxyHops
+}
+
+func (rl *RateLimiter) Allow(key string) bool {
+	rl.mutex.Lock()
+	defer rl.mutex.Unlock()
+
+	now := time.Now()
+	cutoff := now.Add(-rl.window)
+
+	if now.Sub(rl.lastCleanup) > common.CleanupInterval {
+		rl.cleanup()
+		rl.lastCleanup = now
+	}
+
+	timestamps := rl.requests[key]
+	valid := make([]time.Time, 0, len(timestamps))
+	for _, ts := range timestamps {
+		if ts.After(cutoff) {
+			valid = append(valid, ts)
+		}
+	}
+
+	if len(valid) >= rl.limit {
+		rl.requests[key] = valid
+		metrics.RateLimitRejected.Inc(nil)
+		return false
+	}
+
+	valid = append(valid, now)
+	rl.requests[key] = valid
+	return true
+}
+
+func (rl *RateLimiter) cleanup() {
+	cutoff := time.Now().Add(-rl.window)
+	for k, v := range rl.requests {
+		valid := make([]time.Time, 0, len(v))
+		for _, ts := range v {
+			if ts.After(cutoff) {
+				valid = append(valid, ts)
+			}
+		}
+		if len(valid) == 0 {
+			delete(rl.requests, k)
+		} else {
+			rl.requests[k] = valid
+		}
+	}
+
+	if len(rl.requests) > common.MaxRateLimiterEntries {
+		log.Printf("警告: 限流器条目数 %d 超过上限 %d，触发强制清理", len(rl.requests), common.MaxRateLimiterEntries)
+		// 【修复】原版用 `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, e.key)
+		}
+	}
+}
+
+var privateCIDRs []*net.IPNet
+
+func init() {
+	for _, cidr := range []string{
+		"10.0.0.0/8",
+		"172.16.0.0/12",
+		"192.168.0.0/16",
+		"127.0.0.0/8",
+		"169.254.0.0/16",
+		"::1/128",
+		"fc00::/7",
+		"fe80::/10",
+	} {
+		_, ipNet, _ := net.ParseCIDR(cidr)
+		privateCIDRs = append(privateCIDRs, ipNet)
+	}
+}
+
+func isPrivateIP(ipStr string) bool {
+	ip := net.ParseIP(ipStr)
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
+		return true
+	}
+	for _, cidr := range privateCIDRs {
+		if cidr.Contains(ip) {
+			return true
+		}
+	}
+	return false
+}
+
+func GetClientIP(r *http.Request) string {
+	directIP, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		directIP = r.RemoteAddr
+	}
+
+	if isPrivateIP(directIP) {
+		// Parse X-Forwarded-For when there's a reverse proxy in front (direct
+		// connection is from a private IP). Both modes walk from the END of
+		// the chain so that the client-controllable first value cannot be
+		// used to spoof a different client IP for rate limit bypass.
+		if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+			parts := strings.Split(xff, ",")
+			if trustedProxyHops > 0 {
+				// PRECISE MODE: count back N hops from end. Real client IP
+				// sits at index (len(parts) - N). Walk backwards to skip
+				// any malformed values; if chain is shorter than expected,
+				// fall through to the first valid IP in the chain.
+				target := len(parts) - trustedProxyHops
+				if target < 0 {
+					target = 0
+				}
+				for i := target; i >= 0; i-- {
+					ip := strings.TrimSpace(parts[i])
+					if net.ParseIP(ip) != nil {
+						return ip
+					}
+				}
+			} else {
+				// HEURISTIC MODE (default): walk from end, return first
+				// PUBLIC IP. Skips private/loopback hops that come from
+				// internal proxies between the public-facing proxy and us.
+				for i := len(parts) - 1; i >= 0; i-- {
+					ip := strings.TrimSpace(parts[i])
+					if parsed := net.ParseIP(ip); parsed != nil && !isPrivateIP(ip) {
+						return ip
+					}
+				}
+			}
+		}
+		if xri := strings.TrimSpace(r.Header.Get("X-Real-IP")); xri != "" {
+			if net.ParseIP(xri) != nil {
+				return xri
+			}
+		}
+	}
+
+	return directIP
+}

middleware/ratelimit_instrumented.go

@@ -0,0 +1,57 @@
+package middleware
+
+// 本文件提供带 metrics 埋点的限流 / 并发中间件版本。
+// 相比 router 实际使用的实现,本版本额外做了:
+//   - 加 metrics 埋点(限流拒绝 / 并发拒绝计数)
+//   - 仅对 /v1/ 下的业务请求生效,监控路径(/health /metrics /dashboard)不消耗配额
+
+import (
+	"log"
+	"net/http"
+	"strings"
+
+	"github.com/volcano-tts/tts-api/metrics"
+)
+
+// RateLimitWithMetrics 是限流中间件,带埋点 + 路径过滤。
+func RateLimitWithMetrics(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 仅对 /v1/ 下的业务请求限流,/health /metrics /dashboard 等监控路径不限流
+		if !strings.HasPrefix(r.URL.Path, "/v1/") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		clientIP := GetClientIP(r)
+		if !GlobalRateLimiter.Allow(clientIP) {
+			log.Printf("警告: 已超过IP速率限制，拒绝请求 - 客户端IP: %s", clientIP)
+			SendJSONError(w, http.StatusTooManyRequests, "Rate limit exceeded. Please try again later.", "rate_limit_error", "rate_limit_exceeded")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// ConcurrencyLimitWithMetrics 是并发控制中间件,带埋点 + 路径过滤。
+func ConcurrencyLimitWithMetrics(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 仅对 /v1/ 下的业务请求统计并发和加锁,监控路径不占用并发槽位
+		if !strings.HasPrefix(r.URL.Path, "/v1/") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		select {
+		case ConcurrencySem <- struct{}{}:
+			metrics.ConcurrencyActive.Inc(nil)
+			defer func() {
+				<-ConcurrencySem
+				metrics.ConcurrencyActive.Dec(nil)
+			}()
+			next.ServeHTTP(w, r)
+		default:
+			metrics.ConcurrencyRejected.Inc(nil)
+			log.Printf("警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: %s", GetClientIP(r))
+			SendJSONError(w, http.StatusServiceUnavailable, "Server is busy, maximum concurrent requests reached. Please try again later.", "concurrency_limit_error", "max_concurrent_requests")
+			return
+		}
+	})
+}

middleware/security.go

@@ -0,0 +1,21 @@
+package middleware
+
+import (
+	"net/http"
+	"strings"
+)
+
+func SecurityHeaders(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Content-Type-Options", "nosniff")
+		w.Header().Set("X-Frame-Options", "DENY")
+		w.Header().Set("X-XSS-Protection", "1; mode=block")
+		w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")
+
+		if strings.HasPrefix(r.URL.Path, "/v1/") || r.URL.Path == "/health" || r.URL.Path == "/dashboard" || r.URL.Path == "/metrics" {
+			w.Header().Set("Cache-Control", "no-store")
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}

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/admin.html

@@ -0,0 +1,106 @@
+<!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 class="stat-grid">
+                    <div class="stat-card">
+                        <div class="stat-top">
+                            <span class="stat-label">运行模式</span>
+                            <span class="pill" :class="overview.installed ? 'pill-success' : 'pill-accent'">
+                                <span class="pill-dot"></span>
+                                {{ overview.installed ? '已就绪' : '待配置' }}
+                            </span>
+                        </div>
+                        <div class="stat-value" :class="overview.installed ? 'text-success' : 'text-accent'">{{ overview.mode || '—' }}</div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-top"><span class="stat-label">音色</span></div>
+                        <div class="stat-value">{{ overview.voice_count ?? 0 }}<span class="stat-unit">条</span></div>
+                        <div class="stat-foot">
+                            <span class="text-success">{{ overview.voice_enabled_count ?? 0 }}</span> 启用 ·
+                            <span class="text-dim">{{ (overview.voice_count ?? 0) - (overview.voice_enabled_count ?? 0) }}</span> 停用
+                        </div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-top"><span class="stat-label">运行时间</span></div>
+                        <div class="stat-value">{{ formatUptime(overview.uptime_seconds) }}</div>
+                        <div class="stat-foot text-dim">{{ formatStart(overview.start_time) }}</div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-top"><span class="stat-label">数据库</span></div>
+                        <div class="stat-value mono" style="font-size: 15px; word-break: break-all;">{{ shortPath(overview.db_path) || '—' }}</div>
+                        <div class="stat-foot text-dim mono" style="font-size: 10px; word-break: break-all;">{{ overview.db_path || '' }}</div>
+                    </div>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">系统信息</div>
+                            <div class="card-sub">运行版本与资源</div>
+                        </div>
+                    </div>
+                    <dl class="kv">
+                        <div class="kv-row"><dt>Commit</dt><dd class="mono">{{ overview.commit || 'dev' }}</dd></div>
+                        <div class="kv-row"><dt>版本</dt><dd class="mono">{{ overview.version || '—' }}</dd></div>
+                        <div class="kv-row"><dt>运行模式</dt><dd>{{ overview.mode || '—' }}</dd></div>
+                        <div class="kv-row"><dt>数据库路径</dt><dd class="mono text-dim">{{ overview.db_path || '—' }}</dd></div>
+                        <div class="kv-row"><dt>锁文件</dt><dd class="mono text-dim">{{ overview.lock_path || '—' }}</dd></div>
+                        <div class="kv-row">
+                            <dt>内存</dt>
+                            <dd class="mono text-dim">
+                                goroutines {{ overview.memory?.goroutines ?? '—' }} · heap {{ formatBytes(overview.memory?.heap_alloc) }}
+                            </dd>
+                        </div>
+                    </dl>
+                </div>
+            </main>
+        </div>
+    </div>
+
+    <script src="/admin/admin-shell.js"></script>
+    <script>
+    const { createApp, ref, onMounted } = Vue;
+    const { http, getKey, formatUptime, shortPath, formatBytes, formatStart, mountShell } = window.admin;
+    createApp({
+        setup() {
+            const overview = ref({});
+
+            const loadOverview = async () => {
+                try { overview.value = (await http.get('/admin/overview')).data; }
+                catch (e) {
+                    window.admin.toast('err', '加载概览失败: ' + e.message);
+                }
+            };
+
+            onMounted(() => {
+                if (!getKey()) { location.href = '/admin/login'; return; }
+                mountShell({ activeNav: 'dashboard', overview: overview.value, voiceCount: overview.value.voice_count, onReload: loadOverview });
+                loadOverview();
+            });
+
+            return { overview, formatUptime, shortPath, formatBytes, formatStart, loadOverview };
+        },
+    }).mount('#app');
+    </script>
+</body>
+</html>

router/health.html

@@ -0,0 +1,668 @@
+<!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>
+    <style>
+        :root {
+            --bg: #0b0f1a;
+            --bg-card: #131826;
+            --bg-elev: #1a2138;
+            --border: #232b42;
+            --text: #e4e7ee;
+            --text-dim: #8a92a6;
+            --text-mute: #5a6275;
+            --accent: #00d4ff;
+            --accent-2: #7b2ff7;
+            --success: #22c55e;
+            --warning: #f59e0b;
+            --danger: #ef4444;
+        }
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+            background: var(--bg); color: var(--text);
+            min-height: 100vh; padding: 24px; font-size: 14px;
+            background-image:
+                radial-gradient(ellipse 80% 50% at 50% -20%, rgba(0,212,255,0.08), transparent),
+                radial-gradient(ellipse 60% 40% at 80% 100%, rgba(123,47,247,0.06), transparent);
+        }
+        #app { max-width: 1280px; margin: 0 auto; }
+
+        .header {
+            display: flex; align-items: center; justify-content: space-between;
+            margin-bottom: 24px; flex-wrap: wrap; gap: 16px;
+        }
+        .header-left { display: flex; align-items: center; gap: 16px; }
+        .logo {
+            width: 44px; height: 44px; border-radius: 12px;
+            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; box-shadow: 0 4px 20px rgba(0,212,255,0.3);
+        }
+        .header h1 { font-size: 20px; font-weight: 600; }
+        .header .sub { font-size: 12px; color: var(--text-dim); margin-top: 2px; }
+        .status-badge {
+            display: inline-flex; align-items: center; gap: 6px;
+            padding: 4px 10px; border-radius: 999px; font-size: 12px; font-weight: 500;
+        }
+        .status-badge.ok { background: rgba(34,197,94,0.15); color: var(--success); }
+        .status-badge.error { background: rgba(239,68,68,0.15); color: var(--danger); }
+        .status-dot { width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
+        .status-dot.live { animation: pulse 2s infinite; }
+        @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
+
+        .btn {
+            background: var(--bg-elev); border: 1px solid var(--border); color: var(--text);
+            padding: 8px 16px; border-radius: 8px; cursor: pointer; font-size: 13px;
+            transition: all 0.2s; display: inline-flex; align-items: center; gap: 6px;
+        }
+        .btn:hover { border-color: var(--accent); }
+        .btn-primary { background: var(--accent); color: #00121a; border-color: var(--accent); font-weight: 500; }
+        .btn-primary:hover { background: #33ddff; }
+
+        .stats {
+            display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+            gap: 12px; margin-bottom: 20px;
+        }
+        .stat-card {
+            background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px;
+            padding: 18px; transition: all 0.2s;
+        }
+        .stat-card:hover { border-color: rgba(0,212,255,0.4); transform: translateY(-1px); }
+        .stat-label { font-size: 12px; color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.5px; }
+        .stat-value { font-size: 28px; font-weight: 700; margin-top: 6px; color: var(--text); }
+        .stat-value.accent { color: var(--accent); }
+        .stat-value.success { color: var(--success); }
+        .stat-value.warning { color: var(--warning); }
+        .stat-value.danger { color: var(--danger); }
+        .stat-foot { font-size: 11px; color: var(--text-mute); margin-top: 4px; }
+
+        .section { margin-bottom: 20px; }
+        .section-title {
+            font-size: 13px; font-weight: 600; color: var(--text-dim);
+            text-transform: uppercase; letter-spacing: 1px; margin-bottom: 12px;
+            display: flex; align-items: center; gap: 8px;
+        }
+        .section-title::before {
+            content: ""; width: 3px; height: 14px; background: var(--accent); border-radius: 2px;
+        }
+
+        .grid-2 { display: grid; grid-template-columns: repeat(auto-fit, minmax(420px, 1fr)); gap: 16px; }
+        .card {
+            background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 20px;
+        }
+        .card-head {
+            display: flex; align-items: center; justify-content: space-between;
+            margin-bottom: 14px; padding-bottom: 12px; border-bottom: 1px solid var(--border);
+        }
+        .card-title { font-size: 14px; font-weight: 600; }
+        .card-desc { font-size: 11px; color: var(--text-mute); margin-top: 2px; }
+
+        .table { width: 100%; border-collapse: collapse; }
+        .table th, .table td {
+            text-align: left; padding: 8px 10px; font-size: 12px;
+            border-bottom: 1px solid var(--border);
+        }
+        .table th { color: var(--text-dim); font-weight: 500; font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; }
+        .table tr:last-child td { border-bottom: none; }
+        .table td.num { font-family: "SF Mono", Monaco, "Cascadia Code", monospace; text-align: right; color: var(--accent); font-weight: 500; }
+        .table td.num.success { color: var(--success); }
+        .table td.num.warning { color: var(--warning); }
+        .table td.num.danger { color: var(--danger); }
+        .table td.label-cell { color: var(--text-dim); font-family: "SF Mono", Monaco, monospace; font-size: 11px; }
+        .table td.name { color: var(--text); font-family: "SF Mono", Monaco, monospace; }
+
+        .tag {
+            display: inline-block; padding: 2px 6px; border-radius: 4px;
+            background: var(--bg-elev); color: var(--text-dim);
+            font-size: 10px; font-family: "SF Mono", Monaco, monospace;
+            margin-right: 4px; border: 1px solid var(--border);
+        }
+        .tag.status-ok { background: rgba(34,197,94,0.12); color: var(--success); border-color: rgba(34,197,94,0.3); }
+        .tag.status-error { background: rgba(239,68,68,0.12); color: var(--danger); border-color: rgba(239,68,68,0.3); }
+        .tag.format-mp3 { background: rgba(0,212,255,0.12); color: var(--accent); border-color: rgba(0,212,255,0.3); }
+        .empty { color: var(--text-mute); font-size: 12px; text-align: center; padding: 20px; }
+        .refresh-time { color: var(--text-mute); font-size: 11px; }
+
+        .error-box {
+            background: rgba(239,68,68,0.1); border: 1px solid rgba(239,68,68,0.3);
+            border-radius: 8px; padding: 12px 16px; color: var(--danger);
+            margin-bottom: 16px; font-size: 13px;
+        }
+
+        .row-flex { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+    </style>
+</head>
+<body>
+    <div id="app">
+        <div class="header">
+            <div class="header-left">
+                <div class="logo">TTS</div>
+                <div>
+                    <h1>火山 TTS 服务监控</h1>
+                    <div class="sub">{{ health.service || '' }} · {{ health.version || '' }}</div>
+                </div>
+            </div>
+            <div class="row-flex">
+                <span class="status-badge" :class="health.status === 'ok' ? 'ok' : 'error'">
+                    <span class="status-dot" :class="{ live: health.status === 'ok' }"></span>
+                    {{ health.status === 'ok' ? '运行中' : (health.status || '加载中') }}
+                </span>
+                <button class="btn btn-primary" @click="refresh" :disabled="loading">
+                    {{ loading ? "刷新中..." : "刷新" }}
+                </button>
+                <span class="refresh-time">{{ lastRefresh }}</span>
+            </div>
+        </div>
+
+        <div v-if="error" class="error-box">{{ error }}</div>
+
+        <div class="stats">
+            <div class="stat-card">
+                <div class="stat-label">运行时长</div>
+                <div class="stat-value">{{ formatUptime(health.uptime) }}</div>
+                <div class="stat-foot">启动于 {{ formatTime(health.start_time) }}</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-label">总请求数</div>
+                <div class="stat-value accent">{{ totalRequests }}</div>
+                <div class="stat-foot">自启动以来</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-label">成功率</div>
+                <div class="stat-value" :class="successRateClass">{{ successRate }}</div>
+                <div class="stat-foot">{{ okRequests }} 成功 / {{ errRequests }} 失败</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-label">当前并发</div>
+                <div class="stat-value">{{ concurrencyActive }}</div>
+                <div class="stat-foot">在飞请求数</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-label">Goroutines</div>
+                <div class="stat-value">{{ health.memory?.goroutines || 0 }}</div>
+                <div class="stat-foot">Go 运行时</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-label">堆内存</div>
+                <div class="stat-value">{{ formatBytes(health.memory?.heap_alloc) }}</div>
+                <div class="stat-foot">已分配 / 容量 {{ formatBytes(health.memory?.heap_inuse) }}</div>
+            </div>
+        </div>
+
+        <div class="section">
+            <div class="section-title">请求 & 流量</div>
+            <div class="grid-2">
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">请求数</div>
+                            <div class="card-desc">tts_request_total · 按 status / format / speaker 拆分</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="requestRows.length">
+                        <thead><tr><th>状态</th><th>格式</th><th>音色</th><th>次数</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in requestRows" :key="r.key">
+                                <td><span class="tag" :class="r.statusClass">{{ r.status }}</span></td>
+                                <td><span class="tag" v-if="r.format" :class="`format-${r.format}`">{{ r.format }}</span><span v-else class="tag">-</span></td>
+                                <td class="label-cell">{{ r.speaker || "-" }}</td>
+                                <td class="num" :class="r.statusClass">{{ r.value }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">端到端延迟</div>
+                            <div class="card-desc">tts_request_duration_seconds · 50/95/99 百分位</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="durationRows.length">
+                        <thead><tr><th>状态</th><th>格式</th><th>p50</th><th>p95</th><th>p99</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in durationRows" :key="r.key">
+                                <td><span class="tag" :class="r.statusClass">{{ r.status }}</span></td>
+                                <td><span class="tag" v-if="r.format" :class="`format-${r.format}`">{{ r.format }}</span><span v-else class="tag">-</span></td>
+                                <td class="num">{{ r.p50 }}</td>
+                                <td class="num">{{ r.p95 }}</td>
+                                <td class="num warning">{{ r.p99 }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+            </div>
+        </div>
+
+        <div class="section">
+            <div class="section-title">上游火山 API</div>
+            <div class="grid-2">
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">上游调用</div>
+                            <div class="card-desc">tts_upstream_total · 按 status / format 拆分</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="upstreamRows.length">
+                        <thead><tr><th>状态</th><th>格式</th><th>次数</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in upstreamRows" :key="r.key">
+                                <td><span class="tag" :class="r.statusClass">{{ r.status }}</span></td>
+                                <td><span class="tag" v-if="r.format" :class="`format-${r.format}`">{{ r.format }}</span><span v-else class="tag">-</span></td>
+                                <td class="num" :class="r.statusClass">{{ r.value }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">首字节耗时 (TTFB)</div>
+                            <div class="card-desc">tts_upstream_first_byte_seconds · 按格式拆分</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="ttfbRows.length">
+                        <thead><tr><th>格式</th><th>p50</th><th>p95</th><th>p99</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in ttfbRows" :key="r.format">
+                                <td><span class="tag" :class="`format-${r.format}`">{{ r.format }}</span></td>
+                                <td class="num">{{ r.p50 }}</td>
+                                <td class="num">{{ r.p95 }}</td>
+                                <td class="num warning">{{ r.p99 }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">流量统计</div>
+                            <div class="card-desc">chunks & 音频字节数</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="trafficRows.length">
+                        <thead><tr><th>格式</th><th>音频分片</th><th>音频字节</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in trafficRows" :key="r.format">
+                                <td><span class="tag" :class="`format-${r.format}`">{{ r.format }}</span></td>
+                                <td class="num">{{ r.chunks }}</td>
+                                <td class="num success">{{ r.audioBytes }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">上游错误</div>
+                            <div class="card-desc">tts_upstream_errors_total · 按错误码聚合</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="errorRows.length">
+                        <thead><tr><th>错误码</th><th>次数</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in errorRows" :key="r.code">
+                                <td class="label-cell">{{ r.code }}</td>
+                                <td class="num danger">{{ r.value }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无错误</div>
+                </div>
+            </div>
+        </div>
+
+        <div class="section">
+            <div class="section-title">限流 & 计费</div>
+            <div class="grid-2">
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">被拒请求</div>
+                            <div class="card-desc">限流 / 并发 / 鉴权失败</div>
+                        </div>
+                    </div>
+                    <table class="table">
+                        <tbody>
+                            <tr>
+                                <td class="label-cell">tts_ratelimit_rejected_total</td>
+                                <td class="num" :class="{ danger: rateLimitRejected > 0 }">{{ rateLimitRejected }}</td>
+                            </tr>
+                            <tr>
+                                <td class="label-cell">tts_concurrency_rejected_total</td>
+                                <td class="num" :class="{ danger: concurrencyRejected > 0 }">{{ concurrencyRejected }}</td>
+                            </tr>
+                            <tr>
+                                <td class="label-cell">tts_auth_failed_total</td>
+                                <td class="num" :class="{ danger: authFailed > 0 }">{{ authFailed }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                </div>
+
+                <div class="card">
+                    <div class="card-head">
+                        <div>
+                            <div class="card-title">计费字符</div>
+                            <div class="card-desc">tts_usage_text_words_total · 按模型拆分</div>
+                        </div>
+                    </div>
+                    <table class="table" v-if="usageRows.length">
+                        <thead><tr><th>模型</th><th>字符数</th></tr></thead>
+                        <tbody>
+                            <tr v-for="r in usageRows" :key="r.model">
+                                <td class="label-cell">{{ r.model }}</td>
+                                <td class="num success">{{ r.value }}</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                    <div v-else class="empty">暂无数据</div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+    const { createApp, ref, computed, onMounted } = Vue;
+
+    function parseProm(text) {
+        const out = {};
+        text.split("\n").forEach(line => {
+            line = line.trim();
+            if (!line || line.startsWith("#")) return;
+            const m = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)(\{([^}]*)\})?\s+(.+)$/);
+            if (!m) return;
+            const name = m[1];
+            const labels = {};
+            if (m[3]) {
+                m[3].split(",").forEach(p => {
+                    const kv = p.match(/^(\w+)="([^"]*)"$/);
+                    if (kv) labels[kv[1]] = kv[2];
+                });
+            }
+            const value = parseFloat(m[4]);
+            if (!out[name]) out[name] = [];
+            out[name].push({ labels, value });
+        });
+        return out;
+    }
+
+    function histogramStats(samples) {
+        // bucket le="+Inf" 的值是总数
+        let total = 0;
+        const buckets = [];
+        for (const s of samples) {
+            if (s.labels.le === "+Inf") total = s.value;
+            else buckets.push({ le: parseFloat(s.labels.le), count: s.value });
+        }
+        buckets.sort((a, b) => a.le - b.le);
+        function quantile(q) {
+            if (!total) return 0;
+            const target = total * q;
+            let prevCount = 0;
+            let prevLe = 0;
+            for (const b of buckets) {
+                if (b.count >= target) {
+                    if (b.count === prevCount) return prevLe;
+                    return prevLe + (b.le - prevLe) * (target - prevCount) / (b.count - prevCount);
+                }
+                prevCount = b.count;
+                prevLe = b.le;
+            }
+            return buckets.length ? buckets[buckets.length - 1].le : 0;
+        }
+        return { p50: quantile(0.5), p95: quantile(0.95), p99: quantile(0.99) };
+    }
+
+    function statusClass(status) {
+        if (status === "ok" || !status) return "status-ok";
+        if (status.includes("error") || status.includes("reject") || status === "internal_error") return "status-error";
+        return "status-error";
+    }
+
+    function fmtNum(n) {
+        if (n === undefined || n === null) return "-";
+        if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+        if (n >= 1e3) return (n / 1e3).toFixed(1) + "k";
+        return String(Math.round(n));
+    }
+    function fmtSec(s) {
+        if (!s || s === 0) return "0s";
+        if (s < 1) return (s * 1000).toFixed(0) + "ms";
+        return s.toFixed(2) + "s";
+    }
+    function fmtBytes(b) {
+        if (!b) return "0 B";
+        const k = 1024, sizes = ["B", "KB", "MB", "GB"];
+        const i = Math.floor(Math.log(b) / Math.log(k));
+        return (b / Math.pow(k, i)).toFixed(1) + " " + sizes[i];
+    }
+
+    createApp({
+        setup() {
+            const health = ref({});
+            const metrics = ref({});
+            const loading = ref(false);
+            const error = ref(null);
+            const lastRefresh = ref("-");
+
+            const totalRequests = computed(() => {
+                const arr = metrics.value["tts_request_total"] || [];
+                return fmtNum(arr.reduce((a, b) => a + b.value, 0));
+            });
+            const okRequests = computed(() => {
+                const arr = metrics.value["tts_request_total"] || [];
+                return fmtNum(arr.filter(s => s.labels.status === "ok").reduce((a, b) => a + b.value, 0));
+            });
+            const errRequests = computed(() => {
+                const arr = metrics.value["tts_request_total"] || [];
+                return fmtNum(arr.filter(s => s.labels.status !== "ok").reduce((a, b) => a + b.value, 0));
+            });
+            const successRate = computed(() => {
+                const total = (metrics.value["tts_request_total"] || []).reduce((a, b) => a + b.value, 0);
+                if (!total) return "-";
+                const ok = (metrics.value["tts_request_total"] || []).filter(s => s.labels.status === "ok").reduce((a, b) => a + b.value, 0);
+                return (ok / total * 100).toFixed(1) + "%";
+            });
+            const successRateClass = computed(() => {
+                const total = (metrics.value["tts_request_total"] || []).reduce((a, b) => a + b.value, 0);
+                if (!total) return "";
+                const ok = (metrics.value["tts_request_total"] || []).filter(s => s.labels.status === "ok").reduce((a, b) => a + b.value, 0);
+                const r = ok / total;
+                if (r >= 0.95) return "success";
+                if (r >= 0.8) return "warning";
+                return "danger";
+            });
+            const concurrencyActive = computed(() => {
+                const arr = metrics.value["tts_concurrency_active"] || [];
+                return fmtNum(arr.reduce((a, b) => a + b.value, 0));
+            });
+            const rateLimitRejected = computed(() => {
+                const arr = metrics.value["tts_ratelimit_rejected_total"] || [];
+                return fmtNum(arr.reduce((a, b) => a + b.value, 0));
+            });
+            const concurrencyRejected = computed(() => {
+                const arr = metrics.value["tts_concurrency_rejected_total"] || [];
+                return fmtNum(arr.reduce((a, b) => a + b.value, 0));
+            });
+            const authFailed = computed(() => {
+                const arr = metrics.value["tts_auth_failed_total"] || [];
+                return fmtNum(arr.reduce((a, b) => a + b.value, 0));
+            });
+
+            const requestRows = computed(() => {
+                const arr = metrics.value["tts_request_total"] || [];
+                return arr
+                    .map(s => ({
+                        key: JSON.stringify(s.labels),
+                        status: s.labels.status || "-",
+                        format: s.labels.format || "",
+                        speaker: s.labels.speaker || "",
+                        value: fmtNum(s.value),
+                        statusClass: statusClass(s.labels.status)
+                    }))
+                    .sort((a, b) => parseFloat(b.value) - parseFloat(a.value));
+            });
+
+            const durationRows = computed(() => {
+                const groups = {};
+                (metrics.value["tts_request_duration_seconds"] || []).forEach(s => {
+                    const key = `${s.labels.status || "-"}|${s.labels.format || ""}`;
+                    if (!groups[key]) groups[key] = { status: s.labels.status, format: s.labels.format, samples: [] };
+                    groups[key].samples.push(s);
+                });
+                return Object.values(groups).map(g => {
+                    const stats = histogramStats(g.samples);
+                    return {
+                        key: `${g.status}|${g.format}`,
+                        status: g.status || "-",
+                        format: g.format || "",
+                        p50: fmtSec(stats.p50),
+                        p95: fmtSec(stats.p95),
+                        p99: fmtSec(stats.p99),
+                        statusClass: statusClass(g.status)
+                    };
+                }).sort((a, b) => a.format.localeCompare(b.format));
+            });
+
+            const upstreamRows = computed(() => {
+                const arr = metrics.value["tts_upstream_total"] || [];
+                return arr.map(s => ({
+                    key: JSON.stringify(s.labels),
+                    status: s.labels.status || "-",
+                    format: s.labels.format || "",
+                    value: fmtNum(s.value),
+                    statusClass: statusClass(s.labels.status)
+                })).sort((a, b) => parseFloat(b.value) - parseFloat(a.value));
+            });
+
+            const ttfbRows = computed(() => {
+                const groups = {};
+                (metrics.value["tts_upstream_first_byte_seconds"] || []).forEach(s => {
+                    const key = s.labels.format || "-";
+                    if (!groups[key]) groups[key] = { format: s.labels.format, samples: [] };
+                    groups[key].samples.push(s);
+                });
+                return Object.values(groups).map(g => {
+                    const stats = histogramStats(g.samples);
+                    return { format: g.format || "-", p50: fmtSec(stats.p50), p95: fmtSec(stats.p95), p99: fmtSec(stats.p99) };
+                }).sort((a, b) => a.format.localeCompare(b.format));
+            });
+
+            const trafficRows = computed(() => {
+                const groups = {};
+                (metrics.value["tts_upstream_chunks_total"] || []).forEach(s => {
+                    const key = s.labels.format || "-";
+                    if (!groups[key]) groups[key] = { format: s.labels.format, chunks: 0, audioBytes: 0 };
+                    groups[key].chunks += s.value;
+                });
+                (metrics.value["tts_upstream_audio_bytes_total"] || []).forEach(s => {
+                    const key = s.labels.format || "-";
+                    if (!groups[key]) groups[key] = { format: s.labels.format, chunks: 0, audioBytes: 0 };
+                    groups[key].audioBytes += s.value;
+                });
+                return Object.values(groups).map(g => ({
+                    format: g.format || "-",
+                    chunks: fmtNum(g.chunks),
+                    audioBytes: fmtBytes(g.audioBytes)
+                })).sort((a, b) => a.format.localeCompare(b.format));
+            });
+
+            const errorRows = computed(() => {
+                const arr = metrics.value["tts_upstream_errors_total"] || [];
+                return arr.map(s => ({ code: s.labels.code || "-", value: fmtNum(s.value) }))
+                    .sort((a, b) => parseFloat(b.value) - parseFloat(a.value));
+            });
+
+            const usageRows = computed(() => {
+                const arr = metrics.value["tts_usage_text_words_total"] || [];
+                return arr.map(s => ({ model: s.labels.model || "-", value: fmtNum(s.value) }))
+                    .sort((a, b) => parseFloat(b.value) - parseFloat(a.value));
+            });
+
+            const fetchHealth = async () => {
+                try {
+                    const r = await axios.get("/health");
+                    health.value = r.data;
+                } catch (e) {
+                    error.value = "无法获取健康状态: " + (e.message || "未知错误");
+                }
+            };
+
+            const fetchMetrics = async () => {
+                try {
+                    const r = await axios.get("/metrics");
+                    metrics.value = parseProm(r.data);
+                } catch (e) {
+                    // 不覆盖 error,让 health 错误更显眼
+                    console.warn("metrics fetch failed:", e.message);
+                }
+            };
+
+            const refresh = async () => {
+                loading.value = true;
+                await Promise.all([fetchHealth(), fetchMetrics()]);
+                loading.value = false;
+                lastRefresh.value = new Date().toLocaleTimeString("zh-CN", { hour12: false });
+                error.value = null;
+            };
+
+            const formatTime = (iso) => {
+                if (!iso) return "-";
+                try {
+                    const d = new Date(iso);
+                    return d.toLocaleString("zh-CN", { hour12: false });
+                } catch { return iso; }
+            };
+
+            const formatUptime = (s) => {
+                if (!s) return "-";
+                const sec = parseInt(s);
+                if (isNaN(sec)) return s;
+                const d = Math.floor(sec / 86400);
+                const h = Math.floor((sec % 86400) / 3600);
+                const m = Math.floor((sec % 3600) / 60);
+                if (d > 0) return `${d}d ${h}h`;
+                if (h > 0) return `${h}h ${m}m`;
+                return `${m}m`;
+            };
+
+            const formatBytes = (b) => {
+                if (!b) return "0 B";
+                const k = 1024, sizes = ["B", "KB", "MB", "GB"];
+                const i = Math.floor(Math.log(b) / Math.log(k));
+                return (b / Math.pow(k, i)).toFixed(1) + " " + sizes[i];
+            };
+
+            onMounted(() => {
+                refresh();
+                setInterval(refresh, 10000);
+            });
+
+            return {
+                health, metrics, loading, error, lastRefresh,
+                totalRequests, okRequests, errRequests, successRate, successRateClass,
+                concurrencyActive, rateLimitRejected, concurrencyRejected, authFailed,
+                requestRows, durationRows, upstreamRows, ttfbRows, trafficRows, errorRows, usageRows,
+                refresh, formatBytes, formatUptime, formatTime
+            };
+        }
+    }).mount("#app");
+    </script>
+</body>
+</html>

router/router.go

@@ -0,0 +1,170 @@
+package router
+
+import (
+	_ "embed"
+	"net/http"
+	"strings"
+
+	"github.com/gorilla/mux"
+	"github.com/volcano-tts/tts-api/controller"
+	"github.com/volcano-tts/tts-api/installer"
+	"github.com/volcano-tts/tts-api/metrics"
+	"github.com/volcano-tts/tts-api/middleware"
+)
+
+//go:embed health.html
+var dashboardHTML []byte
+
+//go:embed setup.html
+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
+// 关键: InstallGuard 必须在 RateLimit 之前,避免安装模式被限流计数污染。
+//
+// /admin 和 /api/admin/* 都加 RequireAdmin;InstallGuard 不预先放行(让安装模式下
+// 自动 302 跳 /setup,体验一致)。
+func Setup() *mux.Router {
+	r := mux.NewRouter()
+
+	r.Use(middleware.SecurityHeaders)
+	r.Use(middleware.InstallGuard(installer.GetMode))
+	r.Use(middleware.RateLimitWithMetrics)
+	r.Use(middleware.ConcurrencyLimitWithMetrics)
+	r.Use(middleware.Logger)
+
+	// mux 路由未匹配时 NotFoundHandler 单独处理(不走 r.Use() 中间件链);
+	// 安装模式 + 浏览器访问任意未注册路径 → 302 跳 /setup。
+	r.NotFoundHandler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if installer.GetMode() == installer.ModeSetup && acceptsHTML(req.Header.Get("Accept")) {
+			http.Redirect(w, req, "/setup", http.StatusFound)
+			return
+		}
+		http.NotFound(w, req)
+	})
+
+	// 安装相关路由(InstallGuard 已在 setup 模式放行;完成后由 controller 二次校验 404)
+	// /setup 页面本身:装完后必须不可用,否则用户敲 /setup 还会看到安装表单,容易误以为要重装。
+	r.HandleFunc("/setup", func(w http.ResponseWriter, req *http.Request) {
+		if installer.GetMode() == installer.ModeNormal {
+			http.Redirect(w, req, "/admin", http.StatusFound)
+			return
+		}
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write(setupHTML)
+	}).Methods("GET")
+	r.HandleFunc("/api/setup/status", controller.SetupStatusHandler).Methods("GET")
+	r.HandleFunc("/api/setup/prefill", controller.SetupPrefillHandler).Methods("GET")
+	r.HandleFunc("/api/setup", controller.SetupSubmitHandler).Methods("POST")
+
+	// /admin 管理后台(M2);HTML 本身公开,鉴权由前端 JS 拦截
+	// (sessionStorage 没 key 就显示登录页;有 key 调 /api/admin/overview 触发 401 跳登录)
+	// API 端点(/api/admin/* /api/voices*)才需要 RequireAdmin。
+	//
+	// 拆分后 admin.html / admin-login.html / admin-voices.html / admin-settings.html
+	// 各自独立,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 (鉴权)
+	r.Handle("/api/admin/overview", middleware.RequireAdmin(http.HandlerFunc(controller.AdminOverviewHandler))).Methods("GET")
+	// /api/admin/metrics (鉴权);返 Prometheus 文本
+	r.Handle("/api/admin/metrics", middleware.RequireAdmin(http.HandlerFunc(controller.AdminMetricsHandler))).Methods("GET")
+
+	// /api/voices 音色 CRUD (鉴权)
+	r.Handle("/api/voices", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoicesListHandler))).Methods("GET")
+	r.Handle("/api/voices", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoiceCreateHandler))).Methods("POST")
+	r.Handle("/api/voices/{name}", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoiceDeleteHandler))).Methods("DELETE")
+	r.Handle("/api/voices/{name}/toggle", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoiceToggleHandler))).Methods("PATCH")
+
+	// /api/settings 全局设置 (鉴权) — M3
+	r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsGetHandler))).Methods("GET")
+	r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsUpdateHandler))).Methods("PUT")
+	r.Handle("/api/settings/api-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAPIKeyHandler))).Methods("PUT")
+	r.Handle("/api/settings/auth-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAuthKeyHandler))).Methods("PUT")
+	r.Handle("/api/settings/cors", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsCORSHandler))).Methods("PUT")
+
+	// 业务路由
+	r.HandleFunc("/v1/audio/speech", controller.OpenaiTTSHandler).Methods("POST", "OPTIONS")
+	r.HandleFunc("/health", controller.HealthHandler).Methods("GET")
+	r.HandleFunc("/dashboard", func(w http.ResponseWriter, req *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write(dashboardHTML)
+	}).Methods("GET")
+	r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
+		// 安装模式下,根路径跳 /setup
+		if installer.GetMode() == installer.ModeSetup {
+			http.Redirect(w, req, "/setup", http.StatusFound)
+			return
+		}
+		// 正常模式:跳 /admin(M2 之后优先于 /dashboard)
+		http.Redirect(w, req, "/admin", http.StatusFound)
+	}).Methods("GET")
+
+	// /metrics 不做鉴权(对齐 /health 策略),但仍然走 RateLimit / ConcurrencyLimit。
+	// Prometheus 抓取不带 Origin,因此经过 CORS 中间件时会直接 pass-through。
+	r.Handle("/metrics", metrics.Meter.Handler()).Methods("GET")
+
+	return r
+}
+
+// acceptsHTML 在 router 包内复刻,middleware 包的版本未导出。
+// 用途:NotFoundHandler 判断浏览器 Accept。
+func acceptsHTML(accept string) bool {
+	if accept == "" {
+		return false
+	}
+	for _, part := range strings.Split(accept, ",") {
+		mt := strings.TrimSpace(part)
+		if mt == "" {
+			continue
+		}
+		if idx := strings.Index(mt, ";"); idx >= 0 {
+			mt = strings.TrimSpace(mt[:idx])
+		}
+		mt = strings.ToLower(mt)
+		if mt == "text/html" || mt == "text/*" {
+			return true
+		}
+	}
+	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)
+	}
+}

router/setup.html

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

setting/config.go

@@ -0,0 +1,603 @@
+package setting
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/volcano-tts/tts-api/adapter/volcano"
+	"github.com/volcano-tts/tts-api/common"
+	"github.com/volcano-tts/tts-api/telemetry"
+)
+
+// 全部环境变量读取的单一入口:其它包不允许直接 os.Getenv,只读这里的全局 Config。
+//
+// 并发模型:
+//   - TTSOptions / TTSTimeout / TTSConfigErr / Auth.APIKeys / CORS 是运行期可被
+//     LoadRuntimeConfig(由 PUT /api/settings 触发)整体替换的"运行时配置快照"。
+//     struct 整体赋值不是原子的,若 TTS 请求正在读,可能拿到半写状态。
+//   - 解决: 用 ttsMu(RWMutex)统一保护这些字段;读路径用 Get* 拿快照(RLock),
+//     写路径用 Set* 整体替换(Lock)。读多写少,RWMutex 读不互斥,不会显著拖慢热路径。
+//   - Server.Port / TrustedProxyHops / SetupToken 仅启动期写、运行期读,无并发修改,
+//     保持原样不加锁。
+var (
+	ttsMu       sync.RWMutex
+	ttsOptions  volcano.Options
+	ttsTimeout  time.Duration = common.DefaultTimeout
+	ttsConfigErr error
+	authAPIKeys []string
+	// corsAllowAll / corsOrigins 拆成两个独立字段,各自在 RLock 下读取,
+	// 避免 CORSConfig 整体读时被 Lock 阻塞热路径。
+	corsAllowAll bool
+	corsOrigins  []string
+)
+
+// GetTTSOptions 读 TTSOptions 快照(值类型,使用方可以放心使用,不会被并发写破坏)。
+// 提供给业务侧(controller)的统一读取入口;LoadRuntimeConfig 写入时用 SetTTSOptions 整体替换。
+// 业务侧不要缓存这个值跨 goroutine 使用(应该每次调用时重新拿)。
+func GetTTSOptions() volcano.Options {
+	ttsMu.RLock()
+	defer ttsMu.RUnlock()
+	return ttsOptions
+}
+
+// SetTTSOptions 整体替换 TTSOptions。LoadRuntimeConfig 写路径专用。
+func SetTTSOptions(o volcano.Options) {
+	ttsMu.Lock()
+	defer ttsMu.Unlock()
+	ttsOptions = o
+}
+
+// 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 {
+	Port string
+}
+
+var Server ServerConfig
+
+// TrustedProxyHops 由 middleware.InitRateLimiter 在启动期写入,
+// 表示当前 XFF 解析模式:0=启发式,N>0=精确 N 跳。
+// setting.LogStartupSummary 读这个字段以展示运行期配置,
+// 不直接调用 middleware(避免循环 import)。
+//
+// 【并发】仅启动期被 InitRateLimiter 写一次,运行期只读,无并发问题,不加锁。
+var TrustedProxyHops int
+
+// SetupToken 是安装模式下的初始化凭证。
+//   - 若 TTS_ADMIN_KEY 环境变量非空,用其值(用户可复现,便于脚本化安装)
+//   - 若 TTS_ADMIN_KEY 为空,启动时随机生成 32 字节十六进制,
+//     打印到日志(/api/setup 提交时必须带这个 token)
+//
+// 安装完成后,/api/setup 端点永久关闭,SetupToken 失去意义但保留在内存。
+//
+// 【并发】仅 setup 阶段使用,运行期不会再写,无并发问题,不加锁。
+var SetupToken string
+
+// SetupTokenSource 标记 SetupToken 的来源,便于日志区分。
+//   "env"      = 来自 TTS_ADMIN_KEY
+//   "ephemeral"= 启动时随机生成(每次启动变)
+//   ""         = 未设置
+var SetupTokenSource string
+
+// InitAllConfigs 集中初始化所有配置,启动期调用一次。
+func InitAllConfigs() {
+	InitServerConfig()
+	InitAuthConfig()
+	InitCORSConfig()
+	InitSetupToken()
+	// InitTTSConfig 不再这里调 — 改为启动期从 store 加载(LoadRuntimeConfig)。
+}
+
+func InitServerConfig() {
+	Server.Port = os.Getenv("PORT")
+	if Server.Port == "" {
+		Server.Port = common.DefaultPort
+	}
+}
+
+func InitAuthConfig() {
+	raw := os.Getenv("OPENAI_TTS_API_KEY")
+	if raw == "" {
+		SetAuthAPIKeys(nil)
+		return
+	}
+	parts := strings.Split(raw, ",")
+	keys := make([]string, 0, len(parts))
+	for _, p := range parts {
+		k := strings.TrimSpace(p)
+		if k != "" {
+			keys = append(keys, k)
+		}
+	}
+	SetAuthAPIKeys(keys)
+}
+
+func InitCORSConfig() {
+	raw := os.Getenv("ALLOWED_ORIGINS")
+	allowAll := false
+	var origins []string
+	if raw != "" {
+		for _, p := range strings.Split(raw, ",") {
+			o := strings.TrimSpace(p)
+			if o == "" {
+				continue
+			}
+			if o == "*" {
+				allowAll = true
+				continue
+			}
+			origins = append(origins, normalizeOrigin(o))
+		}
+	}
+	SetCORS(allowAll, origins)
+}
+
+func normalizeOrigin(origin string) string {
+	origin = strings.TrimSpace(origin)
+	origin = strings.TrimRight(origin, "/")
+	return strings.ToLower(origin)
+}
+
+// SplitOriginsForCORS 解析逗号/换行/空格分隔的 origins 列表,
+// 全部小写、trim 末尾 / 后面统一比较。导出供 controller 复用
+// (PUT /api/settings/cors 写完立即刷新 CORS 用)。
+func SplitOriginsForCORS(s string) []string {
+	return splitAndLowerOrigins(s)
+}
+
+// splitAndLowerOrigins 解析逗号/换行/空格分隔的 origins 列表,
+// 全部小写、trim 末尾 / 后面统一比较(只在本包内用,外部用 SplitOriginsForCORS)。
+// 实现细节:用 strings.FieldsFunc 切分,首尾 trim,末尾去 /。
+func splitAndLowerOrigins(s string) []string {
+	parts := strings.FieldsFunc(s, func(r rune) bool {
+		return r == ',' || r == '\n' || r == ' ' || r == '\t'
+	})
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.ToLower(strings.TrimRight(strings.TrimSpace(p), "/"))
+		if p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// LoadRuntimeConfig 从 store 加载 TTS 全局配置到 TTSOptions / TTSTimeout / Auth.APIKeys 内存。
+// 启动期(master 模式)调一次,或 PUT /api/settings 后调一次(改完立即生效)。
+////
+// 与原 InitTTSConfig 的区别:
+//   - 不再读 BYTEDANCE_TTS_* env;全部从 store.Settings 读
+//   - 必填项(api_key / default_resource_id / default_speaker)缺失时返 error
+//   - 失败时 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
+//   BYTEDANCE_TTS_SPEAKER        → default_speaker
+//   BYTEDANCE_TTS_MODEL          → model
+//   BYTEDANCE_TTS_FORMAT         → default_format (默认 mp3)
+//   BYTEDANCE_TTS_SAMPLE_RATE    → sample_rate (默认 24000)
+//   BYTEDANCE_TTS_BIT_RATE       → bit_rate (默认 0)
+//   BYTEDANCE_TTS_MODEL_TYPE     → model_type (默认 0)
+//   BYTEDANCE_TTS_EXPLICIT_LANGUAGE → explicit_language
+//   BYTEDANCE_TTS_ENABLE_SUBTITLE   → enable_subtitle (默认 false)
+//   BYTEDANCE_TTS_TIMEOUT        → TTSTimeout (默认 30s)
+//
+// 鉴权 key(auth_key)优先级:DB > env OPENAI_TTS_API_KEY
+//   - 首次启动(无 DB 数据):用 env,保证向后兼容
+//   - 已 install:用 DB,env 不再读
+//   - DB 没 auth_key 但 env 有(env fallback):仍用 env
+func LoadRuntimeConfig(s Store) error {
+	all, err := s.SettingsGetAll()
+	if err != nil {
+		wrapped := fmt.Errorf("read settings failed: %w", err)
+		SetTTSConfigErr(wrapped)
+		return wrapped
+	}
+
+	apiKey := all["api_key"]
+	resourceId := all["default_resource_id"]
+	speaker := all["default_speaker"]
+	missing := []string{}
+	if apiKey == "" {
+		missing = append(missing, "api_key")
+	}
+	if resourceId == "" {
+		missing = append(missing, "default_resource_id")
+	}
+	if speaker == "" {
+		missing = append(missing, "default_speaker")
+	}
+	if len(missing) > 0 {
+		wrapped := fmt.Errorf("missing required settings: %v", missing)
+		SetTTSConfigErr(wrapped)
+		return wrapped
+	}
+
+	// 【BUG 修复 · 第二轮】default_speaker 是 voice **名字**(如 "chun"),
+	// 不是火山 speaker ID (如 "S_G8tEKnaJ1")。原代码直接把 voice 名当
+	// speaker ID 用,导致调 /v1/audio/speech 不传 voice 时火山 55000000。
+	//
+	// 字段优先级:
+	//   - speaker     ←  从 default_speaker 这个 voice 查表拿真 ID (必查)
+	//   - resource_id ←  settings 里的(用户偏好,不被 voice 行覆盖)
+	//   - model       ←  voice 行的优先,settings 里的次之
+	//
+	// 之前 f5563e6 把 resourceId 也覆盖了,导致用户在 setup 设的
+	// default_resource_id 永远没机会生效。这次只覆盖 speaker,不动 resourceId。
+	var voiceModel string
+	if vSpeaker, _, vModel, found, vErr := s.GetVoiceForTTS(speaker); vErr == nil && found {
+		speaker = vSpeaker
+		if vModel != "" {
+			voiceModel = vModel
+		}
+		// 找不到 voice 时不报错 — 保持原值(向后兼容)
+	}
+
+	model := all["model"]
+	if voiceModel != "" {
+		model = voiceModel // voice 行有 model 时优先用 voice 的
+	}
+	format := all["default_format"]
+	if format == "" {
+		format = "mp3"
+	}
+	sampleRate, _ := s.SettingsGetInt("sample_rate", 24000)
+	bitRate, _ := s.SettingsGetInt("bit_rate", 0)
+	modelType, _ := s.SettingsGetInt("model_type", 0)
+	explicitLanguage := all["explicit_language"]
+	enableSubtitle, _ := s.SettingsGetBool("enable_subtitle", false)
+
+	var adds *volcano.Additions
+	if modelType != 0 || explicitLanguage != "" {
+		adds = &volcano.Additions{}
+		if modelType != 0 {
+			v := modelType
+			adds.ModelType = &v
+		}
+		if explicitLanguage != "" {
+			adds.ExplicitLanguage = explicitLanguage
+		}
+	}
+
+	timeout := common.DefaultTimeout
+	if v, err := s.SettingsGetDuration("timeout", common.DefaultTimeout); err == nil {
+		timeout = v
+	} else {
+		timeout = common.DefaultTimeout
+	}
+	SetTTSTimeout(timeout)
+
+	SetTTSOptions(volcano.Options{
+		APIKey:         apiKey,
+		ResourceID:     resourceId,
+		UID:            "uid",
+		Speaker:        speaker,
+		Model:          model,
+		Format:         format,
+		SampleRate:     sampleRate,
+		BitRate:        bitRate,
+		SpeechRate:     0,
+		LoudnessRate:   0,
+		EnableSubtitle: enableSubtitle,
+		Additions:      adds,
+	})
+
+	// 鉴权 key:DB > env(向后兼容)
+	authKey := all["auth_key"]
+	if authKey == "" {
+		authKey = os.Getenv("OPENAI_TTS_API_KEY")
+	}
+	if authKey != "" {
+		SetAuthAPIKeys([]string{authKey})
+	} else {
+		SetAuthAPIKeys(nil)
+	}
+
+	// CORS 配置:DB > env
+	// cors_allow_all (bool): 允许所有来源(*)
+	// cors_origins (string): 逗号分隔白名单
+	// 同源豁免由 middleware/cors.go 的 isSameOrigin 负责,DB 这里只管跨域名单
+	corsAllowAll, _ := s.SettingsGetBool("cors_allow_all", false)
+	if !corsAllowAll {
+		// env 兜底
+		if v := strings.ToLower(strings.TrimSpace(os.Getenv("CORS_ALLOW_ALL"))); v == "1" || v == "true" || v == "yes" {
+			corsAllowAll = true
+		}
+	}
+	originsStr := strings.TrimSpace(all["cors_origins"])
+	if originsStr == "" {
+		originsStr = os.Getenv("ALLOWED_ORIGINS")
+	}
+	if corsAllowAll {
+		SetCORS(true, nil)
+	} else if originsStr != "" {
+		SetCORS(false, SplitOriginsForCORS(originsStr))
+	} else {
+		SetCORS(false, nil)
+	}
+
+	SetTTSConfigErr(nil)
+	return nil
+}
+
+// Store 是 LoadRuntimeConfig 需要的最小接口(避免 setting 包 import store 产生 cycle)。
+//
+// 重要:VoiceGetByName 用 4 个返回值(speaker/resourceID/model/found/err)
+// 而非 (VoiceRef, error),这样 store 包不需要 import setting 包
+// 就能实现这个接口(避免循环 import)。
+type Store interface {
+	SettingsGetAll() (map[string]string, error)
+	SettingsGetInt(key string, def int) (int, error)
+	SettingsGetBool(key string, def bool) (bool, error)
+	SettingsGetDuration(key string, def time.Duration) (time.Duration, error)
+	// GetVoiceForTTS 给定 voice 名字,返 (speaker_id, resource_id, model, found, err)。
+	//   - found=false 表示 voice 不存在(此时 err=nil,返回值是空串)
+	//   - err!=nil 是真错误(db 失败等)
+	//   - 找到时返 voice 行的真实字段值
+	GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error)
+}
+
+func getEnvDefault(name, def string) string {
+	if v := os.Getenv(name); v != "" {
+		return v
+	}
+	return def
+}
+
+func getEnvInt(name string, def int) int {
+	v := os.Getenv(name)
+	if v == "" {
+		return def
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		log.Printf("环境变量 %s=%q 不是合法整数,使用默认 %d", name, v, def)
+		return def
+	}
+	return n
+}
+
+func getEnvBool(name string, def bool) bool {
+	v := os.Getenv(name)
+	if v == "" {
+		return def
+	}
+	b, err := strconv.ParseBool(v)
+	if err != nil {
+		log.Printf("环境变量 %s=%q 不是合法 bool,使用默认 %v", name, v, def)
+		return def
+	}
+	return b
+}
+
+// InitSetupToken 加载或生成安装模式下的初始化凭证。
+//   - TTS_ADMIN_KEY 存在:用其值,SetupTokenSource="env"
+//   - TTS_ADMIN_KEY 空:随机生成 16 字节 = 32 字符 hex,SetupTokenSource="ephemeral",打印到日志
+func InitSetupToken() {
+	v := os.Getenv("TTS_ADMIN_KEY")
+	if v != "" {
+		SetupToken = v
+		SetupTokenSource = "env"
+		return
+	}
+	// 临时 token:16 字节随机 = 32 字符 hex,够用且短
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		// 极端情况:随机源失败,降级为时间戳(不应发生)
+		log.Printf("[setup] 生成一次性 token 失败,使用时间戳: %v", err)
+		SetupToken = fmt.Sprintf("dev-%d", time.Now().UnixNano())
+		SetupTokenSource = "ephemeral"
+		return
+	}
+	SetupToken = hex.EncodeToString(b)
+	SetupTokenSource = "ephemeral"
+	log.Printf("[setup] 一次性安装 token(仅打印一次,公网部署请设置 TTS_ADMIN_KEY): %s", SetupToken)
+}
+
+// CheckEnvironmentVariables 返回 /health 用的环境变量状态快照。
+func CheckEnvironmentVariables() map[string]interface{} {
+	// 一次性拿所有需要的快照,缩短锁占用窗口;后续只读本地变量。
+	opts := GetTTSOptions()
+	authKeys := GetAuthAPIKeys()
+	allowAll := GetCORSAllowAll()
+	origins := GetCORSOrigins()
+
+	required := map[string]bool{
+		"BYTEDANCE_TTS_API_KEY":     opts.APIKey != "",
+		"BYTEDANCE_TTS_RESOURCE_ID": opts.ResourceID != "",
+		"BYTEDANCE_TTS_SPEAKER":     opts.Speaker != "",
+	}
+	missing := []string{}
+	for k, ok := range required {
+		if !ok {
+			missing = append(missing, k)
+		}
+	}
+	optional := map[string]bool{
+		"BYTEDANCE_TTS_MODEL":             opts.Model != "",
+		"BYTEDANCE_TTS_FORMAT":            opts.Format != "mp3",
+		"BYTEDANCE_TTS_SAMPLE_RATE":       opts.SampleRate != 24000,
+		"BYTEDANCE_TTS_EXPLICIT_LANGUAGE": opts.Additions != nil && opts.Additions.ExplicitLanguage != "",
+		"OPENAI_TTS_API_KEY":              len(authKeys) > 0,
+		"ALLOWED_ORIGINS":                 allowAll || len(origins) > 0,
+		"PORT":                            Server.Port != common.DefaultPort,
+	}
+	return map[string]interface{}{
+		"all_required_vars_set": len(missing) == 0,
+		"missing_required_vars": missing,
+		"required_vars_set":     required,
+		"optional_vars_set":     optional,
+	}
+}
+
+// LogStartupSummary 启动期一次性打印所有 Config 状态。
+func LogStartupSummary() {
+	log.Printf("=== 环境配置汇总 ===")
+	log.Printf("服务端口: %s", Server.Port)
+
+	authKeys := GetAuthAPIKeys()
+	if len(authKeys) == 0 {
+		log.Printf("OPENAI_TTS_API_KEY: 未设置(所有请求无需鉴权)")
+	} else {
+		log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(authKeys))
+	}
+
+	allowAll := GetCORSAllowAll()
+	origins := GetCORSOrigins()
+	if allowAll {
+		log.Printf("ALLOWED_ORIGINS: *(允许所有跨域;不可与鉴权共用)")
+	} else if len(origins) == 0 {
+		log.Printf("ALLOWED_ORIGINS: 未设置(跨域请求将被拒绝)")
+	} else {
+		log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(origins))
+	}
+
+	if h := TrustedProxyHops; h == 0 {
+		log.Printf("TRUSTED_PROXY_HOPS: 启发式模式(默认,XFF 链尾第一个公网 IP)")
+	} else {
+		log.Printf("TRUSTED_PROXY_HOPS: 精确模式,信任 %d 跳反代", h)
+	}
+
+	// 一次性拿 TTSOptions 快照;后续只读本地变量,避免在多个 log.Printf 调用之间
+	// 被 LoadRuntimeConfig 整体替换导致打印出不连贯的数据。
+	opts := GetTTSOptions()
+	log.Printf("火山 TTS 必填项状态:")
+	type ttsCheck struct {
+		name  string
+		value string
+		ok    bool
+	}
+	checks := []ttsCheck{
+		{"BYTEDANCE_TTS_API_KEY", maskAPIKey(opts.APIKey), opts.APIKey != ""},
+		{"BYTEDANCE_TTS_RESOURCE_ID", telemetry.MaskResourceID(opts.ResourceID), opts.ResourceID != ""},
+		// speaker 是火山复刻音色 ID(用户付费资产),日志里打码,避免明文落盘
+		{"BYTEDANCE_TTS_SPEAKER", telemetry.MaskSpeaker(opts.Speaker), opts.Speaker != ""},
+	}
+	missingCount := 0
+	for _, c := range checks {
+		mark := "✓"
+		if !c.ok {
+			mark = "✗"
+			missingCount++
+		}
+		val := c.value
+		if val == "" {
+			val = "(未设置)"
+		}
+		log.Printf("  %s %s: %s", mark, c.name, val)
+	}
+
+	if err := GetTTSConfigErr(); err != nil {
+		log.Printf("火山 TTS 整体: 初始化失败(%d 个必填项缺失),/v1/audio/speech 路由将全部返回 500", missingCount)
+	} else {
+		log.Printf("火山 TTS 整体: 初始化成功")
+	}
+}
+
+func maskAPIKey(key string) string {
+	if key == "" {
+		return ""
+	}
+	if len(key) <= 8 {
+		return "****"
+	}
+	return key[:4] + "****" + key[len(key)-4:]
+}

store/db.go

@@ -0,0 +1,153 @@
+// Package store 负责 SQLite 访问层:打开/建表/迁移、settings/voices CRUD、
+// 完整性校验。所有运行时可变配置(全局参数 + 音色库)统一落 SQLite,
+// 环境变量仅作引导参数(TTS_DB_PATH 等)。
+//
+// 设计约束:
+//   - 单二进制分发,纯 Go SQLite(modernc.org/sqlite),CGO_ENABLED=0
+//   - 单用户自用,SetMaxOpenConns(1) 避免并发写竞争
+//   - 所有 SQL 参数化,严禁字符串拼接
+//   - schema_version 表保留未来升级钩子
+package store
+
+import (
+	"database/sql"
+	"fmt"
+
+	_ "modernc.org/sqlite" // 注册 sqlite driver
+)
+
+// schemaVersion 是当前 schema 版本号;每次结构性变更 +1。
+// migrate.go 负责在 Open 时按版本号增量应用。
+const schemaVersion = 1
+
+// Store 是 SQLite 访问层的统一入口;所有 settings/voices 操作都通过它。
+type Store struct {
+	db *sql.DB
+}
+
+// Open 打开或创建 SQLite 数据库,自动应用建表与迁移。
+// path 推荐为绝对路径;空字符串会落到临时目录,不应用于生产。
+func Open(path string) (*Store, error) {
+	// modernc.org/sqlite 注册名:"sqlite" + "sqlite3" 两种
+	// _dsn 参数控制 journal_mode 等;这里先打开,再用 PRAGMA 调整
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		return nil, fmt.Errorf("store: open %q failed: %w", path, err)
+	}
+
+	// 单用户自用场景,避免并发写竞争
+	db.SetMaxOpenConns(1)
+
+	// PRAGMA 需要连接,触发一次 Ping 拿连接
+	if _, err := db.Exec(`PRAGMA journal_mode = WAL`); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("store: enable WAL failed: %w", err)
+	}
+	if _, err := db.Exec(`PRAGMA foreign_keys = ON`); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("store: enable foreign_keys failed: %w", err)
+	}
+	if _, err := db.Exec(`PRAGMA synchronous = NORMAL`); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("store: enable synchronous=NORMAL failed: %w", err)
+	}
+
+	s := &Store{db: db}
+	if err := s.migrate(); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("store: migrate failed: %w", err)
+	}
+	return s, nil
+}
+
+// Close 关闭底层连接;调用方应保证只 Close 一次。
+func (s *Store) Close() error {
+	if s == nil || s.db == nil {
+		return nil
+	}
+	return s.db.Close()
+}
+
+// DB 返回底层 *sql.DB,仅供 store 包内或集成测试使用;
+// 业务代码不应直接拿连接,所有操作走 Store 暴露的方法。
+func (s *Store) DB() *sql.DB { return s.db }
+
+// IntegrityCheck 执行 PRAGMA integrity_check;返回 "ok" 即视为库健康。
+// installer 包据此判定是否触发损坏回退。
+func (s *Store) IntegrityCheck() (string, error) {
+	row := s.db.QueryRow(`PRAGMA integrity_check`)
+	var result string
+	if err := row.Scan(&result); err != nil {
+		return "", fmt.Errorf("store: integrity_check scan failed: %w", err)
+	}
+	return result, nil
+}
+
+// Path 返回当前 db 的 SQLite 报告路径(用于日志)。
+// 通过 PRAGMA database_list 拿权威值,避免和入参 path 不一致时的混淆。
+func (s *Store) Path() (string, error) {
+	rows, err := s.db.Query(`PRAGMA database_list`)
+	if err != nil {
+		return "", fmt.Errorf("store: database_list query failed: %w", err)
+	}
+	defer rows.Close()
+	if !rows.Next() {
+		return "", fmt.Errorf("store: database_list returned no rows")
+	}
+	var seq int
+	var name, file string
+	if err := rows.Scan(&seq, &name, &file); err != nil {
+		return "", fmt.Errorf("store: database_list scan failed: %w", err)
+	}
+	return file, nil
+}
+
+// migrate 应用 schema 迁移。当前 schema_version=1,只做基础建表。
+// 未来升级:写 applyMigration(n) 函数,n 为目标版本号。
+func (s *Store) migrate() error {
+	// schema_version 表记录当前版本
+	if _, err := s.db.Exec(`
+		CREATE TABLE IF NOT EXISTS schema_version (
+			version    INTEGER PRIMARY KEY,
+			applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+		)`); err != nil {
+		return fmt.Errorf("create schema_version: %w", err)
+	}
+
+	// settings 表(全局配置)
+	if _, err := s.db.Exec(`
+		CREATE TABLE IF NOT EXISTS settings (
+			key        TEXT PRIMARY KEY,
+			value      TEXT NOT NULL,
+			updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+		)`); err != nil {
+		return fmt.Errorf("create settings: %w", err)
+	}
+
+	// voices 表(音色库)
+	if _, err := s.db.Exec(`
+		CREATE TABLE IF NOT EXISTS voices (
+			id          INTEGER PRIMARY KEY AUTOINCREMENT,
+			name        TEXT NOT NULL UNIQUE,
+			speaker     TEXT NOT NULL,
+			resource_id TEXT NOT NULL,
+			model       TEXT DEFAULT '',
+			language    TEXT DEFAULT '',
+			description TEXT DEFAULT '',
+			enabled     INTEGER NOT NULL DEFAULT 1,
+			created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+			updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+		)`); err != nil {
+		return fmt.Errorf("create voices: %w", err)
+	}
+	if _, err := s.db.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_voices_name ON voices(name)`); err != nil {
+		return fmt.Errorf("create idx_voices_name: %w", err)
+	}
+
+	// 当前版本
+	if _, err := s.db.Exec(`
+		INSERT OR IGNORE INTO schema_version (version) VALUES (?)`, schemaVersion); err != nil {
+		return fmt.Errorf("insert schema_version: %w", err)
+	}
+	return nil
+}

store/migrate.go

@@ -0,0 +1,27 @@
+package store
+
+// schema 版本号演进与迁移函数注册表。
+//
+// 用法:每次结构性变更时 +1 schemaVersion 常量,并在 migrations 切片中追加 applyV<n>。
+// migrate.go 会在 Open 时按版本号顺序应用。
+//
+// 注意:本文件留作未来扩展,本期 M0 阶段 schemaVersion=1,migrate() 在 db.go
+// 内做基础建表,未触发 migrations 调度。切到 v2 时再启用。
+
+// Migration 是从 version N-1 升级到 N 的迁移函数。
+type Migration struct {
+	From int
+	To   int
+	Fn   func(tx interface{ Exec(query string, args ...any) (any, error) }) error
+}
+
+// migrations 是按 From 升序排列的迁移列表;首条 From 必须等于 1。
+// 留作占位,本期为空。
+var migrations = []Migration{}
+
+// schemaVersionRequested 是期望的 schema 版本号;db.go 里直接写常量。
+// 这里留个常量引用便于未来从 db.go 解耦。
+const schemaVersionRequested = 1
+
+// CurrentVersion 返回当前代码期望的 schema 版本。
+func CurrentVersion() int { return schemaVersionRequested }

store/settings.go

@@ -0,0 +1,175 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"strconv"
+	"time"
+)
+
+// SettingsKey 是 settings 表的合法键白名单;防止上游拼写错误静默落库。
+// 留空 hash 表示允许任意键;严格模式时把允许的键填进来。
+//
+// 本期(M0)使用宽松模式:任何非空字符串键都可以写入。
+// 收紧时把对应键填入 allowedSettingsKeys 即可。
+var allowedSettingsKeys = map[string]struct{}{}
+
+// SettingsAccess 返回单条配置;键不存在返回 ("", false, nil)。
+// 第二返回值表示键是否存在,便于上层区分"未设置"和"值为空串"。
+func (s *Store) SettingsGet(key string) (string, bool, error) {
+	if key == "" {
+		return "", false, fmt.Errorf("store: settings key is empty")
+	}
+	row := s.db.QueryRow(`SELECT value FROM settings WHERE key = ?`, key)
+	var v string
+	err := row.Scan(&v)
+	if errors.Is(err, sql.ErrNoRows) {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, fmt.Errorf("store: settings get %q: %w", key, err)
+	}
+	return v, true, nil
+}
+
+// SettingsSet 写入单条配置;空值会删除该键(SQLite 没 NULL 写法更直观)。
+func (s *Store) SettingsSet(key, value string) error {
+	if key == "" {
+		return fmt.Errorf("store: settings key is empty")
+	}
+	if !isAllowedSettingsKey(key) {
+		return fmt.Errorf("store: settings key %q not in whitelist", key)
+	}
+	_, err := s.db.Exec(`
+		INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
+		ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+		key, value)
+	if err != nil {
+		return fmt.Errorf("store: settings set %q: %w", key, err)
+	}
+	return nil
+}
+
+// SettingsDelete 显式删除单条键;键不存在不报错。
+func (s *Store) SettingsDelete(key string) error {
+	if key == "" {
+		return fmt.Errorf("store: settings key is empty")
+	}
+	_, err := s.db.Exec(`DELETE FROM settings WHERE key = ?`, key)
+	if err != nil {
+		return fmt.Errorf("store: settings delete %q: %w", key, err)
+	}
+	return nil
+}
+
+// SettingsGetAll 返回所有配置;按 key 升序。
+func (s *Store) SettingsGetAll() (map[string]string, error) {
+	rows, err := s.db.Query(`SELECT key, value FROM settings ORDER BY key`)
+	if err != nil {
+		return nil, fmt.Errorf("store: settings getall: %w", err)
+	}
+	defer rows.Close()
+	out := make(map[string]string)
+	for rows.Next() {
+		var k, v string
+		if err := rows.Scan(&k, &v); err != nil {
+			return nil, fmt.Errorf("store: settings getall scan: %w", err)
+		}
+		out[k] = v
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: settings getall rows: %w", err)
+	}
+	return out, nil
+}
+
+// SettingsSetBatch 一次性写入多对;保留单事务原子性,失败整体回滚。
+// 适合 /api/setup 一次性写入全局配置。
+func (s *Store) SettingsSetBatch(kv map[string]string) error {
+	if len(kv) == 0 {
+		return nil
+	}
+	tx, err := s.db.Begin()
+	if err != nil {
+		return fmt.Errorf("store: settings setbatch begin: %w", err)
+	}
+	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 {
+		_ = tx.Rollback()
+		return fmt.Errorf("store: settings setbatch prepare: %w", err)
+	}
+	for k, v := range kv {
+		if k == "" {
+			_ = tx.Rollback()
+			return fmt.Errorf("store: settings setbatch: empty key")
+		}
+		if !isAllowedSettingsKey(k) {
+			_ = tx.Rollback()
+			return fmt.Errorf("store: settings setbatch: key %q not in whitelist", k)
+		}
+		if _, err := stmt.Exec(k, v); err != nil {
+			_ = stmt.Close()
+			_ = tx.Rollback()
+			return fmt.Errorf("store: settings setbatch exec %q: %w", k, err)
+		}
+	}
+	if err := stmt.Close(); err != nil {
+		_ = tx.Rollback()
+		return fmt.Errorf("store: settings setbatch close stmt: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("store: settings setbatch commit: %w", err)
+	}
+	return nil
+}
+
+// SettingsGetInt 返回整型配置,带默认值;键不存在或解析失败时回退到 def。
+func (s *Store) SettingsGetInt(key string, def int) (int, error) {
+	v, ok, err := s.SettingsGet(key)
+	if err != nil || !ok {
+		return def, err
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return def, nil // 解析失败静默回退,不污染调用方
+	}
+	return n, nil
+}
+
+// SettingsGetBool 返回 bool 配置,接受 "1"/"true"/"t"/"TRUE" 等;
+func (s *Store) SettingsGetBool(key string, def bool) (bool, error) {
+	v, ok, err := s.SettingsGet(key)
+	if err != nil || !ok {
+		return def, err
+	}
+	b, err := strconv.ParseBool(v)
+	if err != nil {
+		return def, nil
+	}
+	return b, nil
+}
+
+// SettingsGetDuration 返回 duration 配置;支持 "30s" "5m" "1h" 等。
+func (s *Store) SettingsGetDuration(key string, def time.Duration) (time.Duration, error) {
+	v, ok, err := s.SettingsGet(key)
+	if err != nil || !ok {
+		return def, err
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil {
+		return def, nil
+	}
+	return d, nil
+}
+
+// isAllowedSettingsKey 检查 key 是否在白名单;白名单空时全放行。
+func isAllowedSettingsKey(key string) bool {
+	if len(allowedSettingsKeys) == 0 {
+		return true
+	}
+	_, ok := allowedSettingsKeys[key]
+	return ok
+}

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

@@ -0,0 +1,356 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// Voice 是一行音色记录;时间字段保持 ISO8601 字符串(SQLite TEXT 默认)。
+//
+// JSON tag 是为了前端(admin.html)能直接读取 — 之前没加 tag 时 Go 的
+// "Name" / "Speaker" 等大写字段会原样输出,前端用 v.name 拿到 undefined,
+// 整张表看起来"空"但其实有数据。补 tag 后前端能正常显示。
+type Voice struct {
+	ID          int64  `json:"id"`
+	Name        string `json:"name"`
+	Speaker     string `json:"speaker"`
+	ResourceID  string `json:"resource_id"`
+	Model       string `json:"model"`
+	Language    string `json:"language"`
+	Description string `json:"description"`
+	Enabled     bool   `json:"enabled"`
+	CreatedAt   string `json:"created_at"`
+	UpdatedAt   string `json:"updated_at"`
+}
+
+// ErrDuplicate 表示 name 唯一冲突;controller 翻译为 409。
+var ErrDuplicate = errors.New("store: voice name already exists")
+
+// ErrInUse 表示试图删除被 default_speaker 引用的音色;controller 翻译为 409。
+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}$`)
+
+// VoiceList 列出所有音色;includeDisabled=false 时只返回 enabled=1。
+// 按 id 升序,稳定顺序便于前端展示。
+func (s *Store) VoiceList(includeDisabled bool) ([]Voice, error) {
+	q := `SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
+	      FROM voices`
+	if !includeDisabled {
+		q += ` WHERE enabled = 1`
+	}
+	q += ` ORDER BY id ASC`
+
+	rows, err := s.db.Query(q)
+	if err != nil {
+		return nil, fmt.Errorf("store: voice list: %w", err)
+	}
+	defer rows.Close()
+
+	out := make([]Voice, 0, 8)
+	for rows.Next() {
+		v, err := scanVoice(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, v)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: voice list rows: %w", err)
+	}
+	return out, nil
+}
+
+// VoiceGet 按 id 查;未命中返回 ErrNotFound。
+func (s *Store) VoiceGet(id int64) (*Voice, error) {
+	row := s.db.QueryRow(`SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
+	                     FROM voices WHERE id = ?`, id)
+	v, err := scanVoice(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: voice get id=%d: %w", id, err)
+	}
+	return &v, nil
+}
+
+// VoiceGetByName 按 name 查;未命中返回 ErrNotFound。
+// tts.go 路由用这个,要求 name 走参数化查询。
+func (s *Store) VoiceGetByName(name string) (*Voice, error) {
+	row := s.db.QueryRow(`SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
+	                     FROM voices WHERE name = ?`, name)
+	v, err := scanVoice(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: voice getbyname %q: %w", name, err)
+	}
+	return &v, nil
+}
+
+// GetVoiceForTTS 实现 setting.Store 接口,返 voice 行的 TTS 关键字段。
+//   - found=false: voice 不存在(ErrNotFound 翻译为 found=false)
+//   - err != nil:  真错误(db 失败等)
+// 这个方法存在是为了让 *Store 满足 setting.Store 接口,且不引起
+// setting → store → setting 循环 import。
+func (s *Store) GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error) {
+	v, err := s.VoiceGetByName(name)
+	if err != nil {
+		if errors.Is(err, ErrNotFound) {
+			return "", "", "", false, nil
+		}
+		return "", "", "", false, err
+	}
+	return v.Speaker, v.ResourceID, v.Model, true, nil
+}
+
+// VoiceInsert 新增音色;name 冲突返回 ErrDuplicate。
+// 客户端输入错误(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)
+	v.ResourceID = strings.TrimSpace(v.ResourceID)
+	v.Model = strings.TrimSpace(v.Model)
+	v.Language = strings.TrimSpace(v.Language)
+	v.Description = strings.TrimSpace(v.Description)
+
+	if err := validateVoiceName(v.Name); err != nil {
+		// validateVoiceName 返纯文本;这里 wrap 进 ErrInvalid 让 controller 用 errors.Is 判定。
+		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 := s.db.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
+}
+
+// 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)
+	v.ResourceID = strings.TrimSpace(v.ResourceID)
+	v.Model = strings.TrimSpace(v.Model)
+	v.Language = strings.TrimSpace(v.Language)
+	v.Description = strings.TrimSpace(v.Description)
+
+	if err := validateVoiceName(v.Name); err != nil {
+		return err
+	}
+	if v.Speaker == "" {
+		return fmt.Errorf("store: voice update: speaker is required")
+	}
+	if v.ResourceID == "" {
+		return fmt.Errorf("store: voice update: resource_id is required")
+	}
+
+	// 整段事务: 读旧名 → 同步 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)
+	if err != nil {
+		if isUniqueViolation(err) {
+			return ErrDuplicate
+		}
+		return fmt.Errorf("store: voice update id=%d: %w", v.ID, err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return ErrNotFound
+	}
+
+	// 4. 提交
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("store: voice update commit: %w", err)
+	}
+	return nil
+}
+
+// VoiceDelete 按 id 删;若被 settings.default_speaker 引用则返回 ErrInUse。
+func (s *Store) VoiceDelete(id int64) error {
+	v, err := s.VoiceGet(id)
+	if err != nil {
+		return err
+	}
+
+	// 检查 default_speaker 引用
+	defVal, defOK, err := s.SettingsGet("default_speaker")
+	if err != nil {
+		return err
+	}
+	if defOK && defVal == v.Name {
+		return ErrInUse
+	}
+
+	res, err := s.db.Exec(`DELETE FROM voices WHERE id = ?`, id)
+	if err != nil {
+		return fmt.Errorf("store: voice delete id=%d: %w", id, err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+// VoiceToggleEnabled 翻转启用状态;返回更新后的值。
+func (s *Store) VoiceToggleEnabled(id int64, enabled bool) error {
+	res, err := s.db.Exec(`UPDATE voices SET enabled=?, updated_at=datetime('now') WHERE id = ?`,
+		boolToInt(enabled), id)
+	if err != nil {
+		return fmt.Errorf("store: voice toggle id=%d: %w", id, err)
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+// VoiceCount 统计行数;M2 仪表盘用。
+func (s *Store) VoiceCount() (int, error) {
+	var n int
+	err := s.db.QueryRow(`SELECT COUNT(*) FROM voices`).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("store: voice count: %w", err)
+	}
+	return n, nil
+}
+
+// VoiceCountEnabled 统计 enabled=1 的行数;仪表盘用。
+func (s *Store) VoiceCountEnabled() (int, error) {
+	var n int
+	err := s.db.QueryRow(`SELECT COUNT(*) FROM voices WHERE enabled = 1`).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("store: voice count enabled: %w", err)
+	}
+	return n, nil
+}
+
+// scanVoice 把 row 扫描成 Voice;接受 *sql.Row 或 *sql.Rows(都实现 Scan)。
+type scanner interface {
+	Scan(dest ...any) error
+}
+
+func scanVoice(r scanner) (Voice, error) {
+	var v Voice
+	var enabled int
+	err := r.Scan(&v.ID, &v.Name, &v.Speaker, &v.ResourceID, &v.Model, &v.Language, &v.Description, &enabled, &v.CreatedAt, &v.UpdatedAt)
+	if err != nil {
+		return v, err
+	}
+	v.Enabled = enabled != 0
+	return v, nil
+}
+
+func validateVoiceName(name string) error {
+	if name == "" {
+		return fmt.Errorf("store: voice name is required")
+	}
+	if !voiceNameRe.MatchString(name) {
+		return fmt.Errorf("store: voice name %q invalid (must match [a-zA-Z0-9_-]{1,64})", name)
+	}
+	return nil
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// isUniqueViolation 判定 SQLite 唯一约束错误。
+// modernc.org/sqlite 错误信息中包含 "UNIQUE constraint failed: <table>.<col>";做大小写不敏感包含判定。
+func isUniqueViolation(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "unique constraint failed")
+}
+
+// VoiceInsertedAt 返回当前时间字符串(UTC, RFC3339);留作未来 Voice 构造时使用,
+// 暂不导出。
+func voiceNow() string { return time.Now().UTC().Format(time.RFC3339) }

telemetry/counter.go

@@ -0,0 +1,90 @@
+package telemetry
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"sync"
+	"sync/atomic"
+)
+
+// Counter 单调递增的累计指标(整数语义,内部用 float64 位以 atomic 操作)。
+type Counter struct {
+	metricName string
+	help       string
+	labelNames []string
+
+	mu     sync.RWMutex
+	values map[string]*counterChild // key = labelKey(...)
+}
+
+type counterChild struct {
+	labels Labels
+	bits   atomic.Uint64 // float64
+}
+
+func newCounter(name, help string, labelNames []string) *Counter {
+	return &Counter{
+		metricName: name,
+		help:       help,
+		labelNames: append([]string(nil), labelNames...),
+		values:     make(map[string]*counterChild),
+	}
+}
+
+// Inc 计数 +1。
+func (c *Counter) Inc(labels Labels) { c.Add(1, labels) }
+
+// Add 累加 v(v 必须 >= 0)。
+func (c *Counter) Add(v float64, labels Labels) {
+	if v < 0 {
+		return
+	}
+	child := c.getOrCreate(labels)
+	for {
+		bits := child.bits.Load()
+		cur := float64frombits(bits)
+		next := float64bits(cur + v)
+		if child.bits.CompareAndSwap(bits, next) {
+			return
+		}
+	}
+}
+
+func (c *Counter) getOrCreate(labels Labels) *counterChild {
+	key := labelKey(c.labelNames, labels)
+	c.mu.RLock()
+	if child, ok := c.values[key]; ok {
+		c.mu.RUnlock()
+		return child
+	}
+	c.mu.RUnlock()
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if child, ok := c.values[key]; ok {
+		return child
+	}
+	child := &counterChild{labels: copyLabels(labels, c.labelNames)}
+	c.values[key] = child
+	return child
+}
+
+func (c *Counter) collect(w io.Writer) {
+	fmt.Fprintf(w, "# HELP %s %s\n", c.metricName, c.help)
+	fmt.Fprintf(w, "# TYPE %s counter\n", c.metricName)
+
+	c.mu.RLock()
+	keys := make([]string, 0, len(c.values))
+	for k := range c.values {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	defer c.mu.RUnlock()
+
+	for _, k := range keys {
+		child := c.values[k]
+		val := float64frombits(child.bits.Load())
+		writeMetricLine(w, c.metricName, child.labels, val)
+	}
+}

telemetry/format.go

@@ -0,0 +1,88 @@
+package telemetry
+
+import (
+	"fmt"
+	"io"
+	"math"
+	"strconv"
+	"strings"
+)
+
+// copyLabels 返回只包含 labelNames 中声明的 key 的副本,缺失补空串。
+// 这样序列化时输出顺序和数量固定。
+func copyLabels(labels Labels, names []string) Labels {
+	if len(names) == 0 {
+		return Labels{}
+	}
+	out := make(Labels, len(names))
+	for _, n := range names {
+		out[n] = labels[n]
+	}
+	return out
+}
+
+func mergeLabels(a, b Labels) Labels {
+	out := make(Labels, len(a)+len(b))
+	for k, v := range a {
+		out[k] = v
+	}
+	for k, v := range b {
+		out[k] = v
+	}
+	return out
+}
+
+// formatLabels 序列化为 `{k1="v1",k2="v2"}`;空集合返回空字符串。
+// value 内的 `\`, `"`, 换行会按 Prometheus 规范转义。
+func formatLabels(labels Labels) string {
+	if len(labels) == 0 {
+		return ""
+	}
+	keys := sortedKeys(labels)
+	var sb strings.Builder
+	sb.WriteByte('{')
+	for i, k := range keys {
+		if i > 0 {
+			sb.WriteByte(',')
+		}
+		sb.WriteString(k)
+		sb.WriteString(`="`)
+		sb.WriteString(escapeLabelValue(labels[k]))
+		sb.WriteByte('"')
+	}
+	sb.WriteByte('}')
+	return sb.String()
+}
+
+func escapeLabelValue(v string) string {
+	if !strings.ContainsAny(v, "\\\"\n") {
+		return v
+	}
+	var sb strings.Builder
+	sb.Grow(len(v) + 2)
+	for i := 0; i < len(v); i++ {
+		switch v[i] {
+		case '\\':
+			sb.WriteString(`\\`)
+		case '"':
+			sb.WriteString(`\"`)
+		case '\n':
+			sb.WriteString(`\n`)
+		default:
+			sb.WriteByte(v[i])
+		}
+	}
+	return sb.String()
+}
+
+func writeMetricLine(w io.Writer, name string, labels Labels, value float64) {
+	fmt.Fprintf(w, "%s%s %s\n", name, formatLabels(labels), formatFloat(value))
+}
+
+func formatFloat(f float64) string {
+	return strconv.FormatFloat(f, 'g', -1, 64)
+}
+
+// float64 bits 互转,封装到独立文件避免重复。
+func float64bits(f float64) uint64     { return math.Float64bits(f) }
+func float64frombits(b uint64) float64 { return math.Float64frombits(b) }

telemetry/gauge.go

@@ -0,0 +1,96 @@
+package telemetry
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"sync"
+	"sync/atomic"
+)
+
+// Gauge 可增可减的瞬时值。
+type Gauge struct {
+	metricName string
+	help       string
+	labelNames []string
+
+	mu     sync.RWMutex
+	values map[string]*gaugeChild
+}
+
+type gaugeChild struct {
+	labels Labels
+	bits   atomic.Uint64
+}
+
+func newGauge(name, help string, labelNames []string) *Gauge {
+	return &Gauge{
+		metricName: name,
+		help:       help,
+		labelNames: append([]string(nil), labelNames...),
+		values:     make(map[string]*gaugeChild),
+	}
+}
+
+// Set 直接设置当前值。
+func (g *Gauge) Set(v float64, labels Labels) {
+	child := g.getOrCreate(labels)
+	child.bits.Store(float64bits(v))
+}
+
+// Inc +1。
+func (g *Gauge) Inc(labels Labels) { g.Add(1, labels) }
+
+// Dec -1。
+func (g *Gauge) Dec(labels Labels) { g.Add(-1, labels) }
+
+// Add 累加 v(可负)。
+func (g *Gauge) Add(v float64, labels Labels) {
+	child := g.getOrCreate(labels)
+	for {
+		bits := child.bits.Load()
+		cur := float64frombits(bits)
+		next := float64bits(cur + v)
+		if child.bits.CompareAndSwap(bits, next) {
+			return
+		}
+	}
+}
+
+func (g *Gauge) getOrCreate(labels Labels) *gaugeChild {
+	key := labelKey(g.labelNames, labels)
+	g.mu.RLock()
+	if c, ok := g.values[key]; ok {
+		g.mu.RUnlock()
+		return c
+	}
+	g.mu.RUnlock()
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if c, ok := g.values[key]; ok {
+		return c
+	}
+	c := &gaugeChild{labels: copyLabels(labels, g.labelNames)}
+	g.values[key] = c
+	return c
+}
+
+func (g *Gauge) collect(w io.Writer) {
+	fmt.Fprintf(w, "# HELP %s %s\n", g.metricName, g.help)
+	fmt.Fprintf(w, "# TYPE %s gauge\n", g.metricName)
+
+	g.mu.RLock()
+	keys := make([]string, 0, len(g.values))
+	for k := range g.values {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	defer g.mu.RUnlock()
+
+	for _, k := range keys {
+		child := g.values[k]
+		val := float64frombits(child.bits.Load())
+		writeMetricLine(w, g.metricName, child.labels, val)
+	}
+}

telemetry/histogram.go

@@ -0,0 +1,114 @@
+package telemetry
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"sync"
+	"sync/atomic"
+)
+
+// DefaultLatencyBuckets 适合 HTTP/TTS 场景的默认桶(秒)。
+var DefaultLatencyBuckets = []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30}
+
+// Histogram 累计分布型指标,记录观测值的分布。
+//
+// 内部为每个 child 维护:
+//   - buckets[i] 累计计数(<= le_i 的观测数,不含 +Inf 桶)
+//   - count 全部观测计数
+//   - sum 全部观测值之和
+type Histogram struct {
+	metricName string
+	help       string
+	labelNames []string
+	buckets    []float64 // 用户声明的上界,不含 +Inf
+
+	mu     sync.RWMutex
+	values map[string]*histChild
+}
+
+type histChild struct {
+	labels  Labels
+	buckets []atomic.Uint64 // 累计计数
+	count   atomic.Uint64
+	sumBits atomic.Uint64 // float64
+}
+
+func newHistogram(name, help string, buckets []float64, labelNames []string) *Histogram {
+	bs := append([]float64(nil), buckets...)
+	sort.Float64s(bs)
+	return &Histogram{
+		metricName: name,
+		help:       help,
+		labelNames: append([]string(nil), labelNames...),
+		buckets:    bs,
+		values:     make(map[string]*histChild),
+	}
+}
+
+// Observe 记录一个观测值。
+func (h *Histogram) Observe(v float64, labels Labels) {
+	child := h.getOrCreate(labels)
+	for {
+		bits := child.sumBits.Load()
+		cur := float64frombits(bits)
+		next := float64bits(cur + v)
+		if child.sumBits.CompareAndSwap(bits, next) {
+			break
+		}
+	}
+	child.count.Add(1)
+	for i, le := range h.buckets {
+		if v <= le {
+			child.buckets[i].Add(1)
+		}
+	}
+}
+
+func (h *Histogram) getOrCreate(labels Labels) *histChild {
+	key := labelKey(h.labelNames, labels)
+	h.mu.RLock()
+	if c, ok := h.values[key]; ok {
+		h.mu.RUnlock()
+		return c
+	}
+	h.mu.RUnlock()
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if c, ok := h.values[key]; ok {
+		return c
+	}
+	c := &histChild{
+		labels:  copyLabels(labels, h.labelNames),
+		buckets: make([]atomic.Uint64, len(h.buckets)),
+	}
+	h.values[key] = c
+	return c
+}
+
+func (h *Histogram) collect(w io.Writer) {
+	fmt.Fprintf(w, "# HELP %s %s\n", h.metricName, h.help)
+	fmt.Fprintf(w, "# TYPE %s histogram\n", h.metricName)
+
+	h.mu.RLock()
+	keys := make([]string, 0, len(h.values))
+	for k := range h.values {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	defer h.mu.RUnlock()
+
+	for _, k := range keys {
+		child := h.values[k]
+		for i, le := range h.buckets {
+			merged := mergeLabels(child.labels, Labels{"le": formatFloat(le)})
+			fmt.Fprintf(w, "%s_bucket%s %d\n", h.metricName, formatLabels(merged), child.buckets[i].Load())
+		}
+		merged := mergeLabels(child.labels, Labels{"le": "+Inf"})
+		fmt.Fprintf(w, "%s_bucket%s %d\n", h.metricName, formatLabels(merged), child.count.Load())
+		sum := float64frombits(child.sumBits.Load())
+		fmt.Fprintf(w, "%s_sum%s %s\n", h.metricName, formatLabels(child.labels), formatFloat(sum))
+		fmt.Fprintf(w, "%s_count%s %d\n", h.metricName, formatLabels(child.labels), child.count.Load())
+	}
+}

telemetry/labels.go

@@ -0,0 +1,104 @@
+// Package telemetry 提供进程内可观测能力:Counter / Gauge / Histogram,
+// 以及 Prometheus 文本格式导出。
+//
+// 设计原则:
+//   - 零外部依赖,只使用标准库;
+//   - label key 在指标注册时锁定,运行期不可新增(避免 cardinality 爆炸);
+//   - 所有并发安全由实现保证,调用方无需加锁;
+//   - Meter 是高层入口,NoopMeter 用于测试。
+package telemetry
+
+import (
+	"crypto/sha1"
+	"encoding/hex"
+	"sort"
+	"strings"
+)
+
+// Labels 是指标附加的标签集合。Value 在序列化时会按 Prometheus 规范转义。
+type Labels map[string]string
+
+// SpeakerLabel 把 speaker ID 转成不可逆的稳定短哈希,作为指标 label。
+// 目的:保护火山复刻音色资产(speaker ID 是用户付费 / 隐私敏感);
+// 同时仍能按 voice 聚合观测(同 speaker → 同 label)。
+//
+// 算法: sha1(s)[:8] = 32 bits 空间;典型 <100 个 voice 场景无碰撞风险。
+// 空串返回 "unknown",避免 /metrics label 出现空值 (Prometheus 禁止空 label)。
+//
+// 注意: 这是**不可逆**哈希,不是加密;不可用于需要还原原始 speaker 的场景。
+// Admin UI 想要看原名时,通过 /api/voices 拿 name 字段对照。
+func SpeakerLabel(s string) string {
+	if s == "" {
+		return "unknown"
+	}
+	sum := sha1.Sum([]byte(s))
+	return hex.EncodeToString(sum[:])[:8]
+}
+
+// MaskSpeaker 把 speaker ID 部分打码用于日志输出。
+//   - 空 → "***"
+//   - 长度 ≤ 4 → 全打码
+//   - 其它 → 前 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 emptyLabel
+	}
+	if len(s) <= 4 {
+		return strings.Repeat("*", len(s))
+	}
+	// 找前 4 字符中第一个非 [A-Za-z0-9_] 字符做截断,避免截到奇怪位置
+	// (虽然火山 ID 实际都是字母数字组合,这里保险)
+	prefix := s[:4]
+	suffix := s[len(s)-4:]
+	return prefix + "****" + suffix
+}
+
+// labelKey 计算一组标签的稳定 key,用于在内部 map 中唯一定位 child。
+// 缺失或多余的 label 一律视为空串,以保证 child 数量与 label 名集合一致。
+func labelKey(names []string, labels Labels) string {
+	if len(names) == 0 {
+		return ""
+	}
+	parts := make([]string, 0, len(names)*2)
+	for _, n := range names {
+		parts = append(parts, n, labels[n])
+	}
+	return joinLabelParts(parts)
+}
+
+func joinLabelParts(parts []string) string {
+	out := make([]byte, 0, 16*len(parts))
+	for i, p := range parts {
+		if i > 0 {
+			out = append(out, 0)
+		}
+		out = append(out, p...)
+	}
+	return string(out)
+}
+
+// sortedKeys 返回按字典序排列的 key,用于导出时输出稳定顺序。
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}

telemetry/meter.go

@@ -0,0 +1,60 @@
+package telemetry
+
+import "net/http"
+
+// Meter 是 telemetry 的高层入口,提供 Counter / Gauge / Histogram 的构造方法。
+// 启动时调用 NewMeter() 得到默认实现,测试时可换成 NoopMeter。
+//
+// 设计:抽象成 interface 是为了在测试或禁用观测时能无侵入替换实现;
+// 真正的注册逻辑全部委托给内部 *Registry。
+type Meter interface {
+	Handler() http.Handler
+	Registry() *Registry
+	NewCounter(name, help string, labelNames ...string) *Counter
+	NewGauge(name, help string, labelNames ...string) *Gauge
+	NewHistogram(name, help string, buckets []float64, labelNames ...string) *Histogram
+}
+
+// RealMeter 是 Meter 的默认实现,内部维护一个 *Registry。
+type RealMeter struct {
+	reg *Registry
+}
+
+// NewMeter 构造默认 Meter 实现。
+func NewMeter() Meter {
+	return &RealMeter{reg: newRegistry()}
+}
+
+func (m *RealMeter) Handler() http.Handler { return m.reg.Handler() }
+
+// Registry 暴露给特殊用例(如测试断言),生产代码不应使用。
+func (m *RealMeter) Registry() *Registry { return m.reg }
+
+// NewCounter 注册并返回一个 Counter。
+//   - name 指标名(Prometheus 风格,如 "tts_request_total")
+//   - help 帮助文本
+//   - labelNames 注册时锁定的 label key 集合,运行期不可变
+func (m *RealMeter) NewCounter(name, help string, labelNames ...string) *Counter {
+	c := newCounter(name, help, labelNames)
+	if err := m.reg.register(name, c); err != nil {
+		// 注册重名是启动期 bug,直接 panic 让问题在启动时暴露。
+		panic(err)
+	}
+	return c
+}
+
+func (m *RealMeter) NewGauge(name, help string, labelNames ...string) *Gauge {
+	g := newGauge(name, help, labelNames)
+	if err := m.reg.register(name, g); err != nil {
+		panic(err)
+	}
+	return g
+}
+
+func (m *RealMeter) NewHistogram(name, help string, buckets []float64, labelNames ...string) *Histogram {
+	h := newHistogram(name, help, buckets, labelNames)
+	if err := m.reg.register(name, h); err != nil {
+		panic(err)
+	}
+	return h
+}

telemetry/noop.go

@@ -0,0 +1,22 @@
+package telemetry
+
+import "net/http"
+
+// NoopMeter 是一个不采集、不输出的 Meter,用于单元测试或禁用观测的场景。
+// 返回的 Counter / Gauge / Histogram 实例不会被注册到任何 Registry,
+// 它们的 Inc/Add/Observe 调用在本进程内没有可见效果(每次返回新的空实例)。
+//
+// 实现 Meter 接口。
+type NoopMeter struct{}
+
+func (NoopMeter) NewCounter(string, string, ...string) *Counter {
+	return newCounter("", "", nil)
+}
+func (NoopMeter) NewGauge(string, string, ...string) *Gauge {
+	return newGauge("", "", nil)
+}
+func (NoopMeter) NewHistogram(string, string, []float64, ...string) *Histogram {
+	return newHistogram("", "", nil, nil)
+}
+func (NoopMeter) Handler() http.Handler { return http.NotFoundHandler() }
+func (NoopMeter) Registry() *Registry   { return nil }

telemetry/registry.go

@@ -0,0 +1,66 @@
+package telemetry
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+	"sync"
+)
+
+// collector 是 Counter / Gauge / Histogram 共同实现的内部接口。
+type collector interface {
+	collect(w io.Writer)
+}
+
+// Registry 持有已注册的全部指标,提供 Prometheus 文本格式导出。
+type Registry struct {
+	mu      sync.RWMutex
+	entries map[string]collector
+	order   []string // 保留注册顺序,使输出可预测
+}
+
+func newRegistry() *Registry {
+	return &Registry{
+		entries: make(map[string]collector),
+	}
+}
+
+func (r *Registry) register(name string, c collector) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if _, exists := r.entries[name]; exists {
+		return fmt.Errorf("metric %q already registered", name)
+	}
+	r.entries[name] = c
+	r.order = append(r.order, name)
+	return nil
+}
+
+// Gather 把所有指标按注册顺序写入 w,文本格式遵循 Prometheus 0.0.4。
+func (r *Registry) Gather(w io.Writer) error {
+	r.mu.RLock()
+	order := append([]string(nil), r.order...)
+	defer r.mu.RUnlock()
+	for _, name := range order {
+		r.entries[name].collect(w)
+	}
+	return nil
+}
+
+// Handler 返回标准 Prometheus 抓取端点。
+func (r *Registry) Handler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+		_ = r.Gather(w)
+	})
+}
+
+// 注册顺序的辅助,用于测试断言。
+func (r *Registry) names() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := append([]string(nil), r.order...)
+	sort.Strings(out)
+	return out
+}

tts_server.go

@@ -1,778 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"bytes"
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net"
-	"net/http"
-	"os"
-	"os/signal"
-	"runtime"
-	"strings"
-	"sync"
-	"syscall"
-	"time"
-
-	"github.com/google/uuid"
-	"github.com/gorilla/mux"
-)
-
-const (
-	DEFAULT_PORT            = "8080"
-	DEFAULT_TIMEOUT         = 30 * time.Second
-	MAX_TEXT_LENGTH         = 5000
-	MIN_SPEED               = 0.25
-	MAX_SPEED               = 4.0
-	DEFAULT_SPEED           = 1.0
-	MAX_REQUEST_BODY_SIZE   = 1024 * 1024
-	RATE_LIMIT_REQUESTS     = 100
-	RATE_LIMIT_WINDOW       = time.Minute
-	MAX_RESPONSE_TIMES      = 100
-	MAX_ERRORS              = 10
-	MAX_CONCURRENT_REQUESTS = 10
-)
-
-type V3TTSResponse struct {
-	ReqID    string `json:"reqid"`
-	Code     int    `json:"code"`
-	Message  string `json:"message"`
-	Event    string `json:"event"`
-	Sequence int    `json:"sequence"`
-	Data     string `json:"data"`
-	Sentence string `json:"sentence,omitempty"`
-	IsFinal  bool   `json:"is_final"`
-	Usage    *Usage `json:"usage,omitempty"`
-}
-
-type Usage struct {
-	TextWords int `json:"text_words"`
-}
-
-type OpenAITTSRequest struct {
-	Model          string  `json:"model"`
-	Input          string  `json:"input"`
-	Voice          string  `json:"voice"`
-	ResponseFormat string  `json:"response_format,omitempty"`
-	Speed          float64 `json:"speed,omitempty"`
-}
-
-type ByteDanceTTSConfig struct {
-	ApiKey     string
-	ResourceId string
-	Speaker    string
-	URL        string
-	Timeout    time.Duration
-}
-
-type RateLimiter struct {
-	requests    map[string][]time.Time
-	mutex       sync.Mutex
-	limit       int
-	window      time.Duration
-	lastCleanup time.Time
-}
-
-const cleanupInterval = time.Hour
-
-type Stats struct {
-	totalRequests       int64
-	successfulRequests  int64
-	failedRequests      int64
-	totalResponseTime   time.Duration
-	recentResponseTimes []float64
-	responseTimesIndex  int
-	lastErrors          []string
-	errorsIndex         int
-	mutex               sync.RWMutex
-}
-
-var (
-	VALID_API_KEYS   []string
-	ttsConfig        ByteDanceTTSConfig
-	ttsConfigErr     error
-	globalHTTPClient *http.Client
-	apiStats         *Stats
-	rateLimiter      *RateLimiter
-	concurrencySem   chan struct{}
-)
-
-func init() {
-	globalHTTPClient = &http.Client{
-		Timeout: DEFAULT_TIMEOUT,
-		Transport: &http.Transport{
-			MaxIdleConns:        100,
-			MaxIdleConnsPerHost: 10,
-			IdleConnTimeout:     90 * time.Second,
-			TLSHandshakeTimeout: 10 * time.Second,
-		},
-	}
-
-	apiStats = &Stats{
-		recentResponseTimes: make([]float64, MAX_RESPONSE_TIMES),
-		lastErrors:          make([]string, MAX_ERRORS),
-	}
-
-	rateLimiter = &RateLimiter{
-		requests: make(map[string][]time.Time),
-		limit:    RATE_LIMIT_REQUESTS,
-		window:   RATE_LIMIT_WINDOW,
-	}
-
-	concurrencySem = make(chan struct{}, MAX_CONCURRENT_REQUESTS)
-}
-
-func (rl *RateLimiter) Allow(key string) bool {
-	rl.mutex.Lock()
-	defer rl.mutex.Unlock()
-
-	now := time.Now()
-	cutoff := now.Add(-rl.window)
-
-	if now.Sub(rl.lastCleanup) > cleanupInterval {
-		rl.cleanup()
-		rl.lastCleanup = now
-	}
-
-	timestamps := rl.requests[key]
-	valid := make([]time.Time, 0, len(timestamps))
-	for _, ts := range timestamps {
-		if ts.After(cutoff) {
-			valid = append(valid, ts)
-		}
-	}
-
-	if len(valid) >= rl.limit {
-		rl.requests[key] = valid
-		return false
-	}
-
-	valid = append(valid, now)
-	rl.requests[key] = valid
-	return true
-}
-
-func (rl *RateLimiter) cleanup() {
-	cutoff := time.Now().Add(-rl.window)
-	for k, v := range rl.requests {
-		valid := make([]time.Time, 0, len(v))
-		for _, ts := range v {
-			if ts.After(cutoff) {
-				valid = append(valid, ts)
-			}
-		}
-		if len(valid) == 0 {
-			delete(rl.requests, k)
-		} else {
-			rl.requests[k] = valid
-		}
-	}
-}
-
-func initTTSConfig() error {
-	apiKey := os.Getenv("BYTEDANCE_TTS_API_KEY")
-	resourceId := os.Getenv("BYTEDANCE_TTS_RESOURCE_ID")
-	speaker := os.Getenv("BYTEDANCE_TTS_SPEAKER")
-
-	missingVars := []string{}
-
-	if apiKey == "" {
-		missingVars = append(missingVars, "BYTEDANCE_TTS_API_KEY")
-	}
-	if resourceId == "" {
-		missingVars = append(missingVars, "BYTEDANCE_TTS_RESOURCE_ID")
-	}
-	if speaker == "" {
-		missingVars = append(missingVars, "BYTEDANCE_TTS_SPEAKER")
-	}
-
-	if len(missingVars) > 0 {
-		return fmt.Errorf("缺少必需的环境变量: %v", missingVars)
-	}
-
-	url := "https://openspeech.bytedance.com/api/v3/tts/unidirectional"
-
-	timeout := DEFAULT_TIMEOUT
-	if timeoutStr := os.Getenv("BYTEDANCE_TTS_TIMEOUT"); timeoutStr != "" {
-		if parsedTimeout, err := time.ParseDuration(timeoutStr); err == nil {
-			timeout = parsedTimeout
-		} else {
-			log.Printf("无效的超时设置 '%s'，使用默认值: %v", timeoutStr, timeout)
-		}
-	}
-
-	ttsConfig = ByteDanceTTSConfig{
-		ApiKey:     apiKey,
-		ResourceId: resourceId,
-		Speaker:    speaker,
-		URL:        url,
-		Timeout:    timeout,
-	}
-
-	return nil
-}
-
-func initAPIKeys() {
-	apiKey := os.Getenv("OPENAI_TTS_API_KEY")
-	if apiKey != "" {
-		VALID_API_KEYS = strings.Split(apiKey, ",")
-		for i, k := range VALID_API_KEYS {
-			VALID_API_KEYS[i] = strings.TrimSpace(k)
-		}
-		log.Printf("已配置 %d 个有效的API密钥", len(VALID_API_KEYS))
-	} else {
-		log.Println("警告: OPENAI_TTS_API_KEY 环境变量未设置，将允许所有请求")
-	}
-}
-
-func checkEnvironmentVariables() map[string]interface{} {
-	requiredVars := map[string]bool{
-		"BYTEDANCE_TTS_API_KEY":     os.Getenv("BYTEDANCE_TTS_API_KEY") != "",
-		"BYTEDANCE_TTS_RESOURCE_ID": os.Getenv("BYTEDANCE_TTS_RESOURCE_ID") != "",
-		"BYTEDANCE_TTS_SPEAKER":     os.Getenv("BYTEDANCE_TTS_SPEAKER") != "",
-	}
-
-	missingVars := []string{}
-	for varName, isSet := range requiredVars {
-		if !isSet {
-			missingVars = append(missingVars, varName)
-		}
-	}
-
-	optionalVars := map[string]bool{
-		"BYTEDANCE_TTS_TIMEOUT": os.Getenv("BYTEDANCE_TTS_TIMEOUT") != "",
-		"OPENAI_TTS_API_KEY":    os.Getenv("OPENAI_TTS_API_KEY") != "",
-		"PORT":                  os.Getenv("PORT") != "",
-	}
-
-	return map[string]interface{}{
-		"all_required_vars_set": len(missingVars) == 0,
-		"missing_required_vars": missingVars,
-		"required_vars_set":     requiredVars,
-		"optional_vars_set":     optionalVars,
-	}
-}
-
-func httpPostStream(url string, headers map[string]string, body []byte, timeout time.Duration) (*http.Response, error) {
-	req, err := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(body))
-	if err != nil {
-		return nil, err
-	}
-	for key, value := range headers {
-		req.Header.Set(key, value)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-	defer cancel()
-
-	req = req.WithContext(ctx)
-
-	return globalHTTPClient.Do(req)
-}
-
-func convertSpeedToSpeechRate(speed float64) int {
-	if speed <= 0.5 {
-		return -50
-	}
-	if speed >= 2.0 {
-		return 100
-	}
-	return int((speed - 1.0) * 100)
-}
-
-type SynthesisResult struct {
-	AudioData []byte
-	ReqID     string
-}
-
-func synthesis(text string, speed float64) (*SynthesisResult, error) {
-	reqID := uuid.NewString()
-
-	speechRate := convertSpeedToSpeechRate(speed)
-
-	params := map[string]interface{}{
-		"user": map[string]interface{}{
-			"uid": "uid",
-		},
-		"namespace": "BidirectionalTTS",
-		"req_params": map[string]interface{}{
-			"text":    text,
-			"speaker": ttsConfig.Speaker,
-			"audio_params": map[string]interface{}{
-				"format":      "wav",
-				"sample_rate": 24000,
-				"speech_rate": speechRate,
-			},
-		},
-	}
-
-	headers := map[string]string{
-		"Content-Type":      "application/json",
-		"Connection":        "keep-alive",
-		"X-Api-Resource-Id": ttsConfig.ResourceId,
-		"X-Api-Request-Id":  reqID,
-		"X-Api-Key":         ttsConfig.ApiKey,
-	}
-
-	bodyStr, err := json.Marshal(params)
-	if err != nil {
-		log.Printf("JSON marshal fail: %v", err)
-		return nil, err
-	}
-
-	resp, err := httpPostStream(ttsConfig.URL, headers, bodyStr, ttsConfig.Timeout)
-	if err != nil {
-		log.Printf("http post fail: %v", err)
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body)
-		log.Printf("TTS service error: status=%d, body=%s", resp.StatusCode, string(body))
-		return nil, fmt.Errorf("TTS service error: status %d", resp.StatusCode)
-	}
-
-	var audioData []byte
-	scanner := bufio.NewScanner(resp.Body)
-	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
-
-	for scanner.Scan() {
-		line := scanner.Bytes()
-		if len(line) == 0 {
-			continue
-		}
-
-		var v3Resp V3TTSResponse
-		if err := json.Unmarshal(line, &v3Resp); err != nil {
-			log.Printf("unmarshal chunk fail: %v, line: %s", err, string(line))
-			continue
-		}
-
-		if v3Resp.Code == 20000000 {
-			if v3Resp.Usage != nil {
-				log.Printf("TTS synthesis completed, usage: %+v", v3Resp.Usage)
-			}
-			for scanner.Scan() {
-			}
-			break
-		}
-
-		if v3Resp.Code != 0 {
-			log.Printf("TTS service error: code=%d, message=%s", v3Resp.Code, v3Resp.Message)
-			return nil, fmt.Errorf("TTS service error: %s", v3Resp.Message)
-		}
-
-		if v3Resp.Data != "" {
-			chunk, err := base64.StdEncoding.DecodeString(v3Resp.Data)
-			if err != nil {
-				log.Printf("base64 decode fail: %v", err)
-				return nil, err
-			}
-			audioData = append(audioData, chunk...)
-		} else if v3Resp.Sentence != "" {
-			log.Printf("Received sentence info (sequence %d): %s", v3Resp.Sequence, v3Resp.Sentence)
-		}
-	}
-
-	if err := scanner.Err(); err != nil {
-		log.Printf("read stream fail: %v", err)
-		return nil, err
-	}
-
-	if len(audioData) == 0 {
-		return nil, fmt.Errorf("no audio data received")
-	}
-
-	return &SynthesisResult{AudioData: audioData, ReqID: reqID}, nil
-}
-
-func validateAPIKey(r *http.Request) bool {
-	if len(VALID_API_KEYS) == 0 {
-		return true
-	}
-
-	authHeader := r.Header.Get("Authorization")
-	if authHeader == "" {
-		return false
-	}
-
-	if !strings.HasPrefix(authHeader, "Bearer ") {
-		return false
-	}
-
-	token := strings.TrimPrefix(authHeader, "Bearer ")
-	for _, validKey := range VALID_API_KEYS {
-		if token == validKey {
-			return true
-		}
-	}
-	return false
-}
-
-func getClientIP(r *http.Request) string {
-	xForwardedFor := r.Header.Get("X-Forwarded-For")
-	if xForwardedFor != "" {
-		ips := strings.Split(xForwardedFor, ",")
-		if len(ips) > 0 {
-			return strings.TrimSpace(ips[0])
-		}
-	}
-
-	xRealIP := r.Header.Get("X-Real-IP")
-	if xRealIP != "" {
-		return xRealIP
-	}
-
-	host, _, err := net.SplitHostPort(r.RemoteAddr)
-	if err != nil {
-		return r.RemoteAddr
-	}
-	return host
-}
-
-func openaiTTSHandler(w http.ResponseWriter, r *http.Request) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
-		return
-	}
-
-	if !validateAPIKey(r) {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusUnauthorized)
-		json.NewEncoder(w).Encode(map[string]interface{}{
-			"error": map[string]interface{}{
-				"message": "Invalid API key provided.",
-				"type":    "invalid_request_error",
-				"code":    "invalid_api_key",
-			},
-		})
-		return
-	}
-
-	if ttsConfigErr != nil {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusServiceUnavailable)
-		json.NewEncoder(w).Encode(map[string]interface{}{
-			"error": map[string]interface{}{
-				"message": fmt.Sprintf("TTS service configuration error: %v. Please check environment variables and restart the service.", ttsConfigErr),
-				"type":    "configuration_error",
-				"code":    "service_unavailable",
-			},
-		})
-		return
-	}
-
-	clientIP := getClientIP(r)
-	if !rateLimiter.Allow(clientIP) {
-		log.Printf("警告: 已超过IP速率限制，拒绝请求 - 客户端IP: %s", clientIP)
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusTooManyRequests)
-		json.NewEncoder(w).Encode(map[string]interface{}{
-			"error": map[string]interface{}{
-				"message": "Rate limit exceeded. Please try again later.",
-				"type":    "rate_limit_error",
-				"code":    "rate_limit_exceeded",
-			},
-		})
-		return
-	}
-
-	select {
-	case concurrencySem <- struct{}{}:
-		defer func() { <-concurrencySem }()
-	default:
-		log.Printf("警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: %s", getClientIP(r))
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusServiceUnavailable)
-		json.NewEncoder(w).Encode(map[string]interface{}{
-			"error": map[string]interface{}{
-				"message": "Server is busy, maximum concurrent requests reached. Please try again later.",
-				"type":    "concurrency_limit_error",
-				"code":    "max_concurrent_requests",
-			},
-		})
-		return
-	}
-
-	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, MAX_REQUEST_BODY_SIZE))
-	if err != nil {
-		if strings.Contains(err.Error(), "request body too large") {
-			http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
-		} else {
-			http.Error(w, "Failed to read request body", http.StatusBadRequest)
-		}
-		return
-	}
-
-	var req OpenAITTSRequest
-	if err := json.Unmarshal(body, &req); err != nil {
-		http.Error(w, "Invalid JSON", http.StatusBadRequest)
-		return
-	}
-
-	if req.Input == "" {
-		http.Error(w, "Input text is required", http.StatusBadRequest)
-		return
-	}
-
-	if len(req.Input) > MAX_TEXT_LENGTH {
-		http.Error(w, fmt.Sprintf("Input text too long (max %d characters)", MAX_TEXT_LENGTH), http.StatusBadRequest)
-		return
-	}
-
-	speed := req.Speed
-	if speed <= 0 {
-		speed = DEFAULT_SPEED
-	}
-	if speed < MIN_SPEED {
-		speed = MIN_SPEED
-	}
-	if speed > MAX_SPEED {
-		speed = MAX_SPEED
-	}
-
-	ttsStart := time.Now()
-	result, err := synthesis(req.Input, speed)
-	duration := time.Since(ttsStart)
-
-	if err != nil {
-		addRequestStats(false, duration, err.Error())
-		http.Error(w, "TTS synthesis failed", http.StatusInternalServerError)
-		return
-	}
-
-	addRequestStats(true, duration, "")
-
-	w.Header().Set("Content-Type", "audio/wav")
-	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)
-}
-
-func addRequestStats(success bool, responseTime time.Duration, errMsg string) {
-	apiStats.mutex.Lock()
-	defer apiStats.mutex.Unlock()
-
-	apiStats.totalRequests++
-	apiStats.totalResponseTime += responseTime
-
-	apiStats.recentResponseTimes[apiStats.responseTimesIndex] = responseTime.Seconds() * 1000
-	apiStats.responseTimesIndex = (apiStats.responseTimesIndex + 1) % MAX_RESPONSE_TIMES
-
-	if success {
-		apiStats.successfulRequests++
-	} else {
-		apiStats.failedRequests++
-		if errMsg != "" {
-			errInfo := fmt.Sprintf("%s: %s", time.Now().Format(time.RFC3339), errMsg)
-			apiStats.lastErrors[apiStats.errorsIndex] = errInfo
-			apiStats.errorsIndex = (apiStats.errorsIndex + 1) % MAX_ERRORS
-		}
-	}
-}
-
-func getMemoryInfo() map[string]interface{} {
-	var m runtime.MemStats
-	runtime.ReadMemStats(&m)
-	return map[string]interface{}{
-		"total_alloc": m.TotalAlloc,
-		"heap_alloc":  m.HeapAlloc,
-		"heap_inuse":  m.HeapInuse,
-		"goroutines":  runtime.NumGoroutine(),
-	}
-}
-
-func healthHandler(w http.ResponseWriter, r *http.Request) {
-	w.Header().Set("Content-Type", "application/json")
-
-	if ttsConfigErr != nil {
-		w.WriteHeader(http.StatusServiceUnavailable)
-	} else {
-		w.WriteHeader(http.StatusOK)
-	}
-
-	apiStats.mutex.RLock()
-	totalRequests := apiStats.totalRequests
-	successfulRequests := apiStats.successfulRequests
-	failedRequests := apiStats.failedRequests
-	totalResponseTime := apiStats.totalResponseTime
-	recentResponseTimes := make([]float64, 0, MAX_RESPONSE_TIMES)
-	for _, t := range apiStats.recentResponseTimes {
-		if t > 0 {
-			recentResponseTimes = append(recentResponseTimes, t)
-		}
-	}
-	lastErrors := make([]string, 0, MAX_ERRORS)
-	for _, e := range apiStats.lastErrors {
-		if e != "" {
-			lastErrors = append(lastErrors, e)
-		}
-	}
-	apiStats.mutex.RUnlock()
-
-	var errorRate float64
-	if totalRequests > 0 {
-		errorRate = float64(failedRequests) / float64(totalRequests) * 100
-	}
-
-	var avgResponseTime float64
-	if totalRequests > 0 {
-		avgResponseTime = totalResponseTime.Seconds() * 1000 / float64(totalRequests)
-	}
-
-	envCheckStatus := checkEnvironmentVariables()
-	allEnvVarsSet := envCheckStatus["all_required_vars_set"].(bool)
-
-	status := "ok"
-	if !allEnvVarsSet {
-		status = "configuration_error"
-	}
-
-	response := map[string]interface{}{
-		"status":     status,
-		"service":    "ByteDance TTS to OpenAI API Adapter",
-		"version":    "2.0.0 (v3 API)",
-		"uptime":     fmt.Sprintf("%.0f seconds", time.Since(startTime).Seconds()),
-		"start_time": startTime.Format(time.RFC3339),
-		"memory":     getMemoryInfo(),
-		"api_stats": map[string]interface{}{
-			"total_requests":           totalRequests,
-			"successful_requests":      successfulRequests,
-			"failed_requests":          failedRequests,
-			"error_rate_percent":       fmt.Sprintf("%.2f", errorRate),
-			"avg_response_time_ms":     fmt.Sprintf("%.2f", avgResponseTime),
-			"recent_response_times_ms": recentResponseTimes,
-		},
-		"errors": map[string]interface{}{
-			"recent_errors_count": len(lastErrors),
-		},
-		"config_status": map[string]interface{}{
-			"all_required_vars_set": allEnvVarsSet,
-			"config_error":          ttsConfigErr != nil,
-			"config_error_message":  fmt.Sprintf("%v", ttsConfigErr),
-		},
-	}
-
-	json.NewEncoder(w).Encode(response)
-}
-
-var startTime time.Time
-
-type statusRecorder struct {
-	http.ResponseWriter
-	statusCode int
-}
-
-func (rec *statusRecorder) WriteHeader(code int) {
-	rec.statusCode = code
-	rec.ResponseWriter.WriteHeader(code)
-}
-
-func corsMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
-
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusOK)
-			return
-		}
-
-		next.ServeHTTP(w, r)
-	})
-}
-
-func main() {
-	startTime = time.Now()
-
-	log.SetFlags(log.LstdFlags | log.Lshortfile)
-	log.SetPrefix("[TTS-Server] ")
-
-	initAPIKeys()
-
-	ttsConfigErr = initTTSConfig()
-	if ttsConfigErr != nil {
-		log.Printf("警告: 配置初始化失败: %v", ttsConfigErr)
-		log.Printf("服务将继续运行，但TTS功能不可用，请检查环境变量配置")
-	} else {
-		log.Printf("配置初始化成功")
-	}
-
-	router := mux.NewRouter()
-
-	router.Use(corsMiddleware)
-
-	router.Use(func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			if r.URL.Path == "/health" {
-				start := time.Now()
-				next.ServeHTTP(w, r)
-				log.Printf("%s %s %s %v", r.Method, r.RequestURI, r.RemoteAddr, time.Since(start))
-				return
-			}
-
-			start := time.Now()
-			rec := &statusRecorder{ResponseWriter: w, statusCode: http.StatusOK}
-			next.ServeHTTP(rec, r)
-			duration := time.Since(start)
-
-			log.Printf("%s %s %s %d %v", r.Method, r.RequestURI, r.RemoteAddr, rec.statusCode, duration)
-		})
-	})
-
-	router.HandleFunc("/v1/audio/speech", openaiTTSHandler).Methods("POST", "OPTIONS")
-	router.HandleFunc("/health", healthHandler).Methods("GET")
-	router.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		http.Redirect(w, r, "/health", http.StatusFound)
-	}).Methods("GET")
-
-	port := os.Getenv("PORT")
-	if port == "" {
-		port = DEFAULT_PORT
-	}
-
-	server := &http.Server{
-		Addr:         ":" + port,
-		Handler:      router,
-		ReadTimeout:  15 * time.Second,
-		WriteTimeout: 15 * time.Second,
-		IdleTimeout:  60 * time.Second,
-	}
-
-	quit := make(chan os.Signal, 1)
-	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-
-	go func() {
-		log.Printf("Starting ByteDance TTS to OpenAI API Adapter Server")
-		log.Printf("Listening on port: %s", port)
-		log.Printf("OpenAI TTS endpoint: http://localhost:%s/v1/audio/speech", port)
-		log.Printf("Health check: http://localhost:%s/health", port)
-		log.Printf("Using ByteDance v3 API: %s", ttsConfig.URL)
-		log.Printf("Resource ID: %s", ttsConfig.ResourceId)
-		log.Printf("Speaker: %s", ttsConfig.Speaker)
-
-		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			log.Fatalf("Server failed to start: %v", err)
-		}
-	}()
-
-	<-quit
-	log.Println("Shutting down server...")
-
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-
-	if err := server.Shutdown(ctx); err != nil {
-		log.Printf("Server forced to shutdown: %v", err)
-	} else {
-		log.Println("Server exited gracefully")
-	}
-}

version/version.go

@@ -0,0 +1,18 @@
+// Package version 提供构建时注入的版本信息。
+//
+// Version 和 Commit 在编译时通过 -ldflags 注入:
+//
+//	go build -ldflags "-X github.com/volcano-tts/tts-api/version.Version=$VERSION \
+//	                   -X github.com/volcano-tts/tts-api/version.Commit=$COMMIT"
+//
+// 开发时默认 "dev",CI/CD 时通常由 git describe 自动算出:
+//   VERSION=$(git describe --tags --always --dirty)
+//   COMMIT=$(git rev-parse --short HEAD)
+//
+// /health 端点会暴露这两个值,方便运维确认"跑的到底是哪个 commit"。
+package version
+
+var (
+	Version = "dev"
+	Commit  = "dev"
+)