Ai_GirlFriend/开发/2026年2月4日/音乐库唱歌视频部署清单.md

音乐库唱歌视频功能 - 部署清单

📋 部署前检查

1. 文件完整性

• 开发/2026年2月4日/音乐库唱歌视频数据库修改.sql - 数据库修改脚本
• lover/models.py - 数据模型已更新
• lover/routers/music_library.py - 转换 API 已添加
• lover/routers/sing.py - 导入已更新
• test_music_library_sing.py - 测试脚本
• xuniYou/pages/index/index.vue - 前端代码（待修改）

2. 代码质量检查

• Python 语法检查 - 无错误
• 数据模型验证 - 正确
• API 端点验证 - 正确
• 前端代码检查 - 待修改

🚀 部署步骤

步骤 1: 备份数据库 ⚠️ 重要

# 备份整个数据库
mysqldump -u root -p fastadmin > backup_before_music_sing_$(date +%Y%m%d_%H%M%S).sql

# 或者只备份相关表
mysqldump -u root -p fastadmin nf_sing_song_video nf_song_library nf_music_library > backup_music_sing_tables_$(date +%Y%m%d_%H%M%S).sql

• 数据库已备份
• 备份文件已验证

步骤 2: 执行数据库修改（可选但推荐）

mysql -u root -p fastadmin < "开发/2026年2月4日/音乐库唱歌视频数据库修改.sql"

验证:

-- 查看表结构
SHOW COLUMNS FROM nf_sing_song_video;

-- 应该看到新字段：
-- music_library_id
-- music_source

• SQL 执行成功
• 新字段已添加
• 索引已创建

步骤 3: 重启 Python 后端

# 停止现有服务
# Ctrl+C 或关闭终端

# 启动新服务
cd lover
python -m uvicorn main:app --host 0.0.0.0 --port 30101 --reload

验证:

• 服务启动成功
• 无错误日志
• 可以访问 http://localhost:30101/docs
• 可以看到新 API: POST /music/convert-to-song

步骤 4: 测试后端 API

4.1 使用 Swagger UI 测试

1. 访问 http://localhost:30101/docs
2. 找到 POST /music/convert-to-song
3. 点击 "Try it out"
4. 输入 music_id: 1
5. 点击 "Execute"

预期结果:

{
  "code": 1,
  "message": "success",
  "data": {
    "song_id": 123,
    "title": "Sunny",
    "from_cache": false
  }
}

• API 调用成功
• 返回 song_id
• 数据正确

4.2 使用测试脚本

# 1. 编辑测试脚本，设置 TOKEN
notepad test_music_library_sing.py

# 2. 运行测试
python test_music_library_sing.py

• 转换音乐 - 成功
• 拒绝外部链接 - 成功
• 生成视频 - 成功
• 查询任务 - 成功
• 获取历史 - 成功

步骤 5: 修改前端代码

按照 音乐库唱歌视频前端修改指南.md 修改前端代码。

修改位置: xuniYou/pages/index/index.vue

1. 找到 selectMusicFromLibrary 方法（约第 2387 行）
2. 替换方法内容
3. 添加 generateSingVideoFromLibrary 方法
4. 添加 generateSingVideoWithSongId 方法

• 前端代码已修改
• 代码语法正确
• 方法添加完整

步骤 6: 前端测试

6.1 基本功能测试

1. 打开应用
2. 进入"唱歌"页面
3. 切换到"音乐库" tab
4. 点击一首直链音乐（Bensound）
5. 确认生成

预期结果:

• 显示"准备中..."
• 显示"生成中..."
• 自动切换到"历史记录" tab
• 生成成功后显示视频

6.2 外部链接测试

1. 点击一首外部链接音乐（网易云）
2. 查看提示

预期结果:

• 显示"外部平台音乐无法生成视频"提示
• 不会开始生成

6.3 历史记录测试

1. 切换到"历史记录" tab
2. 查看生成的视频

预期结果:

• 显示新生成的视频
• 可以播放视频
• 显示正确的标题

6.4 缓存测试

1. 再次点击相同的音乐
2. 确认生成

预期结果:

• 立即生成成功（有缓存）
• 不需要等待
• 复用之前的视频

✅ 部署后验证

1. 功能验证

• 可以转换音乐为系统歌曲
• 可以生成唱歌视频
• 可以查看历史记录
• 外部链接被正确拒绝
• 缓存机制正常工作

2. 数据验证

-- 查询转换的系统歌曲
SELECT id, title, artist, gender, audio_hash
FROM nf_song_library
WHERE createtime > UNIX_TIMESTAMP(NOW() - INTERVAL 1 DAY)
ORDER BY id DESC
LIMIT 10;

-- 查询生成的视频
SELECT id, user_id, song_id, music_library_id, music_source, status
FROM nf_sing_song_video
WHERE created_at > NOW() - INTERVAL 1 DAY
ORDER BY id DESC
LIMIT 10;

-- 查询生成任务
SELECT id, user_id, task_type, status, payload
FROM nf_generation_tasks
WHERE task_type = 'video'
AND created_at > NOW() - INTERVAL 1 DAY
ORDER BY id DESC
LIMIT 10;

• 数据正确
• 无重复记录
• 关联正确

3. 性能验证

• API 响应时间 < 500ms
• 视频生成时间正常
• 无内存泄漏
• 无数据库连接泄漏

4. 日志检查

# 查看后端日志
tail -f lover/logs/app.log

# 查看数据库日志
tail -f /var/log/mysql/error.log

• 无错误日志
• 无警告日志
• API 调用正常

🔄 回滚计划

如果部署失败，按以下步骤回滚：

1. 恢复数据库

# 恢复备份
mysql -u root -p fastadmin < backup_before_music_sing_YYYYMMDD_HHMMSS.sql

2. 恢复代码

# 使用 Git 回滚
git checkout HEAD~1 lover/models.py
git checkout HEAD~1 lover/routers/music_library.py
git checkout HEAD~1 lover/routers/sing.py
git checkout HEAD~1 xuniYou/pages/index/index.vue

3. 重启服务

cd lover
python -m uvicorn main:app --host 0.0.0.0 --port 30101 --reload

📊 部署结果

成功标准

• ✅ 所有测试通过
• ✅ 无错误日志
• ✅ 性能正常
• ✅ 数据完整
• ✅ 用户体验良好

部署记录

• 部署日期: ___________
• 部署人员: ___________
• 部署结果: [ ] 成功 [ ] 失败
• 问题记录: ___________
• 解决方案: ___________

📞 问题处理

常见问题

问题 1: 转换 API 返回 404

解决方案：
1. 检查后端是否重启
2. 检查 API 路由是否正确
3. 查看后端日志

问题 2: 生成视频失败

解决方案：
1. 检查视频生成次数
2. 检查音乐 URL 是否可访问
3. 检查恋人形象是否存在
4. 查看任务错误信息

问题 3: 前端无法调用 API

解决方案：
1. 检查 TOKEN 是否有效
2. 检查 API 地址是否正确
3. 检查网络连接
4. 查看浏览器控制台

问题 4: 历史记录不显示

解决方案：
1. 刷新页面
2. 检查 API 返回数据
3. 检查数据库记录
4. 查看前端日志

📝 部署签名

• 部署人员: ___________
• 审核人员: ___________
• 部署日期: ___________
• 签名: ___________

---

部署清单版本: 1.0
更新时间: 2026-02-04
状态: 待部署