fix: 安全加固（VUL-001~009）+ 构建版本注入 + 死代码清理' (#2 ) from develop into main

Reviewed-on: #2
chore: 删除 ratelimit_middleware.go.tmp 临时文件
2026-08-27 11:01:47 +08:00 · 2026-08-23 13:16:17 +08:00 · 2026-08-23 10:01:35 +08:00 · 2026-05-19 18:41:59 +08:00 · 2026-05-18 23:29:21 +08:00 · 2026-05-11 17:58:28 +08:00
23 changed files with 445 additions and 2156 deletions
@@ -4,9 +4,6 @@
 *.test
 *.out
 # Go test sources (prevent accidental commit; tests live outside the repo by policy)
 *_test.go
 # Editor / OS
 .vscode/
 .idea/
@@ -23,12 +20,3 @@ Thumbs.db
 # Local-only working notes (use task board for shared tracking)
 TODO.md
 # Release artifacts (build output)
 release/
 # Runtime database artifacts (created by M1 installer flow)
 tts.db
 tts.db-*
 tts.db.*
 installed.lock
@@ -25,7 +25,7 @@ RUN apk --no-cache add ca-certificates tzdata \
 WORKDIR /app
 COPY --from=builder /app/tts-api .
-# health.html 已通过 //go:embed 嵌入 binary,无需单独复制
+COPY --from=builder /app/health.html .
 RUN chown -R appuser:appgroup /app
@@ -1,391 +0,0 @@
 # 火山 TTS 聚合平台 · 项目书（v0.1）
 > 定位：个人自用（无甲方）· 单机部署 · 单二进制分发
 > 基线代码：Volcano-Engine-TTS-UI（develop 分支，Go，约 2900 行）
 ---
 ## 1. 项目概述
 ### 1.1 背景与动机
 现有 `Volcano-Engine-TTS-UI` 是一个"火山引擎 TTS v3 → OpenAI 兼容接口"的适配器，已具备 `/v1/audio/speech`、多格式输出、鉴权限流、Prometheus 观测等能力。当前存在三个核心问题：
 1. **配置全部堆在环境变量里**：API Key、资源 ID、音色、采样率……随音色增长会持续"溢出"，无法维护。
 2. **音色是静态的**：`voice`/`model` 请求字段被接收但忽略，只支持 env 里配死的单音色。
 3. **首次启动没有入口**：无 UI、无数据库，配置只能靠手写 env。
 ### 1.2 项目目标
 把该项目升级为**自用聚合平台**：
 - 用 **SQLite** 接管所有运行时可变配置（全局设置 + 音色库），环境变量只保留 3 个左右引导参数；
 - 提供**引导式安装 UI**：首次启动（未安装）进入 `/setup` 向导收集配置，写入数据库后即完成安装；
 - 采用 **lock 文件**作为安装状态判据，支持"损坏自动回退、可重置安装"；
 - `/v1/audio/speech` 的 `voice` 参数**按数据库路由**，实现多音色动态切换；
 - 保持**单二进制分发**（SQLite 用纯 Go 驱动，`//go:embed` 嵌入引导页）。
 ### 1.3 设计原则
 | 原则 | 说明 |
 |---|---|
 | 数据库为唯一配置源 | 运行时的全局参数、音色全部读库，不做"库 + env 双轨" |
 | 环境变量只做引导 | 仅保留 DB 路径、端口、初始化凭证 |
 | lock 是安装门卫 | 存在 = 已安装；不存在 = 安装模式；损坏 = 备份 + 删 lock + 回退 |
 | 损坏可自愈 | 库异常自动备份留档并回退安装模式，不裸奔 |
 | 先内核后 UI | 本期只做"引导页"（安装必需），完整管理后台后置 |
 ---
 ## 2. 需求范围
 ### 2.1 本期（MVP）范围
 | 编号 | 需求 | 说明 |
 |---|---|---|
 | R1 | SQLite 接入 | `modernc.org/sqlite`（纯 Go、无 CGO），自动建表、轻量迁移 |
 | R2 | 全局配置入库 | `settings` 表接管现有全部 TTS 全局环境变量 |
 | R3 | 音色库 | `voices` 表：name → speaker/resource_id/model/…，支持增删改查 |
 | R4 | 安装状态检测 | `installed.lock` 判据 + 启动判定流程 |
 | R5 | 引导式安装 UI | `/setup` 引导页（首次启动数据收集）+ `POST /api/setup` |
 | R6 | 安装模式路由守卫 | 未安装时全站只开放 `/setup`，其余返回 503/跳转 |
 | R7 | voice 动态路由 | `/v1/audio/speech` 按 `voice` 查库路由到火山 |
 | R8 | 音色管理 API | `GET/POST /api/voices`、`PUT/DELETE /api/voices/:id`（带鉴权） |
 | R9 | 损坏回退 | 库校验失败 → 备份 `.corrupt-<ts>` → 删 lock → 重新安装 |
 | R10 | 环境变量收敛 | 迁移后 env 仅剩：`TTS_DB_PATH`、`PORT`、初始化凭证 |
 ### 2.2 后置（不在本期）
 - 完整管理后台（音色列表/用量图表/配置管理）
 - 多服务商聚合（火山 / OpenAI / 微软统一适配）
 - 流式实时输出（SSE/WebSocket）
 - TTS 结果缓存、长文本自动分片、字幕透出
 - ASR 转写端点（`/v1/audio/transcriptions`）
 ---
 ## 3. 总体架构
 ```
 ┌───────────────────────────── 单二进制 tts-api ─────────────────────────────┐
 │                                                                              │
 │  main.go ── 启动：初始化 DB → 安装状态检测 → 加载配置 → 路由 → 监听            │
 │                                                                              │
 │  ┌────────────┐   ┌─────────────┐   ┌────────────────────────────────────┐   │
 │  │ installer/ │──▶│   store/    │   │             router/                │   │
 │  │ lock 检测  │   │ SQLite 访问 │   │  /setup(引导页·embed)  /api/setup  │   │
 │  │ 安装模式   │   │ settings    │   │  /api/voices*        /v1/audio/speech│ │
 │  └────────────┘   │ voices      │   │  /health /metrics /dashboard        │   │
 │                   └─────────────┘   └────────────────────────────────────┘   │
 │                                                                              │
 │  controller/ ── 语音合成(查库路由) · setup · voices CRUD                      │
 │  middleware/ ── 鉴权 · 限流 · 并发 · 安装守卫                                 │
 │  setting/    ── 仅保留引导参数(DB路径/端口/凭证) + 启动汇总                    │
 │  adapter/volcano/ ── 火山 v3 客户端（不改，仅入参来源变为 DB）                 │
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
 ---
 ## 4. 技术选型
 | 项 | 选型 | 理由 |
 |---|---|---|
 | 语言 | Go（沿用） | 现有项目基线，无迁移成本 |
 | 数据库 | SQLite（`modernc.org/sqlite`） | 纯 Go 无 CGO，保持 `CGO_ENABLED=0` 单二进制；单文件零运维 |
 | 前端 | Vue3 + axios（沿用 dashboard 技术栈） | 复用现有 `//go:embed` 模式，`setup.html` 嵌入二进制 |
 | 路由 | gorilla/mux（沿用） | 现有实现 |
 | 构建 | 保持单二进制 | `//go:embed` 内嵌引导页与监控页 |
 > 依赖注意：`modernc.org/sqlite` 体积较大（约 30-40MB 二进制），如介意可换 `mattn/go-sqlite3`（需 CGO，破坏单二进制），**本项目选前者**。
 ---
 ## 5. 数据模型设计
 ### 5.1 `settings` 表（全局配置）
 ```sql
 CREATE TABLE IF NOT EXISTS settings (
    key        TEXT PRIMARY KEY,      -- 配置键名
    value      TEXT NOT NULL,          -- 配置值（统一存字符串，读取时按需转换）
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 ```
 初始化后必填的键：
 | key | 说明 | 来源（原环境变量） |
 |---|---|---|
 | `api_key` | 火山 API Key | `BYTEDANCE_TTS_API_KEY` |
 | `default_resource_id` | 默认资源 ID | `BYTEDANCE_TTS_RESOURCE_ID` |
 | `default_speaker` | 默认音色 | `BYTEDANCE_TTS_SPEAKER` |
 | `initialized` | 安装完成标记 `"1"` | —（双保险，配合 lock） |
 可选键（读取时带默认值）：
 | key | 默认值 | 来源 |
 |---|---|---|
 | `default_format` | `mp3` | `BYTEDANCE_TTS_FORMAT` |
 | `sample_rate` | `24000` | `BYTEDANCE_TTS_SAMPLE_RATE` |
 | `timeout` | `30s` | `BYTEDANCE_TTS_TIMEOUT` |
 | `model` | 空 | `BYTEDANCE_TTS_MODEL` |
 | `model_type` | 空 | `BYTEDANCE_TTS_MODEL_TYPE` |
 | `explicit_language` | 空 | `BYTEDANCE_TTS_EXPLICIT_LANGUAGE` |
 | `enable_subtitle` | `false` | `BYTEDANCE_TTS_ENABLE_SUBTITLE` |
 > 迁移建议：首次安装时若检测到旧的对应环境变量仍存在，可作为引导页**预填默认值**（仅预填，不替代库），便于老用户平滑迁移。
 ### 5.2 `voices` 表（音色库）
 ```sql
 CREATE TABLE IF NOT EXISTS voices (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    name        TEXT NOT NULL UNIQUE,   -- 对外 voice 名，请求里 voice 字段查它
    speaker     TEXT NOT NULL,          -- 火山音色 ID（复刻音色以 S_ 开头）
    resource_id TEXT NOT NULL,          -- 对应火山资源 ID（决定计费/模型族）
    model       TEXT DEFAULT '',        -- 子模型 seed-tts-2.0-standard / -expressive
    language    TEXT DEFAULT '',        -- 显式语种（可选）
    description TEXT DEFAULT '',        -- 备注
    enabled     INTEGER NOT NULL DEFAULT 1,  -- 0/1 启用
    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_voices_name ON voices(name);
 ```
 > 默认音色：`settings.default_speaker` 表示请求**未传 voice** 时用的音色；也可以约定默认 voice 名为 `default` 的行，二选一，建议用 settings 字段（更直观）。
 ---
 ## 6. 安装与启动流程设计
 ### 6.1 lock 判据
 - lock 文件：`<DB目录>/installed.lock`（与 `tts.db` 同目录）。
 - **存在 = 已成功完成过安装**；不存在 = 未安装。
 - lock 内容：一行文本 `version <版本号> <初始化时间>`，便于未来判断是否需要重装/迁移。
 - 写入时机：**先写库、后写 lock**（`/api/setup` 成功后、且通过完整性校验后才原子创建 lock），避免"lock 在、库是半成品"。
 - **不用 `.db` 文件是否存在作为安装判据**（建表会自动创建 db 文件，无法区分"从未安装"和"已安装"）。
 ### 6.2 启动判定流程
 ```
 main 启动
  ├─ 解析引导环境变量（TTS_DB_PATH / PORT / 初始化凭证）
  ├─ store.Open()（打开/创建 SQLite，自动建表）
  │
  ├─ installed.lock 不存在？
  │    └─ YES → 进入【安装模式】：仅开放 /setup（静态资源 + 引导页 + POST /api/setup）
  │            其余路由（/v1/audio/speech、/api/voices 等）→ 503 + 跳转 /setup
  │    └─ NO  → 尝试读库 + PRAGMA integrity_check
  │              ├─ 通过 → 加载 settings/voices 到内存缓存 → 【正常模式】
  │              └─ 失败 → 备份 tts.db → tts.db.corrupt-<时间戳>
  │                        → 删除 installed.lock → 进入【安装模式】
  │
  └─ 打印启动摘要（模式 / DB路径 / lock状态 / 音色数）
 ```
 ### 6.3 损坏回退规则
 1. 只在 lock 存在但库打不开 / `integrity_check` 失败时触发回退；
 2. **先备份**：损坏的 `.db` 改名 `tts.db.corrupt-<ts>` 留档，不直接删除；
 3. 删除 `installed.lock`，进入安装模式；
 4. 日志明确打印回退原因（文件损坏 / 权限 / 磁盘 / 版本等），便于排查；
 5. 回退后用户重新走 `/setup` 即可恢复。
 ### 6.4 setup 劫持防护（必须）
 安装模式是"谁先访问谁配置"，公网暴露时存在被抢先初始化的风险。防护方案（至少一项）：
 - **A（推荐）初始化凭证**：启动时打印一次性 setup token（或从环境变量 `TTS_ADMIN_KEY` 指定），引导页提交时必须带 token，校验通过才写入；
 - **B 回环限制**：安装模式下 `/setup` 仅允许本机回环地址访问（`127.0.0.1`），初始化完成后即失效；
 - 二者可叠加。初始化完成后 `/api/setup` 永久关闭。
 ---
 ## 7. 接口设计
 ### 7.1 安装相关
 | 方法 | 路径 | 说明 | 鉴权 |
 |---|---|---|---|
 | GET | `/setup` | 引导页 HTML（`//go:embed`） | 安装模式开放 |
 | GET | `/api/setup/status` | 返回 `{installed: bool}`，供引导页判断 | 无 |
 | POST | `/api/setup` | 提交初始配置（全局 + 音色列表 + token）→ 写库 → 写 lock | 初始化凭证 |
 `POST /api/setup` 请求体示例：
 ```json
 {
  "token": "一次性凭证",
  "settings": {
    "api_key": "xxx",
    "default_resource_id": "volc.megatts.default",
    "default_speaker": "zh_female_qingxin",
    "default_format": "mp3",
    "sample_rate": 24000
  },
  "voices": [
    { "name": "qian",  "speaker": "S_xxx", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-standard" },
    { "name": "xun",   "speaker": "S_yyy", "resource_id": "volc.megatts.icl", "model": "seed-tts-2.0-expressive" }
  ]
 }
 ```
 响应：`200 {ok:true, message:"installed"}` 或 `400/401/409`。
 ### 7.2 音色管理（正常模式）
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | GET | `/api/voices` | 列表（可分页/过滤 enabled） |
 | POST | `/api/voices` | 新增音色（name 唯一冲突返回 409） |
 | PUT | `/api/voices/:id` | 更新音色 |
 | DELETE | `/api/voices/:id` | 删除音色（`default_speaker` 引用的音色禁止删除） |
 鉴权：复用现有 `OPENAI_TTS_API_KEY`（Bearer）。若安装后用户未配置管理 Key，可提示在 settings 中配置。
 ### 7.3 语音合成（改造点）
 `/v1/audio/speech` 改造逻辑：
 ```
 收到请求
  ├─ voice 为空 → 用 settings.default_speaker（无默认 → 400 "no default voice"）
  ├─ voice 非空 → 查 voices 表
  │    ├─ 命中 → 用该行 speaker/resource_id/model/language 覆盖 opts
  │    └─ 未命中 → 400 "unknown voice: <name>"
  ├─ model 非空 → 查库/映射（本期：model 仅校验长度，不做映射，或按 settings 默认）
  └─ 其余逻辑不变（格式解析、speed、鉴权、限流、埋点）
 ```
 ### 7.4 现有端点（不变）
 `/health`、`/metrics`、`/dashboard`、`/` 行为保持；但**安装模式下**除 `/setup` 外统一返回 503（`/health` 可返回 `installed:false` 便于部署探针识别未初始化）。
 ---
 ## 8. 模块划分与代码改动清单
 ### 8.1 新增包
 | 包 | 职责 | 关键文件 |
 |---|---|---|
 | `store/` | SQLite 访问层：打开/建表/迁移、settings CRUD、voices CRUD、integrity_check | `db.go`、`settings.go`、`voices.go`、`migrate.go` |
 | `installer/` | 安装状态：lock 检测/创建/删除、安装模式判定、损坏回退 | `lock.go`、`bootstrap.go` |
 ### 8.2 改造文件
 | 文件 | 改动 |
 |---|---|
 | `router/router.go` | 新增 `/setup`、`/api/setup/*`、`/api/voices`；安装模式路由守卫 |
 | `controller/` | 新增 `setup.go`（安装提交）、`voices.go`（CRUD）；改造 `tts.go`（voice 查库路由） |
 | `middleware/` | 新增 `installguard.go`（安装模式拦截，未安装非 `/setup` → 503） |
 | `setting/config.go` | 收敛：仅读 `TTS_DB_PATH`、`PORT`、初始化凭证；启动汇总展示"模式/lock/音色数" |
 | `main.go` | 启动流程：初始化 DB → 安装检测 → 模式分支 |
 | `router/setup.html` | 新增引导页（Vue3 + axios，`//go:embed`） |
 | `go.mod` | 新增 `modernc.org/sqlite` |
 | `.env.example` / `README.md` / `docker-compose.yml` | 更新为新的引导参数与首次安装说明 |
 ### 8.3 环境变量收敛表
 **迁移前（现状，会持续膨胀）：**
 ```
 BYTEDANCE_TTS_API_KEY
 BYTEDANCE_TTS_RESOURCE_ID
 BYTEDANCE_TTS_SPEAKER
 BYTEDANCE_TTS_FORMAT
 BYTEDANCE_TTS_SAMPLE_RATE
 BYTEDANCE_TTS_BIT_RATE
 BYTEDANCE_TTS_MODEL
 BYTEDANCE_TTS_MODEL_TYPE
 BYTEDANCE_TTS_EXPLICIT_LANGUAGE
 BYTEDANCE_TTS_ENABLE_SUBTITLE
 BYTEDANCE_TTS_TIMEOUT
 BYTEDANCE_TTS_DEBUG
 OPENAI_TTS_API_KEY
 ALLOWED_ORIGINS
 TRUSTED_PROXY_HOPS
 PORT
 ```
 **迁移后（仅引导参数，其余进库）：**
 ```
 TTS_DB_PATH        # 数据库/lock 目录（默认 ./）
 PORT               # 监听端口
 TTS_ADMIN_KEY      # 安装初始化凭证（可选，不设则启动打印一次性 token）
 OPENAI_TTS_API_KEY # 管理 API / 合成 API 鉴权（可选，迁移进 settings 或保留）
 ALLOWED_ORIGINS    # CORS（可保留，属运行环境而非业务配置）
 TRUSTED_PROXY_HOPS # 反代拓扑参数（保留，属部署环境）
 ```
 > `BYTEDANCE_TTS_DEBUG`、`TRUSTED_PROXY_HOPS`、`ALLOWED_ORIGINS` 属"部署/运维环境"而非"业务配置"，可留在 env；其余 TTS 业务配置全部进库。
 ---
 ## 9. 安全设计
 | 项 | 措施 |
 |---|---|
 | Setup 劫持 | 初始化凭证（`TTS_ADMIN_KEY` 或一次性 token）+ 可选回环限制；完成后 `/api/setup` 永久关闭 |
 | 合成/管理鉴权 | 复用 `OPENAI_TTS_API_KEY`（Bearer）；voice 路由不绕过鉴权 |
 | 敏感信息 | API Key 在引导页只进不出；日志/`/health` 不回显明文 Key（沿用 `maskAPIKey`） |
 | 输入校验 | voice 名白名单（字母数字 `_-`）、长度限制；SQL 全部参数化，防注入 |
 | lock/DB 写入 | 先写库后写 lock；lock 原子创建；损坏先备份再回退 |
 | 默认音色保护 | 删除被 `default_speaker` 引用的音色时拒绝（409） |
 ---
 ## 10. 开发计划与里程碑
 | 里程碑 | 内容 | 验收标准 |
 |---|---|---|
 | M1 存储层 | `store/` 包：SQLite 接入、两表建表、迁移、settings/voices CRUD、`integrity_check` | `go build` 通过；单测覆盖 CRUD |
 | M2 安装流程 | `installer/`：lock 检测/创建/删除、安装模式判定、损坏回退；`middleware/installguard` | 无 lock → 安装模式；有 lock → 正常模式；损坏库 → 备份+回退 |
 | M3 引导 UI | `/setup` 引导页 + `POST /api/setup`（token 校验、写库、写 lock） | 首次访问可完成安装；重复安装被拒；token 错误 401 |
 | M4 音色路由 | `/api/voices` CRUD + `/v1/audio/speech` voice 查库路由 | 新增音色后 voice 生效；未知 voice 400；默认音色兜底 |
 | M5 收敛与文档 | `setting/` 收敛、`.env.example`/README/部署更新、启动摘要展示模式与音色数 | 迁移后仅引导 env；文档与行为一致 |
 | M6 测试收尾 | 覆盖 lock 判定、setup 流程、voice 路由、损坏回退的集成测试 | 关键路径有自动化测试 |
 建议 M1→M2 连续做（安装流程是主链路），M3 与 M2 可并行；M4 依赖 M1 完成。
 ---
 ## 11. 风险与对策
 | 风险 | 影响 | 对策 |
 |---|---|---|
 | `modernc.org/sqlite` 体积增大 | 单二进制从 ~7MB 增至 ~40MB | 接受；如不可接受改 CGO 版（牺牲单文件） |
 | Setup 劫持（公网部署） | 他人抢先配置 | 初始化凭证 + 回环限制 + 完成后关闭端点（见 6.4） |
 | 库损坏导致服务不可用 | 服务起不来 | 自愈回退：备份 + 删 lock + 重新安装（见 6.3） |
 | 老用户迁移 | 现有 env 用户升级后无库 | 引导页预填旧 env 值；README 给出迁移步骤 |
 | voice 名冲突/默认引用 | 删除默认音色致不可用 | 唯一约束 + 默认音色删除保护（409） |
 | 并发写库 | 数据竞争 | 单写锁（`database/sql` 默认 + 业务层互斥），单用户场景风险低 |
 | 表结构未来升级 | 旧库不兼容 | lock 内容带版本号；`migrate.go` 预留版本迁移 |
 ---
 ## 12. 验收标准（本期 MVP）
 1. 删除所有业务 env 后，首次启动进入 `/setup` 引导页，可完成安装（全局 + ≥1 音色）；
 2. 安装完成后有 `installed.lock`，重启进入正常模式，`/v1/audio/speech` 可用；
 3. 通过 `/api/voices` 新增音色后，请求带该 `voice` 能正常合成；未知 voice 返回 400；
 4. 未传 `voice` 时使用默认音色；
 5. 手动制造损坏库 → 自动备份 `.corrupt-*` 并删 lock 回退安装模式；
 6. 安装模式下 `/v1/audio/speech` 返回 503 或跳转 `/setup`；
 7. 单二进制运行，无外部文件依赖（引导页已 embed）。
 ---
 ## 13. 非目标（明确不做）
 - 本期不做多服务商聚合、流式输出、缓存、字幕透出、ASR；
 - 不做完整的运营管理后台（仅引导页，管理 API 先行）；
 - 不做多租户/多用户体系（个人自用，单管理员）。
 ---
 *文档版本：v0.1 · 状态：待评审 · 配套代码基线：Volcano-Engine-TTS-UI @ develop*
