注意：此文档集适用于 Gemini Enterprise 的 Standard 版、Plus 版、随用随付版和一线员工版。如需查看 Business 版文档，请参阅 Gemini Enterprise - Business 版帮助中心。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

部署 Google Antigravity 企业版网关

本文档向管理员和安全架构师展示了如何为 Google Antigravity 部署和配置企业网关。

受监管行业的企业组织通常会实施严格的网络控制，以防止开发者工作站直接通过互联网连接到外部服务，或完成基于浏览器的交互式 Google 登录。

借助 Antigravity Enterprise Gateway，您可以通过组织运营的企业网关路由 Antigravity 流量，然后再将推理请求转发到 Google。此架构通过网关路由模型推理请求，并移除交互式登录，同时保留 Gemini Enterprise 合约结算归因。

概览

配置 Antigravity Enterprise Gateway 后，开发者工作站会与企业网关通信，而不是直接连接到 Google。开发者使用网关颁发的 API 密钥向网关进行身份验证，因此 Antigravity 不会提示他们使用个人 Google 账号登录。然后，您的网关会使用集中式Google Cloud 服务账号向 Google 进行身份验证并转发 Antigravity 请求。

Antigravity 会自动附加客户端归因标头，以识别开发者聊天提示和 Agentic Workflows。为确保系统能够识别此模型的使用情况，并根据贵组织现有的 Gemini Enterprise 协议进行结算，而不是作为未承诺的原始 API 消耗进行结算，您的网关必须保留这些 Antigravity 标头并将其转发给 Google：

User-Agent：Antigravity 会自动发出一个标识标头：

User-Agent: antigravity/<var>VERSION</var> (aidev_client; auth_method=gateway)

X-Goog-Api-Client：标识 Antigravity 客户端运行时和 SDK 遥测，以便 Google 将活动归功于您获得许可的企业部署。

支持的工具和版本

Antigravity Enterprise Gateway 支持以下 AI 开发者工具：

工具	最低版本	支持的平台
Antigravity 应用	2.15.0 或更高版本	macOS、Windows 和 Linux
Antigravity CLI (`agy`)	1.2.15 或更高版本	macOS 和 Linux
Antigravity for IDEs	Visual Studio Code 和 Visual Studio：Antigravity CLI 1.2.15 或更高版本，扩展程序会自动下载和更新。 JetBrains IDE 和 Zed（使用 ACP 服务器）：1.3.0 或更高版本	Visual Studio Code、Visual Studio、JetBrains IDE 和 Zed。如需了解详情，请参阅 Antigravity IDE 扩展程序。

准备工作

在部署网关之前，请验证您是否具备以下条件：

Google Cloud 项目：一个 Google Cloud 项目，该项目有权访问 Gemini Enterprise Agent Platform（原 Vertex AI），并且已启用 Gemini Enterprise Agent Platform API (aiplatform.googleapis.com)。部署企业网关不需要账单结算 Cloud Billing 账号。任何有权访问 Gemini Enterprise Agent Platform 的用户都可以使用该网关。
服务账号：项目中被授予 roles/aiplatform.user IAM 角色的 Google Cloud 服务账号。您的网关会使用此服务账号向 Google Cloud验证 Antigravity 请求。
数据访问审核日志：如需在 Cloud Logging 中验证结算归因，请为 Gemini Enterprise Agent Platform API 启用数据访问审核日志。如需了解详情，请参阅启用数据访问审核日志。
支持的客户端版本：开发者必须使用每个 Antigravity 工具的支持版本。如需了解详情，请参阅支持的 Antigravity 工具。

部署企业网关

您可以使用任何容器化或代管式平台（例如 Cloud Run、Envoy、LiteLLM 或 Apigee）托管企业网关。

网关必须满足以下三项基础设施要求：

保留客户端归因标头：将传入的客户端标头原封不动地转发给 Google，包括 User-Agent、X-Goog-Api-Client 以及在 gateway.customHeaders 中配置的所有自定义标头（例如 X-Cost-Center）。

