sun/Volcano-Engine-TTS-UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
111 Commits 2 Branches 6 Tags
a2d72efb34c35292376178ede4de0038e7047af7
Commit Graph
30 Commits
Author SHA1 Message Date
sun 9353790899 refactor: 删 trimAll + 修 isSensitive,统一用 stdlib 
两处自实现 / 半成品:

1. controller/settings.go trimAll (11 行)
   - 自己写循环 trim 4 个 ASCII 字符 (' ' \t \n \r)
   - 等价于 strings.TrimSpace (后者 trim 所有 Unicode 空白)
   - strings 包已 import (其他代码用着), 没引用代价
   - 改: 7 个调用点全替, 删函数定义

2. cmd/dumpdb/main.go isSensitive (13 行)
   - 自实现 strings.Contains 循环, 没调 strings.ToLower
   - 变量名叫 lowK 但实际从未小写化
   - Bug: API_KEY / Auth_Token 这类大写 key 不会被判为敏感, 漏打码
   - 修: 用 strings.ToLower + strings.Contains, 大小写不敏感
   - 顺手加 strings import

收益:
- 行数: +15 / -27 (净删 12 行)
- 一致性: 看到 strings.TrimSpace / strings.Contains 就懂, 不必读自实现
- 安全: 大写 key 之前漏打码, 修了

e2e 验证 (verifydbsens 临时脚本, 已删):
  api_key        -> sensitive ✓
  auth_key       -> sensitive ✓
  API_KEY_UPPER  -> sensitive ✓ (修前漏)
  Auth_Token_Mixed -> sensitive ✓ (修前漏)
  default_speaker -> sensitive ✓
  default_resource_id -> not sensitive ✓
  note            -> not sensitive ✓

build + go test ./... 全绿
未 push (待用户)
 2026-09-05 11:59:06 +08:00
sun 59c0027122 fix(cors): SettingsCORSRequest.Origins 改 *string,支持显式清空 
Bug 2 报告: controller/settings.go:330-332 的死代码
  if body.AllowAll == nil && trimAll(body.Origins) == "" && body.Origins != "" {
      // 空 body 不算错误
  }
该条件永远 false (trim 空 != "" 矛盾), 整个 if 块只注释不执行。

更严重的是: 用户无法清空 origins —
原代码 body.Origins == "" 就 400, 但用户可能就是想传空串清空。
struct 字段是 string, 区分不出"未传"和"传空串"。

修法:
- struct.SettingsCORSRequest.Origins: string → *string
  - nil = 未传 (不动)
  - *""  = 传空串 (清空)
  - *"url1\nurl2" = 覆盖
- 删掉 line 330-332 死代码
- 改校验逻辑:
  - 2 个字段都 nil → 400 no_fields
  - 至少一个非 nil → 200
- 空串不校验 origin 格式 (无 origin 可校), 直接存

行为变更:
  - {"origins": "https://a.com"} → 写, 同以前
  - {"origins": ""} → 清空 (新功能, 以前返 400)
  - {"origins": null} → 视为未传, 不动
  - {"allow_all": true} → 写, 同以前
  - {"allow_all": false} → 设为 false, 同以前
  - {} → 400 no_fields
  - {"origins": "not-a-url"} → 400 origin_invalid (同以前)

测试: test/integration/settings_test.go (gitignored) 5 个 case
  - EmptyOrigins_ClearsOrigins
  - OriginsNotInBody_NotTouched
  - EmptyBody_400
  - NullOrigins_TreatedAsMissing
  - InvalidOrigin_400

e2e: 4 场景全过 (设/清空/空 body 400/null 不动)。

不向后兼容: SettingsCORSRequest 内部 DTO, 仅 admin webui 调,
不暴露给外部 OpenAI 客户端。

未 push (待用户)
 2026-09-05 11:42:48 +08:00
sun 9e38566952 fix(startup): normal 模式配置损坏 → fail-fast, 加 health error 字段 + metric 
Bug 报告 (用户排查后提出):
- main.go:61-68 在 normal 模式下 LoadRuntimeConfig 失败只打 log.Printf
- TTSConfigErr 被设, /v1/audio/speech 返 503
- 但服务进程继续跑, 监听端口
- 运维看到"服务在跑", 排查成本高
- /health 虽然 503 + body 有 config_error:true, 但普通用户不会看 body
- 没 metric 计数, 监控告警配不出来

修法 (P0+P1+P2 一起):

P0 - main.go: mode 区分
  - setup mode + 失败 = WARN (没装正常)
  - normal mode + 失败 = log.Fatalf (进程退出, K8s 拉起, 触发告警)

P1 - dto/health.go + controller/tts.go:
  - ConfigStatusResponse 加 Error 字段 (omitempty)
  - 错误时填 setting.TTSConfigErr.Error()
  - /health body 运维一眼看出原因

