xiaoxia-saas/docs/本地验证检查清单.md

小虾 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
OSS_ENDPOINT=localhost:9000
OSS_ACCESS_KEY_ID=minioadmin
OSS_ACCESS_KEY_SECRET=minioadmin
OSS_BUCKET_NAME=xiaoxia-saas
OSS_SECURE=false
OSS_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 用户注册/登录

步骤：

1. 打开浏览器：http://localhost:5173
2. 点击"注册"
3. 填写信息：
   • 邮箱：test@example.com
   • 密码：Test123456
   • 用户名：测试用户
4. 点击注册
5. 使用刚注册的账号登录

检查点：

• 注册成功
• 登录成功
• 跳转到工作空间页面

预期时间：2 分钟

---

3.2 创建工作空间和项目

步骤：

1. 点击"创建工作空间"
2. 填写名称：测试工作空间
3. 创建成功后，点击进入
4. 点击"创建项目"
5. 填写项目名称：测试项目

检查点：

• 工作空间创建成功
• 项目创建成功
• 能看到项目详情页

预期时间：2 分钟

---

3.3 上传素材

步骤：

1. 进入项目
2. 点击"素材管理"
3. 点击"上传素材"
4. 选择 2-3 个视频文件（MP4 格式）
5. 等待上传完成

检查点：

• 上传进度条显示
• 上传成功提示
• 素材列表显示上传的文件
• 能看到缩略图

预期时间：3-5 分钟（取决于文件大小）

调试检查（如果上传失败）：

# 查看 API 日志（终端 1）
# 查看 MinIO 存储
curl http://localhost:9000  # 应该能访问

---

3.4 素材分类

步骤：

1. 在素材列表中选择一个素材
2. 点击"分类"
3. 等待分类完成

检查点：

• 分类任务创建成功
• 分类状态显示为"处理中"
• 分类完成后显示结果（如：scenic, product, person 等）

预期时间：1-2 分钟

调试检查（如果分类卡住）：

# 查看 Worker 日志（终端 2）
# 应该看到分类任务执行

---

3.5 创建生成任务

步骤：

1. 点击"视频生成"
2. 选择素材库
3. 选择生成策略（如果有）
4. 点击"开始生成"

检查点：

• 生成任务创建成功
• 任务状态显示为"队列中"或"处理中"
• 进度条更新

预期时间：1 分钟

---

3.6 等待生成完成

步骤：

1. 刷新页面或等待自动刷新
2. 查看任务状态

检查点：

• 任务状态变为"已完成"
• 进度条显示 100%
• 显示生成的视频数量

预期时间：2-5 分钟（取决于素材数量和大小）

调试检查（如果生成失败）：

# 查看 Worker 日志（终端 2）
# 应该看到：
# - 素材下载
# - FFmpeg 执行
# - 文件上传

---

3.7 查看生成结果

步骤：

1. 点击"生成结果"
2. 查看生成的视频列表
3. 点击某个视频

检查点：

• 能看到视频列表
• 显示缩略图
• 显示视频元数据（时长、分辨率、大小）

预期时间：1 分钟

---

3.8 下载视频

步骤：

1. 在视频详情页点击"下载"
2. 浏览器开始下载
3. 下载完成后播放视频

检查点：

• 下载链接正常
• 文件下载成功
• 视频能正常播放
• 视频内容是多个素材的拼接

预期时间：2-3 分钟

最终验证：

• 播放器能打开
• 画面流畅
• 没有黑屏或错误

---

四、问题记录

发现的问题

序号	功能点	问题描述	严重程度
1			P0/P1/P2
2
3

严重程度定义：

• P0：阻断上线（如：无法登录、无法生成）
• P1：影响体验（如：UI 错位、加载慢）
• P2：小问题（如：文字错误、样式小瑕疵）

---

五、验收标准

✅ 通过标准

核心流程必须全部通过：

• 用户注册/登录
• 创建工作空间/项目
• 上传素材
• 素材分类
• 创建生成任务
• 生成完成
• 查看结果
• 下载视频

无 P0 问题

---

⚠️ 有条件通过

核心流程通过，但有 P1 问题：

• 可以先修复后上线
• 或者标注已知问题后上线

---

❌ 不通过

任何核心流程失败，或有 P0 问题：

• 必须修复后再验证
• 不能上线

---

六、验证完成后

✅ 如果通过

下一步：

1. 小虾准备生产部署脚本
2. 部署到服务器
3. 绑定域名
4. 开放访问

⚠️ 如果有问题

下一步：

1. 老大记录问题到上面的表格
2. 小虾立刻修复 P0 问题
3. P1/P2 问题排期修复
4. 修复后再次验证

---

七、验证提示

💡 验证技巧

1. 别着急

   • 每个步骤都看清楚
   • 发现问题立刻截图

2. 多试几次

   • 如果某个功能失败，试 2-3 次
   • 确认是真的有问题，不是网络抖动

3. 记录详细

   • 问题描述要具体（不是"不行"，而是"点击后无响应"）
   • 最好有截图或错误信息

4. 随时叫小虾

   • 遇到问题不确定的，立刻问我
   • 我可以远程看日志帮你诊断

---

八、常见问题

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）
# 找到错误信息
# 发给小虾

---

检查清单创建完成！

老大，现在可以开始验证了！

---

小虾待命中 🦐
有问题随时叫我！