本项目为对 chenyme/grok2api 的二次修改与增强。

中文 | English

基于 FastAPI 重构的 Grok2API，全面适配最新 Web 调用格式，支持流/非流式对话、图像生成/编辑、深度思考，号池并发与自动负载均衡一体化。

本仓库额外提供 Cloudflare Workers / Pages（TypeScript，D1 + KV）版本，适合在 Cloudflare 上运行与代理出站。

• 部署与配置说明：README.cloudflare.md
• 一键部署工作流：.github/workflows/cloudflare-workers.yml
  • 一键部署前置条件：仓库需配置 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID。

本项目支持三种部署方式，功能语义一致（Token 管理、API Key 管理、后台接口行为对齐）。

# 安装依赖
uv sync

# 启动服务（默认 :8000）
uv run main.py

# （可选）启动后自检
python scripts/smoke_test.py --base-url http://127.0.0.1:8000

git clone https://github.com/TQZHR/grok2api.git
cd grok2api

# 1. 拉取镜像启动
docker compose up -d

# 2. 更新到最新镜像
docker compose pull && docker compose up -d

# 3. 从源码构建（可选）
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

数据持久化：容器内 /app/data 和 /app/logs 已映射到宿主机 ./data 和 ./logs。

存储后端选择（通过 .env 配置）：

示例（启用 PostgreSQL）：

# .env
COMPOSE_PROFILES=pgsql
SERVER_STORAGE_TYPE=pgsql
PGSQL_PASSWORD=change_me
SERVER_STORAGE_URL=postgresql+asyncpg://grok2api:change_me@pgsql:5432/grok2api

如果拉取镜像时报 denied：GHCR 镜像未公开或需要登录。可先 docker login ghcr.io，或在 .env 设置 GROK2API_IMAGE 指向自有镜像，也可用 --build 从源码构建。

详见 README.cloudflare.md，要点：

• 存储：D1（SQLite）持久化 + KV 缓存图片/视频
• 一键部署：.github/workflows/cloudflare-workers.yml（需配置 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID）
• 手动部署：npm install && npx wrangler deploy

如需通过 Nginx/Caddy 反向代理，注意：

• 转发 Host、X-Real-IP、X-Forwarded-For 头
• 流式响应需关闭代理缓冲（Nginx: proxy_buffering off;）
• WebSocket 升级（如使用实验性生图）：proxy_set_header Upgrade $http_upgrade;

部署完成后建议运行：

# Python 测试
uv run pytest -q

# Workers 类型检查
npm run typecheck

# 模型目录一致性
python scripts/check_model_catalog_sync.py

# Docker Compose 配置校验
docker compose -f docker-compose.yml config

# （可选）冒烟测试
python scripts/smoke_test.py --base-url http://127.0.0.1:8000

访问地址：http://<host>:8000/login

默认账号密码：admin / admin（对应配置项 app.admin_username / app.app_key，建议上线后修改）。

常用页面：

• http://<host>:8000/admin/token：Token 管理（导入/导出/批量操作/自动注册）
• http://<host>:8000/admin/keys：API Key 管理（统计/筛选/新增/编辑/删除）
• http://<host>:8000/admin/datacenter：数据中心（常用指标 + 日志查看）
• http://<host>:8000/admin/config：配置管理（含自动注册所需配置）
• http://<host>:8000/admin/cache：缓存管理（本地缓存 + 在线资产）

• 已覆盖页面：/login、/admin/token、/admin/keys、/admin/cache、/admin/config、/admin/datacenter、/chat、/admin/chat。
• 后台顶部导航在手机端改为抽屉菜单（支持：打开/关闭、点击遮罩关闭、点击菜单项后自动收起、Esc 关闭）。
• 表格在手机端保持“横向滚动优先”，不压缩列结构（Token/API Key/缓存表格行为一致）。
• Toast 在窄屏改为左右边距自适应，不再固定最小宽度导致溢出。
• 底部批量操作条（Token/缓存）在手机端改为全宽底部卡片样式，减少遮挡主操作。
• 三部署一致性：上述适配使用同一套静态资源，在本地 FastAPI / Docker / Cloudflare Workers 下行为一致。

• 支持类型筛选：sso、supersso（可组合）。
• 支持状态筛选：活跃、失效、额度用尽（可组合，按并集语义）。
• 提供“结果计数”和“清空筛选”。
• 筛选后勾选/全选/批量刷新/批量删除均基于 Token 唯一值，避免过滤后行索引错位导致误操作。
• 状态判定规则：
  • 失效：status 为 invalid/expired/disabled
  • 额度用尽：status = cooling，或（quota_known = true 且 quota <= 0），或（super 且 heavy_quota_known = true 且 heavy_quota <= 0）
  • 活跃：非失效且非额度用尽
• 类型映射规则：ssoBasic -> sso，ssoSuper -> supersso（接口字段 token_type 为 sso / ssoSuper）。

• 页面新增统计卡片：总数、启用、禁用、今日额度用尽。
• 工具栏支持：名称/Key 搜索、状态筛选（全部/启用/禁用/额度用尽）、重置筛选。
• 新增 API Key 弹窗增强：
  • 居中悬浮弹窗（遮罩层 + 缩放入场动画）
  • 支持点击遮罩关闭、Esc 关闭
  • 移动端弹窗内容可滚动且网格布局自适应
  • 自动生成 Key
  • 额度预设（推荐/不限）
  • 提交中禁用按钮，防止重复提交
  • 创建成功后支持一键复制 Key
