sun/Volcano-Engine-TTS-UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
88 Commits 2 Branches 6 Tags
f5563e6f3195cfa11f0e5cf574a625410ee73236
Commit Graph
88 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
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 d22abecf12 fix(ui): store.Voice 加 JSON tag,修「音色是空的」+ UI 整体换皮 
本次 3 个改动:

1. **【BUG 修复】store.Voice 加 JSON tag** — 用户报「进入系统音色是空的」。
   实际:DB 里有数据,API 也返了。Bug 在 store.Voice 结构体没加 json tag,
   Go 序列化为大写("Name"/"Speaker"/"ResourceID"/"Enabled"),而所有
   admin.html 用 v.name/v.speaker/v.resource_id/v.enabled 拿,全是 undefined。
   表渲染了但每格空。修复后 API 返小写,前端能正常读。
   写 store/voices_test.go 加 TestVoice_JSONTags 防退化。

2. **【UI 换皮】Codex 改造 admin.html + setup.html**
   - admin.html: 31KB → 58.8KB (1075 行)
     加: 侧边栏 + 品牌 + 4 步导航、toast 通知系统、grid 卡片、
     搜索/筛选/状态分页、stat-card 带 pill、modal + 过渡动画、
     按钮大小/颜色变体、响应式字体缩放
   - setup.html: 13KB → 23KB (428 行)
     加: 4 步向导 + 进度条 (步骤 1: 上游凭证 / 2: 默认路由 /
     3: 音色列表 / 4: 确认)、语音行 hover、确认页打码展示
   - 功能完全保留: API 路径/字段/hash 路由/401 拦截都未改

3. **【小修】setup.html 装完跳转回退用 /admin 不是 /dashboard**
   Codex 改的版本回退写成 /dashboard,是回归。已改回 /admin。

测试:
- 已有 store/installer/middleware/router/telemetry 测试全绿
- 新增 store/voices_test.go: TestVoice_JSONTags + TestVoice_UnmarshalTags

E2E 验证(本机):
- install 2 voices → DB 写入 ✓
- GET /api/voices 返小写 id/name/speaker/resource_id/enabled 等 ✓
- PATCH /api/voices/qian/toggle → 200 + lowercase 回包 ✓
- POST /api/voices → 201 + lowercase 回包 ✓
- GET /api/voices 再次列 3 条(原 2 + 新 1)✓

未 push (等用户测试「音色终于显示出来」)

二进制大小: ~18MB → ~18.5MB (admin.html +27KB embed)
 2026-08-30 00:51:23 +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 1bed8d8ed0 fix(cors): 同源请求跳过 CORS 校验,避免浏览器自家人拦自家人 
修 bug: 用户从浏览器访问 /setup 提交表单时,浏览器对同源 POST
也会设 Origin 头(防 fetch 滥用)。原 CORS 中间件只看 Origin 是否
在 ALLOWED_ORIGINS 白名单,未配白名单时同源 POST 会被 403 拒,
表现为"安装失败: status code 403"。

此前用 curl 测试时没 Origin 头(CORS 跳过),所以本地测不出来。
浏览器必带。

修法: 在 CORS 校验前加同源豁免 — 比较 Origin 与 r.Host(含
X-Forwarded-Host / X-Forwarded-Proto 反向代理场景),一致就放行,
不进入 CORS 检查、不设 Vary 头。

测试 (被 .gitignore 排除, 本地保留):
- middleware/cors_test.go: 新增
  - TestIsSameOrigin: 10 场景
    - 空 origin / 同 host+port / 同 host https / 不同 port / 不同 host
    - 大小写不敏感 / XFH 代理 / XFH 不匹配 / origin 带 path / 无 scheme
  - TestSplitOrigin: 5 场景
    - https://example.com:8080 / http://localhost / 带 path
    - not-a-url / ://broken

e2e 验证 (本机跑通):
- install 无 Origin (curl): 200
- install 同源 Origin: 200 ✓ 修复
- install 跨域 Origin: 403 (仍正确拒绝)
- install 不同端口 Origin: 403 (仍正确拒绝)

未 push (等用户确认)
 2026-08-30 00:00:21 +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 dbaee35400 fix(install): M1 后续 · 2 个 install 模式入口 bug 
Bug 1: 安装模式下浏览器访问 / 看到 503 JSON
- 根因: middleware/installguard.go 默认白名单没包含 /;
  浏览器访问 / 时 InstallGuard 先于 router 的 redirect 拦掉,返 503 JSON。
