Grok2API 接入服务

项目简介

Grok2API 是一个使用 Go 编写的 API 网关，内置 React 管理控制台。它统一管理 Grok Build、Grok Web、Grok Console 三类独立的账号池，并对外暴露兼容 OpenAI 和 Anthropic 协议的接口。客户端 SDK、Codex、Claude Code 均可直接对接。

该项目仅供技术研究与学习，使用时须遵守 Grok 官方条款及当地法规。

技术架构

网关采用四层领域划分：

• 接入域：API 客户端与 React 管理后台
• 核心域：账号管理、模型管理、客户端密钥、运行时设置、账号同步、网关路由、审计计费
• Provider 通道域：通过 Provider Registry 注册 Build、Web、Console 三类通道
• 基础设施域：出口代理管理、SQLite/PostgreSQL 数据库、内存/Redis 运行时存储

每个 Provider 维护独立的凭证、配额、健康状态、冷却、并发与模型能力，故障转移仅在选定 Provider 内部进行。

核心能力

• API 形态：Responses、Chat Completions、Anthropic Messages、Images、异步 Videos
• 客户端兼容：Codex、Claude Code、OpenAI/Anthropic 兼容 SDK
• 账号管理：批量导入导出、配额同步、凭证续期、跨通道转换、清理
• 路由：模型发现、Provider 绑定、粘性会话、配额/并发守护、有界故障转移
• 会话：存储响应、压缩、Prompt 缓存亲和、可选推理回放
• 媒体：图像生成/编辑、视频任务、本地归档、URL/Base64/SSE 输出
• 出口代理：HTTP/SOCKS/Resin、订阅与探测、代理池分配与回退、FlareSolverr
• 运维：仪表盘、模型路由、客户端密钥、审计、运行时设置、媒体库

快速开始

官方镜像支持 linux/amd64 与 linux/arm64：

git clone https://github.com/chenyme/grok2api.git
cd grok2api
cp config.example.yaml config.yaml

生成密钥并写入 config.yaml：

openssl rand -hex 32           # 用于 jwtSecret
openssl rand -base64 32        # 用于 credentialEncryptionKey

secrets:
  jwtSecret: "替换为生成的十六进制值"
  credentialEncryptionKey: "替换为生成的 Base64 密钥"

bootstrapAdmin:
  username: "admin"
  password: "请改为强密码"

docker compose pull
docker compose up -d
docker compose logs -f grok2api

访问 http://127.0.0.1:8000，SQLite 数据与本地媒体存放于 Compose 卷中。源码运行可使用 make run，前端开发使用 pnpm install && pnpm dev。

初始化流程

1. 使用引导管理员登录
2. 连接 Build/Web/Console 账号
3. 等待配额与模型能力同步
4. 在「Model Routes」查看公开路由
5. 在「Client Keys」创建客户端密钥
6. 使用该密钥调用 /v1/* 接口

首次登录后应立即修改管理员密码并移除 bootstrapAdmin 配置；credentialEncryptionKey 一旦写入则不得轮换。账号支持 JSON/JSONL 批量导入，UTF-8 BOM 可正常解析。Build 通道提供 Device OAuth；Web/Console 支持粘贴或 TXT 文件导入 SSO。

模型与通道

Provider	鉴权方式	模型来源	关键能力
Build	OAuth / Device OAuth	按账号动态发现	Responses、Chat、Messages、压缩、存储响应、付费视频
Web	SSO	内置目录，按等级过滤	Responses、Chat、Messages、存储响应、图像、编辑、视频
Console	SSO	内置目录	无状态 Responses、Chat、Messages、图像、编辑、视频

Build 对话请求被翻译为 Build Responses 协议，同时保留工具调用、推理、多轮与 Prompt 缓存兼容性。Build 通道当前不开放图像生成与编辑路由。Web 的同模型可与匹配 Build/Console 账号弱关联，仅共享匿名出口身份与来源展示，凭证、配额、计费等不互通。

API 用法

客户端使用 Bearer Token 调用，格式为 g2a_xxx_xxx：

方法	路径	用途
GET	/healthz、/readyz	存活与就绪检查
GET	/v1/models	可服务模型列表
POST	/v1/responses	Responses JSON/SSE
POST	/v1/responses/compact	压缩支持的 Response 会话
GET/DELETE	/v1/responses/{id}	读取或删除存储响应
POST	/v1/chat/completions	Chat Completions JSON/SSE
POST	/v1/messages	Anthropic Messages JSON/SSE
POST	/v1/images/generations、/v1/images/edits	图像生成与编辑
POST/GET	/v1/videos/*	创建与查询视频任务
GET	/v1/media/images/{asset_id}、/v1/media/videos/{asset_id}	读取归档媒体

调用示例：

curl http://127.0.0.1:8000/v1/responses \
  -H "Authorization: Bearer g2a_xxx_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "input": "用三句话解释量子隧穿效应。",
    "stream": true
  }'

客户端密钥可配置模型白名单以及 RPM、并发、额度、过期时间等限制。

出口与 Cloudflare

出口节点按 Build、Web、Console、Web 资源分别隔离，支持 HTTP/HTTPS、SOCKS4/4A、SOCKS5/5H、Resin 协议，提供订阅与文本/Base64 导入、批量探测、过滤、分配与负载均衡。每个 Scope 可独立设置回退策略，固定代理在传输失败后立即发起恢复探测，并在五秒内有界等待后继续重试。代理池租约每次使用新建通道，单一出口轮换失败不会拖累整个池子。

启用 qualityGuard 后，主服务会自动创建不可导出的系统探针身份：

qualityGuard:
  enabled: true
  model: "grok-4.5"

docker compose --profile quality-guard up -d --build

需要 Cloudflare 托管校验时，启动 FlareSolverr sidecar 并在「Runtime Settings → Media & Network → Clearance」中指向 http://flaresolverr:8191。

部署与配置

部署形态	数据库	运行时存储	媒体
单实例	SQLite	内存	本地目录
多实例	PostgreSQL	Redis	共享读写目录

多实例需为每个副本设置唯一的 deployment.instanceID 与共享的 clusterID，并在媒体目录就绪后再启用 sharedMedia: true。PostgreSQL 凭据可通过环境变量注入：

GROK2API_DATABASE_URL='postgresql://user:password@host:5432/grok2api?sslmode=require' docker compose up -d

优先级为：内置默认值 → config.yaml → GROK2API_DATABASE_URL。

关键可选配置包括 audit.ledgerMode（observe/enforce）、routing.accountIsolatedConnections、routing.segmentedSelectorEnabled，以及 Build 响应头超时与 403 失效规则的热更新项。

生产检查清单

• 启用 HTTPS 与 auth.secureCookies
• 关闭公网部署的 Swagger
• 使用强且已备份的密钥，禁止提交凭证、Cookie、导出文件与数据库
• 备份 config.yaml、数据库与媒体存储
• 多实例启用 PostgreSQL、Redis 与共享媒体目录
• 在公网部署前部署反向代理与访问控制

开发命令

cd backend
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/grok2api

cd frontend
pnpm install --frozen-lockfile
pnpm lint
pnpm build

修改公共 API 注解后，使用 make swagger 重新生成 Swagger 文档。