feat(tts): 正式合成支持克隆音色 + 保存到配音库改写 assets 素材体系 + 克隆接口支持 asset_id #1556

Merged

auto-approve-bot merged 10 commits from fix/tts-clone-voice-and-save-to-assets into develop 2026-08-30 18:46:07 +08:00

Conversation 5 Commits 10 Files Changed 10

+1353 -79

xiaoxia commented 2026-08-30 16:13:15 +08:00

Owner

Copy Link

Copy Source

配音库 3 个后端修复：

1. TTS 正式合成支持克隆音色：synthesize() 复用 preview 的克隆音色解析——voice_id 传克隆 profile UUID 时校验归属(403)/克隆完成状态(400)，job.voice_id 存解析后的 CosyVoice id，voice_clone_profile_id 记录 profile。
2. 保存到配音库改写 assets 素材体系：TTS 音频持久化独立副本到 uploads/voice/tts/，创建 audio/ready 的 asset 挂用户 voice 素材库（无则自动创建），metadata 记录 source=tts_job；返回结构保持 id/name/audio_url/duration 兼容；切断旧 voice_library 表写入。
3. 克隆接口支持 asset_id：校验素材归属与音频类型，用 storage_key 生成 7 天签名 URL 供 worker 下载；source_audio_url 保留兼容。

测试：tts/voice 专项 467 passed；新增 synthesize 克隆 4 用例、save-to-library asset 断言、clone from asset 5 用例。

配音库 3 个后端修复： 1. **TTS 正式合成支持克隆音色**：`synthesize()` 复用 preview 的克隆音色解析——voice_id 传克隆 profile UUID 时校验归属(403)/克隆完成状态(400)，job.voice_id 存解析后的 CosyVoice id，voice_clone_profile_id 记录 profile。 2. **保存到配音库改写 assets 素材体系**：TTS 音频持久化独立副本到 `uploads/voice/tts/`，创建 audio/ready 的 asset 挂用户 voice 素材库（无则自动创建），metadata 记录 source=tts_job；返回结构保持 id/name/audio_url/duration 兼容；切断旧 voice_library 表写入。 3. **克隆接口支持 asset_id**：校验素材归属与音频类型，用 storage_key 生成 7 天签名 URL 供 worker 下载；source_audio_url 保留兼容。 测试：tts/voice 专项 467 passed；新增 synthesize 克隆 4 用例、save-to-library asset 断言、clone from asset 5 用例。

xiaoxia added 1 commit 2026-08-30 16:13:15 +08:00

feat(tts): 正式合成支持克隆音色、保存到配音库改写 assets 素材体系、克隆接口支持 asset_id ... 539c71f5cb

1. TTS synthesize() 复用 preview 的克隆音色解析逻辑：voice_id 传克隆 profile UUID 时
   校验归属(403)/克隆完成状态(400 音色克隆尚未完成)，job.voice_id 存解析后的
   CosyVoice voice_id，voice_clone_profile_id 记录 profile id。
2. save_tts_job_to_library 改写为新素材体系：TTS 音频持久化独立副本到
   uploads/voice/tts/，创建 file_type=audio/status=ready 的 asset 挂用户 voice
   素材库（无则自动创建），duration/metadata(source=tts_job) 完整记录；
   返回结构保持 id/name/audio_url/duration 兼容前端；移除旧 voice_library 表写入。
3. voice clone 创建接口支持 asset_id 字段：校验素材归属与音频类型，用 asset
   storage_key 生成 7 天有效签名 URL 供 worker 下载，不依赖前端签名；
   source_audio_url 方式保留兼容。

补集成测试：synthesize 克隆音色 4 用例、save-to-library asset 断言、
clone from asset 5 用例（成功/404/403/非音频400/两参同传400）。

gitea-actions bot commented 2026-08-30 16:16:29 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1556
预览链接	https://pr-1556.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1556 | | 预览链接 | [https://pr-1556.preview.xiaoxiajianji.com](https://pr-1556.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot approved these changes 2026-08-30 16:20:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-30 16:20:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-30 16:32:33 +08:00

fix(tts): 修复 AI Review 阻塞问题——克隆音色解析强制生效 + 素材库并发创建防护 ... afa7fae921