P2 - metrics/metrics.go:
  - 加 tts_config_load_failures_total counter, labeled by mode
  - 不管 fail-fast 还是 warn 都计数, 但 mode 区分
  - Prometheus 告警: rate(tts_config_load_failures_total{mode="normal"}[5m]) > 0

e2e 验证 (本机, 3 场景):
  - 空 DB / setup 模式 → /health 200 + body error 字段 + 进程不退出 ✓
  - 装好 OK / normal 模式 → /health 200, body 无 error 字段 ✓
  - 装完 + default_resource_id='' (损坏) / normal 模式 →
    log 出现 [FATAL] "service cannot start in normal mode..."
    进程退出, K8s 拉起会循环触发, 直到 DB 修好 ✓

副作用:
- fail-fast 后, 自愈回退逻辑不变 (installer.Detect 仍把损坏 db
  备份 + 转 setup mode), 但用户已正常装过的 db 不会被自愈删除
- 不影响启动日志, LogStartupSummary() 仍照常打印
- 不影响 setup 模式, 该 WARN 还是 WARN

未 push (待用户)
 2026-08-30 22:43:07 +08:00
sun a655f8ae0e fix(tts): voice.enabled=0 真生效,返回 403 voice_disabled 
Bug: admin UI 切换"启用/禁用"toggle → DB 字段更新 ✓,
但 controller/tts.go 路由时不查 enabled, 关掉的 voice 仍能正常调通。
admin 关闭形同虚设。

修法: 在 voice 查库命中后, 立即检查 v.Enabled:
  - enabled=1 → 走原流程
  - enabled=0 → 立即 403, 错误码 voice_disabled

Body 格式(对齐 OpenAI error 规范):
  {
    "error": {
      "code": "voice_disabled",
      "message": "voice 'chun' is disabled",
      "type": "invalid_request_error"
    }
  }

为什么 403 (vs 400 / 410):
- 400: 客户端发错 — 不准, voice 存在, 只是被关
- 410: 资源 gone — 不准, 不是永久弃用, 可能再开
- 403: 资源存在但无权用 — 准确, admin 关 = 拒绝调用
  (OpenAI 其他端点对禁用资源用 403, 这是惯例)

e2e (本机):
- TEST 1: voice=chun, enabled=1 → 500 (volcano 假 key 401, 路由通了)
- TEST 2: voice=chun, enabled=0 → 403 voice_disabled ✓
- TEST 3: voice=ghost, 不存在 → 400 unknown_voice (原有行为不变)

副作用:
- 没有任何 admin 路径失败 (admin 改 enabled 字段直接生效, 无需 reload)
- metrics 没加新 label (后续可加 voice_disabled 计数, 留给 M4)

未 push (待用户)
 2026-08-30 19:25:05 +08:00
sun ad4727c507 fix(tts): voice 命中 log 跟合成 log 一致打码 
Bug 报告: 同一次请求, controller/tts.go:193 输出明文 speaker
  [tts] voice=chun 命中 (speaker=S_G8tEKnaJ1 ...)

但 adapter/volcano/synthesis.go:148 输出打码
  TTS 合成成功 - 音色=S_G8****naJ1

不一致 — 同一进程同一请求, 一处裸奔一处打码, 脱裤子放屁。

修法: 全部用 telemetry.MaskSpeaker (前4+****+后4)。
不动 telemetry.SpeakerLabel (sha1[:8] 不可逆哈希, /metrics 用, 保留)。

注意: server log 仍能看到带前缀/后缀的 speaker (e.g. S_G8****naJ1),
但 *完整* speaker 不可见, 防 log 泄漏给非 root 用户。
如果 log 路径对外可读, 仍需考虑更严的方案 (e.g. 整体不 log speaker),
但自托管单用户场景下, 这个折中 OK。

未 push (待用户 push)
 2026-08-30 15:56:59 +08:00
sun 65247b095a ux(setup): voice.resource_id 留空时自动用 settings.default_resource_id 
问题: step 2 有 "默认资源 ID" 字段,但 step 3 的每个 voice 行
也有 "资源 ID" 字段,要求用户填 2 次。用户经常只在 step 2 填,
留空 step 3 的 resource_id,导致 voice 行拿到 form placeholder
"volc.megatts.icl" 或空串。结果 settings 和 voice 不一致,
运行时火山 500(mismatch / not granted)。

修法 (后端兜底,无需前端改动):
1. 装时校验放宽: resource_id 留空是允许的(原来是必填)
2. 装时遍历 voices, 如果 voice.resource_id == "" 就用
   settings.default_resource_id 兜底, 并记 log

用户收益: step 3 voice 行的 resource_id 字段可以不动,
step 2 填一次就行,始终保持一致。