Antigravity 客户端在网关模式下不会发送 Google Cloud 项目信息。如果您的网关将请求转发到包含网关服务账号的项目以外的项目，请将网关配置为注入 X-Goog-User-Project 标头，其中包含用于结算和配额归因的目标项目 ID。
支持无缓冲流式传输：在处理流式传输请求 (:streamGenerateContent?alt=sse) 时，立即刷新服务器发送的事件 (SSE) 数据块。不要在网关层缓冲数据块。
确认遥测端点：使用 HTTP 200 OK ({}) 响应后台指标调用 (POST /v1beta:*)，或将其转发到您的安全信息和事件管理 (SIEM) 系统。

强制性请求路径

网关必须路由以下推理路径。路径相对于网关网址。例如，对 https://gateway.cymbal.com 的流式传输请求使用 https://gateway.cymbal.com/v1beta/models/<var>MODEL_ID</var>:streamGenerateContent?alt=sse。

流式推理：POST /v1beta/models/<var>MODEL_ID</var>:streamGenerateContent?alt=sse
一元推理： POST /v1beta/models/<var>MODEL_ID</var>:generateContent

您的网关还必须接受等效的完整 Gemini Enterprise Agent Platform 路径：

流式推理：POST /v1beta1/projects/<var>PROJECT_ID</var>/locations/<var>REGION</var>/publishers/google/models/<var>MODEL_ID</var>:streamGenerateContent?alt=sse
一元推理： POST /v1beta1/projects/<var>PROJECT_ID</var>/locations/<var>REGION</var>/publishers/google/models/<var>MODEL_ID</var>:generateContent

请求正文使用标准 generateContent JSON 架构（contents、generationConfig、safetySettings 和 systemInstruction）。

支持的有线协议

Antigravity Enterprise Gateway 支持两种用于推理请求的有线协议：

Gemini 协议 (genai)：默认传输协议。Antigravity 会将采用 Google generateContent 架构格式的推理请求发送到前面所述的 POST /v1beta/models/... 端点。
OpenAI 传输协议 (openai)：将 gateway.wireProtocol 设置为 openai（或设置 AGY_LLM_GATEWAY_WIRE_PROTOCOL=openai）后，Antigravity 会按照 OpenAI Chat Completions 协议格式化推理请求，并将其发送到 POST /v1/chat/completions。

对发送至网关的请求进行身份验证

Antigravity 使用网关颁发的 API 密钥向网关进行身份验证。Antigravity 会将 gateway.apiKey（或 AGY_LLM_GATEWAY_API_KEY 环境变量）中的密钥作为不记名令牌在 Authorization 标头中发送：

Authorization: Bearer <var>GATEWAY_API_KEY</var>

Antigravity 不会代表开发者获取 Google Cloud 凭据、OAuth 令牌或客户端证书。您的网关必须对每个请求进行身份验证，并拒绝未提供有效密钥的请求。

由于 API 密钥存储在开发者工作站上，因此请将其与网络级控制措施结合使用：

将网关设为不公开：仅在公司网络上公开网关，例如通过工作站通过 Cloud VPN 或 Cloud Interconnect 访问的内部应用负载均衡器。请勿为网关提供公共端点。
限制哪些设备可以连接：仅允许来自受管理工作站的连接，例如使用防火墙规则、零信任网络访问代理或设备状态检查。
保护和轮替密钥：将密钥存储在 Secret Manager 中，在每次请求时验证密钥，并定期轮替密钥。如需将用量归因于各个开发者，请向每个开发者单独发放密钥。

如需了解详情，请参阅安全注意事项。

将网关连接到 Gemini Enterprise Agent Platform

网关使用 Google Cloud 服务账号调用 Gemini Enterprise Agent Platform API。您可以在 Apigee 等代管式 API 网关上构建网关，也可以在自己的基础设施上部署 Envoy 或 LiteLLM 等网关。

启用必需的 API：

gcloud services enable \
  aiplatform.googleapis.com \
  secretmanager.googleapis.com \
  --project=<var>PROJECT_ID</var>

将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

为网关创建服务账号，并向其授予 roles/aiplatform.user 角色：

gcloud iam service-accounts create <var>SERVICE_ACCOUNT_NAME</var> \
  --project=<var>PROJECT_ID</var> \
  --display-name="Antigravity Enterprise Gateway"

gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \
  --member="serviceAccount:<var>SERVICE_ACCOUNT_NAME</var>@<var>PROJECT_ID</var>." \
  --role="roles/aiplatform.user"

将 SERVICE_ACCOUNT_NAME 替换为服务账号的名称，例如 agy-gateway-sa。

