DEPLOYMENT_CHECKLIST.md

# Huggingface Spaces 部署检查清单

## 📋 必须上传的文件清单

### ✅ 核心文件
- [x] `app.py` - HF Spaces入口文件
- [x] `README.md` - 带有正确YAML头的项目说明
- [x] `requirements.txt` - Python依赖
- [x] `packages.txt` - 系统依赖
- [x] `config.toml` - 配置文件

### ✅ 应用代码
- [x] `app/` - 完整应用目录
- [x] `webui/` - Streamlit界面
- [x] `resource/` - 字体和音乐资源

### ✅ 文档文件
- [x] `API_GUIDE.md` - API使用指南
- [x] `DEPLOYMENT_HF.md` - 部署指南
- [x] `.gitignore` - Git忽略文件

## 🚫 不需要上传的文件

### ❌ 开发文件
- [ ] `Dockerfile` - HF不使用Docker构建
- [ ] `.dockerignore` - HF不需要
- [ ] `docker-compose.yml` - 本地开发用
- [ ] `main.py` - 本地启动脚本
- [ ] `webui.bat` / `webui.sh` - 本地脚本
- [ ] `start_hf.sh` - 已集成到app.py

### ❌ 示例和测试文件
- [ ] `config.example.toml` - 示例配置
- [ ] `test/` - 测试目录
- [ ] `docs/` - 文档图片

## 🔧 构建卡住的常见原因及解决方案

### 1. 缺少YAML头部
**问题**: README.md没有正确的YAML配置
**解决**: 确保README.md开头有完整的YAML头部

### 2. 依赖版本冲突
**问题**: requirements.txt中的包版本不兼容
**解决**: 使用优化后的requirements.txt（已修复）

### 3. 系统依赖缺失
**问题**: 缺少ffmpeg等系统依赖
**解决**: 创建packages.txt文件（已创建）

### 4. 启动脚本问题
**问题**: app.py启动逻辑有误
**解决**: 使用优化后的app.py（已修复）

### 5. 配置文件问题
**问题**: config.toml格式错误
**解决**: 检查TOML语法，确保没有语法错误

## 🔍 部署后故障排除

### 检查构建日志
1. 在HF Spaces界面查看"Logs"标签
2. 寻找错误信息，通常出现在：
   - 依赖安装阶段
   - 应用启动阶段

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

#### 错误: "No module named 'xxx'"
```bash
解决: 在requirements.txt中添加缺失的包
```

#### 错误: "Address already in use"
```bash
解决: 检查app.py中的端口配置是否为7860
```

#### 错误: "Permission denied"
```bash
解决: 检查文件权限，确保app.py有执行权限
```

#### 错误: "ffmpeg not found"
```bash
解决: 确保packages.txt包含ffmpeg
```

## 🚀 优化建议

### 性能优化
- 限制最大并发任务数为1
- 使用轻量级依赖版本
- 启用资源限制保护

### 安全优化
- 配置环境变量保护API密钥
- 启用API访问控制
- 移除调试日志中的敏感信息

### 用户体验优化
- 提供清晰的配置指引
- 添加错误处理和用户友好的错误消息
- 支持多语言界面

## 📞 支持信息

如果部署仍然失败，请检查：
1. HF Spaces配额是否足够
2. 是否选择了正确的SDK (Streamlit)
3. 文件是否完整上传
4. YAML配置是否正确