可选前端优化 (待前端做): step 2 的 "默认资源 ID" 改变时,
自动同步所有 voice 行的 resource_id (placeholder 提示已自动填充)。

e2e 验证 (本机):
- 提交 install body 中 voice[0].resource_id=""
- 启动 log: '[setup] voice "chun" resource_id 留空,自动用 default_resource_id="seed-icl-2.0"'
- dumpdb 看 voice chun.resource_id = seed-icl-2.0 (从 settings 兜底) ✓

二进制: ~18MB → ~18MB (代码量几乎不变)

未 push (待用户确认)
 2026-08-30 14:07:03 +08:00
sun 8a4187720c fix(tts): settings.default_resource_id 不再被 voice 行覆盖 
Bug 001 (后端):

之前 f5563e6 修 55000000 时,LoadRuntimeConfig 拿 default_speaker 查
voice 表后,把 voice.Speaker/ResourceID/Model 全部覆盖了 settings 里
的对应值。本意是修 speaker,副作用是 default_resource_id 永远被
voice.resource_id 覆盖 → 用户在 setup 设的 default_resource_id
(seed-icl-2.0) 没机会生效,被 voice 行的 (volc.megatts.icl) 替换。

修法 (option B: settings 优先 + voice 兜底):
- speaker:  从 voice 表查 (default_speaker 是 voice 名,要解析成真 ID)
- resource_id: 保持 settings 里的(用户偏好)
- model:  voice 行的优先,settings 里的次之(向后兼容, 不动)

字段语义重新明确:
- settings.default_resource_id: 全局默认 resource(用户必设,运行时用)
- voices[].resource_id: 仅在 voice= 显式传时使用(per-voice 覆盖)
- 用户保持两个一致即可

附带修复: controller/tts.go 的注释误导(说 voice 为空用
setting.TTSOptions.Speaker 即 default_speaker),实际是 LoadRuntimeConfig
已解析为真 speaker ID。

测试:
- 已有 store/installer/middleware/router/telemetry 测试全绿
- e2e (本机): install settings.default_resource_id=seed-icl-2.0
  voice chun.resource_id=volc.megatts.icl (故意不一致)
  → 启动 log: 'resource=seed-icl-2.0' (settings 优先 ✓)
  → 火山 55000000/45000030 → 401 Invalid X-Api-Key (说明参数对,key 假)
  → 换真 key 即能 work

二进制大小: ~18MB → ~18MB (代码量不变)

未 push (待用户确认)
 2026-08-30 13:09:40 +08:00
sun f5563e6f31 fix(tts): default_speaker 查 voice 表,改后立即生效 
Bug 链:

1. 【核心 bug】setting/config.go LoadRuntimeConfig 把
   "default_speaker" 当成"火山 speaker ID"用 — 但 DB 里存的是
   voice **名字**(如 "chun"),不是 speaker ID (如 "S_G8tEKnaJ1")。
   结果: TTSOptions.Speaker = "chun", TTSOptions.ResourceID 仍来自
   default_resource_id 配置。调 /v1/audio/speech 不传 voice 时,
   把 "chun" 当 speaker ID 发给火山 → 55000000 resource ID mismatched。

2. 【次生 bug】装完 install 没 reload TTS 配置。
   启动期 LoadRuntimeConfig 失败(无 lock 无 settings), TTSConfigErr 被设;
   装完 mode 变 normal 但 TTSConfigErr 没清, /v1/audio/speech 仍 503/500
   (要重启才生效)。

修法:
- setting/config.go: 拿到 default_speaker 后调 GetVoiceForTTS(name)
  查 voice 表, 用 voice.Speaker / ResourceID / Model 覆盖。
  (新增 store.Store interface 方法 GetVoiceForTTS,4 元组返回值
  避免循环 import;store 包加 GetVoiceForTTS 实现,内部包 VoiceGetByName)
- controller/setup.go: 装完 install 调 LoadRuntimeConfig 一次,
  让 TTSConfigErr 立即清,TTSOptions 立即可用。

测试:
- 已有 store/installer/middleware/router 测试全绿
- e2e (本机): install voice "chun" + speaker "S_G8tEKnaJ1" →
  启动 log 显示 "speaker=S_G8tEKnaJ1" (不是 "chun") ✓
  → /v1/audio/speech 不传 voice → 火山收到正确 speaker,
  错误从 55000000 变成 401 Invalid X-Api-Key (假 key,换真 key 就 work)

二进制大小: ~18MB → ~18MB (代码量不变)

未 push (等用户验证)
 2026-08-30 01:53:30 +08:00
sun 7660db14d8 fix(cors): CORS 全 DB 化,install 模式完全跳过,WebUI 可配 
完整方案: 与 auth_key 同思路,让 CORS 也走 DB,彻底干掉 ALLOWED_ORIGINS env。

