企业官网建设流程全解析

Antigravity-Manager HTTP API 参考指南：8045 端口统一网关的鉴权、管理接口与 AI 协议兼容详解

【免费下载链接】Antigravity-ManagerProfessional Antigravity Account Manager & Switcher. One-click seamless account switching for Antigravity Tools. Built with Tauri v2 + React (Rust).专业的 Antigravity 账号管理与切换工具。为 Antigravity 提供一键无缝账号切换功能。项目地址: https://gitcode.com/gh_mirrors/an/Antigravity-Manager

本指南以 Antigravity-Manager（Antigravity Tools）v4.3.0 的 HTTP API 为对象，完整梳理统一端口8045上的双重角色服务器：面向 AI 客户端的 OpenAI / Anthropic / Google 协议兼容接口，以及面向账号、配置与监控的管理后台接口。读完本文你将掌握两种接口的鉴权方式、全部管理端点的请求语义与参数示例，并能结合仓库源码理解切换账号、热更新模型映射、Token 统计等能力的底层实现链路。

1. 概览：一个端口，双重角色

Antigravity Gateway（即本项目内置的反代与管理服务器）在同一进程、同一端口上同时扮演两个角色：

1. AI Proxy Interface：兼容 OpenAI / Anthropic / Google 官方 SDK 的标准接口，AI 客户端（Claude Code、Cursor、Cherry Studio、Codex CLI 等）可以直接把 Base URL 指向本服务。
2. Management Admin API：用于管理账号、配置系统、监控流量的 RESTful 接口，供管理后台（Tauri 前端）或脚本化控制使用。

版本注意：自 v4.0.1 起，所有服务（包括 AI 反代与系统管理）均已整合至统一端口8045，原有的 19527 端口已废弃。这一点在源码中也有体现：旧版独立的 HTTP API 模块 modules/http_api.rs 仍保留DEFAULT_PORT: u16 = 19527常量（且注明"当前未在主流程中启用"），而当前主流程的服务器由 proxy/server.rs 承载，通过bind_tcp_listener(&host, port)监听统一端口，其中port默认即 8045。

1.1 鉴权体系（Authentication）

两种接口采用完全不同的鉴权路径：

提示：默认情况下，Admin Token与API Key是同一个值（即您在.env或 Docker 环境变量中设置的API_KEY）。

