-
sun released this
2026-10-04 16:44:46 +08:00 | 0 commits to main since this releasev0.2.4 把默认对外的监控面收窄到只有一个匿名存活探针，并把管理凭证与业务调用凭证拆开，同时把管理入口统一到
/dashboard。业务接口/v1/audio/speech行为不变。⚠️ 本版本为破坏性变更版本（以
0.2.4发布、按补丁号连续，但语义是破坏性的），升级前请务必阅读下方 Breaking Changes。
⚠️ Breaking Changes（升级前必读）
1. 监控端点不再匿名可读
端点 v0.2.3 v0.2.4 /healthz不存在 匿名可读，只回 200 ok（不含任何字段）/health匿名，返回完整健康数据 需管理凭证，否则 401 /metrics（根路径）匿名 默认 404；需配置 METRICS_ALLOW_CIDR才注册/dashboard匿名（服务状态预览页） 需鉴权（且已成为管理看板，见第 3 条） /api/setup/status匿名 需管理凭证 你需要做的：
- K8s 探针 / Docker HEALTHCHECK 改指
/healthz。继续指向/health会一律 401 → Pod 反复重启 / 容器被判 unhealthy。（本仓库的docker-compose.yml与Dockerfile已同步修改。） - Prometheus 二选一：
- 改用鉴权版
/api/admin/metrics，并在scrape_configs配authorization: { credentials: <管理凭证> }； - 或配置
METRICS_ALLOW_CIDR走根路径白名单。⚠️ Docker 中不要填127.0.0.1/32（那是容器自身回环），请填容器内网网段，例如172.16.0.0/12。
- 改用鉴权版
2. 未配置管理凭证时服务拒绝启动
RequireAdmin此前在凭证列表为空时直接放行（等于管理接口完全裸奔）。现在该情况返回 401；并且 normal 模式下若admin_key/auth_key/OPENAI_TTS_API_KEY三者皆为空，服务将 fail-fast 拒绝启动。你需要做的：升级前确认三者至少配置一个，否则服务起不来。
3. 管理入口从
/admin迁至/dashboard/dashboard、/dashboard/voices、/dashboard/settings为新入口- 详细服务状态页迁至
/dashboard/status（原/dashboard是状态预览页） /admin及子路径 301 永久重定向到对应新路径，书签与脚本请尽快迁移
4. 管理 API 正式路径改为
/api/admin/*- 新：
/api/admin/voices、/api/admin/settings（含api-key/auth-key/admin-key） - 旧：
/api/voices、/api/settings仍可用（别名，不是重定向），计划后续版本移除
✨ 新特性
独立管理凭证
admin_key管理后台登录凭证与业务调用凭证分离。取值优先级：
admin_key（DB） → auth_key（DB） → OPENAI_TTS_API_KEY（env）- 不配置：回退使用
auth_key，行为与 v0.2.3 完全一致 - 配置后：业务调用方持有的
auth_key无法访问管理接口（返回 401）
配置方式：
PUT /api/admin/settings/admin-key，或在/dashboard → 设置中操作。凭证只写不读 ——GET /api/admin/settings只返回打码值与来源标记。内网 CIDR 白名单
METRICS_ALLOW_CIDR逗号分隔，支持裸 IP 自动补掩码。非白名单来源返回 404（而非 403，避免向扫描者确认端点存在）。未配置时根路径
/metrics完全不注册。匿名存活探针
/healthz刻意不返回任何字段（无版本、无内存、无配置状态、无模式），只回答"进程还在不在"。运维要细节请走鉴权后的
/health或/api/admin/health。鉴权版详细健康数据
/api/admin/health与
/api/admin/metrics风格一致，供管理面板与运维使用。
🔧 修复
- 指标空指针崩溃：
metrics包的全局指标（UpstreamTotal等）默认是 nil，只有main调过metrics.Init()后才有值。任何不经过 main 的调用路径（直接调 handler、复用为库）都会在telemetry埋点处 nil 解引用 panic。现在Counter.Add/Gauge.Set/Gauge.Add/Histogram.Observe一律空接收者安全（nil 静默忽略，与 noop 语义一致）。 - 上游 client 空指针：
volcano.(*HTTPClient).PostStream在 client 未初始化时 panic。现在返回错误，由 controller 归一成 5xx 并记日志——装配错误不该拖垮进程。 RequireAdmin空凭证放行（安全缺口，见 Breaking Change 第 2 条）/api/setup/status在 normal 模式下仍匿名暴露{installed, mode}（见第 1 条）docker-compose.yml/Dockerfile健康检查端点随鉴权改动失效（见第 1 条）
📋 其他变更
- 新增 CI 质量门（
.github/workflows/ci.yml）：push / PR 到develop、main时跑go build+go vet+go test -count=1。 - 测试源码不再入库：
.gitignore恢复整体屏蔽*_test.go。测试文件保留在本地磁盘，由开发者自行执行go test ./... -count=1。⚠️ 仓库内不提供自动化测试，CI 只能守住"编译通过 + 静态检查通过"，守不住行为回归。 - 文档订正：
docs/UI_HANDOFF.md标注为历史文档，补上当前真实文件结构与验收清单。 - 新增上游适配器开发指南：
docs/UPSTREAM_ADAPTER_GUIDE.md——逐行核对现有火山适配器的真实契约，并给出 Provider 抽象的目标设计与分阶段实施计划。
✅ 验证方式
go build ./... go vet ./... go test ./... -count=1端到端实测结果（真实服务器）：
检查 结果 /healthz匿名200+ 字面量ok/health无凭证 / 带凭证401/200根 /metrics未配 CIDR404（不注册）/admin系列路径全部 301至对应/dashboard/*/dashboard*浏览器请求 / 脚本请求200页面外壳 /401/api/admin/*与/api/*别名均 200（无 301/308）配独立 admin_key后业务 key 访问管理接口401业务接口 /v1/audio/speech行为不变
📦 升级步骤
- 确认已配置
admin_key/auth_key/OPENAI_TTS_API_KEY至少一个 - 更新探针指向
/healthz - 更新 Prometheus 抓取配置（鉴权版或
METRICS_ALLOW_CIDR） - 替换镜像 / 二进制并重启
- 访问
/dashboard登录验证；确认旧/admin书签仍能自动跳转 - 按需在
/dashboard → 设置配置独立admin_key
无需数据库迁移 —— 旧的
tts.db可直接复用。Downloads
- K8s 探针 / Docker HEALTHCHECK 改指