1. synthesize() 克隆音色解析修复：原逻辑仅在 voice_id == profile UUID 时才把
   actual_voice_id 替换为克隆 CosyVoice id，导致 voice_id 传预置音色+显式传
   voice_clone_profile_id 时仍用预置音色合成、与记录的 profile 不一致。
   改为命中 profile 并校验通过后一律 actual_voice_id = resolved_profile.voice_id。
   补回归用例（老测试只断言 201，未覆盖解析结果）。
2. 自动创建 voice 素材库并发竞态：新增 migration 058 给 asset_libraries
   加 (project_id, kind) 唯一索引（model 同步 UniqueConstraint，staging
   2137 条数据无重复可安全建索引）；创建处捕获 IntegrityError 回滚后重查，
   返回抢先创建成功的库。
3. 明确 download_asset 自动识别 URL/OSS key 的注释（Review 第 1 条为误报，
   SharedStorageService.download_asset 对 http(s):// 前缀走 HTTP 下载）。

xiaoxia added 1 commit 2026-08-30 16:37:38 +08:00

fix(migration): 缩短 revision id 至 29 字符（alembic_version.version_num 为 varchar(32)） 30ffd3bb89

xiaoxia added 1 commit 2026-08-30 17:04:37 +08:00

test(tts): 补路由级单元测试满足 CI 增量覆盖率门槛 ... 204715b155

CI Unit Tests job 仅跑 tests/unit，原新增用例都在 tests/integration 不被统计，
diff 覆盖率 15% 未达 40% 门槛。新增 3 个单元测试文件共 22 用例：
- test_tts_save_to_library_assets.py：save-to-library 写 assets 链路
  （成功断言 audio/ready asset、自动建库、IntegrityError 竞态兜底、
  未完成 400、无音频 400、下载失败 502、无项目 400、他人 job 404）
- test_tts_synthesize_clone_voice.py：synthesize 克隆音色解析
  （profile UUID/显式 profile id/预置+profile 同传以克隆为准/403/400/404/预置透传）
- test_voice_clone_from_asset.py：克隆接口 asset_id 分支
  （成功签名 URL、两参同传 400、404、403、非音频 400、无 key 400、旧 URL 流程兼容）

本地 diff 覆盖率 92%。

xiaoxia added 1 commit 2026-08-30 17:13:12 +08:00

style: 修复测试 E741 模糊变量名 l → lib、移除未使用 import 16536c6c9a

auto-approve-bot added 1 commit 2026-08-30 17:19:10 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 352f2d85e1

xiaoxia added 1 commit 2026-08-30 17:37:14 +08:00

fix(tts): AI Review 阻塞项——去除竞态处理中对 repository 内部 session 的依赖 ... 17748d356b

IntegrityError 后不再手动 getattr(repo, 'session').rollback()：
SQLAlchemy commit 失败时 session 已自动回滚，直接重查已存在的库即可，
避免依赖 repository 内部实现（scoped_session/async session 下可能失效）。

同时 mypy：_find_or_create_voice_library 的 asset_library_repository 参数
改 Any 类型（port Protocol 声明 async、SQLAlchemy 实现为同步，与
upload/asset_libraries 路由既有惯例一致）。

xiaoxia added 1 commit 2026-08-30 17:48:28 +08:00

fix(tts): AI Review 第二轮——migration 去重清洗 + session 回滚容错 ... e70939031d

1. migration 058：create unique index 前先按 (project_id, kind) 分区
   ROW_NUMBER 去重（保留 created_at 最新），防止存量重复导致建索引失败阻塞部署。
2. _find_or_create_voice_library 竞态处理：IntegrityError 后显式 rollback
   （立即 commit 模式下为幂等 no-op，UoW/flush 模式下必须回滚才能继续查询），
   rollback 本身抛异常（session 已关闭）时容错继续重查。补对应用例。
3. voice_clones：移除 file_type 的 hasattr 防御判断（Asset 领域对象确定有该字段）。

xiaoxia added 1 commit 2026-08-30 17:59:33 +08:00

fix(tts): AI Review 第三轮——约束类型一致 + OSS 孤儿文件清理 + import 规范 ... 0454d2a97e

1. migration 058 改用 op.create_unique_constraint（与 model 的 UniqueConstraint
   定义一致，pg_constraint+pg_index 同时注册），避免 autogenerate schema drift。