设计:
- install 模式: CORS 中间件直接 next(无 CORS 头也无 Vary),让装时永远能成功
  (用户首次装不可能提前知道自己的访问域名)
- normal 模式: 走 CORS 检查,但有 2 道防线:
  1) 同源豁免 (isSameOrigin) — Origin 匹配 Host 直接放行
  2) 跨域白名单 — 读 setting.CORS (DB > env)
- DB 字段:
  - cors_allow_all (bool): 允许所有(*)
  - cors_origins (string): 换行分隔白名单,后端 trim+lower+去末尾 /
- WebUI: /admin 设置 tab 加 CORS 段(allow_all checkbox + origins textarea + 保存)
- 顶部 banner: cors_configured=false 时显示黄条提示,引导去设置

新增:
- middleware/cors.go: 顶部 installer.GetMode() == ModeSetup 时直接 next
- setting/config.go: SplitOriginsForCORS 导出 helper(供 controller 复用)
- controller/settings.go: SettingsCORSRequest + SettingsCORSHandler
  - 校验每个 origin 必须 http:// 或 https:// 开头
  - 写完立即刷新 setting.CORS.AllowAll + setting.CORS.Origins(下个跨域请求生效)
  - 拒绝空 body
- router/router.go: 挂 /api/settings/cors (PUT, RequireAdmin)
- router/admin.html: 设置 tab 加 CORS card + 顶部 banner (31.19KB, 略超 30KB 预算可接受)

改造:
- setting/config.go LoadRuntimeConfig: 顺便读 cors_allow_all + cors_origins,
  DB > env 兜底
- controller/settings.go SettingsResponse: 加 cors_allow_all + cors_origins + cors_configured

e2e 跑通(本机)10 场景:
- install 任意 Origin → 200 (install mode 跳 CORS)
- normal 同源 → 200
- normal 跨域无 allowlist → 403
- GET settings cors_configured=false
- PUT /api/settings/cors → 200
- GET settings cors_configured=true
- 跨域命中白名单 → 200
- 跨域未命中白名单 → 403
- allow_all=true → 任意跨域 200
- 重启后 CORS 仍从 DB 加载

未 push(等用户测试 install 是否顺利,以及 CORS banner 是否合适)
 2026-08-30 00:08:14 +08:00
sun a4ea53bfa0 fix(auth): OpenAI 端 key 也走 DB,setup 是单一配置入口 
修 M2/M3 遗漏:OPENAI_TTS_API_KEY (admin + 合成鉴权) 此前只能从 env
读,setup 前端没收集。装完用户还要回去设 env,体验断,违反
'setup 是单一配置源' 承诺。

改动:
- setting/config.go: LoadRuntimeConfig 顺便把 auth_key 灌到
  setting.Auth.APIKeys。优先级 DB > env(env 仅作 fallback,首次启
  动无 DB 时仍可用,向后兼容)。
- controller/setup.go: validateSetupSettings 加 auth_key 为必填,
  写 DB 后立即 setting.Auth.APIKeys = [auth_key](本进程内立刻生效)。
- controller/settings.go: GET /api/settings 返 auth_key (打码) +
  auth_key_set;新增 SettingsAuthKeyHandler (PUT /api/settings/auth-key),
  改完单独刷新 setting.Auth.APIKeys(避免被自踢,只下次请求生效)。
- router/router.go: 挂 /api/settings/auth-key 路由。
- router/setup.html: 加 OpenAI 鉴权 Key 字段(密码框,带提示);
  表单 default + submit 都加 auth_key。
- router/admin.html: 设置 tab 拆两张卡 — 鉴权 Key(独立保存按钮,
  改完会自踢当前会话)+ 火山 TTS 凭证;vue setup 加 authKeyInput +
  saveAuthKey 函数。
- main.go: 把 LoadRuntimeConfig(st) 提到 LogStartupSummary 之前,
  让启动日志反映真实运行时状态(DB 已加载的 key 数量)而不是
  过时的 env 状态。

未 push(等用户当前 M3 测完一起或单独)
 2026-08-29 23:18:51 +08:00
sun 9db038dd05 feat(settings): M3 全局设置 + voice 动态路由 + env 收敛 
M3 完成:env 业务配置全进 DB,WebUI 可改,改完立即生效(无需重启)。

新增:
- controller/settings.go: 3 个 handler
  - GET /api/settings: 读所有设置,api_key 永远打码
  - PUT /api/settings: 部分更新(白名单字段);default_speaker 改时校验
    音色必须在 voices 表里(避免引用不存在);改完调 LoadRuntimeConfig 即时生效
  - PUT /api/settings/api-key: 独立端点,只改 api_key