从源码实现看，管理接口的鉴权中间件admin_auth_middleware（定义于 proxy/middleware/auth.rs）为"强制严格鉴权"模式：除/health、/healthz、/api/health等健康检查端点保持公开外，其余/api/*请求一律要求凭证。凭证的解析兼容多种标准 Header（Authorization: Bearer <token>、x-api-key、x-goog-api-key），并优先使用独立的admin_password（若未设置则回退到api_key）进行比对：

• 若admin_password已配置，管理接口使用admin_password校验；
• 若未配置，则回退使用api_key（即文档所述的"默认 Admin Token 与 API Key 相同"）；
• 若两者均为空，中间件将直接拒绝请求并返回 401。

同时，ProxyAuthMode（见 proxy/config.rs 中的枚举：Off/Strict/AllExceptHealth/Auto）控制 AI 代理接口的鉴权策略：Off模式下请求直接放行（但仍会尝试识别 User Token 以便记录用量），AllExceptHealth模式仅豁免健康检查，Strict模式则对 AI 接口也强制校验 API Key。

2. 管理接口（Management API）

Base URL：http://<host>:8045/api

所有管理端点均挂在/api前缀之下（源码中通过Router::new().nest("/api", admin_routes)注册，见 proxy/server.rs）。在应用管理鉴权层之前，还叠加了monitor_middleware、auth_middleware、ip_filter_middleware、service_status_middleware与cors_layer等全局中间件；请求体大小默认限制为 100MB，可通过环境变量ABV_MAX_BODY_SIZE调整（源码中std::env::var("ABV_MAX_BODY_SIZE")解析失败时回退100 * 1024 * 1024）。

2.1 账号管理（Account Management）

切换账号的底层实现（源码admin_switch_account，见 proxy/server.rs 的 handler）：

• 切换采用互斥保护：若已有切换任务在执行，新请求直接返回409 Conflict（"Another switch operation is already in progress"），防止并发切换导致状态错乱；
• 请求结构体SwitchRequest包含account_id与可选的target_ide两个字段，对应文档中的targetIde语义。仓库测试用例test_switch_request_deserialization_with_and_without_target_ide明确验证了传"agy"时target_ide被正确解析；
• 切换成功后，服务会立即清理内存会话缓存（token_manager.clear_all_sessions()）并重新加载账号（token_manager.load_accounts()），确保新账号凭据立即对后续 AI 请求生效（对应 Issue #1166 的修复）。

账号列表的返回结构：GET /accounts返回{ accounts: [...], current_account_id }，每个账号对象包含id、email、name、is_current、disabled、disabled_reason、disabled_at、proxy_disabled、protected_models、live_limited_models、quota（含models、last_updated、subscription_tier、is_forbidden、quota_groups）、device_bound、last_used以及 403 验证阻止状态（validation_blocked等），字段序列化逻辑见 proxy/server.rs 的to_account_response。

2.2 系统配置（System Config）

模型映射的热更新原理：POST /proxy/mapping对应admin_update_model_mapping，它写入AxumServer.custom_mapping（一个Arc<RwLock<HashMap<String, String>>>），从而实现对模型映射规则的全量热更新，无需重启服务（update_mapping注释明确为"模型映射 (Custom) 已全量热更新"）。类似地，反代上游代理、代理池、安全配置、z.ai 配置、实验性配置等也都有对应的热更新方法（update_proxy、update_proxy_pool、update_security、update_zai、update_experimental、update_debug_logging、update_user_agent），POST /config保存配置后这些状态会同步刷新。

2.3 监控与统计（Monitoring & Stats）

流量日志

• GET/logs：获取日志列表（支持limit,offset,filter,errorsOnly参数）
• GET/logs/count：获取日志总数
• GET/logs/:id：获取日志详情
• POST/logs/clear：清空日志

日志数据来自反代监控模块（ProxyRequestLog），GET /logs返回{ total, logs }结构；limit缺省时默认取 50，filter与errorsOnly会下推到数据库层做过滤统计（对应proxy_db::get_logs_filtered与get_logs_count_filtered）。

Token 统计（v4.0.1 New）

• GET/stats/token/summary：获取 Token 消耗摘要（今日/本周/总量）
• GET/stats/token/hourly：获取按小时统计数据
• GET/stats/token/daily：获取按日统计数据
• GET/stats/token/by-account：按账号统计消耗占比
• GET/stats/token/by-model：按模型统计消耗占比
• POST/stats/token/clear：重置统计数据

在源码路由表中，Token 统计接口还扩展了weekly、model-trend/hourly、model-trend/daily、account-trend/hourly、account-trend/daily等更细粒度的维度，数据由token_stats模块（modules/token_stats.rs）提供，可用于监控面板的趋势图与占比图。

2.4 高级功能（Advanced）

• POST/proxy/cli/sync：执行 CLI（Claude/Codex）配置文件同步
• POST/accounts/import/db：从 v1 旧数据库导入账号
• POST/accounts/oauth/start：发起 OAuth 授权流程 (Headless)
• POST/proxy/cloudflared/start：启动 Cloudflare Tunnel

围绕这些高级功能，源码路由还提供了更完整的能力矩阵，均可通过/api前缀访问：

• CLI 同步族：/proxy/cli/status、/proxy/cli/restore、/proxy/cli/config；OpenCode 同步族/proxy/opencode/*（status/sync/openai-sync/restore/clear/config/families）；Droid 同步族/proxy/droid/*（status/sync/restore/config）。对应实现见 cli_sync.rs、opencode_sync.rs、droid_sync.rs。
• OAuth 流程：/accounts/oauth/prepare、/accounts/oauth/complete、/accounts/oauth/cancel、/accounts/oauth/submit-code、/accounts/oauth/clients等，支撑 Headless 环境下的授权登录（对应模块 modules/oauth.rs 与 modules/oauth_server.rs）。
• 设备指纹管理：/accounts/:accountId/bind-device、/accounts/:accountId/device-profiles、/accounts/:accountId/device-versions、/accounts/device-preview、/accounts/restore-original及版本恢复/删除端点，绑定结果返回machine_id、mac_machine_id、dev_device_id、sqm_id四元组。
• 代理池管理：/proxy/pool/config、/proxy/pool/bindings、/proxy/pool/bind、/proxy/pool/unbind、/proxy/pool/binding/:accountId，以及/proxy/health-check/trigger手动触发健康检查。
• 安全与 IP 监控：/security/logs、/security/stats、/security/blacklist（增删查）、/security/whitelist、/security/config等，配合 middleware/ip_filter.rs 实现请求级 IP 过滤。
• 用户令牌（User Token）：/user-tokens（列表/创建）、/user-tokens/summary、/user-tokens/:id/renew、/user-tokens/:id（删除/更新），用于多用户场景的令牌发放与用量追踪。
• 系统管理：/system/data-dir、/system/updates/*、/system/autostart/*、/system/http-api/settings、/system/antigravity/path、/system/cache/clear等。
• 反代辅助：/proxy/api-key/generate、/proxy/rate-limits（清空限流状态）、/proxy/preferred-account、/proxy/monitor/toggle、/proxy/stats。

2.5 管理接口调用示例

# 获取账号列表 curl -H "x-admin-token: <TOKEN>" http://127.0.0.1:8045/api/accounts # 获取当前活跃账号 curl -H "x-admin-token: <TOKEN>" http://127.0.0.1:8045/api/accounts/current # 切换账号（targetIde 可选；传 "agy" 时仅写入凭据、免重启 IDE） curl -X POST http://127.0.0.1:8045/api/accounts/switch \ -H "x-admin-token: <TOKEN>" \ -H "Content-Type: application/json" \ -d '{"accountId": "acc_123", "targetIde": "agy"}' # 刷新所有账号配额 curl -X POST http://127.0.0.1:8045/api/accounts/refresh \ -H "x-admin-token: <TOKEN>" # 查询指定账号配额 curl -H "x-admin-token: <TOKEN>" http://127.0.0.1:8045/api/accounts/acc_123/quota # 热更新模型映射规则 curl -X POST http://127.0.0.1:8045/api/proxy/mapping \ -H "x-admin-token: <TOKEN>" \ -H "Content-Type: application/json" \ -d '{"custom_mapping": {"gpt-4o": "claude-sonnet-4"}}' # 获取 Token 消耗摘要 curl -H "x-admin-token: <TOKEN>" http://127.0.0.1:8045/api/stats/token/summary # 健康检查（无需鉴权） curl http://127.0.0.1:8045/api/health

说明：以上示例使用文档约定的x-admin-tokenHeader；从 middleware/auth.rs 的实现看，管理接口同样接受Authorization: Bearer <token>、x-api-key、x-goog-api-key等标准 Header 携带同一凭证，实际接入时可按客户端习惯选用。

3. AI 协议接口（AI Protocol Interface）

Base URL：http://<host>:8045

本服务完全兼容主流 AI 厂商的官方协议规范，可以直接将本服务地址填入支持 OpenAI / Claude 的客户端中。源码中 AI 路由与/api管理路由在同一个 Axum 应用中注册（Router::new().nest("/api", admin_routes).merge(proxy_routes)），并按照洋葱模型依次经过ip_filter -> auth -> monitor中间件，再进入各协议处理器。

3.1 OpenAI Compatible

• 对话生成（Chat Completions）

  • POST/v1/chat/completions
  • 支持模型：任何映射后的模型 ID（如gpt-4o、gemini-1.5-pro）
  • 兼容性：完全兼容 OpenAI 官方 Response 格式（包括流式 SSE）
  • 处理器为handlers::openai::handle_chat_completions（见 proxy/handlers/openai.rs），底层通过 mappers/openai 系列完成请求/响应转换、流式转发与思维链恢复。

• 图片生成（Image Generation）

  • POST/v1/images/generations
  • 支持模型：gemini-3-pro-image（自动映射到 Imagen 3）
  • 参数扩展：支持size: "1920x1080"、quality: "hd"等高级参数
  • 同族端点还包括/v1/images/edits（图像编辑）与/v1/audio/transcriptions（音频转录），分别由handlers::openai::handle_images_edits与handlers::audio::handle_audio_transcription处理。

此外，为兼容 Codex CLI 等客户端，还注册了/v1/responses（POST 与 WebSocket GET）、/responses、/responses/compact、/v1/completions等端点，/v1/models用于列出可用模型。

3.2 Anthropic Compatible

• Claude Messages
  • POST/v1/messages
  • 用途：支持 Claude CLI（claude）、Cursor、Cherry Studio 等客户端
  • 特性：完整支持 Tool Use（工具调用）和 Thinking（思维链）模式
  • 处理器为handlers::claude::handle_messages（见 proxy/handlers/claude.rs），配套端点还包括/v1/messages/count_tokens（Token 计数）与/v1/models/claude（模型列表）。Tool Use / Thinking 的映射细节位于 mappers/claude 目录（request/response/streaming/thinking_utils 等）。

3.3 Gemini Native

• Google AI Studio
  • GET/POST/v1beta/models/*
  • 用途：供使用 Google 官方 SDK（Python/Node.js）的应用调用
  • 路由注册于 proxy/server.rs：/v1beta/models列表、/v1beta/models/:model（GET 取模型信息、POST 执行generateContent）、/v1beta/models/:model/countTokens，处理器见 proxy/handlers/gemini.rs 与 proxy/mappers/gemini 的封装层。

3.4 其他协议辅助端点

• POST/v1/models/detect：模型自动探测（handlers::common::handle_detect_model）
• POST/internal/warmup：内部预热端点（handlers::warmup::handle_warmup，豁免鉴权）
• POST/v1/thinking/end、GET/DELETE /v1/thinking/sessions/:session_id：思维链会话的结束、统计与删除（handlers/thinking.rs）
• MCP 反代：/mcp/web_search_prime/mcp、/mcp/web_reader/mcp、/mcp/zai-mcp-server/mcp（handlers/mcp.rs），支持将 z.ai 系列 MCP 服务通过本网关反代。

3.5 AI 接口调用示例

# OpenAI 兼容：Chat Completions（流式） curl http://127.0.0.1:8045/v1/chat/completions \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}], "stream": true }' # Anthropic 兼容：Claude Messages curl http://127.0.0.1:8045/v1/messages \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}] }' # 图片生成（映射到 Imagen 3） curl http://127.0.0.1:8045/v1/images/generations \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-image", "prompt": "a mountain lake at sunset", "size": "1920x1080", "quality": "hd" }' # Gemini Native：generateContent curl http://127.0.0.1:8045/v1beta/models/gemini-1.5-pro:generateContent \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{"contents": [{"parts": [{"text": "Hello"}]}]}'

4. 从源码理解请求处理链路

将文档中的接口清单与 proxy/server.rs 的路由注册对照，可以总结出如下处理链路：

1. 入口层：所有请求先经过service_status_middleware（服务状态）与cors_layer（CORS，允许本地任意来源调用），再按路径分发到/api管理路由或 AI 代理路由；
2. IP 过滤层：ip_filter_middleware根据安全配置中的黑名单/白名单决定是否放行（middleware/ip_filter.rs）；
3. 鉴权层：auth_middleware（AI 接口，遵循auth_mode）或admin_auth_middleware（管理接口，强制严格校验）执行凭证校验，并通过UserTokenIdentity扩展注入用户身份；
4. 监控层：monitor_middleware记录请求/响应、采集 Token 用量（在鉴权之后执行，才能拿到用户身份）；
5. 业务层：各协议处理器（handlers）完成协议转换，经由上游客户端（proxy/upstream/client.rs）转发到真实厂商，并将响应按原协议格式返回。

其中账号切换、配额刷新等管理操作还会联动TokenManager（proxy/token_manager.rs）与AccountService（modules/account_service.rs）：切换后清空会话、重载账号缓存；配额更新后通过全局待重载队列（PENDING_RELOAD_ACCOUNTS）通知TokenManager在下次取 Token 时刷新；账号删除则进入PENDING_DELETE_ACCOUNTS队列清理内存缓存。

5. 实践建议与注意事项

• 端口确认：统一端口为 8045；若您在旧版本上配置过 19527，请同步更新客户端 Base URL 与环境变量。
• 凭证安全：管理接口具备完整的状态控制能力（删号、改配置、清日志），建议在部署时设置独立的admin_password；未设置时务必保管好API_KEY，因为它同时是 Admin Token 与 AI 接口密钥。
• 健康检查：/health、/healthz、/api/health无需鉴权，适合接入 Docker Compose 或系统监控的探针（docker-compose.yml 中 healthcheck 可复用该端点）。
• 模型映射：POST /api/proxy/mapping支持运行时热更新，无需重启进程即可调整gpt-4o -> claude-sonnet-4之类的映射关系；更完整的映射逻辑可参考 docs/model-remapping-logic.md。
• 并发切换保护：账号切换接口在并发时会返回 409，客户端脚本应做好重试或串行化。
• 限流与安全：反代内置 Rate Limit（proxy/rate_limit.rs）与 IP 安全策略，管理接口可随时通过/api/proxy/rate-limits清空限流状态，避免误伤。

本参考与仓库当前实现保持一致；如需在本地验证接口行为，可通过 docker/Dockerfile 构建镜像后以 8045 端口运行，或直接运行桌面版（Tauri）应用后访问http://127.0.0.1:8045。

【免费下载链接】Antigravity-ManagerProfessional Antigravity Account Manager & Switcher. One-click seamless account switching for Antigravity Tools. Built with Tauri v2 + React (Rust).专业的 Antigravity 账号管理与切换工具。为 Antigravity 提供一键无缝账号切换功能。项目地址: https://gitcode.com/gh_mirrors/an/Antigravity-Manager