docs/README_HUGGINGFACE.md

# 🚀 在 Hugging Face Spaces 上部署 Flask 应用

## 📋 部署步骤

### 1. 创建 Hugging Face Space

1. 访问 https://huggingface.co/spaces
2. 点击 "Create new Space"
3. 填写信息：
   - **Space name**: 你的应用名称（例如：english-learning-app）
   - **License**: 选择合适的许可证
   - **Select the Space SDK**: 选择 **Docker**（重要！）
   - **Visibility**: Public 或 Private

### 2. 推送代码到 Hugging Face Space

#### 方式一：使用 Git（推荐）

```bash
# 添加 Hugging Face Space 作为远程仓库
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# 推送代码
git add .
git commit -m "部署 Flask 应用到 Hugging Face Spaces"
git push space main
```

#### 方式二：使用 Hugging Face Hub CLI

```bash
# 安装 Hugging Face Hub CLI
pip install huggingface-hub

# 登录
huggingface-cli login

# 上传文件
huggingface-cli upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type=space
```

### 3. 等待构建

- Hugging Face Spaces 会自动检测 `Dockerfile`
- 构建过程需要 5-10 分钟
- 可以在 Space 页面查看构建日志

### 4. 访问应用

构建完成后，应用将在以下地址可用：
```
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
```

---

## 🔧 配置说明

### Dockerfile 配置

当前 `Dockerfile` 已配置为使用：
- **Python 3.12**
- **Gunicorn** 生产服务器（4 个工作进程）
- **端口 7860**（Hugging Face Spaces 要求）
- **健康检查**：自动检测应用状态

### 环境变量

如需设置环境变量，在 Hugging Face Space 设置中添加：

1. 进入你的 Space 页面
2. 点击 "Settings"
3. 在 "Repository secrets" 部分添加环境变量：
   - `SECRET_KEY`: Flask 密钥（生产环境必需）
   - `OPENSEARCH_HOST`: OpenSearch 主机（如需要）
   - `OPENSEARCH_PORT`: OpenSearch 端口（如需要）

---

## 📝 重要文件清单

确保以下文件存在于仓库根目录：

- ✅ `Dockerfile` - Docker 构建文件
- ✅ `requirements.txt` - Python 依赖
- ✅ `app.py` - Flask 主应用
- ✅ `config.py` - 配置文件
- ✅ `index.html` - 前端页面
- ✅ `style.css` - 样式文件
- ✅ `script.js` - JavaScript 文件
- ✅ `book_10242.json` - 书籍数据
- ✅ `static/` - 静态资源目录
- ✅ `assets/` - 音频、图片等资源

---

## 🧪 本地测试 Docker 构建

在推送到 Hugging Face 之前，建议本地测试：

```bash
# 构建 Docker 镜像
docker build -t english-learning-app .

# 运行容器
docker run -p 7860:7860 english-learning-app

# 测试应用
curl http://localhost:7860/api/health
```

如果本地测试成功，推送到 Hugging Face Spaces 后应该也能正常运行。

---

## 🔍 故障排查

### 问题：构建失败

**解决方案**：
1. 检查 Hugging Face Space 的构建日志
2. 确保 `requirements.txt` 中的所有依赖都能正确安装
3. 验证 `Dockerfile` 语法正确

### 问题：应用启动失败

**解决方案**：
1. 检查应用日志（在 Space 页面的 "Logs" 标签）
2. 确认必要文件都已上传（特别是 `book_10242.json`）
3. 检查端口是否正确设置为 7860

### 问题：静态资源无法访问

**解决方案**：
1. 确认 `static/` 和 `assets/` 目录已上传
2. 检查 `.gitignore` 是否误排除了必要文件
3. 验证文件路径大小写正确（Linux 区分大小写）

### 问题：应用运行缓慢

**解决方案**：
1. 检查 `book_10242.json` 文件大小
2. 考虑使用 Hugging Face Spaces 的付费套餐（更多资源）
3. 优化数据加载方式（延迟加载、缓存等）

---

## 📊 性能优化建议

### 1. 使用 Gunicorn（已配置）

```dockerfile
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "--timeout", "120", "app:app"]
```

### 2. 静态资源优化

考虑将大型静态资源（音频、图片）上传到 CDN 或 Hugging Face Hub。

### 3. 数据库持久化

Hugging Face Spaces 提供持久化存储：

```python
# 在 app.py 中使用持久化目录
import os
PERSISTENT_DIR = os.environ.get('SPACE_PERSISTENT_DIR', '.')
```

---

## 🌐 访问 API

部署后，可以通过以下端点访问：

```bash
# 健康检查
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/health

# 获取书籍信息
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/book/info

# 搜索内容
curl -X POST https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/search \
  -H "Content-Type: application/json" \
  -d '{"keyword": "hello"}'
```

---

## 📚 参考资源

- [Hugging Face Spaces 文档](https://huggingface.co/docs/hub/spaces)
- [Docker Spaces 指南](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Flask 部署最佳实践](https://flask.palletsprojects.com/en/latest/deploying/)

---

## ⚙️ 高级配置

### 自定义启动命令

如果需要使用 Flask 内置服务器而非 Gunicorn，修改 `Dockerfile` 最后一行：

```dockerfile
CMD ["python3.12", "app.py"]
```

### 添加工作进程

根据你的 Space 资源调整 Gunicorn 工作进程数：

```dockerfile
# 2 个进程（较小的 Space）
CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:7860", "app:app"]

# 8 个进程（更大的 Space）
CMD ["gunicorn", "-w", "8", "-b", "0.0.0.0:7860", "app:app"]
```

---

## 🎉 部署完成！

部署成功后，你的 Flask 英语学习应用将在 Hugging Face Spaces 上运行！

**示例 URL**: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`

享受你的应用吧！🚀