改造:
- setting/config.go: 用 LoadRuntimeConfig(store) 替代 InitTTSConfig
  - 不再读 BYTEDANCE_TTS_* env,完全从 store.Settings 拿
  - 必填项缺失返 error,设 TTSConfigErr(/v1/audio/speech 返 503)
  - 定义 Store 接口(避免 setting → store 循环 import)
  - 字段映射: BYTEDANCE_TTS_API_KEY → api_key, BYTEDANCE_TTS_RESOURCE_ID
    → default_resource_id, ... 全部一一对应
- controller/tts.go: voice 路由
  - voice 为空 → 用 setting.TTSOptions.Speaker (即 store.default_speaker)
  - voice 非空 → 查 voices 表,替换 opts.Speaker / ResourceID / Model
  - 命中但 enabled=0 → 仍可用(显式 voice 覆盖)
  - 未命中 → 400 unknown_voice
  - voice 路由日志: "[tts] voice=xxx 命中 (speaker=... resource=... model=...)"
- router/admin.html: 加 #settings tab (24.78KB, 仍 <30KB 预算)
  - API key 区:打码显示 + 独立更新按钮
  - 路由/格式区:default_resource_id / default_speaker (下拉源 /api/voices) /
    default_format / sample_rate / model
  - "保存" 按钮 PUT /api/settings + 立即 reload (settingsOk 提示)
- router/router.go: 挂 /api/settings[/{api-key}] 三路由
- main.go: Detect 之后调 LoadRuntimeConfig,失败也允许进入
  (env 阶段无 db,LogStartupSummary 仍显示 BYTEDANCE_TTS_* 必填项用于诊断)

测试(都被 .gitignore 排除,本地保留):
- 已有 store/installer/middleware/router/telemetry 测试保持全绿
- e2e 验证(本机跑通 9 场景):
  - install 写入 3 voices + 7 settings
  - 重启后 main.go log: "TTS 运行时配置已加载(api_key=***, speaker=default-voice, resource=volc.megatts.icl, format=wav)" — 确认走 DB 不读 env
  - GET /api/settings 返所有字段
  - voice=clone-voice-1 命中 S_clone_1 + seed-tts-2.0-expressive
  - voice=clone-voice-2 命中 S_clone_2 + volc.megatts.icl-2
  - voice=unknown 返 400 unknown_voice
  - PUT /api/settings 改 default_speaker 即时生效
  - PUT /api/settings/api-key 改 key 即时生效
  - PUT /api/settings default_speaker=ghost 返 400 default_speaker_missing

注意: e2e 里的 TTS 500 是因为我用假 key 调上游,路由逻辑本身正确。
换真火山 API key 即可 work。

二进制大小: ~17MB → ~18MB (+1MB)

未 push(等用户测试 M1+M2+speaker fix 全部稳定后,跟 51bd7ae+70865a3 一起或单独 push)
 2026-08-29 22:40:53 +08:00
sun 70865a3cf4 feat(admin): M2 WebUI 管理后台(鉴权+仪表盘+音色 CRUD) 
新增 /admin 管理后台,Vue3 + axios 单文件 SPA。

新增:
- middleware/admin_auth.go: RequireAdmin 中间件
  复用 OPENAI_TTS_API_KEY(Bearer),密钥为空等同无鉴权;
  常量时间比较防计时攻击(用 common.SecureEqualString);
  401 + WWW-Authenticate 头 + JSON 错误体。
- controller/admin.go: 5 个 admin handler
  - GET /api/admin/overview: 模式/db路径/lock/版本/运行时间/音色数/内存
  - GET /api/admin/metrics: 鉴权版 Prometheus 文本(无鉴权版 /metrics 仍给 Prometheus)
  - GET /api/voices: 列表(含 disabled)
  - POST /api/voices: 新增,409 处理重复,400 处理字段不合法
  - DELETE /api/voices/{name}: 删除,409 处理被 default_speaker 引用
  - PATCH /api/voices/{name}/toggle: 启停
- router/admin.html: 单文件 SPA(18KB)
  登录页(单 input) + 仪表盘(metrics cards) + 音色 tab(表格+新增+启停+删除);
  hash 路由切 tab;axios 拦截器自动加 Bearer,401 回登录页;
  sessionStorage 存 key(关浏览器失效)。
- common/constants.go: SecureEqualString 提取到公共包
  controller/setup.go + middleware/admin_auth.go 共用,避免重复实现。

改造:
- router/router.go: 挂 /admin(/admin HTML 公开,鉴权由前端 JS 拦截)
  + /api/admin/{overview,metrics} + /api/voices{,/{name},/{name}/toggle}
  全部 API 端点套 RequireAdmin;正常模式 / → 302 /admin(M2 优先于 /dashboard)。
