HUGGINGFACE_DEPLOY.md

🚀 Hugging Face Spaces 部署指南

✅ 部署前检查清单

1. 根目录必需文件

确保以下文件在根目录（不是子目录）：

• ✅ Dockerfile - Docker 构建配置
• ✅ start.py - 应用启动脚本
• ✅ requirements.txt - Python 依赖
• ✅ README_HF.md - Hugging Face 专用 README（带 frontmatter）

2. 前端构建文件

确保前端已构建：

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：

---
title: Nora - 治愈系记录助手
emoji: 🌟
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: mit
---

🔧 部署步骤

方法 1：通过 GitHub 同步（推荐）

1. 提交所有更改到 GitHub：

   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：

   git add .
   git commit -m "Update: 描述你的更改"
   git push origin main
   

2. 同步到 Hugging Face：

   • 在 Space Settings 中点击 Sync now
   • 或者等待自动同步（如果已配置）

3. 重启 Space（如果需要）：

   • 点击 Factory reboot

📚 相关文档

• Hugging Face Spaces 文档
• Docker SDK 文档
• 项目完整文档

🆘 需要帮助？

如果遇到问题：

1. 查看 Space 的 Logs 标签页
2. 检查 Community 标签页的讨论
3. 在 GitHub 仓库提 Issue