# 部署前检查清单

## 文件信息
- **文件路径**: DEPLOY_CHECKLIST.md
- **创建时间**: 2025-12-16
- **开发者**: aidaox

## 在推送到 Hugging Face 之前，请逐项检查：

### ✅ 1. 依赖配置检查

- [ ] **requirements.txt** 使用 `onnxruntime`（不是 `onnxruntime-gpu`）
- [ ] 所有依赖包都有明确的版本号或兼容版本范围
- [ ] `gradio` 版本 >= 5.29.0（与 README.md 中的 sdk_version 一致）
- [ ] `packages.txt` 只包含系统包（如 `ffmpeg`），不包含 Python 包

### ✅ 2. 代码兼容性检查

- [ ] **SinglePhoto.py** 中的 `ctx_id` 配置：
  - 当前使用 `ctx_id=0`（会自动回退到 CPU，通常可用）
  - 如果 Hugging Face 上出现问题，考虑改为 `ctx_id=-1`（明确使用 CPU）
- [ ] 没有硬编码的本地路径（如 `C:\Users\...`、`/home/user/...`）
- [ ] 所有文件路径使用相对路径
- [ ] 没有引用本地不存在的文件或目录

### ✅ 3. 文件完整性检查

- [ ] `app.py` 存在且可以正常导入
- [ ] `README.md` 中的 `app_file: app.py` 配置正确
- [ ] `inswapper_128.onnx` 模型文件存在（或会在运行时自动下载）
- [ ] 所有必要的 Python 模块文件都存在：
  - [ ] `SinglePhoto.py`
  - [ ] `VideoSwapping.py`
  - [ ] `app.py`

### ✅ 4. 功能测试检查

- [ ] 本地运行 `python test_local.py` 所有检查通过
- [ ] 本地运行 `python app.py` 可以正常启动
- [ ] 测试单张图片换脸功能正常
- [ ] 检查日志输出，没有错误或警告

### ✅ 5. 性能优化检查（针对免费 CPU 服务器）

- [ ] 图片处理大小限制合理（建议不超过 1024x1024）
- [ ] 视频处理有合理的时长限制提示
- [ ] 长时间运行的操作有超时处理
- [ ] 临时文件及时清理（代码中已有清理逻辑）

### ✅ 6. Git 提交检查

- [ ] 所有修改已添加到暂存区：`git add .`
- [ ] 提交信息清晰描述修改内容
- [ ] 没有提交敏感信息（如 API keys、tokens）
- [ ] 没有提交不必要的文件（如 `__pycache__`、`.pyc` 文件）

### ✅ 7. 文档检查

- [ ] `README.md` 中的配置信息正确
- [ ] 项目描述清晰
- [ ] 必要的使用说明已添加

## 快速检查命令

在推送前，运行以下命令进行快速检查：

```bash
# 1. 检查 requirements.txt 是否包含 GPU 依赖
grep -i "gpu" requirements.txt
# 应该没有输出，如果有 onnxruntime-gpu，需要改为 onnxruntime

# 2. 检查是否有硬编码路径
grep -r "C:\\\\Users" . --include="*.py"
grep -r "/home/" . --include="*.py"
# 应该没有输出

# 3. 运行本地测试
python test_local.py

# 4. 检查 Git 状态
git status
```

## 推送步骤

1. **提交所有修改**：
   ```bash
   git add .
   git commit -m "修复 CPU 兼容性并添加测试脚本"
   ```

2. **推送到 Hugging Face**：
   ```bash
   git push origin main
   ```

3. **在 Hugging Face 上验证**：
   - 访问 https://huggingface.co/spaces/aidao/FaceSwap
   - 等待构建完成（查看 "Logs" 标签页）
   - 测试应用功能
   - 检查是否有错误

## 如果部署失败

### 检查构建日志

1. 在 Hugging Face Space 页面点击 "Logs" 标签
2. 查看错误信息
3. 常见问题：
   - 依赖安装失败 → 检查 `requirements.txt`
   - 系统包缺失 → 检查 `packages.txt`
   - 代码错误 → 检查本地测试是否通过
   - 内存不足 → 优化代码，减少内存使用

### 常见错误及解决方法

| 错误 | 可能原因 | 解决方法 |
|------|---------|---------|
| `ModuleNotFoundError` | 依赖未安装 | 检查 `requirements.txt` |
| `onnxruntime` 相关错误 | 使用了 GPU 版本 | 确保使用 `onnxruntime`（CPU 版本） |
| `ffmpeg` 相关错误 | 系统包缺失 | 确保 `packages.txt` 包含 `ffmpeg` |
| 内存不足 | 处理大文件 | 限制输入文件大小 |
| 超时 | 处理时间过长 | 优化代码或添加超时处理 |

## 部署后验证

- [ ] Space 构建成功（无错误日志）
- [ ] 应用界面正常加载
- [ ] 可以上传图片
- [ ] 单张图片换脸功能正常
- [ ] 日志输出正常（无错误）

## 性能监控

部署后注意观察：
- 应用启动时间
- 单次处理时间
- 内存使用情况
- 是否有超时错误

如果性能问题严重，考虑：
- 优化图片处理大小
- 添加缓存机制
- 限制并发请求