diff --git a/docs/API_CONTRACT.md b/docs/API_CONTRACT.md index b02fae6..fe1f857 100644 --- a/docs/API_CONTRACT.md +++ b/docs/API_CONTRACT.md @@ -21,7 +21,7 @@ | 超时和大小限制 | 上游超时 `120000ms`;请求体最多 `1 MiB`;文本最多 `5000` 字符;未见上游响应大小限制 | `body()` 与 `AbortSignal.timeout(120000)` | | 幂等支持 | 未实现 | 无幂等键、provider task ID 或重复请求去重 | -代码契约已核实;对默认地址的真实最小文本联调返回 `401 Unauthorized`,说明地址可达但当前请求缺少有效鉴权。不能把代码默认值写成已确认的实际部署地址。当前测试服务器没有 TTS 监听端口。 +代码契约已核实;首次无鉴权请求返回 `401 Unauthorized`,配置服务端凭据后最小文本请求已返回 `200 audio/wav`。当前测试服务器没有 TTS 上游监听端口,业务 API 通过固定环境地址访问外部上游。 旧工程自身的业务接口为:登录后 `GET /api/config` 获取模型/音色元数据,`POST /api/tts` 同步返回音频,`GET /api/history` 返回当前用户最多 100 条历史;管理员配置接口为 `/api/admin/config`。Phase 3 只复用上游边界,不复制旧工程用户体系或整套工程。 diff --git a/docs/TTS_UPSTREAM_REQUEST.md b/docs/TTS_UPSTREAM_REQUEST.md index 6eb1777..0ac3324 100644 --- a/docs/TTS_UPSTREAM_REQUEST.md +++ b/docs/TTS_UPSTREAM_REQUEST.md @@ -1,6 +1,6 @@ # TTS 上游资料请求清单 -状态:已取得旧工程代码契约;实际部署状态、完整音色资料和联调授权仍待确认。 +状态:旧工程代码契约和一次真实成功联调已完成;完整音色资料、计量规则和上游高级能力仍待确认。 日期:2026-09-08 ## 已核查范围 @@ -12,7 +12,7 @@ - 测试服务器:当前仅有 PostgreSQL、API、Web、Caddy 和 SSH 监听;未发现 TTS 监听端口或 TTS 服务配置。 - `services/api`:仅实现认证、会话、权益和额度基础;没有 Phase 3 生成路由或上游调用。 - 旧工程没有真实音色语言元数据、异步任务查询、provider task ID 或幂等键实现。 -- 代码默认地址的最小文本联调已执行:返回 `401 Unauthorized`;地址可达,但缺少有效测试鉴权凭据。 +- 代码默认地址首次无鉴权请求返回 `401 Unauthorized`;配置服务端凭据后最小文本请求返回 `200 audio/wav`,地址和凭据当前可用。 - `www_site` 不增加网页端上游地址/API Key 配置后台;Phase 3 只从服务端环境变量 `TTS_UPSTREAM_URL`、`TTS_API_KEY` 和 `TTS_TIMEOUT_SECONDS` 加载配置。 - 测试服务器的配置文件为 root-only `/etc/kaotings/api.env`;API Key 原文不进入响应、前端构建、Git 或普通日志。 @@ -34,8 +34,7 @@ 当前最具体阻断是: -- 需要确认 `43.248.188.28:44480` 是否仍是授权测试地址。 -- 需要提供该地址的有效测试 API Key,或明确其他鉴权方式和服务端注入名称。 -- 需要提供当前可用音色 ID/语言清单和计量规则。 +- 需要提供完整当前音色 ID/语言清单和计量规则;目前只确认代码默认 `default` 可用。 +- 需要确认上游是否支持异步任务、查询、取消、provider task ID、幂等和重试;旧工程代码未实现这些能力。 资料补齐前,Phase 3 不固定生产音色和计量策略,不创建伪造音色,不使用 Mock 成功替代真实联调,不扫描或猜测其他服务地址。 diff --git a/docs/phase-3-report.md b/docs/phase-3-report.md index d2b406d..87373d7 100644 --- a/docs/phase-3-report.md +++ b/docs/phase-3-report.md @@ -2,7 +2,7 @@ 日期:2026-09-08 范围:P3-01 至 P3-07 -状态:任务持久化、额度冻结/释放、Worker 失败路径、历史和访问接口已部署;真实上游成功生成、回放和下载待 API Key/鉴权资料。 +状态:任务持久化、额度冻结/释放、Worker、历史、真实音频回放和下载已部署并完成最小成功联调;高级异常矩阵和上游异步/幂等能力仍待补充。 ## 1. 已实现 @@ -31,23 +31,35 @@ | 失败后冻结 | `0` | | 真实上游最小请求 | `401 Unauthorized` | -当前没有成功音频,因此本轮不能声称真实回放、下载、音频校验和成功消费已通过。不能用 Mock 音频替代。 +配置服务端凭据后重新联调: + +| 项目 | 结果 | +| --- | --- | +| 上游精确路径 | `POST http://43.248.188.28:44480/v1/audio/speech` | +| 最小上游探测 | `200 audio/wav` | +| 业务任务创建 | `202` | +| Worker 最终状态 | `succeeded` | +| 回放接口 | `200`,返回音频字节 | +| 下载接口 | `200`,返回音频字节 | +| 历史查询 | `1` 条记录 | +| 额度 | `10000 -> 9998`,已用 `2`,冻结 `0` | + +成功音频路径已通过最小文本验证;并发争用、Worker 重启、存储失败和上游超时矩阵仍需补测。 ## 3. P3 工作包状态 | 编号 | 状态 | 说明 | | --- | --- | --- | -| P3-01 | 部分完成 | 模型、适配调用和配置边界已实现;缺上游凭据和真实音色资料 | +| P3-01 | 已完成最小真实路径 | 模型、适配调用、默认音色和最小 WAV 联调已通过;完整音色资料待补 | | P3-02 | 已完成负向/基础路径 | 幂等、校验、额度冻结已真实测试;并发争用测试待补 | | P3-03 | 部分完成 | 持久化 Worker 已运行;任务租约、重启恢复和有限重试待加强验证 | -| P3-04 | 部分完成 | 私有存储和结算代码已实现;成功音频路径待真实上游 | -| P3-05 | 已完成布局和任务调用 | 页面已提交、轮询和显示失败;成功音频待联调 | -| P3-06 | 部分完成 | 历史和资源归属接口已实现;回放/下载需成功音频验证 | -| P3-07 | 未完成 | 缺少上游凭据,尚不能完成成功、重启、争用和存储异常全矩阵 | +| P3-04 | 已完成最小真实路径 | 私有存储、checksum、成功消费和失败释放已验证 | +| P3-05 | 已完成最小真实路径 | 页面提交、轮询、成功音频和失败状态已验证 | +| P3-06 | 已完成最小真实路径 | 历史、资源归属、回放和下载已验证 | +| P3-07 | 部分完成 | 正常、上游未配置和成功路径已验证;并发争用、重启恢复、存储失败待补 | ## 4. 阻断项 -- 旧工程默认上游 `http://43.248.188.28:44480` 的最小请求返回 `401`,需要测试 API Key 或其他鉴权凭据。 - 旧工程没有真实音色语言清单;当前只保留代码默认 `default` 标识。 - 旧工程同步返回音频,没有 provider task ID、异步查询或幂等能力;业务 Worker 不能假设上游可安全重试。 diff --git a/infra/scripts/probe-tts-upstream.py b/infra/scripts/probe-tts-upstream.py new file mode 100644 index 0000000..1066ce5 --- /dev/null +++ b/infra/scripts/probe-tts-upstream.py @@ -0,0 +1,16 @@ +import os + +import httpx + + +url = os.environ["TTS_UPSTREAM_URL"].rstrip("/") + "/v1/audio/speech" +headers = {"Content-Type": "application/json"} +if os.environ.get("TTS_API_KEY"): + headers["Authorization"] = f"Bearer {os.environ['TTS_API_KEY']}" +response = httpx.post( + url, + headers=headers, + json={"model": "qwen3-tts", "input": "测试", "voice": "default", "response_format": "wav", "speed": 1}, + timeout=40, +) +print(f"status={response.status_code} content_type={response.headers.get('content-type', '')} bytes={len(response.content)}") diff --git a/infra/scripts/update-tts-env.py b/infra/scripts/update-tts-env.py new file mode 100644 index 0000000..04b3246 --- /dev/null +++ b/infra/scripts/update-tts-env.py @@ -0,0 +1,23 @@ +from pathlib import Path +import sys + + +path = Path("/etc/kaotings/api.env") +url = sys.stdin.readline().rstrip() +key = sys.stdin.readline().rstrip() +values = {"TTS_UPSTREAM_URL": url, "TTS_API_KEY": key} +lines = path.read_text().splitlines() +output = [] +seen = set() +for line in lines: + name = line.split("=", 1)[0] + if name in values: + output.append(f"{name}={values[name]}") + seen.add(name) + else: + output.append(line) +for name, value in values.items(): + if name not in seen: + output.append(f"{name}={value}") +path.write_text("\n".join(output) + "\n") +path.chmod(0o600)