DEPLOY_GUIDE.md

Grok2API Hugging Face Spaces 部署指南

📋 部署清单

1. 准备工作

• 注册 Hugging Face 账号
• 准备 X (Twitter) 账号的 Token
• （可选）准备代理服务器

2. 创建 Space

1. 访问 https://huggingface.co/new-space
2. 填写 Space 信息：
   • Space name: your-grok2api（自定义）
   • License: MIT
   • SDK: Docker
   • Hardware: CPU basic（免费）或更高
3. 点击 "Create Space"

3. 上传项目文件

将以下文件上传到 Space 仓库：

必需文件：

• Dockerfile ✅
• README.md ✅
• pyproject.toml ✅
• requirements.txt ✅
• config.defaults.toml ✅
• .dockerignore ✅
• scripts/ 目录（包含 entrypoint.sh 和 init_storage.sh）✅

源代码：

• app/ 目录（从原项目复制）⚠️ 需要从 GitHub 克隆

4. 配置环境变量

在 Space Settings → Variables and secrets 中添加：

必需变量（Variables）

APP_KEY=your_strong_password_here
API_KEY=sk-your-custom-api-key-12345
APP_URL=https://your-space-name.hf.space
DATA_DIR=/data
LOG_DIR=/data/logs
ACCOUNT_STORAGE=local
ACCOUNT_LOCAL_PATH=/data/accounts.db
CONFIG_LOCAL_PATH=/data/config.toml

可选变量

LOG_LEVEL=INFO
SERVER_WORKERS=1
GROK_FEATURES_STREAM=true
GROK_FEATURES_THINKING=true
GROK_FEATURES_IMAGE_FORMAT=local_url
GROK_FEATURES_VIDEO_FORMAT=local_url
TZ=Asia/Shanghai

代理配置（如需要）

GROK_PROXY_EGRESS_MODE=url
GROK_PROXY_EGRESS_PROXY_URL=http://your-proxy-server:port

Secrets（如需要）

GROK_PROXY_CLEARANCE_CF_COOKIES=your_cf_cookies_here
HF_TOKEN=your_huggingface_token

5. 启用 Persistent Storage

⚠️ 非常重要！

1. 进入 Space Settings
2. 找到 "Persistent Storage" 部分
3. 点击 "Enable" 启用持久化存储
4. 这将创建 /data 目录用于保存数据

6. 配置保活项目

使用 hf-keepalive 防止 Space 休眠：

6.1 Fork 保活仓库

1. Fork https://github.com/wankuzidi/hf-keepalive
2. 或创建新仓库并复制以下文件：
   • .github/workflows/keep-alive.yml
   • keepalive.py
   • spaces.txt

6.2 配置保活目标

方式 A：使用 GitHub Variables（推荐）

在你 fork 的仓库中：

1. Settings → Secrets and variables → Actions → Variables
2. 添加变量：
   • Name: HF_SPACES
   • Value: https://your-space-name.hf.space

方式 B：编辑 spaces.txt

直接编辑文件，每行一个 Space URL：

https://your-space-name.hf.space

6.3 配置保活频率

编辑 .github/workflows/keep-alive.yml：

on:
  schedule:
    - cron: "0 */12 * * *"  # 每 12 小时运行一次（推荐）
    # - cron: "0 */6 * * *"   # 每 6 小时运行一次
    # - cron: "0 * * * *"     # 每小时运行一次

6.4 启用 Workflow

1. 在你的 fork 仓库中，进入 "Actions" 标签
2. 如果看到提示，点击 "I understand my workflows, go ahead and enable them"
3. 工作流将按设定的频率自动运行

7. 测试部署

7.1 检查 Space 状态

1. 等待 Space 构建完成（首次可能需要 5-10 分钟）
2. 访问 Space URL 查看是否正常运行
3. 查看 "Logs" 标签检查启动日志

7.2 访问管理后台

https://your-space-name.hf.space/admin/login

使用你设置的 APP_KEY 登录

7.3 测试 API

import openai

client = openai.OpenAI(
    api_key="your_api_key_here",
    base_url="https://your-space-name.hf.space/v1"
)

# 测试对话
response = client.chat.completions.create(
    model="grok-4.20-auto",
    messages=[
        {"role": "user", "content": "Hello, Grok!"}
    ]
)

print(response.choices[0].message.content)

📚 添加账号

方法 1：通过管理后台

1. 登录管理后台
2. 进入 "账号管理"
3. 点击 "导入账号"
4. 输入 X (Twitter) 账号的 Token

方法 2：通过 API

curl -X POST "https://your-space-name.hf.space/admin/api/tokens" \
  -H "Authorization: Bearer your_app_key" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your_twitter_token",
    "pool": "super"
  }'

🔧 故障排查

Space 无法启动

1. 检查 Logs 标签查看错误信息
2. 确认所有必需的环境变量已设置
3. 确认 Persistent Storage 已启用
4. 检查 Dockerfile 语法是否正确

数据丢失

1. 确认 Persistent Storage 已启用
2. 检查 DATA_DIR 是否设置为 /data
3. 查看是否有保活项目在运行

API 调用失败

1. 检查 APP_URL 是否正确
2. 检查 API Key 是否正确
3. 查看后台日志排查具体错误
4. 确认账号已正确导入

图片/视频链接 403

1. 必须设置正确的 APP_URL
2. 格式必须是：https://your-space-name.hf.space（不要加尾部斜杠）

📊 监控和维护

查看日志

# 在 Space 的 "Logs" 标签中查看实时日志

监控保活状态

1. 访问你的保活项目仓库
2. 进入 "Actions" 标签
3. 查看最近的运行记录

更新配置

1. 在 Space Settings 中修改环境变量
2. 重启 Space 使配置生效（Settings → Factory reboot）

⚠️ 注意事项

1. 免费 CPU basic 配置适合个人使用，高并发场景建议升级硬件
2. Persistent Storage 有容量限制，定期清理缓存
3. 保活频率不要太高，建议 6-12 小时一次
4. 保护好 API Key 和管理密码
5. 遵守 Grok 和 Hugging Face 的使用条款

🔗 相关链接

• 原项目：https://github.com/chenyme/grok2api
• 保活项目：https://github.com/wankuzidi/hf-keepalive
• Hugging Face Spaces 文档：https://huggingface.co/docs/hub/spaces
• Persistent Storage 文档：https://huggingface.co/docs/hub/spaces-storage

📝 版本信息

• grok2api 版本：2.0.4
• Python 版本：3.11
• 适配日期：2026-06-07

---

免责声明：本项目仅供学习交流使用，请遵守相关服务的使用条款。