docs/HUGGINGFACE.md

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

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

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

1. 创建 Space

1. 打开 Hugging Face 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

本地生成密钥示例：

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. 调用示例

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

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