Compare commits
8
Commits
v0.2.3
..
753de8ca9f
| Author | SHA1 | Date | |
|---|---|---|---|
 sun
|
753de8ca9f | ||
|
sun
|
d22e5f0801 | ||
|
sun
|
c4269086fa | ||
|
sun
|
49f57e4d28 | ||
|
sun
|
ad342ec8f1 | ||
|
sun
|
24f8accf71 | ||
|
sun
|
6ac2473099 | ||
|
sun
|
1e2be0cd5b |
@@ -0,0 +1,61 @@
|
|||||||
|
name: CI
|
||||||
|
|
||||||
|
# 触发条件:
|
||||||
|
# - push 到 develop / main
|
||||||
|
# - 针对 develop / main 的 PR
|
||||||
|
#
|
||||||
|
# 为什么单独有这个 workflow:
|
||||||
|
# 之前仓库里唯一的 workflow 是 docker.yml,它只在打 tag 时构建镜像,
|
||||||
|
# 既不做 go build 也不跑 go vet,提交能不能编译没人自动盯着。
|
||||||
|
#
|
||||||
|
# ⚠️ 本 workflow 的实际覆盖范围(务必知悉):
|
||||||
|
# 测试源码按项目策略**不入库**(见 .gitignore 的 `*_test.go`),因此干净克隆里
|
||||||
|
# 没有任何 *_test.go,下面的 go test 步骤会打印 "no test files" 后通过。
|
||||||
|
# 也就是说:**CI 只能守住"编译通过 + 静态检查通过",守不住行为回归。**
|
||||||
|
# 行为回归要靠开发者在本地(测试文件所在处)自行执行:
|
||||||
|
# go test ./... -count=1
|
||||||
|
# 如果哪天测试重新入库,把下面的 go test 步骤改成会真正跑起来的形态即可。
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [develop, main]
|
||||||
|
pull_request:
|
||||||
|
branches: [develop, main]
|
||||||
|
|
||||||
|
# 同一分支的重复推送取消上一次未完成的运行,省 CI 时间。
|
||||||
|
concurrency:
|
||||||
|
group: ci-${{ github.workflow }}-${{ github.ref }}
|
||||||
|
cancel-in-progress: true
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
build-and-test:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- name: Checkout
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Set up Go
|
||||||
|
uses: actions/setup-go@v5
|
||||||
|
with:
|
||||||
|
# 以 go.mod 里的 go 指令为准,避免两处版本漂移
|
||||||
|
go-version-file: go.mod
|
||||||
|
cache: true
|
||||||
|
|
||||||
|
- name: 下载依赖
|
||||||
|
run: go mod download
|
||||||
|
|
||||||
|
- name: 编译检查
|
||||||
|
run: go build ./...
|
||||||
|
|
||||||
|
- name: 静态检查
|
||||||
|
run: go vet ./...
|
||||||
|
|
||||||
|
# 以下两步在"测试不入库"策略下是空转(no test files),保留是为了:
|
||||||
|
# 1. 覆盖 lock 判定 / 损坏回退 / voice 路由等关键路径的测试一旦重新入库,
|
||||||
|
# 无需改 workflow 即可直接生效;
|
||||||
|
# 2. -count=1 禁用测试缓存,避免"改坏了却因缓存仍显示通过"。
|
||||||
|
- name: 测试(测试源码不入库时为空转)
|
||||||
|
run: go test ./... -count=1
|
||||||
|
|
||||||
|
- name: 关键路径汇总(integration)
|
||||||
|
run: go test ./test/integration/ -count=1 -v
|
||||||
|
|
||||||
+12
-7
@@ -4,7 +4,10 @@
|
|||||||
*.test
|
*.test
|
||||||
*.out
|
*.out
|
||||||
|
|
||||||
# Go test sources (prevent accidental commit; tests live outside the repo by policy)
|
# Go 测试源码:不入库(测试保留在本地磁盘,由开发者自行 go test ./... -count=1)
|
||||||
|
# 理由:测试用例会暴露内部实现细节与断言,不作为交付物外流。
|
||||||
|
# 注意:本规则会把测试文件挡在 git 之外,因此仓库内不提供自动化测试;
|
||||||
|
# .github/workflows/ci.yml 里的测试步骤在纯净克隆上无测试可跑。
|
||||||
*_test.go
|
*_test.go
|
||||||
|
|
||||||
# Editor / OS
|
# Editor / OS
|
||||||
@@ -33,14 +36,16 @@ bin/
|
|||||||
# Local dev scripts (per-user; not part of repo)
|
# Local dev scripts (per-user; not part of repo)
|
||||||
start-local.ps1
|
start-local.ps1
|
||||||
|
|
||||||
|
# Windows / PowerShell 脚本:一律不入库、不外流
|
||||||
|
# ui-handoff/serve.ps1 与 start-local.ps1 是本地起服便利脚本(含本机路径与端口),
|
||||||
|
# 不属于交付物。这两个文件在文件系统层面删除被拒,因此只能在 git 层屏蔽。
|
||||||
|
*.ps1
|
||||||
|
|
||||||
|
# UI handoff bundle(改造前的单文件副本 + 离线 mock 预览;仅本地对照,不部署)
|
||||||
|
ui-handoff/
|
||||||
|
|
||||||
# Runtime database artifacts (created by M1 installer flow)
|
# Runtime database artifacts (created by M1 installer flow)
|
||||||
tts.db
|
tts.db
|
||||||
tts.db-*
|
tts.db-*
|
||||||
tts.db.*
|
tts.db.*
|
||||||
installed.lock
|
installed.lock
|
||||||
|
|
||||||
# UI handoff bundle (for external AI redesign work; not deployed)
|
|
||||||
ui-handoff/
|
|
||||||
|
|
||||||
# Docs (本地草稿,不入库)
|
|
||||||
docs/
|
|
||||||
|
|||||||
@@ -2,6 +2,75 @@
|
|||||||
|
|
||||||
本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。
|
本项目的所有重要变更都记录在本文档。版本号遵循 [SemVer](https://semver.org/)。
|
||||||
|
|
||||||
|
## [未发布]
|
||||||
|
|
||||||
|
### v0.3.0 · 进行中
|
||||||
|
|
||||||
|
按 [docs/IMPLEMENT_v0.3.0.md](docs/IMPLEMENT_v0.3.0.md) 分阶段实施,当前完成 **阶段 1、阶段 2**。
|
||||||
|
|
||||||
|
#### 新增
|
||||||
|
|
||||||
|
- **`GET /healthz` 匿名存活探针**:只返回 `200` 与字面量 `ok`,**不含任何字段**。
|
||||||
|
供 K8s liveness/readiness、Docker HEALTHCHECK、负载均衡健康检查使用 ——
|
||||||
|
这些探针默认不带 `Authorization`,若继续指向 `/health` 会因鉴权而全部失败。
|
||||||
|
- **`GET /api/admin/health` 鉴权版详细健康数据**:与 `/api/admin/metrics` 风格一致,
|
||||||
|
供管理面板与运维使用。
|
||||||
|
- **`METRICS_ALLOW_CIDR` 内网白名单**(逗号分隔 CIDR,支持裸 IP 自动补掩码):
|
||||||
|
配置后在根路径注册 `/metrics`,仅放行白名单来源;**非白名单返回 404 而非 403**,
|
||||||
|
不向扫描者确认端点存在。未配置时根路径 `/metrics` **完全不注册**。
|
||||||
|
- **独立管理凭证 `admin_key`(可选)**:管理接口凭证与业务调用凭证分离。
|
||||||
|
取值优先级 `admin_key`(DB) → `auth_key`(DB) → `OPENAI_TTS_API_KEY`(env)。
|
||||||
|
**不配置时行为与旧版完全一致**(回退用 `auth_key`),配置后业务 key 无法访问管理接口。
|
||||||
|
新增 `PUT /api/admin/settings/admin-key`(及旧前缀别名 `/api/settings/admin-key`)用于配置,
|
||||||
|
凭证**只写不读**(`GET /api/settings` 仅返回打码值与 `admin_key_set` / `admin_key_source`)。
|
||||||
|
|
||||||
|
#### 变更(Breaking Change)
|
||||||
|
|
||||||
|
- **`/health`、`/metrics`、`/dashboard` 不再匿名可读**:
|
||||||
|
- `/health` → 鉴权(原匿名,泄漏版本 / commit / 内存 / goroutine / 配置错误文本)
|
||||||
|
- `/dashboard` → 鉴权(原匿名,且它同时聚合 `/health` + `/metrics`,是单点泄漏最严重的端点)。
|
||||||
|
对浏览器 HTML 请求做内容协商:返回页面外壳由前端显示登录视图;非 HTML 请求(脚本、抓取)无凭证一律 401。
|
||||||
|
- 根路径 `/metrics` → 需要 `METRICS_ALLOW_CIDR`,否则 404
|
||||||
|
- `/api/setup/status` → 鉴权(原本 normal 模式下仍匿名返回 `{installed, mode}`)
|
||||||
|
- **`RequireAdmin` 在凭证未配置时不再放行**。此前 `len(keys)==0` 直接放行,导致未配置凭证的
|
||||||
|
部署上管理接口完全裸奔(也使得给 `/metrics`、`/health` 加鉴权的加固形同虚设)。现在该情况返回 **401**。
|
||||||
|
- **normal 模式下未配置任何管理凭证时服务拒绝启动**(fail-fast),启动摘要打印管理凭证来源。
|
||||||
|
|
||||||
|
> ⚠️ **升级提示**
|
||||||
|
> 1. 若部署未配置 `auth_key` / `admin_key` / `OPENAI_TTS_API_KEY` 中任何一个,升级后服务将拒绝启动。
|
||||||
|
> 2. K8s 探针 / Docker HEALTHCHECK 请改指 **`/healthz`**;Prometheus 请改用鉴权版
|
||||||
|
> `/api/admin/metrics`,或配置 `METRICS_ALLOW_CIDR`。
|
||||||
|
> 3. `METRICS_ALLOW_CIDR` 在 Docker 中**不要填 `127.0.0.1/32`**(那是容器自身回环),
|
||||||
|
> 请填容器内网网段(如 `172.16.0.0/12`)。
|
||||||
|
|
||||||
|
### 修复
|
||||||
|
|
||||||
|
- **指标空指针崩溃**: `metrics` 包的全局指标(`UpstreamTotal` 等)默认是 nil,只有 `main` 调过
|
||||||
|
`metrics.Init()` 后才有值。任何**不经过 main** 的调用路径(直接调 handler、复用为库)都会在
|
||||||
|
`controller/tts.go` → `adapter/volcano/synthesis.go` → `metrics.AdapterRecorder` 处 nil 解引用 panic。
|
||||||
|
现在 `telemetry` 的 `Counter.Add` / `Gauge.Set` / `Gauge.Add` / `Histogram.Observe` 一律
|
||||||
|
**空接收者安全**(nil 静默忽略),并在包注释里写成显式设计约定。
|
||||||
|
- **上游 client 空指针**: `volcano.(*HTTPClient).PostStream` 在 client 未初始化时 panic。
|
||||||
|
现在返回错误,由 controller 归一成 5xx 并记日志——装配错误不该拖垮进程。
|
||||||
|
|
||||||
|
> 上面两个崩溃是**本地测试暴露出来的**:直接调用 handler 而不经过 `main` 的路径,
|
||||||
|
> 会跳过 `metrics.Init()` 与 `volcanoClient` 的赋值。生产二进制不受影响。
|
||||||
|
|
||||||
|
### 变更
|
||||||
|
|
||||||
|
- **测试源码不再入库**: `.gitignore` 恢复整体屏蔽 `*_test.go`。测试用例会暴露内部实现
|
||||||
|
细节与断言,不作为交付物外流;测试文件保留在本地磁盘,由开发者自行执行
|
||||||
|
`go test ./... -count=1`。
|
||||||
|
⚠️ 代价必须明确:仓库内**不提供自动化测试**,`.github/workflows/ci.yml` 里的
|
||||||
|
`go test` 步骤在纯净克隆上无测试可跑(会打印 `no test files` 并通过),
|
||||||
|
**CI 只能守住"编译通过 + 静态检查通过",守不住行为回归**。
|
||||||
|
- **新增 CI 校验** (`.github/workflows/ci.yml`): push / PR 到 `develop`、`main` 时跑
|
||||||
|
`go build` + `go vet` + `go test -count=1`。此前仓库唯一的 workflow 只在打 tag 时构建
|
||||||
|
Docker 镜像,不做任何编译或测试校验。
|
||||||
|
- **文档订正**: `docs/UI_HANDOFF.md` 原为"单文件换皮"外包任务书,其中的
|
||||||
|
"admin.html ≤ 35KB / setup.html ≤ 15KB / 只改两个 .html" 等约束在 admin 拆分多页后已作废,
|
||||||
|
现标注为历史文档并补上当前真实文件结构与验收清单。
|
||||||
|
|
||||||
## [0.2.0] - 2026-08-30
|
## [0.2.0] - 2026-08-30
|
||||||
|
|
||||||
### 新增
|
### 新增
|
||||||
|
|||||||
@@ -29,7 +29,14 @@ func NewHTTPClient() *HTTPClient {
|
|||||||
|
|
||||||
// PostStream 发送一次流式请求,返回带上下文的 *http.Response。
|
// PostStream 发送一次流式请求,返回带上下文的 *http.Response。
|
||||||
// 调用方负责关闭 resp.Body。
|
// 调用方负责关闭 resp.Body。
|
||||||
|
//
|
||||||
|
// 空接收者(nil *HTTPClient)安全:返回错误而不是 panic。未初始化的 client 属于
|
||||||
|
// 装配错误,应当让该次请求以"上游不可用"失败(controller 归一成 5xx 并记日志),
|
||||||
|
// 而不是让整个进程崩掉。
|
||||||
func (h *HTTPClient) PostStream(ctx context.Context, url string, headers map[string]string, body []byte) (*http.Response, error) {
|
func (h *HTTPClient) PostStream(ctx context.Context, url string, headers map[string]string, body []byte) (*http.Response, error) {
|
||||||
|
if h == nil || h.client == nil {
|
||||||
|
return nil, fmt.Errorf("volcano: HTTPClient 未初始化,无法发起上游请求")
|
||||||
|
}
|
||||||
if ctx == nil {
|
if ctx == nil {
|
||||||
ctx = context.Background()
|
ctx = context.Background()
|
||||||
}
|
}
|
||||||
|
|||||||
+91
-19
@@ -16,22 +16,27 @@ import (
|
|||||||
// SettingsResponse 是 GET /api/settings 的响应。
|
// SettingsResponse 是 GET /api/settings 的响应。
|
||||||
// API key 永远打码(借用 setting.maskAPIKey 风格,前 4 后 4 中间 ****)。
|
// API key 永远打码(借用 setting.maskAPIKey 风格,前 4 后 4 中间 ****)。
|
||||||
type SettingsResponse struct {
|
type SettingsResponse struct {
|
||||||
APIKey string `json:"api_key"` // 打码形式,例如 S_G8****naJ1
|
APIKey string `json:"api_key"` // 打码形式,例如 S_G8****naJ1
|
||||||
APIKeySet bool `json:"api_key_set"` // 是否已设置(用于前端判断要不要提示必填)
|
APIKeySet bool `json:"api_key_set"` // 是否已设置(用于前端判断要不要提示必填)
|
||||||
AuthKey string `json:"auth_key"` // 鉴权 key 打码(客户端访问 + admin 登录用)
|
AuthKey string `json:"auth_key"` // 鉴权 key 打码(客户端访问 + admin 登录用)
|
||||||
AuthKeySet bool `json:"auth_key_set"`
|
AuthKeySet bool `json:"auth_key_set"`
|
||||||
CORSAllowAll bool `json:"cors_allow_all"` // 允许所有来源(*)
|
// AdminKey 是**管理接口专用**凭证(v0.3.0 新增,可选)。
|
||||||
CORSOrigins string `json:"cors_origins"` // 逗号分隔的白名单(原文,含大小写,trim 末尾 /)
|
// 为空表示未单独配置,管理接口回退用 auth_key(向后兼容)。
|
||||||
CORSConfigured bool `json:"cors_configured"` // 是否配了 CORS(给 banner 用)
|
AdminKey string `json:"admin_key"` // 打码形式
|
||||||
|
AdminKeySet bool `json:"admin_key_set"` // 是否单独配置了 admin_key
|
||||||
|
AdminKeySource string `json:"admin_key_source"` // admin_key / auth_key / env / ""(未配置)
|
||||||
|
CORSAllowAll bool `json:"cors_allow_all"` // 允许所有来源(*)
|
||||||
|
CORSOrigins string `json:"cors_origins"` // 逗号分隔的白名单(原文,含大小写,trim 末尾 /)
|
||||||
|
CORSConfigured bool `json:"cors_configured"` // 是否配了 CORS(给 banner 用)
|
||||||
DefaultResourceID string `json:"default_resource_id"`
|
DefaultResourceID string `json:"default_resource_id"`
|
||||||
DefaultSpeaker string `json:"default_speaker"`
|
DefaultSpeaker string `json:"default_speaker"`
|
||||||
DefaultFormat string `json:"default_format"`
|
DefaultFormat string `json:"default_format"`
|
||||||
SampleRate int `json:"sample_rate"`
|
SampleRate int `json:"sample_rate"`
|
||||||
Model string `json:"model"`
|
Model string `json:"model"`
|
||||||
ModelType int `json:"model_type"`
|
ModelType int `json:"model_type"`
|
||||||
ExplicitLanguage string `json:"explicit_language"`
|
ExplicitLanguage string `json:"explicit_language"`
|
||||||
EnableSubtitle bool `json:"enable_subtitle"`
|
EnableSubtitle bool `json:"enable_subtitle"`
|
||||||
UpdatedAt string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
|
UpdatedAt string `json:"updated_at"` // RFC3339,来自 settings.installed_at(沿用)
|
||||||
}
|
}
|
||||||
|
|
||||||
// SettingsGetHandler GET /api/settings
|
// SettingsGetHandler GET /api/settings
|
||||||
@@ -58,6 +63,9 @@ func SettingsGetHandler(w http.ResponseWriter, r *http.Request) {
|
|||||||
APIKeySet: all["api_key"] != "",
|
APIKeySet: all["api_key"] != "",
|
||||||
AuthKey: maskAPIKeyField(all["auth_key"]),
|
AuthKey: maskAPIKeyField(all["auth_key"]),
|
||||||
AuthKeySet: all["auth_key"] != "",
|
AuthKeySet: all["auth_key"] != "",
|
||||||
|
AdminKey: maskAPIKeyField(all["admin_key"]),
|
||||||
|
AdminKeySet: all["admin_key"] != "",
|
||||||
|
AdminKeySource: setting.GetAdminKeySource(),
|
||||||
CORSAllowAll: all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true",
|
CORSAllowAll: all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true",
|
||||||
CORSOrigins: all["cors_origins"],
|
CORSOrigins: all["cors_origins"],
|
||||||
CORSConfigured: all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true" || all["cors_origins"] != "",
|
CORSConfigured: all["cors_allow_all"] == "1" || all["cors_allow_all"] == "true" || all["cors_origins"] != "",
|
||||||
@@ -298,10 +306,74 @@ func SettingsAuthKeyHandler(w http.ResponseWriter, r *http.Request) {
|
|||||||
_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
|
_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// SettingsAdminKeyRequest 是 PUT /api/admin/settings/admin-key 的 body。
|
||||||
|
// admin_key 是**管理接口专用**凭证;与 auth_key(业务侧 /v1/audio/speech 鉴权)分离后,
|
||||||
|
// 业务调用方拿到的 key 不再能访问管理接口。
|
||||||
|
// 传空串表示"清除独立管理凭证",管理接口回退用 auth_key(即旧行为)。
|
||||||
|
type SettingsAdminKeyRequest struct {
|
||||||
|
AdminKey string `json:"admin_key"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// SettingsAdminKeyHandler PUT /api/admin/settings/admin-key
|
||||||
|
// 鉴权: RequireAdmin(注意:能用当前凭证改,改完下一个请求即用新凭证)。
|
||||||
|
func SettingsAdminKeyHandler(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)
|
||||||
|
var body SettingsAdminKeyRequest
|
||||||
|
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 := strings.TrimSpace(body.AdminKey)
|
||||||
|
|
||||||
|
if key == "" {
|
||||||
|
// 清除独立管理凭证 → 回退 auth_key。回退后若 auth_key 也为空,
|
||||||
|
// 管理接口将全部 401(RequireAdmin 不再空凭证放行),这里必须挡住。
|
||||||
|
authKey, _, _ := s.SettingsGet("auth_key")
|
||||||
|
if authKey == "" {
|
||||||
|
middleware.SendJSONError(w, http.StatusBadRequest,
|
||||||
|
"admin_key cannot be cleared while auth_key is empty (would lock out admin access)",
|
||||||
|
"invalid_request_error", "missing_field")
|
||||||
|
return
|
||||||
|
}
|
||||||
|
if err := s.SettingsDelete("admin_key"); err != nil {
|
||||||
|
log.Printf("[settings] admin-key clear: %v", err)
|
||||||
|
middleware.SendJSONError(w, http.StatusInternalServerError, "clear admin_key failed", "server_error", "db_write_failed")
|
||||||
|
return
|
||||||
|
}
|
||||||
|
setting.SetAdminKeys([]string{authKey}, "auth_key")
|
||||||
|
log.Printf("[settings] admin_key cleared; admin auth falls back to auth_key")
|
||||||
|
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||||
|
_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "admin_key_set": false, "admin_key_source": "auth_key"})
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
if err := s.SettingsSet("admin_key", key); err != nil {
|
||||||
|
log.Printf("[settings] admin-key set: %v", err)
|
||||||
|
middleware.SendJSONError(w, http.StatusInternalServerError, "write admin_key failed", "server_error", "db_write_failed")
|
||||||
|
return
|
||||||
|
}
|
||||||
|
// 立即生效:只单独刷新管理凭证列表,不重新 LoadRuntimeConfig(那会覆盖其它字段)
|
||||||
|
setting.SetAdminKeys([]string{key}, "admin_key")
|
||||||
|
log.Printf("[settings] admin_key updated, runtime active (next request uses new admin credential)")
|
||||||
|
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||||
|
_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "admin_key_set": true, "admin_key_source": "admin_key"})
|
||||||
|
}
|
||||||
|
|
||||||
// SettingsCORSRequest 是 PUT /api/settings/cors 的 body。
|
// SettingsCORSRequest 是 PUT /api/settings/cors 的 body。
|
||||||
// 两个字段都可选(至少给一个),用指针区分"未传"和"传空串":
|
// 两个字段都可选(至少给一个),用指针区分"未传"和"传空串":
|
||||||
// - allow_all 指针: nil=未传(不动) *true=开 *false=关
|
// - allow_all 指针: nil=未传(不动) *true=开 *false=关
|
||||||
// - origins 字符串: nil=未传(不动) ""=传空串(清空) "url1\nurl2"=覆盖
|
// - origins 字符串: nil=未传(不动) ""=传空串(清空) "url1\nurl2"=覆盖
|
||||||
|
//
|
||||||
// 这样用户能精确表达意图(保留 / 改 / 清空),不会被 0/"" 歧义坑死。
|
// 这样用户能精确表达意图(保留 / 改 / 清空),不会被 0/"" 歧义坑死。
|
||||||
type SettingsCORSRequest struct {
|
type SettingsCORSRequest struct {
|
||||||
AllowAll *bool `json:"allow_all,omitempty"`
|
AllowAll *bool `json:"allow_all,omitempty"`
|
||||||
@@ -386,10 +458,10 @@ func SettingsCORSHandler(w http.ResponseWriter, r *http.Request) {
|
|||||||
log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.GetCORSAllowAll(), originsStr)
|
log.Printf("[settings] cors updated (allow_all=%v origins=%q), runtime active", setting.GetCORSAllowAll(), originsStr)
|
||||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||||
_ = json.NewEncoder(w).Encode(map[string]any{
|
_ = json.NewEncoder(w).Encode(map[string]any{
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"allow_all": setting.GetCORSAllowAll(),
|
"allow_all": setting.GetCORSAllowAll(),
|
||||||
"origins": originsStr,
|
"origins": originsStr,
|
||||||
"cors_active": true,
|
"cors_active": true,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -274,6 +274,21 @@ func contentTypeFor(format string) string {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// HealthHandler 暴露运行期状态;无鉴权。
|
// HealthHandler 暴露运行期状态;无鉴权。
|
||||||
|
// HealthzHandler GET /healthz —— 匿名存活探针,**只回 200 与字面量 "ok"**。
|
||||||
|
//
|
||||||
|
// 为什么单独做这个:v0.3.0 把详细健康数据(/health)收口到管理鉴权之后,
|
||||||
|
// 但 K8s liveness/readiness、Docker HEALTHCHECK、负载均衡健康检查默认都不带 Authorization。
|
||||||
|
// 若把它们继续指向 /health,加鉴权后会一律 401,导致探针失败、Pod 反复重启。
|
||||||
|
//
|
||||||
|
// 因此本端点刻意**不返回任何字段**(无版本、无内存、无配置状态、无模式信息),
|
||||||
|
// 只用于回答"进程还在不在"。运维要细节请走鉴权后的 /health。
|
||||||
|
func HealthzHandler(w http.ResponseWriter, r *http.Request) {
|
||||||
|
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
|
||||||
|
w.Header().Set("Cache-Control", "no-store")
|
||||||
|
w.WriteHeader(http.StatusOK)
|
||||||
|
_, _ = w.Write([]byte("ok"))
|
||||||
|
}
|
||||||
|
|
||||||
func HealthHandler(w http.ResponseWriter, r *http.Request) {
|
func HealthHandler(w http.ResponseWriter, r *http.Request) {
|
||||||
w.Header().Set("Content-Type", "application/json")
|
w.Header().Set("Content-Type", "application/json")
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,412 @@
|
|||||||
|
# Volcano-Engine-TTS-UI v0.3.0 阶段性实施步骤书
|
||||||
|
|
||||||
|
> **文件名**：`IMPLEMENT_v0.3.0.md`
|
||||||
|
> **基线**：`develop`
|
||||||
|
> **版本目标**：v0.3.0 —— 路由鉴权架构升级、健康/指标端点收口、管理入口统一到 `/dashboard`
|
||||||
|
> **关联文档**：[UPSTREAM_ADAPTER_GUIDE.md](UPSTREAM_ADAPTER_GUIDE.md)（上游适配器重构，与本改造正交，互不干扰）
|
||||||
|
>
|
||||||
|
> 本文是 v0.3.0 的**唯一实施依据**，由初版方案按实际代码基线校正而成。
|
||||||
|
> 校正说明见 [附录 A](#附录-a与初版方案的差异)。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. 改造目标
|
||||||
|
|
||||||
|
| # | 目标 | 验收标准 |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | **收口健康/指标端点**：`/metrics`、`/health`、`/dashboard` 不再匿名可读 | 未携带管理凭证时不可读到任何健康数据 |
|
||||||
|
| 2 | **补前置缺口**：`RequireAdmin` 在凭证未配置时不再静默放行 | 未配置凭证时管理接口拒绝访问，且启动期有明确信号 |
|
||||||
|
| 3 | **权限隔离**：业务调用凭证不得访问管理接口 | 用 TTS 调用 key 访问 `/api/admin/*` 返回 401 |
|
||||||
|
| 4 | 管理入口统一：`/admin` → `/dashboard`，旧路径 301 兼容 | 访问 `/admin` 301 到 `/dashboard` |
|
||||||
|
| 5 | API 路由分层：`/api/public/*`、`/api/user/*`、`/api/admin/*` | 三条前缀各自挂对应中间件，`/api/user/*` 为桩 |
|
||||||
|
| 6 | 存量管理接口迁移到 `/api/admin/*`，旧路径继续可用 | 新旧路径行为一致，老脚本零改动 |
|
||||||
|
| 7 | 两套用量查询占位接口 | `/api/user/usage`（管理鉴权）、`/v1/dashboard/billing/usage`（Bearer） |
|
||||||
|
| 8 | 文档 / 示例配置 / Docker 注释同步更新，标注 Breaking Change | README、`.env.example`、`docker-compose.yml`、CHANGELOG 一致 |
|
||||||
|
| 9 | **不改动** `adapter/`、`store/` 核心业务模型，**不破坏** `/v1/audio/speech` | TTS 业务接口回归通过 |
|
||||||
|
|
||||||
|
### 重要约束
|
||||||
|
|
||||||
|
- v0.3.0 **仍是单用户模式**；`/api/user/*` 仅骨架 + 桩实现，完整多用户能力放 v0.4.0。
|
||||||
|
- **不引入 Cookie 会话**（理由见 [附录 B](#附录-b为什么不做-cookie-会话)）。管理鉴权继续使用
|
||||||
|
`Authorization: Bearer <key>`，前端继续用 `sessionStorage` 保存凭证。
|
||||||
|
- **每个阶段结束必须可编译、可运行、可本地回归**，拒绝大爆炸式一次性修改。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 现状基线（开工前必须知道的事实）
|
||||||
|
|
||||||
|
本项目的真实鉴权现状与初版方案的假设**不同**，照着初版做会返工。以下是核对过代码的结论：
|
||||||
|
|
||||||
|
| 事项 | 真实现状 | 代码位置 |
|
||||||
|
|---|---|---|
|
||||||
|
| 管理鉴权中间件 | **只有 `RequireAdmin`**，Bearer 请求头校验。**不存在 `AdminSessionMiddleware`** | `middleware/admin_auth.go:20` |
|
||||||
|
| 凭证存储 | 前端 `sessionStorage['ttsAdminKey']`，**无 Cookie** | `router/admin-shell.js:10-15` |
|
||||||
|
| 凭证来源 | 数据库 `auth_key` → 回退环境变量 `OPENAI_TTS_API_KEY` | `setting/config.go:384-392` |
|
||||||
|
| 凭证复用 | **同一个 key 既登录后台、又调 TTS 接口**（本次要拆开） | `middleware/auth.go` + `middleware/admin_auth.go` |
|
||||||
|
| 指标实现 | 自研 `telemetry` 包，**未引入 `prometheus/client_golang`**，无 `promhttp` | `router/router.go:136` |
|
||||||
|
| 客户端 IP | 已有 `middleware.GetClientIP`，支持 XFF + `TRUSTED_PROXY_HOPS` | `middleware/ratelimit.go:196` |
|
||||||
|
| CORS | 非白名单 Origin 在中间件层直接 403 | `middleware/cors.go:138-147` |
|
||||||
|
|
||||||
|
### 1.1 匿名可读端点（本次要收口的全部）
|
||||||
|
|
||||||
|
| 端点 | 泄漏内容 | 代码位置 |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET /dashboard` | **HTML 看板，同时拉 `/health` + `/metrics`**，聚合度最高 | `router/router.go:120` |
|
||||||
|
| `GET /metrics` | Prometheus 全量指标（流量、模型名、错误分布、计费字符数） | `router/router.go:136` |
|
||||||
|
| `GET /health` | 版本 / commit / 运行时长 / 内存 / goroutine + 配置错误文本 | `router/router.go:119` |
|
||||||
|
| `GET /api/setup/status` | normal 模式下仍返回 `{installed, mode}` | `router/router.go:75` |
|
||||||
|
|
||||||
|
> `/api/setup/prefill` 在 normal 模式返回 404（handler 内自检），**不可达**，无需处理。
|
||||||
|
|
||||||
|
### 1.2 已有但必须保留的机制
|
||||||
|
|
||||||
|
- `InstallGuard`：安装模式下按白名单放行（`/setup`、`/api/setup`、`/health`、`/metrics`），
|
||||||
|
安装阶段无数据库、无凭证，**不得套用 `RequireAdmin`**。`middleware/installguard.go:19`
|
||||||
|
- 现有 `/api/admin/metrics` 已有 `RequireAdmin`，返回同样的 Prometheus 文本（保留复用）。
|
||||||
|
- 现有静态资源路由 `/admin/admin.css`、`/admin/admin-shell.js`（`router/router.go:90-97`），
|
||||||
|
迁移时必须同步处理，否则页面丢样式。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 分阶段实施
|
||||||
|
|
||||||
|
### 阶段 1｜收紧 `RequireAdmin`（前置缺口，最小改动）
|
||||||
|
|
||||||
|
**为什么先做这一步**：`RequireAdmin` 当前在凭证列表为空时**直接放行**（`middleware/admin_auth.go:29-33`）。
|
||||||
|
不修这个，后面给 `/metrics`、`/health` 套 `RequireAdmin` **等于没套**。
|
||||||
|
|
||||||
|
**改动范围**：`middleware/admin_auth.go`、`middleware/auth.go`、`setting/config.go`、`main.go`
|
||||||
|
|
||||||
|
#### 1.1 空凭证不再放行
|
||||||
|
|
||||||
|
将 `len(keys) == 0 → next.ServeHTTP` 改为拒绝 + 显式日志：
|
||||||
|
|
||||||
|
```go
|
||||||
|
keys := setting.GetAdminKeys()
|
||||||
|
if len(keys) == 0 {
|
||||||
|
log.Printf("[admin_auth] 拒绝访问:未配置管理凭证(admin_key / auth_key 均为空) - 路径=%s", r.URL.Path)
|
||||||
|
denyAdmin(w, r)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 1.2 新增独立 `admin_key`（权限隔离）
|
||||||
|
|
||||||
|
- `store`：新增可选的设置项 `admin_key`（**无需数据库迁移**，`settings` 是键值表）。
|
||||||
|
- `setting`：新增 `GetAdminKeys() []string`，取值优先级：
|
||||||
|
|
||||||
|
```
|
||||||
|
admin_key（DB） → 回退 auth_key（DB） → 回退 OPENAI_TTS_API_KEY（env）
|
||||||
|
```
|
||||||
|
|
||||||
|
- `RequireAdmin` 改用 `GetAdminKeys()`；**`middleware.ValidateAPIKey`（`/v1/audio/speech` 用）保持只看 `auth_key`**。
|
||||||
|
- 效果：配了 `admin_key` 后，业务调用凭证**无法**访问管理接口，隔离成立；不配则行为与旧版完全一致（向后兼容）。
|
||||||
|
|
||||||
|
#### 1.3 启动期校验（fail-fast）
|
||||||
|
|
||||||
|
在 `main.go` normal 模式分支加入：管理凭证为空时**拒绝启动**并打印清晰原因
|
||||||
|
（与现有配置损坏 fail-fast 风格一致）。
|
||||||
|
|
||||||
|
> ⚠️ **破坏性提示**：若你的部署目前未配置任何凭证，本阶段后服务将无法启动。
|
||||||
|
> 这是刻意的——此前那种状态下管理接口是完全裸奔的。请先配好 `auth_key`（或 `admin_key`）再升级。
|
||||||
|
|
||||||
|
#### 1.4 ✅ 阶段 1 回归
|
||||||
|
|
||||||
|
- [ ] `go build ./... && go vet ./...` 通过
|
||||||
|
- [ ] 配置 `auth_key` 后：`/api/admin/overview` 带正确 key 返回 200，错误 key 返回 401
|
||||||
|
- [ ] 不配置任何凭证时启动：进程拒绝启动并给出明确日志
|
||||||
|
- [ ] 配置独立 `admin_key` 后：用 `auth_key` 访问 `/api/admin/*` 返回 401
|
||||||
|
- [ ] `/v1/audio/speech` 用 `auth_key` 调用**不受影响**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 阶段 2｜收口健康 / 指标端点（本版本核心目标）
|
||||||
|
|
||||||
|
**改动范围**：`router/router.go`、`controller/tts.go`、`middleware/`（新增 CIDR 白名单）、`setting/config.go`
|
||||||
|
|
||||||
|
#### 2.1 `/health` 拆分为两个端点
|
||||||
|
|
||||||
|
| 端点 | 鉴权 | 返回 |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET /healthz` | **无鉴权** | 仅 `200` + 字面量 `ok`，**不含任何字段** |
|
||||||
|
| `GET /health` | `RequireAdmin` | 现有完整 JSON（版本/内存/配置状态等） |
|
||||||
|
|
||||||
|
> ⚠️ **`/healthz` 必须与 `/health` 鉴权在同一次改动内落地**。分开部署会出现探针空窗，
|
||||||
|
> 导致 K8s liveness 失败、Pod 反复重启。
|
||||||
|
|
||||||
|
> 📌 探针迁移提醒：若现有 K8s `livenessProbe` / `readinessProbe` / Docker `HEALTHCHECK`
|
||||||
|
> 指向 `/health`，需同步改指 `/healthz`。README 中要写明。
|
||||||
|
|
||||||
|
#### 2.2 `/metrics` 收口 + 可选内网白名单
|
||||||
|
|
||||||
|
新环境变量 `METRICS_ALLOW_CIDR`（逗号分隔多个 CIDR）：
|
||||||
|
|
||||||
|
- **已配置**：在根路径注册 `/metrics`，包裹 `MetricsIPAllowListMiddleware`；
|
||||||
|
非白名单 IP 返回 **404**（不返回 403，避免向扫描者确认端点存在）。
|
||||||
|
- **未配置**：根路径 `/metrics` **完全不注册**，访问 404。
|
||||||
|
- 两种情况都**始终**提供鉴权版 `GET /api/admin/metrics`（已存在，供面板使用）。
|
||||||
|
|
||||||
|
中间件实现要点：复用 `middleware.GetClientIP(r)`（已处理 XFF / `TRUSTED_PROXY_HOPS`），
|
||||||
|
用标准库 `net/netip` 解析 CIDR。
|
||||||
|
|
||||||
|
> ⚠️ **Docker 环境**：`METRICS_ALLOW_CIDR` 必须填**容器内网网段**（如 `172.16.0.0/12`），
|
||||||
|
> **不要填 `127.0.0.1/32`** —— 那是容器自身的回环，Prometheus 在宿主机或其他容器里进不来。
|
||||||
|
|
||||||
|
#### 2.3 `/dashboard` 与 `/api/setup/status` 收口
|
||||||
|
|
||||||
|
- `/dashboard`：套 `RequireAdmin`。它是本版本**单点泄漏最严重**的端点（一个 URL 暴露全部健康数据）。
|
||||||
|
- `/api/setup/status`：套 `RequireAdmin`。
|
||||||
|
- **前端状态提示**：`/dashboard` 的 HTML 外壳本身不敏感，前端登录判断逻辑保持现状
|
||||||
|
（`sessionStorage` 无 key → 显示登录视图）。**不在服务端做页面级跳转**，原因见 [附录 B](#附录-b为什么不做-cookie-会话)。
|
||||||
|
|
||||||
|
#### 2.4 ✅ 阶段 2 回归
|
||||||
|
|
||||||
|
- [ ] 未配置 `METRICS_ALLOW_CIDR`：根 `/metrics`、`/health` 返回 404
|
||||||
|
- [ ] 配置 `METRICS_ALLOW_CIDR=127.0.0.1/32`：本机可访问根 `/metrics`，其他 IP 返回 404
|
||||||
|
- [ ] `/healthz` 无鉴权可访问且**不含任何字段**
|
||||||
|
- [ ] `/health` 无凭证返回 401，带管理凭证返回完整 JSON
|
||||||
|
- [ ] `/dashboard` 无凭证返回 401
|
||||||
|
- [ ] `/api/setup/status` 无凭证返回 401
|
||||||
|
- [ ] 面板内 `/api/admin/metrics`、`/api/admin/health` 正常返回
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 阶段 3｜路由分层与路径迁移
|
||||||
|
|
||||||
|
**改动范围**：`router/router.go`、`controller/`（新增两个桩 handler + 页面路由别名）
|
||||||
|
|
||||||
|
#### 3.1 分层路由注册
|
||||||
|
|
||||||
|
```go
|
||||||
|
apiPublic := r.PathPrefix("/api/public").Subrouter()
|
||||||
|
// 预留空壳，暂不注册业务
|
||||||
|
|
||||||
|
apiUser := r.PathPrefix("/api/user").Subrouter()
|
||||||
|
apiUser.Use(middleware.RequireAdmin) // 单用户模式下与 admin 等价，v0.4.0 再分化
|
||||||
|
|
||||||
|
apiAdmin := r.PathPrefix("/api/admin").Subrouter()
|
||||||
|
apiAdmin.Use(middleware.RequireAdmin)
|
||||||
|
```
|
||||||
|
|
||||||
|
将现有管理 handler 挂到 `apiAdmin`（**复用 handler 本体，不改业务逻辑**）：
|
||||||
|
|
||||||
|
| 旧路径 | 新路径 |
|
||||||
|
|---|---|
|
||||||
|
| `GET/POST /api/voices` | `GET/POST /api/admin/voices` |
|
||||||
|
| `DELETE /api/voices/{name}` | `DELETE /api/admin/voices/{name}` |
|
||||||
|
| `PATCH /api/voices/{name}/toggle` | `PATCH /api/admin/voices/{name}/toggle` |
|
||||||
|
| `GET/PUT /api/settings` | `GET/PUT /api/admin/settings` |
|
||||||
|
| `PUT /api/settings/api-key` | `PUT /api/admin/settings/api-key` |
|
||||||
|
| `PUT /api/settings/auth-key` | `PUT /api/admin/settings/auth-key` |
|
||||||
|
| `PUT /api/settings/cors` | `PUT /api/admin/settings/cors` |
|
||||||
|
| `GET /api/admin/overview` | 位置不变 |
|
||||||
|
| `GET /api/admin/metrics` | 位置不变 |
|
||||||
|
|
||||||
|
#### 3.2 旧路径兼容：用**别名**，不要重定向
|
||||||
|
|
||||||
|
**旧路径指向同一个 handler，不做 301/308 跳转。**
|
||||||
|
|
||||||
|
理由（三者对比）：
|
||||||
|
|
||||||
|
| 方案 | 问题 |
|
||||||
|
|---|---|
|
||||||
|
| 301 | 会把 POST/PUT/PATCH/DELETE **降级成 GET**（RFC 7231），且浏览器**永久缓存**，客户端察觉不到路径变化 |
|
||||||
|
| 308 | 保留方法和请求体，比 301 好；但多一次往返，对非浏览器脚本仍是行为变化 |
|
||||||
|
| **别名（采用）** | 两个路径直接可用，零往返、零破坏，老脚本完全无感 |
|
||||||
|
|
||||||
|
旧路径在当前版本**保留**，并在代码注释标注"过渡期别名，未来版本移除"。
|
||||||
|
|
||||||
|
#### 3.3 页面路由迁移
|
||||||
|
|
||||||
|
```go
|
||||||
|
// 新入口
|
||||||
|
r.HandleFunc("/dashboard", middleware.RequireAdmin(serveAdmin(dashboardHTML))).Methods("GET")
|
||||||
|
r.HandleFunc("/dashboard/login", serveAdmin(adminLoginHTML)).Methods("GET")
|
||||||
|
r.HandleFunc("/dashboard/voices", middleware.RequireAdmin(serveAdmin(adminVoicesHTML))).Methods("GET")
|
||||||
|
r.HandleFunc("/dashboard/settings", middleware.RequireAdmin(serveAdmin(adminSettingsHTML))).Methods("GET")
|
||||||
|
|
||||||
|
// 静态资源：必须同步迁移，否则面板丢样式/脚本
|
||||||
|
r.HandleFunc("/dashboard/admin.css", ...) // 原 /admin/admin.css
|
||||||
|
r.HandleFunc("/dashboard/admin-shell.js", ...) // 原 /admin/admin-shell.js
|
||||||
|
|
||||||
|
// 旧入口 301 永久重定向（页面用 301 正确）
|
||||||
|
r.HandleFunc("/admin", func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
http.Redirect(w, r, "/dashboard", http.StatusMovedPermanently)
|
||||||
|
}).Methods("GET")
|
||||||
|
```
|
||||||
|
|
||||||
|
前端同步改动（`router/*.html`、`admin-shell.js`）：
|
||||||
|
|
||||||
|
- 页面间跳转与链接：`/admin` → `/dashboard`，`/admin/login` → `/dashboard/login` 等
|
||||||
|
- API 调用地址迁移到 `/api/admin/*`
|
||||||
|
- 静态资源引用 `/admin/admin.css` → `/dashboard/admin.css`（同理 `admin-shell.js`）
|
||||||
|
- `admin-shell.js` 的 401 拦截逻辑改为跳 `/dashboard/login`
|
||||||
|
|
||||||
|
> 📌 注意：`/dashboard` 原本是**服务状态预览页**（`router/health.html`）。迁入后该页面的定位
|
||||||
|
> 变成"管理后台首页"，健康/指标数据改由 `/api/admin/health`、`/api/admin/metrics` 提供。
|
||||||
|
> 若仍希望保留独立的只读状态页，请单独确认（本版本不提供匿名版本）。
|
||||||
|
|
||||||
|
#### 3.4 桩接口
|
||||||
|
|
||||||
|
| 端点 | 鉴权 | 行为 |
|
||||||
|
|---|---|---|
|
||||||
|
| `GET /api/user/usage` | `RequireAdmin` | 单用户模式返回全局用量统计（桩，v0.4.0 改为按用户过滤） |
|
||||||
|
| `GET /v1/dashboard/billing/usage` | Bearer 业务 key | 返回用量统计，对齐 OpenAI 返回格式 |
|
||||||
|
|
||||||
|
#### 3.5 ✅ 阶段 3 回归
|
||||||
|
|
||||||
|
- [ ] `/admin` 301 跳 `/dashboard`；`/dashboard` 各页面与静态资源正常加载（无 404、无样式丢失）
|
||||||
|
- [ ] 面板内音色增删改、全局设置、CORS 配置全部正常
|
||||||
|
- [ ] 旧路径 `/api/voices`、`/api/settings` **直接可用**（不是重定向），行为与新路径一致
|
||||||
|
- [ ] `GET /api/user/usage`、`GET /v1/dashboard/billing/usage` 正常返回
|
||||||
|
- [ ] 用业务 Bearer key 访问 `/api/admin/*` 返回 401
|
||||||
|
- [ ] 完整安装流程跑通，装完跳转 `/dashboard`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 阶段 4｜文档、配置、发布
|
||||||
|
|
||||||
|
**改动范围**：`README.md`、`.env.example`、`docker-compose.yml`、`CHANGELOG.md`
|
||||||
|
|
||||||
|
1. **README.md**
|
||||||
|
- WebUI 入口改为 `/dashboard`；注明 `/admin` 为旧兼容重定向
|
||||||
|
- 端点表更新：`/metrics`、`/health` 默认 404；新增 `/healthz`、`METRICS_ALLOW_CIDR`、`admin_key` 说明
|
||||||
|
- 公网部署安全清单更新（整节重写，明确"哪些端点不鉴权、必须靠什么挡"）
|
||||||
|
- 探针迁移提醒：K8s / Docker HEALTHCHECK 改指 `/healthz`
|
||||||
|
2. **`.env.example`**：新增 `METRICS_ALLOW_CIDR` 注释（含 Docker 网段警告）
|
||||||
|
3. **`docker-compose.yml`**：`METRICS_ALLOW_CIDR` 注释示例
|
||||||
|
4. **`CHANGELOG.md`**：v0.3.0 条目，明确列出 Breaking Change
|
||||||
|
|
||||||
|
#### Release Note · Breaking Change 清单
|
||||||
|
|
||||||
|
1. **`/metrics`、`/health`、`/dashboard` 不再匿名可读**。Prometheus 抓取请用
|
||||||
|
`/api/admin/metrics`（带 Bearer），或配置 `METRICS_ALLOW_CIDR`；
|
||||||
|
探针请改用 `/healthz`。
|
||||||
|
2. **未配置任何凭证时服务拒绝启动**（此前管理接口完全裸奔）。
|
||||||
|
3. **管理凭证与业务凭证可分离**：新增 `admin_key`；配了之后业务 key 无法访问管理接口。
|
||||||
|
4. **管理接口迁移到 `/api/admin/*`**；旧路径保留为**别名（非重定向）**，未来版本移除。
|
||||||
|
5. **管理入口迁移到 `/dashboard`**；`/admin` 301 永久重定向。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 阶段 5｜全量回归测试（发布前必须全部通过）
|
||||||
|
|
||||||
|
> ⚠️ **本项目测试文件不入库**（`.gitignore` 的 `*_test.go`），CI 只能守住"编译 + vet"，
|
||||||
|
> **守不住行为回归**。因此下面的手工回归是发布前的唯一防线，必须逐条执行并记录结果。
|
||||||
|
|
||||||
|
### ✨ 安装流程
|
||||||
|
1. 不设 `TTS_ADMIN_KEY` 启动 → 终端打印一次性密钥（带醒目警告）
|
||||||
|
2. 不带密钥 `POST /api/setup` → 401；带密钥 → 安装成功
|
||||||
|
3. 安装完成跳转 `/dashboard`；进程重启后旧一次性密钥失效
|
||||||
|
4. 已安装状态访问 `/setup` → 自动跳 `/dashboard`
|
||||||
|
|
||||||
|
### ✨ 管理面板
|
||||||
|
5. 未登录访问 `/dashboard` → 显示登录视图；登录后完整可用
|
||||||
|
6. 访问 `/admin` → 301 跳 `/dashboard`
|
||||||
|
7. 音色 CRUD、全局设置、CORS 修改全部正常
|
||||||
|
8. 仪表盘通过 `/api/admin/health`、`/api/admin/metrics` 渲染正常
|
||||||
|
9. 用量面板读取 `/api/user/usage` 正常
|
||||||
|
|
||||||
|
### ✨ 指标与健康端点
|
||||||
|
10. 不配 `METRICS_ALLOW_CIDR` → 根 `/metrics`、`/health` 返回 404
|
||||||
|
11. 配 `METRICS_ALLOW_CIDR=127.0.0.1/32` → 本机根路径可访问，其他 IP 404
|
||||||
|
12. `/healthz` 匿名可访问且**响应体不含任何业务字段**
|
||||||
|
|
||||||
|
### ✨ 业务接口
|
||||||
|
13. `/v1/audio/speech` OpenAI TTS 合成完全正常
|
||||||
|
14. `GET /v1/dashboard/billing/usage` 合法 key → 200；非法 key → 401
|
||||||
|
15. 业务 Bearer key 访问 `/api/admin/*` → 401（隔离生效）
|
||||||
|
|
||||||
|
### ✨ 存量兼容
|
||||||
|
16. 旧管理接口路径`/api/voices`、`/api/settings` 直接可用，行为与新路径一致
|
||||||
|
|
||||||
|
### ✨ 安全场景
|
||||||
|
17. 未配置凭证时服务拒绝启动
|
||||||
|
18. 匿名无法获取任何健康 / 指标数据
|
||||||
|
19. 旧 `tts.db` 直接复用升级，**无需数据库迁移**
|
||||||
|
|
||||||
|
### ✨ 本地自动化
|
||||||
|
20. `go build ./... && go vet ./...` 通过
|
||||||
|
21. `go test ./... -count=1` 全绿
|
||||||
|
（含抓出过 `VoiceList` 语义 bug 的那批集成测试，是本次改造最重要的安全网）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 发布 v0.3.0
|
||||||
|
|
||||||
|
1. 阶段 5 全部通过；Docker 镜像构建测试通过
|
||||||
|
2. `git tag v0.3.0` 并推送
|
||||||
|
3. 创建 Release，粘贴 Release Notes，**明确列出 5 条 Breaking Change**
|
||||||
|
4. 创建维护分支 `v0.3.x`，用于后续 bugfix 与安全补丁
|
||||||
|
5. `develop` 继续迭代 v0.4.0；上游适配器重构可并行
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. v0.4.0 后续规划（仅规划，不在 v0.3.0 实现）
|
||||||
|
|
||||||
|
v0.3.0 已把**路由分层**和**权限隔离**打好；v0.4.0 只需填充业务逻辑。
|
||||||
|
|
||||||
|
1. `store` 新增 `users` 表，区分普通用户 / 管理员角色
|
||||||
|
2. 引入真正的会话机制（此时才需要 Cookie + CSRF，或采用 Bearer-per-user）
|
||||||
|
3. `/api/user/*` 从桩转真实业务：个人用量、个人 API 密钥管理、个人调用日志
|
||||||
|
4. `/api/admin/*` 实现用户 CRUD、配额管理；音色归属绑定用户
|
||||||
|
5. SPA 扩展个人中心、密钥管理页面
|
||||||
|
6. `/v1/dashboard/billing/usage` 按 API-Key 归属过滤统计
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 风险注意事项
|
||||||
|
|
||||||
|
| # | 风险 | 对策 |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | **`/healthz` 与 `/health` 加鉴权分批上线** → 探针空窗、Pod 重启循环 | 必须同一批改动内落地 |
|
||||||
|
| 2 | **未配凭证导致服务启动失败**（阶段 1 的破坏性结果） | 升级前先配 `auth_key`；README 与 Release Note 明确提示 |
|
||||||
|
| 3 | Docker 内 `METRICS_ALLOW_CIDR` 填 `127.0.0.1/32` | 必须填容器内网网段 |
|
||||||
|
| 4 | **禁止把 `RequireAdmin` 套到 `/setup`** | 安装阶段无数据库、无凭证，保留 `InstallGuard` |
|
||||||
|
| 5 | 旧路径若用重定向会导致 POST 降级 / 客户端无感 | 采用**别名**，不重定向 |
|
||||||
|
| 6 | 静态资源路由遗漏导致面板丢样式 | 迁移时同步 `/dashboard/admin.css`、`/dashboard/admin-shell.js` |
|
||||||
|
| 7 | **CI 跑不到测试**（测试文件不入库） | 每阶段结束本地执行 `go test ./... -count=1` |
|
||||||
|
| 8 | 误改 `adapter/`、`store/` 业务模型 | 本改造不涉及；改动仅限 router / middleware / controller / 前端 / 文档 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附录 A｜与初版方案的差异
|
||||||
|
|
||||||
|
| 初版方案 | 本版 | 原因 |
|
||||||
|
|---|---|---|
|
||||||
|
| 阶段 0 "重命名 `AdminSessionMiddleware`" | **删除该阶段** | 该中间件**不存在**；实为新建 Cookie 会话层，会把"低风险重构"变成破坏性变更 |
|
||||||
|
| 新增 `UserSessionMiddleware` | **不做** | 没有会话机制；`/dashboard` 页面请求不带 `sessionStorage`，服务端无从判断登录态 |
|
||||||
|
| 新增 `CSRFMiddleware` | **不做** | Bearer 认证免疫 CSRF（浏览器不会自动附带 `Authorization`）；CORS 已在中间件层 403 非白名单 Origin |
|
||||||
|
| Cookie `HttpOnly` / `SameSite=Strict` | **不做** | 不使用 Cookie |
|
||||||
|
| `promhttp.Handler()` | `metrics.Meter.Handler()` | 项目未引入 `prometheus/client_golang` |
|
||||||
|
| `controller.AdminSPAPageHandler` / `AdminLoginPageHandler` | `serveAdmin(adminHTML)` 等 | 这两个 handler 不存在 |
|
||||||
|
| 漏点只列 `/metrics`、`/health` | 补入 **`/dashboard`**、`/api/setup/status` | `/dashboard` 聚合度最高；实测确认这两个也匿名可达 |
|
||||||
|
| 旧 API 路径 301 重定向 | **别名**，不重定向 | 301 会把 POST 降级为 GET 且被永久缓存 |
|
||||||
|
| 未提静态资源路由 | 明确 `/dashboard/admin.css` 等 | 遗漏会导致面板丢样式 |
|
||||||
|
| `RequireAdmin` 空凭证放行未处理 | **阶段 1 专门修复 + fail-fast** | 不修则后续所有鉴权改动形同虚设 |
|
||||||
|
|
||||||
|
### 初版保留不变的部分
|
||||||
|
|
||||||
|
分阶段 + 每阶段可编译可回归的原则、`InstallGuard` 保持不动、`/v1/dashboard/billing/usage`
|
||||||
|
走 Bearer、`/api/public` 与 `/api/user` 留桩、Docker CIDR 网段警告、v0.4.0 规划、发布流程。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附录 B｜为什么不做 Cookie 会话
|
||||||
|
|
||||||
|
1. **不解决问题**：目标是"健康数据不外泄"，用现有 `RequireAdmin` 即可 100% 达成，
|
||||||
|
不需要会话层。
|
||||||
|
2. **服务端拿不到 SPA 登录态**：前端凭证存 `sessionStorage`，**不随请求发送**，
|
||||||
|
所以服务端无法判断 `/dashboard` 页面请求是否已登录。初版要的"未登录访问 `/dashboard`
|
||||||
|
自动跳登录页"在服务端**做不到**——除非引入 Cookie，而这正是初版的前提缺失之处。
|
||||||
|
3. **CSRF 需求随之消失**：Cookie 才需要 CSRF 防护；Bearer + `sessionStorage` 天然免疫。
|
||||||
|
不做 Cookie 就不必实现 token 发放与轮换，也避开同源 SPA 下 `SameSite=Strict` 的坑。
|
||||||
|
4. **破坏现有客户端**：现有用 `Authorization: Bearer` 调管理 API 的脚本会全部 401，
|
||||||
|
与"给外部脚本过渡期"的目标冲突。
|
||||||
|
5. **真正的权限问题另有其解**：当前"一个 key 既是管理密码又是业务密钥"才是实质缺陷，
|
||||||
|
用新增可选 `admin_key` 即可分离，成本约 20 行，无需引入会话。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*文档版本：v2 · 校正基线：`develop` @ `49f57e4`（2026-10-04）*
|
||||||
|
*初版：v1（外部产出）· 校正原因见附录 A*
|
||||||
@@ -0,0 +1,343 @@
|
|||||||
|
# UI 外包 Handoff · 火山 TTS 管理后台
|
||||||
|
|
||||||
|
> 历史文档。本文档描述的是**外包给 Codex 做视觉改造**那一次任务,目标是"现有功能完全不动, 只换皮"。
|
||||||
|
>
|
||||||
|
> ⚠️ **状态: 任务已结束, 且路线已变更。** 该任务之后, admin 后台由提交 `9245c13`
|
||||||
|
> 自行重构成**多页 SPA**(见下面 §0.1),本文档正文里的"单文件 / 大小上限 / 改这两个 .html"
|
||||||
|
> 等约束**均已失效**,保留仅为记录当时的交接内容与设计讨论。
|
||||||
|
> 若要再做视觉改造,请以 §0.1 的当前文件结构为准。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0.1 当前真实结构(以此为准)
|
||||||
|
|
||||||
|
admin 后台已从单文件拆分为多页面,共享一套 CSS/JS,由 `//go:embed` 逐条嵌入:
|
||||||
|
|
||||||
|
| 文件 | 作用 | 大小 |
|
||||||
|
|---|---|---|
|
||||||
|
| `router/admin.html` | 后台外壳(导航 / 布局) | 5.5KB |
|
||||||
|
| `router/admin-login.html` | 登录页 | 2.1KB |
|
||||||
|
| `router/admin-voices.html` | 音色管理页 | 13.5KB |
|
||||||
|
| `router/admin-settings.html` | 设置页 | 14.4KB |
|
||||||
|
| `router/admin.css` | 共享样式(全部页面) | 20.2KB |
|
||||||
|
| `router/admin-shell.js` | 共享脚本: axios 实例 / toast / 外壳挂载 / 401 拦截 | 7.1KB |
|
||||||
|
| `router/setup.html` | 安装引导页(仍是单文件) | 24.0KB |
|
||||||
|
|
||||||
|
- URL 路由(非 hash):`/admin` · `/admin/login` · `/admin/voices` · `/admin/settings`
|
||||||
|
- 公共逻辑集中在 `admin-shell.js`,通过 `window.admin` 暴露
|
||||||
|
`{ http, getKey, setKey, clearKey, toast, mountShell, formatUptime, … }`
|
||||||
|
- **已无"单文件 ≤ 35KB"这类约束**;新增页面请复用 `admin.css` + `admin-shell.js`,不要各写一套。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. 任务概览(历史原文)
|
||||||
|
|
||||||
|
| 项 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| 改的文件 | `router/admin.html`、`router/setup.html` |
|
||||||
|
| 改的部分 | 视觉、布局、组件、交互模式（loading/empty/error/反馈）|
|
||||||
|
| 不改的部分 | API 调用、状态管理逻辑、字段名、文案语义 |
|
||||||
|
| 期望产物 | 改完后的两个 .html, 总大小 ≤ 64KB（admin ≤ 35KB, setup ≤ 15KB）|
|
||||||
|
| 验收 | dev 起服, 浏览器走完所有流程无回归 + 视觉明显更好 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 技术栈约束（历史原文；"单文件"部分已失效）
|
||||||
|
|
||||||
|
| 项 | 现状 | 改动空间 |
|
||||||
|
|---|---|---|
|
||||||
|
| 构建 | **无构建步骤**（`//go:embed` 进 binary）| 不可改 |
|
||||||
|
| Vue | 3.4 via `cdn.bootcdn.net` | 可换版本（保持 3.x 即可）|
|
||||||
|
| HTTP | axios 1.6（集中在 `admin-shell.js`）| 可换（fetch / ky / 留 axios 都行）|
|
||||||
|
| CSS | 手写, 走 CSS 变量, 集中在 `admin.css` | 可换 **Tailwind CDN / DaisyUI / Pico / 手写** 都行 |
|
||||||
|
| 图标 | 暂无 | 可加 lucide / heroicons inline SVG / emoji |
|
||||||
|
| 字体 | 系统默认 (`-apple-system, "PingFang SC"...`) | 可加 `Noto Sans SC` via Google Fonts, 但要评估大小 |
|
||||||
|
| 路由 | 拆分后已改为 **URL 路由**（`/admin/voices` 等）,不再是 hash 三 tab | 保持 URL 路由 |
|
||||||
|
|
||||||
|
**注意（历史约束,已不适用）**: 当时二进制大小敏感 —— admin.html 31.19KB / setup.html 13.01KB。拆分后 admin 侧总量约 63KB(分散在 6 个文件里,浏览器可分页只加载所需部分),embed 进 binary 后大小影响可接受。**仍然建议**: 不要无脑加 UI 库(Tailwind 全量 + DaisyUI 会显著增大 embed 体积);要加就加在 `admin.css` 一处,所有页面共享。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 路由 & 模式
|
||||||
|
|
||||||
|
### 2.1 三个 URL
|
||||||
|
- `GET /setup` → `router/setup.html`（安装模式才进得去）
|
||||||
|
- `GET /admin` → `router/admin.html`（任何模式都返回 HTML, 鉴权由前端 JS 拦截）
|
||||||
|
- `GET /` → 重定向到 `/setup` 或 `/admin`
|
||||||
|
|
||||||
|
### 2.2 状态机（admin.html）
|
||||||
|
|
||||||
|
```
|
||||||
|
未登录 (无 sessionStorage 'ttsAdminKey')
|
||||||
|
├─ 输入 key + 调 GET /api/admin/overview 验证
|
||||||
|
└─ 验证通过 → 写入 sessionStorage + 切到登录后视图
|
||||||
|
|
||||||
|
已登录
|
||||||
|
├─ 三个 tab: dashboard / voices / settings（hash 路由）
|
||||||
|
├─ 调任意 API 返 401 → 清 sessionStorage + 回到登录页
|
||||||
|
└─ 改完自己 auth_key → 调 PUT /api/settings/auth-key 200 后清 sessionStorage
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 状态机（setup.html）
|
||||||
|
|
||||||
|
```
|
||||||
|
未提交: 表单 4 必填 + voices 至少 1 条
|
||||||
|
└─ onMounted 调 GET /api/setup/prefill 自动填默认值
|
||||||
|
└─ 提交 POST /api/setup, 成功后 location.href = '/admin'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. API 契约（前端用的全部）
|
||||||
|
|
||||||
|
### 3.1 鉴权
|
||||||
|
|
||||||
|
| 头 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| `Authorization: Bearer <key>` | 所有 /api/* 请求必带（除 /api/setup/*）|
|
||||||
|
| 401 响应 | 清 sessionStorage `ttsAdminKey`, 回到登录页 |
|
||||||
|
|
||||||
|
**axios 实例已配置**:
|
||||||
|
```js
|
||||||
|
const http = axios.create({ baseURL: '/api' });
|
||||||
|
http.interceptors.request.use(c => {
|
||||||
|
if (apiKey.value) c.headers.Authorization = 'Bearer ' + apiKey.value;
|
||||||
|
return c;
|
||||||
|
});
|
||||||
|
http.interceptors.response.use(r => r, err => {
|
||||||
|
if (err.response && err.response.status === 401) {
|
||||||
|
sessionStorage.removeItem('ttsAdminKey');
|
||||||
|
apiKey.value = '';
|
||||||
|
}
|
||||||
|
return Promise.reject(err);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 端点
|
||||||
|
|
||||||
|
| Method | Path | 请求 body | 响应 | 鉴权 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| GET | `/api/setup/prefill` | — | `{ settings: {default_resource_id, default_speaker, default_format, sample_rate} }` | 否（仅 install 模式）|
|
||||||
|
| POST | `/api/setup` | `{token, settings: {auth_key, api_key, default_resource_id, default_speaker, default_format, sample_rate}, voices: [{name, speaker, resource_id, model, language}]}` | `{ok, redirect, settings, voices}` | 否（仅 install 模式）|
|
||||||
|
| GET | `/api/admin/overview` | — | `{mode, installed, db_path, lock_path, version, commit, uptime_seconds, start_time, voice_count, voice_enabled_count, memory: {goroutines, heap_alloc, heap_inuse}}` | 是 |
|
||||||
|
| GET | `/api/admin/metrics` | — | Prometheus text | 是 |
|
||||||
|
| GET | `/api/voices` | — | `{voices: [{ID, Name, Speaker, ResourceID, Model, Language, Description, Enabled, CreatedAt, UpdatedAt}]}` | 是 |
|
||||||
|
| POST | `/api/voices` | `{name, speaker, resource_id, model, language?, description?}` | 创建的 voice 对象 | 是 |
|
||||||
|
| DELETE | `/api/voices/{name}` | — | `{deleted, ok}` | 是 |
|
||||||
|
| PATCH | `/api/voices/{name}/toggle` | `{enabled: bool}` | 更新后的 voice | 是 |
|
||||||
|
| GET | `/api/settings` | — | 完整 settings 对象（见 3.3）| 是 |
|
||||||
|
| PUT | `/api/settings` | 部分字段（`default_resource_id` / `default_speaker` / `default_format` / `sample_rate` / `model`）| `{ok, updated, updated_at}` | 是 |
|
||||||
|
| PUT | `/api/settings/api-key` | `{api_key: string}` | `{ok}` | 是 |
|
||||||
|
| PUT | `/api/settings/auth-key` | `{auth_key: string}` | `{ok}` | 是 |
|
||||||
|
| PUT | `/api/settings/cors` | `{allow_all?: bool, origins?: string}` | `{ok, allow_all, origins, cors_active}` | 是 |
|
||||||
|
|
||||||
|
### 3.3 GET /api/settings 完整响应
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"api_key": "volc****etup", // 打码
|
||||||
|
"api_key_set": true,
|
||||||
|
"auth_key": "my-o****etup", // 打码
|
||||||
|
"auth_key_set": true,
|
||||||
|
"cors_allow_all": false,
|
||||||
|
"cors_origins": "https://app.example.com\nhttps://other.com",
|
||||||
|
"cors_configured": true, // banner 显示控制
|
||||||
|
"default_resource_id": "volc.megatts.icl",
|
||||||
|
"default_speaker": "qian",
|
||||||
|
"default_format": "mp3",
|
||||||
|
"sample_rate": 24000,
|
||||||
|
"model": "seed-tts-2.0-standard",
|
||||||
|
"model_type": 0,
|
||||||
|
"explicit_language": "",
|
||||||
|
"enable_subtitle": false,
|
||||||
|
"updated_at": "2026-08-29T16:07:49Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 错误响应格式
|
||||||
|
|
||||||
|
所有错误（除 OpenAI 兼容的 /v1/audio/speech）用同一格式:
|
||||||
|
```json
|
||||||
|
{ "error": { "code": "bad_request", "message": "...", "type": "invalid_request_error" } }
|
||||||
|
```
|
||||||
|
|
||||||
|
前端用 `e.response?.data?.error?.message` 提取.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 字段语义（写文案 / placeholder 用）
|
||||||
|
|
||||||
|
### 4.1 auth_key
|
||||||
|
"OpenAI 鉴权 Key"
|
||||||
|
- 客户端用这个 Key 调 `/v1/audio/speech`
|
||||||
|
- 登录 `/admin` 也用这个 Key
|
||||||
|
- 自定字符串, 不是火山给的, **完全自己造**
|
||||||
|
- 例: `my-secret-key-2024`
|
||||||
|
|
||||||
|
### 4.2 api_key
|
||||||
|
"火山 TTS API Key" / "上游 API Key"
|
||||||
|
- 调火山 v3 上游用的凭证
|
||||||
|
- 从 https://console.volcengine.com/ 获取
|
||||||
|
- 例: `5b4d7c2a-...`
|
||||||
|
|
||||||
|
### 4.3 default_resource_id
|
||||||
|
- 音色所属的计费资源 ID
|
||||||
|
- `volc.megatts.default` 默认音色 / `volc.megatts.icl` 复刻音色
|
||||||
|
|
||||||
|
### 4.4 default_speaker
|
||||||
|
- 未传 `voice` 字段时用
|
||||||
|
- 必须是"音色" tab 里已添加的 voice name
|
||||||
|
|
||||||
|
### 4.5 voices 字段
|
||||||
|
- `name`: 短英文 id, 唯一, 不可改
|
||||||
|
- `speaker`: 火山给的 speaker id
|
||||||
|
- `resource_id`: 同上 default_resource_id
|
||||||
|
- `model`: `seed-tts-2.0-standard` (默认) / `seed-tts-2.0-expressive` / `seed-tts-2.0-clone`
|
||||||
|
- `language`: ISO 639-1 (`zh` / `en` / `ja` 等)
|
||||||
|
|
||||||
|
### 4.6 CORS origins
|
||||||
|
- 一行一个 origin
|
||||||
|
- 必须 `http://` 或 `https://` 开头
|
||||||
|
- 末尾 `/` 自动 trim
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 当前 UI 的具体问题（按痛感排序）
|
||||||
|
|
||||||
|
### 5.1 admin.html
|
||||||
|
| # | 问题 | 现状 | 期望 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 1 | **登录页太空** | 一个输入框 + 一个按钮 | 加 logo / 提示 / 服务名 / 安装状态提示 |
|
||||||
|
| 2 | **dashboard 卡片平** | 4 个数字 + 路径文本, 无图标无图表 | 加 icon, 用 chart mini sparkline (uptime / memory)|
|
||||||
|
| 3 | **voices 表格简陋** | 5 列 + 启停 switch + 删除 | 加排序/搜索/批量操作/分页/拖拽改顺序 |
|
||||||
|
| 4 | **新增 voice 弹窗原始** | 6 个 input 堆叠 | 分组, 加 help text, 加示例值, 加实时校验 |
|
||||||
|
| 5 | **设置页 1 长页** | 4 段串成 1 长 list | 分 tab/分卡片, 加描述/帮助链接/危险操作分离 |
|
||||||
|
| 6 | **改 key 后无 feedback** | 改了直接清 session | 加 toast 通知 "Key 已更新, 请用新 Key 重新登录" |
|
||||||
|
| 7 | **删除无 undo** | confirm 弹原生 confirm() | 加 inline 二次确认 / undo snackbar |
|
||||||
|
| 8 | **loading 无** | 调 API 时按钮不变 | 加 spinner / disabled 状态 / 进度条 |
|
||||||
|
| 9 | **error 无专门显示区** | 用 `actionErr.value` 全局串 | 用 toast / inline error / 错误码对照 |
|
||||||
|
| 10 | **响应式差** | desktop only | 至少平板能用, 关键操作 (tab 切换) 移动端可点 |
|
||||||
|
| 11 | **配色单调** | 1 个 cyan 强调色 | 加二级色, success/warning/danger 用得不够明显 |
|
||||||
|
| 12 | **字体单薄** | 14px 全局 | 大字标题 24-32px, 重要数字 monospace 突出 |
|
||||||
|
|
||||||
|
### 5.2 setup.html
|
||||||
|
| # | 问题 | 现状 | 期望 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 1 | **4 字段加 voice 列表一锅烩** | 一长页 | 分步骤 (1.凭证 2.默认 3.音色 4.确认) |
|
||||||
|
| 2 | **voice 行无复用 UI** | 自己手写的 row | drag-to-reorder + 复制/粘贴/从预置模板加 |
|
||||||
|
| 3 | **无进度感** | 一个 "安装" 按钮 | 安装中显示进度 (写 settings → 写 voices → 写 lock) |
|
||||||
|
| 4 | **无"安装后会发生什么"** | 提交后只跳 /admin | 加结果页: 装了什么 / 接下来去 admin 干啥 |
|
||||||
|
| 5 | **无 reset** | 改了一锅填错没法批量重置 | "恢复默认值" 按钮 |
|
||||||
|
| 6 | **移动端糟糕** | 1 长页 | 至少 step indicator 在窄屏可见 |
|
||||||
|
|
||||||
|
### 5.3 共性问题
|
||||||
|
| # | 问题 | 期望 |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | 无 dark/light toggle | 加 toggle, 默认跟随系统 |
|
||||||
|
| 2 | 无键盘快捷键 | `/` 聚焦搜索, `Esc` 关弹窗, `Ctrl+S` 保存当前表单 |
|
||||||
|
| 3 | 无国际化 | 默认 zh-CN, 可加 i18n 但不强制 |
|
||||||
|
| 4 | 无 a11y 标签 | aria-label, focus ring, 键盘可达 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 设计参考（建议风格, 不是强制)
|
||||||
|
|
||||||
|
| 风格 | 适配场景 | 推荐度 |
|
||||||
|
|---|---|---|
|
||||||
|
| Linear / Vercel dashboard | 后台工具, dark mode 友好 | ⭐⭐⭐⭐⭐ |
|
||||||
|
| Tailscale admin | 简洁, 卡片化, 信息密度高 | ⭐⭐⭐⭐ |
|
||||||
|
| Coolify / CasaOS | 自托管, "家用服务器"感 | ⭐⭐⭐ |
|
||||||
|
| shadcn/ui | 现代 React 风, 移植到 Vue 略费劲 | ⭐⭐⭐ (参考设计, 不直接用) |
|
||||||
|
| Tailadmin | 通用 admin 模板, 选段借鉴 | ⭐⭐ |
|
||||||
|
|
||||||
|
**主调色建议** (如果重做):
|
||||||
|
- 背景: 深色 (`#0a0e1a`) 或浅色 (`#f8fafc`), 配 system pref
|
||||||
|
- 强调色: cyan / indigo / emerald 之一
|
||||||
|
- 字体: 标题用 Inter, 数字用 JetBrains Mono
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 不要做的事
|
||||||
|
|
||||||
|
- ❌ 改 API 路径 / 改字段名 / 改字段语义
|
||||||
|
- ❌ 加任何状态管理库 (Pinia) — 单文件 setup() 够用
|
||||||
|
- ❌ 加 webpack/vite — 必须保持单文件
|
||||||
|
- ❌ 引大 UI 库 (Element Plus / Naive UI) — 单文件塞不下
|
||||||
|
- ❌ 把 admin.html 和 setup.html 合并 — 它们是独立页面
|
||||||
|
- ❌ 改 axios 实例的 baseURL 或 401 拦截逻辑
|
||||||
|
- ❌ 改 hash 路由的 key 命名（`#dashboard` / `#voices` / `#settings`）
|
||||||
|
- ❌ **不要把单文件架构当最终形态** — 这是最小可工作版本(MVP),看板有 `ui-arch-debt` 卡片记录拆分计划。Codex 改造时保持单文件以便本次走通,但**不要引入新依赖让单文件更难拆**。例如:不要把 axios 拦截器写得依赖 10 个全局 ref;不要让 CSS 选择器深嵌套到无法抽离。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 验收清单（已按拆分后的结构更新）
|
||||||
|
|
||||||
|
改完回来, 我会逐项过:
|
||||||
|
|
||||||
|
- [ ] `go build ./...` 通过
|
||||||
|
- [ ] `go vet ./...` 通过
|
||||||
|
- [ ] `go test ./... -count=1` 全绿
|
||||||
|
- [ ] dev 起服后浏览器:
|
||||||
|
- [ ] `/setup` 流程能跑完
|
||||||
|
- [ ] `/admin` 登录 → dashboard → voices → settings → 增改删全通
|
||||||
|
- [ ] 改 auth_key 后自踢 → 重新登录 → 能用新 key
|
||||||
|
- [ ] CORS 未配时顶部 banner 出现, 配后消失
|
||||||
|
- [ ] 401 错误时自动跳回登录
|
||||||
|
- [ ] 视觉: 跟现在的 admin 比有明显提升 (logo / 排版 / 颜色 / 反馈)
|
||||||
|
- [ ] 至少在 1024px 宽度下好看
|
||||||
|
- [ ] 没有 console error / 404
|
||||||
|
- [ ] 新增页面复用了 `admin.css` + `admin-shell.js`,没有复制粘贴出第二套公共逻辑
|
||||||
|
|
||||||
|
> 旧的"`admin.html` ≤ 35KB / `setup.html` ≤ 15KB"两条**已作废**:admin 已拆成多页,
|
||||||
|
> 单文件大小不再是约束。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 回填方式（历史原文） / 当前做法
|
||||||
|
|
||||||
|
历史原文:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. 拿回 router/admin.html + router/setup.html
|
||||||
|
2. 放到 D:\项目\Volcano-Engine-TTS-UI\router\
|
||||||
|
3. 我 build + 测, 通过后 commit
|
||||||
|
4. push, 服务器自动部署
|
||||||
|
```
|
||||||
|
|
||||||
|
拆分之后的做法:改动落在 §0.1 表格里对应的**具体文件**上(外壳/登录/音色/设置,以及共享的
|
||||||
|
`admin.css` / `admin-shell.js`),不再有"两个 .html"这一说。改完在**项目里**跑:
|
||||||
|
|
||||||
|
```
|
||||||
|
go build ./...
|
||||||
|
go vet ./...
|
||||||
|
go test ./... -count=1
|
||||||
|
```
|
||||||
|
|
||||||
|
三条全过再 commit 到 `develop`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 关联文件（不需要改, 但可读懂逻辑）
|
||||||
|
|
||||||
|
- `controller/admin.go` — admin API 实现
|
||||||
|
- `controller/settings.go` — settings API 实现
|
||||||
|
- `controller/setup.go` — setup API 实现
|
||||||
|
- `router/router.go` — Go 路由 + 挂载点（看 `//go:embed` 用法）
|
||||||
|
- `router/admin-shell.js` — 共享 axios 实例 / toast / 外壳挂载（改交互先看这里）
|
||||||
|
- `middleware/admin_auth.go` — RequireAdmin 实现（理解 401 怎么来）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 当前文件位置（已更新）
|
||||||
|
|
||||||
|
| 文件 | 大小 |
|
||||||
|
|---|---|
|
||||||
|
| `router/admin.html` | 5.5KB |
|
||||||
|
| `router/admin-login.html` | 2.1KB |
|
||||||
|
| `router/admin-voices.html` | 13.5KB |
|
||||||
|
| `router/admin-settings.html` | 14.4KB |
|
||||||
|
| `router/admin.css` | 20.2KB |
|
||||||
|
| `router/admin-shell.js` | 7.1KB |
|
||||||
|
| `router/setup.html` | 24.0KB |
|
||||||
|
|
||||||
|
`ui-handoff/` 目录里保留的是**改造前**的单文件副本与离线 mock 预览,仅供对照,不要回填。
|
||||||
@@ -0,0 +1,493 @@
|
|||||||
|
# 上游适配器开发指南
|
||||||
|
|
||||||
|
> 面向对象:要为本项目接入**新上游 TTS 服务**的开发者(也包括未来的你)。
|
||||||
|
> 阅读前提:知道 OpenAI `/v1/audio/speech` 的请求/响应形状,能读 Go。
|
||||||
|
>
|
||||||
|
> ⚠️ **本文档分两部分,请先看清区别**:
|
||||||
|
> **第一部分「现状」描述的是代码里已经存在的东西**,可以直接照着读代码。
|
||||||
|
> **第二部分「目标架构」是待实施的设计**,代码里**还不存在** ——
|
||||||
|
> 里面的接口、表结构、目录都是提案,需要先按 §4 的分阶段计划落地。
|
||||||
|
> 不要把第二部分的接口名当成现有 API 去调用。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 愿景与现状
|
||||||
|
|
||||||
|
### 1.1 愿景
|
||||||
|
|
||||||
|
把本服务做成**多渠道多上游聚合层**:对外始终是一个 OpenAI 兼容接口,
|
||||||
|
对内可以挂火山、OpenAI、Azure、阿里云、自建 GPT-SoVITS / IndexTTS……等任意上游。
|
||||||
|
调用方不需要知道音频是哪个厂商合成的 —— 换上游对客户端应当**透明**。
|
||||||
|
|
||||||
|
### 1.2 现状(第一部分)
|
||||||
|
|
||||||
|
目前**只有火山一个适配器**,且不是"插件式"的,而是**硬编码进主干**的。
|
||||||
|
这一点必须说清楚,因为它决定了新上游不能"只写一个文件就完事"。
|
||||||
|
|
||||||
|
```
|
||||||
|
入口 controller/tts.go OpenaiTTSHandler
|
||||||
|
│
|
||||||
|
│ opts := setting.GetTTSOptions() ← 类型是 volcano.Options
|
||||||
|
│ volcano.Synthesis(ctx, volcanoClient, opts, ...) ← 直接调实现,无接口
|
||||||
|
▼
|
||||||
|
适配器 adapter/volcano/ Options / Synthesis / ParseStream / UpstreamError
|
||||||
|
▲
|
||||||
|
│ setting.LoadRuntimeConfig 直接构造 volcano.Options / volcano.Additions
|
||||||
|
配置 setting/config.go
|
||||||
|
```
|
||||||
|
|
||||||
|
**关键事实**:主干里有一处 `import "…/adapter/volcano"`,不是注解式的,
|
||||||
|
而是**类型级耦合**。所以"多上游"不是加文件,而是一次重构(见 §4)。
|
||||||
|
|
||||||
|
当前只有火山适配器时,以下代码是合理的;接第二个上游时必须逐个处理,
|
||||||
|
否则会出现"配置是火山的、路由是 OpenAI 的"这种错配。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 现有火山适配器契约(照此实现即可)
|
||||||
|
|
||||||
|
新适配器要能替代火山适配器,就必须满足下面这些**已经被主干依赖**的契约。
|
||||||
|
先读这一节,再读 §3 的接口设计。
|
||||||
|
|
||||||
|
### 2.1 包的职责划分
|
||||||
|
|
||||||
|
| 文件 | 职责 | 新适配器对应物 |
|
||||||
|
|---|---|---|
|
||||||
|
| `adapter/volcano/options.go` | 调用参数集合(`Options`)+ 上游扩展参数(`Additions`)+ `IsZero()` | provider 私有 opts |
|
||||||
|
| `adapter/volcano/request.go` | `Options` → 上游请求体;`buildRequest` 做必填校验;`convertSpeedToSpeechRate` 做 OpenAI speed 换算 | 请求构造 |
|
||||||
|
| `adapter/volcano/client.go` | 复用连接的 `*HTTPClient`(keep-alive 调优);`PostStream` 发流式请求 | 传输层 |
|
||||||
|
| `adapter/volcano/synthesis.go` | **唯一入口** `Synthesis(...)`;编排 埋点 → 构造 → 发送 → 解析 → 收尾 | `Synthesize(...)` |
|
||||||
|
| `adapter/volcano/response.go` | `ParseStream` 解析 NDJSON 流;`ParsedStream` 累计结果 | 响应解析 |
|
||||||
|
| `adapter/volcano/errors.go` | `UpstreamError{Code,Message,Stage,Wrapped}` + `IsAuth()` | 错误类型 |
|
||||||
|
| `adapter/volcano/audio.go` | `WrapWAVHeader` —— 上游只给 PCM 时本地拼标准 wav 头 | 格式收尾 |
|
||||||
|
|
||||||
|
### 2.2 主干对适配器的硬性依赖(必须逐条满足)
|
||||||
|
|
||||||
|
| # | 主干行为 | 位置 | 新适配器必须 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 1 | 用包级 `*HTTPClient` 发请求,连接复用 | `controller/tts.go:27,32` | 提供可复用的 client,不要每次 new |
|
||||||
|
| 2 | 可用 `ctx` 控制超时 | `controller/tts.go:203` | `Synthesize` 必须接受 `context.Context` |
|
||||||
|
| 3 | 埋点接口 **3 个方法** | `adapter/volcano/synthesis.go:20-24` | 见 §2.3 |
|
||||||
|
| 4 | 错误按 `Stage` 分类成 status label | `controller/tts.go:242-256` | 错误必须携带阶段:`request`/`http`/`stream`/`wrap` |
|
||||||
|
| 5 | 错误码进 metrics label | `metrics/metrics.go:160-172` | 非零 code 会被聚合成 `client`/`server`/`upstream` |
|
||||||
|
| 6 | 返回结果结构 | `dto.SynthesisResult` | 见 §2.4 |
|
||||||
|
| 7 | 上游不支持的输出格式要**降级** | `synthesis.go:63-65`、`README` 格式表 | 见 §2.5 |
|
||||||
|
|
||||||
|
### 2.3 埋点接口(MetricsRecorder)
|
||||||
|
|
||||||
|
适配器**不 import telemetry 包**,而是由主干注入一个接口实现
|
||||||
|
(`controller/tts.go:28` 注入 `metrics.AdapterRecorder{}`)。这是刻意的解耦,新适配器请沿用。
|
||||||
|
|
||||||
|
```go
|
||||||
|
type MetricsRecorder interface {
|
||||||
|
UpstreamStarted(speaker, model, format string)
|
||||||
|
UpstreamFinished(speaker, model, format, status string,
|
||||||
|
duration, ttfb time.Duration, chunks, audioBytes, errCode int)
|
||||||
|
UpstreamUsage(model string, textWords int)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
现状实现里 `speaker` 是**语料无关的上游音色 ID**,会被 `telemetry.SpeakerLabel`
|
||||||
|
做 `sha1[:8]` 哈希后才当 label(隐私保护,见 `metrics/metrics.go:127`)。
|
||||||
|
新适配器传自己的音色标识即可,主干不解释它的含义。
|
||||||
|
|
||||||
|
`status` 的取值约定(沿用即可,聚合看板依赖它们):
|
||||||
|
`ok` / `request_error` / `transport_error` / `http_<code>` / `stream_error` / `wrap_error`。
|
||||||
|
|
||||||
|
### 2.4 返回结果(dto.SynthesisResult)
|
||||||
|
|
||||||
|
```go
|
||||||
|
type SynthesisResult struct {
|
||||||
|
AudioData []byte // 最终可直接回给客户端的音频字节(已收尾,如 wav 拼好头)
|
||||||
|
Format string // 真实输出格式,决定 Content-Type
|
||||||
|
SampleRate int
|
||||||
|
ReqID string // 回写 X-Request-Id,排障用
|
||||||
|
TextWords int // 上游计费字符数(取不到填 0)
|
||||||
|
Chunks int
|
||||||
|
AudioBytes int
|
||||||
|
TTFB time.Duration // 首字节耗时
|
||||||
|
Duration time.Duration
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`Format` 必须是主干认识的取值(见 `controller/tts.go:258` `contentTypeFor`):
|
||||||
|
`mp3` / `wav` / `pcm` / `ogg_opus`(别名 `opus`)。填别的会导致 Content-Type 错。
|
||||||
|
|
||||||
|
### 2.5 格式降级规则(容易踩)
|
||||||
|
|
||||||
|
客户端要的 `response_format` 和上游能给的格式**往往不一致**,必须显式降级:
|
||||||
|
|
||||||
|
| 客户端要 | 火山做法 | 为什么 |
|
||||||
|
|---|---|---|
|
||||||
|
| `wav` | 上游请求 `pcm`,本地 `WrapWAVHeader` 拼头 | 流式 wav 每 chunk 带独立头,拼接即坏 |
|
||||||
|
| `aac` / `flac` | **降级成 mp3**,Content-Type 报 `audio/mpeg` | 火山不支持 |
|
||||||
|
| `opus` | 上游 `ogg_opus` | 命名差异 |
|
||||||
|
|
||||||
|
新适配器同样要回答这个问题:**你要的格式上游给不了时,降级到什么?**
|
||||||
|
并且必须在 `Format` 字段里如实回报真实格式,否则客户端拿到的是"声明 mp3 实际 pcm"。
|
||||||
|
|
||||||
|
### 2.6 实测踩过的坑(上游协议层面)
|
||||||
|
|
||||||
|
这些是火山适配器真实修过的 bug,接新上游时同类问题大概率复现:
|
||||||
|
|
||||||
|
1. **事件分发必须白名单**:`ParseStream` 只把 `event == "sentence"` 或事件为空的帧
|
||||||
|
当音频,未知事件只记日志**绝不拼进音频**(`response.go:71-113`)。
|
||||||
|
早期实现把 `TTSSubtitle` 也当音频,导致音频流被污染。
|
||||||
|
2. **结束帧要提前 break**:上游用 `code == 20000000` 表示流正常结束,收到后要
|
||||||
|
把剩余行读完再 break,否则连接不释放。
|
||||||
|
3. **单行可能很长**:`scanner.Buffer` 上限要放大(火山设到 8MB),否则大 chunk 会 EOF。
|
||||||
|
4. **所有音频帧 base64 解码失败要**返回错误,**不能跳过** —— 跳过等于静默产出半截音频。
|
||||||
|
5. **一个字节音频都没收到要报错**,不能返回空切片当成功(`response.go:125-131`)。
|
||||||
|
6. **错误响应体可能含换行**:直接拼进错误消息会伪造日志行,火山做了
|
||||||
|
`\n`/`\r` 转义(`synthesis.go:99-101`),新适配器照做。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 目标架构:Provider 抽象(待实施)
|
||||||
|
|
||||||
|
以下代码**当前不存在**,是建议落地的设计。
|
||||||
|
|
||||||
|
### 3.1 接口定义
|
||||||
|
|
||||||
|
建议新增 `adapter/provider/provider.go`(新包,**不放在** `adapter/volcano` 里,
|
||||||
|
避免主干继续依赖具体实现):
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Provider 是一个上游 TTS 服务的统一抽象。
|
||||||
|
// 实现者只需要关心:把我的能力说清楚、把一次合成做完。
|
||||||
|
type Provider interface {
|
||||||
|
// Name 稳定标识,用于配置键、库表字段、metrics label。
|
||||||
|
// 约定全小写无空格:volcano / openai / azure / aliyun / gpt-sovits。
|
||||||
|
Name() string
|
||||||
|
|
||||||
|
// Capabilities 声明本适配器支持什么。
|
||||||
|
// 主干据此做校验与降级,不靠 if-else 猜实现。
|
||||||
|
Capabilities() Capabilities
|
||||||
|
|
||||||
|
// Synthesize 执行一次合成,阻塞到完成。
|
||||||
|
// 必须遵守:ctx 取消即返回;上游不支持 clientFormat 时按 Capabilities 降级,
|
||||||
|
// 并在 Result.Format 里如实回报真实格式。
|
||||||
|
Synthesize(ctx context.Context, req Request, mtr MetricsRecorder) (*dto.SynthesisResult, error)
|
||||||
|
}
|
||||||
|
|
||||||
|
type Capabilities struct {
|
||||||
|
// 上游原生能产出的格式;客户端要的格式不在其中时,主干负责降级或拒绝。
|
||||||
|
Formats []string
|
||||||
|
// 是否支持用倍率控制语速。不支持时主干忽略 speed 而不是报错。
|
||||||
|
Speed bool
|
||||||
|
// 是否按字符计费并回传用量(决定 UpstreamUsage 是否有意义)。
|
||||||
|
Usage bool
|
||||||
|
// 是否支持多音色路由。不支持时该 provider 只能配一个默认音色。
|
||||||
|
Voices bool
|
||||||
|
// 是否需要资源/部署/项目 ID 这类额外维度(火山需要,OpenAI 不需要)。
|
||||||
|
ExtraScopes bool
|
||||||
|
}
|
||||||
|
|
||||||
|
// Request 是主干交给适配器的、已归一化的合成请求。
|
||||||
|
// 注意:这里刻意不出现任何厂商专属字段。
|
||||||
|
type Request struct {
|
||||||
|
Text string
|
||||||
|
VoiceKey string // voices 表的主键语义(对外 voice 名或上游音色 ID)
|
||||||
|
Model string
|
||||||
|
Format string // 客户端期望格式(主干已归一化:mp3/wav/pcm/ogg_opus)
|
||||||
|
SampleRate int
|
||||||
|
Speed float64 // 1.0 = 原速
|
||||||
|
Language string
|
||||||
|
Extra map[string]string // 厂商专属配置,从 voices/settings 的 JSON 列读
|
||||||
|
|
||||||
|
// Credentials 由 provider 自己解释:
|
||||||
|
// 火山读 api_key + resource_id;OpenAI 只读 api_key。
|
||||||
|
Credentials Credentials
|
||||||
|
}
|
||||||
|
|
||||||
|
type Credentials struct {
|
||||||
|
APIKey string
|
||||||
|
// 厂商额外凭证/路由维度。火山: resource_id;Azure: region;自建: base_url。
|
||||||
|
Scope map[string]string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 注册表
|
||||||
|
|
||||||
|
```go
|
||||||
|
// adapter/provider/registry.go
|
||||||
|
func Register(p Provider) // 通常在包的 init() 里调用
|
||||||
|
func Get(name string) (Provider, bool)
|
||||||
|
func Names() []string // admin UI 下拉框用
|
||||||
|
```
|
||||||
|
|
||||||
|
**要点**:注册要放在**主干之外**。建议 `main.go` 显式空导入:
|
||||||
|
|
||||||
|
```go
|
||||||
|
import (
|
||||||
|
_ "github.com/volcano-tts/tts-api/adapter/volcano" // 注册 volcano
|
||||||
|
_ "github.com/volcano-tts/tts-api/adapter/openai" // 注册 openai
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
这样主干只依赖 `provider` 包,**新增上游不需要改主干任何一行** —— 这是本架构的核心收益,
|
||||||
|
请务必守住。`controller/tts.go` 里不应再出现 `adapter/volcano`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 分阶段实施计划
|
||||||
|
|
||||||
|
**强烈建议按阶段做,每阶段结束都能编译、能跑、行为不变。**
|
||||||
|
一次性重构"配置 + 路由 + 库表 + 前端 + metrics"五个面,几乎必然做出半成品。
|
||||||
|
|
||||||
|
### 阶段 0 · 抽出接口,零行为变更(纯重构)
|
||||||
|
|
||||||
|
目标:主干不再依赖具体实现,但**行为完全不变**,回归风险最低。
|
||||||
|
|
||||||
|
- [ ] 新增 `adapter/provider` 包,放 `Provider` / `Capabilities` / `Request` / `Credentials` / `MetricsRecorder`
|
||||||
|
- [ ] 让 `volcano` 包实现 `Provider`(本质是把 `Options` 包一层适配,`Synthesis` 改成方法)
|
||||||
|
- [ ] `controller/tts.go`:把 `volcanoClient` + `volcano.Synthesis` 换成 `provider.Get(name).Synthesize`
|
||||||
|
- [ ] `MetricsRecorder` 从 `adapter/volcano` **移出**到 `provider` 包(否则接口还是火山专属)
|
||||||
|
- [ ] `setting.LoadRuntimeConfig` 暂时继续构造 `volcano.Options`,通过一个
|
||||||
|
「volcano provider 的配置映射函数」转成 `provider.Request`
|
||||||
|
- [ ] 验收:`go build ./... && go vet ./... && go test ./... -count=1` 全绿,
|
||||||
|
且 `/v1/audio/speech` 行为与重构前逐字节一致(拿同一段文本对比音频长度与格式)
|
||||||
|
|
||||||
|
> 这一阶段**不要**动库表、不要动前端。目标只有一个:主干里那行
|
||||||
|
> `import adapter/volcano` 消失。
|
||||||
|
|
||||||
|
### 阶段 1 · 数据结构:provider 维度入库
|
||||||
|
|
||||||
|
> ⚠️ **先纠正一个常见误解:本项目的迁移框架其实没有接线。**
|
||||||
|
> `store/migrate.go` 里定义了 `Migration` 结构体和 `migrations` 切片,但那个切片是
|
||||||
|
> **空的**,`store/db.go` 的 `migrate()` 也从**不**读取它 —— 注释里写得很明白:
|
||||||
|
> "本期 M0 阶段 schemaVersion=1,migrate() 在 db.go 内做基础建表,**未触发 migrations 调度**"。
|
||||||
|
> 所以 `migrate()` 目前**只做 `CREATE TABLE IF NOT EXISTS`**,没有任何版本比较,
|
||||||
|
> 对已存在的表**完全不做变更**。
|
||||||
|
>
|
||||||
|
> 还有一个既有瑕疵:`db.go:148-150` 的 `INSERT OR IGNORE INTO schema_version (version) VALUES (?)`
|
||||||
|
> 语句里既没有字面量也没传参,绑定到 `?` 的是**零值**,所以表里实际写入的版本号是 **0**,
|
||||||
|
> 不是常量 `schemaVersion`(=1)。做 v2 迁移时请一并修掉,否则版本判断从一开始就是错的。
|
||||||
|
>
|
||||||
|
> **结论**:给 `voices` 加列**不会**自动发生,你必须自己写 `ALTER TABLE`,
|
||||||
|
> 并且在启动时能被重复执行而不报错(老库、新库都要能跑)。
|
||||||
|
|
||||||
|
本阶段要做:
|
||||||
|
|
||||||
|
- [ ] 在 `migrate()`(或新启用的迁移调度)里实现**幂等**加列:
|
||||||
|
先 `PRAGMA table_info(voices)` 查现有列,缺哪个 `ALTER TABLE ... ADD COLUMN` 哪个
|
||||||
|
(SQLite 的 `ADD COLUMN` 不支持 `IF NOT EXISTS`,重复执行会报错,必须先查)
|
||||||
|
- [ ] `voices` 表加列(见 §5.1),老库回填 `provider='volcano'`
|
||||||
|
- [ ] 修正 `schema_version` 写入零值的瑕疵,并写出真实版本号
|
||||||
|
- [ ] 若确实要启用 `migrate.go` 的调度框架,则把 `schemaVersion`(db.go,`=1`)
|
||||||
|
与 `schemaVersionRequested`(migrate.go,`=1`)一并提升到 2;
|
||||||
|
注意 `installer/lock.go` 里的 `schemaVersion = "1"`(字符串)**是另一套东西**——
|
||||||
|
它写在 `installed.lock` 里做安装标记,与库表结构版本是两回事,
|
||||||
|
两者要一起提升就一起提升,不要只改一边造成语义分裂
|
||||||
|
- [ ] `store.Voice` 结构体加字段 + JSON tag
|
||||||
|
- [ ] `store.GetVoiceForTTS` 返回值扩展(见 §5.2),`setting.Store` 接口同步改
|
||||||
|
- [ ] `cmd/dumpdb` 输出新列
|
||||||
|
- [ ] 验收:**用一个装了老数据的 `tts.db`** 启动服务(不要用全新库测),
|
||||||
|
确认自动加列成功、数据不丢、`/v1/audio/speech` 仍可用;
|
||||||
|
再重启一次确认迁移幂等(第二次不报错)
|
||||||
|
|
||||||
|
### 阶段 2 · 配置:按 provider 命名空间化
|
||||||
|
|
||||||
|
现状是 `settings` 表用**扁平键**,且键名全是火山语义(`default_resource_id`、
|
||||||
|
`default_speaker`、`model_type`…)。多上游后必须命名空间化。
|
||||||
|
|
||||||
|
- [ ] 保留全局键:`auth_key` / `cors_*` / `timeout` / `default_provider`
|
||||||
|
- [ ] 厂商专属键改为 `provider.<name>.<key>`,例如
|
||||||
|
`provider.volcano.api_key`、`provider.volcano.resource_id`、
|
||||||
|
`provider.openai.api_key`、`provider.openai.base_url`
|
||||||
|
- [ ] `LoadRuntimeConfig` 只装配**当前 `default_provider`** 的 `Request`,
|
||||||
|
不再构造 `volcano.Options`
|
||||||
|
- [ ] `setting.CheckEnvironmentVariables` / `LogStartupSummary` 去掉
|
||||||
|
`BYTEDANCE_TTS_*` 硬编码名,改成遍历 provider 的必填项(否则 `/health` 会误导运维)
|
||||||
|
- [ ] 迁移:老键 `api_key` → `provider.volcano.api_key` 等,一次性搬完并保留旧键只读兜底一轮
|
||||||
|
- [ ] 验收:除火山外没有任何 provider 时,服务行为仍与阶段 1 相同
|
||||||
|
|
||||||
|
### 阶段 3 · 观测:metrics 加 provider 维度
|
||||||
|
|
||||||
|
- [ ] `tts_upstream_total` / `tts_upstream_duration_seconds` / `tts_upstream_errors_total`
|
||||||
|
等**全部上游指标加 `provider` label**
|
||||||
|
- [ ] `metrics.AdapterRecorder` 增加 provider 字段(构造时注入 name)
|
||||||
|
- [ ] 仪表盘 PromQL 补 `by (provider)`
|
||||||
|
- [ ] ⚠️ **破坏性变更**:加 label 会让现有告警规则里的
|
||||||
|
`tts_upstream_total{...}` 聚合口径变化,发布说明里要写明
|
||||||
|
- [ ] 验收:`/metrics` 上能按 provider 拆分成功率与 P95
|
||||||
|
|
||||||
|
### 阶段 4 · 管理界面:provider 选择与音色归属
|
||||||
|
|
||||||
|
- [ ] `/setup` 向导第 1 步加"上游类型"选择,后续步骤按所选 provider 动态渲染字段
|
||||||
|
(火山显示 resource_id,**OpenAI 显示 base_url 且不显示 resource_id**)
|
||||||
|
- [ ] `router/admin-voices.html` 新增/编辑音色时选 provider 与 model
|
||||||
|
- [ ] `/api/voices` 的请求/响应加 `provider` 字段,`controller/admin.go` 校验
|
||||||
|
"provider 必须已注册",否则 400(不要留到合成时才 500)
|
||||||
|
- [ ] 删除 provider 最后一个音色时的保护逻辑(现在的 `ErrInUse` 只管 `default_speaker`)
|
||||||
|
- [ ] 验收:UI 上能并存火山与 OpenAI 音色,各自路由正确
|
||||||
|
|
||||||
|
### 阶段 5 · 第二个真实适配器(OpenAI 兼容)
|
||||||
|
|
||||||
|
**这一步才是对抽象的真正验收**。选 OpenAI 兼容上游(或其代理)最省事,因为
|
||||||
|
本项目对外就是 OpenAI 形状 —— 可以直接验证"请求/响应穿透"是否正确。
|
||||||
|
|
||||||
|
- [ ] 新建 `adapter/openai/`,只实现 §3.1 的接口
|
||||||
|
- [ ] 全程**不改** `controller/` `setting/` `store/` 任何一行
|
||||||
|
- [ ] 如果为了实现它而必须改主干,说明 §3.1 的抽象漏了维度 —— **回头修接口,而不是打补丁**
|
||||||
|
- [ ] 验收:同一份 `voices` 配置里两个 provider 可同时服务,
|
||||||
|
客户端只看到 `voice` 名不同
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 数据模型改动细节
|
||||||
|
|
||||||
|
### 5.1 voices 表
|
||||||
|
|
||||||
|
现状(真实 schema,`store/db.go:129-142`):
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS voices (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
name TEXT NOT NULL UNIQUE,
|
||||||
|
speaker TEXT NOT NULL, -- 上游音色 ID
|
||||||
|
resource_id TEXT NOT NULL, -- ← 火山专属概念,却写成 NOT NULL 通用列
|
||||||
|
model TEXT DEFAULT '',
|
||||||
|
language TEXT DEFAULT '',
|
||||||
|
description TEXT DEFAULT '',
|
||||||
|
enabled INTEGER NOT NULL DEFAULT 1,
|
||||||
|
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||||||
|
updated_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**问题**:`resource_id` 是火山独有概念(决定模型版本与计费),却成了全表必填列。
|
||||||
|
OpenAI 上游根本没有这个字段 —— 这正是"单上游假设"渗进数据模型的典型症状。
|
||||||
|
|
||||||
|
建议改为:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
ALTER TABLE voices ADD COLUMN provider TEXT NOT NULL DEFAULT 'volcano';
|
||||||
|
ALTER TABLE voices ADD COLUMN vendor_params TEXT NOT NULL DEFAULT '{}'; -- JSON,厂商私有
|
||||||
|
-- resource_id 保留但放宽为可空(或整体搬进 vendor_params,看迁移成本)
|
||||||
|
```
|
||||||
|
|
||||||
|
- `provider` 建索引:`CREATE INDEX idx_voices_provider ON voices(provider)`
|
||||||
|
- `vendor_params` 存厂商私有键值(火山:`{"resource_id":"seed-icl-2.0","model_type":4}`),
|
||||||
|
主干**不解释**它的内容,原样交给对应 provider
|
||||||
|
- 迁移:`UPDATE voices SET provider='volcano' WHERE provider IS NULL OR provider=''`
|
||||||
|
|
||||||
|
### 5.2 GetVoiceForTTS 的签名
|
||||||
|
|
||||||
|
现状(`setting/config.go:426-436`,刻意用 5 个返回值避免循环 import):
|
||||||
|
|
||||||
|
```go
|
||||||
|
GetVoiceForTTS(name string) (speaker, resourceID, model string, found bool, err error)
|
||||||
|
```
|
||||||
|
|
||||||
|
多上游后要扩成:
|
||||||
|
|
||||||
|
```go
|
||||||
|
// 返回该 voice 的 provider 名 + 厂商私有参数,主干据此把请求路由给对应适配器。
|
||||||
|
GetVoiceForTTS(name string) (providerName, speakerID, model string, vendorParams map[string]string, found bool, err error)
|
||||||
|
```
|
||||||
|
|
||||||
|
**注意**:当年之所以不用 `(VoiceRef, error)`,是为了让 `store` 不 import `setting`
|
||||||
|
(避免循环 import)。加字段时**别再引入新的结构体依赖**,继续用扁平返回值或
|
||||||
|
定义在 `store` 包里的中性结构体。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 新增一个适配器的完整清单
|
||||||
|
|
||||||
|
假设要加 `foo` 上游:
|
||||||
|
|
||||||
|
**代码**
|
||||||
|
|
||||||
|
1. `adapter/foo/foo.go` —— 实现 `provider.Provider`(`Name()` 返回 `"foo"`)
|
||||||
|
2. `adapter/foo/request.go` —— `provider.Request` → foo 的 HTTP 请求体
|
||||||
|
3. `adapter/foo/response.go` —— 解析 foo 的响应;严格遵守 §2.6 的 6 条协议纪律
|
||||||
|
4. `adapter/foo/errors.go` —— 错误要带阶段,`Stage` 用统一枚举
|
||||||
|
5. `adapter/foo/foo_test.go` —— 至少覆盖:正常流、未知事件不污染音频、空音频报错、
|
||||||
|
base64 解码失败报错、格式降级回报正确 `Format`、`ctx` 取消能及时返回
|
||||||
|
(测试文件按项目策略不入库,本地保留并在合并前手动跑)
|
||||||
|
6. 在 `foo.go` 的 `init()` 里 `provider.Register(...)`
|
||||||
|
7. `main.go` 加一行空导入
|
||||||
|
|
||||||
|
**配置**
|
||||||
|
|
||||||
|
8. 定义必填项清单(供 `/health` 与启动摘要显示),不要写死在前端
|
||||||
|
9. 在 `/setup` 向导里加该 provider 的字段定义(阶段 4 之后是数据驱动,只需加配置)
|
||||||
|
|
||||||
|
**验收**
|
||||||
|
|
||||||
|
10. `go build ./... && go vet ./... && go test ./... -count=1` 全绿
|
||||||
|
11. 起服 → `/setup` 选 foo → 填凭证 → 加一个音色 → `curl /v1/audio/speech` 出声
|
||||||
|
12. 故意填错凭证 → 客户端应拿到明确的 4xx/5xx 与 `code`,日志里凭证是**打码**的
|
||||||
|
13. 不支持的 `response_format` → 按 `Capabilities` 降级,且 Content-Type 与真实字节一致
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 测试策略(注意本项目的特殊约束)
|
||||||
|
|
||||||
|
**本项目测试文件不入库**(`.gitignore` 里的 `*_test.go`),
|
||||||
|
测试保留在本地磁盘。这带来两个直接后果,必须知道:
|
||||||
|
|
||||||
|
1. **CI 跑不到你的测试**。`.github/workflows/ci.yml` 里的 `go test` 步骤在干净克隆上
|
||||||
|
只会打印 `no test files` 然后通过 —— 它只能守住"编译 + vet"。
|
||||||
|
所以适配器测试**必须在本地跑过再合并**:
|
||||||
|
```bash
|
||||||
|
go test ./... -count=1
|
||||||
|
```
|
||||||
|
2. **不要依赖测试文件来传递知识**。协议细节、踩坑记录要写进**代码注释**和本文档,
|
||||||
|
否则对下一个人(以及在 CI 里)等于不存在。
|
||||||
|
|
||||||
|
适配器测试的**最小可用集合**(按 §2.6 的坑逐条覆盖):
|
||||||
|
|
||||||
|
| 用例 | 断言 |
|
||||||
|
|---|---|
|
||||||
|
| 正常流 | 音频字节非空;`Chunks` / `TTFB` / `Format` 合理 |
|
||||||
|
| 未知事件帧 | 不进入音频;不报错;不改变 `Chunks` |
|
||||||
|
| 字幕帧 | 进 `Subtitles`,**不进** `AudioData` |
|
||||||
|
| 全流无音频 | 返回错误,不是"成功 + 空字节" |
|
||||||
|
| base64 损坏 | 返回错误,不是跳过继续 |
|
||||||
|
| 超长单行(>1MB) | 不 EOF |
|
||||||
|
| 上游 HTTP 4xx/5xx | 错误 `Stage == "http"`,携带 code |
|
||||||
|
| `ctx` 取消 | 及时返回,不泄漏 goroutine |
|
||||||
|
| 格式降级 | `Result.Format` 是真实格式,不是客户端要的格式 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 反模式清单(明确不要做)
|
||||||
|
|
||||||
|
- ❌ **不要在 `controller/` 里写 `switch providerName` 分发**。
|
||||||
|
分发只能走注册表,否则每加一个上游都要改主干,抽象就白做了。
|
||||||
|
- ❌ **不要让 `provider` 包 import 任何具体适配器**。依赖方向永远是
|
||||||
|
`具体适配器 → provider 包 ← 主干`。
|
||||||
|
- ❌ **不要在 `provider.Request` 里加厂商专属字段**(如 `ResourceID`)。
|
||||||
|
厂商私有参数一律走 `Credentials.Scope` / `Request.Extra` / `voices.vendor_params`。
|
||||||
|
- ❌ **不要把上游返回的原始音频直接当结果返回而不收尾**。
|
||||||
|
PCM 要拼头,降级要如实回报 `Format`(见 §2.5)。
|
||||||
|
- ❌ **不要静默跳过解析失败的帧**(§2.6 第 4 条)。
|
||||||
|
- ❌ **不要在日志里打印明文凭证或音色 ID**。沿用
|
||||||
|
`telemetry.MaskSpeaker` / `MaskResourceID`,新适配器的私有敏感字段也要加等价打码。
|
||||||
|
- ❌ **不要用一个 `settings` 键名承载多个 provider 的配置**。
|
||||||
|
- ❌ **不要为了省事把 provider 名写进 `settings` 的扁平键里当"事实上的路由"**,
|
||||||
|
路由的唯一权威是 `voices.provider` 与 `default_provider`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 关键文件索引
|
||||||
|
|
||||||
|
| 关注点 | 文件 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| 请求入口 / 校验 / 路由 | `controller/tts.go` | `resolveClientFormat`、voice 查库、错误归一 |
|
||||||
|
| 合成编排参考实现 | `adapter/volcano/synthesis.go` | 埋点顺序、格式降级、错误分阶段 |
|
||||||
|
| 流解析参考实现 | `adapter/volcano/response.go` | 事件白名单、结束帧、base64 |
|
||||||
|
| 传输层参考实现 | `adapter/volcano/client.go` | 连接复用、nil 安全 |
|
||||||
|
| 配置装配 | `setting/config.go` | `LoadRuntimeConfig`、`setting.Store` 接口 |
|
||||||
|
| 库表与迁移 | `store/db.go`、`store/migrate.go` | `schemaVersion`、`migrate()`(**迁移框架未接线,见阶段 1 警示**);`installer/lock.go` 的 `schemaVersion` 是另一套 |
|
||||||
|
| 音色模型 | `store/voices.go` | `Voice`、`GetVoiceForTTS` |
|
||||||
|
| 指标 | `metrics/metrics.go` | `AdapterRecorder`、`codeLabel` |
|
||||||
|
| 结果类型 | `dto/tts.go` | `SynthesisResult`、`SubtitleEntry` |
|
||||||
|
| 未来抽象落点 | `adapter/provider/` | **尚不存在,待阶段 0 创建** |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*文档版本:v1 · 对应代码基线:`develop` @ `ad342ec`(2026-10-03)*
|
||||||
|
*本文「现状」部分与代码逐行核对过;「目标架构」为提案,实施时请同步更新本文档。*
|
||||||
@@ -35,6 +35,8 @@ func main() {
|
|||||||
setting.InitAllConfigs()
|
setting.InitAllConfigs()
|
||||||
metrics.Init()
|
metrics.Init()
|
||||||
middleware.InitRateLimiter()
|
middleware.InitRateLimiter()
|
||||||
|
// v0.3.0:根路径 /metrics 的内网白名单(未配置则根路径完全不注册)
|
||||||
|
middleware.InitMetricsAllowList()
|
||||||
|
|
||||||
// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
|
// 2) 启动期关键步骤:打开/建库 → 检测 lock → 判定模式
|
||||||
dbPath := ttsDBPath()
|
dbPath := ttsDBPath()
|
||||||
@@ -85,6 +87,21 @@ func main() {
|
|||||||
|
|
||||||
// 5) 启动摘要日志(此时 Auth.APIKeys 已是 DB 值,日志反映真实状态)
|
// 5) 启动摘要日志(此时 Auth.APIKeys 已是 DB 值,日志反映真实状态)
|
||||||
setting.LogStartupSummary()
|
setting.LogStartupSummary()
|
||||||
|
|
||||||
|
// 5.1) v0.3.0 前置校验:normal 模式下必须有管理凭证。
|
||||||
|
// 为什么 fail-fast 而不是警告:mware.RequireAdmin 在凭证为空时**拒绝**访问
|
||||||
|
// (不再像 v0.3.0 之前那样放行)。若此处不拦住,服务会正常起来,
|
||||||
|
// 但 /dashboard 与所有 /api/admin/* 全部 401 —— 相当于把自己锁在门外。
|
||||||
|
// 宁可启动失败并打印明确原因,也不要起来一个进不去后台的实例。
|
||||||
|
if installer.GetMode() == installer.ModeNormal && len(setting.GetAdminKeys()) == 0 {
|
||||||
|
log.Printf("[main][FATAL] normal 模式未配置任何管理凭证:admin_key / auth_key / OPENAI_TTS_API_KEY 均为空。")
|
||||||
|
log.Printf("[main][FATAL] 管理接口(含 /dashboard)将全部返回 401,服务拒绝启动。")
|
||||||
|
log.Fatalf("no admin credential configured; set admin_key (or auth_key) before starting in normal mode")
|
||||||
|
}
|
||||||
|
if installer.GetMode() == installer.ModeNormal {
|
||||||
|
log.Printf("[main] 管理凭证来源: %s", setting.GetAdminKeySource())
|
||||||
|
}
|
||||||
|
|
||||||
log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
|
log.Printf("[main] 当前模式: %s (db=%s lock=%s)", res.Mode, dbPath, res.LockPath)
|
||||||
|
|
||||||
controller.InitController()
|
controller.InitController()
|
||||||
@@ -113,8 +130,13 @@ func main() {
|
|||||||
log.Printf("OpenAI TTS endpoint: http://localhost:%s/v1/audio/speech", setting.Server.Port)
|
log.Printf("OpenAI TTS endpoint: http://localhost:%s/v1/audio/speech", setting.Server.Port)
|
||||||
log.Printf("Admin WebUI: http://localhost:%s/admin", setting.Server.Port)
|
log.Printf("Admin WebUI: http://localhost:%s/admin", setting.Server.Port)
|
||||||
}
|
}
|
||||||
log.Printf("Health check: http://localhost:%s/health", setting.Server.Port)
|
log.Printf("Health check(匿名存活探针): http://localhost:%s/healthz", setting.Server.Port)
|
||||||
log.Printf("Metrics: http://localhost:%s/metrics", setting.Server.Port)
|
if middleware.MetricsAllowListConfigured() {
|
||||||
|
log.Printf("Metrics(内网白名单): http://localhost:%s/metrics", setting.Server.Port)
|
||||||
|
} else {
|
||||||
|
log.Printf("Metrics: 根路径 /metrics 未注册(未配置 METRICS_ALLOW_CIDR);请用鉴权版 /api/admin/metrics")
|
||||||
|
}
|
||||||
|
log.Printf("详细健康数据(鉴权): http://localhost:%s/api/admin/health", setting.Server.Port)
|
||||||
|
|
||||||
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
|
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
|
||||||
log.Fatalf("Server failed to start: %v", err)
|
log.Fatalf("Server failed to start: %v", err)
|
||||||
|
|||||||
+17
-10
@@ -9,14 +9,19 @@ import (
|
|||||||
"github.com/volcano-tts/tts-api/setting"
|
"github.com/volcano-tts/tts-api/setting"
|
||||||
)
|
)
|
||||||
|
|
||||||
// RequireAdmin 是 /admin 路由的鉴权中间件,复用 OPENAI_TTS_API_KEY。
|
// RequireAdmin 是管理接口(/api/admin/*、/api/voices*、/api/settings*)的鉴权中间件。
|
||||||
// 行为:
|
|
||||||
// - Auth.APIKeys 为空 → 所有请求放行(等同无鉴权)
|
|
||||||
// - Authorization 头 Bearer token 在列表中 → 放行
|
|
||||||
// - 其它 → 401 + JSON {error: 'unauthorized', code: 'admin_auth_failed'}
|
|
||||||
//
|
//
|
||||||
// 设计: 与现有 /v1/audio/speech 用的鉴权 key 列表(setting.GetAuthAPIKeys)共享同一份 keys,
|
// 凭证来源:setting.GetAdminKeys(),优先级 admin_key(DB) > auth_key(DB) > OPENAI_TTS_API_KEY(env)。
|
||||||
// 用户只用管一个 env 变量(OPENAI_TTS_API_KEY)。
|
// 与业务侧鉴权(middleware.ValidateAPIKey,只看 auth_key)分离,实现权限隔离:
|
||||||
|
// 配置了独立 admin_key 后,业务调用方持有的 key 无法访问管理接口。
|
||||||
|
//
|
||||||
|
// 行为:
|
||||||
|
// - OPTIONS 预检 → 放行(浏览器预检不带 Authorization)
|
||||||
|
// - 未配置任何凭证 → **拒绝**(401)。这是刻意设计:v0.3.0 之前这里直接放行,
|
||||||
|
// 导致管理接口在"没配 key"的部署上完全裸奔,并让后续给 /metrics、/health
|
||||||
|
// 套本中间件的加固形同虚设。启动期已由 main.go 做 fail-fast 校验。
|
||||||
|
// - Authorization 头 Bearer token 命中凭证列表 → 放行
|
||||||
|
// - 其它 → 401 + JSON {error: {code: 'admin_auth_failed'}}
|
||||||
func RequireAdmin(next http.Handler) http.Handler {
|
func RequireAdmin(next http.Handler) http.Handler {
|
||||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
// 预检: 跨域/OPTIONS 直接放行(让浏览器能发 preflight)
|
// 预检: 跨域/OPTIONS 直接放行(让浏览器能发 preflight)
|
||||||
@@ -25,10 +30,12 @@ func RequireAdmin(next http.Handler) http.Handler {
|
|||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
keys := setting.GetAuthAPIKeys()
|
keys := setting.GetAdminKeys()
|
||||||
if len(keys) == 0 {
|
if len(keys) == 0 {
|
||||||
// 没配 admin key,等同无鉴权
|
// 没配管理凭证 → 拒绝(旧行为是放行,见上方注释说明为何改掉)
|
||||||
next.ServeHTTP(w, r)
|
log.Printf("[admin_auth] 拒绝:未配置管理凭证(admin_key/auth_key/OPENAI_TTS_API_KEY 均为空) - 路径=%s 客户端=%s",
|
||||||
|
r.URL.Path, GetClientIP(r))
|
||||||
|
denyAdmin(w, r)
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,138 @@
|
|||||||
|
package middleware
|
||||||
|
|
||||||
|
import (
|
||||||
|
"net/http"
|
||||||
|
"net/http/httptest"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
"github.com/volcano-tts/tts-api/setting"
|
||||||
|
)
|
||||||
|
|
||||||
|
// okHandler 是被保护的假 handler。
|
||||||
|
func okHandler() http.Handler {
|
||||||
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
w.WriteHeader(http.StatusOK)
|
||||||
|
_, _ = w.Write([]byte("ok"))
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestRequireAdmin_EmptyCredentialDenies 凭证未配置时必须拒绝,不能放行。
|
||||||
|
//
|
||||||
|
// 这是 v0.3.0 阶段 1 的核心修复:v0.3.0 之前 len(keys)==0 直接放行,
|
||||||
|
// 导致"没配 key"的部署上管理接口完全裸奔,也让后续给 /metrics、/health
|
||||||
|
// 套 RequireAdmin 的加固形同虚设。
|
||||||
|
func TestRequireAdmin_EmptyCredentialDenies(t *testing.T) {
|
||||||
|
t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
|
||||||
|
setting.SetAdminKeys(nil, "")
|
||||||
|
|
||||||
|
h := RequireAdmin(okHandler())
|
||||||
|
|
||||||
|
// 完全不带 Authorization
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w, httptest.NewRequest("GET", "/api/admin/overview", nil))
|
||||||
|
if w.Code != http.StatusUnauthorized {
|
||||||
|
t.Errorf("无凭证 + 未配置 admin credential: code=%d, want 401", w.Code)
|
||||||
|
}
|
||||||
|
|
||||||
|
// 带任意 Bearer token 也必须拒绝(列表为空,没有合法 token 可言)
|
||||||
|
w2 := httptest.NewRecorder()
|
||||||
|
r2 := httptest.NewRequest("GET", "/api/admin/overview", nil)
|
||||||
|
r2.Header.Set("Authorization", "Bearer anything")
|
||||||
|
h.ServeHTTP(w2, r2)
|
||||||
|
if w2.Code != http.StatusUnauthorized {
|
||||||
|
t.Errorf("任意 token + 未配置 admin credential: code=%d, want 401", w2.Code)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestRequireAdmin_ConfiguredCredentialEnforced 配了凭证后:命中放行、错误拒绝。
|
||||||
|
func TestRequireAdmin_ConfiguredCredentialEnforced(t *testing.T) {
|
||||||
|
t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
|
||||||
|
setting.SetAdminKeys([]string{"admin-secret"}, "admin_key")
|
||||||
|
|
||||||
|
h := RequireAdmin(okHandler())
|
||||||
|
|
||||||
|
cases := []struct {
|
||||||
|
name string
|
||||||
|
authHeader string
|
||||||
|
wantStatus int
|
||||||
|
}{
|
||||||
|
{"正确凭证", "Bearer admin-secret", http.StatusOK},
|
||||||
|
{"错误凭证", "Bearer wrong-secret", http.StatusUnauthorized},
|
||||||
|
{"缺少 Bearer 前缀", "admin-secret", http.StatusUnauthorized},
|
||||||
|
{"空 Authorization", "", http.StatusUnauthorized},
|
||||||
|
{"仅空白 token", "Bearer ", http.StatusUnauthorized},
|
||||||
|
}
|
||||||
|
for _, c := range cases {
|
||||||
|
t.Run(c.name, func(t *testing.T) {
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
r := httptest.NewRequest("GET", "/api/admin/overview", nil)
|
||||||
|
if c.authHeader != "" {
|
||||||
|
r.Header.Set("Authorization", c.authHeader)
|
||||||
|
}
|
||||||
|
h.ServeHTTP(w, r)
|
||||||
|
if w.Code != c.wantStatus {
|
||||||
|
t.Errorf("code=%d, want %d", w.Code, c.wantStatus)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestRequireAdmin_OptionsAlwaysAllowed OPTIONS 预检必须放行(浏览器预检不带 Authorization)。
|
||||||
|
func TestRequireAdmin_OptionsAlwaysAllowed(t *testing.T) {
|
||||||
|
t.Cleanup(func() { setting.SetAdminKeys(nil, "") })
|
||||||
|
setting.SetAdminKeys([]string{"admin-secret"}, "admin_key")
|
||||||
|
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
h := RequireAdmin(okHandler())
|
||||||
|
h.ServeHTTP(w, httptest.NewRequest("OPTIONS", "/api/admin/overview", nil))
|
||||||
|
if w.Code != http.StatusOK {
|
||||||
|
t.Errorf("OPTIONS: code=%d, want 200", w.Code)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestAdminAndBusinessCredentialIsolation 权限隔离:
|
||||||
|
// 配置了独立 admin_key 后,业务凭证(auth_key)不得访问管理接口;
|
||||||
|
// 未配置 admin_key 时回退,业务凭证仍可管理(向后兼容)。
|
||||||
|
func TestAdminAndBusinessCredentialIsolation(t *testing.T) {
|
||||||
|
t.Cleanup(func() {
|
||||||
|
setting.SetAdminKeys(nil, "")
|
||||||
|
setting.SetAuthAPIKeys(nil)
|
||||||
|
})
|
||||||
|
|
||||||
|
const businessKey = "business-key"
|
||||||
|
const adminKey = "admin-key"
|
||||||
|
|
||||||
|
// 业务侧凭证固定为 businessKey(模拟 /v1/audio/speech 用的 key)
|
||||||
|
setting.SetAuthAPIKeys([]string{businessKey})
|
||||||
|
|
||||||
|
// --- 场景 A:配置了独立 admin_key(隔离生效) ---
|
||||||
|
setting.SetAdminKeys([]string{adminKey}, "admin_key")
|
||||||
|
h := RequireAdmin(okHandler())
|
||||||
|
|
||||||
|
wBiz := httptest.NewRecorder()
|
||||||
|
rBiz := httptest.NewRequest("GET", "/api/admin/overview", nil)
|
||||||
|
rBiz.Header.Set("Authorization", "Bearer "+businessKey)
|
||||||
|
h.ServeHTTP(wBiz, rBiz)
|
||||||
|
if wBiz.Code != http.StatusUnauthorized {
|
||||||
|
t.Errorf("隔离生效时,业务 key 访问管理接口: code=%d, want 401", wBiz.Code)
|
||||||
|
}
|
||||||
|
|
||||||
|
wAdmin := httptest.NewRecorder()
|
||||||
|
rAdmin := httptest.NewRequest("GET", "/api/admin/overview", nil)
|
||||||
|
rAdmin.Header.Set("Authorization", "Bearer "+adminKey)
|
||||||
|
h.ServeHTTP(wAdmin, rAdmin)
|
||||||
|
if wAdmin.Code != http.StatusOK {
|
||||||
|
t.Errorf("隔离生效时,admin_key 访问管理接口: code=%d, want 200", wAdmin.Code)
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- 场景 B:未配置 admin_key,回退用业务凭证(向后兼容) ---
|
||||||
|
setting.SetAdminKeys([]string{businessKey}, "auth_key")
|
||||||
|
|
||||||
|
wFallback := httptest.NewRecorder()
|
||||||
|
rFallback := httptest.NewRequest("GET", "/api/admin/overview", nil)
|
||||||
|
rFallback.Header.Set("Authorization", "Bearer "+businessKey)
|
||||||
|
h.ServeHTTP(wFallback, rFallback)
|
||||||
|
if wFallback.Code != http.StatusOK {
|
||||||
|
t.Errorf("回退模式下,业务 key 应可管理: code=%d, want 200", wFallback.Code)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,103 @@
|
|||||||
|
package middleware
|
||||||
|
|
||||||
|
import (
|
||||||
|
"log"
|
||||||
|
"net"
|
||||||
|
"net/http"
|
||||||
|
"os"
|
||||||
|
"strings"
|
||||||
|
)
|
||||||
|
|
||||||
|
// metricsAllowList 是 METRICS_ALLOW_CIDR 解析出的内网白名单。
|
||||||
|
// 启动期由 InitMetricsAllowList 填充;运行期只读,无并发写。
|
||||||
|
var metricsAllowList []*net.IPNet
|
||||||
|
|
||||||
|
// metricsAllowConfigured 表示是否配置了非空的 METRICS_ALLOW_CIDR。
|
||||||
|
// 决定根路径 /metrics、/health 是否注册(未配置则完全不注册,访问 404)。
|
||||||
|
var metricsAllowConfigured bool
|
||||||
|
|
||||||
|
// InitMetricsAllowList 解析 METRICS_ALLOW_CIDR,启动期调用一次。
|
||||||
|
//
|
||||||
|
// 格式:逗号分隔的 CIDR 列表,例如 "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"。
|
||||||
|
// 也接受裸 IP(自动补 /32 或 /128),方便写 "127.0.0.1"。
|
||||||
|
//
|
||||||
|
// 为什么需要它:根路径 /metrics、/health 是给 Prometheus 抓取 / K8s 探针用的机器端点,
|
||||||
|
// 让它们带 Bearer 会强制改抓取配置;用内网白名单更省事,且默认不暴露。
|
||||||
|
//
|
||||||
|
// 【重要】Docker 环境不要填 127.0.0.1/32 —— 那是容器自身的回环,
|
||||||
|
// Prometheus 在宿主机或另一个容器里根本进不来。请填容器内网网段(如 172.16.0.0/12)。
|
||||||
|
func InitMetricsAllowList() {
|
||||||
|
raw := strings.TrimSpace(os.Getenv("METRICS_ALLOW_CIDR"))
|
||||||
|
metricsAllowList = nil
|
||||||
|
metricsAllowConfigured = false
|
||||||
|
if raw == "" {
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, part := range strings.Split(raw, ",") {
|
||||||
|
entry := strings.TrimSpace(part)
|
||||||
|
if entry == "" {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
// 裸 IP 自动补全掩码
|
||||||
|
if !strings.Contains(entry, "/") {
|
||||||
|
if ip := net.ParseIP(entry); ip != nil {
|
||||||
|
if ip.To4() != nil {
|
||||||
|
entry += "/32"
|
||||||
|
} else {
|
||||||
|
entry += "/128"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
_, ipnet, err := net.ParseCIDR(entry)
|
||||||
|
if err != nil {
|
||||||
|
log.Printf("[metrics-ip] 忽略非法 CIDR 条目 %q: %v", part, err)
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
metricsAllowList = append(metricsAllowList, ipnet)
|
||||||
|
}
|
||||||
|
metricsAllowConfigured = len(metricsAllowList) > 0
|
||||||
|
if metricsAllowConfigured {
|
||||||
|
log.Printf("[metrics-ip] METRICS_ALLOW_CIDR 已启用,根路径 /metrics 仅对 %d 个网段开放", len(metricsAllowList))
|
||||||
|
} else {
|
||||||
|
log.Printf("[metrics-ip] METRICS_ALLOW_CIDR 无有效条目,根路径 /metrics 将不注册")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// MetricsAllowListConfigured 报告是否配置了有效的白名单网段。
|
||||||
|
// router 据此决定是否注册根路径 /metrics / /health。
|
||||||
|
func MetricsAllowListConfigured() bool { return metricsAllowConfigured }
|
||||||
|
|
||||||
|
// MetricsIPAllowList 只放行来源 IP 命中白名单的请求。
|
||||||
|
//
|
||||||
|
// 未命中返回 **404**(而不是 403):不向扫描者确认"这里存在一个只是你没权限的端点"。
|
||||||
|
// 客户端 IP 取自 GetClientIP,它已处理 X-Forwarded-For 与 TRUSTED_PROXY_HOPS,
|
||||||
|
// 所以反代后面的真实来源也能正确判定。
|
||||||
|
func MetricsIPAllowList(next http.Handler) http.Handler {
|
||||||
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
if !ipAllowed(GetClientIP(r)) {
|
||||||
|
// 不打印每个被拒请求,避免扫描流量刷爆日志;只按需在 debug 下输出
|
||||||
|
http.NotFound(w, r)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
next.ServeHTTP(w, r)
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// ipAllowed 判定客户端 IP 是否命中任一白名单网段。
|
||||||
|
// 空 IP(解析失败)一律拒绝 —— 宁可拒绝也不能误放行。
|
||||||
|
func ipAllowed(clientIP string) bool {
|
||||||
|
if clientIP == "" {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
ip := net.ParseIP(strings.TrimSpace(clientIP))
|
||||||
|
if ip == nil {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
for _, n := range metricsAllowList {
|
||||||
|
if n.Contains(ip) {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
@@ -0,0 +1,143 @@
|
|||||||
|
package middleware
|
||||||
|
|
||||||
|
import (
|
||||||
|
"net"
|
||||||
|
"net/http"
|
||||||
|
"net/http/httptest"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
// allowListFrom 把逗号分隔的 CIDR 串解析成白名单,供测试直接注入。
|
||||||
|
func allowListFrom(t *testing.T, spec string) []*net.IPNet {
|
||||||
|
t.Helper()
|
||||||
|
var out []*net.IPNet
|
||||||
|
for _, part := range strings.Split(spec, ",") {
|
||||||
|
entry := strings.TrimSpace(part)
|
||||||
|
if entry == "" {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
_, n, err := net.ParseCIDR(entry)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("测试用例里的 CIDR 非法 %q: %v", entry, err)
|
||||||
|
}
|
||||||
|
out = append(out, n)
|
||||||
|
}
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
// reqFrom 构造带指定来源地址的请求。
|
||||||
|
func reqFrom(remoteAddr string) *http.Request {
|
||||||
|
r := httptest.NewRequest("GET", "/metrics", nil)
|
||||||
|
r.RemoteAddr = remoteAddr
|
||||||
|
return r
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestIPAllowed 验证 CIDR 白名单判定:
|
||||||
|
// 命中放行、未命中拒绝,解析失败的 IP 一律拒绝(宁可拒绝也不误放行)。
|
||||||
|
func TestIPAllowed(t *testing.T) {
|
||||||
|
// 直接构造白名单,不依赖环境变量
|
||||||
|
metricsAllowList = allowListFrom(t, "127.0.0.1/32,10.0.0.0/8,172.16.0.0/12,::1/128")
|
||||||
|
metricsAllowConfigured = true
|
||||||
|
t.Cleanup(func() {
|
||||||
|
metricsAllowList = nil
|
||||||
|
metricsAllowConfigured = false
|
||||||
|
})
|
||||||
|
|
||||||
|
cases := []struct {
|
||||||
|
name string
|
||||||
|
ip string
|
||||||
|
want bool
|
||||||
|
}{
|
||||||
|
{"本机 IPv4 命中 /32", "127.0.0.1", true},
|
||||||
|
{"10.x 命中 /8", "10.1.2.3", true},
|
||||||
|
{"172.16.x 命中 /12", "172.16.5.9", true},
|
||||||
|
{"172.31.x 仍在 /12 内", "172.31.255.254", true},
|
||||||
|
{"IPv6 回环命中 /128", "::1", true},
|
||||||
|
{"公网 IP 不在白名单", "8.8.8.8", false},
|
||||||
|
{"172.32.x 超出 /12 范围", "172.32.0.1", false},
|
||||||
|
{"192.168.x 未配置", "192.168.1.1", false},
|
||||||
|
{"空 IP 拒绝", "", false},
|
||||||
|
{"非法 IP 拒绝", "not-an-ip", false},
|
||||||
|
}
|
||||||
|
for _, c := range cases {
|
||||||
|
t.Run(c.name, func(t *testing.T) {
|
||||||
|
if got := ipAllowed(c.ip); got != c.want {
|
||||||
|
t.Errorf("ipAllowed(%q) = %v, want %v", c.ip, got, c.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestIPAllowed_EmptyListRejectsAll 白名单为空时全部拒绝(未配置 = 不开放)。
|
||||||
|
func TestIPAllowed_EmptyListRejectsAll(t *testing.T) {
|
||||||
|
metricsAllowList = nil
|
||||||
|
metricsAllowConfigured = false
|
||||||
|
t.Cleanup(func() {
|
||||||
|
metricsAllowList = nil
|
||||||
|
metricsAllowConfigured = false
|
||||||
|
})
|
||||||
|
|
||||||
|
if ipAllowed("127.0.0.1") {
|
||||||
|
t.Error("白名单为空时应拒绝所有 IP")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestMetricsIPAllowList_Scope 白名单内放行、白名单外 404。
|
||||||
|
// 用 404 而不是 403,是为了不向扫描者确认"该端点存在,只是你没权限"。
|
||||||
|
func TestMetricsIPAllowList_Scope(t *testing.T) {
|
||||||
|
metricsAllowList = allowListFrom(t, "10.0.0.0/8")
|
||||||
|
t.Cleanup(func() { metricsAllowList = nil })
|
||||||
|
|
||||||
|
h := MetricsIPAllowList(okHandler())
|
||||||
|
|
||||||
|
// 命中白名单 → 放行到 next
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w, reqFrom("10.1.1.1:1234"))
|
||||||
|
if w.Code != http.StatusOK {
|
||||||
|
t.Errorf("白名单内来源: code=%d, want 200", w.Code)
|
||||||
|
}
|
||||||
|
|
||||||
|
// 白名单外(RFC 5737 文档地址)→ 404,且不应触达 next
|
||||||
|
w2 := httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w2, reqFrom("192.0.2.1:1234"))
|
||||||
|
if w2.Code != http.StatusNotFound {
|
||||||
|
t.Errorf("白名单外来源: code=%d, want 404", w2.Code)
|
||||||
|
}
|
||||||
|
if w2.Body.String() == "ok" {
|
||||||
|
t.Error("白名单外来源不应触达被保护的 handler")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestMetricsIPAllowList_XForwardedForSpoof 伪造 X-Forwarded-For 不能绕过白名单。
|
||||||
|
//
|
||||||
|
// GetClientIP 的启发式模式(trustedProxyHops==0,默认)从 XFF 链**尾部**取第一个
|
||||||
|
// **公网** IP,刻意跳过私网跳 —— 这样攻击者无法用 "X-Forwarded-For: <内网IP>"
|
||||||
|
// 把自己伪装成白名单来源。本测试锁死这个安全属性。
|
||||||
|
func TestMetricsIPAllowList_XForwardedForSpoof(t *testing.T) {
|
||||||
|
metricsAllowList = allowListFrom(t, "10.0.0.0/8")
|
||||||
|
t.Cleanup(func() { metricsAllowList = nil })
|
||||||
|
|
||||||
|
h := MetricsIPAllowList(okHandler())
|
||||||
|
|
||||||
|
// 直连是私网(像反代),XFF 里塞一个内网 IP 想混进白名单
|
||||||
|
r := reqFrom("127.0.0.1:1234")
|
||||||
|
r.Header.Set("X-Forwarded-For", "10.9.9.9")
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w, r)
|
||||||
|
|
||||||
|
// 启发式模式会跳过私网跳、落到直连地址 127.0.0.1(不在 10.0.0.0/8)→ 404。
|
||||||
|
// 关键断言:伪造的内网 XFF **没有**让它通过。
|
||||||
|
if w.Code == http.StatusOK {
|
||||||
|
t.Errorf("伪造私网 XFF 不应绕过白名单: code=%d", w.Code)
|
||||||
|
}
|
||||||
|
|
||||||
|
// 反向对照:XFF 填公网 IP 时,GetClientIP 会采用它,同样不在白名单 → 404
|
||||||
|
r2 := reqFrom("127.0.0.1:1234")
|
||||||
|
r2.Header.Set("X-Forwarded-For", "8.8.8.8")
|
||||||
|
w2 := httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w2, r2)
|
||||||
|
if w2.Code != http.StatusNotFound {
|
||||||
|
t.Errorf("公网来源不在白名单: code=%d, want 404", w2.Code)
|
||||||
|
}
|
||||||
|
}
|
||||||
+51
-9
@@ -72,7 +72,8 @@ func Setup() *mux.Router {
|
|||||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||||
_, _ = w.Write(setupHTML)
|
_, _ = w.Write(setupHTML)
|
||||||
}).Methods("GET")
|
}).Methods("GET")
|
||||||
r.HandleFunc("/api/setup/status", controller.SetupStatusHandler).Methods("GET")
|
// v0.3.0:安装状态不再匿名暴露(原本 normal 模式下仍返回 {installed, mode})
|
||||||
|
r.Handle("/api/setup/status", middleware.RequireAdmin(http.HandlerFunc(controller.SetupStatusHandler))).Methods("GET")
|
||||||
r.HandleFunc("/api/setup/prefill", controller.SetupPrefillHandler).Methods("GET")
|
r.HandleFunc("/api/setup/prefill", controller.SetupPrefillHandler).Methods("GET")
|
||||||
r.HandleFunc("/api/setup", controller.SetupSubmitHandler).Methods("POST")
|
r.HandleFunc("/api/setup", controller.SetupSubmitHandler).Methods("POST")
|
||||||
|
|
||||||
@@ -100,6 +101,9 @@ func Setup() *mux.Router {
|
|||||||
r.Handle("/api/admin/overview", middleware.RequireAdmin(http.HandlerFunc(controller.AdminOverviewHandler))).Methods("GET")
|
r.Handle("/api/admin/overview", middleware.RequireAdmin(http.HandlerFunc(controller.AdminOverviewHandler))).Methods("GET")
|
||||||
// /api/admin/metrics (鉴权);返 Prometheus 文本
|
// /api/admin/metrics (鉴权);返 Prometheus 文本
|
||||||
r.Handle("/api/admin/metrics", middleware.RequireAdmin(http.HandlerFunc(controller.AdminMetricsHandler))).Methods("GET")
|
r.Handle("/api/admin/metrics", middleware.RequireAdmin(http.HandlerFunc(controller.AdminMetricsHandler))).Methods("GET")
|
||||||
|
// v0.3.0:详细健康数据的鉴权版(面板与运维用)。
|
||||||
|
// 与根路径 /health 的区别:这里始终注册且强制鉴权;根路径 /health 默认 404。
|
||||||
|
r.Handle("/api/admin/health", middleware.RequireAdmin(http.HandlerFunc(controller.HealthHandler))).Methods("GET")
|
||||||
|
|
||||||
// /api/voices 音色 CRUD (鉴权)
|
// /api/voices 音色 CRUD (鉴权)
|
||||||
r.Handle("/api/voices", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoicesListHandler))).Methods("GET")
|
r.Handle("/api/voices", middleware.RequireAdmin(http.HandlerFunc(controller.AdminVoicesListHandler))).Methods("GET")
|
||||||
@@ -112,15 +116,28 @@ func Setup() *mux.Router {
|
|||||||
r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsUpdateHandler))).Methods("PUT")
|
r.Handle("/api/settings", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsUpdateHandler))).Methods("PUT")
|
||||||
r.Handle("/api/settings/api-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAPIKeyHandler))).Methods("PUT")
|
r.Handle("/api/settings/api-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAPIKeyHandler))).Methods("PUT")
|
||||||
r.Handle("/api/settings/auth-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAuthKeyHandler))).Methods("PUT")
|
r.Handle("/api/settings/auth-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAuthKeyHandler))).Methods("PUT")
|
||||||
|
// v0.3.0: 管理凭证(admin_key)独立配置端点。
|
||||||
|
// 同时注册新旧两个路径:/api/admin/settings/admin-key 是阶段 3 分层后的正式路径,
|
||||||
|
// /api/settings/admin-key 属于旧前缀,保留为别名(与阶段 3 的别名策略一致)。
|
||||||
|
r.Handle("/api/admin/settings/admin-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAdminKeyHandler))).Methods("PUT")
|
||||||
|
r.Handle("/api/settings/admin-key", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsAdminKeyHandler))).Methods("PUT")
|
||||||
r.Handle("/api/settings/cors", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsCORSHandler))).Methods("PUT")
|
r.Handle("/api/settings/cors", middleware.RequireAdmin(http.HandlerFunc(controller.SettingsCORSHandler))).Methods("PUT")
|
||||||
|
|
||||||
// 业务路由
|
// 业务路由
|
||||||
r.HandleFunc("/v1/audio/speech", controller.OpenaiTTSHandler).Methods("POST", "OPTIONS")
|
r.HandleFunc("/v1/audio/speech", controller.OpenaiTTSHandler).Methods("POST", "OPTIONS")
|
||||||
r.HandleFunc("/health", controller.HealthHandler).Methods("GET")
|
|
||||||
r.HandleFunc("/dashboard", func(w http.ResponseWriter, req *http.Request) {
|
// v0.3.0 端点收口:
|
||||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
// /healthz 匿名存活探针,只回 "ok"(K8s probe / Docker HEALTHCHECK 用)
|
||||||
_, _ = w.Write(dashboardHTML)
|
// /health 详细健康数据,**鉴权**(原本匿名,会泄漏版本/内存/配置错误文本)
|
||||||
}).Methods("GET")
|
// /dashboard 管理看板;**鉴权**(原本匿名,聚合了 /health + /metrics 的全部数据)
|
||||||
|
// /api/admin/health 鉴权版详细健康数据(面板拉取用,风格与 /api/admin/* 一致)
|
||||||
|
//
|
||||||
|
// 注意 /health 的鉴权是"内容协商"式的(见 htmlAwareAdmin):
|
||||||
|
// 浏览器直接地址栏访问时返回登录页而不是 401,保持原有 UX;
|
||||||
|
// 非 HTML 请求(脚本/抓取)不带凭证一律 401。数据安全由 API 层保证。
|
||||||
|
r.HandleFunc("/healthz", controller.HealthzHandler).Methods("GET")
|
||||||
|
r.Handle("/health", middleware.RequireAdmin(http.HandlerFunc(controller.HealthHandler))).Methods("GET")
|
||||||
|
r.Handle("/dashboard", htmlAwareAdmin(serveAdmin(adminHTML))).Methods("GET")
|
||||||
r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
|
r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
|
||||||
// 安装模式下,根路径跳 /setup
|
// 安装模式下,根路径跳 /setup
|
||||||
if installer.GetMode() == installer.ModeSetup {
|
if installer.GetMode() == installer.ModeSetup {
|
||||||
@@ -131,13 +148,38 @@ func Setup() *mux.Router {
|
|||||||
http.Redirect(w, req, "/admin", http.StatusFound)
|
http.Redirect(w, req, "/admin", http.StatusFound)
|
||||||
}).Methods("GET")
|
}).Methods("GET")
|
||||||
|
|
||||||
// /metrics 不做鉴权(对齐 /health 策略),但仍然走 RateLimit / ConcurrencyLimit。
|
// 根路径 /metrics 与 /health 的机器访问:
|
||||||
// Prometheus 抓取不带 Origin,因此经过 CORS 中间件时会直接 pass-through。
|
// - 配置了 METRICS_ALLOW_CIDR → 注册 /metrics,包裹内网白名单(非白名单返回 404)
|
||||||
r.Handle("/metrics", metrics.Meter.Handler()).Methods("GET")
|
// - 未配置 → 根路径 /metrics **完全不注册**(访问 404),避免默认对外暴露
|
||||||
|
// /health 已在上面按鉴权注册,不再提供匿名版本。
|
||||||
|
if middleware.MetricsAllowListConfigured() {
|
||||||
|
r.Handle("/metrics", middleware.MetricsIPAllowList(metrics.Meter.Handler())).Methods("GET")
|
||||||
|
}
|
||||||
|
|
||||||
return r
|
return r
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// htmlAwareAdmin 给**浏览器直接访问的管理页面**套鉴权,但对 HTML 请求做内容协商:
|
||||||
|
//
|
||||||
|
// - Accept 含 text/html(地址栏打开、点链接)→ 照常返回页面外壳。
|
||||||
|
// 此时不做 401:因为前端登录态存在 sessionStorage,**不会随请求发送**,
|
||||||
|
// 服务端无从判断是否已登录;强行 401 会让"打开 /dashboard 看到登录页"
|
||||||
|
// 这一现有体验变成"打开 /dashboard 直接报错"。
|
||||||
|
// 页面外壳本身不含任何数据,数据全部来自鉴权后的 /api/admin/* 接口。
|
||||||
|
// - 其它(脚本、curl、抓取工具)→ 强制 RequireAdmin,无凭证 401。
|
||||||
|
//
|
||||||
|
// 这样既堵住了"匿名抓取健康数据",又不破坏 SPA 的登录流程。
|
||||||
|
func htmlAwareAdmin(html http.Handler) http.Handler {
|
||||||
|
guarded := middleware.RequireAdmin(html)
|
||||||
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
if acceptsHTML(r.Header.Get("Accept")) {
|
||||||
|
html.ServeHTTP(w, r)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
guarded.ServeHTTP(w, r)
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
// acceptsHTML 在 router 包内复刻,middleware 包的版本未导出。
|
// acceptsHTML 在 router 包内复刻,middleware 包的版本未导出。
|
||||||
// 用途:NotFoundHandler 判断浏览器 Accept。
|
// 用途:NotFoundHandler 判断浏览器 Accept。
|
||||||
func acceptsHTML(accept string) bool {
|
func acceptsHTML(accept string) bool {
|
||||||
|
|||||||
@@ -32,6 +32,14 @@ var (
|
|||||||
ttsTimeout time.Duration = common.DefaultTimeout
|
ttsTimeout time.Duration = common.DefaultTimeout
|
||||||
ttsConfigErr error
|
ttsConfigErr error
|
||||||
authAPIKeys []string
|
authAPIKeys []string
|
||||||
|
// adminAPIKeys 是**管理接口专用**凭证(admin_key)。
|
||||||
|
// 与 authAPIKeys(业务侧,/v1/audio/speech 用)分离:
|
||||||
|
// - admin_key 为空时回退到 auth_key/env,老部署行为完全不变
|
||||||
|
// - admin_key 配了之后,业务 key 无法访问 /api/admin/*,权限隔离成立
|
||||||
|
// 详见 docs/IMPLEMENT_v0.3.0.md 阶段 1。
|
||||||
|
adminAPIKeys []string
|
||||||
|
// adminKeySource 记录管理凭证的来源,仅用于启动摘要与排障。
|
||||||
|
adminKeySource string
|
||||||
// corsAllowAll / corsOrigins 拆成两个独立字段,各自在 RLock 下读取,
|
// corsAllowAll / corsOrigins 拆成两个独立字段,各自在 RLock 下读取,
|
||||||
// 避免 CORSConfig 整体读时被 Lock 阻塞热路径。
|
// 避免 CORSConfig 整体读时被 Lock 阻塞热路径。
|
||||||
corsAllowAll bool
|
corsAllowAll bool
|
||||||
@@ -108,6 +116,40 @@ func SetAuthAPIKeys(keys []string) {
|
|||||||
authAPIKeys = out
|
authAPIKeys = out
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// GetAdminKeys 读**管理接口专用**凭证列表;返回拷贝防止业务侧持有底层 slice。
|
||||||
|
// 供 middleware.RequireAdmin 使用;业务侧鉴权请用 GetAuthAPIKeys。
|
||||||
|
func GetAdminKeys() []string {
|
||||||
|
ttsMu.RLock()
|
||||||
|
defer ttsMu.RUnlock()
|
||||||
|
if len(adminAPIKeys) == 0 {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
out := make([]string, len(adminAPIKeys))
|
||||||
|
copy(out, adminAPIKeys)
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
// SetAdminKeys 整体替换管理凭证;入参被复制。source 仅用于启动摘要展示。
|
||||||
|
func SetAdminKeys(keys []string, source string) {
|
||||||
|
ttsMu.Lock()
|
||||||
|
defer ttsMu.Unlock()
|
||||||
|
adminKeySource = source
|
||||||
|
if len(keys) == 0 {
|
||||||
|
adminAPIKeys = nil
|
||||||
|
return
|
||||||
|
}
|
||||||
|
out := make([]string, len(keys))
|
||||||
|
copy(out, keys)
|
||||||
|
adminAPIKeys = out
|
||||||
|
}
|
||||||
|
|
||||||
|
// GetAdminKeySource 返回管理凭证来源:admin_key / auth_key / env / ""(未配置)。
|
||||||
|
func GetAdminKeySource() string {
|
||||||
|
ttsMu.RLock()
|
||||||
|
defer ttsMu.RUnlock()
|
||||||
|
return adminKeySource
|
||||||
|
}
|
||||||
|
|
||||||
// GetCORSAllowAll 读 CORS 是否放行所有来源。
|
// GetCORSAllowAll 读 CORS 是否放行所有来源。
|
||||||
func GetCORSAllowAll() bool {
|
func GetCORSAllowAll() bool {
|
||||||
ttsMu.RLock()
|
ttsMu.RLock()
|
||||||
@@ -391,6 +433,18 @@ func LoadRuntimeConfig(s Store) error {
|
|||||||
SetAuthAPIKeys(nil)
|
SetAuthAPIKeys(nil)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// 管理凭证:admin_key(DB) > auth_key(DB) > OPENAI_TTS_API_KEY(env)
|
||||||
|
// 分离的目的:业务调用方拿到的 key 不应同时拥有管理后台权限。
|
||||||
|
// 不配 admin_key 时行为与旧版完全一致(回退用 auth_key),保证向后兼容。
|
||||||
|
switch {
|
||||||
|
case all["admin_key"] != "":
|
||||||
|
SetAdminKeys([]string{all["admin_key"]}, "admin_key")
|
||||||
|
case authKey != "":
|
||||||
|
SetAdminKeys([]string{authKey}, "auth_key")
|
||||||
|
default:
|
||||||
|
SetAdminKeys(nil, "")
|
||||||
|
}
|
||||||
|
|
||||||
// CORS 配置:DB > env
|
// CORS 配置:DB > env
|
||||||
// cors_allow_all (bool): 允许所有来源(*)
|
// cors_allow_all (bool): 允许所有来源(*)
|
||||||
// cors_origins (string): 逗号分隔白名单
|
// cors_origins (string): 逗号分隔白名单
|
||||||
@@ -540,6 +594,16 @@ func LogStartupSummary() {
|
|||||||
log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(authKeys))
|
log.Printf("OPENAI_TTS_API_KEY: 已设置 %d 个有效密钥", len(authKeys))
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// v0.3.0:管理凭证独立于业务凭证(admin_key > auth_key > env)
|
||||||
|
switch GetAdminKeySource() {
|
||||||
|
case "admin_key":
|
||||||
|
log.Printf("管理凭证: 使用独立 admin_key(业务 key 无法访问管理接口)")
|
||||||
|
case "auth_key":
|
||||||
|
log.Printf("管理凭证: 未单独配置 admin_key,回退使用 auth_key(业务 key 同时拥有管理权限)")
|
||||||
|
default:
|
||||||
|
log.Printf("管理凭证: ✗ 未配置(normal 模式下服务将拒绝启动)")
|
||||||
|
}
|
||||||
|
|
||||||
allowAll := GetCORSAllowAll()
|
allowAll := GetCORSAllowAll()
|
||||||
origins := GetCORSOrigins()
|
origins := GetCORSOrigins()
|
||||||
if allowAll {
|
if allowAll {
|
||||||
|
|||||||
@@ -36,8 +36,12 @@ func newCounter(name, help string, labelNames []string) *Counter {
|
|||||||
func (c *Counter) Inc(labels Labels) { c.Add(1, labels) }
|
func (c *Counter) Inc(labels Labels) { c.Add(1, labels) }
|
||||||
|
|
||||||
// Add 累加 v(v 必须 >= 0)。
|
// Add 累加 v(v 必须 >= 0)。
|
||||||
|
//
|
||||||
|
// 空接收者(nil *Counter)安全:未初始化的全局指标(如 metrics.Init() 尚未调用时
|
||||||
|
// 的 metrics.UpstreamTotal)会被静默忽略,而不是 panic。
|
||||||
|
// 这让"直接调用 handler"的测试/复用场景不会因为漏掉指标初始化而崩溃。
|
||||||
func (c *Counter) Add(v float64, labels Labels) {
|
func (c *Counter) Add(v float64, labels Labels) {
|
||||||
if v < 0 {
|
if c == nil || v < 0 {
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
child := c.getOrCreate(labels)
|
child := c.getOrCreate(labels)
|
||||||
|
|||||||
@@ -33,7 +33,11 @@ func newGauge(name, help string, labelNames []string) *Gauge {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// Set 直接设置当前值。
|
// Set 直接设置当前值。
|
||||||
|
// 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
|
||||||
func (g *Gauge) Set(v float64, labels Labels) {
|
func (g *Gauge) Set(v float64, labels Labels) {
|
||||||
|
if g == nil {
|
||||||
|
return
|
||||||
|
}
|
||||||
child := g.getOrCreate(labels)
|
child := g.getOrCreate(labels)
|
||||||
child.bits.Store(float64bits(v))
|
child.bits.Store(float64bits(v))
|
||||||
}
|
}
|
||||||
@@ -45,7 +49,11 @@ func (g *Gauge) Inc(labels Labels) { g.Add(1, labels) }
|
|||||||
func (g *Gauge) Dec(labels Labels) { g.Add(-1, labels) }
|
func (g *Gauge) Dec(labels Labels) { g.Add(-1, labels) }
|
||||||
|
|
||||||
// Add 累加 v(可负)。
|
// Add 累加 v(可负)。
|
||||||
|
// 空接收者(nil *Gauge)安全,见 Counter.Add 的说明。
|
||||||
func (g *Gauge) Add(v float64, labels Labels) {
|
func (g *Gauge) Add(v float64, labels Labels) {
|
||||||
|
if g == nil {
|
||||||
|
return
|
||||||
|
}
|
||||||
child := g.getOrCreate(labels)
|
child := g.getOrCreate(labels)
|
||||||
for {
|
for {
|
||||||
bits := child.bits.Load()
|
bits := child.bits.Load()
|
||||||
|
|||||||
@@ -47,7 +47,11 @@ func newHistogram(name, help string, buckets []float64, labelNames []string) *Hi
|
|||||||
}
|
}
|
||||||
|
|
||||||
// Observe 记录一个观测值。
|
// Observe 记录一个观测值。
|
||||||
|
// 空接收者(nil *Histogram)安全,见 Counter.Add 的说明。
|
||||||
func (h *Histogram) Observe(v float64, labels Labels) {
|
func (h *Histogram) Observe(v float64, labels Labels) {
|
||||||
|
if h == nil {
|
||||||
|
return
|
||||||
|
}
|
||||||
child := h.getOrCreate(labels)
|
child := h.getOrCreate(labels)
|
||||||
for {
|
for {
|
||||||
bits := child.sumBits.Load()
|
bits := child.sumBits.Load()
|
||||||
|
|||||||
+6
-1
@@ -5,7 +5,12 @@
|
|||||||
// - 零外部依赖,只使用标准库;
|
// - 零外部依赖,只使用标准库;
|
||||||
// - label key 在指标注册时锁定,运行期不可新增(避免 cardinality 爆炸);
|
// - label key 在指标注册时锁定,运行期不可新增(避免 cardinality 爆炸);
|
||||||
// - 所有并发安全由实现保证,调用方无需加锁;
|
// - 所有并发安全由实现保证,调用方无需加锁;
|
||||||
// - Meter 是高层入口,NoopMeter 用于测试。
|
// - Meter 是高层入口,NoopMeter 用于测试;
|
||||||
|
// - **空接收者安全**: 未初始化的 *Counter / *Gauge / *Histogram(即 nil 指针)
|
||||||
|
// 上的 Inc/Add/Set/Observe 一律静默忽略,不 panic。
|
||||||
|
// 这条约定是为 metrics 包的全局指标变量服务的 —— 它们默认为 nil,只有 main
|
||||||
|
// 调用过 metrics.Init() 之后才有值;直接复用 handler 的场景(集成测试、
|
||||||
|
// 未来做成库)不应该因为漏掉指标初始化而崩掉整个请求处理。
|
||||||
package telemetry
|
package telemetry
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
|||||||
Reference in New Issue
Block a user