CHECKLIST.md

部署前检查清单

✅ 文件准备

已完成（配置文件）

• Dockerfile
• pyproject.toml
• requirements.txt
• config.defaults.toml
• .env.example
• .dockerignore
• .gitignore
• scripts/entrypoint.sh
• scripts/init_storage.sh
• app_hf.py
• README.md
• DEPLOY_GUIDE.md
• QUICKSTART.md
• PROJECT_INFO.md
• keepalive/ 目录完整配置

待获取（源代码）

• app/ 目录（从 GitHub 原项目获取）

获取命令：

git clone https://github.com/chenyme/grok2api.git temp
cp -r temp/app ./
rm -rf temp

🌐 Hugging Face Space 配置

Space 创建

• 访问 https://huggingface.co/new-space
• 选择 Docker SDK（非常重要！）
• 选择硬件配置（建议 CPU basic）
• 记录 Space URL

环境变量配置（必需）

在 Space Settings → Variables 中添加：

• APP_KEY = 你的管理密码
• API_KEY = sk-your-api-key-here
• APP_URL = https://your-username-your-space.hf.space
• DATA_DIR = /data
• 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
• TZ = Asia/Shanghai

代理配置（如需要）

• GROK_PROXY_EGRESS_MODE = url
• GROK_PROXY_EGRESS_PROXY_URL = http://proxy:port

Persistent Storage

• 启用 Persistent Storage（Settings 中）

🔄 保活项目配置

GitHub 仓库

• 创建新的 GitHub 仓库或 Fork wankuzidi/hf-keepalive
• 上传 keepalive/ 目录的文件：
  • .github/workflows/keep-alive.yml
  • keepalive.py
  • spaces.txt

GitHub Variables

在仓库 Settings → Variables → Actions 中：

• 添加 HF_SPACES = 你的 Space URL

GitHub Secrets（私有 Space 需要）

在仓库 Settings → Secrets → Actions 中：

• 添加 HF_TOKEN = 你的 HF Token

启用 Actions

• 进入 Actions 标签
• 启用 Workflows
• （可选）手动运行一次测试

📤 代码上传

Git 配置

• 初始化 git（如需要）

  git init
  

• 添加所有文件

  git add .
  

• 提交更改

  git commit -m "Initial Hugging Face Spaces deployment"
  

• 添加 HF 远程仓库

  git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
  

• 推送到 HF

  git push hf main
  

🧪 部署测试

构建检查

• 等待 Space 构建完成（5-10分钟）
• 查看 Logs 标签确认无错误
• 访问 Space URL 确认可访问

功能测试

• 访问管理后台：https://your-space.hf.space/admin/login
• 使用 APP_KEY 登录成功
• 添加至少一个 X Token
• 测试 API 调用（见下方）

API 测试

import openai

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

response = client.chat.completions.create(
    model="grok-4.20-auto",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

保活测试

• 检查保活 Actions 是否运行
• 查看运行日志确认成功
• 等待 12 小时后确认 Space 未休眠

📊 监控设置

Space 监控

• 添加到浏览器书签
• 定期查看 Logs
• 监控 Persistent Storage 使用量

保活监控

• 设置 GitHub Actions 通知
• 定期检查运行记录
• 关注失败通知

🔧 后续维护

定期任务

• 每周检查 Space 状态
• 每月清理缓存（如空间不足）
• 定期更新 X Token

配置优化

• 根据使用情况调整缓存大小
• 优化保活频率
• 根据需要调整 Worker 数量

⚠️ 常见错误排查

Space 无法启动

1. 检查 Dockerfile 语法
2. 确认环境变量配置
3. 查看详细错误日志
4. 确认 app/ 目录存在

数据丢失

1. 确认 Persistent Storage 已启用
2. 检查 DATA_DIR 配置
3. 确认保活项目正常运行

API 调用失败

1. 确认 API_KEY 正确
2. 检查 APP_URL 配置
3. 确认账号已添加
4. 查看后台错误日志

📱 联系支持

如遇到问题：

1. 查看 DEPLOY_GUIDE.md
2. 检查 PROJECT_INFO.md
3. 访问原项目 Issues: https://github.com/chenyme/grok2api/issues

---

检查完成后，删除此文件或标记为完成日期：____