docs/HUGGINGFACE.md

<!-- 适配版本: Grok2API v3.0.7 + HF entrypoint -->

# 部署到 Hugging Face Spaces（个人使用）

本仓库已适配 **Docker Space**：无需挂载 `config.yaml`，用 Space Secrets 即可启动。

> 仅供个人学习研究。请遵守 Grok 使用条款与当地法律；不要把管理员密码、API Key、账号凭据写进公开 README。

## 1. 创建 Space

1. 打开 [Hugging Face Spaces](https://huggingface.co/spaces)
2. **Create new Space**
3. SDK 选 **Docker**
4. 可见性建议 **Private**（个人用）
5. 硬件：**CPU basic** 通常够用（个人低频）

## 2. 推送代码

把本仓库推到该 Space 的 Git 仓库（HF 会按根目录 `Dockerfile` 构建）。

## 3. 配置 Secrets（必须）

在 Space 页面：**Settings → Variables and secrets → New secret**

| Secret 名称 | 是否必须 | 说明 |
| --- | --- | --- |
| `BOOTSTRAP_ADMIN_PASSWORD` | **必须** | 管理端初始密码（强密码） |
| `JWT_SECRET` | 强烈建议 | ≥32 字符随机串；不设则首次自动生成并写入数据目录 |
| `CREDENTIAL_ENCRYPTION_KEY` | 强烈建议 | `openssl rand -base64 32`；**一旦写入账号后不要更换** |

可选：

| 名称 | 说明 |
| --- | --- |
| `BOOTSTRAP_ADMIN_USERNAME` | 默认 `admin` |
| `PUBLIC_API_BASE_URL` | 一般不用；HF 会注入 `SPACE_HOST` 并自动拼 `https://...` |
| `SECURE_COOKIES` | HF 默认 `true`；几乎不用改 |
| `DATABASE_DRIVER` | 默认 `sqlite` |
| `POSTGRES_DSN` | 仅当 `DATABASE_DRIVER=postgres` |
| `GROK2API_DATA_DIR` | 数据目录，默认优先 `/data`（HF 持久盘）再 `/app/data` |
| `PORT` | HF 通常注入；未注入时 env 模式会监听 `7860` |

本地生成密钥示例：

```bash
openssl rand -hex 32
openssl rand -base64 32
```

## 4. 启动与登录

1. 等待 Space **Building / Running**
2. 打开 Space 地址（形如 `https://<user>-<space>.hf.space`）
3. 使用 `admin` + 你设的 `BOOTSTRAP_ADMIN_PASSWORD` 登录
4. 导入上游账号 → 创建客户端密钥 `g2a_...` → 调用 `/v1/*`

健康检查：`https://你的域名/healthz`

## 5. 数据与休眠（个人用必看）

| 点 | 说明 |
| --- | --- |
| 免费 Space 休眠 | 闲置会 sleep，首次访问冷启动较慢；流式长请求可能中断 |
| 无持久盘 | 重启可能丢 SQLite / 媒体 / 自动生成的密钥 |
| 有 Persistent Storage | 把盘挂到 `/data`；本入口会自动把库和媒体写到 `/data` |
| 密钥稳定性 | 请把 `JWT_SECRET` 与 `CREDENTIAL_ENCRYPTION_KEY` 固定写在 Secrets 里，避免重建后无法解密旧账号 |

个人建议：

1. Space 设为 **Private**
2. 配齐三个 Secrets（密码 + JWT + 加密密钥）
3. 尽量开通 **Persistent Storage** 挂到 `/data`
4. 不要公开分享管理端密码和 `g2a_` 密钥

## 6. 环境变量一览

| 变量 | 默认 | 作用 |
| --- | --- | --- |
| `BOOTSTRAP_ADMIN_PASSWORD` | （空） | env 模式必需 |
| `BOOTSTRAP_ADMIN_USERNAME` | `admin` | 初始管理员用户名 |
| `JWT_SECRET` / `GROK2API_JWT_SECRET` | 自动生成 | JWT 签名密钥 |
| `CREDENTIAL_ENCRYPTION_KEY` / `GROK2API_CREDENTIAL_ENCRYPTION_KEY` | 自动生成 | 凭据 AES 密钥（Base64 32 字节） |
| `PORT` | HF 注入 / 否则 7860 | 监听端口 |
| `GROK2API_LISTEN` | （空） | 覆盖监听，如 `0.0.0.0:7860` |
| `PUBLIC_API_BASE_URL` | `https://$SPACE_HOST` | 文档里的公开 API 地址 |
| `DATABASE_DRIVER` | `sqlite` | `sqlite` 或 `postgres` |
| `SQLITE_PATH` | `$data/backend.db` | SQLite 路径 |
| `MEDIA_PATH` | `$data/media` | 媒体目录 |
| `GROK2API_DATA_DIR` | `/data` 或 `/app/data` | 数据根目录 |
| `SECURE_COOKIES` | HF 下 `true` | 管理端 Cookie Secure |
| `SWAGGER_ENABLED` | `false` | 是否开 Swagger |
| `GROK2API_CONFIG_SOURCE` | `/run/grok2api/config.yaml` | 若存在该文件则优先用挂载配置（Compose 兼容） |

兼容原有 Docker Compose：继续挂载 `config.yaml` 到 `/run/grok2api/config.yaml` 即可，行为与以前一致。

## 7. 调用示例

```bash
export GROK2API_API_KEY="g2a_xxx_xxx"
export BASE="https://你的用户名-空间名.hf.space"

curl "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-chat-auto",
    "messages": [{"role":"user","content":"你好"}],
    "stream": false
  }'
```

## 8. 常见问题

**构建失败 / Go 1.26**  
HF 构建机需能拉取 `golang:1.26-alpine` 与 `node:22-alpine`。若镜像源慢，可稍后重试。

**一直无法打开管理端**  
看 Space Logs：是否缺少 `BOOTSTRAP_ADMIN_PASSWORD`；是否仍卡在 Building。

**登录后 Cookie 异常**  
确认走 HTTPS（HF 默认是），不要手动把 `SECURE_COOKIES=false`。

**账号导入后重启全部失效**  
多半是加密密钥变了或数据目录被清空。固定 Secrets，并使用持久盘 `/data`。

**上游请求失败 / 风控**  
HF 出口 IP 可能不稳定。个人用可在管理端「设置 → 出口代理」配置你自己的 HTTP/SOCKS 代理（HF 上无法跑 WARP 的 `NET_ADMIN` 方案）。

## 9. 与本地 Compose 的关系

| 方式 | 配置 | 端口 |
| --- | --- | --- |
| Docker Compose | 挂载 `config.yaml` | `8000` |
| Hugging Face | Secrets / 环境变量 | `7860` 或 `$PORT` |

同一套镜像两种模式都支持。