- main.go: 启动期调 SetAdminStore + SetMetricsTextWriter(避免 controller → metrics cycle)
- metrics/metrics.go: AdapterRecorder 用 SpeakerLabel 替代明文 speaker
  (这是第 4 处 speaker 泄漏,顺带补上;前面 3 处在 51bd7ae 已修)。
- controller/setup.go: 用 common.SecureEqualString 替自己的实现(去重)。

测试(都被 .gitignore 排除,本地保留):
- router/router_test.go: 更新 4 个 NotFound 测试路径(/admin 现是注册路由,不再 404)
- telemetry/labels_test.go: 已有 SpeakerLabel/MaskSpeaker 测试(M2 复用)

e2e 验证(本机跑通):
- /admin 200 HTML(无鉴权,前端 JS 拦截)
- /api/admin/overview 无 Bearer 401
- /api/admin/overview 错 Bearer 401
- /api/admin/overview 对 Bearer 200 + JSON
- /api/voices GET 200 + 2 voices
- /api/voices POST 201 + new voice
- /api/voices/{name} DELETE 200
- /api/voices/{name}/toggle PATCH 200 + updated voice
- 正常模式 / 302 /admin
- 启动日志 BYTEDANCE_TTS_SPEAKER 仍打码 S_G8****naJ1(前次 fix 生效)

二进制大小: 16MB → ~17MB(admin.html +5 个 handler + 中间件)

未 push(用户要求与 speaker fix 51bd7ae 一起发,等服务器测完 M1 后一起验证)
 2026-08-29 21:53:19 +08:00
sun 51bd7ae37a fix(privacy): speaker ID 不再裸奔(3 处) 
speaker 是火山复刻音色 ID,用户付费资产,不能裸奔。
本次修复 3 处泄漏:

1. controller/tts.go: /metrics label 用 sha1(speaker)[:8] 替代
   - /metrics 无鉴权,Prometheus 可枚举,原值直接暴露是最大的泄漏面
   - 哈希替代保留 per-voice 聚合能力,反推不出原值
   - Admin UI 想看原名通过 /api/voices 拿 name 字段

2. setting/config.go: 启动日志 LogStartupSummary 用 MaskSpeaker
   - API Key 早用 maskAPIKey,speaker 漏了
   - 现在 S_G8tEKnaJ1 形式

3. adapter/volcano/synthesis.go: 合成 debug + 成功日志用 MaskSpeaker
   - 之前 resource_id=xxx speaker=原始ID 直接打
   - 现在打码

新增 telemetry/labels.go:
- SpeakerLabel(s) -> sha1(s)[:8] (8 字符十六进制,稳定、不可逆、同输入同输出)
- MaskSpeaker(s) -> 前 4 + **** + 后 4 (空串返中文未设置,长度 <=4 全打码)
- 空 speaker label -> 'unknown' (Prometheus 禁止空 label)

单测 telemetry/labels_test.go 覆盖:
- SpeakerLabel: 同输入同输出 / 不同输入不同输出 / 空串 unknown / 长度 8 / 全是 hex
- MaskSpeaker: 各种长度边界 + 真实火山 ID 形式

e2e 验证(本机):
- 启动日志看到打码形式,无明文
- 自动化 grep 原始 ID 在 server log: 0 匹配
- go test ./... 全绿

未 push(用户要求先修后等 M2 一起发)
 2026-08-29 21:42:57 +08:00
sun 7984c1880a feat(installer): M1 安装流程 + /setup 引导页 
新增:
- installer/lock.go: lock 文件检测/创建/删除(原子写入);ErrLockExists sentinel
- installer/bootstrap.go: Detect() 启动期判定 ModeSetup/ModeNormal,
  损坏自愈(自动备份 db.corrupt-<ts> + 删 lock + 回退安装模式)
- middleware/installguard.go: 安装模式白名单(/setup /api/setup /health /metrics),
  中间件顺序: SecurityHeaders → InstallGuard → RateLimit → ...(避免限流计数污染)
- controller/setup.go: GET /api/setup/status + /api/setup/prefill + POST /api/setup;
  token 校验用常量时间比较防计时攻击;安装后端点永久 404
- router/setup.html: Vue3 + axios CDN,4 字段表单 + 动态音色行,
  调用 /api/setup/prefill 自动从旧 env 预填(API key 永不预填)

