sun/Volcano-Engine-TTS-UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

feat(settings): M3 全局设置 + voice 动态路由 + env 收敛

Browse Source 
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)
This commit is contained in:
sun
2026-08-29 22:40:53 +08:00
parent 70865a3cf4
commit 9db038dd05
6 changed files with 524 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
controller/settings.go
+284
View File
@@ -0,0 +1,284 @@
package controller
import (
"encoding/json"
"fmt"
"log"
"net/http"
"strconv"
"time"
"github.com/volcano-tts/tts-api/middleware"
"github.com/volcano-tts/tts-api/setting"
)
// SettingsResponse 是 GET /api/settings 的响应。
// API key 永远打码(借用 setting.maskAPIKey 风格,前 4 后 4 中间 ****)。
type SettingsResponse struct {
APIKey string `json:"api_key"` // 打码形式,例如 S_G8****naJ1
APIKeySet bool `json:"api_key_set"` // 是否已设置(用于前端判断要不要提示必填)
DefaultResourceID string `json:"default_resource_id"`
DefaultSpeaker string `json:"default_speaker"`
DefaultFormat string `json:"default_format"`
SampleRate int `json:"sample_rate"`
Model string `json:"model"`
ModelType int `json:"model_type"`
ExplicitLanguage string `json:"explicit_language"`
EnableSubtitle bool `json:"enable_subtitle"`
UpdatedAt string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
}
// SettingsGetHandler GET /api/settings
// 鉴权: RequireAdmin;store nil 时 503。
func SettingsGetHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
s := GetAdminStore()
if s == nil {
middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
return
}
all, err := s.SettingsGetAll()
if err != nil {
log.Printf("[settings] getall: %v", err)
middleware.SendJSONError(w, http.StatusInternalServerError, "read settings failed", "server_error", "db_read_failed")
return
}
resp := SettingsResponse{
APIKey: maskAPIKeyField(all["api_key"]),
APIKeySet: all["api_key"] != "",
DefaultResourceID: all["default_resource_id"],
DefaultSpeaker: all["default_speaker"],
DefaultFormat: all["default_format"],
Model: all["model"],
ExplicitLanguage: all["explicit_language"],
}
if v, _ := s.SettingsGetInt("sample_rate", 0); v > 0 {
resp.SampleRate = v
}
if v, _ := s.SettingsGetInt("model_type", 0); v > 0 {
resp.ModelType = v
}
if v, _ := s.SettingsGetBool("enable_subtitle", false); v {
resp.EnableSubtitle = true
}
if ts := all["installed_at"]; ts != "" {
resp.UpdatedAt = ts
}
w.Header().Set("Content-Type", "application/json; charset=utf-8")
_ = json.NewEncoder(w).Encode(resp)
}
// SettingsUpdateRequest 是 PUT /api/settings 的 body(部分更新)。
// 字段都是可选;只更新非空 / 非零值。
type SettingsUpdateRequest struct {
APIKey *string `json:"api_key,omitempty"` // 用指针区分 "未传" vs "传空串"
DefaultResourceID *string `json:"default_resource_id,omitempty"`
DefaultSpeaker *string `json:"default_speaker,omitempty"`
DefaultFormat *string `json:"default_format,omitempty"`
SampleRate *int `json:"sample_rate,omitempty"`
Model *string `json:"model,omitempty"`
ModelType *int `json:"model_type,omitempty"`
ExplicitLanguage *string `json:"explicit_language,omitempty"`
EnableSubtitle *bool `json:"enable_subtitle,omitempty"`
}
// SettingsUpdateHandler PUT /api/settings
// 鉴权: RequireAdmin;store nil 时 503。
// 至少要改 1 个字段(空 body 返 400);api_key 修改走专用端点 /api/settings/api-key。
func SettingsUpdateHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPut {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
s := GetAdminStore()
if s == nil {
middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
return
}
r.Body = http.MaxBytesReader(w, r.Body, 1<<16) // 64KB
var body SettingsUpdateRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
return
}
// 收集要更新的键值对
updates := make(map[string]string)
if body.DefaultResourceID != nil {
v := trimAll(*body.DefaultResourceID)
if v == "" {
middleware.SendJSONError(w, http.StatusBadRequest, "default_resource_id cannot be empty", "invalid_request_error", "missing_field")
return
}
updates["default_resource_id"] = v
}
if body.DefaultSpeaker != nil {
v := trimAll(*body.DefaultSpeaker)
if v == "" {
middleware.SendJSONError(w, http.StatusBadRequest, "default_speaker cannot be empty", "invalid_request_error", "missing_field")
return
}
// 校验音色在库中(避免 default_speaker 引用不存在的 voice)
if _, err := s.VoiceGetByName(v); err != nil {
middleware.SendJSONError(w, http.StatusBadRequest,
fmt.Sprintf("default_speaker %q not found in voices table", v),
"invalid_request_error", "default_speaker_missing")
return
}
updates["default_speaker"] = v
}
if body.DefaultFormat != nil {
v := trimAll(*body.DefaultFormat)
if !isValidFormat(v) {
middleware.SendJSONError(w, http.StatusBadRequest,
fmt.Sprintf("default_format %q invalid; valid: mp3/wav/opus/pcm/aac/flac", v),
"invalid_request_error", "format_invalid")
return
}
updates["default_format"] = v
}
if body.SampleRate != nil {
v := *body.SampleRate
if v < 8000 || v > 48000 {
middleware.SendJSONError(w, http.StatusBadRequest,
"sample_rate must be 8000-48000", "invalid_request_error", "sample_rate_invalid")
return
}
updates["sample_rate"] = strconv.Itoa(v)
}
if body.Model != nil {
updates["model"] = trimAll(*body.Model)
}
if body.ModelType != nil {
updates["model_type"] = strconv.Itoa(*body.ModelType)
}
if body.ExplicitLanguage != nil {
updates["explicit_language"] = trimAll(*body.ExplicitLanguage)
}
if body.EnableSubtitle != nil {
updates["enable_subtitle"] = boolToStr(*body.EnableSubtitle)
}
if len(updates) == 0 {
middleware.SendJSONError(w, http.StatusBadRequest,
"at least one field is required (use /api/settings/api-key to change api_key)",
"invalid_request_error", "no_fields")
return
}
// 写入 DB
if err := s.SettingsSetBatch(updates); err != nil {
log.Printf("[settings] update: %v", err)
middleware.SendJSONError(w, http.StatusInternalServerError, "write settings failed", "server_error", "db_write_failed")
return
}
// 关键: 更新后**立刻刷新运行时缓存**,M3 要求"改设置实时生效"
if err := setting.LoadRuntimeConfig(s); err != nil {
log.Printf("[settings] reload runtime: %v", err)
// 不返 500:DB 已写,只是 reload 失败;下次启动会生效
middleware.SendJSONError(w, http.StatusInternalServerError,
"settings saved but runtime reload failed; restart required",
"server_error", "reload_failed")
return
}
log.Printf("[settings] updated %d fields, runtime reloaded", len(updates))
w.Header().Set("Content-Type", "application/json; charset=utf-8")
_ = json.NewEncoder(w).Encode(map[string]any{
"ok": true,
"updated": len(updates),
"updated_at": time.Now().UTC().Format(time.RFC3339),
})
}
// SettingsAPIKeyRequest 是 PUT /api/settings/api-key 的 body。
type SettingsAPIKeyRequest struct {
APIKey string `json:"api_key"`
}
// SettingsAPIKeyHandler PUT /api/settings/api-key
// 鉴权: RequireAdmin。专门改 api_key,因为它需要单独的安全处理(不能 mask,要走加密通道)。
func SettingsAPIKeyHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPut {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
s := GetAdminStore()
if s == nil {
middleware.SendJSONError(w, http.StatusServiceUnavailable, "database not ready", "configuration_error", "db_not_ready")
return
}
r.Body = http.MaxBytesReader(w, r.Body, 1<<10) // 1KB
var body SettingsAPIKeyRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
middleware.SendJSONError(w, http.StatusBadRequest, "invalid JSON body", "invalid_request_error", "bad_request")
return
}
key := trimAll(body.APIKey)
if key == "" {
middleware.SendJSONError(w, http.StatusBadRequest, "api_key cannot be empty", "invalid_request_error", "missing_field")
return
}
if err := s.SettingsSet("api_key", key); err != nil {
log.Printf("[settings] api-key set: %v", err)
middleware.SendJSONError(w, http.StatusInternalServerError, "write api_key failed", "server_error", "db_write_failed")
return
}
if err := setting.LoadRuntimeConfig(s); err != nil {
log.Printf("[settings] reload after api-key: %v", err)
middleware.SendJSONError(w, http.StatusInternalServerError,
"api_key saved but runtime reload failed", "server_error", "reload_failed")
return
}
log.Printf("[settings] api_key updated, runtime reloaded")
w.Header().Set("Content-Type", "application/json; charset=utf-8")
_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
}
// maskAPIKeyField 复用 setting 包的打码风格(前 4 后 4 中间 ****)。
// 单独导出版本避免从 setting 包拉整个 APIKeyMask 之类的工具(那个是 unexported)。
func maskAPIKeyField(s string) string {
if s == "" {
return ""
}
if len(s) <= 4 {
return "****"
}
// 仿 setting.maskAPIKey: 但这里打的是 TTS 服务用的 key,可能含字母数字和连字符
return s[:4] + "****" + s[len(s)-4:]
}
func trimAll(s string) string {
// 简单 trim 前后空白;不剥中间空格
out := s
for len(out) > 0 && (out[0] == ' ' || out[0] == '\t' || out[0] == '\n' || out[0] == '\r') {
out = out[1:]
}
for len(out) > 0 && (out[len(out)-1] == ' ' || out[len(out)-1] == '\t' || out[len(out)-1] == '\n' || out[len(out)-1] == '\r') {
out = out[:len(out)-1]
}
return out
}
func isValidFormat(s string) bool {
switch s {
case "mp3", "wav", "opus", "pcm", "aac", "flac", "":
return true
}
return false
}
func boolToStr(b bool) string {
if b {
return "1"
}
return "0"
}
controller/tts.go
+39
View File
@@ -18,6 +18,7 @@ import (
"github.com/volcano-tts/tts-api/metrics"
"github.com/volcano-tts/tts-api/middleware"
"github.com/volcano-tts/tts-api/setting"
"github.com/volcano-tts/tts-api/store"
"github.com/volcano-tts/tts-api/telemetry"
"github.com/volcano-tts/tts-api/version"
)
@@ -153,6 +154,44 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
opts := setting.TTSOptions
opts.Text = req.Input
// M3: voice 路由
// - voice 为空 → 用 setting.TTSOptions.Speaker (即 store 里的 default_speaker)
// - voice 非空 → 查 voices 表,替换 opts.Speaker / ResourceID / Model
// - 命中但 enabled=0 → 仍可用(用户显式传 voice 即覆盖 enabled 状态;若想禁用在 admin UI 关掉就行)
// - 未命中 → 400 "unknown voice: <name>"
if req.Voice != "" {
s := GetAdminStore()
if s == nil {
log.Printf("警告: voice=%s 路由但 store 未初始化 - 路径=%s", req.Voice, r.URL.Path)
middleware.SendJSONError(w, http.StatusServiceUnavailable,
"voice routing requires database; not initialized",
"configuration_error", "db_not_ready")
return
}
v, err := s.VoiceGetByName(req.Voice)
if err != nil {
if err == store.ErrNotFound {
log.Printf("警告: 未知 voice=%s - 路径=%s 客户端=%s", req.Voice, r.URL.Path, middleware.GetClientIP(r))
middleware.SendJSONError(w, http.StatusBadRequest,
fmt.Sprintf("unknown voice: %s", req.Voice),
"invalid_request_error", "unknown_voice")
return
}
log.Printf("警告: voice 查库失败 - 错误=%v voice=%s", err, req.Voice)
middleware.SendJSONError(w, http.StatusInternalServerError,
"voice lookup failed", "server_error", "db_read_failed")
return
}
// 覆盖 opts(API key / UID 保留自 setting.TTSOptions)
opts.Speaker = v.Speaker
opts.ResourceID = v.ResourceID
if v.Model != "" {
opts.Model = v.Model
}
log.Printf("[tts] voice=%s 命中 (speaker=%s resource=%s model=%s) - 客户端=%s",
req.Voice, v.Speaker, v.ResourceID, v.Model, middleware.GetClientIP(r))
}
ctx, cancel := context.WithTimeout(r.Context(), setting.TTSTimeout)
defer cancel()