@@ -158,7 +158,7 @@ TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公
 已配置 TRUSTED_PROXY_HOPS=2(精确模式,信任 2 跳反代)
 ```
-也可在 `GetClientIP` 临时加 `log.Printf` 打印解析结果,或参考已有的 `middleware/ratelimit_test.go`(24 个 XFF 表驱动用例)来扩展更多 XFF 链场景。生产环境不要保留 debug 日志。
+也可在 `GetClientIP` 临时加 `log.Printf` 打印解析结果,或写一个 Go 测试用例(参见 DEBT-1 单元测试任务)来覆盖不同 XFF 链场景。生产环境不要保留 debug 日志。
 ### Resource ID 说明
@@ -0,0 +1,197 @@
 # 漏洞报告 — Volcano-Engine-TTS-UI
 ## 元信息
 | 项目 | 内容 |
 |---|---|
 | 目标 | ByteDance TTS v3 → OpenAI 兼容接口适配器(Go) |
 | 审查范围 | 全部 12 个包、约 2400 行源码(不含 health.html 前端静态页) |
 | 审查方式 | 人工代码审查 + `go build` / `go vet`(均通过) |
 | 分支/提交 | develop @ 78c7200 |
 | 报告日期 | 2026 年 8 月 25 日  |
 | 严重度分级 | 🔴 高(必须修复)/ 🟠 中(建议修复)/ 🟡 低(视部署环境)/ ⚪ 信息(记录备查) |
 ---
 ## 漏洞清单(按严重度)
 | 编号 | 严重度 | 标题 | 位置 | 一句话影响 |
 |---|---|---|---|---|
 | VUL-004 | 🔴 高 | `.env` 未被 `.gitignore` 忽略,凭据可能入库/入镜像 | `.gitignore` | API Key 随 git 提交或 Docker 镜像层泄露 |
 | VUL-001 | 🟠 中 | aac/flac 响应 Content-Type 与数据不一致 | controller/tts.go、adapter/volcano/synthesis.go | 客户端按 AAC 解码 MP3 数据,播放失败 |
 | VUL-003 | 🟠 中 | `X-Forwarded-For` 信任链可伪造 IP 绕过限流 | middleware/ratelimit.go | 反代追加模式下限流失效 |
 | VUL-002 | 🟡 低 | transport 层错误不进入 `UpstreamErrors` 指标 | metrics/metrics.go、adapter/volcano/synthesis.go | 网络故障在监控上不可见 |
 | VUL-005 | 🟡 低 | 日志注入:客户端可控内容原样写入日志 | middleware/logger.go、controller/tts.go | 可伪造日志行 |
 | VUL-006 | 🟡 低 | `/metrics`、`/health`、`/dashboard` 无鉴权 | router/router.go | 公网暴露时泄漏运行细节(设计权衡) |
 | VUL-007 | 🟡 低 | `OPENAI_TTS_API_KEY` 未设置时鉴权完全关闭 | middleware/auth.go | 公网直连即无访问控制(设计权衡) |
 | VUL-008 | ⚪ 信息 | speed 超范围静默截断 | adapter/volcano/request.go | 0.25~0.5x、2.0~4.0x 实际被 clamp,无提示 |
 | VUL-009 | ⚪ 信息 | WAV 输出采样率依赖配置而非上游实际值 | adapter/volcano/audio.go | 配置错误导致音频变速 |
 ---
 ## VUL-004 🔴 高 — `.env` 未被忽略,凭据可能入库/入镜像
 **位置**: `.gitignore`(全文件仅忽略构建产物与编辑器文件)
 **描述**: README 与 `.env.example` 均指导用户执行 `cp .env.example .env` 后填入火山 API Key。但 `.gitignore` **没有包含 `.env`**。任何按此流程操作并执行 `git add .` / `git commit` 的用户,都会把含 `BYTEDANCE_TTS_API_KEY`、`OPENAI_TTS_API_KEY` 的文件提交进仓库历史(即使之后删除,历史中仍可找回)。Dockerfile 第 8 行 `COPY . .` 同样会把 `.env` 拷入镜像层。
 **影响**: 火山账号 API Key 泄露 → 冒用额度、产生费用、音色资源被盗用。密钥一旦进入 git 历史或镜像层即视为已泄露,只能吊销重建。
 **修复建议**:
 ```gitignore
 # Secrets
 .env
 .env.*
 !.env.example
 ```
 **验证**: 当前工作区无 `.env` 文件,仓库历史也未发现已提交的 `.env`(已核查 `git log` 提交列表无该文件),属"配置隐患"而非"已泄露"。
 ---
 ## VUL-001 🟠 中 — aac/flac 响应 Content-Type 与真实数据不一致
 **位置**: controller/tts.go:196-212(`contentTypeFor`)、adapter/volcano/synthesis.go:59-63、118-119
 **描述**: 客户端请求 `response_format: "aac"`(或 `flac`)时,调用链为:
 ```
 resolveClientFormat("aac") → "aac"(白名单放行)
 synthesis: opts.Format = "mp3"(上游降级,正确)
 synthesis: finalFormat = clientFormat = "aac"(错误,保留客户端格式)
 controller: Content-Type = contentTypeFor("aac") = "audio/aac"(错误)
 ```
 实际响应字节是 **MP3**,但 `Content-Type` 是 `audio/aac`。
 **影响**: 客户端(浏览器 `<audio>`、播放器 SDK)按 AAC 解码器处理 MP3 流,轻则播放失败/杂音,重则解码崩溃。README 声称"降级到 mp3",但响应头未同步降级。
 **修复建议**(二选一):
 1. `synthesis.go` 在降级后把 `finalFormat` 置为实际上游格式(`mp3`);
 2. `contentTypeFor` 对 `aac`/`flac` 直接返回 `audio/mpeg`。
 推荐方案 1(响应头应反映真实数据)。
 ---
 ## VUL-003 🟠 中 — X-Forwarded-For 信任链可伪造 IP 绕过限流
 **位置**: middleware/ratelimit.go:129-150(`GetClientIP`)
 **描述**: `GetClientIP` 在直连 IP 为私有地址(即判定为反代)时,信任 `X-Forwarded-For` 的**第一个**值,其次信任 `X-Real-IP`。若反代(nginx 等)使用追加模式(`$proxy_add_x_forwarded_for`),攻击者发送 `X-Forwarded-For: 1.2.3.4`,反代追加真实 IP 后请求头为 `1.2.3.4, 真实IP`,代码取 `1.2.3.4`。
 **影响**:
 - 攻击者每次请求携带不同伪造 IP,即可绕过 100 次/分钟的 IP 限流(限流 key 由该函数返回值决定);
 - 可伪装成受害 IP 请求,把受害 IP 的限流配额耗尽(间接 DoS)。
 **前提**: 服务必须部署在反代之后(反代 IP 为私有)。直接公网直连时直连 IP 非私有,不走信任分支,不受影响。
 **修复建议**(任一):
 1. 反代配置覆盖而非追加:`proxy_set_header X-Forwarded-For $remote_addr`;
 2. 代码改取 `XFF` **最后一个**值(追加模式下最后一个为真实来源);
 3. 部署时用 `X-Real-IP` 且确保反代覆盖该头,代码优先信任 `X-Real-IP`。
 ---
 ## VUL-002 🟡 低 — transport 层错误不进入 UpstreamErrors 指标
 **位置**: metrics/metrics.go:134-136、adapter/volcano/synthesis.go:90-92、112
 **描述**: `UpstreamFinished` 中 `if errCode != 0 { UpstreamErrors.Inc(...) }`。传输错误(连接失败、DNS 失败、读流失败)时调用方传入的 `errCode` 均为 0:
 - `client.PostStream` 失败 → `UpstreamFinished(..., 0)` → 不计
 - `ParseStream` 读流错误 → `UpstreamError{Code: 0}` → 不计
 而 `codeLabel`(metrics/metrics.go:148-158)明确设计了 `code == 0 → "transport"` 分类,**该分类永远不会被触发**。
 **影响**: 上游网络故障时 `tts_upstream_errors_total` 不增长,`/metrics` 与监控面板无法发现"火山接口连不上"类故障,只能从日志人工发现。
 **修复建议**: 将 transport 错误单独计数,例如 `if errCode != 0 || status == "transport_error" { UpstreamErrors.Inc(Labels{"code": codeLabel(errCode)}) }`。
 ---
 ## VUL-005 🟡 低 — 日志注入
 **位置**: middleware/logger.go:26、adapter/volcano/synthesis.go:100(`Message` 拼入上游响应体)
 **描述**: 访问日志直接拼接 `r.RequestURI`(客户端可控,URL 中可含 `\n`/`\r`);上游非 200 响应体 `rawBody` 拼入错误日志。Go `log` 不做转义,原样输出。
 **影响**: 攻击者可在请求 URL 中注入换行符,伪造服务端日志行(如伪造"合成成功"记录、注入误导信息),干扰排障;无代码执行风险。
 **修复建议**(低优先): 对 RequestURI 做换行转义(`strings.NewReplacer("\n", "\\n", "\r", "\\r")`)。
 ---
 ## VUL-006 🟡 低 — 监控端点无鉴权(设计权衡)
 **位置**: router/router.go:21-31
 **描述**: `/health`、`/metrics`、`/dashboard` 均不鉴权(README 明示,与 Prometheus 抓取场景对齐)。
 **影响**: 若公网直接暴露,任何人可查看 `/metrics`(含 speaker/model/format 业务标签、请求计数、上游错误聚合)与 `/dashboard`(运行状态、配置检查结果)。不涉及凭据,但为侦察提供信息。
 **判定**: 属于明确的设计决策,个人/内网使用可接受;公网部署建议通过反代鉴权(如 basic auth)保护 `/metrics`。
 ---
 ## VUL-007 🟡 低 — 未配置 OPENAI_TTS_API_KEY 时鉴权完全关闭
 **位置**: middleware/auth.go:20-22、setting/config.go:64-79
 **描述**: `ValidateAPIKey` 在 `setting.Auth.APIKeys` 为空时直接返回 `true`(全部放行)。该变量仅在 `OPENAI_TTS_API_KEY` 设置后才会填充。
 **影响**: 公网直接暴露且未配置该环境变量时,任何人均可无限制调用 TTS 合成,消耗火山额度。
 **判定**: 属设计行为(内网可信),README 已有说明。公网部署必须配置该变量,或由反代承担鉴权。
 ---
 ## VUL-008 ⚪ 信息 — speed 超范围静默截断
 **位置**: adapter/volcano/request.go:89-101、controller/tts.go:132-141
 **描述**: README 声明 `speed` 支持 0.25~4.0;controller 按此范围 clamp,但火山 `speech_rate` 仅支持 [-50, 100](即 0.5x~2.0x)。`0.25~0.5x` 与 `2.0~4.0x` 区间会被二次 clamp 截断,且无任何客户端提示。
 **影响**: 用户请求 0.25x 实际得到 0.5x 语速,表现与预期不符。
 **修复建议**: README 修正文档范围,或对超范围请求返回 400 而非静默截断。
 ---
 ## VUL-009 ⚪ 信息 — WAV 采样率依赖配置而非上游实际值
 **位置**: adapter/volcano/audio.go:32-39、controller/tts.go:121
 **描述**: `WrapWAVHeader` 使用 `opts.SampleRate`(环境变量 `BYTEDANCE_TTS_SAMPLE_RATE`,默认 24000)写 WAV 头。若上游实际返回的 PCM 采样率与配置不一致(配置错误或上游忽略该参数),WAV 头与数据不匹配。
 **影响**: 音频以错误速率播放(变速/变调)。
 **判定**: 正常配置下无影响;配置异常时表现为"音频怪声",README 第 3 条已有排查指引。
 ---
 ## 安全加固建议(非漏洞)
 1. **Docker 环境变量**: compose 中密钥通过 `environment` 明文传递,进程环境可见(`/proc/<pid>/environ`)。生产可改用 Docker Secrets 或启动时注入。
 2. **TLS**: 当前 HTTP 明文,建议生产经反代(nginx/caddy)终结 TLS,或服务前挂证书。
 3. **依赖固定**: go.mod 仅锁定 `gorilla/mux v1.8.1`(2018 年发布),建议 `go get -u` 检查是否存在已知 CVE 的新版本,或至少 `go mod verify`。
 ## 工程债务(非安全,记录备查)
 | 项目 | 说明 |
 |---|---|
 | 零单元测试 | 全部 12 个包无 `_test.go`;流解析(曾有 4 次 bug 修复)、WAV 拼头、speech_rate 转换、限流窗口、Prometheus 转义均无自动化回归保护 |
 | 死代码 | `ratelimit_middleware.go` 整文件未引用;`auth.go:InitAPIKeys`、`cors.go:InitCORSConfig` 为未被调用的 no-op;`dto.ByteDanceTTSConfig` + `setting/config.go:311` 占位引用 |
 | 冗余代码 | `resolveClientFormat`(controller/tts.go:49-52)两分支同值;`common.MaxResponseTimes`/`MaxErrors` 常量未使用 |
 | 云盘占用 | 注释表明 `ratelimit_middleware.go` 因"云盘同步被永久占用"无法删除,仓库位于云盘目录,git 操作与文件删除存在异常风险 |
 ## 已核查无风险项
 - ✅ API Key 比较使用 `subtle.ConstantTimeCompare`,无时序侧信道
 - ✅ 启动日志与 `/health` 对 API Key 脱敏(`maskAPIKey`)
 - ✅ 请求体上限 1MB、文本上限 5000 字、model 名长度/字符校验
 - ✅ 并发信号量 + IP 限流仅对 `/v1/` 生效,监控路径豁免;CORS 预检不消耗配额
 - ✅ telemetry label key 注册时锁定,当前 cardinality 可控(无客户端可控高基数标签)
 - ✅ 上游连接池复用、超时(30s)与 context 取消正确传播
 - ✅ 优雅退出(SIGINT/SIGTERM → 5s 内 Shutdown)
 - ✅ 无 `_test.go` 之外的明显并发竞态:全局配置启动期写入后只读,共享状态均有锁
@@ -1,278 +0,0 @@
 package controller
 import (
 	"encoding/json"
 	"fmt"
 	"log"
 	"net/http"
 	"os"
 	"strings"
 	"time"
 	"github.com/volcano-tts/tts-api/installer"
 	"github.com/volcano-tts/tts-api/middleware"
 	"github.com/volcano-tts/tts-api/setting"
 	"github.com/volcano-tts/tts-api/store"
 )
 // SetupAPIState 是 setup 控制器需要的状态:
 //   - Store:  db 访问,可能为 nil(自愈回退后 store 已关闭,等待重新 setup)
 //   - DBPath: 用于安装完成时写 lock
 type SetupAPIState struct {
 	Store  *store.Store
 	DBPath string
 	Token  string
 }
 // 全局 setup 状态,在 main.go 启动时通过 SetSetupState 注入。
 // 进程内只有一个二进制实例,全局变量是合适的。
 var setupState SetupAPIState
 // SetSetupState 注入 setup 控制器所需的 store + dbPath,启动期调用一次。
 func SetSetupState(s *store.Store, dbPath string) {
 	setupState.Store = s
 	setupState.DBPath = dbPath
 }
 // GetSetupStore 供 router/main 注入的 store 访问函数。
 func GetSetupStore() *store.Store { return setupState.Store }
 // GetSetupDBPath 供 router/main 注入的 dbPath 访问函数。
 func GetSetupDBPath() string { return setupState.DBPath }
 // SetupStatusHandler GET /api/setup/status
 // 始终返回当前模式,无论安装与否;用于部署探针 + 引导页判断。
 func SetupStatusHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	resp := map[string]any{
 		"installed": installer.GetMode() == installer.ModeNormal,
 		"mode":      installer.GetMode().String(),
 	}
 	_ = json.NewEncoder(w).Encode(resp)
 }
 // SetupPrefillHandler GET /api/setup/prefill
 // 仅在安装模式有响应;返回旧 env 变量值,便于引导页预填,实现平滑迁移。
 func SetupPrefillHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
 	if installer.GetMode() != installer.ModeSetup {
 		http.Error(w, "not in setup mode", http.StatusNotFound)
 		return
 	}
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	resp := map[string]any{
 		"settings": prefillFromEnv(),
 	}
 	_ = json.NewEncoder(w).Encode(resp)
 }
 // prefillFromEnv 读 BYTEDANCE_TTS_* 等旧 env,作为引导页预填值。
 // 读不到就返回空串,前端会用默认值。
 func prefillFromEnv() map[string]string {
 	get := func(k string) string { return os.Getenv(k) }
 	return map[string]string{
 		"api_key":            "", // API key 永不回显,即便 env 里有;必须让用户重新输入
 		"default_resource_id": get("BYTEDANCE_TTS_RESOURCE_ID"),
 		"default_speaker":    get("BYTEDANCE_TTS_SPEAKER"),
 		"default_format":     get("BYTEDANCE_TTS_FORMAT"),
 		"sample_rate":        get("BYTEDANCE_TTS_SAMPLE_RATE"),
 		"model":              get("BYTEDANCE_TTS_MODEL"),
 		"model_type":         get("BYTEDANCE_TTS_MODEL_TYPE"),
 		"explicit_language":  get("BYTEDANCE_TTS_EXPLICIT_LANGUAGE"),
 		"enable_subtitle":    get("BYTEDANCE_TTS_ENABLE_SUBTITLE"),
 		"timeout":            get("BYTEDANCE_TTS_TIMEOUT"),
 	}
 }
 // SetupRequestBody 是 POST /api/setup 的请求体结构。
 type SetupRequestBody struct {
 	Token    string            `json:"token"`
 	Settings map[string]string `json:"settings"`
 	Voices   []SetupVoice      `json:"voices"`
 }
 // SetupVoice 是 POST /api/setup 里 voices 数组的条目。
 type SetupVoice struct {
 	Name       string `json:"name"`
 	Speaker    string `json:"speaker"`
 	ResourceID string `json:"resource_id"`
 	Model      string `json:"model"`
 	Language   string `json:"language"`
 }
 // SetupSubmitHandler POST /api/setup
 // 校验 token → 校验字段 → 写 settings → 写 voices → 写 lock。
 // 必须在安装模式才接受;装完后永久 404。
 func SetupSubmitHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
 	// 安装完成后此端点永久关闭(防止被误触)
 	if installer.GetMode() != installer.ModeSetup {
 		http.NotFound(w, r)
 		return
 	}
 	// 解析 body
 	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1MB
 	var body SetupRequestBody
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
 		return
 	}
 	// token 校验(常量时间比较防计时攻击)
 	if setting.SetupToken == "" || !secureEqualString(body.Token, setting.SetupToken) {
 		log.Printf("[setup] token 校验失败 - 客户端=%s", middleware.GetClientIP(r))
 		middleware.SendJSONError(w, http.StatusUnauthorized, "invalid setup token", "authentication_error", "invalid_token")
 		return
 	}
 	// 校验 settings 必填项
 	if err := validateSetupSettings(body.Settings); err != nil {
 		middleware.SendJSONError(w, http.StatusBadRequest, err.Error(), "invalid_request_error", "missing_field")
 		return
 	}
 	// 校验 voices
 	if err := validateSetupVoices(body.Voices); err != nil {
 		middleware.SendJSONError(w, http.StatusBadRequest, err.Error(), "invalid_request_error", "invalid_voice")
 		return
 	}
 	// 取 store:必须为非 nil(自愈回退后 store 是 nil,这种状态下不接 setup,要求重启)
 	s := GetSetupStore()
 	if s == nil {
 		middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready, please restart service", "configuration_error", "db_not_ready")
 		return
 	}
 	// 写 settings(包含 initialized=1)
 	settingsKV := make(map[string]string, len(body.Settings)+1)
 	for k, v := range body.Settings {
 		settingsKV[k] = v
 	}
 	settingsKV["initialized"] = "1"
 	settingsKV["installed_at"] = time.Now().UTC().Format(time.RFC3339)
 	if err := s.SettingsSetBatch(settingsKV); err != nil {
 		log.Printf("[setup] 写 settings 失败: %v", err)
 		middleware.SendJSONError(w, http.StatusInternalServerError, "failed to write settings", "server_error", "db_write_failed")
 		return
 	}
 	// 清空旧 voices 再插入(假设是首次安装;若不是,name 冲突会变成 409)
 	// 这里选择 "清空+插入" 语义,符合"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
 	for _, v := range body.Voices {
 		_, err := s.VoiceInsert(store.Voice{
 			Name:       v.Name,
 			Speaker:    v.Speaker,
 			ResourceID: v.ResourceID,
 			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 {
 		log.Printf("[setup] 写 lock 失败: %v", err)
 		middleware.SendJSONError(w, http.StatusInternalServerError, "failed to create install lock", "server_error", "lock_write_failed")
 		return
 	}
 	// 切到正常模式(本进程内)
 	installer.SetMode(installer.ModeNormal)
 	log.Printf("[setup] 安装完成!后续请求将进入正常模式")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"ok":       true,
 		"message":  "installed",
 		"redirect": "/admin",
 		"settings": len(settingsKV),
 		"voices":   inserted,
 	})
 }
 // validateSetupSettings 校验必填项。
 func validateSetupSettings(m map[string]string) error {
 	required := []string{"api_key", "default_resource_id", "default_speaker"}
 	var missing []string
 	for _, k := range required {
 		if strings.TrimSpace(m[k]) == "" {
 			missing = append(missing, k)
 		}
 	}
 	if len(missing) > 0 {
 		return fmt.Errorf("missing required fields: %v", missing)
 	}
 	return nil
 }
 // validateSetupVoices 校验音色列表;至少 1 条。
 // 详细合法性(白名单、speaker 非空)由 store.VoiceInsert 负责。
 func validateSetupVoices(vs []SetupVoice) error {
 	if len(vs) == 0 {
 		return fmt.Errorf("at least one voice is required")
 	}
 	names := make(map[string]struct{}, len(vs))
 	for i, v := range vs {
 		if strings.TrimSpace(v.Name) == "" {
 			return fmt.Errorf("voices[%d]: name is required", i)
 		}
 		if strings.TrimSpace(v.Speaker) == "" {
 			return fmt.Errorf("voices[%d] (%s): speaker is required", i, v.Name)
 		}
 		if strings.TrimSpace(v.ResourceID) == "" {
 			return fmt.Errorf("voices[%d] (%s): resource_id is required", i, v.Name)
 		}
 		if _, dup := names[v.Name]; dup {
 			return fmt.Errorf("voices[%d]: duplicate name %q", i, v.Name)
 		}
 		names[v.Name] = struct{}{}
 	}
 	return nil
 }
 // secureEqualString 是常量时间字符串比较,防止 token 计时攻击。
 func secureEqualString(a, b string) bool {
 	if len(a) != len(b) {
 		// 先比对长度(避免短串早返回时泄漏长度信息)
 		// 但仍要遍历一遍避免优化器消除分支
 		_ = a[0]
 		return false
 	}
 	var diff byte
 	for i := 0; i < len(a); i++ {
 		diff |= a[i] ^ b[i]
 	}
 	return diff == 0
 }
@@ -14,7 +14,6 @@ import (
 	"github.com/volcano-tts/tts-api/adapter/volcano"
 	"github.com/volcano-tts/tts-api/common"
 	"github.com/volcano-tts/tts-api/dto"
 	"github.com/volcano-tts/tts-api/installer"
 	"github.com/volcano-tts/tts-api/metrics"
 	"github.com/volcano-tts/tts-api/middleware"
 	"github.com/volcano-tts/tts-api/setting"
@@ -63,15 +62,6 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	// 安装模式双保险:即使 InstallGuard 中间件没拦住,这里也 503 + 引导跳转
 	if installer.GetMode() == installer.ModeSetup {
 		log.Printf("[tts] 安装模式下拒绝 /v1/audio/speech - 客户端=%s", middleware.GetClientIP(r))
 		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		w.WriteHeader(http.StatusServiceUnavailable)
 		_, _ = w.Write([]byte(`{"error":"not installed","code":"install_required","redirect":"/setup"}`))
 		return
 	}
 	if !middleware.ValidateAPIKey(r) {
 		metrics.AuthFailed.Inc(telemetry.Labels{})
 		log.Printf("警告: API Key 鉴权失败 - 路径=%s 客户端=%s 远端=%s",
@@ -223,12 +213,7 @@ func contentTypeFor(format string) string {
 func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
-	// 安装模式下 /health 仍然 200,但通过 installed 字段让探针/运维识别
+	if setting.TTSConfigErr != nil {
 	// (Kubernetes readiness probe 可以用 installed=false 决定是否放流量)
 	mode := installer.GetMode()
 	if mode == installer.ModeSetup {
 		w.WriteHeader(http.StatusOK) // 200,因为进程活着,只是还没初始化
 	} else if setting.TTSConfigErr != nil {
 		w.WriteHeader(http.StatusServiceUnavailable)
 	} else {
 		w.WriteHeader(http.StatusOK)
@@ -238,9 +223,7 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	allRequired := env["all_required_vars_set"].(bool)
 	status := "ok"
-	if mode == installer.ModeSetup {
+	if !allRequired {
 		status = "not_installed"
 	} else if !allRequired {
 		status = "configuration_error"
 	}
@@ -256,8 +239,6 @@ func HealthHandler(w http.ResponseWriter, r *http.Request) {
 			AllRequiredVarsSet: allRequired,
 			ConfigError:        setting.TTSConfigErr != nil,
 		},
 		Installed: mode == installer.ModeNormal,
 		Mode:      mode.String(),
 	}
 	json.NewEncoder(w).Encode(resp)
 }
@@ -12,9 +12,6 @@ type HealthResponse struct {
 	StartTime    string                 `json:"start_time"`
 	Memory       map[string]interface{} `json:"memory"`
 	ConfigStatus ConfigStatusResponse   `json:"config_status"`
 	// M1 新增:反映 installer 模式,便于部署探针/运维识别未初始化状态
 	Installed bool   `json:"installed"`
 	Mode      string `json:"mode"`
 }
 type ConfigStatusResponse struct {
@@ -3,16 +3,3 @@ module github.com/volcano-tts/tts-api
 go 1.26
 require github.com/gorilla/mux v1.8.1
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	modernc.org/libc v1.74.4 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
 	modernc.org/sqlite v1.57.0 // indirect
 )
@@ -1,22 +1,2 @@
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
 github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
 github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k=
 modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
 modernc.org/sqlite v1.57.0 h1:qNQP6xnx5M0ISNtlnxoOX0+cD5bJ0/gr9aMmndFczzg=
 modernc.org/sqlite v1.57.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=
@@ -1,191 +0,0 @@
 package installer
 import (
 	"errors"
 	"fmt"
 	"log"
 	"os"
 	"path/filepath"
 	"time"
 	"github.com/volcano-tts/tts-api/store"
 )
 // Mode 表示服务当前的运行模式。
 // 启动期由 Detect 确定,运行期不变。
 type Mode int
 const (
 	// ModeSetup 未安装,只放行 /setup + /api/setup/*。
 	ModeSetup Mode = iota
 	// ModeNormal 已安装,全部路由可用。
 	ModeNormal
 )
 func (m Mode) String() string {
 	switch m {
 	case ModeSetup:
 		return "setup"
 	case ModeNormal:
 		return "normal"
 	}
 	return "unknown"
 }
 // CurrentMode 是 Detect 确定的运行期模式;供 controller/middleware 双保险使用。
 // 进程内只有一个二进制实例,所以全局变量是合适的;不必走 DI。
 var CurrentMode Mode = ModeSetup // 默认 setup,Detect 后会被覆盖
 // SetMode 在 Detect 完成后调用,设置进程级模式。
 func SetMode(m Mode) { CurrentMode = m }
 // GetMode 返回进程级模式;Controller 双保险用。
 func GetMode() Mode { return CurrentMode }
 // Result 是 Detect 的完整输出;调用方关心 Mode + 一些诊断信息。
 type Result struct {
 	Mode      Mode
 	DBPath    string // 实际打开的 db 路径
 	LockPath  string
 	Corrupted bool   // 这次启动是否从损坏回退
 	BackupTo  string // 损坏回退时备份文件路径
 }
 // ErrInUse 标识在 Detect 期间发现 db 正在被另一个进程占用;
 // 这种情况下不应该自动 rename,会破坏另一个进程的运行。
 // 上层应记录日志并按"装模式"启动,等下次重启再处理。
 var ErrInUse = errors.New("installer: database is locked by another process")
 // Detect 是启动期的总入口:打开/创建 db、判定 lock、检测损坏并自愈。
 //
 // 流程:
 //  1. Open db(可能新建)
 //  2. 检查 lock:
 //     - 不存在 → ModeSetup
 //     - 存在 → 跑 IntegrityCheck
 //     - 通过 → ModeNormal
 //     - 不通过 → 备份 db.corrupt-<ts> + 删 lock + ModeSetup(并标记 Corrupted=true)
 //
 // 返回的 *store.Store 必须由调用方在进程退出时 Close。
 func Detect(dbPath string) (*store.Store, Result, error) {
 	if dbPath == "" {
 		return nil, Result{}, fmt.Errorf("installer: db path is empty")
 	}
 	res := Result{
 		DBPath:   dbPath,
 		LockPath: LockPath(dbPath),
 	}
 	s, err := store.Open(dbPath)
 	if err != nil {
 		// 打开失败通常意味着文件损坏;走自愈回退。
 		// 重要:不要区分"不存在"和"损坏"——SQLite 第一次 Open 会自动建空库,
 		// 如果"不存在"能走到这里说明更严重的系统错误,也不该贸然启动。
 		if backup, ok := tryBackupCorrupt(dbPath, err); ok {
 			res.Corrupted = true
 			res.BackupTo = backup
 			log.Printf("[installer] 检测到损坏 db,已备份到 %q,删除 lock,回退到安装模式", backup)
 		} else {
 			return nil, res, fmt.Errorf("installer: open db %q failed: %w", dbPath, err)
 		}
 	}
 	// lock 状态判定
 	exists, err := LockExists(dbPath)
 	if err != nil {
 		if s != nil {
 			_ = s.Close()
 		}
 		return nil, res, fmt.Errorf("installer: lock check failed: %w", err)
 	}
 	if !exists {
 		res.Mode = ModeSetup
 		SetMode(ModeSetup)
 		if !res.Corrupted {
 			log.Printf("[installer] 启动模式: 安装模式(无 lock 文件)")
 		}
 		return s, res, nil
 	}
 	// lock 在,跑完整性检查
 	if s == nil {
 		// 自愈回退已经走完,应该删了 lock;但保险起见再删一次
 		if err := DeleteLock(dbPath); err != nil {
 			return nil, res, fmt.Errorf("installer: delete lock after fallback: %w", err)
 		}
 		res.Mode = ModeSetup
 		SetMode(ModeSetup)
 		return nil, res, nil
 	}
 	check, err := s.IntegrityCheck()
 	if err != nil {
 		_ = s.Close()
 		// integrity_check 自身报错,等同损坏,走自愈
 		backup, ok := tryBackupCorrupt(dbPath, err)
 		if !ok {
 			return nil, res, fmt.Errorf("installer: integrity_check failed: %w", err)
 		}
 		_ = DeleteLock(dbPath)
 		res.Corrupted = true
 		res.BackupTo = backup
 		res.Mode = ModeSetup
 		SetMode(ModeSetup)
 		log.Printf("[installer] integrity_check 错误,已备份到 %q,删除 lock,回退到安装模式", backup)
 		return nil, res, nil
 	}
 	if check != "ok" {
 		_ = s.Close()
 		backup, ok := tryBackupCorrupt(dbPath, fmt.Errorf("integrity_check returned: %s", check))
 		if !ok {
 			return nil, res, fmt.Errorf("installer: integrity_check = %q (not ok)", check)
 		}
 		_ = DeleteLock(dbPath)
 		res.Corrupted = true
 		res.BackupTo = backup
 		res.Mode = ModeSetup
 		SetMode(ModeSetup)
 		log.Printf("[installer] 库不完整(integrity_check=%q),已备份到 %q,删除 lock,回退到安装模式", check, backup)
 		return nil, res, nil
 	}
 	res.Mode = ModeNormal
 	SetMode(ModeNormal)
 	log.Printf("[installer] 启动模式: 正常模式(lock=%s)", res.LockPath)
 	return s, res, nil
 }
 // tryBackupCorrupt 尝试把损坏的 db 文件 rename 为 .corrupt-<unix-ms>;
 // 成功返回 (新路径, true),失败 (任何原因) 返回 ("", false)。
 // 注意:这里不返回 error,因为 "无法备份" 不应阻止回退(可以后续人工排查)。
 func tryBackupCorrupt(dbPath string, reason error) (string, bool) {
 	if dbPath == "" {
 		return "", false
 	}
 	// 不存在的话没法 rename(也没必要)
 	if _, err := os.Stat(dbPath); err != nil {
 		return "", false
 	}
 	ts := time.Now().UnixMilli()
 	backup := fmt.Sprintf("%s.corrupt-%d", dbPath, ts)
 	if err := os.Rename(dbPath, backup); err != nil {
 		log.Printf("[installer] 备份损坏 db 失败: %v(将直接重建空库)", err)
 		return "", false
 	}
 	log.Printf("[installer] 损坏原因: %v", reason)
 	return backup, true
 }
 // EnsureDBDir 确保 dbPath 所在目录存在(对首次安装很有用;
 // 当 dbDir 是新目录时 store.Open 之前需要先 mkdir)。
 func EnsureDBDir(dbPath string) error {
 	if dbPath == "" {
 		return nil
 	}
 	dir := filepath.Dir(dbPath)
 	if dir == "" || dir == "." {
 		return nil
 	}
 	return os.MkdirAll(dir, 0o755)
 }
@@ -1,121 +0,0 @@
 // Package installer 负责安装状态判定:lock 文件检测/创建/删除、
 // 启动期 Detect 流程、损坏自愈回退。
 //
 // 设计要点:
 //   - lock 文件路径: <dbDir>/installed.lock,与 tts.db 同目录
 //   - lock 不存在 = 未安装(进入安装模式)
 //   - lock 存在 + 库 OK = 已安装(正常模式)
 //   - lock 存在 + 库损坏 = 自动备份 + 删 lock + 回到安装模式
 //   - 写顺序: 先写库,后写 lock(避免 lock 在、库是半成品)
 //   - 写锁用临时文件 + 原子 rename,避免崩溃中途留半成品 lock
 package installer
 import (
 	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 )
 // lockFileName 是 lock 文件名;固定不变,所有部署共用。
 const lockFileName = "installed.lock"
 // schemaVersion 是 lock 内容里的 schema 版本号;留作未来版本兼容判断。
 // 未来若有破坏性升级,可读这个值决定是否要重装/迁移。
 const schemaVersion = "1"
 // LockPath 返回给定 db 路径下 lock 文件的绝对路径。
 // dbPath 通常是 .db 文件路径(不是目录);若传入目录则直接拼 lockFileName。
 func LockPath(dbPath string) string {
 	if dbPath == "" {
 		return lockFileName
 	}
 	// 如果 dbPath 是已存在的目录,直接拼文件名
 	if info, err := os.Stat(dbPath); err == nil && info.IsDir() {
 		return filepath.Join(dbPath, lockFileName)
 	}
 	dir := filepath.Dir(dbPath)
 	return filepath.Join(dir, lockFileName)
 }
 // ErrLockExists 表示 lock 已存在;CreateLock 会返回这个,提醒上层别覆盖。
 var ErrLockExists = errors.New("installer: lock already exists")
 // LockExists 检测 lock 文件是否存在;不存在不算错误(常见的"未安装"状态)。
 func LockExists(dbPath string) (bool, error) {
 	p := LockPath(dbPath)
 	_, err := os.Stat(p)
 	if err == nil {
 		return true, nil
 	}
 	if errors.Is(err, os.ErrNotExist) {
 		return false, nil
 	}
 	return false, fmt.Errorf("installer: stat lock %q: %w", p, err)
 }
 // CreateLock 原子写入 lock 文件;lock 已存在返回 ErrLockExists。
 // 内容: "version <schemaVersion> <RFC3339 时间戳>"
 func CreateLock(dbPath string) error {
 	exists, err := LockExists(dbPath)
 	if err != nil {
 		return err
 	}
 	if exists {
 		return ErrLockExists
 	}
 	p := LockPath(dbPath)
 	content := fmt.Sprintf("version %s %s\n", schemaVersion, time.Now().UTC().Format(time.RFC3339))
 	// 原子写入:先写临时文件,再 rename
 	dir := filepath.Dir(p)
 	tmp, err := os.CreateTemp(dir, ".installed.lock.*.tmp")
 	if err != nil {
 		return fmt.Errorf("installer: create lock tmp: %w", err)
 	}
 	tmpName := tmp.Name()
 	// 确保临时文件最终被清理(出错时)
 	defer func() {
 		_ = os.Remove(tmpName)
 	}()
 	if _, err := tmp.WriteString(content); err != nil {
 		_ = tmp.Close()
 		return fmt.Errorf("installer: write lock tmp: %w", err)
 	}
 	if err := tmp.Close(); err != nil {
 		return fmt.Errorf("installer: close lock tmp: %w", err)
 	}
 	if err := os.Rename(tmpName, p); err != nil {
 		return fmt.Errorf("installer: rename lock tmp: %w", err)
 	}
 	return nil
 }
 // DeleteLock 删 lock;不存在不报错。
 // 主要用于损坏自愈流程和测试清理。
 func DeleteLock(dbPath string) error {
 	p := LockPath(dbPath)
 	err := os.Remove(p)
 	if err == nil || errors.Is(err, os.ErrNotExist) {
 		return nil
 	}
 	return fmt.Errorf("installer: remove lock %q: %w", p, err)
 }
 // ReadLock 读 lock 内容;主要用于诊断日志和未来版本兼容判断。
 // 不存在返回 ("", nil)。
 func ReadLock(dbPath string) (string, error) {
 	p := LockPath(dbPath)
 	b, err := os.ReadFile(p)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
 			return "", nil
 		}
 		return "", fmt.Errorf("installer: read lock %q: %w", p, err)
 	}
 	return strings.TrimSpace(string(b)), nil
 }
@@ -10,48 +10,23 @@ import (
 	"time"
 	"github.com/volcano-tts/tts-api/controller"
 	"github.com/volcano-tts/tts-api/installer"
 	"github.com/volcano-tts/tts-api/metrics"
 	"github.com/volcano-tts/tts-api/middleware"
 	"github.com/volcano-tts/tts-api/router"
 	"github.com/volcano-tts/tts-api/setting"
 )
 // ttsDBPath 返回数据库/lock 所在路径;空时落到当前目录的 tts.db。
 func ttsDBPath() string {
 	if p := os.Getenv("TTS_DB_PATH"); p != "" {
 		return p
 	}
 	return "tts.db"
 }
 func main() {
 	log.SetFlags(log.LstdFlags | log.Lshortfile)
 	log.SetPrefix("[TTS-Server] ")
 	// 1) 加载引导环境变量(PORT / OPENAI_TTS_API_KEY / TTS_ADMIN_KEY 等)
 	setting.InitAllConfigs()
 	metrics.Init()
 	middleware.InitRateLimiter()
 	setting.CheckStaticFiles()
 	controller.InitController()
 	setting.LogStartupSummary()
 	// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
 	dbPath := ttsDBPath()
 	if err := installer.EnsureDBDir(dbPath); err != nil {
 		log.Fatalf("FATAL: cannot create db dir: %v", err)
 	}
 	st, res, err := installer.Detect(dbPath)
 	if err != nil {
 		log.Fatalf("FATAL: installer detect failed: %v", err)
 	}
 	if res.Corrupted {
 		log.Printf("[main] 注意: 启动时检测到 db 损坏并已自愈回退(备份=%s)", res.BackupTo)
 	}
 	// 注入 setup 控制器需要的 store + dbPath(无论哪种模式都注入,正常模式下备用)
 	controller.SetSetupState(st, dbPath)
 	log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
 	controller.InitController()
 	controller.SetStartTime(time.Now())
 	r := router.Setup()
@@ -68,16 +43,12 @@ func main() {
 	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 	go func() {
 		if installer.GetMode() == installer.ModeSetup {
 			log.Printf("Starting TTS Server in SETUP mode")
 			log.Printf("Open browser to http://localhost:%s/setup to install", setting.Server.Port)
 		} else {
 		log.Printf("Starting ByteDance TTS to OpenAI API Adapter Server")
 		log.Printf("Listening on port: %s", setting.Server.Port)
 		log.Printf("OpenAI TTS endpoint: http://localhost:%s/v1/audio/speech", setting.Server.Port)
 		}
 		log.Printf("Health check: http://localhost:%s/health", setting.Server.Port)
 		log.Printf("Metrics: http://localhost:%s/metrics", setting.Server.Port)
 		log.Printf("Using ByteDance v3 API")
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			log.Fatalf("Server failed to start: %v", err)
@@ -87,11 +58,6 @@ func main() {
 	<-quit
 	log.Println("Shutting down server...")
 	// 关闭 db 连接(仅当 st 非 nil 时)
 	if st != nil {
 		_ = st.Close()
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
@@ -1,81 +0,0 @@
 package middleware
 import (
 	"log"
 	"net/http"
 	"strings"
 	"github.com/volcano-tts/tts-api/installer"
 )
 // InstallGuard 拦截所有非白名单路由,在安装模式下按 Accept 头做内容协商:
 //
 //   - text/html 类(浏览器) → 302 重定向到 /setup
 //   - 其它(API 客户端、curl 等) → 503 + JSON
 //
 // 设计:放行白名单路径前缀,其余一律拦截。
 // 中间件顺序:必须装在 RateLimit / ConcurrencyLimit / Logger 之前,
 // 避免安装模式下被限流计数污染(参考 M1 风险点 #2)。
 func InstallGuard(currentMode func() installer.Mode, allowPrefixes ...string) func(http.Handler) http.Handler {
 	defaults := []string{
 		"/setup",          // 安装引导页
 		"/api/setup",      // 安装相关 API
 		"/health",         // 部署探针要能识别未安装状态
 		"/metrics",        // Prometheus 拉取
 		"/static/",        // 引导页静态资源(留口子)
 	}
 	allow := append(defaults, allowPrefixes...)
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			if currentMode() != installer.ModeSetup {
 				next.ServeHTTP(w, r)
 				return
 			}
 			// 安装模式:仅放行白名单
 			path := r.URL.Path
 			for _, p := range allow {
 				if strings.HasPrefix(path, p) {
 					next.ServeHTTP(w, r)
 					return
 				}
 			}
 			log.Printf("[installguard] 安装模式下拒绝非白名单请求 - 路径=%s 客户端=%s accept=%q",
 				path, GetClientIP(r), r.Header.Get("Accept"))
 			// 内容协商:浏览器自动跳 /setup,API 客户端拿 JSON。
 			// / 不在白名单里,所以这里同时覆盖"敲域名根路径"和"敲其他路径"两种场景。
 			if acceptsHTML(r.Header.Get("Accept")) {
 				w.Header().Set("Location", "/setup")
 				w.WriteHeader(http.StatusFound) // 302
 				return
 			}
 			w.Header().Set("Content-Type", "application/json; charset=utf-8")
 			w.WriteHeader(http.StatusServiceUnavailable)
 			_, _ = w.Write([]byte(`{"error":"not installed","code":"install_required","redirect":"/setup"}`))
 		})
 	}
 }
 // acceptsHTML 判断客户端是否接受 HTML 响应。
 // 严格匹配:Accept 必须显式包含 text/html 或 text/*,避免通配 */*(curl/API 默认)
 // 走 302 路径影响 API 行为。
 func acceptsHTML(accept string) bool {
 	if accept == "" {
 		return false
 	}
 	for _, part := range strings.Split(accept, ",") {
 		mt := strings.TrimSpace(part)
 		if mt == "" {
 			continue
 		}
 		// 去掉 q= 等参数
 		if idx := strings.Index(mt, ";"); idx >= 0 {
 			mt = strings.TrimSpace(mt[:idx])
 		}
 		mt = strings.ToLower(mt)
 		if mt == "text/html" || mt == "text/*" {
 			return true
 		}
 	}
 	return false
 }
@@ -0,0 +1,229 @@
 package middleware
 import (
 	"net/http/httptest"
 	"testing"
 )
 // TestGetClientIP 覆盖 XFF 解析在两种模式下的关键场景。
 // 表驱动测试,每个 case 独立设置 trustedProxyHops,验证 GetClientIP 输出。
 func TestGetClientIP(t *testing.T) {
 	tests := []struct {
 		name       string
 		mode       int    // 0=启发式, N>0=精确 N 跳
 		remoteAddr string // 直连 IP:port
 		xff        string // X-Forwarded-For 头(空则不设)
 		xri        string // X-Real-IP 头(空则不设)
 		want       string
 	}{
 		// === 直出部署(directIP 是公网,XFF 分支不进)===
 		{
 			name:       "直出_无XFF",
 			mode:       0,
 			remoteAddr: "1.2.3.4:5678",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "直出_XFF被忽略",
 			mode:       0,
 			remoteAddr: "1.2.3.4:5678",
 			xff:        "fake",
 			want:       "1.2.3.4", // 公网直连不走 XFF 分支
 		},
 		{
 			name:       "直出_精确模式也不走XFF",
 			mode:       2,
 			remoteAddr: "1.2.3.4:5678",
 			xff:        "fake, 5.6.7.8",
 			want:       "1.2.3.4",
 		},
 		// === 单跳反代 ===
 		{
 			name:       "单跳_启发式",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "单跳_精确N1",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		// === 攻击者伪造首值 ===
 		{
 			name:       "伪造_启发式跳过fake",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "fake, 1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "伪造_精确N1也跳过fake",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "fake, 1.2.3.4",
 			want:       "1.2.3.4", // target=1, 跳过 fake 取 real
 		},
 		{
 			name:       "伪造_多个假值前缀",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "fake1, fake2, 1.2.3.4",
 			want:       "1.2.3.4", // 从尾扫,只看最后一个
 		},
 		// === 多跳 CDN+nginx ===
 		{
 			name:       "多跳_启发式返回CDN边缘",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, 203.0.113.5",
 			want:       "203.0.113.5", // 链尾公网=CDN 边缘
 		},
 		{
 			name:       "多跳_精确N2返回真实client",
 			mode:       2,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, 203.0.113.5",
 			want:       "1.2.3.4", // 倒数第2=真实 client
 		},
 		{
 			name:       "多跳_精确N1不够穿透",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, 203.0.113.5",
 			want:       "203.0.113.5", // 数到 nginx,没穿透到 client
 		},
 		// === 链尾私有 IP ===
 		{
 			name:       "链尾私有_启发式跳过",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, 10.0.0.1",
 			want:       "1.2.3.4", // 跳过私有取公网
 		},
 		{
 			name:       "链尾私有_精确N1取末值",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, 10.0.0.1",
 			want:       "10.0.0.1", // 精确模式不跳私有
 		},
 		// === X-Real-IP 兜底 ===
 		{
 			name:       "无XFF_走XRI",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xri:        "1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "XFF全非法_走XRI",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "not_ip, also_not",
 			xri:        "1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "XRI被XFF优先_但XFF全非法",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "not_an_ip",
 			xri:        "1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		// === 全部私有 IP(启发式无解)===
 		{
 			name:       "全私有_启发式回退directIP",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "192.168.1.1, 172.16.0.1",
 			want:       "10.0.0.1", // 全跳私有,走 directIP
 		},
 		// === 畸形/空 XFF ===
 		{
 			name:       "畸形XFF_启发式跳过畸形",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "not_an_ip, 1.2.3.4",
 			want:       "1.2.3.4",
 		},
 		{
 			name:       "全空XFF_回退directIP",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "  ,  ,  ",
 			want:       "10.0.0.1",
 		},
 		{
 			name:       "XFF带前后空格",
 			mode:       0,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "  1.2.3.4  ,  5.6.7.8  ",
 			want:       "5.6.7.8", // TrimSpace 处理
 		},
 		// === 精确模式 N 超出链长 ===
 		{
 			name:       "精确N超出链长_回退到首值",
 			mode:       5,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4",
 			want:       "1.2.3.4", // target<0 保护,取首个合法
 		},
 		{
 			name:       "精确N等于链长_取首值",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4",
 			want:       "1.2.3.4", // target=0
 		},
 		{
 			name:       "精确N大于链长_取首值",
 			mode:       2,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4",
 			want:       "1.2.3.4", // target<0,fall back
 		},
 		// === 精确模式链中含畸形 ===
 		{
 			name:       "精确N1_链中畸形回退到首值",
 			mode:       1,
 			remoteAddr: "10.0.0.1:5678",
 			xff:        "1.2.3.4, not_ip",
 			want:       "1.2.3.4", // target=1(not_ip 失败)→ i=0(1.2.3.4 成功)
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			trustedProxyHops = tt.mode
 			r := httptest.NewRequest("GET", "/", nil)
 			r.RemoteAddr = tt.remoteAddr
 			if tt.xff != "" {
 				r.Header.Set("X-Forwarded-For", tt.xff)
 			}
 			if tt.xri != "" {
 				r.Header.Set("X-Real-IP", tt.xri)
 			}
 			got := GetClientIP(r)
 			if got != tt.want {
 				t.Errorf("GetClientIP() = %q, want %q", got, tt.want)
 			}
 		})
 	}
 	// 重置为默认,避免影响其他测试或运行时行为
 	trustedProxyHops = 0
 }
@@ -1,75 +1,28 @@
 package router
 import (
 	_ "embed"
 	"net/http"
 	"strings"
 	"github.com/gorilla/mux"
 	"github.com/volcano-tts/tts-api/controller"
 	"github.com/volcano-tts/tts-api/installer"
 	"github.com/volcano-tts/tts-api/metrics"
 	"github.com/volcano-tts/tts-api/middleware"
 )
 //go:embed health.html
 var dashboardHTML []byte
 //go:embed setup.html
 var setupHTML []byte
 // Setup 返回主路由。
 // 中间件顺序(由外向内):
 //   SecurityHeaders → InstallGuard → RateLimit → ConcurrencyLimit → Logger → handler
 // 关键: InstallGuard 必须在 RateLimit 之前,避免安装模式被限流计数污染。
 func Setup() *mux.Router {
 	r := mux.NewRouter()
 	r.Use(middleware.SecurityHeaders)
 	r.Use(middleware.InstallGuard(installer.GetMode))
 	r.Use(middleware.RateLimitWithMetrics)
 	r.Use(middleware.ConcurrencyLimitWithMetrics)
 	r.Use(middleware.Logger)
 	// mux 的 NotFoundHandler 不会走 r.Use() 中间件链,
 	// 所以 InstallGuard 的内容协商在 404 路径上不生效。
 	// 手动设一个:安装模式 + 浏览器访问任意未注册路径 → 302 跳 /setup。
 	r.NotFoundHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if installer.GetMode() == installer.ModeSetup && acceptsHTML(r.Header.Get("Accept")) {
 			http.Redirect(w, r, "/setup", http.StatusFound)
 			return
 		}
 		http.NotFound(w, r)
 	})
 	// 安装相关路由(InstallGuard 已在 setup 模式放行;完成后由 controller 二次校验 404)
 	// /setup 页面本身:装完后必须不可用,否则用户敲 /setup 还会看到安装表单,容易误以为要重装。
 	// 装后跳 /admin(M2 之后才有;目前会 404,这是预期,比继续显示表单好)。
 	r.HandleFunc("/setup", func(w http.ResponseWriter, r *http.Request) {
 		if installer.GetMode() == installer.ModeNormal {
 			http.Redirect(w, r, "/admin", http.StatusFound)
 			return
 		}
 		w.Header().Set("Content-Type", "text/html; charset=utf-8")
 		_, _ = w.Write(setupHTML)
 	}).Methods("GET")
 	r.HandleFunc("/api/setup/status", controller.SetupStatusHandler).Methods("GET")
 	r.HandleFunc("/api/setup/prefill", controller.SetupPrefillHandler).Methods("GET")
 	r.HandleFunc("/api/setup", controller.SetupSubmitHandler).Methods("POST")
 	// 业务路由
 	r.HandleFunc("/v1/audio/speech", controller.OpenaiTTSHandler).Methods("POST", "OPTIONS")
 	r.HandleFunc("/health", controller.HealthHandler).Methods("GET")
 	r.HandleFunc("/dashboard", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		http.ServeFile(w, r, "health.html")
 		_, _ = w.Write(dashboardHTML)
 	}).Methods("GET")
 	r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 		// 安装模式下,根路径跳 /setup(给运维一个明显入口)
 		if installer.GetMode() == installer.ModeSetup {
 			http.Redirect(w, r, "/setup", http.StatusFound)
 			return
 		}
 		http.Redirect(w, r, "/dashboard", http.StatusFound)
 	}).Methods("GET")
@@ -79,26 +32,3 @@ func Setup() *mux.Router {
 	return r
 }
 // acceptsHTML 在 router 包内复刻一份,middleware 包的版本未导出。
 // 用途:NotFoundHandler 判断浏览器 Accept。
 // 与 middleware.acceptsHTML 行为一致(简单实现,严格匹配 text/html 或 text/*)。
 func acceptsHTML(accept string) bool {
 	if accept == "" {
 		return false
 	}
 	for _, part := range strings.Split(accept, ",") {
 		mt := strings.TrimSpace(part)
 		if mt == "" {
 			continue
 		}
 		if idx := strings.Index(mt, ";"); idx >= 0 {
 			mt = strings.TrimSpace(mt[:idx])
 		}
 		mt = strings.ToLower(mt)
 		if mt == "text/html" || mt == "text/*" {
 			return true
 		}
 	}
 	return false
 }
@@ -1,238 +0,0 @@
 <!DOCTYPE html>
 <html lang="zh-CN">
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>火山 TTS · 安装引导</title>
    <script src="https://cdn.bootcdn.net/ajax/libs/vue/3.4.21/vue.global.prod.js"></script>
    <script src="https://cdn.bootcdn.net/ajax/libs/axios/1.6.7/axios.min.js"></script>
    <style>
        :root {
            --bg: #0b0f1a;
            --bg-card: #131826;
            --bg-elev: #1a2138;
            --border: #232b42;
            --text: #e4e7ee;
            --text-dim: #8a92a6;
            --text-mute: #5a6275;
            --accent: #00d4ff;
            --accent-2: #7b2ff7;
            --success: #22c55e;
            --warning: #f59e0b;
            --danger: #ef4444;
        }
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
            background: var(--bg); color: var(--text);
            min-height: 100vh; padding: 32px 24px; font-size: 14px;
            background-image:
                radial-gradient(ellipse 80% 50% at 50% -20%, rgba(0,212,255,0.08), transparent),
                radial-gradient(ellipse 60% 40% at 80% 100%, rgba(123,47,247,0.06), transparent);
        }
        #app { max-width: 760px; margin: 0 auto; }
        .header { display: flex; align-items: center; gap: 16px; margin-bottom: 28px; }
        .logo {
            width: 48px; height: 48px; border-radius: 12px;
            background: linear-gradient(135deg, var(--accent), var(--accent-2));
            display: flex; align-items: center; justify-content: center;
            font-weight: 700; font-size: 20px; color: #fff; box-shadow: 0 4px 20px rgba(0,212,255,0.3);
        }
        .header h1 { font-size: 22px; font-weight: 600; }
        .header .sub { font-size: 12px; color: var(--text-dim); margin-top: 4px; }
        .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 24px; margin-bottom: 16px; }
        .card-title { font-size: 15px; font-weight: 600; margin-bottom: 4px; }
        .card-desc { font-size: 12px; color: var(--text-dim); margin-bottom: 16px; }
        .field { margin-bottom: 14px; }
        .field label { display: block; font-size: 12px; color: var(--text-dim); margin-bottom: 6px; }
        .field label .req { color: var(--danger); margin-left: 4px; }
        .field input, .field select {
            width: 100%; background: var(--bg-elev); border: 1px solid var(--border);
            color: var(--text); padding: 10px 12px; border-radius: 8px; font-size: 13px;
            font-family: inherit; transition: border-color 0.2s;
        }
        .field input:focus, .field select:focus { outline: none; border-color: var(--accent); }
        .field .hint { font-size: 11px; color: var(--text-mute); margin-top: 4px; }
        .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
        .voice-row { display: grid; grid-template-columns: 1fr 1fr 1.4fr 1.2fr 32px; gap: 8px; align-items: center; margin-bottom: 8px; }
        .voice-row input { font-size: 12px; padding: 8px 10px; }
        .voice-row .rm { background: transparent; border: 1px solid var(--border); color: var(--danger); cursor: pointer; padding: 6px; border-radius: 6px; font-size: 14px; }
        .voice-row .rm:hover { border-color: var(--danger); }
        .btn {
            background: var(--bg-elev); border: 1px solid var(--border); color: var(--text);
            padding: 10px 18px; border-radius: 8px; cursor: pointer; font-size: 13px;
            transition: all 0.2s; display: inline-flex; align-items: center; gap: 6px;
            font-family: inherit;
        }
        .btn:hover { border-color: var(--accent); }
        .btn-primary { background: var(--accent); color: #00121a; border-color: var(--accent); font-weight: 500; }
        .btn-primary:hover { background: #33ddff; }
        .btn-primary:disabled { background: var(--text-mute); border-color: var(--text-mute); cursor: not-allowed; color: var(--bg); }
        .btn-add { background: transparent; border: 1px dashed var(--border); color: var(--text-dim); width: 100%; justify-content: center; padding: 10px; }
        .btn-add:hover { border-color: var(--accent); color: var(--accent); }
        .actions { display: flex; justify-content: space-between; align-items: center; margin-top: 24px; }
        .err { color: var(--danger); font-size: 12px; margin-top: 8px; }
        .ok { color: var(--success); font-size: 12px; margin-top: 8px; }
        .banner { background: rgba(245,158,11,0.1); border: 1px solid rgba(245,158,11,0.3); border-radius: 8px; padding: 10px 14px; color: var(--warning); font-size: 12px; margin-bottom: 16px; }
    </style>
 </head>
 <body>
    <div id="app">
        <div class="header">
            <div class="logo">TTS</div>
            <div>
                <h1>火山 TTS 聚合平台 · 首次安装</h1>
                <div class="sub">填写以下信息完成初始化。token 来自启动日志或环境变量 <code>TTS_ADMIN_KEY</code>。</div>
            </div>
        </div>
        <div v-if="errorMsg" class="banner">⚠ {{ errorMsg }}</div>
        <div class="card">
            <div class="card-title">火山引擎 TTS 凭证</div>
            <div class="card-desc">从火山引擎控制台获取,API Key 仅在此页面输入,不会回显。</div>
            <div class="field">
                <label>API Key <span class="req">*</span></label>
                <input type="password" v-model="form.api_key" placeholder="例如: 5b4d7c2a-..." autocomplete="off">
            </div>
            <div class="field-row">
                <div class="field">
                    <label>默认资源 ID <span class="req">*</span></label>
                    <input v-model="form.default_resource_id" placeholder="volc.megatts.default">
                    <div class="hint">音色所属的计费资源 ID;volc.megatts.icl 用于复刻音色。</div>
                </div>
                <div class="field">
                    <label>默认音色 <span class="req">*</span></label>
                    <input v-model="form.default_speaker" placeholder="zh_female_qingxin">
                    <div class="hint">未传 voice 字段时使用。</div>
                </div>
            </div>
            <div class="field-row">
                <div class="field">
                    <label>默认输出格式</label>
                    <select v-model="form.default_format">
                        <option value="mp3">mp3</option>
                        <option value="wav">wav</option>
                        <option value="opus">opus (ogg_opus)</option>
                        <option value="pcm">pcm</option>
                        <option value="aac">aac</option>
                        <option value="flac">flac</option>
                    </select>
                </div>
                <div class="field">
                    <label>采样率 (Hz)</label>
                    <input type="number" v-model.number="form.sample_rate" placeholder="24000">
                </div>
            </div>
            <div class="field">
                <label>初始化 Token <span class="req">*</span></label>
                <input type="password" v-model="form.token" placeholder="启动日志里打印的一次性 token,或 TTS_ADMIN_KEY" autocomplete="off">
                <div class="hint">公网部署建议设置 TTS_ADMIN_KEY;否则每次启动会重新生成。</div>
            </div>
        </div>
        <div class="card">
            <div class="card-title">音色列表 <span style="font-weight: 400; color: var(--text-dim); font-size: 12px;">(至少 1 条)</span></div>
            <div class="card-desc">填入火山 TTS 音色 ID(S_ 开头的为复刻音色)。可后续在 /admin 中增删。</div>
            <div v-for="(v, i) in form.voices" :key="i" class="voice-row">
                <input v-model="v.name" placeholder="对外名 qian">
                <input v-model="v.speaker" placeholder="S_xxx">
                <input v-model="v.resource_id" placeholder="volc.megatts.icl">
                <input v-model="v.model" placeholder="seed-tts-2.0-standard">
                <button class="rm" @click="removeVoice(i)" :disabled="form.voices.length <= 1" title="删除">×</button>
            </div>
            <button class="btn btn-add" @click="addVoice">+ 添加音色</button>
        </div>
        <div class="actions">
            <div style="color: var(--text-mute); font-size: 12px;">
                提交后立即进入正常模式;后续管理请访问 <code>/admin</code>。
            </div>
            <button class="btn btn-primary" @click="submit" :disabled="submitting">
                {{ submitting ? '安装中...' : '完成安装' }}
            </button>
        </div>
    </div>
    <script>
    const { createApp, ref, onMounted } = Vue;
    createApp({
        setup() {
            const form = ref({
                api_key: '',
                default_resource_id: 'volc.megatts.default',
                default_speaker: '',
                default_format: 'mp3',
                sample_rate: 24000,
                token: '',
                voices: [{ name: '', speaker: '', resource_id: 'volc.megatts.icl', model: 'seed-tts-2.0-standard' }],
            });
            const errorMsg = ref('');
            const submitting = ref(false);
            const addVoice = () => {
                form.value.voices.push({ name: '', speaker: '', resource_id: 'volc.megatts.icl', model: 'seed-tts-2.0-standard' });
            };
            const removeVoice = (i) => {
                if (form.value.voices.length > 1) form.value.voices.splice(i, 1);
            };
            onMounted(async () => {
                // 预填旧 env 变量(只填非空字段;api_key 永不预填,需手动输入)
                try {
                    const r = await axios.get('/api/setup/prefill');
                    const s = r.data.settings || {};
                    if (s.default_resource_id) form.value.default_resource_id = s.default_resource_id;
                    if (s.default_speaker) form.value.default_speaker = s.default_speaker;
                    if (s.default_format) form.value.default_format = s.default_format;
                    if (s.sample_rate) form.value.sample_rate = parseInt(s.sample_rate, 10) || 24000;
                } catch (e) {
                    console.log('prefill skipped:', e.message);
                }
            });
            const submit = async () => {
                errorMsg.value = '';
                if (!form.value.api_key || !form.value.default_resource_id || !form.value.default_speaker || !form.value.token) {
                    errorMsg.value = '请填写所有必填项(API Key / 资源 ID / 默认音色 / Token)';
                    return;
                }
                if (!form.value.voices.length || form.value.voices.some(v => !v.name || !v.speaker || !v.resource_id)) {
                    errorMsg.value = '音色列表不完整(每条都需要 name + speaker + resource_id)';
                    return;
                }
                submitting.value = true;
                try {
                    const r = await axios.post('/api/setup', {
                        token: form.value.token,
                        settings: {
                            api_key: form.value.api_key,
                            default_resource_id: form.value.default_resource_id,
                            default_speaker: form.value.default_speaker,
                            default_format: form.value.default_format,
                            sample_rate: String(form.value.sample_rate || 24000),
                        },
                        voices: form.value.voices,
                    });
                    // 成功:跳 /admin(M2 才会有,先跳 /dashboard)
                    window.location.href = r.data.redirect || '/dashboard';
                } catch (e) {
                    const msg = e.response?.data?.error?.message || e.message;
                    errorMsg.value = `安装失败: ${msg}`;
                    submitting.value = false;
                }
            };
            return { form, errorMsg, submitting, addVoice, removeVoice, submit };
        },
    }).mount('#app');
    </script>
 </body>
 </html>
@@ -1,8 +1,6 @@
 package setting
 import (
 	"crypto/rand"
 	"encoding/hex"
 	"fmt"
 	"log"
 	"os"
@@ -53,26 +51,11 @@ var Server ServerConfig
 // 不直接调用 middleware(避免循环 import)。
 var TrustedProxyHops int
 // SetupToken 是安装模式下的初始化凭证。
 //   - 若 TTS_ADMIN_KEY 环境变量非空,用其值(用户可复现,便于脚本化安装)
 //   - 若 TTS_ADMIN_KEY 为空,启动时随机生成 32 字节十六进制,
 //     打印到日志(/api/setup 提交时必须带这个 token)
 //
 // 安装完成后,/api/setup 端点永久关闭,SetupToken 失去意义但保留在内存。
 var SetupToken string
 // SetupTokenSource 标记 SetupToken 的来源,便于日志区分。
 //   "env"      = 来自 TTS_ADMIN_KEY
 //   "ephemeral"= 启动时随机生成(每次启动变)
 //   ""         = 未设置
 var SetupTokenSource string
 // InitAllConfigs 集中初始化所有配置,启动期调用一次。
 func InitAllConfigs() {
 	InitServerConfig()
 	InitAuthConfig()
 	InitCORSConfig()
 	InitSetupToken()
 	TTSConfigErr = InitTTSConfig()
 }
@@ -230,30 +213,6 @@ func getEnvBool(name string, def bool) bool {
 	return b
 }
 // InitSetupToken 加载或生成安装模式下的初始化凭证。
 //   - TTS_ADMIN_KEY 存在:用其值,SetupTokenSource="env"
 //   - TTS_ADMIN_KEY 空:随机生成 16 字节 = 32 字符 hex,SetupTokenSource="ephemeral",打印到日志
 func InitSetupToken() {
 	v := os.Getenv("TTS_ADMIN_KEY")
 	if v != "" {
 		SetupToken = v
 		SetupTokenSource = "env"
 		return
 	}
 	// 临时 token:16 字节随机 = 32 字符 hex,够用且短
 	b := make([]byte, 16)
 	if _, err := rand.Read(b); err != nil {
 		// 极端情况:随机源失败,降级为时间戳(不应发生)
 		log.Printf("[setup] 生成一次性 token 失败,使用时间戳: %v", err)
 		SetupToken = fmt.Sprintf("dev-%d", time.Now().UnixNano())
 		SetupTokenSource = "ephemeral"
 		return
 	}
 	SetupToken = hex.EncodeToString(b)
 	SetupTokenSource = "ephemeral"
 	log.Printf("[setup] 一次性安装 token(仅打印一次,公网部署请设置 TTS_ADMIN_KEY): %s", SetupToken)
 }
 // CheckEnvironmentVariables 返回 /health 用的环境变量状态快照。
 func CheckEnvironmentVariables() map[string]interface{} {
 	required := map[string]bool{
@@ -350,3 +309,10 @@ func maskAPIKey(key string) string {
 	}
 	return key[:4] + "****" + key[len(key)-4:]
 }
 // CheckStaticFiles 检查 /dashboard 路由依赖的 health.html 是否存在。
 func CheckStaticFiles() {
 	if _, err := os.Stat("health.html"); os.IsNotExist(err) {
 		log.Println("警告: health.html 不存在,/dashboard 路由将返回 404")
 	}
 }
@@ -1,153 +0,0 @@
 // Package store 负责 SQLite 访问层:打开/建表/迁移、settings/voices CRUD、
 // 完整性校验。所有运行时可变配置(全局参数 + 音色库)统一落 SQLite,
 // 环境变量仅作引导参数(TTS_DB_PATH 等)。
 //
 // 设计约束:
 //   - 单二进制分发,纯 Go SQLite(modernc.org/sqlite),CGO_ENABLED=0
 //   - 单用户自用,SetMaxOpenConns(1) 避免并发写竞争
 //   - 所有 SQL 参数化,严禁字符串拼接
 //   - schema_version 表保留未来升级钩子
 package store
 import (
 	"database/sql"
 	"fmt"
 	_ "modernc.org/sqlite" // 注册 sqlite driver
 )
 // schemaVersion 是当前 schema 版本号;每次结构性变更 +1。
 // migrate.go 负责在 Open 时按版本号增量应用。
 const schemaVersion = 1
 // Store 是 SQLite 访问层的统一入口;所有 settings/voices 操作都通过它。
 type Store struct {
 	db *sql.DB
 }
 // Open 打开或创建 SQLite 数据库,自动应用建表与迁移。
 // path 推荐为绝对路径;空字符串会落到临时目录,不应用于生产。
 func Open(path string) (*Store, error) {
 	// modernc.org/sqlite 注册名:"sqlite" + "sqlite3" 两种
 	// _dsn 参数控制 journal_mode 等;这里先打开,再用 PRAGMA 调整
 	db, err := sql.Open("sqlite", path)
 	if err != nil {
 		return nil, fmt.Errorf("store: open %q failed: %w", path, err)
 	}
 	// 单用户自用场景,避免并发写竞争
 	db.SetMaxOpenConns(1)
 	// PRAGMA 需要连接,触发一次 Ping 拿连接
 	if _, err := db.Exec(`PRAGMA journal_mode = WAL`); err != nil {
 		_ = db.Close()
 		return nil, fmt.Errorf("store: enable WAL failed: %w", err)
 	}
 	if _, err := db.Exec(`PRAGMA foreign_keys = ON`); err != nil {
 		_ = db.Close()
 		return nil, fmt.Errorf("store: enable foreign_keys failed: %w", err)
 	}
 	if _, err := db.Exec(`PRAGMA synchronous = NORMAL`); err != nil {
 		_ = db.Close()
 		return nil, fmt.Errorf("store: enable synchronous=NORMAL failed: %w", err)
 	}
 	s := &Store{db: db}
 	if err := s.migrate(); err != nil {
 		_ = db.Close()
 		return nil, fmt.Errorf("store: migrate failed: %w", err)
 	}
 	return s, nil
 }
 // Close 关闭底层连接;调用方应保证只 Close 一次。
 func (s *Store) Close() error {
 	if s == nil || s.db == nil {
 		return nil
 	}
 	return s.db.Close()
 }
 // DB 返回底层 *sql.DB,仅供 store 包内或集成测试使用;
 // 业务代码不应直接拿连接,所有操作走 Store 暴露的方法。
 func (s *Store) DB() *sql.DB { return s.db }
 // IntegrityCheck 执行 PRAGMA integrity_check;返回 "ok" 即视为库健康。
 // installer 包据此判定是否触发损坏回退。
 func (s *Store) IntegrityCheck() (string, error) {
 	row := s.db.QueryRow(`PRAGMA integrity_check`)
 	var result string
 	if err := row.Scan(&result); err != nil {
 		return "", fmt.Errorf("store: integrity_check scan failed: %w", err)
 	}
 	return result, nil
 }
 // Path 返回当前 db 的 SQLite 报告路径(用于日志)。
 // 通过 PRAGMA database_list 拿权威值,避免和入参 path 不一致时的混淆。
 func (s *Store) Path() (string, error) {
 	rows, err := s.db.Query(`PRAGMA database_list`)
 	if err != nil {
 		return "", fmt.Errorf("store: database_list query failed: %w", err)
 	}
 	defer rows.Close()
 	if !rows.Next() {
 		return "", fmt.Errorf("store: database_list returned no rows")
 	}
 	var seq int
 	var name, file string
 	if err := rows.Scan(&seq, &name, &file); err != nil {
 		return "", fmt.Errorf("store: database_list scan failed: %w", err)
 	}
 	return file, nil
 }
 // migrate 应用 schema 迁移。当前 schema_version=1,只做基础建表。
 // 未来升级:写 applyMigration(n) 函数,n 为目标版本号。
 func (s *Store) migrate() error {
 	// schema_version 表记录当前版本
 	if _, err := s.db.Exec(`
 		CREATE TABLE IF NOT EXISTS schema_version (
 			version    INTEGER PRIMARY KEY,
 			applied_at TEXT NOT NULL DEFAULT (datetime('now'))
 		)`); err != nil {
 		return fmt.Errorf("create schema_version: %w", err)
 	}
 	// settings 表(全局配置)
 	if _, err := s.db.Exec(`
 		CREATE TABLE IF NOT EXISTS settings (
 			key        TEXT PRIMARY KEY,
 			value      TEXT NOT NULL,
 			updated_at TEXT NOT NULL DEFAULT (datetime('now'))
 		)`); err != nil {
 		return fmt.Errorf("create settings: %w", err)
 	}
 	// voices 表(音色库)
 	if _, err := s.db.Exec(`
 		CREATE TABLE IF NOT EXISTS voices (
 			id          INTEGER PRIMARY KEY AUTOINCREMENT,
 			name        TEXT NOT NULL UNIQUE,
 			speaker     TEXT NOT NULL,
 			resource_id TEXT NOT NULL,
 			model       TEXT DEFAULT '',
 			language    TEXT DEFAULT '',
 			description TEXT DEFAULT '',
 			enabled     INTEGER NOT NULL DEFAULT 1,
 			created_at  TEXT NOT NULL DEFAULT (datetime('now')),
 			updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
 		)`); err != nil {
 		return fmt.Errorf("create voices: %w", err)
 	}
 	if _, err := s.db.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_voices_name ON voices(name)`); err != nil {
 		return fmt.Errorf("create idx_voices_name: %w", err)
 	}
 	// 当前版本
 	if _, err := s.db.Exec(`
 		INSERT OR IGNORE INTO schema_version (version) VALUES (?)`, schemaVersion); err != nil {
 		return fmt.Errorf("insert schema_version: %w", err)
 	}
 	return nil
 }
