5 Commits
Author SHA1 Message Date
sun ec82e895c3 chore(ci): 删除 ci.yml workflow
该 workflow 没有实际价值:

- 仓库按策略不提供测试源码(*_test.go 被 .gitignore 屏蔽),因此其中的
  go test 步骤在干净克隆上只是空转(打印 no test files 后通过),它连
  "测试是否存在"都不会告诉你,自然守不住行为回归。
- 剩下的 go build / go vet 收益也很有限 —— 真正会用到编译产物的 docker.yml
  在发版打 tag 时本就会完整构建一次。

删除后仓库只保留 docker.yml(打 tag 时构建并推送镜像),不再有多余的自动化。

同步清理对它的引用:
- CHANGELOG 的"新增 CI 校验"条目(改述为"没有自动化质量门")
- .gitignore 里测试策略注释中指向 ci.yml 的那句
- docs/UPSTREAM_ADAPTER_GUIDE.md 第 7 节(原表述"CI 跑不到你的测试"已不准确,
  改为"没有任何自动化会跑你的测试")
2026-10-04 16:26:32 +08:00
sun 96a525446b docs(changelog): 补 v0.2.4 正式版本段
CI / build-and-test (push) Canceled after 0s
Docker Publish / build-and-push (push) Canceled after 0s
原 CHANGELOG 只有 [未发布]/0.2.0/0.1.0,而 v0.2.1、v0.2.2、v0.2.3 三个已发布版本均无条目。本次先补齐 v0.2.4 的正式版本段(含版本号与破坏性变更说明),v0.2.1~v0.2.3 的历史缺目留待后续补。

注意:本次改动在 tag v0.2.4 之后提交,因此 v0.2.4 的镜像产物中不含此 CHANGELOG 条目。
2026-10-04 15:21:53 +08:00
sun f7c7e6ee3a docs: v0.3.0 阶段三 文档、示例配置与发布说明
CI / build-and-test (push) Canceled after 0s
Docker Publish / build-and-push (push) Canceled after 0s
文档与配置同步 v0.3.0 的破坏性变更:

README.md:
- 特性列表更新:管理入口 /dashboard、凭证分离、默认无匿名监控端点
- 环境变量表补充 METRICS_ALLOW_CIDR,并说明未配任何管理凭证时服务拒绝启动
- 端点文档重写:/healthz(匿名且不含字段)、/health(需鉴权)、
  /metrics(默认 404,两种使用方式)、管理页面与安装页对照表
  (含"页面需鉴权为何又能直接打开"的内容协商说明)
- 公网部署安全清单重写:按端点列出真实暴露面,并提醒探针必须指向 /healthz
- 故障排查、架构表、迁移表中的 /admin 引用统一改为 /dashboard

.env.example:新增 METRICS_ALLOW_CIDR 与 admin_key 说明(含 Docker 网段警告)。

两处部署陷阱修复(阶段一给 /health 加鉴权引发的连带问题):
- docker-compose.yml 的 healthcheck 原指向 /health,加鉴权后会一律 401,
  导致容器被判定为 unhealthy → 改为 /healthz
- Dockerfile 的 HEALTHCHECK 同样指向 /health → 改为 /healthz
  (这两处若不改,升级后容器健康状态会持续异常,且现象与鉴权改动看起来无关,排查成本高)

新增 docs/RELEASE_NOTES_v0.3.0.md:可直接用于创建 Release,
含 Breaking Change 清单、新特性、验证方式与实测结果、升级步骤。

docs/IMPLEMENT_v0.3.0.md:
- 按合并后的阶段编号重写实施进度表与阶段标题
  (原「阶段 1 收紧鉴权」与「阶段 2 收口端点」合并为「阶段 1」,后续顺延),
  并说明合并原因:两者只做前者是"有风险无收益"
- 记录本轮实际验证结果

验证:go build / go vet / go test ./... -count=1 全绿。
2026-10-04 01:17:43 +08:00
sun 7b8f557f54 feat(router): v0.3.0 阶段二 管理入口迁移与前端同步
管理入口从 /admin 迁至 /dashboard:
- /dashboard、/dashboard/voices、/dashboard/settings 为新入口
- 原挂在 /dashboard 上的服务状态预览页(health.html)迁至 /dashboard/status,
  侧边栏新增「观测 → 详细状态」入口