- 修复: InstallGuard 非白名单分支加 Accept 内容协商,
  text/html → 302 Location: /setup(浏览器友好),
  其它(API 客户端 / curl / 空 Accept)→ 维持 503 JSON(API 行为不变)。
- 额外: mux 路由未匹配时不走 r.Use() 中间件链,
  手动设 r.NotFoundHandler 复用同一份 Accept 协商逻辑,
  覆盖 /admin /api/voices 等任意未注册路径。

Bug 2: 装完访问 /setup 仍能进入(看到安装表单)
- 根因: router.go 的 /setup handler 没做 mode 校验。
- 修复: handler 顶部加 if ModeNormal → 302 Location: /admin
  (M2 之后才有 /admin;目前会 404 也比继续显示表单好)。

测试(都被 .gitignore 排除,本地保留):
- middleware/installguard_test.go: 加 2 个 case(浏览器 redirect / API JSON)+ acceptsHTML 单元
- router/router_test.go(新): /setup 装后 redirect + NotFoundHandler 4 个 case
- 全套 go test ./... 全绿

验证(本机 e2e 跑通):
- setup 模式: 浏览器 /, /admin, /api/voices → 302 /setup
- setup 模式: API/curl / → 503 JSON(行为不变)
- normal 模式: /setup → 302 /admin(Bug 2)
- normal 模式: /admin → 404(M2 才有,行为不变)
- normal 模式: /api/setup/status → 200 {installed:true,mode:normal}

二进制大小: 15.87 → ~16MB(几乎不变)
 2026-08-29 21:16:08 +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 865fdd81e8 feat(store): M0 SQLite 存储层 + modernc.org/sqlite 
- 引入 modernc.org/sqlite(纯 Go 无 CGO,保持单二进制分发)
- store/db.go: Open/Close/IntegrityCheck + WAL/foreign_keys/synchronous PRAGMA
- store/settings.go: key-value CRUD,Get/Set/Delete/GetAll/SetBatch,带 int/bool/duration 类型 helper
- store/voices.go: 完整 CRUD + ErrDuplicate/ErrNotFound/ErrInUse,name 白名单 [a-zA-Z0-9_-]{1,64}
- store/migrate.go: schema 版本号占位(migrate 调度留待 v2)
- 27 个单测覆盖:CRUD/Pragma/Idempotent/Integrity/Unique/DefaultSpeaker 保护
- 测试覆盖率 70.7%,测试二进制 +0.87MB(预期 +30MB,实际大幅低于预期)
- 不改 setting/config.go、main.go、router、controller(按 M0 计划保持改动局部)

验证: go vet ./... 干净; go test ./... store 包全绿
 2026-08-29 20:29:28 +08:00
sun dc3248d11c chore: 转移前备份 — cleanup + project book 
- 删 VULNERABILITY_REPORT.md(已审完,合并到 commit 历史)
- 删 middleware/ratelimit_test.go(单测延后)
- .gitignore 加 *_test.go 规则(防误提交)
- README XFF 验证段措辞更新
- 新增 PROJECT_BOOK.md(v0.1 待评审)

基线备份:目录迁移到非云盘路径前的快照。
 2026-08-29 18:40:36 +08:00
sun 8be40ae6dc chore: embed health.html 到 binary,单文件分发 
把 health.html 从外部依赖改为 //go:embed 内嵌,
实现真正的"单 exe 分发"。

  - 新建 router/dashboard.go,用 //go:embed 嵌入 health.html
  - router/router.go:/dashboard handler 改为 w.Write(dashboardHTML)
  - setting/config.go:删 CheckStaticFiles(无需文件检查)
  - main.go:删 setting.CheckStaticFiles() 调用
  - Dockerfile:删 COPY health.html 步骤(已嵌入)
  - .gitignore:加 release/(build 产物不入 git)
  - 物理移动 health.html 到 router/(embed 限制:同包或子包)

效果:
  - 之前: release 包 = tts-api.exe + health.html (2 个文件)
  - 之后: release 包 = tts-api.exe (1 个文件,~7 MB)
  - 用户部署无需额外文件,/dashboard 路由直接工作
 2026-08-27 11:44:44 +08:00
sun cdc9a7c94b ci: 添加 GitHub Actions Docker 发布 workflow 
为 Gitea→GitHub 镜像 + GitHub 镜像仓库场景准备 Docker 镜像
自动构建和发布流程。

