PROJECT_INFO.md

# 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` - 保活项目说明

## 🚀 快速部署流程

### 第一步：获取源代码

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

1. 访问：https://huggingface.co/new-space
2. 配置：
   - **SDK**: Docker ⚠️ 重要！
   - **Hardware**: CPU basic（免费）
   - **Visibility**: Public 或 Private

### 第三步：上传代码

```bash
# 初始化 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 中添加：

**必需：**
```bash
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 中启用

### 第六步：配置保活

1. 将 `keepalive/` 目录内容复制到新的 GitHub 仓库
2. 配置 GitHub Variables: `HF_SPACES=https://YOUR_SPACE.hf.space`
3. 启用 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` 端点

### 环境变量优先级
1. Spaces Variables（最高优先级）
2. `.env` 文件
3. `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/` 目录（源代码），需要从原项目获取：
```bash
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分钟）

## 📚 文档索引

1. **快速开始** → [QUICKSTART.md](./QUICKSTART.md)
2. **详细部署** → [DEPLOY_GUIDE.md](./DEPLOY_GUIDE.md)
3. **Space 说明** → [README.md](./README.md)
4. **保活配置** → [keepalive/README.md](./keepalive/README.md)
5. **环境变量** → [.env.example](./.env.example)
6. **默认配置** → [config.defaults.toml](./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，与原项目保持一致。

---

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