sun
1e2e37ae97
feat(auth)!: v0.2.4 阶段一 鉴权收紧 + 健康/指标端点收口
...
本提交由初版方案的「阶段 1」与「阶段 2」合并而成。合并原因:两者是同一件事的两半——
只收紧鉴权而不收口端点,结果是"有风险无收益"(未配凭证的旧部署可能起不来,
而 /health、/dashboard、/metrics 仍匿名可读)。
一、鉴权收紧(原阶段 1)
- RequireAdmin 在凭证列表为空时不再放行。此前 len(keys)==0 直接 next.ServeHTTP,
导致未配凭证的部署上管理接口完全裸奔,也让后续给端点加鉴权的加固形同虚设。
现在该情况返回 401 并记录明确日志。
- 新增可选独立管理凭证 admin_key,取值优先级:
admin_key(DB) > auth_key(DB) > OPENAI_TTS_API_KEY(env)。
middleware.ValidateAPIKey(业务侧 /v1/audio/speech)保持只看 auth_key,
于是配置 admin_key 后业务调用方持有的 key 无法访问管理接口,权限隔离成立;
不配置则回退 auth_key,老部署行为不变。
新增 PUT /api/admin/settings/admin-key 与旧前缀别名,
凭证只写不读(GET 仅返回打码值与 admin_key_set / admin_key_source)。
- normal 模式下管理凭证为空时启动期 fail-fast。RequireAdmin 改为拒绝后,
若此处不拦,服务会正常起来但 /dashboard 与全部 /api/admin/* 都是 401,
等于把自己锁在门外;宁可启动失败并打印明确原因。
二、端点收口(原阶段 2)
- /health 改为鉴权(原匿名泄漏版本、commit、运行时长、内存、goroutine、配置错误文本)
- /dashboard 改为鉴权,并对浏览器 HTML 请求做内容协商(Accept 含 text/html 时
返回页面外壳,由前端据 sessionStorage 显示登录视图;非 HTML 请求无凭证一律 401)。
不做无条件 401 的原因:SPA 登录态存在 sessionStorage、不随请求发送,
服务端无从判断是否已登录,强行 401 会把"打开看到登录页"变成"打开直接报错"。
页面外壳不含任何数据,数据全部来自鉴权后的 API。
- /api/setup/status 改为鉴权(原本 normal 模式下仍匿名返回 installed/mode)
- 根路径 /metrics 默认完全不注册(访问 404);配置 METRICS_ALLOW_CIDR 后按内网
白名单开放,非白名单返回 404 而非 403,不向扫描者确认端点存在。
- 新增 GET /healthz 匿名存活探针,只回 200 与字面量 ok、不含任何字段,解决
"给 /health 加鉴权后 K8s 探针与 Docker HEALTHCHECK 会一律 401 导致 Pod 反复重启";
新增 GET /api/admin/health 鉴权版详细健康数据。
IP 白名单中间件复用 GetClientIP(已处理 XFF 与 TRUSTED_PROXY_HOPS);
main.go 启动日志同步改为指向 /healthz 与 /api/admin/health。
BREAKING CHANGE:
1. /health、/dashboard、/api/setup/status 不再匿名可读;根路径 /metrics 需配
METRICS_ALLOW_CIDR,否则 404。
2. 未配置 auth_key / admin_key / OPENAI_TTS_API_KEY 任一时,normal 模式下服务拒绝启动。
3. K8s 探针与 Docker HEALTHCHECK 必须改指 /healthz;Prometheus 请改用鉴权版
/api/admin/metrics 或配置 METRICS_ALLOW_CIDR(Docker 中勿填 127.0.0.1/32,
那是容器自身回环,应填容器内网网段)。
验证:go build / go vet / go test ./... -count=1 全绿(7 个包);
另用真实服务器端到端验证端点矩阵、内容协商、凭证隔离与 CIDR 白名单两种形态。
2026-10-04 01:17:06 +08:00
sun
49f57e4d28
docs: 新增上游适配器开发指南
...
CI / build-and-test (push) Canceled after 0s
面向 多渠道多上游适配器 愿景的落地文档,分两部分:第一部分逐行核对现有火山适配器的真实契约(包的职责划分、主干对适配器的 7 项硬性依赖、MetricsRecorder 埋点约定、格式降级规则、以及 6 条实测踩过的上游协议坑);第二部分给出 Provider 抽象的目标设计与分阶段实施计划(阶段 0 抽接口零行为变更 -> 阶段 1 provider 入库 -> 阶段 2 配置命名空间化 -> 阶段 3 metrics 加 provider 维度 -> 阶段 4 管理界面 -> 阶段 5 第二个真实适配器)。
同时如实记录三处现状缺陷,避免按文档实施时踩坑:voice.resource_id 是火山专属概念却成了全表 NOT NULL 通用列;store/migrate.go 的迁移框架定义了 Migration/migrations 但切片为空、migrate() 从不读取它(实际只做 CREATE TABLE IF NOT EXISTS,对已存在的表不做任何变更),且 schema_version 的 INSERT 未传值、实际写入版本号是 0;setting/config.go 整体耦合 volcano.Options,主干因此无法插入第二个上游。
2026-10-03 23:41:22 +08:00
sun
ad342ec8f1
ci: 新增 build/vet/test 质量门
...
CI / build-and-test (push) Canceled after 0s
此前仓库唯一的 workflow 只在打 tag 时构建 Docker 镜像,不做任何编译或测试校验,加上测试源码不入库,导致 go test 全绿从来没有被自动化校验过。
新增 ci.yml:push / PR 到 develop、main 时跑 go build ./... / go vet ./... / go test ./... -count=1,再单跑一遍集成测试并输出明细。版本以 go-version-file 跟随 go.mod;-count=1 禁用测试缓存。
2026-10-03 16:18:54 +08:00
sun
24f8accf71
chore: 测试源码不入库,订正过期的 UI handoff 文档与 CHANGELOG
...
.gitignore 恢复整体屏蔽 *_test.go:测试只保留在本地磁盘供开发者执行,不作为交付物外流。因此仓库内不提供自动化测试。
docs/UI_HANDOFF.md 标注为历史文档:它是改造两个单文件 .html、admin <= 35KB 的外包任务书,而 admin 后台此后已重构成多页 SPA(admin-shell.js / admin.css + 登录/音色/设置三页),原约束与验收标准全部失效。补上当前真实文件结构与新的验收清单。
2026-10-03 16:13:47 +08:00
sun
6ac2473099
fix(volcano): PostStream 对未初始化 client 返回错误而不是 panic
...
Synthesis 里 client 是包级 volcanoClient,只在启动时赋值。不经过 main 的调用路径拿到 nil client 时,(*HTTPClient).PostStream 在 h.client.Do 处 nil 解引用崩溃。
装配错误应该让这一次请求以上游不可用失败:controller 会归一成 5xx 并记日志,而不是拖垮整个进程。
2026-10-03 16:13:47 +08:00
sun
1e2be0cd5b
fix(telemetry): 指标写入对空接收者安全,修 nil 解引用 panic
...
metrics 包的全局指标(UpstreamTotal 等)默认是 nil,只有 main 调过 metrics.Init() 之后才有值。任何不经过 main 的调用路径都会在 controller/tts.go -> adapter/volcano/synthesis.go -> metrics.AdapterRecorder 处 nil 解引用,整个进程崩掉。
生产路径本来没问题(二进制一定先 Init),但这类崩溃只在运行时暴露,且漏掉指标初始化属于很容易踩的装配错误,不该以 panic 收场。
改动: Counter.Add / Gauge.Set / Gauge.Add / Histogram.Observe 增加空接收者判断,nil 时静默忽略(与 noop 语义一致);在包注释里写成显式设计约定,避免以后被当成冗余代码删掉。
2026-10-03 16:13:47 +08:00
sun
21e1fd1fbb
ci(docker): 修 workflow 非法表达式, secrets 改经 job env 透传
...
Docker Publish / build-and-push (push) Canceled after 0s
GitHub Actions 拒绝加载本 workflow, 报:
Invalid workflow file: .github/workflows/docker.yml#L1
(Line: 49, Col: 13): Unrecognized named-value: 'secrets'.
Located at position 40 within expression:
github.event_name != 'pull_request' && secrets.DOCKERHUB_USERNAME != ''
原因: secrets 上下文不允许在 step 的 if: 表达式里引用(GitHub 沙箱限制)。
secrets 只在 with: / env: / run: 等位置可用, if: 里必须走 env 中转。
修复:
- 新增 job 级 env: DOCKERHUB_USERNAME / DOCKERHUB_TOKEN (值来自 secrets)
- DockerHub login step: if 改 env.DOCKERHUB_USERNAME != ''
- DockerHub login step: username/password 改读 env.*
- metadata-action images: DockerHub 那行改 env.DOCKERHUB_USERNAME,
enable 判断同样改 env 上下文
副作用: 无。secret 未配置时行为不变(跳过 login + 不渲染 DockerHub image)。
已用 js-yaml 校验 YAML 结构合法, 并扫描确认全部 step 的 if: 不含 secrets 引用。
2026-09-28 23:30:57 +08:00
sun
ecc1d94fbc
Merge branch 'develop'
Docker Publish / build-and-push (push) Canceled after 0s
2026-09-28 22:29:43 +08:00
sun
9c10a0e49f
ci(docker): 合并为单一 GHCR+DockerHub 双推送 workflow,加 GHA 缓存
...
原 .github/workflows/docker.yml:
- 触发: v* tag + 手动
- 仅推 GHCR
- 无 build 缓存
- buildx action v5
新版本:
- 触发: v*.*.* tag (限定 semver, 避免 vtest 误触发) + 手动按钮
- 双 registry 推送: GHCR (默认) + DockerHub (blueink05/ttshub,需 secrets)
- GHA buildx cache (cache-from + cache-to, mode=max): 首次 ~3-5 min, 后续 30-60s
- buildx action v6
- multi-arch (amd64+arm64, 不变)
- tag 策略: semver + major.minor + tag->latest + short sha
- 安全网: secrets.DOCKERHUB_USERNAME 空时自动跳过 DockerHub login + image name 渲染,
避免生成 'docker.io//ttshub' 这种非法 image 名
- 不验 PR 编译(合到 main 不重跑, 只在打 tag 时构建)
- workflow_dispatch 推镜像: push 表达式保留 '!= pull_request' 兼容未来扩展
需要 GitHub repo 配置的 secrets:
- DOCKERHUB_USERNAME = blueink05
- DOCKERHUB_TOKEN = (hub.docker.com/settings/security 拿 access token)
没加之前,DockerHub login 步骤被 actions 自动跳过,只推 GHCR 一份。
Dockerfile / docker-compose.yml / .dockerignore 不动(Dockerfile 1.26-alpine
base image 已确认存在,tags list 拉到 tip-20260920)。
2026-09-28 21:36:30 +08:00
sun
9245c1339a
refactor(admin): 把单文件 admin.html (1075 行) 拆成多页 SPA,URL 路由切换
...
原 admin.html 是 1075 行的单文件 SPA:登录/仪表盘/音色/设置 4 个面板
挤在一个 Vue 实例里 tab 切换(login -> app shell -> 3 个 section)。
文件太大,样式 + script + template 混在一起,改一个面板要 scroll 整页找位置。
拆分后:
router/admin.html 5.4 KB Dashboard (重定向目标,默认页)
router/admin-login.html 2.1 KB 登录页 (无 sidebar)
router/admin-voices.html 13.3 KB 音色管理 + Add modal
router/admin-settings.html 14.1 KB 系统设置
router/admin.css 19.8 KB 共享样式 (4 个页面 + admin-shell.js 共用)
router/admin-shell.js 6.9 KB 共享:http client (401 自动清 key)、toast 系统、
login helper、sidebar 渲染、format helpers
最大的页面 14 KB,平均 10 KB,各页只负责自己逻辑。
技术细节:
- 栈保持: Vue 3 + Axios 走 CDN,纯静态 HTML,零构建
- URL 路由: /admin /admin/login /admin/voices /admin/settings,
router.go 加 4 条 ServeFile 路由 + 2 条静态资源路由
(/admin/admin.css /admin/admin-shell.js)
- 抽 serveAdmin(body []byte) http.HandlerFunc helper 避免 4 段重复
- 鉴权: 各页 onMounted 检 sessionStorage.ttsAdminKey,无则 location.href
跳 /admin/login;http client 401 响应拦截器清 key,下个请求被跳到 login
- Sidebar 一致: shell.js mountShell({activeNav, overview, voiceCount, ...})
渲染 <aside> + 高亮 active 项,各页只传 activeNav 不重复维护 DOM
- 静态资源 Content-Type 显式设置:text/css / application/javascript
未变更:
- 不动 /api/* 后端接口
- 不动 /setup /dashboard /health /v1/audio/speech 路由
- 鉴权语义: HTML 公开 / API 鉴权 (与原版一致)
- 不引入构建工具 / 不引入新依赖
验证 (PowerShell 起真 server + setup API + curl):
/admin 200 5433 bytes text/html
/admin/login 200 2082 bytes text/html
/admin/voices 200 13282 bytes text/html
/admin/settings 200 14110 bytes text/html
/admin/admin.css 200 19815 bytes text/css
/admin/admin-shell.js 200 6887 bytes application/javascript
/api/admin/overview (无 auth) 401
/api/admin/overview (有 auth) 200
各页内容 marker 命中 (filteredVoices / corsForm / voice_count / login-card)
2026-09-21 23:20:59 +08:00
sun
e738fc8e23
fix(setup): settings + voices 改为事务原子提交,失败整体回滚不再半残
...
原版 controller/setup.go 提交流程:
SettingsSetBatch → 循环 VoiceInsert
任一 voice 失败时,settings 已写、voice 1/N 已落,db 处于半残状态
(settings 指向不存在的 default_speaker,部分 voice 残留,其它丢失)。
注释里甚至自白 '不回滚 settings(用户重启后会重新 setup)' — 有意的妥协,
但用户重启后还要踩 '已装但配置不完整' 的坑,且下次 setup 还会撞 ErrDuplicate
(已插入的 voices 留着没回滚)。
修复:
- 新增 store.SetupApply(settingsKV, voices) (inserted int, err error):
单事务包 settings 写入 + 所有 voice 插入,任一失败整体回滚,db 保持
setup 前的状态(无脏数据)。
- 内部抽 settingsSetBatchTx / voiceInsertTx 两个 helper,逻辑跟现有
SettingsSetBatch / VoiceInsert 一致,只是用 *sql.Tx 代替 s.db。
- ErrDuplicate 静默跳过(兼容 '重复 setup 同一组 voice' 场景),其它
voice 错误整体回滚。ErrInvalid 校验错误沿用上一条 fix 的 400/500 模式
(errors.Is(err, ErrInvalid) → 400,其它 → 500)。
- 锁文件 installer.CreateLock 仍在事务外(controller 层),它本就不属于
db 事务能管的事,这次不动它的失败语义。
controller/setup.go 改用 s.SetupApply 一次调用,删除原 SettingsSetBatch
+ VoiceInsert 内联循环 + '清空旧 voices' 注释(原代码注释承认这逻辑是
'妥协')。响应体字段不变(voices 用 SetupApply 返回的 count)。
store 单 connection (SetMaxOpenConns(1)) 已在 db.go 设置,事务安全。
2026-09-21 21:31:46 +08:00
sun
01bc5ea5bf
fix(admin): VoiceInsert 错误按客户端/服务端分流,400/500 不再混淆
...
原版 controller/admin.go VoiceInsert 错误处理的 default 分支把所有非
ErrDuplicate 错误(含 DB 连接失败等真服务端错误)都当 400 + voice_invalid
返回。问题:
- 客户端拿到 400 不会重试,但实际是服务端问题
- 4xx 通常被监控忽略,DB 故障等不到告警
- err.Error() 透传前端,可能泄漏 DB schema / SQL 细节
修复:加 store.ErrInvalid 哨兵,把客户端校验错误(name 格式 / speaker /
resource_id 缺失)统一 wrap 进 ErrInvalid,controller 改用 errors.Is 三向分流:
- ErrDuplicate → 409 voice_duplicate
- ErrInvalid → 400 voice_invalid(剥掉 store 前缀,返用户友好 detail)
- 其它(DB 失败 / LastInsertId 失败)→ 500 voice_insert_failed
(详细 err 走 log.Printf,不外抛,避免信息泄漏)
新增 stripInvalidPrefix helper 处理 'store: voice invalid: ' 前缀剥离,
保留底层 detail(例如 'speaker is required')给前端展示。
VoiceUpdate 保持不动(本任务范围只到 VoiceInsert);后续若发现类似问题
可复用同一 ErrInvalid 哨兵模式。
2026-09-21 17:22:45 +08:00
sun
6ed25e8e4b
fix(ratelimit): 强制清理按最旧活跃时间排序,避免随机删活跃用户
...
原版用 'for k := range rl.requests' 直接删除超限条目,Go map 遍历顺序
随机,可能命中 timestamp 仍在窗口内的活跃用户,导致其下次请求拿到新配额
(限流语义被破坏)。
同时存在 abuse vector: 攻击者用大量伪造 IP 撑爆 map 触发清理,反而
'清洗'掉自己留的活跃条目,绕过限流。
修复:
- 收集 (key, lastTs) 到 slice,按 lastTs 升序排(最旧在前)
- lastTs 取 timestamps 末尾(Allow 总 append 到末尾,即最近请求时间)
- 从前往后逐个 delete,直到 len(rl.requests) <= MaxRateLimiterEntries/2
- 阈值/触发条件/warning 日志保持不变
复杂度 O(n log n),仅在超 MaxRateLimiterEntries(10w)时触发,代价可接受。
cleanup 仍在 Allow 入口的 rl.mutex.Lock() 区域内,无需额外锁。
2026-09-21 11:14:48 +08:00
sun
19d83f7a3b
fix(setting): runtime config 全局变量加 sync.RWMutex 保护,避免半写状态
...
TTSOptions / TTSTimeout / TTSConfigErr / Auth.APIKeys / CORS 在运行期会被
LoadRuntimeConfig(PUT /api/settings 触发)整体替换,struct 整体赋值不是原子的,
若 TTS 请求正并发读,可能拿到半写状态。单用户场景概率低,属正确性隐患。
改动:
- setting/config.go: 把可变运行时配置迁到包内私有变量,新增 ttsMu
(sync.RWMutex) 统一保护,提供 Get*/Set* 访问器
- GetTTSOptions/SetTTSOptions: 值类型快照,读端无锁开销
- GetTTSTimeout/SetTTSTimeout
- GetTTSConfigErr/SetTTSConfigErr
- GetAuthAPIKeys/SetAuthAPIKeys: 拷贝进出,防止外部持有底层 slice
- GetCORSAllowAll/GetCORSOrigins/SetCORS: AllowAll 和 Origins 拆开,
避免热路径 CORSConfig 整体读时锁粒度过粗
- 删除导出可变全局 var TTSOptions/TTSTimeout/TTSConfigErr/Auth/CORS,
编译期强制所有读写走 Get*/Set*
- Server.Port/TrustedProxyHops/SetupToken 仅启动期写,运行期无并发修改,
保持原状不加锁
- LoadRuntimeConfig/InitAuthConfig/InitCORSConfig 全切到 Set*
- CheckEnvironmentVariables/LogStartupSummary 一次性拿快照,
缩短锁占用窗口,避免多次 log.Printf 之间数据被替换
调用点:
- controller/tts.go: 热路径 opts := setting.GetTTSOptions(),
context 超时走 GetTTSTimeout(),/health 块用 GetTTSConfigErr
- controller/settings.go: 写改 SetAuthAPIKeys/SetCORS
- controller/setup.go: 写改 SetAuthAPIKeys
- middleware/auth.go: 鉴权改 GetAuthAPIKeys()(在 RLock 下拿拷贝)
- middleware/admin_auth.go: 同上
- middleware/cors.go: matchOrigin 改 GetCORSAllowAll/GetCORSOrigins
读多写少,RWMutex 读路径不互斥,不会拖慢热路径。
2026-09-21 10:50:03 +08:00
sun
d6aafa41ff
fix(tts): OpenaiTTSHandler 响应 Write 错误不再吞,记日志排查客户端断开
2026-09-12 15:53:07 +08:00
sun
ef2fea4c25
fix(security): 启动 / 路由 / 上游 log 对 resource_id 一并打码,补 telemetry.MaskResourceID
2026-09-12 14:34:06 +08:00
sun
a2d72efb34
fix(cors): 预检 Allow-Methods 补 PUT/PATCH/DELETE,修 admin 改设置/删音色跨域失败
2026-09-12 14:03:56 +08:00
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
c265cb8836
fix(store): VoiceUpdate 同步 settings.default_speaker (防潜在 stale ref)
...
Bug 报告: admin (或任何 caller) 改 voice.name 时, store 层的
VoiceUpdate 只 UPDATE voices 表, 没碰 settings.default_speaker。
如果该 voice 是 default_speaker, 改名后 settings 还指向旧名, 火山
查不到, TTSConfigErr 路径被触发或 speaker 变空串, 火山 400/500。
现状: admin API 实际没有 "edit voice" endpoint (只有 list/create/
delete/toggle), 所以 Bug 是**潜在的** — store 层有, 但用户当前
无法触发。修复属于防御性 + 未来加 update endpoint 不会重蹈覆辙。
修法: VoiceUpdate 改为单事务:
1. 读旧 name (同事务, 避免并发改)
2. 若 name 变了 + settings.default_speaker == 旧 name → 同步改新 name
3. UPDATE voice
4. Commit
整段在 Begin/Commit 里, 失败回滚, 避免"声音改了但 default_speaker
还指向旧名" 的半残状态。
测试: test/integration/voices_test.go 加 4 个 case:
- rename + 是 default → default_speaker 同步
- rename + default 是别的 voice → 不动 settings
- 改 description (name 不变) → 不动 settings
- 没 default_speaker + rename → 不崩不乱改
e2e: 跑 cmd/verifybug1 验证事务逻辑 (Windows TempDir cleanup 锁问题
是测试工具问题, 跟 fix 无关; 测试 body 本身断言全过)。
未 push (待用户)
2026-09-05 11:38:40 +08:00
sun
8f56b742cb
Merge branch 'main' into develop
2026-09-05 00:15:49 +08:00
sun
2ea33d7572
Merge branch 'develop'
Docker Publish / build-and-push (push) Canceled after 0s
2026-09-05 00:07:19 +08:00
sun
90faf083fd
docs(m4): 重写 README,聚焦 WebUI 安装 + 老用户迁移 + 资源 ID 章节
...
README 旧版 (~535 行) 仍以 BYTEDANCE_TTS_* env 为主线, 与 v0.2.0 实际架构脱节。
M3 起业务配置已全部入 DB, env 只剩 4 个引导变量。
新版 README (重写, ~300 行) 调整:
结构重排:
- 快速开始: 编译 → 启动 → 浏览器 /setup 引导(默认 4 步)→ 调用
- 环境变量: 4 个引导 env + DB 业务配置对照表
- WebUI 使用: /setup 4 步说明 + /admin 5 个 tab + 客户端可见错误码表
- API 端点: /v1/audio/speech + /health + /metrics + /admin + /setup + /dashboard
- 老用户迁移: 11 个 BYTEDANCE_TTS_* 旧 env 逐项映射到 /admin 设置
- 资源 ID 章节: 重要! 强调 v3 API 只允许 2 个 ID, volc.megatts.* 是 1.0 不是 2.0
- 观测 / Metrics: 14 个指标, 告警示例 (tts_config_load_failures_total)
- 公网部署: 鉴权清单 + /metrics /dashboard 反代保护
- 部署: Docker / Systemd
- 架构: 13 个包
- FAQ: 9 条
- 技术支持 checklist
内容更新:
- 删 BYTEDANCE_TTS_* 详细配置章节(老的 11 个变量, 全搬 DB 了)
- 加 "v0.2.0 老用户迁移" 完整映射表
- 资源 ID 章节纠正 1.0 vs 2.0 区别
- /health body 改用 v0.2.0 真实 schema (含 error 字段)
- 错误码表加 400/403/503 客户端可见错误
- 模型名更正: 复刻 2.0 子模型 = seed-tts-2.0-standard (和资源 ID 不同)
- 强调 4 个 bootstrap env + DB 业务配置分工
未提交 (待 M4 全部完成)
2026-08-30 23:32:10 +08:00
sun
621f9f847e
docs(m4): 收敛文档/dock/changelog,env 减到 4 个引导变量
...
M3 后所有业务配置(api_key/resource_id/speaker/format/sample_rate/...)已搬入
数据库,env 只剩 4 个启动引导参数(setup 前 / DB 还不存在时必需):
1. TTS_ADMIN_KEY 安装 token(/api/setup 鉴权)
2. TTS_DB_PATH DB 路径(可选)
3. PORT 监听端口(可选)
4. OPENAI_TTS_API_KEY OpenAI 端鉴权(可选)
之前 .env.example 仍列出 11 个 BYTEDANCE_TTS_* env,误导用户把配置填 env 里
(实际被 DB 覆盖,改了不生效)。
改:
- .env.example: 只列 4 个 bootstrap env,其他写"通过 WebUI 设置"
- docker-compose.yml: env 块只透传 4 个,加 named volume 持久化 tts.db
(无 volume = 容器重启丢所有配置)
- Dockerfile: 准备 /data 目录,appuser 可写
- CHANGELOG.md: 新文件,记 v0.2.0 全部 M0-M3 + 这次修复
不动:
- README.md(M4 第 5 步独立 commit,文件大)
- 集成测试(M4 第 6 步)
e2e 验证:
- go build ./... 通过
- 旧 .env 文件如果存在仍然兼容(env var 作为 DB 缺失时的 fallback)
未 push (待 M4 全部完成)
2026-08-30 23:23:53 +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
3f18f85925
fix(ui): setup 默认 resource_id 改 seed-icl-2.0
...
与 admin 同一类问题 (见 admin 修复 commit):
项目是豆包声音复刻大模型 2.0, 资源 ID 必为 seed-icl-2.0。
setup.html 错的默认值有 5 处:
1. form.default_resource_id placeholder: volc.megatts.default
2. v.resource_id placeholder: volc.megatts.icl
3. v.model placeholder: seed-tts-2.0-standard
4. form 默认 (default_resource_id): volc.megatts.default
5. form 默认 voices[0] + addVoice push: volc.megatts.icl / seed-tts-2.0-standard
修法同 admin: resource_id 改 seed-icl-2.0, model 保持 seed-tts-2.0-standard
(用户后澄清模型名独立)。
附带修:
- step 2 hint 文案从 "volc.megatts.icl 用于复刻音色" 改为
"本项目为豆包声音复刻大模型 2.0, 固定使用 seed-icl-2.0"
(避免误导用户填错资源 ID)
未 push (待用户 push)
2026-08-30 15:57:00 +08:00
sun
155017a27b
fix(ui): admin 默认 resource_id 改 seed-icl-2.0
...
背景: 项目是豆包声音复刻大模型 2.0, v3 API 只允许 2 个
资源 ID: seed-tts-2.0 (普通 TTS) + seed-icl-2.0 (复刻 2.0)。
本项目用复刻 2.0, 资源 ID 必为 seed-icl-2.0。
Bug 报告: admin (admin.html) 表单有 5 处默认值都是错的:
1. settingsForm.default_resource_id placeholder: volc.megatts.default
2. form.resource_id placeholder: volc.megatts.icl
3. form.model placeholder: seed-tts-2.0-standard (1.0 模型, 项目用不了)
4. form resource_id 默认: volc.megatts.icl
5. form model 默认: seed-tts-2.0-standard
+ openAdd 重置
+ settingsForm.model placeholder: seed-tts-2.0-standard
volc.megatts.* 是 1.0 API 的资源/服务品类编码, 不是 v3 API 2.0 的合法
资源 ID, 装完 admin 一看就是错的, 用户不知道要改成什么。
修法:
- 所有 resource_id 默认值 + placeholder 改成 seed-icl-2.0
- model 默认值保持 seed-tts-2.0-standard (用户确认模型名)
(用户后澄清: 模型在 v3 API 2.0 里只此一个名字, 不跟 resource 同步)
- 不硬编码 — 用户仍可改
受影响的 7 处:
- admin.html: settingsForm.default_resource_id placeholder
- admin.html: settingsForm.model placeholder
- admin.html: form.resource_id placeholder
- admin.html: form.model placeholder
- admin.html: form 默认 (resource_id)
- admin.html: form 默认 (model) + openAdd reset
- 全部 7 处 detail 见 diff
未 push (待用户 push)
2026-08-30 15:57:00 +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
2026-08-30 13:09:40 +08:00
sun
92cf8fab8a
fix(ui): dashboard 加 loadSettings, CORS banner 终于不假阳性了
...
Bug FE-002:
- /admin dashboard 顶部黄条"跨域 CORS 未配置"永远显示
- 原因: reloadAll() 没调 loadSettings, dashboard 上 settings.value 一直是 {}
- banner 判断 `!settings.cors_configured` → undefined → falsy → 触发
- 只有手动进 settings tab 触发 loadSettings() 后才消失
- 刷新页面又出现(被用户当成"CORS 没生效")
修法: 一行。reloadAll() 加上 loadSettings(), mount 时一并加载,
dashboard 上 settings 就有真值了, banner 判断正确。
diff:
- const reloadAll = () => { loadOverview(); loadVoices(); };
+ const reloadAll = () => { loadOverview(); loadVoices(); loadSettings(); };
副作用: 无。 loadSettings 自带 try/catch, 即使 /api/settings 失败
也不影响 overview/voices 加载。 watch(tab) 仍会再调一次
loadSettings (idempotent, 覆盖 fresh 值)。
验证 (本机 + 你的报告复现):
- 强刷 admin → mount 时 3 个 API 并行加载
- settings.value 填好, cors_configured = true
- banner `v-if="settings && !settings.cors_configured && ..."` 评估为 false → 不显示
未 push(等你确认)
二进制: ~18MB → ~18MB (HTML 嵌入尺寸不变)
2026-08-30 13:04:26 +08:00
sun
aa3f09752e
tools: 加 cmd/dumpdb ops 工具
...
dumpdb 是 read-only 的 SQLite 探查工具:
go run ./cmd/dumpdb /path/to/tts.db
输出:
- 所有表
- schema_version
- settings(敏感字段打码: api_key/auth_key/speaker_id 等)
- voices(完整行,无打码 — 这是 ops 用)
- journal_mode/page_size 等 pragmas
用法: 服务器 db 排查时,直接下 tts.db 下来用这个查,
不用 sqlite3 CLI,也不用写 SQL。
无依赖(用已有的 modernc.org/sqlite)。
未 push(收尾 commit,跟之前一起发)
2026-08-30 11:45:08 +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
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 处在 51bd7ae51bd7ae
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
0d3517eb5c
fix: 安全加固（VUL-001~009）+ 构建版本注入 + 死代码清理' ( #2 ) from develop into main
...
Docker Publish / build-and-push (push) Canceled after 0s
Reviewed-on: #2
2026-08-27 11:01:47 +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
2026-08-27 00:57:49 +08:00
sun