触发条件:
  - push tag v*  (release 时打 tag 自动触发)
  - workflow_dispatch  (手动触发,可在 GitHub UI 测试)

构建:
  - 多平台:linux/amd64 + linux/arm64
  - 通过 QEMU + Buildx 跨架构构建
  - 推送到 ghcr.io/<github-user>/volcano-engine-tts-ui
  - 双标签:语义版本 + 短 commit hash
  - OCI labels 包含 version 和 revision

与之前 version 包配合:
  workflow 用 git describe --tags --always --dirty 算 VERSION
  (commit hash 类似),通过 --build-arg 传给 Dockerfile,
  Dockerfile 用 -ldflags 注入到 version.Version / version.Commit
  两个变量。最终 /health 端点返回构建时注入的真实版本信息。

前置条件(用户需自行完成):
  1. GitHub 建镜像仓库
  2. Gitea 配置 Push Mirror 到 GitHub(开启 Sync Tags)
  3. 仓库设为 Public(否则 GHCR 镜像默认 private)
 2026-08-27 10:43:19 +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 695b3ecf25 docs: README 修正 speed 与 sample_rate 描述 (VUL-008 / VUL-009) 
VUL-008 (信息): speed 超范围静默截断无提示
  修复:「API 使用说明」speed 描述从"0.25 ~ 4.0"改为
  "客户端接受范围 0.25 ~ 4.0;火山实际生效范围 0.5 ~ 2.0
  (speech_rate [-50, 100]),超出范围会被静默截断,客户端无感反馈"。
  选 TODO 方案 1(诚实修正文档),不改代码。

VUL-009 (信息): WAV 采样率依赖配置而非上游实际值
  修复:BYTEDANCE_TTS_SAMPLE_RATE 描述加风险提示
  "此值直接写入 WAV 头,需与上游实际 PCM 采样率一致,
  否则音频变速变调"。
  上游 v3 协议不返回 sample_rate 字段,代码侧无法自动取真实值,
  仅文档强化。
 2026-08-26 16:16:56 +08:00
sun 7343d5aa5c VUL-006 (低): 监控端点 (/metrics /health /dashboard) 无鉴权 
判定:不引入新鉴权机制(会破坏 Prometheus 抓取),文档引导。
  修复:「观测 / Metrics」section 末尾新增「公网部署:监控端点
  无鉴权」段,含三端点风险表 + nginx 反代 basic auth 配置示例。

VUL-007 (低): 未设置 OPENAI_TTS_API_KEY 时鉴权完全关闭
  判定:不改代码(无 API Key 即不鉴权是 README 明示的设计),
  文档强化。
  修复:三处加强:
    1. 环境变量表 OPENAI_TTS_API_KEY 行加 🔴 公网必设 标记
    2. 「API 使用说明」section 顶部 callout 警示
    3. 「部署」section 末尾新增「公网部署安全清单」段,统一
       覆盖鉴权关闭与监控端点保护,形成完整安全姿态
 2026-08-26 16:06:17 +08:00
sun 171503d775 fix: VUL-002 修复 transport 错误埋点缺失 
VUL-002 (低): transport 层错误不进入 UpstreamErrors 指标
原代码用 if errCode != 0 判断是否记录错误,但合成链路中
多种错误场景的 errCode 本身是 0(火山 v3 业务码非 0 时才
会传入),导致这些场景在 /metrics 上完全不可见:
  - transport_error: client.PostStream 失败(DNS / 连接 / TLS)
  - request_error  : buildRequest 序列化失败
  - wrap_error     : WAV 头拼装失败
  - stream_error (code=0): 读流错误
修复:把判断改为 if status != "ok",status 是上游调用全链
路的权威错误指示器,任何非 ok 状态都计为错误。
codeLabel(0) → "transport" 已有定义,修复后该分类真正生效,
火山接口不可达等网络故障首次在监控上可见。
向后兼容:已统计的 http_XXX 错误(status="http_xxx" != "ok")
行为不变,新增 transport / request / wrap / stream 错误进入指标。
 2026-08-26 15:35:24 +08:00
sun 91b0c8acee fix: VUL-005 修复日志注入(RequestURI 与上游错误体转义) 
VUL-005 (低): 攻击者可在 HTTP 请求 URL 或上游错误响应中
注入 \n / \r 字符,伪造日志行干扰排障。无代码执行风险。