@@ -1,27 +0,0 @@
 package store
 // schema 版本号演进与迁移函数注册表。
 //
 // 用法:每次结构性变更时 +1 schemaVersion 常量,并在 migrations 切片中追加 applyV<n>。
 // migrate.go 会在 Open 时按版本号顺序应用。
 //
 // 注意:本文件留作未来扩展,本期 M0 阶段 schemaVersion=1,migrate() 在 db.go
 // 内做基础建表,未触发 migrations 调度。切到 v2 时再启用。
 // Migration 是从 version N-1 升级到 N 的迁移函数。
 type Migration struct {
 	From int
 	To   int
 	Fn   func(tx interface{ Exec(query string, args ...any) (any, error) }) error
 }
 // migrations 是按 From 升序排列的迁移列表;首条 From 必须等于 1。
 // 留作占位,本期为空。
 var migrations = []Migration{}
 // schemaVersionRequested 是期望的 schema 版本号;db.go 里直接写常量。
 // 这里留个常量引用便于未来从 db.go 解耦。
 const schemaVersionRequested = 1
 // CurrentVersion 返回当前代码期望的 schema 版本。
 func CurrentVersion() int { return schemaVersionRequested }
@@ -1,175 +0,0 @@
 package store
 import (
 	"database/sql"
 	"errors"
 	"fmt"
 	"strconv"
 	"time"
 )
 // SettingsKey 是 settings 表的合法键白名单;防止上游拼写错误静默落库。
 // 留空 hash 表示允许任意键;严格模式时把允许的键填进来。
 //
 // 本期(M0)使用宽松模式:任何非空字符串键都可以写入。
 // 收紧时把对应键填入 allowedSettingsKeys 即可。
 var allowedSettingsKeys = map[string]struct{}{}
 // SettingsAccess 返回单条配置;键不存在返回 ("", false, nil)。
 // 第二返回值表示键是否存在,便于上层区分"未设置"和"值为空串"。
 func (s *Store) SettingsGet(key string) (string, bool, error) {
 	if key == "" {
 		return "", false, fmt.Errorf("store: settings key is empty")
 	}
 	row := s.db.QueryRow(`SELECT value FROM settings WHERE key = ?`, key)
 	var v string
 	err := row.Scan(&v)
 	if errors.Is(err, sql.ErrNoRows) {
 		return "", false, nil
 	}
 	if err != nil {
 		return "", false, fmt.Errorf("store: settings get %q: %w", key, err)
 	}
 	return v, true, nil
 }
 // SettingsSet 写入单条配置;空值会删除该键(SQLite 没 NULL 写法更直观)。
 func (s *Store) SettingsSet(key, value string) error {
 	if key == "" {
 		return fmt.Errorf("store: settings key is empty")
 	}
 	if !isAllowedSettingsKey(key) {
 		return fmt.Errorf("store: settings key %q not in whitelist", key)
 	}
 	_, err := s.db.Exec(`
 		INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
 		ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
 		key, value)
 	if err != nil {
 		return fmt.Errorf("store: settings set %q: %w", key, err)
 	}
 	return nil
 }
 // SettingsDelete 显式删除单条键;键不存在不报错。
 func (s *Store) SettingsDelete(key string) error {
 	if key == "" {
 		return fmt.Errorf("store: settings key is empty")
 	}
 	_, err := s.db.Exec(`DELETE FROM settings WHERE key = ?`, key)
 	if err != nil {
 		return fmt.Errorf("store: settings delete %q: %w", key, err)
 	}
 	return nil
 }
 // SettingsGetAll 返回所有配置;按 key 升序。
 func (s *Store) SettingsGetAll() (map[string]string, error) {
 	rows, err := s.db.Query(`SELECT key, value FROM settings ORDER BY key`)
 	if err != nil {
 		return nil, fmt.Errorf("store: settings getall: %w", err)
 	}
 	defer rows.Close()
 	out := make(map[string]string)
 	for rows.Next() {
 		var k, v string
 		if err := rows.Scan(&k, &v); err != nil {
 			return nil, fmt.Errorf("store: settings getall scan: %w", err)
 		}
 		out[k] = v
 	}
 	if err := rows.Err(); err != nil {
 		return nil, fmt.Errorf("store: settings getall rows: %w", err)
 	}
 	return out, nil
 }
 // SettingsSetBatch 一次性写入多对;保留单事务原子性,失败整体回滚。
 // 适合 /api/setup 一次性写入全局配置。
 func (s *Store) SettingsSetBatch(kv map[string]string) error {
 	if len(kv) == 0 {
 		return nil
 	}
 	tx, err := s.db.Begin()
 	if err != nil {
 		return fmt.Errorf("store: settings setbatch begin: %w", err)
 	}
 	stmt, err := tx.Prepare(`
 		INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
 		ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
 	if err != nil {
 		_ = tx.Rollback()
 		return fmt.Errorf("store: settings setbatch prepare: %w", err)
 	}
 	for k, v := range kv {
 		if k == "" {
 			_ = tx.Rollback()
 			return fmt.Errorf("store: settings setbatch: empty key")
 		}
 		if !isAllowedSettingsKey(k) {
 			_ = tx.Rollback()
 			return fmt.Errorf("store: settings setbatch: key %q not in whitelist", k)
 		}
 		if _, err := stmt.Exec(k, v); err != nil {
 			_ = stmt.Close()
 			_ = tx.Rollback()
 			return fmt.Errorf("store: settings setbatch exec %q: %w", k, err)
 		}
 	}
 	if err := stmt.Close(); err != nil {
 		_ = tx.Rollback()
 		return fmt.Errorf("store: settings setbatch close stmt: %w", err)
 	}
 	if err := tx.Commit(); err != nil {
 		return fmt.Errorf("store: settings setbatch commit: %w", err)
 	}
 	return nil
 }
 // SettingsGetInt 返回整型配置,带默认值;键不存在或解析失败时回退到 def。
 func (s *Store) SettingsGetInt(key string, def int) (int, error) {
 	v, ok, err := s.SettingsGet(key)
 	if err != nil || !ok {
 		return def, err
 	}
 	n, err := strconv.Atoi(v)
 	if err != nil {
 		return def, nil // 解析失败静默回退,不污染调用方
 	}
 	return n, nil
 }
 // SettingsGetBool 返回 bool 配置,接受 "1"/"true"/"t"/"TRUE" 等;
 func (s *Store) SettingsGetBool(key string, def bool) (bool, error) {
 	v, ok, err := s.SettingsGet(key)
 	if err != nil || !ok {
 		return def, err
 	}
 	b, err := strconv.ParseBool(v)
 	if err != nil {
 		return def, nil
 	}
 	return b, nil
 }
 // SettingsGetDuration 返回 duration 配置;支持 "30s" "5m" "1h" 等。
 func (s *Store) SettingsGetDuration(key string, def time.Duration) (time.Duration, error) {
 	v, ok, err := s.SettingsGet(key)
 	if err != nil || !ok {
 		return def, err
 	}
 	d, err := time.ParseDuration(v)
 	if err != nil {
 		return def, nil
 	}
 	return d, nil
 }
 // isAllowedSettingsKey 检查 key 是否在白名单;白名单空时全放行。
 func isAllowedSettingsKey(key string) bool {
 	if len(allowedSettingsKeys) == 0 {
 		return true
 	}
 	_, ok := allowedSettingsKeys[key]
 	return ok
 }
@@ -1,277 +0,0 @@
 package store
 import (
 	"database/sql"
 	"errors"
 	"fmt"
 	"regexp"
 	"strings"
 	"time"
 )
 // Voice 是一行音色记录;时间字段保持 ISO8601 字符串(SQLite TEXT 默认)。
 type Voice struct {
 	ID          int64
 	Name        string
 	Speaker     string
 	ResourceID  string
 	Model       string
 	Language    string
 	Description string
 	Enabled     bool
 	CreatedAt   string
 	UpdatedAt   string
 }
 // ErrDuplicate 表示 name 唯一冲突;controller 翻译为 409。
 var ErrDuplicate = errors.New("store: voice name already exists")
 // ErrInUse 表示试图删除被 default_speaker 引用的音色;controller 翻译为 409。
 var ErrInUse = errors.New("store: voice is referenced by default_speaker")
 // ErrNotFound 表示按 id/name 找不到;controller 翻译为 404。
 var ErrNotFound = errors.New("store: voice not found")
 // voiceNameRe 限制 voice 名为 [a-zA-Z0-9_-]{1,64};SQL 注入 + 路径穿越防护。
 var voiceNameRe = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
 // VoiceList 列出所有音色;includeDisabled=false 时只返回 enabled=1。
 // 按 id 升序,稳定顺序便于前端展示。
 func (s *Store) VoiceList(includeDisabled bool) ([]Voice, error) {
 	q := `SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
 	      FROM voices`
 	if !includeDisabled {
 		q += ` WHERE enabled = 1`
 	}
 	q += ` ORDER BY id ASC`
 	rows, err := s.db.Query(q)
 	if err != nil {
 		return nil, fmt.Errorf("store: voice list: %w", err)
 	}
 	defer rows.Close()
 	out := make([]Voice, 0, 8)
 	for rows.Next() {
 		v, err := scanVoice(rows)
 		if err != nil {
 			return nil, err
 		}
 		out = append(out, v)
 	}
 	if err := rows.Err(); err != nil {
 		return nil, fmt.Errorf("store: voice list rows: %w", err)
 	}
 	return out, nil
 }
 // VoiceGet 按 id 查;未命中返回 ErrNotFound。
 func (s *Store) VoiceGet(id int64) (*Voice, error) {
 	row := s.db.QueryRow(`SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
 	                     FROM voices WHERE id = ?`, id)
 	v, err := scanVoice(row)
 	if errors.Is(err, sql.ErrNoRows) {
 		return nil, ErrNotFound
 	}
 	if err != nil {
 		return nil, fmt.Errorf("store: voice get id=%d: %w", id, err)
 	}
 	return &v, nil
 }
 // VoiceGetByName 按 name 查;未命中返回 ErrNotFound。
 // tts.go 路由用这个,要求 name 走参数化查询。
 func (s *Store) VoiceGetByName(name string) (*Voice, error) {
 	row := s.db.QueryRow(`SELECT id, name, speaker, resource_id, model, language, description, enabled, created_at, updated_at
 	                     FROM voices WHERE name = ?`, name)
 	v, err := scanVoice(row)
 	if errors.Is(err, sql.ErrNoRows) {
 		return nil, ErrNotFound
 	}
 	if err != nil {
 		return nil, fmt.Errorf("store: voice getbyname %q: %w", name, err)
 	}
 	return &v, nil
 }
 // VoiceInsert 新增音色;name 冲突返回 ErrDuplicate。
 // 空字符串/格式不合法返回 error;不依赖 SQLite 约束作为唯一校验。
 func (s *Store) VoiceInsert(v Voice) (int64, error) {
 	v.Name = strings.TrimSpace(v.Name)
 	v.Speaker = strings.TrimSpace(v.Speaker)
 	v.ResourceID = strings.TrimSpace(v.ResourceID)
 	v.Model = strings.TrimSpace(v.Model)
 	v.Language = strings.TrimSpace(v.Language)
 	v.Description = strings.TrimSpace(v.Description)
 	if err := validateVoiceName(v.Name); err != nil {
 		return 0, err
 	}
 	if v.Speaker == "" {
 		return 0, fmt.Errorf("store: voice insert: speaker is required")
 	}
 	if v.ResourceID == "" {
 		return 0, fmt.Errorf("store: voice insert: resource_id is required")
 	}
 	res, err := s.db.Exec(`
 		INSERT INTO voices (name, speaker, resource_id, model, language, description, enabled, created_at, updated_at)
 		VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))`,
 		v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled))
 	if err != nil {
 		if isUniqueViolation(err) {
 			return 0, ErrDuplicate
 		}
 		return 0, fmt.Errorf("store: voice insert: %w", err)
 	}
 	id, err := res.LastInsertId()
 	if err != nil {
 		return 0, fmt.Errorf("store: voice insert lastid: %w", err)
 	}
 	return id, nil
 }
 // VoiceUpdate 整行替换;name 仍需保持唯一。
 // 不允许把 name 改成空/不合法。
 func (s *Store) VoiceUpdate(v Voice) error {
 	v.Name = strings.TrimSpace(v.Name)
 	v.Speaker = strings.TrimSpace(v.Speaker)
 	v.ResourceID = strings.TrimSpace(v.ResourceID)
 	v.Model = strings.TrimSpace(v.Model)
 	v.Language = strings.TrimSpace(v.Language)
 	v.Description = strings.TrimSpace(v.Description)
 	if err := validateVoiceName(v.Name); err != nil {
 		return err
 	}
 	if v.Speaker == "" {
 		return fmt.Errorf("store: voice update: speaker is required")
 	}
 	if v.ResourceID == "" {
 		return fmt.Errorf("store: voice update: resource_id is required")
 	}
 	res, err := s.db.Exec(`
 		UPDATE voices SET name=?, speaker=?, resource_id=?, model=?, language=?, description=?, enabled=?, updated_at=datetime('now')
 		WHERE id = ?`,
 		v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled), v.ID)
 	if err != nil {
 		if isUniqueViolation(err) {
 			return ErrDuplicate
 		}
 		return fmt.Errorf("store: voice update id=%d: %w", v.ID, err)
 	}
 	n, _ := res.RowsAffected()
 	if n == 0 {
 		return ErrNotFound
 	}
 	return nil
 }
 // VoiceDelete 按 id 删;若被 settings.default_speaker 引用则返回 ErrInUse。
 func (s *Store) VoiceDelete(id int64) error {
 	v, err := s.VoiceGet(id)
 	if err != nil {
 		return err
 	}
 	// 检查 default_speaker 引用
 	defVal, defOK, err := s.SettingsGet("default_speaker")
 	if err != nil {
 		return err
 	}
 	if defOK && defVal == v.Name {
 		return ErrInUse
 	}
 	res, err := s.db.Exec(`DELETE FROM voices WHERE id = ?`, id)
 	if err != nil {
 		return fmt.Errorf("store: voice delete id=%d: %w", id, err)
 	}
 	n, _ := res.RowsAffected()
 	if n == 0 {
 		return ErrNotFound
 	}
 	return nil
 }
 // VoiceToggleEnabled 翻转启用状态;返回更新后的值。
 func (s *Store) VoiceToggleEnabled(id int64, enabled bool) error {
 	res, err := s.db.Exec(`UPDATE voices SET enabled=?, updated_at=datetime('now') WHERE id = ?`,
 		boolToInt(enabled), id)
 	if err != nil {
 		return fmt.Errorf("store: voice toggle id=%d: %w", id, err)
 	}
 	n, _ := res.RowsAffected()
 	if n == 0 {
 		return ErrNotFound
 	}
 	return nil
 }
 // VoiceCount 统计行数;M2 仪表盘用。
 func (s *Store) VoiceCount() (int, error) {
 	var n int
 	err := s.db.QueryRow(`SELECT COUNT(*) FROM voices`).Scan(&n)
 	if err != nil {
 		return 0, fmt.Errorf("store: voice count: %w", err)
 	}
 	return n, nil
 }
 // VoiceCountEnabled 统计 enabled=1 的行数;仪表盘用。
 func (s *Store) VoiceCountEnabled() (int, error) {
 	var n int
 	err := s.db.QueryRow(`SELECT COUNT(*) FROM voices WHERE enabled = 1`).Scan(&n)
 	if err != nil {
 		return 0, fmt.Errorf("store: voice count enabled: %w", err)
 	}
 	return n, nil
 }
 // scanVoice 把 row 扫描成 Voice;接受 *sql.Row 或 *sql.Rows(都实现 Scan)。
 type scanner interface {
 	Scan(dest ...any) error
 }
 func scanVoice(r scanner) (Voice, error) {
 	var v Voice
 	var enabled int
 	err := r.Scan(&v.ID, &v.Name, &v.Speaker, &v.ResourceID, &v.Model, &v.Language, &v.Description, &enabled, &v.CreatedAt, &v.UpdatedAt)
 	if err != nil {
 		return v, err
 	}
 	v.Enabled = enabled != 0
 	return v, nil
 }
 func validateVoiceName(name string) error {
 	if name == "" {
 		return fmt.Errorf("store: voice name is required")
 	}
 	if !voiceNameRe.MatchString(name) {
 		return fmt.Errorf("store: voice name %q invalid (must match [a-zA-Z0-9_-]{1,64})", name)
 	}
 	return nil
 }
 func boolToInt(b bool) int {
 	if b {
 		return 1
 	}
 	return 0
 }
 // isUniqueViolation 判定 SQLite 唯一约束错误。
 // modernc.org/sqlite 错误信息中包含 "UNIQUE constraint failed: <table>.<col>";做大小写不敏感包含判定。
 func isUniqueViolation(err error) bool {
 	if err == nil {
 		return false
 	}
 	msg := strings.ToLower(err.Error())
 	return strings.Contains(msg, "unique constraint failed")
 }
 // VoiceInsertedAt 返回当前时间字符串(UTC, RFC3339);留作未来 Voice 构造时使用,
 // 暂不导出。
 func voiceNow() string { return time.Now().UTC().Format(time.RFC3339) }
