| # 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配置是否正确 |