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）

```bash
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
```

#### 可选变量

```bash
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
```

#### 代理配置（如需要）

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

#### Secrets（如需要）

```bash
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`：

```yaml
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

```python
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

```bash
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`（不要加尾部斜杠）

## 📊 监控和维护

### 查看日志

```bash
# 在 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

---

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