CHECKLIST.md

# 部署前检查清单

## ✅ 文件准备

### 已完成（配置文件）
- [x] Dockerfile
- [x] pyproject.toml
- [x] requirements.txt
- [x] config.defaults.toml
- [x] .env.example
- [x] .dockerignore
- [x] .gitignore
- [x] scripts/entrypoint.sh
- [x] scripts/init_storage.sh
- [x] app_hf.py
- [x] README.md
- [x] DEPLOY_GUIDE.md
- [x] QUICKSTART.md
- [x] PROJECT_INFO.md
- [x] keepalive/ 目录完整配置

### 待获取（源代码）
- [ ] **app/ 目录**（从 GitHub 原项目获取）

**获取命令：**
```bash
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（如需要）
  ```bash
  git init
  ```

- [ ] 添加所有文件
  ```bash
  git add .
  ```

- [ ] 提交更改
  ```bash
  git commit -m "Initial Hugging Face Spaces deployment"
  ```

- [ ] 添加 HF 远程仓库
  ```bash
  git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
  ```

- [ ] 推送到 HF
  ```bash
  git push hf main
  ```

## 🧪 部署测试

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

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

### API 测试
```python
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](./DEPLOY_GUIDE.md)
2. 检查 [PROJECT_INFO.md](./PROJECT_INFO.md)
3. 访问原项目 Issues: https://github.com/chenyme/grok2api/issues

---

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