修复位置:
  - middleware/logger.go: 访问日志中的 r.RequestURI 是未经
    解析的原始请求行,客户端可控。转义 \n / \r 为字面字符
  - adapter/volcano/synthesis.go: 上游非 200 响应体 (rawBody)
    可能是攻击者控制的恶意内容,转义后再嵌入错误消息
 2026-08-26 11:52:28 +08:00
sun a238e5c2a4 chore: 忽略本地 TODO.md,避免误提交 
TODO.md 是本地待办清单,通过任务看板追踪更合适,不入 git 仓库。
 2026-08-26 00:37:15 +08:00
sun 272565f736 fix: VUL-003 完整修复,启发式/精确双模式 XFF 解析 
VUL-003 (中): X-Forwarded-For 信任链可被伪造 IP 绕过限流

本服务定位为公网入口,即使单人使用,公网暴露意味着攻击面
与公开服务等同,不能"够用就行"。

采用渐进式披露设计,平衡易用性与功能性:

  1. 启发式模式(默认, 不设环境变量 或 TRUSTED_PROXY_HOPS=0)
     - 从 XFF 链尾扫描,跳过私有 IP,返回第一个公网 IP
     - 适合 90% 部署(单跳/多跳/直出),无需了解精确跳数
     - 限制:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"
     - 直出部署:整个 XFF 分支不会执行

  2. 精确模式(TRUSTED_PROXY_HOPS=N, N>0)
     - 从 XFF 链尾倒数第 N+1 个位置取值
     - 精准到真实 client,需按实际反代跳数正确配置
     - N=1:单跳反代;N=2:CDN+反代;以此类推

  3. 两种模式都从链尾扫描
     - XFF 首值是客户端可控的,信任首值等于信任攻击者
     - 链尾由受控的反代添加,天然免疫伪造绕过

  4. 默认值从 1 改为 0(行为变化)
     - 旧默认:精确模式 N=1,取 XFF 末值
     - 新默认:启发式模式,跳过链尾私有 IP
     - 对单跳场景行为相同
     - 对多跳/链尾含私有 IP 场景新版更准确(返回真实公网 IP)

  5. 配套
     - middleware/ratelimit_test.go:24 个表驱动测试用例,
       覆盖直出/单跳/多跳/伪造/畸形/精确 N 边界,全部通过
     - setting/config.go:LogStartupSummary 显示当前 XFF 模式
     - .env.example:重写说明,标注默认行为 + 何时需配
     - README.md:新增"反代拓扑与 X-Forwarded-For 解析"章节
       (何时需要/两种模式/行为对比/为什么从链尾/启动日志验证)

  6. 已知边界:TRUSTED_PROXY_HOPS=00 等被 Atoi 解析为 0 的
     输入归入启发式模式,日志不会出现"精确模式 0 跳"矛盾输出。
 2026-08-26 00:36:22 +08:00
sun ed3d7c6b61 本次代码审查(全 12 个包,约 2400 行)的交付物: 
- 9 项漏洞(高 1 / 中 2 / 低 4 / 信息 2)
  - 已核查无风险项 8 条
  - 工程债务记录(零测试、死代码、云盘占用)
  - 安全加固建议(Docker 密钥传递、TLS、依赖固定)

供后续按优先级处理备查。
"
 2026-08-25 23:10:34 +08:00
sun 72d0d6a3a9 VUL-001 (中): aac/flac 响应 Content-Type 与真实数据不一致 
controller.tts.go:contentTypeFor 对 aac/flac 返回 audio/aac/flac,
  但 adapter/volcano/synthesis.go 在上游降级时仅修改 opts.Format,
  finalFormat 仍保留 clientFormat,导致响应头与字节流不符。
  修复:finalFormat 改为反映真实输出格式(非 wav 时取 opts.Format),
  客户端按 AAC/FLAC 解码 MP3 流的失败场景消除。

VUL-004 (高): .env 凭据泄露
  README 引导用户 cp .env.example .env 填密钥,但 .gitignore
  未忽略 .env,任何 git add . 都会把含 BYTEDANCE_TTS_API_KEY
  的文件提交进 git 历史,不可逆。
  修复:
  - .gitignore 新增 Secrets section,拦截 .env 与 .env.* 变体,
    保留 .env.example 作为模板追踪
  - .dockerignore 升级为同名规则模式,覆盖未来 .env.local /
    .env.production 等变体,保证 git 与 docker 两通道一致

详见 VULNERABILITY_REPORT.md
"
 2026-08-25 23:09:47 +08:00
