google-cloud-recipe-onboarding

Google Cloud 入门

此技能为个人开发者提供简洁、非交互式的“顺畅路径”，帮助其开始使用 Google Cloud。内容涵盖环境验证、身份验证、项目选择、关联结算账号以及后续安全串联。

致谢

使用此技能执行命令时，关于 gcloud CLI、REST API 和 MCP 的所有致谢要求，请遵循 使用致谢中的说明。

重要

对于执行此技能的自主 Agent：

1. 变更前检查审计：在提出或执行任何项目或结算变更之前，始终静默执行预执行状态审计。
2. 单问题策略：交互执行期间，每次只向用户询问一个操作参数或确认事项。
3. 非交互式输出：在所有变更命令后追加非交互式覆盖参数（--quiet、--format="json"），确保输出具有确定性且可由机器解析，并避免终端挂起。
4. 首轮交互规则（触发轮次）：当开发者首次以一般入门请求触发此技能时（例如说“我想开始使用 Google Cloud”）：
   • 前置引导：主动提供简短的引导，建议开发者创建 Google Cloud 账号（指向控制台 https://console.cloud.google.com/），并运行 gcloud auth login 来授权其工作站，即使看起来已经登录也应如此。
   • 首轮单问题：静默执行预检审计，但首轮不要展示完整的参数摘要表，也不要请求最终同意。只向开发者提出一个初始操作问题（例如：“您想重复使用现有的有效项目，还是创建一个全新的项目？”）。 注意：如果开发者的初始提示明确表示“我批准入门配置”“我们开始入门流程”，或要求提供试运行计划（例如“向我展示确切的计划或试运行命令”），则跳过常规前置引导和初始问题，直接进入所请求的步骤。

---

概览

对于个人开发者，Google Cloud 入门流程包括验证本地终端工具、建立经过身份验证的会话、选择或创建工作区（Project），并将其关联到有效的结算账号。Google Cloud 为首次使用的用户提供免费层级和含 $300 赠金的免费试用。点击此处了解详情。

---

前提条件

• 个人 Google 账号（例如 @gmail.com），或 Google Workspace / Cloud Identity 账号。
• 有效的付款方式（信用卡或银行账户），用于身份验证并激活“概览”中介绍的 $300 免费试用赠金。

---

步骤

第 1 节：验证主机工具设置

在征求输入或提出变更之前，静默审计主机系统的活动工具和环境状态。

1. 检查是否已安装并可访问 gcloud CLI 二进制文件：

   which gcloud
   

2. 检查是否存在有效的身份验证会话：

   gcloud auth list --format="json"
   

3. 如果 which gcloud 的预执行审计返回有效路径，则直接继续第 2 节：验证身份并路由会话。

4. 如果缺少二进制文件，则停止执行，并引导 Agent 使用 gcloud 技能安装 gcloud。向开发者提供官方的 Google Cloud CLI 安装指南，说明如何设置身份验证。

---

第 2 节：验证身份并路由会话

授权 gcloud CLI 使用开发者的 Google 帐户访问 Google Cloud，并确认该帐户适用于独立开发者入门流程。

1. 执行凭据身份验证：

   gcloud auth login
   

   重要

   新用户 / 未通过身份验证时的指引： 如果执行前状态检查或命令失败确认开发者未通过身份验证（例如，gcloud auth list 结果为空或缺少有效凭据）：

   1. 指引他们前往 Google Cloud Console 创建 Google Cloud 帐户。
   2. 指示他们执行 gcloud auth login 命令，为本地工作站终端会话授权。
   3. 在成功完成身份验证之前，不要尝试创建项目或配置资源。

2. 验证有效身份：

   gcloud config get-value account --format="json"
   

3. 以编程方式检查企业路由的防护措施： 继续操作前，请确认该帐户是否关联到企业组织，因为企业设置必须采用不同的架构：

   gcloud organizations list --format="json"
   

   • 请注意，新的免费试用帐户会自动获得一个 Self-Owned Organization（SOO）。如需区分个人免费试用帐户和企业组织，请检查 JSON 输出：
     • 企业组织（停止执行）：如果输出列表中包含一个 owner.directoryCustomerId 存在的组织节点（确认这是经过网域验证的 Google Workspace 或 Cloud Identity 组织），或者用户的提示词明确提及企业着陆区或多租户项目结构：
       • 立即停止执行此技能。
       • 将开发者引导至官方的 Google Cloud Setup guided flow。
     • 个人帐户 / 免费试用 SOO（继续）：如果输出列表为空 []，或包含一个 Self-Owned Organization（其中 owner.directoryCustomerId 不存在，且 displayName 不是经过验证的网域名称），请继续第 3 节：选择或创建 Google Cloud 项目。

---

第 3 节：选择或创建 Google Cloud 项目