生成网关 API 密钥，将其存储在 Secret Manager 中，并让服务账号读取该密钥：

openssl rand -base64 32 | tr -d '\n' | gcloud secrets create <var>SECRET_NAME</var> \
  --project=<var>PROJECT_ID</var> \
  --data-file=-

gcloud secrets add-iam-policy-binding <var>SECRET_NAME</var> \
  --project=<var>PROJECT_ID</var> \
  --member="serviceAccount:<var>SERVICE_ACCOUNT_NAME</var>@<var>PROJECT_ID</var>." \
  --role="roles/secretmanager.secretAccessor"

将 SECRET_NAME 替换为 Secret 的名称，例如 agy-gateway-api-key。您将此密钥作为 admin_settings.json 中的 gateway.apiKey 分发到工作站。

将网关配置为执行以下操作：
- 以服务账号身份向 Gemini Enterprise Agent Platform 进行身份验证。
- 从 Secret Manager 读取 API 密钥，并拒绝未提供该密钥的请求。
- 允许请求运行至少 60 分钟，以免长时间流式传输响应被切断。

如需在配置工作站之前确认网关是否正常运行，请参阅直接测试网关。

使用 MDM 部署设置

如需集中配置开发者工作站，请使用移动设备管理 (MDM) 系统（例如 Jamf、Microsoft Intune、Ansible 或 Google Workspace MDM）部署 admin_settings.json 配置文件。

Antigravity 会从以下操作系统路径读取 admin_settings.json：

macOS： /Library/Application Support/Antigravity/admin_settings.json
Linux： /etc/antigravity/admin_settings.json
Windows： %ProgramData%\Antigravity\admin_settings.json

如需部署设置文件，请执行以下操作：

创建一个 admin_settings.json 文件，其中包含网关网址、API 密钥和已获批准的模型。如需查看示例，请参阅配置示例。

在 MDM 系统中，创建一个软件包、政策或脚本，用于将文件复制到每个目标操作系统的路径。请以管理员权限运行该脚本，以便该文件归管理员账号所有，开发者可以读取但无法修改该文件。例如，您的 MDM 脚本可以运行以下命令：

macOS

在 shell 中，以管理员身份运行以下命令：

sudo mkdir -p "/Library/Application Support/Antigravity"
sudo install -m 644 -o root -g wheel admin_settings.json \
"/Library/Application Support/Antigravity/admin_settings.json"

Linux

在 shell 中，以管理员身份运行以下命令：

sudo install -D -m 644 -o root -g root admin_settings.json \
/etc/antigravity/admin_settings.json

Windows

在 PowerShell 中，以管理员身份运行以下命令：

$dir = Join-Path $env:ProgramData "Antigravity"
# Remove any folder that a non-admin created first, so they can't keep ownership.
if (Test-Path $dir) { Remove-Item -Recurse -Force $dir }
New-Item -ItemType Directory -Path $dir | Out-Null
# Administrators own the folder; only admins and SYSTEM can write; users can read.
icacls $dir /setowner "*S-1-5-32-544"
icacls $dir /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-545:(OI)(CI)RX"
Copy-Item admin_settings.json (Join-Path $dir "admin_settings.json")

这些命令使文件夹和文件可供所有用户读取，并且只能由管理员写入。

将软件包或政策分配给使用 Antigravity 的设备或设备组。
在工作站上重启 Antigravity，以便加载新设置。
如需确认工作站已连接到网关，请参阅验证客户端连接。

设置优先级

Antigravity 会从三个来源读取网关设置。如果在多个来源中定义了相同的设置，则优先级较高的来源会胜出：

管理员设置文件（最高）：由 MDM 系统部署的 admin_settings.json。
环境变量：在工作站上设置的 AGY_LLM_GATEWAY_* 变量。如需了解详情，请参阅将 Antigravity 连接到 Enterprise Gateway。
用户设置文件（最低）：开发者主文件夹中的 ~/.antigravity/settings.json。

设置会逐个字段合并。例如，如果 admin_settings.json 设置了网关网址，但未设置 API 密钥，则 Antigravity 会使用环境变量中的 API 密钥。由于管理员设置文件具有最高优先级，因此开发者无法覆盖您在其中设置的值。

配置示例