• 错误提示优化：前端优先展示后端 detail/error/message，避免“创建失败/更新失败”无上下文。
• 更新不存在的 Key 会返回 404（FastAPI 与 Workers 一致）。

支持两种方式：

• 直接添加 Token（手动/批量导入）
• 自动注册并自动写入 Token 池

自动注册特性：

• 可设置注册数量（不填默认 100）
• 可设置并发（默认 10）
• 注册前会自动启动本地 Turnstile Solver（默认 5 线程），注册结束后自动关闭
• 注册成功后会自动执行：同意用户协议（TOS）+ 设置年龄 + 开启 NSFW
  • 若 TOS / 年龄 / NSFW 任一步骤失败，会判定该次注册失败并在前端显示错误原因

自动注册前置配置（在「配置管理」-> register.*）：

• register.worker_domain / register.email_domain / register.admin_password：临时邮箱 Worker 配置
• register.solver_url / register.solver_browser_type / register.solver_threads：本地 Turnstile Solver 配置
• 可选：register.yescaptcha_key（配置后优先走 YesCaptcha，无需本地 solver）

升级兼容：

• 本地部署升级后会自动对「旧 Token」做一次 TOS + 设置年龄 + NSFW（并发 10，best-effort，仅执行一次，避免重复刷）。

配置 .env 文件

• 配置文件：data/config.toml（首次启动会基于 config.defaults.toml 自动生成；管理面板也可直接修改）
• Token 数据：data/token.json
• 升级时自动兼容迁移（本地/Docker）：
  • 旧版配置：检测到 data/setting.toml 时，会按“缺失字段/仍为默认值”的策略合并到新配置
  • 旧版缓存目录：data/temp/{image,video} -> data/tmp/{image,video}
  • 旧账号一次性修复（best-effort）：升级后会对现有 Token 自动执行一次「同意用户协议 + 设置年龄 + 开启 NSFW」（并发 10）

• Basic 账号：80 次 / 20h
• Super 账号：无账号，作者未测试

通用接口，支持对话聊天、图像生成、图像编辑、视频生成、视频超分

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4",
    "messages": [{"role":"user","content":"你好"}]
  }'

图像生成接口

curl http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-1.0",
    "prompt": "一只在太空漂浮的猫",
    "n": 1
  }'

返回当前生图后端方式（/chat 与 /admin/chat 用于判断是否启用“新生图瀑布流 + 宽高比 + 并发”）

curl http://localhost:8000/v1/images/method \
  -H "Authorization: Bearer $GROK2API_API_KEY"

返回示例：

{ "image_generation_method": "legacy" }

• 可选值：legacy、imagine_ws_experimental
• Cloudflare / Docker / 本地 三种部署均保持同一接口语义

• In experimental mode, the image panel is replaced and supports two run modes: single and continuous.
• single keeps using POST /v1/images/generations and remains response-compatible.
• continuous uses WebSocket: /api/v1/admin/imagine/ws?api_key=<API_KEY>.
• WS commands: start / stop / ping.
• WS events: status / image / error / pong.
• Continuous payload includes b64_json, sequence, elapsed_ms, aspect_ratio, run_id.

图像编辑接口（multipart/form-data）

curl http://localhost:8000/v1/images/edits \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -F "model=grok-imagine-1.0-edit" \
  -F "prompt=给这只猫加一副太阳镜" \
  -F "image=@./cat.png" \
  -F "n=1" \
  -F "response_format=url"

1. GET /api/v1/admin/tokens（增量兼容，保留旧字段）新增：
   • token_type
   • quota_known
   • heavy_quota
   • heavy_quota_known
2. POST /api/v1/admin/keys/update：
   • 当 key 不存在时返回 404（此前部分实现可能返回成功）。
3. 额度语义补充：
   • quota_known = false 表示额度未知（例如 remaining_queries = -1 场景），不应直接判定为“额度用尽”。

配置文件：data/config.toml

当你从旧版本升级到当前版本时，程序会在启动时自动兼容并读取旧数据：

• 旧配置：若存在 data/setting.toml，会自动迁移/合并到 data/config.toml（仅覆盖“缺失项”或“仍为默认值”的字段）。
• 旧缓存目录：旧版 data/temp/{image,video} 会自动迁移到新版 data/tmp/{image,video}，未到清理时间的缓存文件不会丢失。
• Docker 部署：务必持久化挂载 ./data:/app/data（以及 ./logs:/app/logs），否则容器更新/重建会丢失本地数据。

当 Grok 启用 Cloudflare 质询时，可开启 cf_clearance 自动刷新，后台定时获取新 cookie 并注入请求头。

• 启用：将 cf_clearance.enabled 设为 true
• Provider 链：按 cf_clearance.providers 列表顺序依次尝试，任一成功即停止
  • local — 复用本地 Turnstile Solver 进程（需先启动 solver）
  • flaresolverr — 兼容 FlareSolverr / Byparr API
  • cloudflare_bypass — CloudflareBypassForScraping
• 刷新策略：成功后按 refresh_interval（默认 1200s）等待下次刷新；全部失败时指数退避重试（上限 max_backoff 秒）
• 仅 Python/FastAPI 运行时可用；Cloudflare Workers 侧不适用

• 请求统计 debounce 写入（5s 合并），高并发下减少 90%+ 磁盘 I/O
• TokenPool 选择改为单次遍历，消除 2-3 次重复扫描
• 共享请求头模板收敛，净减 ~70 行重复代码

• 信号量竞态：动态调整内部计数器，避免旧信号量协程失去并发控制
• 流式 processor 资源泄漏：确保消费者断开时 session 被清理
• Windows 锁退化：per-name asyncio.Lock 替代全局锁