+
+
+ 运行模式
+
+
+ {{ overview.installed ? '已就绪' : '待配置' }}
+
-
-
音色
-
{{ overview.voice_count ?? 0 }}条
-
-
-
-
运行时间
-
{{ formatUptime(overview.uptime_seconds) }}
-
-
-
-
数据库
-
{{ shortPath(overview.db_path) || '—' }}
-
+
{{ overview.mode || '—' }}
+
+
+
音色
+
{{ overview.voice_count ?? 0 }}条
+
-
-
-
-
- - Commit
- {{ overview.commit || 'dev' }}
- - 版本
- {{ overview.version || '—' }}
- - 运行模式
- {{ overview.mode || '—' }}
- - 数据库路径
- {{ overview.db_path || '—' }}
- - 锁文件
- {{ overview.lock_path || '—' }}
-
-
- 内存
- -
- goroutines {{ overview.memory?.goroutines ?? '—' }} · heap {{ formatBytes(overview.memory?.heap_alloc) }}
-
-
-
+
+
运行时间
+
{{ formatUptime(overview.uptime_seconds) }}
+
-
-
-
-
-
-
-
-
⚠
-
-
操作失败
-
{{ actionErr }}
-
-
-
-
-
-
♪
-
还没有音色
-
点击右上角「+ 新增音色」开始添加第一个火山 TTS 音色
-
-
-
-
-
⌕
-
没有匹配的音色
-
尝试调整搜索词或筛选条件
-
-
-
-
-
-
-
-
-
-
-
鉴权 Key
-
客户端调用 /v1/audio/speech 与登录 /admin 共用
-
-
敏感
-
-
-
-
{{ settings.auth_key || '(未设置)' }}
-
-
-
-
-
-
-
-
改了之后,你的浏览器 401 自动跳回登录页,用新 Key 重登。
-
-
-
-
-
-
-
火山 TTS 上游凭证
-
调火山 v3 上游用的凭证与默认路由
-
-
-
-
-
{{ settings.api_key || '(未设置)' }}
-
-
-
-
-
-
-
-
独立端点 PUT /api/settings/api-key,与其他字段分开传输
-
-
-
-
-
-
-
-
-
-
-
必须是「音色」tab 里存在的 name
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
跨域 CORS
-
控制哪些前端域名能跨域调 /v1/audio/speech
-
-
-
- {{ settings.cors_configured ? '已配置' : '未配置' }}
-
-
-
-
-
勾上后下面白名单失效。仅测试用
-
-
-
-
-
一行一个。当前: {{ corsCurrentLabel }}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
新增音色
-
-
-
-
+
+
数据库
+
{{ shortPath(overview.db_path) || '—' }}
+
-
-
+
+
+
+
+ - Commit
- {{ overview.commit || 'dev' }}
+ - 版本
- {{ overview.version || '—' }}
+ - 运行模式
- {{ overview.mode || '—' }}
+ - 数据库路径
- {{ overview.db_path || '—' }}
+ - 锁文件
- {{ overview.lock_path || '—' }}
+
+
- 内存
+ -
+ goroutines {{ overview.memory?.goroutines ?? '—' }} · heap {{ formatBytes(overview.memory?.heap_alloc) }}
+
+
+
+
+
+
+
diff --git a/router/router.go b/router/router.go
index c82781d..f86a7b6 100644
--- a/router/router.go
+++ b/router/router.go
@@ -21,6 +21,21 @@ var setupHTML []byte
//go:embed admin.html
var adminHTML []byte
+//go:embed admin-login.html
+var adminLoginHTML []byte
+
+//go:embed admin-voices.html
+var adminVoicesHTML []byte
+
+//go:embed admin-settings.html
+var adminSettingsHTML []byte
+
+//go:embed admin.css
+var adminCSS []byte
+
+//go:embed admin-shell.js
+var adminShellJS []byte
+
// Setup 返回主路由。
// 中间件顺序(由外向内):
// SecurityHeaders → InstallGuard → RateLimit → ConcurrencyLimit → Logger → handler
@@ -64,9 +79,21 @@ func Setup() *mux.Router {
// /admin 管理后台(M2);HTML 本身公开,鉴权由前端 JS 拦截
// (sessionStorage 没 key 就显示登录页;有 key 调 /api/admin/overview 触发 401 跳登录)
// API 端点(/api/admin/* /api/voices*)才需要 RequireAdmin。
- r.HandleFunc("/admin", func(w http.ResponseWriter, req *http.Request) {
- w.Header().Set("Content-Type", "text/html; charset=utf-8")
- _, _ = w.Write(adminHTML)
+ //
+ // 拆分后 admin.html / admin-login.html / admin-voices.html / admin-settings.html
+ // 各自独立,URL 路由切换;共享 admin.css + admin-shell.js 由 adminStatic 提供。
+ r.HandleFunc("/admin", serveAdmin(adminHTML)).Methods("GET")
+ r.HandleFunc("/admin/login", serveAdmin(adminLoginHTML)).Methods("GET")
+ r.HandleFunc("/admin/voices", serveAdmin(adminVoicesHTML)).Methods("GET")
+ r.HandleFunc("/admin/settings", serveAdmin(adminSettingsHTML)).Methods("GET")
+ // admin 静态资源
+ r.HandleFunc("/admin/admin.css", func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/css; charset=utf-8")
+ _, _ = w.Write(adminCSS)
+ }).Methods("GET")
+ r.HandleFunc("/admin/admin-shell.js", func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/javascript; charset=utf-8")
+ _, _ = w.Write(adminShellJS)
}).Methods("GET")
// /api/admin/overview (鉴权)
@@ -132,3 +159,12 @@ func acceptsHTML(accept string) bool {
}
return false
}
+
+// serveAdmin 返回一个把 embed 的 HTML bytes 以 text/html 写出的 handler。
+// 抽出来只为让 /admin/voices 等多条路由的注册保持单行,避免重复 4 段。
+func serveAdmin(body []byte) http.HandlerFunc {
+ return func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/html; charset=utf-8")
+ _, _ = w.Write(body)
+ }
+}
diff --git a/setting/config.go b/setting/config.go
index 189326a..748fee8 100644
--- a/setting/config.go
+++ b/setting/config.go
@@ -8,6 +8,7 @@ import (
"os"
"strconv"
"strings"
+ "sync"
"time"
"github.com/volcano-tts/tts-api/adapter/volcano"
@@ -16,30 +17,129 @@ import (
)
// 全部环境变量读取的单一入口:其它包不允许直接 os.Getenv,只读这里的全局 Config。
-
-// TTSOptions 是火山 v3 TTS 调用的完整参数集合,启动期由 LoadRuntimeConfig 从 store 填充。
-// 业务侧(controller)直接读取并传入 volcano.Synthesis。
+//
+// 并发模型:
+// - TTSOptions / TTSTimeout / TTSConfigErr / Auth.APIKeys / CORS 是运行期可被
+// LoadRuntimeConfig(由 PUT /api/settings 触发)整体替换的"运行时配置快照"。
+// struct 整体赋值不是原子的,若 TTS 请求正在读,可能拿到半写状态。
+// - 解决: 用 ttsMu(RWMutex)统一保护这些字段;读路径用 Get* 拿快照(RLock),
+// 写路径用 Set* 整体替换(Lock)。读多写少,RWMutex 读不互斥,不会显著拖慢热路径。
+// - Server.Port / TrustedProxyHops / SetupToken 仅启动期写、运行期读,无并发修改,
+// 保持原样不加锁。
var (
- TTSOptions volcano.Options
- TTSConfigErr error
- // TTSTimeout 单次合成请求的超时;controller 用来派生 context。
- TTSTimeout time.Duration = common.DefaultTimeout
+ ttsMu sync.RWMutex
+ ttsOptions volcano.Options
+ ttsTimeout time.Duration = common.DefaultTimeout
+ ttsConfigErr error
+ authAPIKeys []string
+ // corsAllowAll / corsOrigins 拆成两个独立字段,各自在 RLock 下读取,
+ // 避免 CORSConfig 整体读时被 Lock 阻塞热路径。
+ corsAllowAll bool
+ corsOrigins []string
)
-// AuthConfig OpenAI 兼容接口的客户端 API Key 鉴权配置。
-type AuthConfig struct {
- APIKeys []string
+// GetTTSOptions 读 TTSOptions 快照(值类型,使用方可以放心使用,不会被并发写破坏)。
+// 提供给业务侧(controller)的统一读取入口;LoadRuntimeConfig 写入时用 SetTTSOptions 整体替换。
+// 业务侧不要缓存这个值跨 goroutine 使用(应该每次调用时重新拿)。
+func GetTTSOptions() volcano.Options {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ return ttsOptions
}
-var Auth AuthConfig
-
-// CORSConfig 跨域白名单配置。
-type CORSConfig struct {
- Origins []string
- AllowAll bool
+// SetTTSOptions 整体替换 TTSOptions。LoadRuntimeConfig 写路径专用。
+func SetTTSOptions(o volcano.Options) {
+ ttsMu.Lock()
+ defer ttsMu.Unlock()
+ ttsOptions = o
}
-var CORS CORSConfig
+// GetTTSTimeout 读当前超时;controller 用它派生 context。
+func GetTTSTimeout() time.Duration {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ return ttsTimeout
+}
+
+// SetTTSTimeout 整体替换超时。
+func SetTTSTimeout(d time.Duration) {
+ ttsMu.Lock()
+ defer ttsMu.Unlock()
+ ttsTimeout = d
+}
+
+// GetTTSConfigErr 读运行时配置错误;nil 表示就绪。
+func GetTTSConfigErr() error {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ return ttsConfigErr
+}
+
+// SetTTSConfigErr 设运行时配置错误;nil 表示清错。
+func SetTTSConfigErr(err error) {
+ ttsMu.Lock()
+ defer ttsMu.Unlock()
+ ttsConfigErr = err
+}
+
+// GetAuthAPIKeys 读鉴权 key 列表;返回拷贝防止业务侧持有底层 slice 后被并发写破坏。
+// 外部不应直接读 Auth.APIKeys,统一走 Get*。
+func GetAuthAPIKeys() []string {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ if len(authAPIKeys) == 0 {
+ return nil
+ }
+ out := make([]string, len(authAPIKeys))
+ copy(out, authAPIKeys)
+ return out
+}
+
+// SetAuthAPIKeys 整体替换鉴权 key 列表;入参被复制以防外部后续修改影响内部状态。
+func SetAuthAPIKeys(keys []string) {
+ ttsMu.Lock()
+ defer ttsMu.Unlock()
+ if len(keys) == 0 {
+ authAPIKeys = nil
+ return
+ }
+ out := make([]string, len(keys))
+ copy(out, keys)
+ authAPIKeys = out
+}
+
+// GetCORSAllowAll 读 CORS 是否放行所有来源。
+func GetCORSAllowAll() bool {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ return corsAllowAll
+}
+
+// GetCORSOrigins 读 CORS 白名单;返回拷贝防止业务侧持有后被并发写破坏。
+func GetCORSOrigins() []string {
+ ttsMu.RLock()
+ defer ttsMu.RUnlock()
+ if len(corsOrigins) == 0 {
+ return nil
+ }
+ out := make([]string, len(corsOrigins))
+ copy(out, corsOrigins)
+ return out
+}
+
+// SetCORS 整体替换 CORS 配置;LoadRuntimeConfig 和 PUT /api/settings/cors 写路径专用。
+func SetCORS(allowAll bool, origins []string) {
+ ttsMu.Lock()
+ defer ttsMu.Unlock()
+ corsAllowAll = allowAll
+ if len(origins) == 0 {
+ corsOrigins = nil
+ return
+ }
+ out := make([]string, len(origins))
+ copy(out, origins)
+ corsOrigins = out
+}
// ServerConfig HTTP 服务监听配置。
type ServerConfig struct {
@@ -52,6 +152,8 @@ var Server ServerConfig
// 表示当前 XFF 解析模式:0=启发式,N>0=精确 N 跳。
// setting.LogStartupSummary 读这个字段以展示运行期配置,
// 不直接调用 middleware(避免循环 import)。
+//
+// 【并发】仅启动期被 InitRateLimiter 写一次,运行期只读,无并发问题,不加锁。
var TrustedProxyHops int
// SetupToken 是安装模式下的初始化凭证。
@@ -60,6 +162,8 @@ var TrustedProxyHops int
// 打印到日志(/api/setup 提交时必须带这个 token)
//
// 安装完成后,/api/setup 端点永久关闭,SetupToken 失去意义但保留在内存。
+//
+// 【并发】仅 setup 阶段使用,运行期不会再写,无并发问题,不加锁。
var SetupToken string
// SetupTokenSource 标记 SetupToken 的来源,便于日志区分。
@@ -87,7 +191,7 @@ func InitServerConfig() {
func InitAuthConfig() {
raw := os.Getenv("OPENAI_TTS_API_KEY")
if raw == "" {
- Auth.APIKeys = nil
+ SetAuthAPIKeys(nil)
return
}
parts := strings.Split(raw, ",")
@@ -98,27 +202,27 @@ func InitAuthConfig() {
keys = append(keys, k)
}
}
- Auth.APIKeys = keys
+ SetAuthAPIKeys(keys)
}
func InitCORSConfig() {
raw := os.Getenv("ALLOWED_ORIGINS")
- CORS.Origins = nil
- CORS.AllowAll = false
- if raw == "" {
- return
- }
- for _, p := range strings.Split(raw, ",") {
- o := strings.TrimSpace(p)
- if o == "" {
- continue
+ allowAll := false
+ var origins []string
+ if raw != "" {
+ for _, p := range strings.Split(raw, ",") {
+ o := strings.TrimSpace(p)
+ if o == "" {
+ continue
+ }
+ if o == "*" {
+ allowAll = true
+ continue
+ }
+ origins = append(origins, normalizeOrigin(o))
}
- if o == "*" {
- CORS.AllowAll = true
- continue
- }
- CORS.Origins = append(CORS.Origins, normalizeOrigin(o))
}
+ SetCORS(allowAll, origins)
}
func normalizeOrigin(origin string) string {
@@ -129,7 +233,7 @@ func normalizeOrigin(origin string) string {
// SplitOriginsForCORS 解析逗号/换行/空格分隔的 origins 列表,
// 全部小写、trim 末尾 / 后面统一比较。导出供 controller 复用
-// (PUT /api/settings/cors 写完立即刷新 setting.CORS 用)。
+// (PUT /api/settings/cors 写完立即刷新 CORS 用)。
func SplitOriginsForCORS(s string) []string {
return splitAndLowerOrigins(s)
}
@@ -160,6 +264,9 @@ func splitAndLowerOrigins(s string) []string {
// - 失败时 TTSConfigErr 被设置,/v1/audio/speech 路由会返 503
// - 成功时清空 TTSConfigErr
//
+// 【并发】所有写都走 Set* 系列函数,在 ttsMu.Lock 下完成;运行中的 TTS 请求
+// 用 Get* 拿快照不会读到半写状态。
+//
// 字段映射(原 env → store key):
// BYTEDANCE_TTS_API_KEY → api_key
// BYTEDANCE_TTS_RESOURCE_ID → default_resource_id
@@ -180,8 +287,9 @@ func splitAndLowerOrigins(s string) []string {
func LoadRuntimeConfig(s Store) error {
all, err := s.SettingsGetAll()
if err != nil {
- TTSConfigErr = fmt.Errorf("read settings failed: %w", err)
- return TTSConfigErr
+ wrapped := fmt.Errorf("read settings failed: %w", err)
+ SetTTSConfigErr(wrapped)
+ return wrapped
}
apiKey := all["api_key"]
@@ -198,8 +306,9 @@ func LoadRuntimeConfig(s Store) error {
missing = append(missing, "default_speaker")
}
if len(missing) > 0 {
- TTSConfigErr = fmt.Errorf("missing required settings: %v", missing)
- return TTSConfigErr
+ wrapped := fmt.Errorf("missing required settings: %v", missing)
+ SetTTSConfigErr(wrapped)
+ return wrapped
}
// 【BUG 修复 · 第二轮】default_speaker 是 voice **名字**(如 "chun"),
@@ -248,14 +357,15 @@ func LoadRuntimeConfig(s Store) error {
}
}
- TTSTimeout = common.DefaultTimeout
+ timeout := common.DefaultTimeout
if v, err := s.SettingsGetDuration("timeout", common.DefaultTimeout); err == nil {
- TTSTimeout = v
+ timeout = v
} else {
- TTSTimeout = common.DefaultTimeout
+ timeout = common.DefaultTimeout
}
+ SetTTSTimeout(timeout)
- TTSOptions = volcano.Options{
+ SetTTSOptions(volcano.Options{
APIKey: apiKey,
ResourceID: resourceId,
UID: "uid",
@@ -268,18 +378,17 @@ func LoadRuntimeConfig(s Store) error {
LoudnessRate: 0,
EnableSubtitle: enableSubtitle,
Additions: adds,
- }
+ })
// 鉴权 key:DB > env(向后兼容)
authKey := all["auth_key"]
if authKey == "" {
authKey = os.Getenv("OPENAI_TTS_API_KEY")
}
- // 用临时 slice 避免和 InitAuthConfig 抢同一个 Auth.APIKeys 底层
if authKey != "" {
- Auth.APIKeys = []string{authKey}
+ SetAuthAPIKeys([]string{authKey})
} else {
- Auth.APIKeys = nil
+ SetAuthAPIKeys(nil)
}
// CORS 配置:DB > env
@@ -298,17 +407,14 @@ func LoadRuntimeConfig(s Store) error {
originsStr = os.Getenv("ALLOWED_ORIGINS")
}
if corsAllowAll {
- CORS.AllowAll = true
- CORS.Origins = nil
+ SetCORS(true, nil)
} else if originsStr != "" {
- CORS.AllowAll = false
- CORS.Origins = SplitOriginsForCORS(originsStr)
+ SetCORS(false, SplitOriginsForCORS(originsStr))
} else {
- CORS.AllowAll = false
- CORS.Origins = nil
+ SetCORS(false, nil)
}
- TTSConfigErr = nil
+ SetTTSConfigErr(nil)
return nil
}
@@ -388,10 +494,16 @@ func InitSetupToken() {
// CheckEnvironmentVariables 返回 /health 用的环境变量状态快照。
func CheckEnvironmentVariables() map[string]interface{} {
+ // 一次性拿所有需要的快照,缩短锁占用窗口;后续只读本地变量。
+ opts := GetTTSOptions()
+ authKeys := GetAuthAPIKeys()
+ allowAll := GetCORSAllowAll()
+ origins := GetCORSOrigins()
+
required := map[string]bool{
- "BYTEDANCE_TTS_API_KEY": TTSOptions.APIKey != "",
- "BYTEDANCE_TTS_RESOURCE_ID": TTSOptions.ResourceID != "",
- "BYTEDANCE_TTS_SPEAKER": TTSOptions.Speaker != "",
+ "BYTEDANCE_TTS_API_KEY": opts.APIKey != "",
+ "BYTEDANCE_TTS_RESOURCE_ID": opts.ResourceID != "",
+ "BYTEDANCE_TTS_SPEAKER": opts.Speaker != "",
}
missing := []string{}
for k, ok := range required {
@@ -400,12 +512,12 @@ func CheckEnvironmentVariables() map[string]interface{} {
}
}
optional := map[string]bool{
- "BYTEDANCE_TTS_MODEL": TTSOptions.Model != "",
- "BYTEDANCE_TTS_FORMAT": TTSOptions.Format != "mp3",
- "BYTEDANCE_TTS_SAMPLE_RATE": TTSOptions.SampleRate != 24000,
- "BYTEDANCE_TTS_EXPLICIT_LANGUAGE": TTSOptions.Additions != nil && TTSOptions.Additions.ExplicitLanguage != "",
- "OPENAI_TTS_API_KEY": len(Auth.APIKeys) > 0,
- "ALLOWED_ORIGINS": CORS.AllowAll || len(CORS.Origins) > 0,
+ "BYTEDANCE_TTS_MODEL": opts.Model != "",
+ "BYTEDANCE_TTS_FORMAT": opts.Format != "mp3",
+ "BYTEDANCE_TTS_SAMPLE_RATE": opts.SampleRate != 24000,
+ "BYTEDANCE_TTS_EXPLICIT_LANGUAGE": opts.Additions != nil && opts.Additions.ExplicitLanguage != "",
+ "OPENAI_TTS_API_KEY": len(authKeys) > 0,
+ "ALLOWED_ORIGINS": allowAll || len(origins) > 0,
"PORT": Server.Port != common.DefaultPort,
}
return map[string]interface{}{
@@ -421,18 +533,21 @@ func LogStartupSummary() {
log.Printf("=== 环境配置汇总 ===")
log.Printf("服务端口: %s", Server.Port)
- if len(Auth.APIKeys) == 0 {
+ authKeys := GetAuthAPIKeys()
+ if len(authKeys) == 0 {
log.Printf("OPENAI_TTS_API_KEY: 未设置(所有请求无需鉴权)")
} else {
- log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(Auth.APIKeys))
+ log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(authKeys))
}
- if CORS.AllowAll {
+ allowAll := GetCORSAllowAll()
+ origins := GetCORSOrigins()
+ if allowAll {
log.Printf("ALLOWED_ORIGINS: *(允许所有跨域;不可与鉴权共用)")
- } else if len(CORS.Origins) == 0 {
+ } else if len(origins) == 0 {
log.Printf("ALLOWED_ORIGINS: 未设置(跨域请求将被拒绝)")
} else {
- log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(CORS.Origins))
+ log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(origins))
}
if h := TrustedProxyHops; h == 0 {
@@ -441,6 +556,9 @@ func LogStartupSummary() {
log.Printf("TRUSTED_PROXY_HOPS: 精确模式,信任 %d 跳反代", h)
}
+ // 一次性拿 TTSOptions 快照;后续只读本地变量,避免在多个 log.Printf 调用之间
+ // 被 LoadRuntimeConfig 整体替换导致打印出不连贯的数据。
+ opts := GetTTSOptions()
log.Printf("火山 TTS 必填项状态:")
type ttsCheck struct {
name string
@@ -448,10 +566,10 @@ func LogStartupSummary() {
ok bool
}
checks := []ttsCheck{
- {"BYTEDANCE_TTS_API_KEY", maskAPIKey(TTSOptions.APIKey), TTSOptions.APIKey != ""},
- {"BYTEDANCE_TTS_RESOURCE_ID", TTSOptions.ResourceID, TTSOptions.ResourceID != ""},
+ {"BYTEDANCE_TTS_API_KEY", maskAPIKey(opts.APIKey), opts.APIKey != ""},
+ {"BYTEDANCE_TTS_RESOURCE_ID", telemetry.MaskResourceID(opts.ResourceID), opts.ResourceID != ""},
// speaker 是火山复刻音色 ID(用户付费资产),日志里打码,避免明文落盘
- {"BYTEDANCE_TTS_SPEAKER", telemetry.MaskSpeaker(TTSOptions.Speaker), TTSOptions.Speaker != ""},
+ {"BYTEDANCE_TTS_SPEAKER", telemetry.MaskSpeaker(opts.Speaker), opts.Speaker != ""},
}
missingCount := 0
for _, c := range checks {
@@ -467,7 +585,7 @@ func LogStartupSummary() {
log.Printf(" %s %s: %s", mark, c.name, val)
}
- if TTSConfigErr != nil {
+ if err := GetTTSConfigErr(); err != nil {
log.Printf("火山 TTS 整体: 初始化失败(%d 个必填项缺失),/v1/audio/speech 路由将全部返回 500", missingCount)
} else {
log.Printf("火山 TTS 整体: 初始化成功")
diff --git a/store/setup.go b/store/setup.go
new file mode 100644
index 0000000..33168a7
--- /dev/null
+++ b/store/setup.go
@@ -0,0 +1,132 @@
+package store
+
+import (
+ "database/sql"
+ "errors"
+ "fmt"
+ "strings"
+)
+
+// SetupApply 原子提交:settings 批量写入 + voices 全部插入,任一失败整体回滚,
+// 保证 db 不会留下半残状态(原 controller 直接调 SettingsSetBatch + 循环
+// VoiceInsert 时,voice 第 3 条失败 → settings 已写、voice 1/2 已落、voice 4
+// 没了,db 处于"装了一半"的脏状态,只能靠重启救)。
+//
+// 行为契约:
+// - settingsKV 全部写入(settings 白名单校验复用 SettingsSetBatch 逻辑);
+// - voices 逐条插入;ErrInvalid 校验错误 → 整体回滚,errors.Is(err, ErrInvalid) 仍可用;
+// - voices 中已存在的 name 命中 ErrDuplicate → 静默跳过(不计 inserted,事务继续),
+// 兼容"重复 setup 同一组 voice"场景;
+// - 其它 voice 错误 → 整体回滚;
+// - 全部成功 → tx.Commit,返回 inserted count(不含被 ErrDuplicate 跳过的)。
+//
+// 不动 lock 文件:lock 由 controller 层(installer.CreateLock)管理,
+// 失败/成功都不应影响 db 事务(事务外)。
+func (s *Store) SetupApply(settingsKV map[string]string, voices []Voice) (inserted int, err error) {
+ tx, err := s.db.Begin()
+ if err != nil {
+ return 0, fmt.Errorf("store: setup apply begin: %w", err)
+ }
+ // defer Rollback:Commit 成功时 Rollback 返 sql.ErrTxDone,无害。
+ defer func() {
+ _ = tx.Rollback()
+ }()
+
+ // 1) 写 settings(同事务)
+ if len(settingsKV) > 0 {
+ if err := settingsSetBatchTx(tx, settingsKV); err != nil {
+ return 0, err
+ }
+ }
+
+ // 2) 逐条插 voice;ErrDuplicate 跳过,ErrInvalid/其它整体回滚
+ for i, v := range voices {
+ // trim 各字段,跟 VoiceInsert 保持一致(防止 controller 已经 trim 过但
+ // 未来调用方不 trim 时行为不一致)
+ v.Name = strings.TrimSpace(v.Name)
+ v.Speaker = strings.TrimSpace(v.Speaker)
+ v.ResourceID = strings.TrimSpace(v.ResourceID)
+ v.Model = strings.TrimSpace(v.Model)
+ v.Language = strings.TrimSpace(v.Language)
+ v.Description = strings.TrimSpace(v.Description)
+ // Enabled 走 setup 语义:用户主动配置时保留(允许 admin 预设 disabled);
+ // 但 controller.SetupSubmitHandler 走的是用户首次安装,统一 enabled=true。
+ // 这里不强制覆盖,保持原值(等同 VoiceInsert 行为)。
+
+ id, err := voiceInsertTx(tx, v)
+ if err != nil {
+ if errors.Is(err, ErrDuplicate) {
+ // 已存在,跳过(不计 inserted)
+ continue
+ }
+ // ErrInvalid / DB 错误等:整体回滚,把原始 error 透传(已 wrap ErrInvalid)
+ return 0, fmt.Errorf("store: setup apply voice[%d] %q: %w", i, v.Name, err)
+ }
+ _ = id // id 当前用不到,后续如果 controller 需要可加返回值
+ inserted++
+ }
+
+ if err := tx.Commit(); err != nil {
+ return 0, fmt.Errorf("store: setup apply commit: %w", err)
+ }
+ return inserted, nil
+}
+
+// settingsSetBatchTx 在已有 tx 上写 settings;逻辑跟 SettingsSetBatch 一致
+// 但用 tx 代替 s.db。失败时**不**回滚(交给 caller 决定);caller 拿 err 后
+// defer Rollback 兜底。
+func settingsSetBatchTx(tx *sql.Tx, kv map[string]string) error {
+ if len(kv) == 0 {
+ return nil
+ }
+ stmt, err := tx.Prepare(`
+ INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
+ ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
+ if err != nil {
+ return fmt.Errorf("store: settings setbatch prepare: %w", err)
+ }
+ defer stmt.Close()
+
+ for k, v := range kv {
+ if k == "" {
+ return fmt.Errorf("store: settings setbatch: empty key")
+ }
+ if !isAllowedSettingsKey(k) {
+ return fmt.Errorf("store: settings setbatch: key %q not in whitelist", k)
+ }
+ if _, err := stmt.Exec(k, v); err != nil {
+ return fmt.Errorf("store: settings setbatch exec %q: %w", k, err)
+ }
+ }
+ return nil
+}
+
+// voiceInsertTx 在已有 tx 上插 voice;跟 VoiceInsert 逻辑一致。
+// 校验(name 格式 / speaker / resource_id)用 ErrInvalid wrap;
+// 唯一冲突返 ErrDuplicate;其它错误返 wrap 的 db error。
+func voiceInsertTx(tx *sql.Tx, v Voice) (int64, error) {
+ if err := validateVoiceName(v.Name); err != nil {
+ return 0, fmt.Errorf("%w: %s", ErrInvalid, err.Error())
+ }
+ if v.Speaker == "" {
+ return 0, fmt.Errorf("%w: speaker is required", ErrInvalid)
+ }
+ if v.ResourceID == "" {
+ return 0, fmt.Errorf("%w: resource_id is required", ErrInvalid)
+ }
+ res, err := tx.Exec(`
+ INSERT INTO voices (name, speaker, resource_id, model, language, description, enabled, created_at, updated_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))`,
+ v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled))
+ if err != nil {
+ if isUniqueViolation(err) {
+ return 0, ErrDuplicate
+ }
+ return 0, fmt.Errorf("store: voice insert: %w", err)
+ }
+ id, err := res.LastInsertId()
+ if err != nil {
+ return 0, fmt.Errorf("store: voice insert lastid: %w", err)
+ }
+ return id, nil
+}
diff --git a/store/voices.go b/store/voices.go
index 152fa05..6d265b8 100644
--- a/store/voices.go
+++ b/store/voices.go
@@ -36,6 +36,11 @@ var ErrInUse = errors.New("store: voice is referenced by default_speaker")
// ErrNotFound 表示按 id/name 找不到;controller 翻译为 404。
var ErrNotFound = errors.New("store: voice not found")
+// ErrInvalid 表示客户端输入不合法(name 格式 / 必填字段缺失);
+// controller 用 errors.Is(err, ErrInvalid) 翻译为 400。
+// 服务端错误(DB 失败等)不会被 wrap,controller 应翻译为 500。
+var ErrInvalid = errors.New("store: voice invalid")
+
// voiceNameRe 限制 voice 名为 [a-zA-Z0-9_-]{1,64};SQL 注入 + 路径穿越防护。
var voiceNameRe = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
@@ -115,7 +120,9 @@ func (s *Store) GetVoiceForTTS(name string) (speaker, resourceID, model string,
}
// VoiceInsert 新增音色;name 冲突返回 ErrDuplicate。
-// 空字符串/格式不合法返回 error;不依赖 SQLite 约束作为唯一校验。
+// 客户端输入错误(name 格式 / 必填字段缺失)返回 wrap ErrInvalid 的 error;
+// 服务端错误(DB 失败等)不被 wrap,controller 用 errors.Is 区分。
+// 不依赖 SQLite 约束作为唯一校验。
func (s *Store) VoiceInsert(v Voice) (int64, error) {
v.Name = strings.TrimSpace(v.Name)
v.Speaker = strings.TrimSpace(v.Speaker)
@@ -125,13 +132,14 @@ func (s *Store) VoiceInsert(v Voice) (int64, error) {
v.Description = strings.TrimSpace(v.Description)
if err := validateVoiceName(v.Name); err != nil {
- return 0, err
+ // validateVoiceName 返纯文本;这里 wrap 进 ErrInvalid 让 controller 用 errors.Is 判定。
+ return 0, fmt.Errorf("%w: %s", ErrInvalid, err.Error())
}
if v.Speaker == "" {
- return 0, fmt.Errorf("store: voice insert: speaker is required")
+ return 0, fmt.Errorf("%w: speaker is required", ErrInvalid)
}
if v.ResourceID == "" {
- return 0, fmt.Errorf("store: voice insert: resource_id is required")
+ return 0, fmt.Errorf("%w: resource_id is required", ErrInvalid)
}
res, err := s.db.Exec(`
@@ -153,6 +161,12 @@ func (s *Store) VoiceInsert(v Voice) (int64, error) {
// VoiceUpdate 整行替换;name 仍需保持唯一。
// 不允许把 name 改成空/不合法。
+//
+// 同步 default_speaker:
+// - 改 name 前,先查旧记录
+// - 若 settings.default_speaker == 旧 name,把它改成新 name
+// - 整个 voice UPDATE + settings UPDATE 在同一事务里,
+// 失败回滚,避免"声音改了但 default_speaker 还指向旧名"导致火山查不到
func (s *Store) VoiceUpdate(v Voice) error {
v.Name = strings.TrimSpace(v.Name)
v.Speaker = strings.TrimSpace(v.Speaker)
@@ -171,7 +185,47 @@ func (s *Store) VoiceUpdate(v Voice) error {
return fmt.Errorf("store: voice update: resource_id is required")
}
- res, err := s.db.Exec(`
+ // 整段事务: 读旧名 → 同步 settings → UPDATE voice
+ tx, err := s.db.Begin()
+ if err != nil {
+ return fmt.Errorf("store: voice update begin: %w", err)
+ }
+ defer func() {
+ // commit 成功时 Rollback 返回 sql.ErrTxDone,无害
+ _ = tx.Rollback()
+ }()
+
+ // 1. 读旧名(同事务,避免并发改)
+ var oldName string
+ if err := tx.QueryRow(`SELECT name FROM voices WHERE id = ?`, v.ID).Scan(&oldName); err != nil {
+ if errors.Is(err, sql.ErrNoRows) {
+ return ErrNotFound
+ }
+ return fmt.Errorf("store: voice update read old name id=%d: %w", v.ID, err)
+ }
+
+ // 2. 若 name 变了 + 是默认音色 → 同步 default_speaker
+ if oldName != v.Name {
+ var defVal string
+ err := tx.QueryRow(`SELECT value FROM settings WHERE key = 'default_speaker'`).Scan(&defVal)
+ switch {
+ case errors.Is(err, sql.ErrNoRows):
+ // 没设 default_speaker,无事可做
+ case err != nil:
+ return fmt.Errorf("store: voice update read default_speaker: %w", err)
+ case defVal == oldName:
+ // 同步改名为新名
+ if _, err := tx.Exec(`
+ INSERT INTO settings (key, value, updated_at) VALUES ('default_speaker', ?, datetime('now'))
+ ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+ v.Name); err != nil {
+ return fmt.Errorf("store: voice update sync default_speaker: %w", err)
+ }
+ }
+ }
+
+ // 3. UPDATE voice
+ res, err := tx.Exec(`
UPDATE voices SET name=?, speaker=?, resource_id=?, model=?, language=?, description=?, enabled=?, updated_at=datetime('now')
WHERE id = ?`,
v.Name, v.Speaker, v.ResourceID, v.Model, v.Language, v.Description, boolToInt(v.Enabled), v.ID)
@@ -185,6 +239,11 @@ func (s *Store) VoiceUpdate(v Voice) error {
if n == 0 {
return ErrNotFound
}
+
+ // 4. 提交
+ if err := tx.Commit(); err != nil {
+ return fmt.Errorf("store: voice update commit: %w", err)
+ }
return nil
}
diff --git a/telemetry/labels.go b/telemetry/labels.go
index 7dfaa29..a45604a 100644
--- a/telemetry/labels.go
+++ b/telemetry/labels.go
@@ -41,14 +41,29 @@ func SpeakerLabel(s string) string {
// - 其它 → 前 4 + **** + 后 4 (保留前缀便于肉眼区分 "S_xx 开头" vs "BV001_...")
// 例子: "S_G8tEKnaJ1" → "S_G8****naJ1"
func MaskSpeaker(s string) string {
+ return maskWithAffix(s, "(未设置)")
+}
+
+// MaskResourceID 把火山 TTS 资源 ID 部分打码用于日志输出。
+// 资源 ID 同样属于用户付费/敏感资产(指向 V3 复刻项目),与 speaker 走同一规则。
+// - 空 → "(未设置)"
+// - 长度 ≤ 4 → 全打码
+// - 其它 → 前 4 + **** + 后 4
+// 例子: "volc.megatts.icl" → "volc****.icl"; "seed-icl-2.0" → "seed****2.0"
+func MaskResourceID(s string) string {
+ return maskWithAffix(s, "(未设置)")
+}
+
+// maskWithAffix 共用的"前 4 + **** + 后 4"打码逻辑,空串返回 emptyLabel。
+func maskWithAffix(s, emptyLabel string) string {
if s == "" {
- return "(未设置)"
+ return emptyLabel
}
if len(s) <= 4 {
return strings.Repeat("*", len(s))
}
// 找前 4 字符中第一个非 [A-Za-z0-9_] 字符做截断,避免截到奇怪位置
- // (虽然火山 ID 实际都是 S_xxx 字母数字组合,这里保险)
+ // (虽然火山 ID 实际都是字母数字组合,这里保险)
prefix := s[:4]
suffix := s[len(s)-4:]
return prefix + "****" + suffix