改造:
- main.go: 启动期 store.Open → installer.Detect → 注入 setup 控制器
- controller/tts.go: 安装模式双保险(/v1/audio/speech 即便漏过中间件也 503)
- controller/health.go (via dto): 加 installed + mode 字段,部署探针可识别
- router/router.go: 挂载 /setup + /api/setup/*,根路径安装模式跳 /setup
- setting/config.go: InitSetupToken 读 TTS_ADMIN_KEY 或随机生成 32 字符 hex
  (公网部署建议设 env;空时启动日志一次性打印)

删除:
- router/dashboard.go: 内容并入 router/router.go

.gitignore: tts.db / tts.db-* / installed.lock 加入(运行时产物)

验收(端到端跑通,见 scripts/ 已删除):
1. 删 lock → /v1/audio/speech 503 + /setup 200 HTML
2. POST /api/setup 错 token → 401;对 token → 200 + 写 lock + 写 db
3. 重复 POST → 404(端点永久关闭)
4. /health: 安装期 installed=false,装后 installed=true
5. 损坏 db header: 自动备份 tts.db.corrupt-<ts> + 删 lock + 回安装模式

测试:
- installer: 6 个 test, 覆盖 lock 生命周期 + Detect 三态 + 损坏自愈
- middleware: 3 个 test, 覆盖白名单/denylist/自定义
- store(M0): 仍 27/27 绿, 70.7% 覆盖率

二进制大小: 9.77 → 15.87 MB (+6MB,大部分是 setup.html embed + 新包)
 2026-08-29 20:44:33 +08:00
sun c00c46e7a1 chore: 注入构建时版本信息到 /health 端点 
现状:controller/tts.go:232 硬编码 Version: "2.0.0 (v3 API)",
不会随代码变化而更新,/health 无法反映实际跑的代码。
修复:四文件改动,实现构建时 ldflags 注入。
  1. 新建 version/version.go,声明两个包级变量:
       Version (默认 "dev")
       Commit  (默认 "dev")
  2. dto/health.go:HealthResponse 加 Commit 字段(JSON 输出多一字段)
  3. controller/tts.go:HealthResponse 用 version.Version / version.Commit
     替代硬编码字面量
  4. Dockerfile:加 ARG VERSION=dev ARG COMMIT=dev,
     go build 时通过 -ldflags 注入到 version 包的两个变量
效果:
  - 本地 go build (不传 ldflags) → version=dev commit=dev
  - 开发 build (git describe) → version=v0.2.0-5-g4abcd5 commit=g4abcd5
  - release build (打 tag 后) → version=v0.2.1 commit=<对应 hash>
测试环境(develop 分支,无 tag)显示距离上次 release 几个 commit +
具体 hash;生产环境(main + tag)显示干净 semver。
 2026-08-27 10:18:34 +08:00
sun 3b3aa3b708 chore: 清理 DEBT-2 死代码(7 文件,约 30 行) 
VUL-003 修复期间意外发现项目遗留一批死代码,本次一并清掉:

  - middleware/ratelimit_middleware.go(37 行,物理删除)
    文件内 RateLimit / ConcurrencyLimit 函数从 977e9cc 创建后
    从未被引用,370a217 commit 用 ratelimit_instrumented.go
    (带 metrics 埋点 + 路径过滤)取代了它。占用包体,清。

  - middleware/auth.go:InitAPIKeys(6 行)
    注释说"已在 setting.InitAuthConfig 中完成",无 op。

  - middleware/cors.go:InitCORSConfig(6 行)
    同上,setting.InitCORSConfig 已做实际工作。

  - dto/tts.go:ByteDanceTTSConfig 类型(7 行)
    完整的配置走 setting.TTSOptions + adapter/volcano.Options,
    此类型从未被任何代码实例化。

  - setting/config.go: var _ = dto.ByteDanceTTSConfig{} 占位(3 行)
    配合上方类型删除,移除 dto import。

  - controller/tts.go:resolveClientFormat
    合并 if reqFmt == "" 与 default 分支(都返回
    setting.TTSOptions.Format),2 行简化。

  - common/constants.go: MaxResponseTimes / MaxErrors
    定义后从未被任何文件引用。

  - middleware/ratelimit_instrumented.go 顶部注释
    移除对"原 ratelimit_middleware.go"的悬空引用,
    改为描述本文件相对路由使用实现的两个增强点。

影响:
  - 包体减少约 30 行
  - 降低新人接手时的代码理解成本
  - 零功能变更,24 个现有测试用例全过
 2026-08-27 00:57:49 +08:00
sun 155fab6b4b feat: add debug log control and optimize error response and cors log 
- add DebugLog global variable controlled by BYTEDANCE_TTS_DEBUG env
- enable debug logs for cors, tts upstream, response parsing etc when debug mode is on
- update tts error response to use standardized json error format
- add dashboard and metrics path to cache-control exempt list
 2026-08-15 19:03:37 +08:00
sun 81fcc9fff4 chore: 清理多余的BOM头并整理依赖与telemetry代码 
- 移除所有文件开头的多余UTF-8 BOM头
- 简化go.mod依赖，移除未使用的uuid包
- 重构telemetry包：将Meter改为接口并拆分默认实现
 2026-08-15 14:38:14 +08:00
sun 5b970f49e1 feat: 实现完整可观测性架构与火山v3适配器重构 
重构整体架构：
1.  新增telemetry包实现零依赖的Prometheus指标系统
2.  新增metrics包集中管理业务埋点指标
3.  重构火山v3适配器，拆分client/request/response等模块
4.  替换旧的service/stats统计系统为标准指标埋点
5.  新增/metrics观测端点与完整仪表盘支持

功能更新：
- 实现基于IP的限流与并发限制，添加指标埋点
- 重构TTS控制器，支持多格式输出与完整错误分类
- 更新.env.example配置示例，新增多项可选参数
- 替换旧的volcano适配器实现，支持完整的v3 API特性
- 清理冗余代码，移除service/stats与旧adapter实现
 2026-08-15 13:30:35 +08:00
sun 07a7dd450c refactor(tts): 简化火山TTS实现，移除可配置格式采样率等参数 
重构了火山TTS的适配器与配置逻辑，移除了格式、采样率、model等可配置项，固定使用wav/24000Hz参数，简化请求流程并删除冗余的格式转换、WAV头拼装逻辑，同时更新文档与环境变量配置。
 2026-07-01 18:27:07 +08:00
sun 21b86bfcfe feat: 新增音频格式与采样率配置，完善OpenAI兼容格式映射 
1.  新增BYTEDANCE_TTS_FORMAT和BYTEDANCE_TTS_SAMPLE_RATE环境变量配置
2.  实现OpenAI TTS格式到火山API格式的映射转换
3.  自动处理wav格式：内部用pcm请求后封装标准WAV头
4.  动态设置响应Content-Type，适配不同输出格式
5.  更新文档与配置示例，完善日志与错误处理
 2026-06-27 23:28:35 +08:00
sun 8592843bdf refactor(tts controller): add detailed request logging for TTS handler 
新增truncateForLog工具函数处理日志截断，为各个请求校验环节和错误场景补充详细日志记录，包括请求方法、鉴权状态、配置错误、请求体读取、参数校验以及合成失败等场景，同时记录客户端IP、请求路径等上下文信息，方便问题排查。
 2026-06-26 23:09:27 +08:00
sun bc42295ff6 chore(controller/tts): 移除未使用的log导入包 
删除了tts控制器文件中不再需要的log标准库导入
 2026-06-26 20:46:34 +08:00
sun 61431e00ba refactor: 重构并优化项目多项功能 
1. 调整CORS中间件挂载位置，重构CORS处理逻辑
2. 重写IP获取逻辑，增加私有网络IP信任校验
3. 优化日志中间件，移除/health接口单独日志逻辑
4. 改进API密钥未配置时的提示信息
5. 重构volcano TTS调用，新增voice参数支持
6. 优化请求体过大错误处理
7. 完善统计服务，修复环形缓冲区遍历逻辑，新增去重错误日志功能
 2026-06-26 19:12:50 +08:00
sun 3d50b6c69d fix: 修复代码格式、乱码和CORS校验问题 
1. 修复tts.go中多余的缩进错误
2. 修复main.go和auth.go中的中文乱码问题，修正日志文本
3. 修复CORS校验逻辑，将origin转为小写后再判断协议前缀
4. 修正auth.go中API密钥未配置时的提示逻辑
 2026-06-23 10:23:44 +08:00
sun 977e9ccadb build: 升级go版本到1.26并添加限流中间件 
1.  调整go.mod将Go版本升级至1.26
2.  新增速率限制和并发限制中间件，将其加入路由中间件链
3.  重构TTS处理逻辑，将限流逻辑迁移至中间件统一处理
4.  优化CORS中间件代码，移除冗余日志和格式调整
 2026-06-22 18:13:35 +08:00
sun be6c2ad34e Revert "fix: 修复请求体过大处理和冗余代码问题" 
This reverts commit 23b962a90e.
 2026-05-26 10:42:41 +08:00
sun 23b962a90e fix: 修复请求体过大处理和冗余代码问题 
1. 修复OpenAI TTS接口的请求体过大错误提示，返回正确的状态码和提示信息
2. 删除volcano适配器中无用的空循环扫描代码
3. 修正constants.go的包声明重复空格问题
 2026-05-26 10:41:47 +08:00
sun 9c35f780db 功能 (语音合成)：新增语音合成请求的模型名校验 
新增模型名最大长度常量，限定字符上限为 64 位
传入模型名称时，校验名称长度并拦截非法控制字符
移除闲置的 tts-api.exe 可执行文件
 2026-05-24 11:52:57 +08:00
sun 4e1820d45b refactor: 重构项目架构，拆分代码到模块化目录 
将单文件tts_server.go重构为模块化项目结构，拆分出common、dto、middleware、router、controller、service、adapter、setting等目录，优化代码组织提升可维护性
 2026-05-23 20:32:12 +08:00