9.1 KiB
9.1 KiB
小虾 SaaS 本地验证检查清单
验证目标：确保前后端真实联调通过，为上线做准备
预计时间：30 分钟 - 1 小时
执行人：老大
协助：小虾 🦐
一、环境准备（10 分钟）
1.1 检查系统依赖
# 检查 FFmpeg
ffmpeg -version
# 检查 Python
python --version # 需要 3.12+
# 检查 Node.js
node --version # 需要 18+
预期：
- ✅ FFmpeg 已安装
- ✅ Python 3.12+
- ✅ Node.js 18+
1.2 准备环境变量
位置：F:\openclaw-saas\.env.development
必须配置的项：
# 数据库
DATABASE_URL=postgresql://xiaoxia:xiaoxia123@localhost:5432/xiaoxia_saas
# Redis
REDIS_URL=redis://localhost:6379/0
# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=xiaoxia-saas
MINIO_SECURE=false
MINIO_PUBLIC_URL=http://localhost:9000
# JWT
JWT_SECRET_KEY=your-super-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
# Celery
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/2
检查方式：
cd F:\openclaw-saas
cat .env.development
1.3 启动基础设施
方式 1：Docker Compose（推荐）
cd F:\openclaw-saas\infra\docker
docker-compose up -d postgres redis minio
方式 2：本地服务
- PostgreSQL 手动启动
- Redis 手动启动
- MinIO 手动启动
验证：
# 检查 PostgreSQL
psql -h localhost -U xiaoxia -d xiaoxia_saas -c "SELECT 1;"
# 检查 Redis
redis-cli ping
# 检查 MinIO
curl http://localhost:9000/minio/health/live
预期：
- ✅ PostgreSQL 连接成功
- ✅ Redis 返回 PONG
- ✅ MinIO 返回 200 OK
1.4 安装依赖
后端依赖：
cd F:\openclaw-saas
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
前端依赖：
cd F:\openclaw-saas\apps\web
npm install
预期时间：5-10 分钟
1.5 初始化数据库
cd F:\openclaw-saas
.venv\Scripts\activate
# 运行数据库迁移
# （如果有 alembic）
# alembic upgrade head
# 或者直接运行 SQL
psql -h localhost -U xiaoxia -d xiaoxia_saas -f migrations/001_initial_schema.sql
psql -h localhost -U xiaoxia -d xiaoxia_saas -f migrations/004_asset_management.sql
验证：
psql -h localhost -U xiaoxia -d xiaoxia_saas -c "\dt"
预期：看到所有表（users, workspaces, assets, generation_tasks 等）
二、启动服务（5 分钟）
2.1 启动 API 服务
终端 1：
cd F:\openclaw-saas
.venv\Scripts\activate
cd apps\api
python main.py
预期输出：
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
验证：
curl http://localhost:8000/api/v1/health
预期响应：
{"status": "healthy"}
2.2 启动 Worker 服务
终端 2：
cd F:\openclaw-saas
.venv\Scripts\activate
cd apps\worker
celery -A celery_app worker --loglevel=info
预期输出：
[tasks]
. worker.generate_video
celery@LAPTOP ready.
2.3 启动前端服务
终端 3：
cd F:\openclaw-saas\apps\web
npm run dev
预期输出：
VITE v5.x.x ready in xxx ms
➜ Local: http://localhost:5173/
三、功能验证（15-30 分钟）
3.1 用户注册/登录
步骤：
- 打开浏览器：
http://localhost:5173 - 点击"注册"
- 填写信息：
- 邮箱：
test@example.com - 密码：
Test123456 - 用户名：
测试用户
- 邮箱：
- 点击注册
- 使用刚注册的账号登录
检查点：
- 注册成功
- 登录成功
- 跳转到工作空间页面
预期时间：2 分钟
3.2 创建工作空间和项目
步骤：
- 点击"创建工作空间"
- 填写名称：
测试工作空间 - 创建成功后，点击进入
- 点击"创建项目"
- 填写项目名称：
测试项目
检查点：
- 工作空间创建成功
- 项目创建成功
- 能看到项目详情页
预期时间：2 分钟
3.3 上传素材
步骤：
- 进入项目
- 点击"素材管理"
- 点击"上传素材"
- 选择 2-3 个视频文件（MP4 格式）
- 等待上传完成
检查点：
- 上传进度条显示
- 上传成功提示
- 素材列表显示上传的文件
- 能看到缩略图
预期时间：3-5 分钟（取决于文件大小）
调试检查（如果上传失败）：
# 查看 API 日志（终端 1）
# 查看 MinIO 存储
curl http://localhost:9000 # 应该能访问
3.4 素材分类
步骤：
- 在素材列表中选择一个素材
- 点击"分类"
- 等待分类完成
检查点：
- 分类任务创建成功
- 分类状态显示为"处理中"
- 分类完成后显示结果（如：scenic, product, person 等）
预期时间：1-2 分钟
调试检查（如果分类卡住）：
# 查看 Worker 日志（终端 2）
# 应该看到分类任务执行
3.5 创建生成任务
步骤：
- 点击"视频生成"
- 选择素材库
- 选择生成策略（如果有）
- 点击"开始生成"
检查点：
- 生成任务创建成功
- 任务状态显示为"队列中"或"处理中"
- 进度条更新
预期时间：1 分钟
3.6 等待生成完成
步骤：
- 刷新页面或等待自动刷新
- 查看任务状态
检查点：
- 任务状态变为"已完成"
- 进度条显示 100%
- 显示生成的视频数量
预期时间：2-5 分钟（取决于素材数量和大小）
调试检查（如果生成失败）：
# 查看 Worker 日志（终端 2）
# 应该看到：
# - 素材下载
# - FFmpeg 执行
# - 文件上传
3.7 查看生成结果
步骤：
- 点击"生成结果"
- 查看生成的视频列表
- 点击某个视频
检查点：
- 能看到视频列表
- 显示缩略图
- 显示视频元数据（时长、分辨率、大小）
预期时间：1 分钟
3.8 下载视频
步骤：
- 在视频详情页点击"下载"
- 浏览器开始下载
- 下载完成后播放视频
检查点：
- 下载链接正常
- 文件下载成功
- 视频能正常播放
- 视频内容是多个素材的拼接
预期时间：2-3 分钟
最终验证：
- 播放器能打开
- 画面流畅
- 没有黑屏或错误
四、问题记录
发现的问题
| 序号 | 功能点 | 问题描述 | 严重程度 |
|---|---|---|---|
| 1 | P0/P1/P2 | ||
| 2 | |||
| 3 |
严重程度定义：
- P0：阻断上线（如：无法登录、无法生成）
- P1：影响体验（如：UI 错位、加载慢）
- P2：小问题（如：文字错误、样式小瑕疵）
五、验收标准
✅ 通过标准
核心流程必须全部通过：
- 用户注册/登录
- 创建工作空间/项目
- 上传素材
- 素材分类
- 创建生成任务
- 生成完成
- 查看结果
- 下载视频
无 P0 问题
⚠️ 有条件通过
核心流程通过，但有 P1 问题：
- 可以先修复后上线
- 或者标注已知问题后上线
❌ 不通过
任何核心流程失败，或有 P0 问题：
- 必须修复后再验证
- 不能上线
六、验证完成后
✅ 如果通过
下一步：
- 小虾准备生产部署脚本
- 部署到服务器
- 绑定域名
- 开放访问
⚠️ 如果有问题
下一步：
- 老大记录问题到上面的表格
- 小虾立刻修复 P0 问题
- P1/P2 问题排期修复
- 修复后再次验证
七、验证提示
💡 验证技巧
-
别着急
- 每个步骤都看清楚
- 发现问题立刻截图
-
多试几次
- 如果某个功能失败，试 2-3 次
- 确认是真的有问题，不是网络抖动
-
记录详细
- 问题描述要具体（不是"不行"，而是"点击后无响应"）
- 最好有截图或错误信息
-
随时叫小虾
- 遇到问题不确定的，立刻问我
- 我可以远程看日志帮你诊断
八、常见问题
Q1: MinIO 连不上
症状：上传素材失败
解决：
# 检查 MinIO 是否启动
docker ps | grep minio
# 重启 MinIO
docker restart minio
Q2: Worker 没反应
症状：分类/生成任务一直"处理中"
解决：
# 检查 Worker 日志（终端 2）
# 如果没有任务输出，重启 Worker
Ctrl+C
celery -A celery_app worker --loglevel=info
Q3: 前端报错
症状：浏览器控制台有红色错误
解决：
- F12 打开开发者工具
- 截图错误信息
- 发给小虾
Q4: 视频生成失败
症状：任务状态变为"失败"
解决：
# 查看 Worker 日志（终端 2）
# 找到错误信息
# 发给小虾
检查清单创建完成！
老大，现在可以开始验证了！
小虾待命中 🦐
有问题随时叫我！