Author	SHA1	Message	Date
sun	0d3517eb5c	fix: 安全加固（VUL-001~009）+ 构建版本注入 + 死代码清理' (#2 ) from develop into main Docker Publish / build-and-push (push) Canceled after 0s Details Reviewed-on: #2	2026-08-27 11:01:47 +08:00
sun	d1e7f9a4dd	chore: 删除 ratelimit_middleware.go.tmp 临时文件与 ratelimit_middleware.go 内容完全重复(SHA256 一致,1116 字节), 且无任何代码引用 .tmp 路径,属于误提交的开发期残留文件。	2026-08-23 13:16:17 +08:00
sun	4a8c563b32	Merge branch 'develop' into main 将 develop 分支累积的 51 个提交合入 main,涵盖完整的架构重构与可观测性建设,作为下一阶段对外发布的稳定基线。 ## 主要变更 ### 架构重构 - 将单体 tts_server.go (778 行) 拆分为模块化目录:adapter/volcano、 controller、dto、middleware、router、setting、telemetry、metrics - 引入 OpenAI /v1/audio/speech 兼容接口,火山引擎作为后端适配器 - 统一以 main.go 作为入口,集中启动顺序与信号处理 ### 火山 TTS 适配器 - 重构请求/响应/合成为独立文件 (request.go / response.go / synthesis.go / audio.go),namespace 修正为 UnidirectionalTTS - 适配 v3 模型参数与音色复刻路由 - 兼容上游 sentence 字段对象/字符串两种形态,处理 event 字段缺失 - 新增请求诊断日志,便于排障 ### 可观测性 - 自研轻量 telemetry 库 (counter/gauge/histogram/labels/registry) - 暴露 Prometheus 格式指标,内置 /metrics 端点 - 限流与并发中间件仅统计 /v1/ 路由,避免监控路径污染计数 - 新增 health.html 监控面板,分组展示请求、延迟、限流、字节数等 ### 中间件 - CORS:支持 ALLOWED_ORIGINS 白名单,日志优化 - 限流:令牌桶 + 并发控制,带可观测埋点 - 安全/鉴权:API Key 校验、请求体大小限制 - Logger:统一请求日志,修复中文乱码与换行 ### 配置与启动 - setting/config.go 集中环境变量管理,启动时打印配置摘要 - 配置文件切换到 .env.example,支持音频格式/采样率/调试日志开关 ### 文档与构建 - README 重写,补充 BYTEDANCE_TTS_DEBUG 调试日志小节,移除 1.0 旧内容 - Go 版本升级 1.23 -> 1.26 - 新增 Dockerfile / docker-compose.yml,镜像构建与编排 - 补充 .dockerignore / .gitignore,清理 BOM 头与废弃 tts-api.exe ### 修复 - 修复 response.go switch 大括号结构错误、synthesis.go 类型不匹配 - 修复请求体过大时的处理、冗余代码与日志乱码 - 限流/并发中间件跳过非 /v1/ 路由,避免监控路径污染计数	2026-08-23 10:01:35 +08:00
sun	cd70157aea	ci: 删除无用的 Gitea CI/CD 部署配置文件移除了原本用于部署到宝塔的工作流文件，清理冗余的CI配置	2026-05-19 18:41:59 +08:00
sun	ac614be190	Merge pull request 'test' (#1 ) from test into main Go CI/CD Deploy to Baota / build-and-deploy (push) Has been cancelled Details Reviewed-on: #1	2026-05-18 23:29:21 +08:00
sun	880c199ce4	Reapply "ci: 添加Gitea工作流用于Go项目部署到宝塔" Go CI/CD Deploy to Baota / build-and-deploy (push) Failing after 5m10s Details This reverts commit `25e09cd54f`.	2026-05-11 17:58:28 +08:00