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] `.gitignore` - Git忽略文件

## 🚫 不需要上传的文件

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

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

## 🔧 API密钥配置优先级

### 配置方式选择
1. **HF Spaces环境变量** (推荐) - 更安全，自动加载
2. **WebUI界面配置** - 简单直观，适合测试

### 环境变量配置
在HF Spaces的Settings → Repository secrets中配置：

```bash

# 核心API密钥

MONEYPRINTER_API_KEY=your_api_key_here    # 用于外部API调用



# LLM服务（至少选择一个）

DEEPSEEK_API_KEY=your_deepseek_key        # 推荐

MOONSHOT_API_KEY=your_moonshot_key        # 推荐

OPENAI_API_KEY=your_openai_key



# 视频素材源（至少选择一个）

PEXELS_API_KEY=your_pexels_key            # 推荐

PIXABAY_API_KEY=your_pixabay_key



# 可选服务

AZURE_SPEECH_KEY=your_azure_key

AZURE_SPEECH_REGION=eastus

```

### 配置说明
- 环境变量会在启动时自动加载到config.toml
- 如果同时配置了环境变量和WebUI，环境变量优先
- 未配置环境变量时，可在WebUI中手动配置

## 🚀 使用方式

### 1. 仅WebUI使用
- 在左侧配置面板设置API密钥
- 通过界面生成视频

### 2. API调用
- 需要设置`MONEYPRINTER_API_KEY`环境变量
- 使用该密钥调用外部API接口
- 详见`API_GUIDE.md`

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

### 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. HF Spaces配额是否足够
2. 是否选择了正确的SDK (Streamlit)
3. 文件是否完整上传
4. YAML配置是否正确