- /admin 及子路径 301 永久重定向到对应新路径(页面用 301 是正确的)
- 静态资源同时注册 /dashboard/ 与 /admin/ 两套路径,
  避免过渡期出现"页面能开但丢样式"

前端同步:
- admin-shell.js:侧边栏导航、登出、登录跳转改指 /dashboard/*
- admin.html / admin-login.html / admin-voices.html / admin-settings.html:
  静态资源引用与登录跳转改指 /dashboard/*
- health.html:改用 admin-shell 的 http 实例并改调 /admin/health、/admin/metrics
  (该实例自动附加 Authorization: Bearer;原实现用裸 axios,不带凭证),
  并加登录校验与「返回控制台」入口
- setup.html:安装完成跳转目标改为 /dashboard,页面内 /admin 文案同步更新
- 各页面的 API 调用路径无需修改:axios baseURL 为 /api,
  故 /voices、/admin/overview 等自动落成 /api/admin/*

controller/setup.go:安装成功响应的 redirect 字段由 /admin 改为 /dashboard。

验证:go build / go vet / go test ./... -count=1 全绿;
另用真实服务器端到端验证:旧入口 301 全部正确、静态资源新旧路径均 200、
管理页面内容协商(html 200 / 非 html 401)、登录页公开、
各页面引用的静态资源均为新路径且无残留旧路径。
2026-10-04 01:17:26 +08:00
sun c18cf63518 feat(auth)!: v0.3.0 阶段一 鉴权收紧 + 健康/指标端点收口
本提交由初版方案的「阶段 1」与「阶段 2」合并而成。合并原因:两者是同一件事的两半——
只收紧鉴权而不收口端点,结果是"有风险无收益"(未配凭证的旧部署可能起不来,
而 /health、/dashboard、/metrics 仍匿名可读)。

一、鉴权收紧(原阶段 1)
- RequireAdmin 在凭证列表为空时不再放行。此前 len(keys)==0 直接 next.ServeHTTP,
  导致未配凭证的部署上管理接口完全裸奔,也让后续给端点加鉴权的加固形同虚设。
  现在该情况返回 401 并记录明确日志。
- 新增可选独立管理凭证 admin_key,取值优先级:
  admin_key(DB) > auth_key(DB) > OPENAI_TTS_API_KEY(env)。
  middleware.ValidateAPIKey(业务侧 /v1/audio/speech)保持只看 auth_key,
  于是配置 admin_key 后业务调用方持有的 key 无法访问管理接口,权限隔离成立;
  不配置则回退 auth_key,老部署行为不变。
  新增 PUT /api/admin/settings/admin-key 与旧前缀别名,
  凭证只写不读(GET 仅返回打码值与 admin_key_set / admin_key_source)。
- normal 模式下管理凭证为空时启动期 fail-fast。RequireAdmin 改为拒绝后,
  若此处不拦,服务会正常起来但 /dashboard 与全部 /api/admin/* 都是 401,
  等于把自己锁在门外;宁可启动失败并打印明确原因。

二、端点收口(原阶段 2)
- /health 改为鉴权(原匿名泄漏版本、commit、运行时长、内存、goroutine、配置错误文本)
- /dashboard 改为鉴权,并对浏览器 HTML 请求做内容协商(Accept 含 text/html 时
  返回页面外壳,由前端据 sessionStorage 显示登录视图;非 HTML 请求无凭证一律 401)。
  不做无条件 401 的原因:SPA 登录态存在 sessionStorage、不随请求发送,
  服务端无从判断是否已登录,强行 401 会把"打开看到登录页"变成"打开直接报错"。
  页面外壳不含任何数据,数据全部来自鉴权后的 API。
- /api/setup/status 改为鉴权(原本 normal 模式下仍匿名返回 installed/mode)
- 根路径 /metrics 默认完全不注册(访问 404);配置 METRICS_ALLOW_CIDR 后按内网
  白名单开放,非白名单返回 404 而非 403,不向扫描者确认端点存在。
- 新增 GET /healthz 匿名存活探针,只回 200 与字面量 ok、不含任何字段,解决
  "给 /health 加鉴权后 K8s 探针与 Docker HEALTHCHECK 会一律 401 导致 Pod 反复重启";
  新增 GET /api/admin/health 鉴权版详细健康数据。

IP 白名单中间件复用 GetClientIP(已处理 XFF 与 TRUSTED_PROXY_HOPS);
main.go 启动日志同步改为指向 /healthz 与 /api/admin/health。

BREAKING CHANGE:
1. /health、/dashboard、/api/setup/status 不再匿名可读;根路径 /metrics 需配
   METRICS_ALLOW_CIDR,否则 404。
2. 未配置 auth_key / admin_key / OPENAI_TTS_API_KEY 任一时,normal 模式下服务拒绝启动。
3. K8s 探针与 Docker HEALTHCHECK 必须改指 /healthz;Prometheus 请改用鉴权版
   /api/admin/metrics 或配置 METRICS_ALLOW_CIDR(Docker 中勿填 127.0.0.1/32,
   那是容器自身回环,应填容器内网网段)。

验证:go build / go vet / go test ./... -count=1 全绿(7 个包);
另用真实服务器端到端验证端点矩阵、内容协商、凭证隔离与 CIDR 白名单两种形态。
2026-10-04 01:17:06 +08:00
4 changed files with 9 additions and 73 deletions
-61
View File
@@ -1,61 +0,0 @@
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
+2 -2
View File
@@ -6,8 +6,8 @@
# Go 测试源码:不入库(测试保留在本地磁盘,由开发者自行 go test ./... -count=1)
# 理由:测试用例会暴露内部实现细节与断言,不作为交付物外流。
# 注意:本规则会把测试文件挡在 git 之外,因此仓库内不提供自动化测试;
# .github/workflows/ci.yml 里的测试步骤在纯净克隆上无测试可跑。
# 注意:本规则会把测试文件挡在 git 之外,因此仓库内不提供自动化测试,
# 也没有自动化质量门 —— 守行为回归只能靠开发者在本地执行测试。
*_test.go
# Editor / OS
+3 -6
View File
@@ -79,12 +79,9 @@
- **测试源码不再入库**: `.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 镜像,不做任何编译或测试校验。
⚠️ 代价必须明确:仓库内**不提供自动化测试**,也没有自动化质量门。
守行为回归只能靠开发者在本地(测试文件所在处)执行测试;
CI 仅在发版打 tag 时构建 Docker 镜像。
- **文档订正**: `docs/UI_HANDOFF.md` 原为"单文件换皮"外包任务书,其中的
"admin.html ≤ 35KB / setup.html ≤ 15KB / 只改两个 .html" 等约束在 admin 拆分多页后已作废,
现标注为历史文档并补上当前真实文件结构与验收清单。
+4 -4
View File
@@ -428,14 +428,14 @@ GetVoiceForTTS(name string) (providerName, speakerID, model string, vendorParams
**本项目测试文件不入库**(`.gitignore` 里的 `*_test.go`),
测试保留在本地磁盘。这带来两个直接后果,必须知道:
1. **CI 跑不到你的测试**。`.github/workflows/ci.yml` 里的 `go test` 步骤在干净克隆上
只会打印 `no test files` 然后通过 —— 它只能守住"编译 + vet"。
所以适配器测试**必须在本地跑过再合并**:
1. **没有任何自动化会跑你的测试**。仓库里不提供 CI 质量门:
GitHub 上只有一个 workflow,且它只在**发版打 tag 时构建 Docker 镜像**,
既不编译校验也不跑测试。所以适配器测试**必须在本地跑过再合并**:
```bash
go test ./... -count=1
```
2. **不要依赖测试文件来传递知识**。协议细节、踩坑记录要写进**代码注释**和本文档,
否则对下一个人(以及在 CI 里)等于不存在。
否则对下一个人等于不存在。
适配器测试的**最小可用集合**(按 §2.6 的坑逐条覆盖):