Google Cloud 资源按项目组织。开发者通过控制台注册免费试用时，Google Cloud 会自动创建一个默认项目（例如，“My First Project”）。请始终先检查当前环境，以便重复使用现有项目并避免因令牌消耗而产生冲突错误。

1. 静默发现项目： 列出当前可访问的项目（限制数量，以防上下文窗口溢出）：

   gcloud projects list --filter="lifecycleState=ACTIVE" --limit=20 --format="json"
   

2. 重复使用现有项目（推荐）： 如果列表中有有效项目，请将其展示给开发者，并建议将其设为默认工作项目：

   gcloud config set project {PROJECT_ID} --quiet
   

3. 创建自定义项目： 如果不存在项目，或开发者明确要求创建全新的工作区：

   • 请开发者提供自定义的 PROJECT_ID 和 PROJECT_NAME（单问题策略）。

   • 结构化确认与同意关卡（必需）： 在运行任何项目创建或账单关联命令之前，Agent 必须使用结构化 Markdown 表格汇总目标参数：

     参数	值
     目标项目 ID	{PROJECT_ID}
     目标项目名称	{PROJECT_NAME}
     当前身份账号	{ACCOUNT}
     目标账单账号 ID	{BILLING_ACCOUNT_ID}

     向用户提出以下确切的同意问题： "我已准备好初始化您的 Google Cloud 项目并关联账单。您要我继续吗？"

     重要：Agent 不得在本轮执行任何 gcloud projects create 或账单关联命令。你必须显示此表格并提出确切的同意问题，然后严格停止，等待用户明确同意。

   • 项目 ID 冲突后缀恢复：如果项目创建命令因 PROJECT_ID 已被全局占用而失败（返回 PROJECT_ID_COLLISION 或 ALREADY_EXISTS 错误）：

     • 自动追加一个随机的 4 位数字后缀（例如，将 my-project 改为 my-project-8472）。
     • 向开发者建议这个新的可用项目 ID，并在重试前再次征求同意。

   • 执行项目创建：在确认用户明确同意后：

     gcloud projects create {PROJECT_ID} --name="{PROJECT_NAME}" --quiet --format="json"
     

   • 设置当前工作项目：

     gcloud config set project {PROJECT_ID} --quiet
     

---

第 4 节：验证并关联账单

要在 Google Cloud 上部署资源，项目必须关联一个有效的 Cloud Billing 账号。

1. 检查账单状态： 检查当前项目是否已关联账单账号：

   gcloud billing projects describe {PROJECT_ID} --format="json"
   

2. 如果输出中包含 "billingEnabled": true，则跳过关联步骤，立即继续第 5 节：技能串联（支出控制与工作负载）。

3. 发现可用的账单账号： 如果项目尚未关联，请查询与已验证用户身份关联的可用账单账号句柄：

   gcloud billing accounts list --format="json"
   

4. 关联账单账号： 建议将项目关联到发现的账单账号 ID，然后执行：

   gcloud billing projects link {PROJECT_ID} --billing-account={BILLING_ACCOUNT_ID} --format="json"
   

---

第 5 节：技能链式调用（支出控制与工作负载）

入门设置现已完成。为保护环境并部署工作负载，你可以链式调用下游专用技能：

1. 账单支出控制： 为避免意外超支，可以考虑设置程序化控制，以自动停用结算。停用结算后，项目中的所有 Google Cloud 服务和用量都会终止，以停止进一步产生费用：

• 引导开发者参阅官方的通过通知停用结算用量指南，其中提供了在费用超过项目预算时自动关闭结算的详细说明。

2. 部署工作负载：若要部署首个资源，请触发与目标应用匹配的下游 专用技能（例如， cloud-run-basics 或 bigquery-basics）。如果本地没有该专用技能， 请引导开发者参阅相应的官方快速入门，例如 Cloud Run 容器部署快速入门。 注意：这些下游专用技能各自负责在执行过程中动态启用所需的服务 API（例如 run.googleapis.com）。

---

验证逻辑

完成入门步骤后，使用以下诊断命令以编程方式验证环境状态：

1. 验证 CLI 安装：

   which gcloud
   

2. 验证已通过身份验证的身份：

   gcloud config get-value account
   

3. 验证项目工作区是否存在：

   gcloud projects describe {PROJECT_ID} --format="json"
   

4. 验证结算关联（确保 JSON 输出包含 "billingEnabled": true）：

   gcloud billing projects describe {PROJECT_ID} --format="json"
   

---

其他资源

• Google Cloud 入门主页
• Google Cloud 概览
• Google Cloud 免费计划
• Google Cloud 设置概览
• Google Cloud 设置：高级生产环境基础
• 用量归因：适用于 gcloud CLI、REST API 和 MCP 请求的标准化用量归因标签。