Update README.md

README.md

@@ -1,10 +1,283 @@
 ---
-title: Grok2api
-emoji: 📈
-colorFrom: indigo
-colorTo: blue
+title: Grok2API
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 Grok2API on HuggingFace Spaces
+
+> 基于 FastAPI 重构的 Grok 反向代理，提供 OpenAI 兼容接口。  
+> 支持流式/非流式对话、图像生成/编辑、视频生成、深度推理、Token 池并发与负载均衡。
+
+---
+
+## 📁 仓库文件结构
+
+部署到 HuggingFace Space 只需以下文件：
+
+```
+your-space/
+├── README.md          # 本文件（含 HF metadata）
+├── Dockerfile         # 容器构建配置
+└── entrypoint.sh      # 启动脚本（注入环境变量生成 config.toml）
+```
+
+---
+
+## 📄 Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
+
+# 安装 uv 包管理器
+RUN pip install uv --no-cache-dir
+
+# 克隆 grok2api 源码
+RUN git clone https://github.com/chenyme/grok2api /app
+
+WORKDIR /app
+
+# 安装 Python 依赖
+RUN uv sync
+
+# HuggingFace 文件系统只读，所有写入必须走 /tmp
+RUN mkdir -p /tmp/data /tmp/logs
+
+# 复制启动脚本
+COPY entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# 环境变量默认值
+ENV DATA_DIR=/tmp/data
+ENV LOG_FILE_ENABLED=false
+ENV LOG_LEVEL=INFO
+ENV SERVER_PORT=7860
+ENV SERVER_HOST=0.0.0.0
+
+# HuggingFace Spaces 固定使用 7860 端口
+EXPOSE 7860
+
+CMD ["/app/entrypoint.sh"]
+```
+
+---
+
+## 📄 entrypoint.sh
+
+```bash
+#!/bin/sh
+set -e
+
+echo "[entrypoint] Starting grok2api on HuggingFace Space..."
+
+# 确保 /tmp 目录存在
+mkdir -p /tmp/data /tmp/logs
+
+# 从环境变量生成 config.toml
+# APP_KEY      → 管理后台密码（默认 grok2api，强烈建议修改）
+# API_KEY      → 调用 API 时需携带的访问密钥（留空则不鉴权）
+# APP_URL      → 对外访问的完整 URL，用于生成文件链接
+#                格式: https://你的用户名-grok2api.hf.space
+cat > /tmp/data/config.toml << EOF
+[app]
+app_key   = "${APP_KEY:-grok2api}"
+api_key   = "${API_KEY:-}"
+app_url   = "${APP_URL:-}"
+image_format = "url"
+video_format = "html"
+temporary    = true
+disable_memory = true
+stream       = true
+thinking     = true
+
+[server]
+storage_type = "${SERVER_STORAGE_TYPE:-local}"
+storage_url  = "${SERVER_STORAGE_URL:-}"
+EOF
+
+echo "[entrypoint] config.toml generated."
+echo "[entrypoint] admin panel: ${APP_URL:-http://localhost:7860}/admin"
+
+# 启动 FastAPI 服务
+exec uv run granian \
+  --interface asgi \
+  --host 0.0.0.0 \
+  --port 7860 \
+  --workers 1 \
+  main:app
+```
+
+---
+
+## ⚙️ 环境变量配置
+
+在 HuggingFace Space **Settings → Variables and secrets** 中配置以下变量：
+
+### 🔐 Secrets（敏感信息，加密存储）
+
+| 变量名 | 必填 | 说明 | 示例 |
+|--------|:----:|------|------|
+| `APP_KEY` | ✅ | 管理后台登录密码，**务必修改默认值** | `my-secure-password` |
+| `API_KEY` | ⬜ | 调用 `/v1/chat/completions` 时需携带的密钥，留空则不鉴权 | `sk-my-api-key` |
+| `SERVER_STORAGE_URL` | ⬜ | 外部数据库 DSN（推荐 Neon PostgreSQL，见下方说明） | `postgresql+asyncpg://user:pass@host/db?sslmode=require` |
+
+### 🌐 Variables（普通变量）
+
+| 变量名 | 必填 | 说明 | 示例 |
+|--------|:----:|------|------|
+| `APP_URL` | ⬜ | Space 对外 URL，用于生成图片/视频访问链接 | `https://你的用户名-grok2api.hf.space` |
+| `SERVER_STORAGE_TYPE` | ⬜ | 存储类型，使用外部数据库时填 `pgsql` | `pgsql` / `local` |
+| `LOG_LEVEL` | ⬜ | 日志级别 | `INFO` |
+
+---
+
+## 🗄️ 持久化存储（强烈推荐）
+
+HuggingFace Space **重启后 `/tmp` 数据会丢失**，导致已导入的 Grok Token 全部清空。  
+推荐使用 **Neon PostgreSQL 免费版** 做持久化：
+
+1. 前往 [neon.tech](https://neon.tech) 注册，创建一个数据库
+2. 复制 Connection String，格式如下：
+   ```
+   postgresql+asyncpg://user:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
+   ```
+3. 在 HF Space Secrets 中设置：
+   - `SERVER_STORAGE_TYPE` = `pgsql`
+   - `SERVER_STORAGE_URL` = 上方连接字符串
+
+> **为什么选 Neon 而非 Supabase？**  
+> Supabase 免费项目 7 天无活动会自动暂停，Neon 不会，更适合低频使用场景。
+
+---
+
+## 🚀 部署步骤
+
+### 第一步：创建 Space
+
+1. 登录 [huggingface.co](https://huggingface.co)
+2. 点击右上角头像 → **New Space**
+3. 填写：
+   - Space name: `grok2api`
+   - SDK: **Docker**（必须选这个）
+   - Hardware: CPU Basic（免费）
+4. 点击 **Create Space**
+
+### 第二步：上传文件
+
+```bash
+# 克隆 Space 仓库
+git clone https://huggingface.co/spaces/你的用户名/grok2api
+cd grok2api
+
+# 创建 README.md、Dockerfile、entrypoint.sh（内容见上��）
+
+# 推送
+git add .
+git commit -m "deploy grok2api"
+git push
+```
+
+推送后 HuggingFace 自动构建镜像，约 3~5 分钟后服务启动。
+
+### 第三步：配置 Secrets
+
+在 Space 页面 → **Settings → Variables and secrets** 中添加上方表格中的变量。
+
+> 修改 Secrets 后需点击 **Restart Space** 使配置生效。
+
+### 第四步：访问管理后台
+
+```
+https://你的用户名-grok2api.hf.space/admin
+```
+
+默认密码为 `grok2api`，首次登录后请立即在 Secrets 中设置 `APP_KEY` 修改密码。
+
+---
+
+## 🔑 导入 Grok Token
+
+服务启动后，在管理后台 `/admin` 中：
+
+1. 点击 **Token Management**
+2. 点击 **Add Token**，粘贴你的 Grok SSO Token
+3. 等待状态变为 **Active** 即可使用
+
+---
+
+## 📡 API 使用示例
+
+将你客户端的 Base URL 替换为 Space 地址即可：
+
+### cURL
+
+```bash
+curl https://你的用户名-grok2api.hf.space/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $API_KEY" \
+  -d '{
+    "model": "grok-3",
+    "stream": true,
+    "messages": [{"role": "user", "content": "你好！"}]
+  }'
+```
+
+### Python（OpenAI SDK）
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="你的 API_KEY",  # 未设置则填任意字符串
+    base_url="https://你的用户名-grok2api.hf.space/v1",
+)
+
+response = client.chat.completions.create(
+    model="grok-3",
+    messages=[{"role": "user", "content": "你好！"}],
+    stream=True,
+)
+
+for chunk in response:
+    print(chunk.choices[0].delta.content or "", end="")
+```
+
+---
+
+## 📊 支持的模型
+
+| 模型 | 类型 | 账号要求 |
+|------|------|---------|
+| `grok-3` | 对话 / 图像 | Basic / Super |
+| `grok-3-mini` | 对话 / 图像 | Basic / Super |
+| `grok-3-thinking` | 深度推理 | Basic / Super |
+| `grok-imagine-1.0` | 图像生成 | Basic / Super |
+| `grok-imagine-1.0-edit` | 图像编辑 | Basic / Super |
+| `grok-imagine-1.0-video` | 视频生成 | Basic / Super |
+
+---
+
+## ⚠️ 注意事项
+
+| 限制 | 说明 |
+|------|------|
+| **端口** | HF Space 固定使用 `7860`，不可更改 |
+| **休眠** | 免费版 48 小时无访问后自动休眠，首次访问需约 30 秒唤醒 |
+| **数据持久化** | 不接外部数据库则重启丢失所有 Token，强烈建议配置 Neon |
+| **文件系统只读** | 所有配置/日志必须写入 `/tmp`，entrypoint 已处理 |
+| **免责声明** | 本项目仅供学习研究，请遵守 Grok 使用条款及当地法律法规 |
+
+---
+
+## 🔗 相关链接
+
+- [grok2api 源码](https://github.com/chenyme/grok2api)
+- [Neon 免费 PostgreSQL](https://neon.tech)
+- [HuggingFace Spaces 文档](https://huggingface.co/docs/hub/spaces)