sun 78c72004bf chore: 删除 ratelimit_middleware.go.tmp 临时文件 
与 ratelimit_middleware.go 内容完全重复(SHA256 一致,1116 字节),
且无任何代码引用 .tmp 路径,属于误提交的开发期残留文件。
 2026-08-23 13:15:15 +08:00
sun 370a21760c fix: 限流和并发中间件跳过非 /v1/ 路由,避免监控路径污染计数 2026-08-16 18:50:33 +08:00
sun f971de6821 chore: 删除无用的预检测试脚本 _preflight.js 
该脚本仅用于本地测试，不属于项目核心代码，清理冗余文件减少项目杂乱度
 2026-08-16 18:43:56 +08:00
sun 0f7102a41d fix: 补上 dashboard 缺失的 formatBytes 函数定义 2026-08-16 18:41:33 +08:00
sun ec2b78533d test: add preflight check test script for cors 
新增了用于测试CORS预检请求的_node脚本，包含OPTIONS预检请求和实际POST请求的测试逻辑，用于验证接口的跨域配置是否正确。
 2026-08-16 18:35:34 +08:00
sun 36e0d87cec ui: 替换 unpkg 为 bootcdn 国内 CDN 2026-08-16 18:32:58 +08:00
sun c4e278d544 ui: 重写监控面板,解析Prometheus指标分组展示,移除原始文本iframe 2026-08-16 18:13:04 +08:00
sun 5519697f87 fix: merge case sentence and empty to handle audio frames with empty event field 2026-08-16 18:03:21 +08:00
sun 78bb7d87ab refactor: remove fallback audio collection in case empty after namespace fix 2026-08-16 17:56:49 +08:00
sun d516dddf1d fix: namespace 修正为 UnidirectionalTTS 匹配 HTTP 单向端点 2026-08-16 17:54:43 +08:00
sun 677f606935 fix: 修复上游省略event字段导致音频帧被丢弃的bug 2026-08-16 17:50:02 +08:00
sun 55244e9a45 fix: 修复 response.go switch 语句大括号结构错误 2026-08-16 17:32:00 +08:00
sun 483db85259 fix: 兼容上游 sentence 字段为对象/字符串两种形态,加 debug 打印无 event 元数据行 2026-08-16 17:27:20 +08:00
sun b4b8ec33ed docs: 重写README,补充BYTEDANCE_TTS_DEBUG调试日志独立小节 2026-08-16 14:41:07 +08:00
sun cdd143f7e2 docs: 移除复刻1.0相关内容，仅保留2.0 2026-08-15 19:17:42 +08:00
sun c84f99a13f docs: 更新README补充TTS可选参数、调试日志、音频格式说明 2026-08-15 19:12:40 +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 1455e4bf80 fix: 修复 synthesis.go 类型不匹配编译错误 ([]byte→string) 2026-08-15 17:55:13 +08:00
sun f75a8461d1 chore: 移除文件开头多余的UTF-8 BOM头 
修复多个文件中存在的隐藏BOM字符问题，包括go.mod、README.md、health.html和.env.example，同时更新go.sum文件的校验和
 2026-08-15 15:02:00 +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 638dcc7721 fix: 更新字节语音合成默认模型为音色复刻路由适配版本 
更新了默认模型值从seed-tts-2.0-standard为seed-icl-2.0，同步修改了配置检查逻辑、文档说明，修正了复刻音色的使用指引，解决默认模型与复刻资源不匹配导致的55000000错误问题。
 2026-07-01 15:02:43 +08:00
sun 7e2d050d51 feat(volcano): add upstream TTS request diagnostic log 
移除了README中旧的环境配置日志说明部分，新增火山TTS上游请求的诊断日志，打印关键请求参数和请求体用于排查问题
 2026-07-01 14:31:40 +08:00
sun f39c72acbe refactor(setting): 优化配置启动日志与错误提示 
1. 移除main.go中重复的TTS配置错误警告
2. 统一日志中文全角逗号格式
3. 新增TTS配置项脱敏掩码函数
4. 完善启动日志的必填项检查和状态展示
5. 调整TTS配置错误的提示文案，明确500路由情况
 2026-07-01 00:13:15 +08:00
sun 7e1102902d refactor(volcano adapter): 重构火山 TTS 适配器请求体结构与错误处理 
重构请求体为类型安全的结构体实现，替换原有的map动态构造方式；统一错误处理为fmt.Errorf包装原始错误，优化注释与代码格式，提升代码可维护性与可读性。
 2026-06-30 23:34:45 +08:00