File size: 4,245 Bytes
59bd45e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | # 🚀 Hugging Face Spaces 部署指南
## ✅ 部署前检查清单
### 1. 根目录必需文件
确保以下文件在**根目录**（不是子目录）：
- ✅ `Dockerfile` - Docker 构建配置
- ✅ `start.py` - 应用启动脚本
- ✅ `requirements.txt` - Python 依赖
- ✅ `README_HF.md` - Hugging Face 专用 README（带 frontmatter）
### 2. 前端构建文件
确保前端已构建：
```bash
cd frontend
npm install
npm run build
```
检查 `frontend/dist/` 目录是否存在且包含：
- ✅ `index.html`
- ✅ `assets/` 目录（包含 JS 和 CSS 文件）
### 3. 环境变量配置
在 Hugging Face Space 的 **Settings → Variables and secrets** 中配置：
**必需：**
- `ZHIPU_API_KEY` - 智谱 AI API 密钥
**可选：**
- `MINIMAX_API_KEY` - MiniMax API 密钥
- `MINIMAX_GROUP_ID` - MiniMax Group ID
### 4. README 配置
确保 `README_HF.md` 包含正确的 frontmatter：
```yaml
---
title: Nora - 治愈系记录助手
emoji: 🌟
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: mit
---
```
## 🔧 部署步骤
### 方法 1：通过 GitHub 同步（推荐）
1. **提交所有更改到 GitHub**：
```bash
git add .
git commit -m "Fix: Add required files to root directory for HF deployment"
git push origin main
```
2. **在 Hugging Face Space 中同步**：
- 进入你的 Space：https://huggingface.co/spaces/kernel14/Nora
- 点击 **Settings**
- 找到 **Sync from GitHub** 部分
- 点击 **Sync now**
3. **等待构建完成**：
- 查看 **Logs** 标签页
- 等待 Docker 构建完成（可能需要 5-10 分钟）
### 方法 2：直接上传文件
1. **在 Hugging Face Space 中上传文件**：
- 进入 **Files** 标签页
- 上传以下文件到根目录：
- `Dockerfile`
- `start.py`
- `requirements.txt`
- `README_HF.md`（重命名为 `README.md`）
2. **上传应用代码**：
- 上传 `app/` 目录
- 上传 `data/` 目录
- 上传 `frontend/dist/` 目录
3. **触发重新构建**：
- 点击 **Factory reboot**
## 🐛 常见问题
### 问题 1：Space 显示 "Missing app file"
**原因**：根目录缺少 `Dockerfile` 或 `start.py`
**解决方案**：
1. 确认根目录有 `Dockerfile` 和 `start.py`
2. 如果使用 GitHub 同步，确保这些文件已提交并推送
3. Factory reboot 重启 Space
### 问题 2：Docker 构建失败
**原因**：依赖安装失败或文件路径错误
**解决方案**：
1. 查看 **Logs** 标签页的详细错误信息
2. 检查 `requirements.txt` 是否正确
3. 检查 `Dockerfile` 中的路径是否正确
### 问题 3：前端无法加载
**原因**：`frontend/dist/` 目录不存在或未包含在 Docker 镜像中
**解决方案**：
1. 本地运行 `cd frontend && npm run build`
2. 确认 `frontend/dist/` 目录存在
3. 提交并推送到 GitHub
4. 重新同步 Space
### 问题 4：API 调用失败
**原因**：未配置环境变量
**解决方案**：
1. 在 Space Settings 中配置 `ZHIPU_API_KEY`
2. Factory reboot 重启 Space
3. 检查 Logs 确认环境变量已加载
## 📊 验证部署
部署成功后，访问你的 Space URL，应该能看到：
1. ✅ 前端页面正常加载
2. ✅ AI 角色形象显示
3. ✅ 可以进行文本输入
4. ✅ 可以查看心情、灵感、待办数据
测试 API 端点：
- `https://你的space.hf.space/health` - 应该返回健康状态
- `https://你的space.hf.space/docs` - 应该显示 API 文档
## 🔄 更新部署
当你更新代码后：
1. **提交到 GitHub**：
```bash
git add .
git commit -m "Update: 描述你的更改"
git push origin main
```
2. **同步到 Hugging Face**：
- 在 Space Settings 中点击 **Sync now**
- 或者等待自动同步（如果已配置）
3. **重启 Space**（如果需要）：
- 点击 **Factory reboot**
## 📚 相关文档
- [Hugging Face Spaces 文档](https://huggingface.co/docs/hub/spaces)
- [Docker SDK 文档](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [项目完整文档](README.md)
## 🆘 需要帮助？
如果遇到问题：
1. 查看 Space 的 **Logs** 标签页
2. 检查 **Community** 标签页的讨论
3. 在 GitHub 仓库提 Issue
|