2. save-to-library：asset_repository.create 失败时删除已上传的 OSS 文件，
   避免孤儿文件；补对应用例。
3. tempfile/Path import 移到模块顶部（PEP8）。

xiaoxia added 1 commit 2026-08-30 18:22:25 +08:00

style: B904 — except 中 raise HTTPException 补 from None b3acc755ae

auto-approve-bot commented 2026-08-30 18:30:37 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：通过
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

1. [apps/api/app/api/routes/tts.py: 447] 建议增加幂等性检查

   • 具体内容：在 save_tts_job_to_library 函数中，如果同一个 TTS Job 被多次保存，会在 assets 表中创建多条记录，虽然它们指向同一个 OSS 文件（会被覆盖），但会产生冗余的数据库记录。建议在创建 Asset 前先查询是否已存在该 tts_job_id 对应的 Asset，若存在则直接返回，实现幂等性。

2. [apps/api/app/api/routes/tts.py: 413] 确认 URL 下载的安全性

   • 具体内容：代码中 download_source = job.output_audio_key or job.output_audio_url，如果 job.output_audio_url 可被用户控制（非仅由后端 CosyVoice 服务写入），直接调用 storage_service.download_asset 可能存在 SSRF（服务端请求伪造）风险。请确认 output_audio_url 的来源完全可信，或在 download_asset 中增加对内网地址的限制。

✅ 良好实践

1. 并发处理：在 _find_or_create_voice_library 中正确使用了 IntegrityError 捕获和 session.rollback() 来处理并发创建素材库的竞态条件，保证了数据一致性。
2. 资源清理：在 save_tts_job_to_library 中，当数据库写入失败时，能够正确清理已上传的 OSS 文件，有效避免了垃圾文件的堆积。
3. 权限校验：在 voice_clones.py 中，通过 asset.project_id 关联查询 project 并校验 can_access，实现了基于项目归属的细粒度权限控制，防止了越权访问素材。
4. 数据迁移：Alembic 迁移脚本中使用了 ROW_NUMBER() 窗口函数并在子查询中包裹，符合 PostgreSQL 等数据库的语法规范，能够安全地清洗历史重复数据。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-30 10:30:37 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/api/app/api/routes/tts.py: 447] 建议增加幂等性检查** - 具体内容：在 `save_tts_job_to_library` 函数中，如果同一个 TTS Job 被多次保存，会在 `assets` 表中创建多条记录，虽然它们指向同一个 OSS 文件（会被覆盖），但会产生冗余的数据库记录。建议在创建 Asset 前先查询是否已存在该 `tts_job_id` 对应的 Asset，若存在则直接返回，实现幂等性。 2. **[apps/api/app/api/routes/tts.py: 413] 确认 URL 下载的安全性** - 具体内容：代码中 `download_source = job.output_audio_key or job.output_audio_url`，如果 `job.output_audio_url` 可被用户控制（非仅由后端 CosyVoice 服务写入），直接调用 `storage_service.download_asset` 可能存在 SSRF（服务端请求伪造）风险。请确认 `output_audio_url` 的来源完全可信，或在 `download_asset` 中增加对内网地址的限制。 ### ✅ 良好实践 1. **并发处理**：在 `_find_or_create_voice_library` 中正确使用了 `IntegrityError` 捕获和 `session.rollback()` 来处理并发创建素材库的竞态条件，保证了数据一致性。 2. **资源清理**：在 `save_tts_job_to_library` 中，当数据库写入失败时，能够正确清理已上传的 OSS 文件，有效避免了垃圾文件的堆积。 3. **权限校验**：在 `voice_clones.py` 中，通过 `asset.project_id` 关联查询 `project` 并校验 `can_access`，实现了基于项目归属的细粒度权限控制，防止了越权访问素材。 4. **数据迁移**：Alembic 迁移脚本中使用了 `ROW_NUMBER()` 窗口函数并在子查询中包裹，符合 PostgreSQL 等数据库的语法规范，能够安全地清洗历史重复数据。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-30 10:30:37 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit 61295b9c25 into develop 2026-08-30 18:46:07 +08:00

auto-approve-bot deleted branch fix/tts-clone-voice-and-save-to-assets 2026-08-30 18:46:07 +08:00

gitea-actions bot commented 2026-08-30 18:50:58 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1556 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1556 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1556