feat(security): v0.3.0 阶段2 收口健康与指标端点

收口三个匿名可读端点:

- 根路径 /metrics:默认完全不注册(访问 404);配置 METRICS_ALLOW_CIDR 后按内网白名单开放
- /health:改为鉴权(原本匿名泄漏版本、commit、运行时长、内存、goroutine 与配置错误文本)
- /dashboard:改为鉴权(原本匿名,且它同时聚合 /health 与 /metrics,是单点泄漏最严重的端点)
- /api/setup/status:改为鉴权(原本 normal 模式下仍匿名返回 installed/mode)

新增 /healthz 匿名存活探针,只回 200 与字面量 ok、不含任何字段,解决
"给 /health 加鉴权后 K8s 探针与 Docker HEALTHCHECK 会一律 401 导致 Pod 反复重启" 的问题;
新增 /api/admin/health 鉴权版详细健康数据,与 /api/admin/metrics 风格一致。

/dashboard 对浏览器 HTML 请求做内容协商:返回页面外壳由前端显示登录视图(SPA 登录态存在
sessionStorage、不随请求发送,服务端无从判断,强行 401 会把现有体验变成直接报错);
非 HTML 请求(脚本、抓取)无凭证一律 401。页面外壳本身不含数据,数据全部来自鉴权后的 API。

IP 白名单中间件复用 GetClientIP(已处理 XFF 与 TRUSTED_PROXY_HOPS),非白名单返回 404
而非 403,避免向扫描者确认端点存在。main.go 启动日志同步改为指向 /healthz 与 /api/admin/health。

