Grok2API Hugging Face Spaces 部署包
完整的 Hugging Face Spaces 部署配置文件，支持持久化存储和自动保活。
📦 包含内容
核心配置文件
- ✅
Dockerfile- Docker 构建配置（Python 3.11） - ✅
pyproject.toml- 项目依赖定义 - ✅
requirements.txt- Python 依赖列表 - ✅
config.defaults.toml- 默认配置模板 - ✅
.env.example- 环境变量示例 - ✅
.dockerignore- Docker 构建排除文件 - ✅
.gitignore- Git 版本控制排除文件
启动脚本
- ✅
scripts/entrypoint.sh- Docker 入口脚本 - ✅
scripts/init_storage.sh- 存储初始化脚本 - ✅
app_hf.py- Hugging Face 备用启动脚本
文档
- ✅
README.md- Spaces 项目说明（显示在 Space 页面） - ✅
DEPLOY_GUIDE.md- 详细部署指南 - ✅
QUICKSTART.md- 快速开始指南 - ✅
PROJECT_INFO.md- 本文件
保活项目（keepalive/）
- ✅
keepalive/.github/workflows/keep-alive.yml- GitHub Actions 配置 - ✅
keepalive/keepalive.py- 保活 Python 脚本 - ✅
keepalive/spaces.txt- Space URL 配置 - ✅
keepalive/README.md- 保活项目说明
🚀 快速部署流程
第一步：获取源代码
# 1. 克隆原项目获取 app 目录
git clone https://github.com/chenyme/grok2api.git temp_grok2api
# 2. 复制 app 目录到当前文件夹
cp -r temp_grok2api/app ./
# 3. 清理临时文件
rm -rf temp_grok2api
第二步：创建 Hugging Face Space
- 访问：https://huggingface.co/new-space
- 配置：
- SDK: Docker ⚠️ 重要！
- Hardware: CPU basic（免费）
- Visibility: Public 或 Private
第三步：上传代码
# 初始化 git（如果需要）
git init
git add .
git commit -m "Initial deployment"
# 添加 HF 远程仓库并推送
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
git push hf main
第四步：配置环境变量
在 Space Settings → Variables 中添加：
必需：
APP_KEY=your_password
API_KEY=sk-your-api-key
APP_URL=https://YOUR_USERNAME-YOUR_SPACE.hf.space
DATA_DIR=/data
ACCOUNT_STORAGE=local
第五步：启用 Persistent Storage
⚠️ 非常重要！ 在 Space Settings 中启用
第六步：配置保活
- 将
keepalive/目录内容复制到新的 GitHub 仓库 - 配置 GitHub Variables:
HF_SPACES=https://YOUR_SPACE.hf.space - 启用 GitHub Actions
📁 目录结构
grok2api/
├── app/ # ⚠️ 需要从原项目获取
│ ├── main.py
│ ├── control/
│ ├── dataplane/
│ ├── platform/
│ ├── products/
│ └── statics/
├── scripts/
│ ├── entrypoint.sh
│ └── init_storage.sh
├── keepalive/ # 保活项目配置
│ ├── .github/
│ │ └── workflows/
│ │ └── keep-alive.yml
│ ├── keepalive.py
│ ├── spaces.txt
│ └── README.md
├── Dockerfile # Docker 构建文件
├── pyproject.toml # 项目配置
├── requirements.txt # 依赖列表
├── config.defaults.toml # 默认配置
├── .env.example # 环境变量示例
├── .dockerignore # Docker 排除文件
├── .gitignore # Git 排除文件
├── app_hf.py # HF 启动脚本
├── README.md # Space 页面说明
├── DEPLOY_GUIDE.md # 部署指南
├── QUICKSTART.md # 快速开始
└── PROJECT_INFO.md # 本文件
⚙️ 关键配置说明
Dockerfile
- 基础镜像：
python:3.11-slim-bookworm - 使用
uv加速依赖安装 - 支持 Persistent Storage (
/data) - 健康检查：
/health端点
环境变量优先级
- Spaces Variables（最高优先级）
.env文件config.defaults.toml（默认值）
数据持久化路径
- 账号数据库：
/data/accounts.db - 运行配置：
/data/config.toml - 图片缓存：
/data/images/ - 视频缓存：
/data/videos/ - 日志文件：
/data/logs/
🔍 功能特性
API 兼容性
- ✅ OpenAI Chat Completions
- ✅ OpenAI Images (generations/edits)
- ✅ OpenAI Videos
- ✅ Anthropic Messages
- ✅ 流式和非流式输出
管理功能
- ✅ Web 管理后台
- ✅ 账号池管理
- ✅ 配置热更新
- ✅ 缓存管理
- ✅ 实时监控
保活机制
- ✅ GitHub Actions 定时任务
- ✅ 可配置访问频率
- ✅ 支持多个 Space
- ✅ 失败重试
⚠️ 重要提示
关于源代码
当前配置包不包含 app/ 目录（源代码），需要从原项目获取：
git clone https://github.com/chenyme/grok2api.git
cp -r grok2api/app ./
关于 Python 版本
- 原项目要求：Python ≥ 3.13
- 本配置调整为：Python 3.11（HF Spaces 兼容）
- 已测试兼容性，如遇问题请反馈
关于 Persistent Storage
- 必须启用，否则每次重启都会丢失数据
- 免费额度有容量限制
- 定期清理缓存（图片/视频）
关于保活频率
- 推荐：每 12 小时（
0 */12 * * *） - 最低：每 6 小时
- 避免：过于频繁（<30分钟）
📚 文档索引
- 快速开始 → QUICKSTART.md
- 详细部署 → DEPLOY_GUIDE.md
- Space 说明 → README.md
- 保活配置 → keepalive/README.md
- 环境变量 → .env.example
- 默认配置 → config.defaults.toml
🔗 相关链接
- 原项目: https://github.com/chenyme/grok2api
- 保活项目: https://github.com/wankuzidi/hf-keepalive
- HF Spaces 文档: https://huggingface.co/docs/hub/spaces
- Persistent Storage: https://huggingface.co/docs/hub/spaces-storage
🐛 常见问题
Q: Space 无法启动？
A: 检查 Logs 标签，确认环境变量配置正确，确保已启用 Persistent Storage
Q: 如何获取 X Token？
A: 登录 X (Twitter)，F12 打开开发者工具，查看请求头中的 Cookie
Q: 图片/视频链接 403？
A: 必须正确设置 APP_URL 环境变量
Q: 数据经常丢失？
A: 启用 Persistent Storage + 配置保活项目
Q: 保活项目不工作？
A: 检查 GitHub Actions 是否启用，查看运行日志
📝 版本信息
- 配置包版本: 1.0.0
- grok2api 版本: 2.0.4
- Python 版本: 3.11
- 创建日期: 2026-06-07
📄 许可证
本配置包基于 MIT License，与原项目保持一致。
免责声明: 本项目仅供学习交流使用，请遵守相关服务的使用条款。