以下示例 admin_settings.json 文件将 Antigravity 配置为通过 https://gateway.cymbal.com 处的企业网关路由 AI 流量，附加企业成本中心标头，并将模型选择限制为已获批准的模型：

{
  "gateway": {
    "enabled": true,
    "url": "https://gateway.cymbal.com",
    "apiKey": "<var>GATEWAY_API_KEY</var>",
    "wireProtocol": "genai",
    "customHeaders": {
      "X-Cost-Center": "Platform-Engineering",
      "X-Corporate-BU": "DevTools"
    }
  },
  "caCertPath": "/etc/ssl/certs/cymbal-root-ca.pem",
  "models": {
    "defaultModelId": "gemini-3.8-flash",
    "list": [
      { "modelId": "gemini-3.8-flash" },
      { "modelId": "gemini-3.7-flash" },
      { "modelId": "gemini-3.1-pro-preview" }
    ]
  }
}

此示例配置定义了以下设置：

gateway.enabled：启用网关路由模式。设置为 true 时，Antigravity 会将所有推理请求发送到您的网关，而不是直接发送到 Google，并且不会提示开发者使用 Google 账号登录。
gateway.url：企业网关的 HTTPS 端点 (https://gateway.cymbal.com)。
gateway.apiKey：网关授权请求所需的 API 密钥 (<var>GATEWAY_API_KEY</var>)。此密钥由您的网关（而非 Google）签发。Antigravity 在 Authorization 标头中将其作为不记名令牌发送。
gateway.wireProtocol：API 传输协议。支持的值包括：
- genai（默认）：使用 Gemini API 协议 (POST /v1beta/models/...)。
- openai：使用 OpenAI Chat Completions 传输协议 (POST /v1/chat/completions)。
注意： JetBrains IDE 和 Zed 使用 ACP 服务器，该服务器仅支持 genai 传输协议。
gateway.customHeaders：Antigravity 添加到每个请求的自定义 HTTP 标头（X-Cost-Center 和 X-Corporate-BU）。使用这些标头在网关日志或 SIEM 中将用量归因于团队或成本中心。
caCertPath：企业根证书授权机构 (CA) 软件包的绝对路径。此设置可确保工作站信任网关的内部 TLS 证书。
models.defaultModelId：Antigravity 默认选择的模型（例如 gemini-3.8-flash）。
models.list：开发者可以在 Antigravity 中选择的已获批准的模型。每个条目都需要一个与网关提供的模型匹配的 modelId。如需查看支持的 Google 模型列表，请参阅支持的模型。

安全注意事项

在规划网关身份验证和归因时，请考虑以下事项：

客户端提供的标头不可信：开发者可以控制自己的工作站，因此他们可以更改由环境变量 (AGY_LLM_GATEWAY_HEADERS) 或用户设置文件设置的标头。请勿依赖这些标头进行对安全性至关重要的审核日志记录或结算归因。
使用 MDM 固定标头：为防止开发者覆盖归因或政策标头，请在 admin_settings.json 的 gateway.customHeaders 中定义这些标头。admin_settings.json 中的值优先于环境变量和用户设置。
在网络层或传输层进行身份验证：如需验证开发者身份或强制执行严格的成本中心归因，请在网络层或传输层对流量进行身份验证，例如使用双向 TLS (mTLS)、代理级单点登录 (SSO) 或网络微细分。请勿仅依赖 API 密钥或 HTTP 标头。

验证 Deployment

在将配置文件部署到开发者工作站之前，请验证企业网关是否正确路由流量，以及归因信息是否到达 Cloud Logging。

直接测试网关

在开发者工作站上进行测试之前，请先使用 curl 直接测试企业网关端点。直接测试网关可确认网络路由、TLS 证书验证、身份验证和无缓冲服务器发送事件 (SSE) 流式传输是否独立于 Antigravity 运行。

以下示例 curl 命令会将流式传输请求直接发送到网关端点：

curl -N -X POST "https://gateway.cymbal.com/v1beta/models/<var>MODEL_ID</var>:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer <var>GATEWAY_API_KEY</var>" \
  -H "Content-Type: application/json" \
  -H "User-Agent: antigravity/1.2.15 (aidev_client; auth_method=gateway)" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Reply with PONG"}]}]}'

在此命令中：

-N：关闭 curl 中的响应缓冲，以便服务器发送事件 (SSE) 立即流式传输。
<var>MODEL_ID</var>：models.list 中已获批准的模型（例如 gemini-3.8-flash 或 gemini-3.7-flash）。我们建议您使用 Flash 模型进行测试，以完成初始验证。如需查看可用模型的列表，请参阅支持的模型。
Authorization：发送网关 API 密钥 (<var>GATEWAY_API_KEY</var>)，以通过网关对请求进行身份验证。
User-Agent：发送客户端归因字符串，Google 会使用该字符串将用量归因于您的 Gemini Enterprise 协议。
streamGenerateContent?alt=sse：调用指定模型的流式 API 端点。

验证网关是否立即流式传输响应分块。如果您遇到连接错误、证书警告或响应缓冲延迟，请参阅问题排查。

验证客户端连接

在已配置的工作站上检查客户端状态：

Antigravity 应用：在底部状态栏中，验证指示器是否显示已连接：企业网关。在账号设置中，验证是否显示企业网关模式已启用。
Antigravity CLI：运行测试提示：
```
agy -p "Explain binary search in Go"
```
此命令会向网关发送测试提示。验证响应是否在终端中流式传输，而不会显示交互式 Google 登录提示。如果客户端无法连接或提示进行 Google 身份验证，请参阅问题排查。

在 Cloud Logging 中验证归因

在 Google Cloud 控制台中，验证是否收到了归因标头：

在 Google Cloud 控制台中，前往 Logs Explorer 页面：

转到日志浏览器

请运行以下查询：

resource.type="aiplatform.googleapis.com/Endpoint" OR
protoPayload.serviceName="aiplatform.googleapis.com"

检查日志条目元数据。验证 protoPayload.requestMetadata.callerSuppliedUserAgent 是否包含 antigravity/<var>VERSION</var> (aidev_client; auth_method=gateway)。

如果未显示任何日志条目，请验证是否已为 Gemini Enterprise Agent Platform API 启用数据访问审核日志。

为开发者提供入门指导

验证网关后，请让开发者做好使用 Antigravity 的准备：

受管理的工作站：如果您使用 MDM 系统部署 admin_settings.json，则开发者无需执行任何配置。Antigravity 在启动时会自动连接到网关。
沙盒和 CI/CD 流水线：对于在容器化运行器、远程 SSH 主机或非代管式开发环境中工作的开发者，请提供网关网址、API 密钥和根 CA 路径。引导开发者将 Antigravity 连接到企业网关。

问题排查

下表列出了常见的部署问题以及解决方法：

症状	原因	解决方法
`x509: certificate signed by unknown authority`	工作站不信任网关 TLS 证书。	使用 `admin_settings.json` 中的 `caCertPath` 指定公司根 CA 软件包的路径。
`401 Unauthorized` 或 `403 Forbidden`	API 密钥无效，或网关服务账号缺少访问权限。	验证 `gateway.apiKey` 值，并验证网关服务账号在目标项目中是否具有 `roles/aiplatform.user` IAM 角色。
`404 Not Found`	所请求的模型在企业网关上不可用，或者模型 ID 输入有误。	验证 `admin_settings.json` 的 `models.list` 中配置的每个模型 ID 是否与企业网关提供的模型名称匹配。
`gateway.wireProtocol 'openai' is not supported by the ACP server`	`admin_settings.json` 或环境变量指定了 ACP 服务器不支持的 `openai` 传输协议。	对于 JetBrains IDE 和 Zed 工作站，请将 `wireProtocol` 设置为 `genai`（或省略该参数以使用默认值）。
流式响应超时	网关正在缓冲 HTTP 响应。	将网关配置为针对服务器发送的事件 (`text/event-stream`) 关闭响应缓冲。
Antigravity 提示使用 Google 账号登录	网关模式未开启，或 Antigravity 找不到设置文件。	验证 `admin_settings.json` 是否已部署到正确的操作系统路径，并且在 `gateway` 部分中包含 `"enabled": true` 和 `url`。

后续步骤

了解开发者如何从远程沙盒进行连接：将 Antigravity 连接到企业网关。
详细了解 Antigravity 功能和工作流：Antigravity 文档。
查看开发者工具指标和用量：查看 AI 开发者工具指标。
配置项目安全政策：配置 AI 开发者工具设置。