验证(真实服务器端到端,非仅单元测试):
- 安装前 /healthz=200、/health=401
- 安装后未带凭证:/healthz=200 /health=401 /metrics=404 /dashboard=401 /api/setup/status=401
- /dashboard 带 Accept: text/html 得 200 页面外壳,Accept: application/json 得 401
- /healthz 响应体确认为字面量 ok(不含任何字段)
- 回退模式(未配 admin_key):业务 key 访问管理接口全部 200,向后兼容成立
- 配置独立 admin_key 后:业务 key 访问 /health /api/admin/* /api/voices /api/settings 全部 401,
  admin_key 全部 200,而 /v1/audio/speech 不受影响;GET /api/settings 只回打码值

另新增 middleware/metricsip_test.go 覆盖 CIDR 命中、越界、非法 IP、空列表拒绝,
以及伪造 X-Forwarded-For 不能绕过白名单。

go build ./... / go vet ./... / go test ./... -count=1 全绿。

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+# 触发条件:
+#   - push 到 develop / main
+#   - 针对 develop / main 的 PR
+#
+# 为什么单独有这个 workflow:
+#   之前仓库里唯一的 workflow 是 docker.yml,它只在打 tag 时构建镜像,
+#   既不做 go build 也不跑 go vet,提交能不能编译没人自动盯着。
+#
+# ⚠️ 本 workflow 的实际覆盖范围(务必知悉):
+#   测试源码按项目策略**不入库**(见 .gitignore 的 `*_test.go`),因此干净克隆里
+#   没有任何 *_test.go,下面的 go test 步骤会打印 "no test files" 后通过。
+#   也就是说:**CI 只能守住"编译通过 + 静态检查通过",守不住行为回归。**
+#   行为回归要靠开发者在本地(测试文件所在处)自行执行:
+#       go test ./... -count=1
+#   如果哪天测试重新入库,把下面的 go test 步骤改成会真正跑起来的形态即可。
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+
+# 同一分支的重复推送取消上一次未完成的运行,省 CI 时间。
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          # 以 go.mod 里的 go 指令为准,避免两处版本漂移
+          go-version-file: go.mod
+          cache: true
+
+      - name: 下载依赖
+        run: go mod download
+
+      - name: 编译检查
+        run: go build ./...
+
+      - name: 静态检查
+        run: go vet ./...
+
+      # 以下两步在"测试不入库"策略下是空转(no test files),保留是为了:
+      #   1. 覆盖 lock 判定 / 损坏回退 / voice 路由等关键路径的测试一旦重新入库,
+      #      无需改 workflow 即可直接生效;
+      #   2. -count=1 禁用测试缓存,避免"改坏了却因缓存仍显示通过"。
+      - name: 测试(测试源码不入库时为空转)
+        run: go test ./... -count=1
+
+      - name: 关键路径汇总(integration)
+        run: go test ./test/integration/ -count=1 -v
+

.github/workflows/docker.yml

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

.gitignore

@@ -4,7 +4,10 @@
 *.test
 *.out
 
-# Go test sources (prevent accidental commit; tests live outside the repo by policy)
+# Go 测试源码:不入库(测试保留在本地磁盘,由开发者自行 go test ./... -count=1)
+# 理由:测试用例会暴露内部实现细节与断言,不作为交付物外流。
+# 注意:本规则会把测试文件挡在 git 之外,因此仓库内不提供自动化测试;
+#      .github/workflows/ci.yml 里的测试步骤在纯净克隆上无测试可跑。
 *_test.go
 
 # Editor / OS
@@ -33,14 +36,16 @@ bin/
 # Local dev scripts (per-user; not part of repo)
 start-local.ps1
 
+# Windows / PowerShell 脚本:一律不入库、不外流
+# ui-handoff/serve.ps1 与 start-local.ps1 是本地起服便利脚本(含本机路径与端口),
+# 不属于交付物。这两个文件在文件系统层面删除被拒,因此只能在 git 层屏蔽。
+*.ps1
+
+# UI handoff bundle(改造前的单文件副本 + 离线 mock 预览;仅本地对照,不部署)
+ui-handoff/
+
 # 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

@@ -2,6 +2,75 @@
 
 本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。
 
+## [未发布]
+
+### v0.3.0 · 进行中
+
+按 [docs/IMPLEMENT_v0.3.0.md](docs/IMPLEMENT_v0.3.0.md) 分阶段实施,当前完成 **阶段 1、阶段 2**。
+
+#### 新增
+
+- **`GET /healthz` 匿名存活探针**:只返回 `200` 与字面量 `ok`,**不含任何字段**。
+  供 K8s liveness/readiness、Docker HEALTHCHECK、负载均衡健康检查使用 ——
+  这些探针默认不带 `Authorization`,若继续指向 `/health` 会因鉴权而全部失败。
+- **`GET /api/admin/health` 鉴权版详细健康数据**:与 `/api/admin/metrics` 风格一致,
+  供管理面板与运维使用。
+- **`METRICS_ALLOW_CIDR` 内网白名单**(逗号分隔 CIDR,支持裸 IP 自动补掩码):
+  配置后在根路径注册 `/metrics`,仅放行白名单来源;**非白名单返回 404 而非 403**,
+  不向扫描者确认端点存在。未配置时根路径 `/metrics` **完全不注册**。
+- **独立管理凭证 `admin_key`(可选)**:管理接口凭证与业务调用凭证分离。
+  取值优先级 `admin_key`(DB) → `auth_key`(DB) → `OPENAI_TTS_API_KEY`(env)。
+  **不配置时行为与旧版完全一致**(回退用 `auth_key`),配置后业务 key 无法访问管理接口。
+  新增 `PUT /api/admin/settings/admin-key`(及旧前缀别名 `/api/settings/admin-key`)用于配置,
+  凭证**只写不读**(`GET /api/settings` 仅返回打码值与 `admin_key_set` / `admin_key_source`)。
+
+#### 变更(Breaking Change)
+
+- **`/health`、`/metrics`、`/dashboard` 不再匿名可读**:
+  - `/health` → 鉴权(原匿名,泄漏版本 / commit / 内存 / goroutine / 配置错误文本)
+  - `/dashboard` → 鉴权(原匿名,且它同时聚合 `/health` + `/metrics`,是单点泄漏最严重的端点)。
+    对浏览器 HTML 请求做内容协商:返回页面外壳由前端显示登录视图;非 HTML 请求(脚本、抓取)无凭证一律 401。
+  - 根路径 `/metrics` → 需要 `METRICS_ALLOW_CIDR`,否则 404
+  - `/api/setup/status` → 鉴权(原本 normal 模式下仍匿名返回 `{installed, mode}`)
+- **`RequireAdmin` 在凭证未配置时不再放行**。此前 `len(keys)==0` 直接放行,导致未配置凭证的
+  部署上管理接口完全裸奔(也使得给 `/metrics`、`/health` 加鉴权的加固形同虚设)。现在该情况返回 **401**。
+- **normal 模式下未配置任何管理凭证时服务拒绝启动**(fail-fast),启动摘要打印管理凭证来源。
+
+> ⚠️ **升级提示**
+> 1. 若部署未配置 `auth_key` / `admin_key` / `OPENAI_TTS_API_KEY` 中任何一个,升级后服务将拒绝启动。
+> 2. K8s 探针 / Docker HEALTHCHECK 请改指 **`/healthz`**;Prometheus 请改用鉴权版
+>    `/api/admin/metrics`,或配置 `METRICS_ALLOW_CIDR`。
+> 3. `METRICS_ALLOW_CIDR` 在 Docker 中**不要填 `127.0.0.1/32`**(那是容器自身回环),
+>    请填容器内网网段(如 `172.16.0.0/12`)。
+
+### 修复
+
+- **指标空指针崩溃**: `metrics` 包的全局指标(`UpstreamTotal` 等)默认是 nil,只有 `main` 调过
+  `metrics.Init()` 后才有值。任何**不经过 main** 的调用路径(直接调 handler、复用为库)都会在
+  `controller/tts.go` → `adapter/volcano/synthesis.go` → `metrics.AdapterRecorder` 处 nil 解引用 panic。
+  现在 `telemetry` 的 `Counter.Add` / `Gauge.Set` / `Gauge.Add` / `Histogram.Observe` 一律
+  **空接收者安全**(nil 静默忽略),并在包注释里写成显式设计约定。
+- **上游 client 空指针**: `volcano.(*HTTPClient).PostStream` 在 client 未初始化时 panic。
+  现在返回错误,由 controller 归一成 5xx 并记日志——装配错误不该拖垮进程。
+
+> 上面两个崩溃是**本地测试暴露出来的**:直接调用 handler 而不经过 `main` 的路径,
+> 会跳过 `metrics.Init()` 与 `volcanoClient` 的赋值。生产二进制不受影响。
+
+### 变更
+
+- **测试源码不再入库**: `.gitignore` 恢复整体屏蔽 `*_test.go`。测试用例会暴露内部实现
+  细节与断言,不作为交付物外流;测试文件保留在本地磁盘,由开发者自行执行
+  `go test ./... -count=1`。
+  ⚠️ 代价必须明确:仓库内**不提供自动化测试**,`.github/workflows/ci.yml` 里的
+  `go test` 步骤在纯净克隆上无测试可跑(会打印 `no test files` 并通过),
+  **CI 只能守住"编译通过 + 静态检查通过",守不住行为回归**。
+- **新增 CI 校验** (`.github/workflows/ci.yml`): push / PR 到 `develop`、`main` 时跑
+  `go build` + `go vet` + `go test -count=1`。此前仓库唯一的 workflow 只在打 tag 时构建
+  Docker 镜像,不做任何编译或测试校验。
+- **文档订正**: `docs/UI_HANDOFF.md` 原为"单文件换皮"外包任务书,其中的
+  "admin.html ≤ 35KB / setup.html ≤ 15KB / 只改两个 .html" 等约束在 admin 拆分多页后已作废,
+  现标注为历史文档并补上当前真实文件结构与验收清单。
+
 ## [0.2.0] - 2026-08-30
 
 ### 新增

adapter/volcano/client.go

@@ -29,7 +29,14 @@ func NewHTTPClient() *HTTPClient {
 
 // PostStream 发送一次流式请求,返回带上下文的 *http.Response。
 // 调用方负责关闭 resp.Body。
+//
+// 空接收者(nil *HTTPClient)安全:返回错误而不是 panic。未初始化的 client 属于
+// 装配错误,应当让该次请求以"上游不可用"失败(controller 归一成 5xx 并记日志),
+// 而不是让整个进程崩掉。
 func (h *HTTPClient) PostStream(ctx context.Context, url string, headers map[string]string, body []byte) (*http.Response, error) {
+	if h == nil || h.client == nil {
+		return nil, fmt.Errorf("volcano: HTTPClient 未初始化,无法发起上游请求")
+	}
 	if ctx == nil {
 		ctx = context.Background()
 	}

adapter/volcano/synthesis.go

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

cmd/dumpdb/main.go

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

controller/admin.go

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

controller/settings.go

@@ -16,22 +16,27 @@ import (
 // SettingsResponse 是 GET /api/settings 的响应。
 // API key 永远打码(借用 setting.maskAPIKey 风格,前 4 后 4 中间 ****)。
 type SettingsResponse struct {
-	APIKey           string `json:"api_key"`           // 打码形式,例如 S_G8****naJ1
+	APIKey     string `json:"api_key"`     // 打码形式,例如 S_G8****naJ1
-	APIKeySet        bool   `json:"api_key_set"`       // 是否已设置(用于前端判断要不要提示必填)
+	APIKeySet  bool   `json:"api_key_set"` // 是否已设置(用于前端判断要不要提示必填)
-	AuthKey          string `json:"auth_key"`          // 鉴权 key 打码(客户端访问 + admin 登录用)
+	AuthKey    string `json:"auth_key"`    // 鉴权 key 打码(客户端访问 + admin 登录用)
-	AuthKeySet       bool   `json:"auth_key_set"`
+	AuthKeySet bool   `json:"auth_key_set"`
-	CORSAllowAll     bool   `json:"cors_allow_all"`    // 允许所有来源(*)
+	// AdminKey 是**管理接口专用**凭证(v0.3.0 新增,可选)。
-	CORSOrigins      string `json:"cors_origins"`      // 逗号分隔的白名单(原文,含大小写,trim 末尾 /)
+	// 为空表示未单独配置,管理接口回退用 auth_key(向后兼容)。
-	CORSConfigured   bool   `json:"cors_configured"`   // 是否配了 CORS(给 banner 用)
+	AdminKey          string `json:"admin_key"`        // 打码形式
+	AdminKeySet       bool   `json:"admin_key_set"`    // 是否单独配置了 admin_key
+	AdminKeySource    string `json:"admin_key_source"` // admin_key / auth_key / env / ""(未配置)
+	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"`
+	DefaultSpeaker    string `json:"default_speaker"`
-	DefaultFormat    string `json:"default_format"`
+	DefaultFormat     string `json:"default_format"`
-	SampleRate       int    `json:"sample_rate"`
+	SampleRate        int    `json:"sample_rate"`
-	Model            string `json:"model"`
+	Model             string `json:"model"`
-	ModelType        int    `json:"model_type"`
+	ModelType         int    `json:"model_type"`
-	ExplicitLanguage string `json:"explicit_language"`
+	ExplicitLanguage  string `json:"explicit_language"`
-	EnableSubtitle   bool   `json:"enable_subtitle"`
+	EnableSubtitle    bool   `json:"enable_subtitle"`
-	UpdatedAt        string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
+	UpdatedAt         string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
 }
 
 // SettingsGetHandler GET /api/settings
@@ -58,6 +63,9 @@ func SettingsGetHandler(w http.ResponseWriter, r *http.Request) {
 		APIKeySet:         all["api_key"] != "",
 		AuthKey:           maskAPIKeyField(all["auth_key"]),
 		AuthKeySet:        all["auth_key"] != "",
+		AdminKey:          maskAPIKeyField(all["admin_key"]),
+		AdminKeySet:       all["admin_key"] != "",
+		AdminKeySource:    setting.GetAdminKeySource(),
 		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"] != "",
@@ -121,7 +129,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 	// 收集要更新的键值对
 	updates := make(map[string]string)
 	if body.DefaultResourceID != nil {
-		v := trimAll(*body.DefaultResourceID)
+		v := strings.TrimSpace(*body.DefaultResourceID)
 		if v == "" {
 			middleware.SendJSONError(w, http.StatusBadRequest, "default_resource_id cannot be empty", "invalid_request_error", "missing_field")
 			return
@@ -129,7 +137,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["default_resource_id"] = v
 	}
 	if body.DefaultSpeaker != nil {
-		v := trimAll(*body.DefaultSpeaker)
+		v := strings.TrimSpace(*body.DefaultSpeaker)
 		if v == "" {
 			middleware.SendJSONError(w, http.StatusBadRequest, "default_speaker cannot be empty", "invalid_request_error", "missing_field")
 			return
@@ -144,7 +152,7 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["default_speaker"] = v
 	}
 	if body.DefaultFormat != nil {
-		v := trimAll(*body.DefaultFormat)
+		v := strings.TrimSpace(*body.DefaultFormat)
 		if !isValidFormat(v) {
 			middleware.SendJSONError(w, http.StatusBadRequest,
 				fmt.Sprintf("default_format %q invalid; valid: mp3/wav/opus/pcm/aac/flac", v),
@@ -163,13 +171,13 @@ func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
 		updates["sample_rate"] = strconv.Itoa(v)
 	}
 	if body.Model != nil {
-		updates["model"] = trimAll(*body.Model)
+		updates["model"] = strings.TrimSpace(*body.Model)
 	}
 	if body.ModelType != nil {
 		updates["model_type"] = strconv.Itoa(*body.ModelType)
 	}
 	if body.ExplicitLanguage != nil {
-		updates["explicit_language"] = trimAll(*body.ExplicitLanguage)
+		updates["explicit_language"] = strings.TrimSpace(*body.ExplicitLanguage)
 	}
 	if body.EnableSubtitle != nil {
 		updates["enable_subtitle"] = boolToStr(*body.EnableSubtitle)
@@ -232,7 +240,7 @@ func SettingsAPIKeyHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	key := trimAll(body.APIKey)
+	key := strings.TrimSpace(body.APIKey)
 	if key == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest, "api_key cannot be empty", "invalid_request_error", "missing_field")
 		return
@@ -261,7 +269,7 @@ type SettingsAuthKeyRequest struct {
 }
 
 // SettingsAuthKeyHandler PUT /api/settings/auth-key
-// 鉴权: RequireAdmin。改完立即更新 setting.Auth.APIKeys(进程内生效),
+// 鉴权: RequireAdmin。改完立即刷新鉴权 key 列表(setting.SetAuthAPIKeys,进程内生效),
 // 下一个请求就用新 key — admin 自己改完要等下一次请求才能验证(避免改完立刻自踢)。
 func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPut {
@@ -280,7 +288,7 @@ func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	key := trimAll(body.AuthKey)
+	key := strings.TrimSpace(body.AuthKey)
 	if key == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest, "auth_key cannot be empty", "invalid_request_error", "missing_field")
 		return
@@ -292,23 +300,88 @@ func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
 	}
 	// 立即生效:不重新 LoadRuntimeConfig(那会覆盖其它字段),
 	// 只单独刷新 Auth.APIKeys
-	setting.Auth.APIKeys = []string{key}
+	setting.SetAuthAPIKeys([]string{key})
 	log.Printf("[settings] auth_key updated, runtime active (next request uses new key)")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
 }
 
+// SettingsAdminKeyRequest 是 PUT /api/admin/settings/admin-key 的 body。
+// admin_key 是**管理接口专用**凭证;与 auth_key(业务侧 /v1/audio/speech 鉴权)分离后,
+// 业务调用方拿到的 key 不再能访问管理接口。
+// 传空串表示"清除独立管理凭证",管理接口回退用 auth_key(即旧行为)。
+type SettingsAdminKeyRequest struct {
+	AdminKey string `json:"admin_key"`
+}
+
+// SettingsAdminKeyHandler PUT /api/admin/settings/admin-key
+// 鉴权: RequireAdmin(注意:能用当前凭证改,改完下一个请求即用新凭证)。
+func SettingsAdminKeyHandler(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 SettingsAdminKeyRequest
+	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.AdminKey)
+
+	if key == "" {
+		// 清除独立管理凭证 → 回退 auth_key。回退后若 auth_key 也为空,
+		// 管理接口将全部 401(RequireAdmin 不再空凭证放行),这里必须挡住。
+		authKey, _, _ := s.SettingsGet("auth_key")
+		if authKey == "" {
+			middleware.SendJSONError(w, http.StatusBadRequest,
+				"admin_key cannot be cleared while auth_key is empty (would lock out admin access)",
+				"invalid_request_error", "missing_field")
+			return
+		}
+		if err := s.SettingsDelete("admin_key"); err != nil {
+			log.Printf("[settings] admin-key clear: %v", err)
+			middleware.SendJSONError(w, http.StatusInternalServerError, "clear admin_key failed", "server_error", "db_write_failed")
+			return
+		}
+		setting.SetAdminKeys([]string{authKey}, "auth_key")
+		log.Printf("[settings] admin_key cleared; admin auth falls back to auth_key")
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "admin_key_set": false, "admin_key_source": "auth_key"})
+		return
+	}
+
+	if err := s.SettingsSet("admin_key", key); err != nil {
+		log.Printf("[settings] admin-key set: %v", err)
+		middleware.SendJSONError(w, http.StatusInternalServerError, "write admin_key failed", "server_error", "db_write_failed")
+		return
+	}
+	// 立即生效:只单独刷新管理凭证列表,不重新 LoadRuntimeConfig(那会覆盖其它字段)
+	setting.SetAdminKeys([]string{key}, "admin_key")
+	log.Printf("[settings] admin_key updated, runtime active (next request uses new admin credential)")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "admin_key_set": true, "admin_key_source": "admin_key"})
+}
+
 // SettingsCORSRequest 是 PUT /api/settings/cors 的 body。
-// 两个字段都可选(至少给一个):
+// 两个字段都可选(至少给一个),用指针区分"未传"和"传空串":
-//   - allow_all: true → 任意 Origin 都接受(*);设了之后 origins 失效
+//   - allow_all 指针: nil=未传(不动)  *true=开 *false=关
-//   - origins: 一行一个 origin,后端 trim + lower + 去末尾 /
+//   - origins  字符串: nil=未传(不动)  ""=传空串(清空)  "url1\nurl2"=覆盖
+//
+// 这样用户能精确表达意图(保留 / 改 / 清空),不会被 0/"" 歧义坑死。
 type SettingsCORSRequest struct {
-	AllowAll *bool  `json:"allow_all,omitempty"`
+	AllowAll *bool   `json:"allow_all,omitempty"`
-	Origins  string `json:"origins,omitempty"` // 也接受 string 数组(任一形式)
+	Origins  *string `json:"origins,omitempty"` // *string 区分"未传(nil)"和"传空串"
 }
 
 // SettingsCORSHandler PUT /api/settings/cors
-// 鉴权: RequireAdmin。改完立即更新 setting.CORS(进程内生效,跨域请求从下个请求开始按新配置)。
+// 鉴权: RequireAdmin。改完立即刷新 CORS(setting.SetCORS,进程内生效,跨域请求从下个请求开始按新配置)。
 // 同源豁免由 middleware/cors.go 的 isSameOrigin 处理,不在这里管。
 func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPut {
@@ -327,10 +400,9 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
-	if body.AllowAll == nil && trimAll(body.Origins) == "" && body.Origins != "" {
+	// 至少要给一个字段(allow_all 或 origins)
-		// 空 body 不算错误,用户可能是想"清空"(只清 origins 保留现状)
+	// 指针为 nil 表示"未传",不计入
-	}
+	if body.AllowAll == nil && body.Origins == nil {
-	if body.AllowAll == nil && body.Origins == "" {
 		middleware.SendJSONError(w, http.StatusBadRequest,
 			"at least one of allow_all / origins required",
 			"invalid_request_error", "no_fields")
@@ -341,22 +413,27 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 	if body.AllowAll != nil {
 		updates["cors_allow_all"] = boolToStr(*body.AllowAll)
 	}
-	if body.Origins != "" {
+	if body.Origins != nil {
-		// 校验每个 origin 至少像 http(s)://... (防止用户填空或填乱字符)
+		// *Origins == "" 表示用户要清空(保留 nil 表示"不动")
-		for _, line := range strings.Split(body.Origins, "\n") {
+		origins := *body.Origins
-			line = strings.TrimSpace(line)
+		if origins != "" {
-			if line == "" {
+			// 校验每个 origin 至少像 http(s)://... (防止用户填乱字符)
-				continue
+			for _, line := range strings.Split(origins, "\n") {
-			}
+				line = strings.TrimSpace(line)
-			low := strings.ToLower(line)
+				if line == "" {
-			if !strings.HasPrefix(low, "http://") && !strings.HasPrefix(low, "https://") {
+					continue
-				middleware.SendJSONError(w, http.StatusBadRequest,
+				}
-					fmt.Sprintf("invalid origin: %q (must start with http:// or https://)", line),
+				low := strings.ToLower(line)
-					"invalid_request_error", "origin_invalid")
+				if !strings.HasPrefix(low, "http://") && !strings.HasPrefix(low, "https://") {
-				return
+					middleware.SendJSONError(w, http.StatusBadRequest,
+						fmt.Sprintf("invalid origin: %q (must start with http:// or https://)", line),
+						"invalid_request_error", "origin_invalid")
+					return
+				}
 			}
 		}
-		updates["cors_origins"] = body.Origins
+		// 空串也能存(表示"清空");trim/lower 在 LoadRuntimeConfig 那侧做
+		updates["cors_origins"] = origins
 	}
 	if err := s.SettingsSetBatch(updates); err != nil {
 		log.Printf("[settings] cors set: %v", err)
@@ -364,7 +441,7 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// 立即刷新 setting.CORS,跨域请求从下个请求开始按新配置生效
+	// 立即刷新 CORS(setting.SetCORS),跨域请求从下个请求开始按新配置生效
 	// 复用 LoadRuntimeConfig 的解析逻辑(只取 cors 部分,避免覆盖其它运行时字段)
 	corsAllowAll, _ := s.SettingsGetBool("cors_allow_all", false)
 	originsStr := ""
@@ -372,22 +449,19 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
 		originsStr = v
 	}
 	if corsAllowAll {
-		setting.CORS.AllowAll = true
+		setting.SetCORS(true, nil)
-		setting.CORS.Origins = nil
 	} else if originsStr != "" {
-		setting.CORS.AllowAll = false
+		setting.SetCORS(false, setting.SplitOriginsForCORS(originsStr))
-		setting.CORS.Origins = setting.SplitOriginsForCORS(originsStr)
 	} else {
-		setting.CORS.AllowAll = false
+		setting.SetCORS(false, nil)
-		setting.CORS.Origins = nil
 	}
-	log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.CORS.AllowAll, originsStr)
+	log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.GetCORSAllowAll(), originsStr)
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	_ = json.NewEncoder(w).Encode(map[string]any{
-		"ok":           true,
+		"ok":          true,
-		"allow_all":    setting.CORS.AllowAll,
+		"allow_all":   setting.GetCORSAllowAll(),
-		"origins":      originsStr,
+		"origins":     originsStr,
-		"cors_active":  true,
+		"cors_active": true,
 	})
 }
 
@@ -404,18 +478,6 @@ func maskAPIKeyField(s string) string {
 	return s[:4] + "****" + s[len(s)-4:]
 }
 
-func trimAll(s string) string {
-	// 简单 trim 前后空白;不剥中间空格
-	out := s
-	for len(out) > 0 && (out[0] == ' ' || out[0] == '\t' || out[0] == '\n' || out[0] == '\r') {
-		out = out[1:]
-	}
-	for len(out) > 0 && (out[len(out)-1] == ' ' || out[len(out)-1] == '\t' || out[len(out)-1] == '\n' || out[len(out)-1] == '\r') {
-		out = out[:len(out)-1]
-	}
-	return out
-}
-
 func isValidFormat(s string) bool {
 	switch s {
 	case "mp3", "wav", "opus", "pcm", "aac", "flac", "":

controller/setup.go

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

controller/tts.go

@@ -40,7 +40,7 @@ func truncateForLog(b []byte, max int) string {
 }
 
 // resolveClientFormat 把 OpenAI 风格的 response_format 映射为最终输出格式;
-// 不识别或未指定时回退到 setting.TTSOptions.Format。
+// 不识别或未指定时回退到 setting.GetTTSOptions().Format。
 func resolveClientFormat(reqFmt string) string {
 	switch strings.ToLower(reqFmt) {
 	case "mp3", "wav", "opus", "pcm", "aac", "flac":
@@ -49,7 +49,7 @@ func resolveClientFormat(reqFmt string) string {
 		}
 		return strings.ToLower(reqFmt)
 	}
-	return setting.TTSOptions.Format
+	return setting.GetTTSOptions().Format
 }
 
 // OpenaiTTSHandler 是 /v1/audio/speech 的入口。
@@ -81,9 +81,9 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if setting.TTSConfigErr != nil {
+	if err := setting.GetTTSConfigErr(); err != nil {
 		log.Printf("警告: TTS配置未就绪,拒绝请求 - 错误=%v 路径=%s 客户端=%s",
-			setting.TTSConfigErr, r.URL.Path, middleware.GetClientIP(r))
+			err, r.URL.Path, middleware.GetClientIP(r))
 		middleware.SendJSONError(w, http.StatusServiceUnavailable, "TTS service configuration error. Please check environment variables and restart the service.", "configuration_error", "service_unavailable")
 		return
 	}
@@ -151,7 +151,7 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 
 	clientFormat := resolveClientFormat(req.ResponseFormat)
 
-	opts := setting.TTSOptions
+	opts := setting.GetTTSOptions()
 	opts.Text = req.Input
 
 	// M3: voice 路由
@@ -183,7 +183,7 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 				"voice lookup failed", "server_error", "db_read_failed")
 			return
 		}
-		// 覆盖 opts(API key / UID 保留自 setting.TTSOptions)
+		// 覆盖 opts(API key / UID 保留自 setting.GetTTSOptions 快照)
 		if !v.Enabled {
 			log.Printf("警告: voice=%q 已禁用 - 客户端=%s", req.Voice, middleware.GetClientIP(r))
 			middleware.SendJSONError(w, http.StatusForbidden,
@@ -197,10 +197,10 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 			opts.Model = v.Model
 		}
 		log.Printf("[tts] voice=%s 命中 (speaker=%s resource=%s model=%s) - 客户端=%s",
-			req.Voice, telemetry.MaskSpeaker(v.Speaker), v.ResourceID, v.Model, middleware.GetClientIP(r))
+			req.Voice, telemetry.MaskSpeaker(v.Speaker), telemetry.MaskResourceID(v.ResourceID), v.Model, middleware.GetClientIP(r))
 	}
 
-	ctx, cancel := context.WithTimeout(r.Context(), setting.TTSTimeout)
+	ctx, cancel := context.WithTimeout(r.Context(), setting.GetTTSTimeout())
 	defer cancel()
 
 	result, err := volcano.Synthesis(ctx, volcanoClient, opts, req.Input, clientFormat, speed, adapterRec)
@@ -232,7 +232,11 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Length", fmt.Sprintf("%d", len(result.AudioData)))
 	w.Header().Set("X-Request-Id", result.ReqID)
 	w.WriteHeader(http.StatusOK)
-	w.Write(result.AudioData)
+	if n, err := w.Write(result.AudioData); err != nil {
+		// header 已发,无法改 status code;只记日志供排查(常见:客户端中途断开 → broken pipe / connection reset)
+		log.Printf("警告: 响应写入失败 - 路径=%s 客户端=%s 已写=%d/%d 错误=%v",
+			r.URL.Path, middleware.GetClientIP(r), n, len(result.AudioData), err)
+	}
 }
 
 func classifyStatus(err error) string {
@@ -270,6 +274,21 @@ func contentTypeFor(format string) string {
 }
 
 // HealthHandler 暴露运行期状态;无鉴权。
+// HealthzHandler GET /healthz —— 匿名存活探针,**只回 200 与字面量 "ok"**。
+//
+// 为什么单独做这个:v0.3.0 把详细健康数据(/health)收口到管理鉴权之后,
+// 但 K8s liveness/readiness、Docker HEALTHCHECK、负载均衡健康检查默认都不带 Authorization。
+// 若把它们继续指向 /health,加鉴权后会一律 401,导致探针失败、Pod 反复重启。
+//
+// 因此本端点刻意**不返回任何字段**(无版本、无内存、无配置状态、无模式信息),
+// 只用于回答"进程还在不在"。运维要细节请走鉴权后的 /health。
+func HealthzHandler(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok"))
+}
+
 func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -278,7 +297,7 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	mode := installer.GetMode()
 	if mode == installer.ModeSetup {
 		w.WriteHeader(http.StatusOK) // 200,因为进程活着,只是还没初始化
-	} else if setting.TTSConfigErr != nil {
+	} else if setting.GetTTSConfigErr() != nil {
 		w.WriteHeader(http.StatusServiceUnavailable)
 	} else {
 		w.WriteHeader(http.StatusOK)
@@ -304,8 +323,8 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 		Memory:    collectMemorySnapshot(),
 		ConfigStatus: dto.ConfigStatusResponse{
 			AllRequiredVarsSet: allRequired,
-			ConfigError:        setting.TTSConfigErr != nil,
+			ConfigError:        setting.GetTTSConfigErr() != nil,
-			Error:              configErrorMessage(setting.TTSConfigErr),
+			Error:              configErrorMessage(setting.GetTTSConfigErr()),
 		},
 		Installed: mode == installer.ModeNormal,
 		Mode:      mode.String(),
@@ -313,7 +332,7 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(resp)
 }
 
-// configErrorMessage 把 setting.TTSConfigErr 安全地转成可对外暴露的字符串。
+// configErrorMessage 把运行时配置错误(setting.GetTTSConfigErr())安全地转成可对外暴露的字符串。
 // 仅在 normal 模式且有错时调用, error 为 nil 时返 "" (被 omitempty 跳过)。
 func configErrorMessage(err error) string {
 	if err == nil {

docs/IMPLEMENT_v0.3.0.md

@@ -0,0 +1,412 @@
+# Volcano-Engine-TTS-UI v0.3.0 阶段性实施步骤书
+
+> **文件名**：`IMPLEMENT_v0.3.0.md`
+> **基线**：`develop`
+> **版本目标**：v0.3.0 —— 路由鉴权架构升级、健康/指标端点收口、管理入口统一到 `/dashboard`
+> **关联文档**：[UPSTREAM_ADAPTER_GUIDE.md](UPSTREAM_ADAPTER_GUIDE.md)（上游适配器重构，与本改造正交，互不干扰）
+>
+> 本文是 v0.3.0 的**唯一实施依据**，由初版方案按实际代码基线校正而成。
+> 校正说明见 [附录 A](#附录-a与初版方案的差异)。
+
+---
+
+## 0. 改造目标
+
+| # | 目标 | 验收标准 |
+|---|---|---|
+| 1 | **收口健康/指标端点**：`/metrics`、`/health`、`/dashboard` 不再匿名可读 | 未携带管理凭证时不可读到任何健康数据 |
+| 2 | **补前置缺口**：`RequireAdmin` 在凭证未配置时不再静默放行 | 未配置凭证时管理接口拒绝访问，且启动期有明确信号 |
+| 3 | **权限隔离**：业务调用凭证不得访问管理接口 | 用 TTS 调用 key 访问 `/api/admin/*` 返回 401 |
+| 4 | 管理入口统一：`/admin` → `/dashboard`，旧路径 301 兼容 | 访问 `/admin` 301 到 `/dashboard` |
+| 5 | API 路由分层：`/api/public/*`、`/api/user/*`、`/api/admin/*` | 三条前缀各自挂对应中间件，`/api/user/*` 为桩 |
+| 6 | 存量管理接口迁移到 `/api/admin/*`，旧路径继续可用 | 新旧路径行为一致，老脚本零改动 |
+| 7 | 两套用量查询占位接口 | `/api/user/usage`（管理鉴权）、`/v1/dashboard/billing/usage`（Bearer） |
+| 8 | 文档 / 示例配置 / Docker 注释同步更新，标注 Breaking Change | README、`.env.example`、`docker-compose.yml`、CHANGELOG 一致 |
+| 9 | **不改动** `adapter/`、`store/` 核心业务模型，**不破坏** `/v1/audio/speech` | TTS 业务接口回归通过 |
+
+### 重要约束
+
+- v0.3.0 **仍是单用户模式**；`/api/user/*` 仅骨架 + 桩实现，完整多用户能力放 v0.4.0。
+- **不引入 Cookie 会话**（理由见 [附录 B](#附录-b为什么不做-cookie-会话)）。管理鉴权继续使用
+  `Authorization: Bearer <key>`，前端继续用 `sessionStorage` 保存凭证。
+- **每个阶段结束必须可编译、可运行、可本地回归**，拒绝大爆炸式一次性修改。
+
+---
+
+## 1. 现状基线（开工前必须知道的事实）
+
+本项目的真实鉴权现状与初版方案的假设**不同**，照着初版做会返工。以下是核对过代码的结论：
+
+| 事项 | 真实现状 | 代码位置 |
+|---|---|---|
+| 管理鉴权中间件 | **只有 `RequireAdmin`**，Bearer 请求头校验。**不存在 `AdminSessionMiddleware`** | `middleware/admin_auth.go:20` |
+| 凭证存储 | 前端 `sessionStorage['ttsAdminKey']`，**无 Cookie** | `router/admin-shell.js:10-15` |
+| 凭证来源 | 数据库 `auth_key` → 回退环境变量 `OPENAI_TTS_API_KEY` | `setting/config.go:384-392` |
+| 凭证复用 | **同一个 key 既登录后台、又调 TTS 接口**（本次要拆开） | `middleware/auth.go` + `middleware/admin_auth.go` |
+| 指标实现 | 自研 `telemetry` 包，**未引入 `prometheus/client_golang`**，无 `promhttp` | `router/router.go:136` |
+| 客户端 IP | 已有 `middleware.GetClientIP`，支持 XFF + `TRUSTED_PROXY_HOPS` | `middleware/ratelimit.go:196` |
+| CORS | 非白名单 Origin 在中间件层直接 403 | `middleware/cors.go:138-147` |
+
+### 1.1 匿名可读端点（本次要收口的全部）
+
+| 端点 | 泄漏内容 | 代码位置 |
+|---|---|---|
+| `GET /dashboard` | **HTML 看板，同时拉 `/health` + `/metrics`**，聚合度最高 | `router/router.go:120` |
+| `GET /metrics` | Prometheus 全量指标（流量、模型名、错误分布、计费字符数） | `router/router.go:136` |
+| `GET /health` | 版本 / commit / 运行时长 / 内存 / goroutine + 配置错误文本 | `router/router.go:119` |
+| `GET /api/setup/status` | normal 模式下仍返回 `{installed, mode}` | `router/router.go:75` |
+
+> `/api/setup/prefill` 在 normal 模式返回 404（handler 内自检），**不可达**，无需处理。
+
+### 1.2 已有但必须保留的机制
+
+- `InstallGuard`：安装模式下按白名单放行（`/setup`、`/api/setup`、`/health`、`/metrics`），
+  安装阶段无数据库、无凭证，**不得套用 `RequireAdmin`**。`middleware/installguard.go:19`
+- 现有 `/api/admin/metrics` 已有 `RequireAdmin`，返回同样的 Prometheus 文本（保留复用）。
+- 现有静态资源路由 `/admin/admin.css`、`/admin/admin-shell.js`（`router/router.go:90-97`），
+  迁移时必须同步处理，否则页面丢样式。
+
+---
+
+## 2. 分阶段实施
+
+### 阶段 1｜收紧 `RequireAdmin`（前置缺口，最小改动）
+
+**为什么先做这一步**：`RequireAdmin` 当前在凭证列表为空时**直接放行**（`middleware/admin_auth.go:29-33`）。
+不修这个，后面给 `/metrics`、`/health` 套 `RequireAdmin` **等于没套**。
+
+**改动范围**：`middleware/admin_auth.go`、`middleware/auth.go`、`setting/config.go`、`main.go`
+
+#### 1.1 空凭证不再放行
+
+将 `len(keys) == 0 → next.ServeHTTP` 改为拒绝 + 显式日志：
+
+```go
+keys := setting.GetAdminKeys()
+if len(keys) == 0 {
+    log.Printf("[admin_auth] 拒绝访问:未配置管理凭证(admin_key / auth_key 均为空) - 路径=%s", r.URL.Path)
+    denyAdmin(w, r)
+    return
+}
+```
+
+#### 1.2 新增独立 `admin_key`（权限隔离）
+
+- `store`：新增可选的设置项 `admin_key`（**无需数据库迁移**，`settings` 是键值表）。
+- `setting`：新增 `GetAdminKeys() []string`，取值优先级：
+
+  ```
+  admin_key（DB） → 回退 auth_key（DB） → 回退 OPENAI_TTS_API_KEY（env）
+  ```
+
+- `RequireAdmin` 改用 `GetAdminKeys()`；**`middleware.ValidateAPIKey`（`/v1/audio/speech` 用）保持只看 `auth_key`**。
+- 效果：配了 `admin_key` 后，业务调用凭证**无法**访问管理接口，隔离成立；不配则行为与旧版完全一致（向后兼容）。
+
+#### 1.3 启动期校验（fail-fast）
+
+在 `main.go` normal 模式分支加入：管理凭证为空时**拒绝启动**并打印清晰原因
+（与现有配置损坏 fail-fast 风格一致）。
+
+> ⚠️ **破坏性提示**：若你的部署目前未配置任何凭证，本阶段后服务将无法启动。
+> 这是刻意的——此前那种状态下管理接口是完全裸奔的。请先配好 `auth_key`（或 `admin_key`）再升级。
+
+#### 1.4 ✅ 阶段 1 回归
+
+- [ ] `go build ./... && go vet ./...` 通过
+- [ ] 配置 `auth_key` 后：`/api/admin/overview` 带正确 key 返回 200，错误 key 返回 401
+- [ ] 不配置任何凭证时启动：进程拒绝启动并给出明确日志
+- [ ] 配置独立 `admin_key` 后：用 `auth_key` 访问 `/api/admin/*` 返回 401
+- [ ] `/v1/audio/speech` 用 `auth_key` 调用**不受影响**
+
+---
+
+### 阶段 2｜收口健康 / 指标端点（本版本核心目标）
+
+**改动范围**：`router/router.go`、`controller/tts.go`、`middleware/`（新增 CIDR 白名单）、`setting/config.go`
+
+#### 2.1 `/health` 拆分为两个端点
+
+| 端点 | 鉴权 | 返回 |
+|---|---|---|
+| `GET /healthz` | **无鉴权** | 仅 `200` + 字面量 `ok`，**不含任何字段** |
+| `GET /health` | `RequireAdmin` | 现有完整 JSON（版本/内存/配置状态等） |
+
+> ⚠️ **`/healthz` 必须与 `/health` 鉴权在同一次改动内落地**。分开部署会出现探针空窗，
+> 导致 K8s liveness 失败、Pod 反复重启。
+
+> 📌 探针迁移提醒：若现有 K8s `livenessProbe` / `readinessProbe` / Docker `HEALTHCHECK`
+> 指向 `/health`，需同步改指 `/healthz`。README 中要写明。
+
+#### 2.2 `/metrics` 收口 + 可选内网白名单
+
+新环境变量 `METRICS_ALLOW_CIDR`（逗号分隔多个 CIDR）：
+
+- **已配置**：在根路径注册 `/metrics`，包裹 `MetricsIPAllowListMiddleware`；
+  非白名单 IP 返回 **404**（不返回 403，避免向扫描者确认端点存在）。
+- **未配置**：根路径 `/metrics` **完全不注册**，访问 404。
+- 两种情况都**始终**提供鉴权版 `GET /api/admin/metrics`（已存在，供面板使用）。
+
+中间件实现要点：复用 `middleware.GetClientIP(r)`（已处理 XFF / `TRUSTED_PROXY_HOPS`），
+用标准库 `net/netip` 解析 CIDR。
+
+> ⚠️ **Docker 环境**：`METRICS_ALLOW_CIDR` 必须填**容器内网网段**（如 `172.16.0.0/12`），
+> **不要填 `127.0.0.1/32`** —— 那是容器自身的回环，Prometheus 在宿主机或其他容器里进不来。
+
+#### 2.3 `/dashboard` 与 `/api/setup/status` 收口
+
+- `/dashboard`：套 `RequireAdmin`。它是本版本**单点泄漏最严重**的端点（一个 URL 暴露全部健康数据）。
+- `/api/setup/status`：套 `RequireAdmin`。
+- **前端状态提示**：`/dashboard` 的 HTML 外壳本身不敏感，前端登录判断逻辑保持现状
+  （`sessionStorage` 无 key → 显示登录视图）。**不在服务端做页面级跳转**，原因见 [附录 B](#附录-b为什么不做-cookie-会话)。
+
+#### 2.4 ✅ 阶段 2 回归
+
+- [ ] 未配置 `METRICS_ALLOW_CIDR`：根 `/metrics`、`/health` 返回 404
+- [ ] 配置 `METRICS_ALLOW_CIDR=127.0.0.1/32`：本机可访问根 `/metrics`，其他 IP 返回 404
+- [ ] `/healthz` 无鉴权可访问且**不含任何字段**
+- [ ] `/health` 无凭证返回 401，带管理凭证返回完整 JSON
+- [ ] `/dashboard` 无凭证返回 401
+- [ ] `/api/setup/status` 无凭证返回 401
+- [ ] 面板内 `/api/admin/metrics`、`/api/admin/health` 正常返回
+
+---
+
+### 阶段 3｜路由分层与路径迁移
+
+**改动范围**：`router/router.go`、`controller/`（新增两个桩 handler + 页面路由别名）
+
+#### 3.1 分层路由注册
+
+```go
+apiPublic := r.PathPrefix("/api/public").Subrouter()
+// 预留空壳，暂不注册业务
+
+apiUser := r.PathPrefix("/api/user").Subrouter()
+apiUser.Use(middleware.RequireAdmin)   // 单用户模式下与 admin 等价，v0.4.0 再分化
+
+apiAdmin := r.PathPrefix("/api/admin").Subrouter()
+apiAdmin.Use(middleware.RequireAdmin)
+```
+
+将现有管理 handler 挂到 `apiAdmin`（**复用 handler 本体，不改业务逻辑**）：
+
+| 旧路径 | 新路径 |
+|---|---|
+| `GET/POST /api/voices` | `GET/POST /api/admin/voices` |
+| `DELETE /api/voices/{name}` | `DELETE /api/admin/voices/{name}` |
+| `PATCH /api/voices/{name}/toggle` | `PATCH /api/admin/voices/{name}/toggle` |
+| `GET/PUT /api/settings` | `GET/PUT /api/admin/settings` |
+| `PUT /api/settings/api-key` | `PUT /api/admin/settings/api-key` |
+| `PUT /api/settings/auth-key` | `PUT /api/admin/settings/auth-key` |
+| `PUT /api/settings/cors` | `PUT /api/admin/settings/cors` |
+| `GET /api/admin/overview` | 位置不变 |
+| `GET /api/admin/metrics` | 位置不变 |
+
+#### 3.2 旧路径兼容：用**别名**，不要重定向
+
+**旧路径指向同一个 handler，不做 301/308 跳转。**
+
+理由（三者对比）：
+
+| 方案 | 问题 |
+|---|---|
+| 301 | 会把 POST/PUT/PATCH/DELETE **降级成 GET**（RFC 7231），且浏览器**永久缓存**，客户端察觉不到路径变化 |
+| 308 | 保留方法和请求体，比 301 好；但多一次往返，对非浏览器脚本仍是行为变化 |
+| **别名（采用）** | 两个路径直接可用，零往返、零破坏，老脚本完全无感 |
+
+旧路径在当前版本**保留**，并在代码注释标注"过渡期别名，未来版本移除"。
+
+#### 3.3 页面路由迁移
+
+```go
+// 新入口
+r.HandleFunc("/dashboard", middleware.RequireAdmin(serveAdmin(dashboardHTML))).Methods("GET")
+r.HandleFunc("/dashboard/login", serveAdmin(adminLoginHTML)).Methods("GET")
+r.HandleFunc("/dashboard/voices", middleware.RequireAdmin(serveAdmin(adminVoicesHTML))).Methods("GET")
+r.HandleFunc("/dashboard/settings", middleware.RequireAdmin(serveAdmin(adminSettingsHTML))).Methods("GET")
+
+// 静态资源：必须同步迁移，否则面板丢样式/脚本
+r.HandleFunc("/dashboard/admin.css", ...)      // 原 /admin/admin.css
+r.HandleFunc("/dashboard/admin-shell.js", ...) // 原 /admin/admin-shell.js
+
+// 旧入口 301 永久重定向（页面用 301 正确）
+r.HandleFunc("/admin", func(w http.ResponseWriter, r *http.Request) {
+    http.Redirect(w, r, "/dashboard", http.StatusMovedPermanently)
+}).Methods("GET")
+```
+
+前端同步改动（`router/*.html`、`admin-shell.js`）：
+
+- 页面间跳转与链接：`/admin` → `/dashboard`，`/admin/login` → `/dashboard/login` 等
+- API 调用地址迁移到 `/api/admin/*`
+- 静态资源引用 `/admin/admin.css` → `/dashboard/admin.css`（同理 `admin-shell.js`）
+- `admin-shell.js` 的 401 拦截逻辑改为跳 `/dashboard/login`
+
+> 📌 注意：`/dashboard` 原本是**服务状态预览页**（`router/health.html`）。迁入后该页面的定位
+> 变成"管理后台首页"，健康/指标数据改由 `/api/admin/health`、`/api/admin/metrics` 提供。
+> 若仍希望保留独立的只读状态页，请单独确认（本版本不提供匿名版本）。
+
+#### 3.4 桩接口
+
+| 端点 | 鉴权 | 行为 |
+|---|---|---|
+| `GET /api/user/usage` | `RequireAdmin` | 单用户模式返回全局用量统计（桩，v0.4.0 改为按用户过滤） |
+| `GET /v1/dashboard/billing/usage` | Bearer 业务 key | 返回用量统计，对齐 OpenAI 返回格式 |
+
+#### 3.5 ✅ 阶段 3 回归
+
+- [ ] `/admin` 301 跳 `/dashboard`；`/dashboard` 各页面与静态资源正常加载（无 404、无样式丢失）
+- [ ] 面板内音色增删改、全局设置、CORS 配置全部正常
+- [ ] 旧路径 `/api/voices`、`/api/settings` **直接可用**（不是重定向），行为与新路径一致
+- [ ] `GET /api/user/usage`、`GET /v1/dashboard/billing/usage` 正常返回
+- [ ] 用业务 Bearer key 访问 `/api/admin/*` 返回 401
+- [ ] 完整安装流程跑通，装完跳转 `/dashboard`
+
+---
+
+### 阶段 4｜文档、配置、发布
+
+**改动范围**：`README.md`、`.env.example`、`docker-compose.yml`、`CHANGELOG.md`
+
+1. **README.md**
+   - WebUI 入口改为 `/dashboard`；注明 `/admin` 为旧兼容重定向
+   - 端点表更新：`/metrics`、`/health` 默认 404；新增 `/healthz`、`METRICS_ALLOW_CIDR`、`admin_key` 说明
+   - 公网部署安全清单更新（整节重写，明确"哪些端点不鉴权、必须靠什么挡"）
+   - 探针迁移提醒：K8s / Docker HEALTHCHECK 改指 `/healthz`
+2. **`.env.example`**：新增 `METRICS_ALLOW_CIDR` 注释（含 Docker 网段警告）
+3. **`docker-compose.yml`**：`METRICS_ALLOW_CIDR` 注释示例
+4. **`CHANGELOG.md`**：v0.3.0 条目，明确列出 Breaking Change
+
+#### Release Note · Breaking Change 清单
+
+1. **`/metrics`、`/health`、`/dashboard` 不再匿名可读**。Prometheus 抓取请用
+   `/api/admin/metrics`（带 Bearer），或配置 `METRICS_ALLOW_CIDR`；
+   探针请改用 `/healthz`。
+2. **未配置任何凭证时服务拒绝启动**（此前管理接口完全裸奔）。
+3. **管理凭证与业务凭证可分离**：新增 `admin_key`；配了之后业务 key 无法访问管理接口。
+4. **管理接口迁移到 `/api/admin/*`**；旧路径保留为**别名（非重定向）**，未来版本移除。
+5. **管理入口迁移到 `/dashboard`**；`/admin` 301 永久重定向。
+
+---
+
+## 3. 阶段 5｜全量回归测试（发布前必须全部通过）
+
+> ⚠️ **本项目测试文件不入库**（`.gitignore` 的 `*_test.go`），CI 只能守住"编译 + vet"，
+> **守不住行为回归**。因此下面的手工回归是发布前的唯一防线，必须逐条执行并记录结果。
+
+### ✨ 安装流程
+1. 不设 `TTS_ADMIN_KEY` 启动 → 终端打印一次性密钥（带醒目警告）
+2. 不带密钥 `POST /api/setup` → 401；带密钥 → 安装成功
+3. 安装完成跳转 `/dashboard`；进程重启后旧一次性密钥失效
+4. 已安装状态访问 `/setup` → 自动跳 `/dashboard`
+
+### ✨ 管理面板
+5. 未登录访问 `/dashboard` → 显示登录视图；登录后完整可用
+6. 访问 `/admin` → 301 跳 `/dashboard`
+7. 音色 CRUD、全局设置、CORS 修改全部正常
+8. 仪表盘通过 `/api/admin/health`、`/api/admin/metrics` 渲染正常
+9. 用量面板读取 `/api/user/usage` 正常
+
+### ✨ 指标与健康端点
+10. 不配 `METRICS_ALLOW_CIDR` → 根 `/metrics`、`/health` 返回 404
+11. 配 `METRICS_ALLOW_CIDR=127.0.0.1/32` → 本机根路径可访问，其他 IP 404
+12. `/healthz` 匿名可访问且**响应体不含任何业务字段**
+
+### ✨ 业务接口
+13. `/v1/audio/speech` OpenAI TTS 合成完全正常
+14. `GET /v1/dashboard/billing/usage` 合法 key → 200；非法 key → 401
+15. 业务 Bearer key 访问 `/api/admin/*` → 401（隔离生效）
+
+### ✨ 存量兼容
+16. 旧管理接口路径`/api/voices`、`/api/settings` 直接可用，行为与新路径一致
+
+### ✨ 安全场景
+17. 未配置凭证时服务拒绝启动
+18. 匿名无法获取任何健康 / 指标数据
+19. 旧 `tts.db` 直接复用升级，**无需数据库迁移**
+
+### ✨ 本地自动化
+20. `go build ./... && go vet ./...` 通过
+21. `go test ./... -count=1` 全绿
+    （含抓出过 `VoiceList` 语义 bug 的那批集成测试，是本次改造最重要的安全网）
+
+---
+
+## 4. 发布 v0.3.0
+
+1. 阶段 5 全部通过；Docker 镜像构建测试通过
+2. `git tag v0.3.0` 并推送
+3. 创建 Release，粘贴 Release Notes，**明确列出 5 条 Breaking Change**
+4. 创建维护分支 `v0.3.x`，用于后续 bugfix 与安全补丁
+5. `develop` 继续迭代 v0.4.0；上游适配器重构可并行
+
+---
+
+## 5. v0.4.0 后续规划（仅规划，不在 v0.3.0 实现）
+
+v0.3.0 已把**路由分层**和**权限隔离**打好；v0.4.0 只需填充业务逻辑。
+
+1. `store` 新增 `users` 表，区分普通用户 / 管理员角色
+2. 引入真正的会话机制（此时才需要 Cookie + CSRF，或采用 Bearer-per-user）
+3. `/api/user/*` 从桩转真实业务：个人用量、个人 API 密钥管理、个人调用日志
+4. `/api/admin/*` 实现用户 CRUD、配额管理；音色归属绑定用户
+5. SPA 扩展个人中心、密钥管理页面
+6. `/v1/dashboard/billing/usage` 按 API-Key 归属过滤统计
+
+---
+
+## 6. 风险注意事项
+
+| # | 风险 | 对策 |
+|---|---|---|
+| 1 | **`/healthz` 与 `/health` 加鉴权分批上线** → 探针空窗、Pod 重启循环 | 必须同一批改动内落地 |
+| 2 | **未配凭证导致服务启动失败**（阶段 1 的破坏性结果） | 升级前先配 `auth_key`；README 与 Release Note 明确提示 |
+| 3 | Docker 内 `METRICS_ALLOW_CIDR` 填 `127.0.0.1/32` | 必须填容器内网网段 |
+| 4 | **禁止把 `RequireAdmin` 套到 `/setup`** | 安装阶段无数据库、无凭证，保留 `InstallGuard` |
+| 5 | 旧路径若用重定向会导致 POST 降级 / 客户端无感 | 采用**别名**，不重定向 |
+| 6 | 静态资源路由遗漏导致面板丢样式 | 迁移时同步 `/dashboard/admin.css`、`/dashboard/admin-shell.js` |
+| 7 | **CI 跑不到测试**（测试文件不入库） | 每阶段结束本地执行 `go test ./... -count=1` |
+| 8 | 误改 `adapter/`、`store/` 业务模型 | 本改造不涉及；改动仅限 router / middleware / controller / 前端 / 文档 |
+
+---
+
+## 附录 A｜与初版方案的差异
+
+| 初版方案 | 本版 | 原因 |
+|---|---|---|
+| 阶段 0 "重命名 `AdminSessionMiddleware`" | **删除该阶段** | 该中间件**不存在**；实为新建 Cookie 会话层，会把"低风险重构"变成破坏性变更 |
+| 新增 `UserSessionMiddleware` | **不做** | 没有会话机制；`/dashboard` 页面请求不带 `sessionStorage`，服务端无从判断登录态 |
+| 新增 `CSRFMiddleware` | **不做** | Bearer 认证免疫 CSRF（浏览器不会自动附带 `Authorization`）；CORS 已在中间件层 403 非白名单 Origin |
+| Cookie `HttpOnly` / `SameSite=Strict` | **不做** | 不使用 Cookie |
+| `promhttp.Handler()` | `metrics.Meter.Handler()` | 项目未引入 `prometheus/client_golang` |
+| `controller.AdminSPAPageHandler` / `AdminLoginPageHandler` | `serveAdmin(adminHTML)` 等 | 这两个 handler 不存在 |
+| 漏点只列 `/metrics`、`/health` | 补入 **`/dashboard`**、`/api/setup/status` | `/dashboard` 聚合度最高；实测确认这两个也匿名可达 |
+| 旧 API 路径 301 重定向 | **别名**，不重定向 | 301 会把 POST 降级为 GET 且被永久缓存 |
+| 未提静态资源路由 | 明确 `/dashboard/admin.css` 等 | 遗漏会导致面板丢样式 |
+| `RequireAdmin` 空凭证放行未处理 | **阶段 1 专门修复 + fail-fast** | 不修则后续所有鉴权改动形同虚设 |
+
+### 初版保留不变的部分
+
+分阶段 + 每阶段可编译可回归的原则、`InstallGuard` 保持不动、`/v1/dashboard/billing/usage`
+走 Bearer、`/api/public` 与 `/api/user` 留桩、Docker CIDR 网段警告、v0.4.0 规划、发布流程。
+
+---
+
+## 附录 B｜为什么不做 Cookie 会话
+
+1. **不解决问题**：目标是"健康数据不外泄"，用现有 `RequireAdmin` 即可 100% 达成，
+   不需要会话层。
+2. **服务端拿不到 SPA 登录态**：前端凭证存 `sessionStorage`，**不随请求发送**，
+   所以服务端无法判断 `/dashboard` 页面请求是否已登录。初版要的"未登录访问 `/dashboard`
+   自动跳登录页"在服务端**做不到**——除非引入 Cookie，而这正是初版的前提缺失之处。
+3. **CSRF 需求随之消失**：Cookie 才需要 CSRF 防护；Bearer + `sessionStorage` 天然免疫。
+   不做 Cookie 就不必实现 token 发放与轮换，也避开同源 SPA 下 `SameSite=Strict` 的坑。
+4. **破坏现有客户端**：现有用 `Authorization: Bearer` 调管理 API 的脚本会全部 401，
+   与"给外部脚本过渡期"的目标冲突。
+5. **真正的权限问题另有其解**：当前"一个 key 既是管理密码又是业务密钥"才是实质缺陷，
+   用新增可选 `admin_key` 即可分离，成本约 20 行，无需引入会话。
+
+---
+
+*文档版本：v2 · 校正基线：`develop` @ `49f57e4`（2026-10-04）*
+*初版：v1（外部产出）· 校正原因见附录 A*

docs/UI_HANDOFF.md

@@ -0,0 +1,343 @@
+# UI 外包 Handoff · 火山 TTS 管理后台
+
+> 历史文档。本文档描述的是**外包给 Codex 做视觉改造**那一次任务,目标是"现有功能完全不动, 只换皮"。
+>
+> ⚠️ **状态: 任务已结束, 且路线已变更。** 该任务之后, admin 后台由提交 `9245c13`
+> 自行重构成**多页 SPA**(见下面 §0.1),本文档正文里的"单文件 / 大小上限 / 改这两个 .html"
+> 等约束**均已失效**,保留仅为记录当时的交接内容与设计讨论。
+> 若要再做视觉改造,请以 §0.1 的当前文件结构为准。
+
+---
+
+## 0.1 当前真实结构(以此为准)
+
+admin 后台已从单文件拆分为多页面,共享一套 CSS/JS,由 `//go:embed` 逐条嵌入:
+
+| 文件 | 作用 | 大小 |
+|---|---|---|
+| `router/admin.html` | 后台外壳(导航 / 布局) | 5.5KB |
+| `router/admin-login.html` | 登录页 | 2.1KB |
+| `router/admin-voices.html` | 音色管理页 | 13.5KB |
+| `router/admin-settings.html` | 设置页 | 14.4KB |
+| `router/admin.css` | 共享样式(全部页面) | 20.2KB |
+| `router/admin-shell.js` | 共享脚本: axios 实例 / toast / 外壳挂载 / 401 拦截 | 7.1KB |
+| `router/setup.html` | 安装引导页(仍是单文件) | 24.0KB |
+
+- URL 路由(非 hash):`/admin` · `/admin/login` · `/admin/voices` · `/admin/settings`
+- 公共逻辑集中在 `admin-shell.js`,通过 `window.admin` 暴露
+  `{ http, getKey, setKey, clearKey, toast, mountShell, formatUptime, … }`
+- **已无"单文件 ≤ 35KB"这类约束**;新增页面请复用 `admin.css` + `admin-shell.js`,不要各写一套。
+
+---
+
+## 0. 任务概览(历史原文)
+
+| 项 | 说明 |
+|---|---|
+| 改的文件 | `router/admin.html`、`router/setup.html` |
+| 改的部分 | 视觉、布局、组件、交互模式（loading/empty/error/反馈）|
+| 不改的部分 | API 调用、状态管理逻辑、字段名、文案语义 |
+| 期望产物 | 改完后的两个 .html, 总大小 ≤ 64KB（admin ≤ 35KB, setup ≤ 15KB）|
+| 验收 | dev 起服, 浏览器走完所有流程无回归 + 视觉明显更好 |
+
+---
+
+## 1. 技术栈约束（历史原文；"单文件"部分已失效）
+
+| 项 | 现状 | 改动空间 |
+|---|---|---|
+| 构建 | **无构建步骤**（`//go:embed` 进 binary）| 不可改 |
+| Vue | 3.4 via `cdn.bootcdn.net` | 可换版本（保持 3.x 即可）|
+| HTTP | axios 1.6（集中在 `admin-shell.js`）| 可换（fetch / ky / 留 axios 都行）|
+| CSS | 手写, 走 CSS 变量, 集中在 `admin.css` | 可换 **Tailwind CDN / DaisyUI / Pico / 手写** 都行 |
+| 图标 | 暂无 | 可加 lucide / heroicons inline SVG / emoji |
+| 字体 | 系统默认 (`-apple-system, "PingFang SC"...`) | 可加 `Noto Sans SC` via Google Fonts, 但要评估大小 |
+| 路由 | 拆分后已改为 **URL 路由**（`/admin/voices` 等）,不再是 hash 三 tab | 保持 URL 路由 |
+
+**注意（历史约束,已不适用）**: 当时二进制大小敏感 —— admin.html 31.19KB / setup.html 13.01KB。拆分后 admin 侧总量约 63KB(分散在 6 个文件里,浏览器可分页只加载所需部分),embed 进 binary 后大小影响可接受。**仍然建议**: 不要无脑加 UI 库(Tailwind 全量 + DaisyUI 会显著增大 embed 体积);要加就加在 `admin.css` 一处,所有页面共享。
+
+---
+
+## 2. 路由 & 模式
+
+### 2.1 三个 URL
+- `GET /setup` → `router/setup.html`（安装模式才进得去）
+- `GET /admin` → `router/admin.html`（任何模式都返回 HTML, 鉴权由前端 JS 拦截）
+- `GET /` → 重定向到 `/setup` 或 `/admin`
+
+### 2.2 状态机（admin.html）
+
+```
+未登录 (无 sessionStorage 'ttsAdminKey')
+  ├─ 输入 key + 调 GET /api/admin/overview 验证
+  └─ 验证通过 → 写入 sessionStorage + 切到登录后视图
+
+已登录
+  ├─ 三个 tab: dashboard / voices / settings（hash 路由）
+  ├─ 调任意 API 返 401 → 清 sessionStorage + 回到登录页
+  └─ 改完自己 auth_key → 调 PUT /api/settings/auth-key 200 后清 sessionStorage
+```
+
+### 2.3 状态机（setup.html）
+
+```
+未提交: 表单 4 必填 + voices 至少 1 条
+  └─ onMounted 调 GET /api/setup/prefill 自动填默认值
+  └─ 提交 POST /api/setup, 成功后 location.href = '/admin'
+```
+
+---
+
+## 3. API 契约（前端用的全部）
+
+### 3.1 鉴权
+
+| 头 | 说明 |
+|---|---|
+| `Authorization: Bearer <key>` | 所有 /api/* 请求必带（除 /api/setup/*）|
+| 401 响应 | 清 sessionStorage `ttsAdminKey`, 回到登录页 |
+
+**axios 实例已配置**:
+```js
+const http = axios.create({ baseURL: '/api' });
+http.interceptors.request.use(c => {
+  if (apiKey.value) c.headers.Authorization = 'Bearer ' + apiKey.value;
+  return c;
+});
+http.interceptors.response.use(r => r, err => {
+  if (err.response && err.response.status === 401) {
+    sessionStorage.removeItem('ttsAdminKey');
+    apiKey.value = '';
+  }
+  return Promise.reject(err);
+});
+```
+
+### 3.2 端点
+
+| Method | Path | 请求 body | 响应 | 鉴权 |
+|---|---|---|---|---|
+| GET | `/api/setup/prefill` | — | `{ settings: {default_resource_id, default_speaker, default_format, sample_rate} }` | 否（仅 install 模式）|
+| POST | `/api/setup` | `{token, settings: {auth_key, api_key, default_resource_id, default_speaker, default_format, sample_rate}, voices: [{name, speaker, resource_id, model, language}]}` | `{ok, redirect, settings, voices}` | 否（仅 install 模式）|
+| GET | `/api/admin/overview` | — | `{mode, installed, db_path, lock_path, version, commit, uptime_seconds, start_time, voice_count, voice_enabled_count, memory: {goroutines, heap_alloc, heap_inuse}}` | 是 |
+| GET | `/api/admin/metrics` | — | Prometheus text | 是 |
+| GET | `/api/voices` | — | `{voices: [{ID, Name, Speaker, ResourceID, Model, Language, Description, Enabled, CreatedAt, UpdatedAt}]}` | 是 |
+| POST | `/api/voices` | `{name, speaker, resource_id, model, language?, description?}` | 创建的 voice 对象 | 是 |
+| DELETE | `/api/voices/{name}` | — | `{deleted, ok}` | 是 |
+| PATCH | `/api/voices/{name}/toggle` | `{enabled: bool}` | 更新后的 voice | 是 |
+| GET | `/api/settings` | — | 完整 settings 对象（见 3.3）| 是 |
+| PUT | `/api/settings` | 部分字段（`default_resource_id` / `default_speaker` / `default_format` / `sample_rate` / `model`）| `{ok, updated, updated_at}` | 是 |
+| PUT | `/api/settings/api-key` | `{api_key: string}` | `{ok}` | 是 |
+| PUT | `/api/settings/auth-key` | `{auth_key: string}` | `{ok}` | 是 |
+| PUT | `/api/settings/cors` | `{allow_all?: bool, origins?: string}` | `{ok, allow_all, origins, cors_active}` | 是 |
+
+### 3.3 GET /api/settings 完整响应
+
+```json
+{
+  "api_key": "volc****etup",       // 打码
+  "api_key_set": true,
+  "auth_key": "my-o****etup",       // 打码
+  "auth_key_set": true,
+  "cors_allow_all": false,
+  "cors_origins": "https://app.example.com\nhttps://other.com",
+  "cors_configured": true,          // banner 显示控制
+  "default_resource_id": "volc.megatts.icl",
+  "default_speaker": "qian",
+  "default_format": "mp3",
+  "sample_rate": 24000,
+  "model": "seed-tts-2.0-standard",
+  "model_type": 0,
+  "explicit_language": "",
+  "enable_subtitle": false,
+  "updated_at": "2026-08-29T16:07:49Z"
+}
+```
+
+### 3.4 错误响应格式
+
+所有错误（除 OpenAI 兼容的 /v1/audio/speech）用同一格式:
+```json
+{ "error": { "code": "bad_request", "message": "...", "type": "invalid_request_error" } }
+```
+
+前端用 `e.response?.data?.error?.message` 提取.
+
+---
+
+## 4. 字段语义（写文案 / placeholder 用）
+
+### 4.1 auth_key
+"OpenAI 鉴权 Key"
+- 客户端用这个 Key 调 `/v1/audio/speech`
+- 登录 `/admin` 也用这个 Key
+- 自定字符串, 不是火山给的, **完全自己造**
+- 例: `my-secret-key-2024`
+
+### 4.2 api_key
+"火山 TTS API Key" / "上游 API Key"
+- 调火山 v3 上游用的凭证
+- 从 https://console.volcengine.com/ 获取
+- 例: `5b4d7c2a-...`
+
+### 4.3 default_resource_id
+- 音色所属的计费资源 ID
+- `volc.megatts.default` 默认音色 / `volc.megatts.icl` 复刻音色
+
+### 4.4 default_speaker
+- 未传 `voice` 字段时用
+- 必须是"音色" tab 里已添加的 voice name
+
+### 4.5 voices 字段
+- `name`: 短英文 id, 唯一, 不可改
+- `speaker`: 火山给的 speaker id
+- `resource_id`: 同上 default_resource_id
+- `model`: `seed-tts-2.0-standard` (默认) / `seed-tts-2.0-expressive` / `seed-tts-2.0-clone`
+- `language`: ISO 639-1 (`zh` / `en` / `ja` 等)
+
+### 4.6 CORS origins
+- 一行一个 origin
+- 必须 `http://` 或 `https://` 开头
+- 末尾 `/` 自动 trim
+
+---
+
+## 5. 当前 UI 的具体问题（按痛感排序）
+
+### 5.1 admin.html
+| # | 问题 | 现状 | 期望 |
+|---|---|---|---|
+| 1 | **登录页太空** | 一个输入框 + 一个按钮 | 加 logo / 提示 / 服务名 / 安装状态提示 |
+| 2 | **dashboard 卡片平** | 4 个数字 + 路径文本, 无图标无图表 | 加 icon, 用 chart mini sparkline (uptime / memory)|
+| 3 | **voices 表格简陋** | 5 列 + 启停 switch + 删除 | 加排序/搜索/批量操作/分页/拖拽改顺序 |
+| 4 | **新增 voice 弹窗原始** | 6 个 input 堆叠 | 分组, 加 help text, 加示例值, 加实时校验 |
+| 5 | **设置页 1 长页** | 4 段串成 1 长 list | 分 tab/分卡片, 加描述/帮助链接/危险操作分离 |
+| 6 | **改 key 后无 feedback** | 改了直接清 session | 加 toast 通知 "Key 已更新, 请用新 Key 重新登录" |
+| 7 | **删除无 undo** | confirm 弹原生 confirm() | 加 inline 二次确认 / undo snackbar |
+| 8 | **loading 无** | 调 API 时按钮不变 | 加 spinner / disabled 状态 / 进度条 |
+| 9 | **error 无专门显示区** | 用 `actionErr.value` 全局串 | 用 toast / inline error / 错误码对照 |
+| 10 | **响应式差** | desktop only | 至少平板能用, 关键操作 (tab 切换) 移动端可点 |
+| 11 | **配色单调** | 1 个 cyan 强调色 | 加二级色, success/warning/danger 用得不够明显 |
+| 12 | **字体单薄** | 14px 全局 | 大字标题 24-32px, 重要数字 monospace 突出 |
+
+### 5.2 setup.html
+| # | 问题 | 现状 | 期望 |
+|---|---|---|---|
+| 1 | **4 字段加 voice 列表一锅烩** | 一长页 | 分步骤 (1.凭证 2.默认 3.音色 4.确认) |
+| 2 | **voice 行无复用 UI** | 自己手写的 row | drag-to-reorder + 复制/粘贴/从预置模板加 |
+| 3 | **无进度感** | 一个 "安装" 按钮 | 安装中显示进度 (写 settings → 写 voices → 写 lock) |
+| 4 | **无"安装后会发生什么"** | 提交后只跳 /admin | 加结果页: 装了什么 / 接下来去 admin 干啥 |
+| 5 | **无 reset** | 改了一锅填错没法批量重置 | "恢复默认值" 按钮 |
+| 6 | **移动端糟糕** | 1 长页 | 至少 step indicator 在窄屏可见 |
+
+### 5.3 共性问题
+| # | 问题 | 期望 |
+|---|---|---|
+| 1 | 无 dark/light toggle | 加 toggle, 默认跟随系统 |
+| 2 | 无键盘快捷键 | `/` 聚焦搜索, `Esc` 关弹窗, `Ctrl+S` 保存当前表单 |
+| 3 | 无国际化 | 默认 zh-CN, 可加 i18n 但不强制 |
+| 4 | 无 a11y 标签 | aria-label, focus ring, 键盘可达 |
+
+---
+
+## 6. 设计参考（建议风格, 不是强制)
+
+| 风格 | 适配场景 | 推荐度 |
+|---|---|---|
+| Linear / Vercel dashboard | 后台工具, dark mode 友好 | ⭐⭐⭐⭐⭐ |
+| Tailscale admin | 简洁, 卡片化, 信息密度高 | ⭐⭐⭐⭐ |
+| Coolify / CasaOS | 自托管, "家用服务器"感 | ⭐⭐⭐ |
+| shadcn/ui | 现代 React 风, 移植到 Vue 略费劲 | ⭐⭐⭐ (参考设计, 不直接用) |
+| Tailadmin | 通用 admin 模板, 选段借鉴 | ⭐⭐ |
+
+**主调色建议** (如果重做):
+- 背景: 深色 (`#0a0e1a`) 或浅色 (`#f8fafc`), 配 system pref
+- 强调色: cyan / indigo / emerald 之一
+- 字体: 标题用 Inter, 数字用 JetBrains Mono
+
+---
+
+## 7. 不要做的事
+
+- ❌ 改 API 路径 / 改字段名 / 改字段语义
+- ❌ 加任何状态管理库 (Pinia) — 单文件 setup() 够用
+- ❌ 加 webpack/vite — 必须保持单文件
+- ❌ 引大 UI 库 (Element Plus / Naive UI) — 单文件塞不下
+- ❌ 把 admin.html 和 setup.html 合并 — 它们是独立页面
+- ❌ 改 axios 实例的 baseURL 或 401 拦截逻辑
+- ❌ 改 hash 路由的 key 命名（`#dashboard` / `#voices` / `#settings`）
+- ❌ **不要把单文件架构当最终形态** — 这是最小可工作版本(MVP),看板有 `ui-arch-debt` 卡片记录拆分计划。Codex 改造时保持单文件以便本次走通,但**不要引入新依赖让单文件更难拆**。例如:不要把 axios 拦截器写得依赖 10 个全局 ref;不要让 CSS 选择器深嵌套到无法抽离。
+
+---
+
+## 8. 验收清单（已按拆分后的结构更新）
+
+改完回来, 我会逐项过:
+
+- [ ] `go build ./...` 通过
+- [ ] `go vet ./...` 通过
+- [ ] `go test ./... -count=1` 全绿
+- [ ] dev 起服后浏览器:
+  - [ ] `/setup` 流程能跑完
+  - [ ] `/admin` 登录 → dashboard → voices → settings → 增改删全通
+  - [ ] 改 auth_key 后自踢 → 重新登录 → 能用新 key
+  - [ ] CORS 未配时顶部 banner 出现, 配后消失
+  - [ ] 401 错误时自动跳回登录
+- [ ] 视觉: 跟现在的 admin 比有明显提升 (logo / 排版 / 颜色 / 反馈)
+- [ ] 至少在 1024px 宽度下好看
+- [ ] 没有 console error / 404
+- [ ] 新增页面复用了 `admin.css` + `admin-shell.js`,没有复制粘贴出第二套公共逻辑
+
+> 旧的"`admin.html` ≤ 35KB / `setup.html` ≤ 15KB"两条**已作废**:admin 已拆成多页,
+> 单文件大小不再是约束。
+
+---
+
+## 9. 回填方式（历史原文） / 当前做法
+
+历史原文:
+
+```
+1. 拿回 router/admin.html + router/setup.html
+2. 放到 D:\项目\Volcano-Engine-TTS-UI\router\
+3. 我 build + 测, 通过后 commit
+4. push, 服务器自动部署
+```
+
+拆分之后的做法:改动落在 §0.1 表格里对应的**具体文件**上(外壳/登录/音色/设置,以及共享的
+`admin.css` / `admin-shell.js`),不再有"两个 .html"这一说。改完在**项目里**跑:
+
+```
+go build ./...
+go vet ./...
+go test ./... -count=1
+```
+
+三条全过再 commit 到 `develop`。
+
+---
+
+## 10. 关联文件（不需要改, 但可读懂逻辑）
+
+- `controller/admin.go` — admin API 实现
+- `controller/settings.go` — settings API 实现
+- `controller/setup.go` — setup API 实现
+- `router/router.go` — Go 路由 + 挂载点（看 `//go:embed` 用法）
+- `router/admin-shell.js` — 共享 axios 实例 / toast / 外壳挂载（改交互先看这里）
+- `middleware/admin_auth.go` — RequireAdmin 实现（理解 401 怎么来）
+
+---
+
+## 11. 当前文件位置（已更新）
+
+| 文件 | 大小 |
+|---|---|
+| `router/admin.html` | 5.5KB |
+| `router/admin-login.html` | 2.1KB |
+| `router/admin-voices.html` | 13.5KB |
+| `router/admin-settings.html` | 14.4KB |
+| `router/admin.css` | 20.2KB |
+| `router/admin-shell.js` | 7.1KB |
+| `router/setup.html` | 24.0KB |
+
+`ui-handoff/` 目录里保留的是**改造前**的单文件副本与离线 mock 预览,仅供对照,不要回填。

docs/UPSTREAM_ADAPTER_GUIDE.md

@@ -0,0 +1,493 @@
+# 上游适配器开发指南
+
+> 面向对象:要为本项目接入**新上游 TTS 服务**的开发者(也包括未来的你)。
+> 阅读前提:知道 OpenAI `/v1/audio/speech` 的请求/响应形状,能读 Go。
+>
+> ⚠️ **本文档分两部分,请先看清区别**:
+> **第一部分「现状」描述的是代码里已经存在的东西**,可以直接照着读代码。
+> **第二部分「目标架构」是待实施的设计**,代码里**还不存在** ——
+> 里面的接口、表结构、目录都是提案,需要先按 §4 的分阶段计划落地。
+> 不要把第二部分的接口名当成现有 API 去调用。
+
+---
+
+## 1. 愿景与现状
+
+### 1.1 愿景
+
+把本服务做成**多渠道多上游聚合层**:对外始终是一个 OpenAI 兼容接口,
+对内可以挂火山、OpenAI、Azure、阿里云、自建 GPT-SoVITS / IndexTTS……等任意上游。
+调用方不需要知道音频是哪个厂商合成的 —— 换上游对客户端应当**透明**。
+
+### 1.2 现状(第一部分)
+
+目前**只有火山一个适配器**,且不是"插件式"的,而是**硬编码进主干**的。
+这一点必须说清楚,因为它决定了新上游不能"只写一个文件就完事"。
+
+```
+入口         controller/tts.go        OpenaiTTSHandler
+                 │
+                 │  opts := setting.GetTTSOptions()      ← 类型是 volcano.Options
+                 │  volcano.Synthesis(ctx, volcanoClient, opts, ...)   ← 直接调实现,无接口
+                 ▼
+适配器       adapter/volcano/         Options / Synthesis / ParseStream / UpstreamError
+                 ▲
+                 │  setting.LoadRuntimeConfig 直接构造 volcano.Options / volcano.Additions
+配置         setting/config.go
+```
+
+**关键事实**:主干里有一处 `import "…/adapter/volcano"`,不是注解式的,
+而是**类型级耦合**。所以"多上游"不是加文件,而是一次重构(见 §4)。
+
+当前只有火山适配器时,以下代码是合理的;接第二个上游时必须逐个处理,
+否则会出现"配置是火山的、路由是 OpenAI 的"这种错配。
+
+---
+
+## 2. 现有火山适配器契约(照此实现即可)
+
+新适配器要能替代火山适配器,就必须满足下面这些**已经被主干依赖**的契约。
+先读这一节,再读 §3 的接口设计。
+
+### 2.1 包的职责划分
+
+| 文件 | 职责 | 新适配器对应物 |
+|---|---|---|
+| `adapter/volcano/options.go` | 调用参数集合(`Options`)+ 上游扩展参数(`Additions`)+ `IsZero()` | provider 私有 opts |
+| `adapter/volcano/request.go` | `Options` → 上游请求体;`buildRequest` 做必填校验;`convertSpeedToSpeechRate` 做 OpenAI speed 换算 | 请求构造 |
+| `adapter/volcano/client.go` | 复用连接的 `*HTTPClient`(keep-alive 调优);`PostStream` 发流式请求 | 传输层 |
+| `adapter/volcano/synthesis.go` | **唯一入口** `Synthesis(...)`;编排 埋点 → 构造 → 发送 → 解析 → 收尾 | `Synthesize(...)` |
+| `adapter/volcano/response.go` | `ParseStream` 解析 NDJSON 流;`ParsedStream` 累计结果 | 响应解析 |
+| `adapter/volcano/errors.go` | `UpstreamError{Code,Message,Stage,Wrapped}` + `IsAuth()` | 错误类型 |
+| `adapter/volcano/audio.go` | `WrapWAVHeader` —— 上游只给 PCM 时本地拼标准 wav 头 | 格式收尾 |
+
+### 2.2 主干对适配器的硬性依赖(必须逐条满足)
+
+| # | 主干行为 | 位置 | 新适配器必须 |
+|---|---|---|---|
+| 1 | 用包级 `*HTTPClient` 发请求,连接复用 | `controller/tts.go:27,32` | 提供可复用的 client,不要每次 new |
+| 2 | 可用 `ctx` 控制超时 | `controller/tts.go:203` | `Synthesize` 必须接受 `context.Context` |
+| 3 | 埋点接口 **3 个方法** | `adapter/volcano/synthesis.go:20-24` | 见 §2.3 |
+| 4 | 错误按 `Stage` 分类成 status label | `controller/tts.go:242-256` | 错误必须携带阶段:`request`/`http`/`stream`/`wrap` |
+| 5 | 错误码进 metrics label | `metrics/metrics.go:160-172` | 非零 code 会被聚合成 `client`/`server`/`upstream` |
+| 6 | 返回结果结构 | `dto.SynthesisResult` | 见 §2.4 |
+| 7 | 上游不支持的输出格式要**降级** | `synthesis.go:63-65`、`README` 格式表 | 见 §2.5 |
+
+### 2.3 埋点接口(MetricsRecorder)
+
+适配器**不 import telemetry 包**,而是由主干注入一个接口实现
+(`controller/tts.go:28` 注入 `metrics.AdapterRecorder{}`)。这是刻意的解耦,新适配器请沿用。
+
+```go
+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)
+}
+```
+
+现状实现里 `speaker` 是**语料无关的上游音色 ID**,会被 `telemetry.SpeakerLabel`
+做 `sha1[:8]` 哈希后才当 label(隐私保护,见 `metrics/metrics.go:127`)。
+新适配器传自己的音色标识即可,主干不解释它的含义。
+
+`status` 的取值约定(沿用即可,聚合看板依赖它们):
+`ok` / `request_error` / `transport_error` / `http_<code>` / `stream_error` / `wrap_error`。
+
+### 2.4 返回结果(dto.SynthesisResult)
+
+```go
+type SynthesisResult struct {
+    AudioData  []byte        // 最终可直接回给客户端的音频字节(已收尾,如 wav 拼好头)
+    Format     string        // 真实输出格式,决定 Content-Type
+    SampleRate int
+    ReqID      string        // 回写 X-Request-Id,排障用
+    TextWords  int           // 上游计费字符数(取不到填 0)
+    Chunks     int
+    AudioBytes int
+    TTFB       time.Duration // 首字节耗时
+    Duration   time.Duration
+}
+```
+
+`Format` 必须是主干认识的取值(见 `controller/tts.go:258` `contentTypeFor`):
+`mp3` / `wav` / `pcm` / `ogg_opus`(别名 `opus`)。填别的会导致 Content-Type 错。
+
+### 2.5 格式降级规则(容易踩)
+
+客户端要的 `response_format` 和上游能给的格式**往往不一致**,必须显式降级:
+
+| 客户端要 | 火山做法 | 为什么 |
+|---|---|---|
+| `wav` | 上游请求 `pcm`,本地 `WrapWAVHeader` 拼头 | 流式 wav 每 chunk 带独立头,拼接即坏 |
+| `aac` / `flac` | **降级成 mp3**,Content-Type 报 `audio/mpeg` | 火山不支持 |
+| `opus` | 上游 `ogg_opus` | 命名差异 |
+
+新适配器同样要回答这个问题:**你要的格式上游给不了时,降级到什么?**
+并且必须在 `Format` 字段里如实回报真实格式,否则客户端拿到的是"声明 mp3 实际 pcm"。
+
+### 2.6 实测踩过的坑(上游协议层面)
+
+这些是火山适配器真实修过的 bug,接新上游时同类问题大概率复现:
+
+1. **事件分发必须白名单**:`ParseStream` 只把 `event == "sentence"` 或事件为空的帧
+   当音频,未知事件只记日志**绝不拼进音频**(`response.go:71-113`)。
+   早期实现把 `TTSSubtitle` 也当音频,导致音频流被污染。
+2. **结束帧要提前 break**:上游用 `code == 20000000` 表示流正常结束,收到后要
+   把剩余行读完再 break,否则连接不释放。
+3. **单行可能很长**:`scanner.Buffer` 上限要放大(火山设到 8MB),否则大 chunk 会 EOF。
+4. **所有音频帧 base64 解码失败要**返回错误,**不能跳过** —— 跳过等于静默产出半截音频。
+5. **一个字节音频都没收到要报错**,不能返回空切片当成功(`response.go:125-131`)。
+6. **错误响应体可能含换行**:直接拼进错误消息会伪造日志行,火山做了
+   `\n`/`\r` 转义(`synthesis.go:99-101`),新适配器照做。
+
+---
+
+## 3. 目标架构:Provider 抽象(待实施)
+
+以下代码**当前不存在**,是建议落地的设计。
+
+### 3.1 接口定义
+
+建议新增 `adapter/provider/provider.go`(新包,**不放在** `adapter/volcano` 里,
+避免主干继续依赖具体实现):
+
+```go
+// Provider 是一个上游 TTS 服务的统一抽象。
+// 实现者只需要关心:把我的能力说清楚、把一次合成做完。
+type Provider interface {
+    // Name 稳定标识,用于配置键、库表字段、metrics label。
+    // 约定全小写无空格:volcano / openai / azure / aliyun / gpt-sovits。
+    Name() string
+
+    // Capabilities 声明本适配器支持什么。
+    // 主干据此做校验与降级,不靠 if-else 猜实现。
+    Capabilities() Capabilities
+
+    // Synthesize 执行一次合成,阻塞到完成。
+    // 必须遵守:ctx 取消即返回;上游不支持 clientFormat 时按 Capabilities 降级,
+    // 并在 Result.Format 里如实回报真实格式。
+    Synthesize(ctx context.Context, req Request, mtr MetricsRecorder) (*dto.SynthesisResult, error)
+}
+
+type Capabilities struct {
+    // 上游原生能产出的格式;客户端要的格式不在其中时,主干负责降级或拒绝。
+    Formats []string
+    // 是否支持用倍率控制语速。不支持时主干忽略 speed 而不是报错。
+    Speed bool
+    // 是否按字符计费并回传用量(决定 UpstreamUsage 是否有意义)。
+    Usage bool
+    // 是否支持多音色路由。不支持时该 provider 只能配一个默认音色。
+    Voices bool
+    // 是否需要资源/部署/项目 ID 这类额外维度(火山需要,OpenAI 不需要)。
+    ExtraScopes bool
+}
+
+// Request 是主干交给适配器的、已归一化的合成请求。
+// 注意:这里刻意不出现任何厂商专属字段。
+type Request struct {
+    Text         string
+    VoiceKey     string            // voices 表的主键语义(对外 voice 名或上游音色 ID)
+    Model        string
+    Format       string            // 客户端期望格式(主干已归一化:mp3/wav/pcm/ogg_opus)
+    SampleRate   int
+    Speed        float64           // 1.0 = 原速
+    Language     string
+    Extra        map[string]string // 厂商专属配置,从 voices/settings 的 JSON 列读
+
+    // Credentials 由 provider 自己解释:
+    // 火山读 api_key + resource_id;OpenAI 只读 api_key。
+    Credentials Credentials
+}
+
+type Credentials struct {
+    APIKey string
+    // 厂商额外凭证/路由维度。火山: resource_id;Azure: region;自建: base_url。
+    Scope map[string]string
+}
+```
+
+### 3.2 注册表
+
+```go
+// adapter/provider/registry.go
+func Register(p Provider)        // 通常在包的 init() 里调用
+func Get(name string) (Provider, bool)
+func Names() []string            // admin UI 下拉框用
+```
+
+**要点**:注册要放在**主干之外**。建议 `main.go` 显式空导入:
+
+```go
+import (
+    _ "github.com/volcano-tts/tts-api/adapter/volcano"  // 注册 volcano
+    _ "github.com/volcano-tts/tts-api/adapter/openai"   // 注册 openai
+)
+```
+
+这样主干只依赖 `provider` 包,**新增上游不需要改主干任何一行** —— 这是本架构的核心收益,
+请务必守住。`controller/tts.go` 里不应再出现 `adapter/volcano`。
+
+---
+
+## 4. 分阶段实施计划
+
+**强烈建议按阶段做,每阶段结束都能编译、能跑、行为不变。**
+一次性重构"配置 + 路由 + 库表 + 前端 + metrics"五个面,几乎必然做出半成品。
+
+### 阶段 0 · 抽出接口,零行为变更(纯重构)
+
+目标:主干不再依赖具体实现,但**行为完全不变**,回归风险最低。
+
+- [ ] 新增 `adapter/provider` 包,放 `Provider` / `Capabilities` / `Request` / `Credentials` / `MetricsRecorder`
+- [ ] 让 `volcano` 包实现 `Provider`(本质是把 `Options` 包一层适配,`Synthesis` 改成方法)
+- [ ] `controller/tts.go`:把 `volcanoClient` + `volcano.Synthesis` 换成 `provider.Get(name).Synthesize`
+- [ ] `MetricsRecorder` 从 `adapter/volcano` **移出**到 `provider` 包(否则接口还是火山专属)
+- [ ] `setting.LoadRuntimeConfig` 暂时继续构造 `volcano.Options`,通过一个
+      「volcano provider 的配置映射函数」转成 `provider.Request`
+- [ ] 验收:`go build ./... && go vet ./... && go test ./... -count=1` 全绿,
+      且 `/v1/audio/speech` 行为与重构前逐字节一致(拿同一段文本对比音频长度与格式)
+
+> 这一阶段**不要**动库表、不要动前端。目标只有一个:主干里那行
+> `import adapter/volcano` 消失。
+
+### 阶段 1 · 数据结构:provider 维度入库
+
+> ⚠️ **先纠正一个常见误解:本项目的迁移框架其实没有接线。**
+> `store/migrate.go` 里定义了 `Migration` 结构体和 `migrations` 切片,但那个切片是
+> **空的**,`store/db.go` 的 `migrate()` 也从**不**读取它 —— 注释里写得很明白:
+> "本期 M0 阶段 schemaVersion=1,migrate() 在 db.go 内做基础建表,**未触发 migrations 调度**"。
+> 所以 `migrate()` 目前**只做 `CREATE TABLE IF NOT EXISTS`**,没有任何版本比较,
+> 对已存在的表**完全不做变更**。
+>
+> 还有一个既有瑕疵:`db.go:148-150` 的 `INSERT OR IGNORE INTO schema_version (version) VALUES (?)`
+> 语句里既没有字面量也没传参,绑定到 `?` 的是**零值**,所以表里实际写入的版本号是 **0**,
+> 不是常量 `schemaVersion`(=1)。做 v2 迁移时请一并修掉,否则版本判断从一开始就是错的。
+>
+> **结论**:给 `voices` 加列**不会**自动发生,你必须自己写 `ALTER TABLE`,
+> 并且在启动时能被重复执行而不报错(老库、新库都要能跑)。
+
+本阶段要做:
+
+- [ ] 在 `migrate()`(或新启用的迁移调度)里实现**幂等**加列:
+      先 `PRAGMA table_info(voices)` 查现有列,缺哪个 `ALTER TABLE ... ADD COLUMN` 哪个
+      (SQLite 的 `ADD COLUMN` 不支持 `IF NOT EXISTS`,重复执行会报错,必须先查)
+- [ ] `voices` 表加列(见 §5.1),老库回填 `provider='volcano'`
+- [ ] 修正 `schema_version` 写入零值的瑕疵,并写出真实版本号
+- [ ] 若确实要启用 `migrate.go` 的调度框架,则把 `schemaVersion`(db.go,`=1`)
+      与 `schemaVersionRequested`(migrate.go,`=1`)一并提升到 2;
+      注意 `installer/lock.go` 里的 `schemaVersion = "1"`(字符串)**是另一套东西**——
+      它写在 `installed.lock` 里做安装标记,与库表结构版本是两回事,
+      两者要一起提升就一起提升,不要只改一边造成语义分裂
+- [ ] `store.Voice` 结构体加字段 + JSON tag
+- [ ] `store.GetVoiceForTTS` 返回值扩展(见 §5.2),`setting.Store` 接口同步改
+- [ ] `cmd/dumpdb` 输出新列
+- [ ] 验收:**用一个装了老数据的 `tts.db`** 启动服务(不要用全新库测),
+      确认自动加列成功、数据不丢、`/v1/audio/speech` 仍可用;
+      再重启一次确认迁移幂等(第二次不报错)
+
+### 阶段 2 · 配置:按 provider 命名空间化
+
+现状是 `settings` 表用**扁平键**,且键名全是火山语义(`default_resource_id`、
+`default_speaker`、`model_type`…)。多上游后必须命名空间化。
+
+- [ ] 保留全局键:`auth_key` / `cors_*` / `timeout` / `default_provider`
+- [ ] 厂商专属键改为 `provider.<name>.<key>`,例如
+      `provider.volcano.api_key`、`provider.volcano.resource_id`、
+      `provider.openai.api_key`、`provider.openai.base_url`
+- [ ] `LoadRuntimeConfig` 只装配**当前 `default_provider`** 的 `Request`,
+      不再构造 `volcano.Options`
+- [ ] `setting.CheckEnvironmentVariables` / `LogStartupSummary` 去掉
+      `BYTEDANCE_TTS_*` 硬编码名,改成遍历 provider 的必填项(否则 `/health` 会误导运维)
+- [ ] 迁移:老键 `api_key` → `provider.volcano.api_key` 等,一次性搬完并保留旧键只读兜底一轮
+- [ ] 验收:除火山外没有任何 provider 时,服务行为仍与阶段 1 相同
+
+### 阶段 3 · 观测:metrics 加 provider 维度
+
+- [ ] `tts_upstream_total` / `tts_upstream_duration_seconds` / `tts_upstream_errors_total`
+      等**全部上游指标加 `provider` label**
+- [ ] `metrics.AdapterRecorder` 增加 provider 字段(构造时注入 name)
+- [ ] 仪表盘 PromQL 补 `by (provider)`
+- [ ] ⚠️ **破坏性变更**:加 label 会让现有告警规则里的
+      `tts_upstream_total{...}` 聚合口径变化,发布说明里要写明
+- [ ] 验收:`/metrics` 上能按 provider 拆分成功率与 P95
+
+### 阶段 4 · 管理界面:provider 选择与音色归属
+
+- [ ] `/setup` 向导第 1 步加"上游类型"选择,后续步骤按所选 provider 动态渲染字段
+      (火山显示 resource_id,**OpenAI 显示 base_url 且不显示 resource_id**)
+- [ ] `router/admin-voices.html` 新增/编辑音色时选 provider 与 model
+- [ ] `/api/voices` 的请求/响应加 `provider` 字段,`controller/admin.go` 校验
+      "provider 必须已注册",否则 400(不要留到合成时才 500)
+- [ ] 删除 provider 最后一个音色时的保护逻辑(现在的 `ErrInUse` 只管 `default_speaker`)
+- [ ] 验收:UI 上能并存火山与 OpenAI 音色,各自路由正确
+
+### 阶段 5 · 第二个真实适配器(OpenAI 兼容)
+
+**这一步才是对抽象的真正验收**。选 OpenAI 兼容上游(或其代理)最省事,因为
+本项目对外就是 OpenAI 形状 —— 可以直接验证"请求/响应穿透"是否正确。
+
+- [ ] 新建 `adapter/openai/`,只实现 §3.1 的接口
+- [ ] 全程**不改** `controller/` `setting/` `store/` 任何一行
+- [ ] 如果为了实现它而必须改主干,说明 §3.1 的抽象漏了维度 —— **回头修接口,而不是打补丁**
+- [ ] 验收:同一份 `voices` 配置里两个 provider 可同时服务,
+      客户端只看到 `voice` 名不同
+
+---
+
+## 5. 数据模型改动细节
+
+### 5.1 voices 表
+
+现状(真实 schema,`store/db.go:129-142`):
+
+```sql
+CREATE TABLE IF NOT EXISTS voices (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT NOT NULL UNIQUE,
+    speaker     TEXT NOT NULL,      -- 上游音色 ID
+    resource_id TEXT NOT NULL,      -- ← 火山专属概念,却写成 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'))
+);
+```
+
+**问题**:`resource_id` 是火山独有概念(决定模型版本与计费),却成了全表必填列。
+OpenAI 上游根本没有这个字段 —— 这正是"单上游假设"渗进数据模型的典型症状。
+
+建议改为:
+
+```sql
+ALTER TABLE voices ADD COLUMN provider TEXT NOT NULL DEFAULT 'volcano';
+ALTER TABLE voices ADD COLUMN vendor_params TEXT NOT NULL DEFAULT '{}';  -- JSON,厂商私有
+-- resource_id 保留但放宽为可空(或整体搬进 vendor_params,看迁移成本)
+```
+
+- `provider` 建索引:`CREATE INDEX idx_voices_provider ON voices(provider)`
+- `vendor_params` 存厂商私有键值(火山:`{"resource_id":"seed-icl-2.0","model_type":4}`),
+  主干**不解释**它的内容,原样交给对应 provider
+- 迁移:`UPDATE voices SET provider='volcano' WHERE provider IS NULL OR provider=''`
+
+### 5.2 GetVoiceForTTS 的签名
+
+现状(`setting/config.go:426-436`,刻意用 5 个返回值避免循环 import):
+
+```go
+GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error)
+```
+
+多上游后要扩成:
+
+```go
+// 返回该 voice 的 provider 名 + 厂商私有参数,主干据此把请求路由给对应适配器。
+GetVoiceForTTS(name string) (providerName, speakerID, model string, vendorParams map[string]string, found bool, err error)
+```
+
+**注意**:当年之所以不用 `(VoiceRef, error)`,是为了让 `store` 不 import `setting`
+(避免循环 import)。加字段时**别再引入新的结构体依赖**,继续用扁平返回值或
+定义在 `store` 包里的中性结构体。
+
+---
+
+## 6. 新增一个适配器的完整清单
+
+假设要加 `foo` 上游:
+
+**代码**
+
+1. `adapter/foo/foo.go` —— 实现 `provider.Provider`(`Name()` 返回 `"foo"`)
+2. `adapter/foo/request.go` —— `provider.Request` → foo 的 HTTP 请求体
+3. `adapter/foo/response.go` —— 解析 foo 的响应;严格遵守 §2.6 的 6 条协议纪律
+4. `adapter/foo/errors.go` —— 错误要带阶段,`Stage` 用统一枚举
+5. `adapter/foo/foo_test.go` —— 至少覆盖:正常流、未知事件不污染音频、空音频报错、
+   base64 解码失败报错、格式降级回报正确 `Format`、`ctx` 取消能及时返回
+   (测试文件按项目策略不入库,本地保留并在合并前手动跑)
+6. 在 `foo.go` 的 `init()` 里 `provider.Register(...)`
+7. `main.go` 加一行空导入
+
+**配置**
+
+8. 定义必填项清单(供 `/health` 与启动摘要显示),不要写死在前端
+9. 在 `/setup` 向导里加该 provider 的字段定义(阶段 4 之后是数据驱动,只需加配置)
+
+**验收**
+
+10. `go build ./... && go vet ./... && go test ./... -count=1` 全绿
+11. 起服 → `/setup` 选 foo → 填凭证 → 加一个音色 → `curl /v1/audio/speech` 出声
+12. 故意填错凭证 → 客户端应拿到明确的 4xx/5xx 与 `code`,日志里凭证是**打码**的
+13. 不支持的 `response_format` → 按 `Capabilities` 降级,且 Content-Type 与真实字节一致
+
+---
+
+## 7. 测试策略(注意本项目的特殊约束)
+
+**本项目测试文件不入库**(`.gitignore` 里的 `*_test.go`),
+测试保留在本地磁盘。这带来两个直接后果,必须知道:
+
+1. **CI 跑不到你的测试**。`.github/workflows/ci.yml` 里的 `go test` 步骤在干净克隆上
+   只会打印 `no test files` 然后通过 —— 它只能守住"编译 + vet"。
+   所以适配器测试**必须在本地跑过再合并**:
+   ```bash
+   go test ./... -count=1
+   ```
+2. **不要依赖测试文件来传递知识**。协议细节、踩坑记录要写进**代码注释**和本文档,
+   否则对下一个人(以及在 CI 里)等于不存在。
+
+适配器测试的**最小可用集合**(按 §2.6 的坑逐条覆盖):
+
+| 用例 | 断言 |
+|---|---|
+| 正常流 | 音频字节非空;`Chunks` / `TTFB` / `Format` 合理 |
+| 未知事件帧 | 不进入音频;不报错;不改变 `Chunks` |
+| 字幕帧 | 进 `Subtitles`,**不进** `AudioData` |
+| 全流无音频 | 返回错误,不是"成功 + 空字节" |
+| base64 损坏 | 返回错误,不是跳过继续 |
+| 超长单行(>1MB) | 不 EOF |
+| 上游 HTTP 4xx/5xx | 错误 `Stage == "http"`,携带 code |
+| `ctx` 取消 | 及时返回,不泄漏 goroutine |
+| 格式降级 | `Result.Format` 是真实格式,不是客户端要的格式 |
+
+---
+
+## 8. 反模式清单(明确不要做)
+
+- ❌ **不要在 `controller/` 里写 `switch providerName` 分发**。
+  分发只能走注册表,否则每加一个上游都要改主干,抽象就白做了。
+- ❌ **不要让 `provider` 包 import 任何具体适配器**。依赖方向永远是
+  `具体适配器 → provider 包 ← 主干`。
+- ❌ **不要在 `provider.Request` 里加厂商专属字段**(如 `ResourceID`)。
+  厂商私有参数一律走 `Credentials.Scope` / `Request.Extra` / `voices.vendor_params`。
+- ❌ **不要把上游返回的原始音频直接当结果返回而不收尾**。
+  PCM 要拼头,降级要如实回报 `Format`(见 §2.5)。
+- ❌ **不要静默跳过解析失败的帧**(§2.6 第 4 条)。
+- ❌ **不要在日志里打印明文凭证或音色 ID**。沿用
+  `telemetry.MaskSpeaker` / `MaskResourceID`,新适配器的私有敏感字段也要加等价打码。
+- ❌ **不要用一个 `settings` 键名承载多个 provider 的配置**。
+- ❌ **不要为了省事把 provider 名写进 `settings` 的扁平键里当"事实上的路由"**,
+  路由的唯一权威是 `voices.provider` 与 `default_provider`。
+
+---
+
+## 9. 关键文件索引
+
+| 关注点 | 文件 | 说明 |
+|---|---|---|
+| 请求入口 / 校验 / 路由 | `controller/tts.go` | `resolveClientFormat`、voice 查库、错误归一 |
+| 合成编排参考实现 | `adapter/volcano/synthesis.go` | 埋点顺序、格式降级、错误分阶段 |
+| 流解析参考实现 | `adapter/volcano/response.go` | 事件白名单、结束帧、base64 |
+| 传输层参考实现 | `adapter/volcano/client.go` | 连接复用、nil 安全 |
+| 配置装配 | `setting/config.go` | `LoadRuntimeConfig`、`setting.Store` 接口 |
+| 库表与迁移 | `store/db.go`、`store/migrate.go` | `schemaVersion`、`migrate()`(**迁移框架未接线,见阶段 1 警示**);`installer/lock.go` 的 `schemaVersion` 是另一套 |
+| 音色模型 | `store/voices.go` | `Voice`、`GetVoiceForTTS` |
+| 指标 | `metrics/metrics.go` | `AdapterRecorder`、`codeLabel` |
+| 结果类型 | `dto/tts.go` | `SynthesisResult`、`SubtitleEntry` |
+| 未来抽象落点 | `adapter/provider/` | **尚不存在,待阶段 0 创建** |
+
+---
+
+*文档版本:v1 · 对应代码基线:`develop` @ `ad342ec`(2026-10-03)*
+*本文「现状」部分与代码逐行核对过;「目标架构」为提案,实施时请同步更新本文档。*

main.go

@@ -35,6 +35,8 @@ func main() {
 	setting.InitAllConfigs()
 	metrics.Init()
 	middleware.InitRateLimiter()
+	// v0.3.0:根路径 /metrics 的内网白名单(未配置则根路径完全不注册)
+	middleware.InitMetricsAllowList()
 
 	// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
 	dbPath := ttsDBPath()
@@ -77,13 +79,29 @@ func main() {
 			}
 			log.Printf("[main][WARN] TTS 运行时配置加载失败 (setup mode, 需先 /setup): %v", err)
 		} else {
+			opts := setting.GetTTSOptions()
 			log.Printf("[main] TTS 运行时配置已加载(api_key=***, speaker=%s, resource=%s, format=%s)",
-				setting.TTSOptions.Speaker, setting.TTSOptions.ResourceID, setting.TTSOptions.Format)
+				telemetry.MaskSpeaker(opts.Speaker), telemetry.MaskResourceID(opts.ResourceID), opts.Format)
 		}
 	}
 
 	// 5) 启动摘要日志(此时 Auth.APIKeys 已是 DB 值,日志反映真实状态)
 	setting.LogStartupSummary()
+
+	// 5.1) v0.3.0 前置校验:normal 模式下必须有管理凭证。
+	// 为什么 fail-fast 而不是警告:mware.RequireAdmin 在凭证为空时**拒绝**访问
+	// (不再像 v0.3.0 之前那样放行)。若此处不拦住,服务会正常起来,
+	// 但 /dashboard 与所有 /api/admin/* 全部 401 —— 相当于把自己锁在门外。
+	// 宁可启动失败并打印明确原因,也不要起来一个进不去后台的实例。
+	if installer.GetMode() == installer.ModeNormal && len(setting.GetAdminKeys()) == 0 {
+		log.Printf("[main][FATAL] normal 模式未配置任何管理凭证:admin_key / auth_key / OPENAI_TTS_API_KEY 均为空。")
+		log.Printf("[main][FATAL] 管理接口(含 /dashboard)将全部返回 401,服务拒绝启动。")
+		log.Fatalf("no admin credential configured; set admin_key (or auth_key) before starting in normal mode")
+	}
+	if installer.GetMode() == installer.ModeNormal {
+		log.Printf("[main] 管理凭证来源: %s", setting.GetAdminKeySource())
+	}
+
 	log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
 
 	controller.InitController()
@@ -112,8 +130,13 @@ func main() {
 			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("Health check(匿名存活探针): http://localhost:%s/healthz", setting.Server.Port)
-		log.Printf("Metrics: http://localhost:%s/metrics", setting.Server.Port)
+		if middleware.MetricsAllowListConfigured() {
+			log.Printf("Metrics(内网白名单): http://localhost:%s/metrics", setting.Server.Port)
+		} else {
+			log.Printf("Metrics: 根路径 /metrics 未注册(未配置 METRICS_ALLOW_CIDR);请用鉴权版 /api/admin/metrics")
+		}
+		log.Printf("详细健康数据(鉴权): http://localhost:%s/api/admin/health", setting.Server.Port)
 
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			log.Fatalf("Server failed to start: %v", err)

middleware/admin_auth.go

@@ -9,14 +9,19 @@ import (
 	"github.com/volcano-tts/tts-api/setting"
 )
 
-// RequireAdmin 是 /admin 路由的鉴权中间件,复用 OPENAI_TTS_API_KEY。
+// RequireAdmin 是管理接口(/api/admin/*、/api/voices*、/api/settings*)的鉴权中间件。
-// 行为:
-//   - Auth.APIKeys 为空 → 所有请求放行(等同无鉴权)
-//   - Authorization 头 Bearer token 在列表中 → 放行
-//   - 其它 → 401 + JSON {error: 'unauthorized', code: 'admin_auth_failed'}
 //
-// 设计: 与现有 /v1/audio/speech 用的 setting.Auth 共享同一份 keys,
+// 凭证来源:setting.GetAdminKeys(),优先级 admin_key(DB) > auth_key(DB) > OPENAI_TTS_API_KEY(env)。
-// 用户只用管一个 env 变量(OPENAI_TTS_API_KEY)。
+// 与业务侧鉴权(middleware.ValidateAPIKey,只看 auth_key)分离,实现权限隔离:
+// 配置了独立 admin_key 后,业务调用方持有的 key 无法访问管理接口。
+//
+// 行为:
+//   - OPTIONS 预检 → 放行(浏览器预检不带 Authorization)
+//   - 未配置任何凭证 → **拒绝**(401)。这是刻意设计:v0.3.0 之前这里直接放行,
+//     导致管理接口在"没配 key"的部署上完全裸奔,并让后续给 /metrics、/health
+//     套本中间件的加固形同虚设。启动期已由 main.go 做 fail-fast 校验。
+//   - Authorization 头 Bearer token 命中凭证列表 → 放行
+//   - 其它 → 401 + JSON {error: {code: 'admin_auth_failed'}}
 func RequireAdmin(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		// 预检: 跨域/OPTIONS 直接放行(让浏览器能发 preflight)
@@ -25,10 +30,12 @@ func RequireAdmin(next http.Handler) http.Handler {
 			return
 		}
 
-		keys := setting.Auth.APIKeys
+		keys := setting.GetAdminKeys()
 		if len(keys) == 0 {
-			// 没配 admin key,等同无鉴权
+			// 没配管理凭证 → 拒绝(旧行为是放行,见上方注释说明为何改掉)
-			next.ServeHTTP(w, r)
+			log.Printf("[admin_auth] 拒绝:未配置管理凭证(admin_key/auth_key/OPENAI_TTS_API_KEY 均为空) - 路径=%s 客户端=%s",
+				r.URL.Path, GetClientIP(r))
+			denyAdmin(w, r)
 			return
 		}
 

middleware/admin_auth_test.go

@@ -0,0 +1,138 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/volcano-tts/tts-api/setting"
+)
+
+// okHandler 是被保护的假 handler。
+func okHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("ok"))
+	})
+}
+
+// TestRequireAdmin_EmptyCredentialDenies 凭证未配置时必须拒绝,不能放行。
+//
+// 这是 v0.3.0 阶段 1 的核心修复:v0.3.0 之前 len(keys)==0 直接放行,
+// 导致"没配 key"的部署上管理接口完全裸奔,也让后续给 /metrics、/health
+// 套 RequireAdmin 的加固形同虚设。
+func TestRequireAdmin_EmptyCredentialDenies(t *testing.T) {
+	t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
+	setting.SetAdminKeys(nil, "")
+
+	h := RequireAdmin(okHandler())
+
+	// 完全不带 Authorization
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, httptest.NewRequest("GET", "/api/admin/overview", nil))
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("无凭证 + 未配置 admin credential: code=%d, want 401", w.Code)
+	}
+
+	// 带任意 Bearer token 也必须拒绝(列表为空,没有合法 token 可言)
+	w2 := httptest.NewRecorder()
+	r2 := httptest.NewRequest("GET", "/api/admin/overview", nil)
+	r2.Header.Set("Authorization", "Bearer anything")
+	h.ServeHTTP(w2, r2)
+	if w2.Code != http.StatusUnauthorized {
+		t.Errorf("任意 token + 未配置 admin credential: code=%d, want 401", w2.Code)
+	}
+}
+
+// TestRequireAdmin_ConfiguredCredentialEnforced 配了凭证后:命中放行、错误拒绝。
+func TestRequireAdmin_ConfiguredCredentialEnforced(t *testing.T) {
+	t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
+	setting.SetAdminKeys([]string{"admin-secret"}, "admin_key")
+
+	h := RequireAdmin(okHandler())
+
+	cases := []struct {
+		name       string
+		authHeader string
+		wantStatus int
+	}{
+		{"正确凭证", "Bearer admin-secret", http.StatusOK},
+		{"错误凭证", "Bearer wrong-secret", http.StatusUnauthorized},
+		{"缺少 Bearer 前缀", "admin-secret", http.StatusUnauthorized},
+		{"空 Authorization", "", http.StatusUnauthorized},
+		{"仅空白 token", "Bearer    ", http.StatusUnauthorized},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/api/admin/overview", nil)
+			if c.authHeader != "" {
+				r.Header.Set("Authorization", c.authHeader)
+			}
+			h.ServeHTTP(w, r)
+			if w.Code != c.wantStatus {
+				t.Errorf("code=%d, want %d", w.Code, c.wantStatus)
+			}
+		})
+	}
+}
+
+// TestRequireAdmin_OptionsAlwaysAllowed OPTIONS 预检必须放行(浏览器预检不带 Authorization)。
+func TestRequireAdmin_OptionsAlwaysAllowed(t *testing.T) {
+	t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
+	setting.SetAdminKeys([]string{"admin-secret"}, "admin_key")
+
+	w := httptest.NewRecorder()
+	h := RequireAdmin(okHandler())
+	h.ServeHTTP(w, httptest.NewRequest("OPTIONS", "/api/admin/overview", nil))
+	if w.Code != http.StatusOK {
+		t.Errorf("OPTIONS: code=%d, want 200", w.Code)
+	}
+}
+
+// TestAdminAndBusinessCredentialIsolation 权限隔离:
+// 配置了独立 admin_key 后,业务凭证(auth_key)不得访问管理接口;
+// 未配置 admin_key 时回退,业务凭证仍可管理(向后兼容)。
+func TestAdminAndBusinessCredentialIsolation(t *testing.T) {
+	t.Cleanup(func() {
+		setting.SetAdminKeys(nil, "")
+		setting.SetAuthAPIKeys(nil)
+	})
+
+	const businessKey = "business-key"
+	const adminKey = "admin-key"
+
+	// 业务侧凭证固定为 businessKey(模拟 /v1/audio/speech 用的 key)
+	setting.SetAuthAPIKeys([]string{businessKey})
+
+	// --- 场景 A:配置了独立 admin_key(隔离生效) ---
+	setting.SetAdminKeys([]string{adminKey}, "admin_key")
+	h := RequireAdmin(okHandler())
+
+	wBiz := httptest.NewRecorder()
+	rBiz := httptest.NewRequest("GET", "/api/admin/overview", nil)
+	rBiz.Header.Set("Authorization", "Bearer "+businessKey)
+	h.ServeHTTP(wBiz, rBiz)
+	if wBiz.Code != http.StatusUnauthorized {
+		t.Errorf("隔离生效时,业务 key 访问管理接口: code=%d, want 401", wBiz.Code)
+	}
+
+	wAdmin := httptest.NewRecorder()
+	rAdmin := httptest.NewRequest("GET", "/api/admin/overview", nil)
+	rAdmin.Header.Set("Authorization", "Bearer "+adminKey)
+	h.ServeHTTP(wAdmin, rAdmin)
+	if wAdmin.Code != http.StatusOK {
+		t.Errorf("隔离生效时,admin_key 访问管理接口: code=%d, want 200", wAdmin.Code)
+	}
+
+	// --- 场景 B:未配置 admin_key,回退用业务凭证(向后兼容) ---
+	setting.SetAdminKeys([]string{businessKey}, "auth_key")
+
+	wFallback := httptest.NewRecorder()
+	rFallback := httptest.NewRequest("GET", "/api/admin/overview", nil)
+	rFallback.Header.Set("Authorization", "Bearer "+businessKey)
+	h.ServeHTTP(wFallback, rFallback)
+	if wFallback.Code != http.StatusOK {
+		t.Errorf("回退模式下,业务 key 应可管理: code=%d, want 200", wFallback.Code)
+	}
+}

middleware/auth.go

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

middleware/cors.go

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

middleware/metricsip.go

@@ -0,0 +1,103 @@
+package middleware
+
+import (
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+)
+
+// metricsAllowList 是 METRICS_ALLOW_CIDR 解析出的内网白名单。
+// 启动期由 InitMetricsAllowList 填充;运行期只读,无并发写。
+var metricsAllowList []*net.IPNet
+
+// metricsAllowConfigured 表示是否配置了非空的 METRICS_ALLOW_CIDR。
+// 决定根路径 /metrics、/health 是否注册(未配置则完全不注册,访问 404)。
+var metricsAllowConfigured bool
+
+// InitMetricsAllowList 解析 METRICS_ALLOW_CIDR,启动期调用一次。
+//
+// 格式:逗号分隔的 CIDR 列表,例如 "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"。
+// 也接受裸 IP(自动补 /32 或 /128),方便写 "127.0.0.1"。
+//
+// 为什么需要它:根路径 /metrics、/health 是给 Prometheus 抓取 / K8s 探针用的机器端点,
+// 让它们带 Bearer 会强制改抓取配置;用内网白名单更省事,且默认不暴露。
+//
+// 【重要】Docker 环境不要填 127.0.0.1/32 —— 那是容器自身的回环,
+// Prometheus 在宿主机或另一个容器里根本进不来。请填容器内网网段(如 172.16.0.0/12)。
+func InitMetricsAllowList() {
+	raw := strings.TrimSpace(os.Getenv("METRICS_ALLOW_CIDR"))
+	metricsAllowList = nil
+	metricsAllowConfigured = false
+	if raw == "" {
+		return
+	}
+
+	for _, part := range strings.Split(raw, ",") {
+		entry := strings.TrimSpace(part)
+		if entry == "" {
+			continue
+		}
+		// 裸 IP 自动补全掩码
+		if !strings.Contains(entry, "/") {
+			if ip := net.ParseIP(entry); ip != nil {
+				if ip.To4() != nil {
+					entry += "/32"
+				} else {
+					entry += "/128"
+				}
+			}
+		}
+		_, ipnet, err := net.ParseCIDR(entry)
+		if err != nil {
+			log.Printf("[metrics-ip] 忽略非法 CIDR 条目 %q: %v", part, err)
+			continue
+		}
+		metricsAllowList = append(metricsAllowList, ipnet)
+	}
+	metricsAllowConfigured = len(metricsAllowList) > 0
+	if metricsAllowConfigured {
+		log.Printf("[metrics-ip] METRICS_ALLOW_CIDR 已启用,根路径 /metrics 仅对 %d 个网段开放", len(metricsAllowList))
+	} else {
+		log.Printf("[metrics-ip] METRICS_ALLOW_CIDR 无有效条目,根路径 /metrics 将不注册")
+	}
+}
+
+// MetricsAllowListConfigured 报告是否配置了有效的白名单网段。
+// router 据此决定是否注册根路径 /metrics / /health。
+func MetricsAllowListConfigured() bool { return metricsAllowConfigured }
+
+// MetricsIPAllowList 只放行来源 IP 命中白名单的请求。
+//
+// 未命中返回 **404**(而不是 403):不向扫描者确认"这里存在一个只是你没权限的端点"。
+// 客户端 IP 取自 GetClientIP,它已处理 X-Forwarded-For 与 TRUSTED_PROXY_HOPS,
+// 所以反代后面的真实来源也能正确判定。
+func MetricsIPAllowList(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !ipAllowed(GetClientIP(r)) {
+			// 不打印每个被拒请求,避免扫描流量刷爆日志;只按需在 debug 下输出
+			http.NotFound(w, r)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// ipAllowed 判定客户端 IP 是否命中任一白名单网段。
+// 空 IP(解析失败)一律拒绝 —— 宁可拒绝也不能误放行。
+func ipAllowed(clientIP string) bool {
+	if clientIP == "" {
+		return false
+	}
+	ip := net.ParseIP(strings.TrimSpace(clientIP))
+	if ip == nil {
+		return false
+	}
+	for _, n := range metricsAllowList {
+		if n.Contains(ip) {
+			return true
+		}
+	}
+	return false
+}

middleware/metricsip_test.go

@@ -0,0 +1,143 @@
+package middleware
+
+import (
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// allowListFrom 把逗号分隔的 CIDR 串解析成白名单,供测试直接注入。
+func allowListFrom(t *testing.T, spec string) []*net.IPNet {
+	t.Helper()
+	var out []*net.IPNet
+	for _, part := range strings.Split(spec, ",") {
+		entry := strings.TrimSpace(part)
+		if entry == "" {
+			continue
+		}
+		_, n, err := net.ParseCIDR(entry)
+		if err != nil {
+			t.Fatalf("测试用例里的 CIDR 非法 %q: %v", entry, err)
+		}
+		out = append(out, n)
+	}
+	return out
+}
+
+// reqFrom 构造带指定来源地址的请求。
+func reqFrom(remoteAddr string) *http.Request {
+	r := httptest.NewRequest("GET", "/metrics", nil)
+	r.RemoteAddr = remoteAddr
+	return r
+}
+
+// TestIPAllowed 验证 CIDR 白名单判定:
+// 命中放行、未命中拒绝,解析失败的 IP 一律拒绝(宁可拒绝也不误放行)。
+func TestIPAllowed(t *testing.T) {
+	// 直接构造白名单,不依赖环境变量
+	metricsAllowList = allowListFrom(t, "127.0.0.1/32,10.0.0.0/8,172.16.0.0/12,::1/128")
+	metricsAllowConfigured = true
+	t.Cleanup(func() {
+		metricsAllowList = nil
+		metricsAllowConfigured = false
+	})
+
+	cases := []struct {
+		name string
+		ip   string
+		want bool
+	}{
+		{"本机 IPv4 命中 /32", "127.0.0.1", true},
+		{"10.x 命中 /8", "10.1.2.3", true},
+		{"172.16.x 命中 /12", "172.16.5.9", true},
+		{"172.31.x 仍在 /12 内", "172.31.255.254", true},
+		{"IPv6 回环命中 /128", "::1", true},
+		{"公网 IP 不在白名单", "8.8.8.8", false},
+		{"172.32.x 超出 /12 范围", "172.32.0.1", false},
+		{"192.168.x 未配置", "192.168.1.1", false},
+		{"空 IP 拒绝", "", false},
+		{"非法 IP 拒绝", "not-an-ip", false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := ipAllowed(c.ip); got != c.want {
+				t.Errorf("ipAllowed(%q) = %v, want %v", c.ip, got, c.want)
+			}
+		})
+	}
+}
+
+// TestIPAllowed_EmptyListRejectsAll 白名单为空时全部拒绝(未配置 = 不开放)。
+func TestIPAllowed_EmptyListRejectsAll(t *testing.T) {
+	metricsAllowList = nil
+	metricsAllowConfigured = false
+	t.Cleanup(func() {
+		metricsAllowList = nil
+		metricsAllowConfigured = false
+	})
+
+	if ipAllowed("127.0.0.1") {
+		t.Error("白名单为空时应拒绝所有 IP")
+	}
+}
+
+// TestMetricsIPAllowList_Scope 白名单内放行、白名单外 404。
+// 用 404 而不是 403,是为了不向扫描者确认"该端点存在,只是你没权限"。
+func TestMetricsIPAllowList_Scope(t *testing.T) {
+	metricsAllowList = allowListFrom(t, "10.0.0.0/8")
+	t.Cleanup(func() { metricsAllowList = nil })
+
+	h := MetricsIPAllowList(okHandler())
+
+	// 命中白名单 → 放行到 next
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, reqFrom("10.1.1.1:1234"))
+	if w.Code != http.StatusOK {
+		t.Errorf("白名单内来源: code=%d, want 200", w.Code)
+	}
+
+	// 白名单外(RFC 5737 文档地址)→ 404,且不应触达 next
+	w2 := httptest.NewRecorder()
+	h.ServeHTTP(w2, reqFrom("192.0.2.1:1234"))
+	if w2.Code != http.StatusNotFound {
+		t.Errorf("白名单外来源: code=%d, want 404", w2.Code)
+	}
+	if w2.Body.String() == "ok" {
+		t.Error("白名单外来源不应触达被保护的 handler")
+	}
+}
+
+// TestMetricsIPAllowList_XForwardedForSpoof 伪造 X-Forwarded-For 不能绕过白名单。
+//
+// GetClientIP 的启发式模式(trustedProxyHops==0,默认)从 XFF 链**尾部**取第一个
+// **公网** IP,刻意跳过私网跳 —— 这样攻击者无法用 "X-Forwarded-For: <内网IP>"
+// 把自己伪装成白名单来源。本测试锁死这个安全属性。
+func TestMetricsIPAllowList_XForwardedForSpoof(t *testing.T) {
+	metricsAllowList = allowListFrom(t, "10.0.0.0/8")
+	t.Cleanup(func() { metricsAllowList = nil })
+
+	h := MetricsIPAllowList(okHandler())
+
+	// 直连是私网(像反代),XFF 里塞一个内网 IP 想混进白名单
+	r := reqFrom("127.0.0.1:1234")
+	r.Header.Set("X-Forwarded-For", "10.9.9.9")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, r)
+
+	// 启发式模式会跳过私网跳、落到直连地址 127.0.0.1(不在 10.0.0.0/8)→ 404。
+	// 关键断言:伪造的内网 XFF **没有**让它通过。
+	if w.Code == http.StatusOK {
+		t.Errorf("伪造私网 XFF 不应绕过白名单: code=%d", w.Code)
+	}
+
+	// 反向对照:XFF 填公网 IP 时,GetClientIP 会采用它,同样不在白名单 → 404
+	r2 := reqFrom("127.0.0.1:1234")
+	r2.Header.Set("X-Forwarded-For", "8.8.8.8")
+	w2 := httptest.NewRecorder()
+	h.ServeHTTP(w2, r2)
+	if w2.Code != http.StatusNotFound {
+		t.Errorf("公网来源不在白名单: code=%d, want 404", w2.Code)
+	}
+}

middleware/ratelimit.go

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

router/admin-login.html

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

router/admin-settings.html

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

router/admin-shell.js

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

router/admin-voices.html

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

router/admin.css

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

router/router.go

@@ -21,6 +21,21 @@ var setupHTML []byte
 //go:embed admin.html
 var adminHTML []byte
 
+//go:embed admin-login.html
+var adminLoginHTML []byte
+
+//go:embed admin-voices.html
+var adminVoicesHTML []byte
+
+//go:embed admin-settings.html
+var adminSettingsHTML []byte
+
+//go:embed admin.css
+var adminCSS []byte
+
+//go:embed admin-shell.js
+var adminShellJS []byte
+
 // Setup 返回主路由。
 // 中间件顺序(由外向内):
 //   SecurityHeaders → InstallGuard → RateLimit → ConcurrencyLimit → Logger → handler
@@ -57,22 +72,38 @@ func Setup() *mux.Router {
 		w.Header().Set("Content-Type", "text/html; charset=utf-8")
 		_, _ = w.Write(setupHTML)
 	}).Methods("GET")
-	r.HandleFunc("/api/setup/status", controller.SetupStatusHandler).Methods("GET")
+	// v0.3.0:安装状态不再匿名暴露(原本 normal 模式下仍返回 {installed, mode})
+	r.Handle("/api/setup/status", middleware.RequireAdmin(http.HandlerFunc(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。
-	r.HandleFunc("/admin", func(w http.ResponseWriter, req *http.Request) {
+	//
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	// 拆分后 admin.html / admin-login.html / admin-voices.html / admin-settings.html
-		_, _ = w.Write(adminHTML)
+	// 各自独立,URL 路由切换;共享 admin.css + admin-shell.js 由 adminStatic 提供。
+	r.HandleFunc("/admin", serveAdmin(adminHTML)).Methods("GET")
+	r.HandleFunc("/admin/login", serveAdmin(adminLoginHTML)).Methods("GET")
+	r.HandleFunc("/admin/voices", serveAdmin(adminVoicesHTML)).Methods("GET")
+	r.HandleFunc("/admin/settings", serveAdmin(adminSettingsHTML)).Methods("GET")
+	// admin 静态资源
+	r.HandleFunc("/admin/admin.css", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/css; charset=utf-8")
+		_, _ = w.Write(adminCSS)
+	}).Methods("GET")
+	r.HandleFunc("/admin/admin-shell.js", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/javascript; charset=utf-8")
+		_, _ = w.Write(adminShellJS)
 	}).Methods("GET")
 
 	// /api/admin/overview (鉴权)
 	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")
+	// v0.3.0:详细健康数据的鉴权版(面板与运维用)。
+	// 与根路径 /health 的区别:这里始终注册且强制鉴权;根路径 /health 默认 404。
+	r.Handle("/api/admin/health", middleware.RequireAdmin(http.HandlerFunc(controller.HealthHandler))).Methods("GET")
 
 	// /api/voices 音色 CRUD (鉴权)
 	r.Handle("/api/voices", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoicesListHandler))).Methods("GET")
@@ -85,15 +116,28 @@ func Setup() *mux.Router {
 	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")
+	// v0.3.0: 管理凭证(admin_key)独立配置端点。
+	// 同时注册新旧两个路径:/api/admin/settings/admin-key 是阶段 3 分层后的正式路径,
+	// /api/settings/admin-key 属于旧前缀,保留为别名(与阶段 3 的别名策略一致)。
+	r.Handle("/api/admin/settings/admin-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAdminKeyHandler))).Methods("PUT")
+	r.Handle("/api/settings/admin-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAdminKeyHandler))).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) {
+	// v0.3.0 端点收口:
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	//   /healthz        匿名存活探针,只回 "ok"(K8s probe / Docker HEALTHCHECK 用)
-		_, _ = w.Write(dashboardHTML)
+	//   /health         详细健康数据,**鉴权**(原本匿名,会泄漏版本/内存/配置错误文本)
-	}).Methods("GET")
+	//   /dashboard      管理看板;**鉴权**(原本匿名,聚合了 /health + /metrics 的全部数据)
+	//   /api/admin/health 鉴权版详细健康数据(面板拉取用,风格与 /api/admin/* 一致)
+	//
+	// 注意 /health 的鉴权是"内容协商"式的(见 htmlAwareAdmin):
+	// 浏览器直接地址栏访问时返回登录页而不是 401,保持原有 UX;
+	// 非 HTML 请求(脚本/抓取)不带凭证一律 401。数据安全由 API 层保证。
+	r.HandleFunc("/healthz", controller.HealthzHandler).Methods("GET")
+	r.Handle("/health", middleware.RequireAdmin(http.HandlerFunc(controller.HealthHandler))).Methods("GET")
+	r.Handle("/dashboard", htmlAwareAdmin(serveAdmin(adminHTML))).Methods("GET")
 	r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
 		// 安装模式下,根路径跳 /setup
 		if installer.GetMode() == installer.ModeSetup {
@@ -104,13 +148,38 @@ func Setup() *mux.Router {
 		http.Redirect(w, req, "/admin", http.StatusFound)
 	}).Methods("GET")
 
-	// /metrics 不做鉴权(对齐 /health 策略),但仍然走 RateLimit / ConcurrencyLimit。
+	// 根路径 /metrics 与 /health 的机器访问:
-	// Prometheus 抓取不带 Origin,因此经过 CORS 中间件时会直接 pass-through。
+	//   - 配置了 METRICS_ALLOW_CIDR → 注册 /metrics,包裹内网白名单(非白名单返回 404)
-	r.Handle("/metrics", metrics.Meter.Handler()).Methods("GET")
+	//   - 未配置 → 根路径 /metrics **完全不注册**(访问 404),避免默认对外暴露
+	// /health 已在上面按鉴权注册,不再提供匿名版本。
+	if middleware.MetricsAllowListConfigured() {
+		r.Handle("/metrics", middleware.MetricsIPAllowList(metrics.Meter.Handler())).Methods("GET")
+	}
 
 	return r
 }
 
+// htmlAwareAdmin 给**浏览器直接访问的管理页面**套鉴权,但对 HTML 请求做内容协商:
+//
+//   - Accept 含 text/html(地址栏打开、点链接)→ 照常返回页面外壳。
+//     此时不做 401:因为前端登录态存在 sessionStorage,**不会随请求发送**,
+//     服务端无从判断是否已登录;强行 401 会让"打开 /dashboard 看到登录页"
+//     这一现有体验变成"打开 /dashboard 直接报错"。
+//     页面外壳本身不含任何数据,数据全部来自鉴权后的 /api/admin/* 接口。
+//   - 其它(脚本、curl、抓取工具)→ 强制 RequireAdmin,无凭证 401。
+//
+// 这样既堵住了"匿名抓取健康数据",又不破坏 SPA 的登录流程。
+func htmlAwareAdmin(html http.Handler) http.Handler {
+	guarded := middleware.RequireAdmin(html)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if acceptsHTML(r.Header.Get("Accept")) {
+			html.ServeHTTP(w, r)
+			return
+		}
+		guarded.ServeHTTP(w, r)
+	})
+}
+
 // acceptsHTML 在 router 包内复刻,middleware 包的版本未导出。
 // 用途:NotFoundHandler 判断浏览器 Accept。
 func acceptsHTML(accept string) bool {
@@ -132,3 +201,12 @@ func acceptsHTML(accept string) bool {
 	}
 	return false
 }
+
+// serveAdmin 返回一个把 embed 的 HTML bytes 以 text/html 写出的 handler。
+// 抽出来只为让 /admin/voices 等多条路由的注册保持单行,避免重复 4 段。
+func serveAdmin(body []byte) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write(body)
+	}
+}

setting/config.go

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

store/setup.go

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

store/voices.go

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

telemetry/counter.go

@@ -36,8 +36,12 @@ func newCounter(name, help string, labelNames []string) *Counter {
 func (c *Counter) Inc(labels Labels) { c.Add(1, labels) }
 
 // Add 累加 v(v 必须 >= 0)。
+//
+// 空接收者(nil *Counter)安全:未初始化的全局指标(如 metrics.Init() 尚未调用时
+// 的 metrics.UpstreamTotal)会被静默忽略,而不是 panic。
+// 这让"直接调用 handler"的测试/复用场景不会因为漏掉指标初始化而崩溃。
 func (c *Counter) Add(v float64, labels Labels) {
-	if v < 0 {
+	if c == nil || v < 0 {
 		return
 	}
 	child := c.getOrCreate(labels)

telemetry/gauge.go

@@ -33,7 +33,11 @@ func newGauge(name, help string, labelNames []string) *Gauge {
 }
 
 // Set 直接设置当前值。
+// 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
 func (g *Gauge) Set(v float64, labels Labels) {
+	if g == nil {
+		return
+	}
 	child := g.getOrCreate(labels)
 	child.bits.Store(float64bits(v))
 }
@@ -45,7 +49,11 @@ func (g *Gauge) Inc(labels Labels) { g.Add(1, labels) }
 func (g *Gauge) Dec(labels Labels) { g.Add(-1, labels) }
 
 // Add 累加 v(可负)。
+// 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
 func (g *Gauge) Add(v float64, labels Labels) {
+	if g == nil {
+		return
+	}
 	child := g.getOrCreate(labels)
 	for {
 		bits := child.bits.Load()

telemetry/histogram.go

@@ -47,7 +47,11 @@ func newHistogram(name, help string, buckets []float64, labelNames []string) *Hi
 }
 
 // Observe 记录一个观测值。
+// 空接收者(nil *Histogram)安全,见 Counter.Add 的说明。
 func (h *Histogram) Observe(v float64, labels Labels) {
+	if h == nil {
+		return
+	}
 	child := h.getOrCreate(labels)
 	for {
 		bits := child.sumBits.Load()

telemetry/labels.go

@@ -5,7 +5,12 @@
 //   - 零外部依赖,只使用标准库;
 //   - label key 在指标注册时锁定,运行期不可新增(避免 cardinality 爆炸);
 //   - 所有并发安全由实现保证,调用方无需加锁;
-//   - Meter 是高层入口,NoopMeter 用于测试。
+//   - Meter 是高层入口,NoopMeter 用于测试;
+//   - **空接收者安全**: 未初始化的 *Counter / *Gauge / *Histogram(即 nil 指针)
+//     上的 Inc/Add/Set/Observe 一律静默忽略,不 panic。
+//     这条约定是为 metrics 包的全局指标变量服务的 —— 它们默认为 nil,只有 main
+//     调用过 metrics.Init() 之后才有值;直接复用 handler 的场景(集成测试、
+//     未来做成库)不应该因为漏掉指标初始化而崩掉整个请求处理。
 package telemetry
 
 import (
@@ -41,14 +46,29 @@ func SpeakerLabel(s string) string {
 //   - 其它 → 前 4 + **** + 后 4 (保留前缀便于肉眼区分 "S_xx 开头" vs "BV001_...")
 // 例子: "S_G8tEKnaJ1" → "S_G8****naJ1"
 func MaskSpeaker(s string) string {
+	return maskWithAffix(s, "(未设置)")
+}
+
+// MaskResourceID 把火山 TTS 资源 ID 部分打码用于日志输出。
+// 资源 ID 同样属于用户付费/敏感资产(指向 V3 复刻项目),与 speaker 走同一规则。
+//   - 空 → "(未设置)"
+//   - 长度 ≤ 4 → 全打码
+//   - 其它 → 前 4 + **** + 后 4
+// 例子: "volc.megatts.icl" → "volc****.icl"; "seed-icl-2.0" → "seed****2.0"
+func MaskResourceID(s string) string {
+	return maskWithAffix(s, "(未设置)")
+}
+
+// maskWithAffix 共用的"前 4 + **** + 后 4"打码逻辑,空串返回 emptyLabel。
+func maskWithAffix(s, emptyLabel string) string {
 	if s == "" {
-		return "(未设置)"
+		return emptyLabel
 	}
 	if len(s) <= 4 {
 		return strings.Repeat("*", len(s))
 	}
 	// 找前 4 字符中第一个非 [A-Za-z0-9_] 字符做截断,避免截到奇怪位置
-	// (虽然火山 ID 实际都是 S_xxx 字母数字组合,这里保险)
+	// (虽然火山 ID 实际都是字母数字组合,这里保险)
 	prefix := s[:4]
 	suffix := s[len(s)-4:]
 	return prefix + "****" + suffix