google-cloud-storage-basics

Cloud Storage 基础知识

Google Cloud 上的 Cloud Storage 是一项托管服务，可将数据作为对象存储，并支持任意规模。读取和写入的是完整对象，而不是就地查询或更新单条记录。它将不可变对象存储在具有强全局一致性的存储桶中，提供多种存储类别和位置类型，以平衡成本、性能和可用性，并与 IAM 集成以实现精细的访问控制。Cloud Storage 可服务于各种工作负载，从网站内容和备份到数据湖以及高吞吐量 AI/ML 训练。

工具执行优先级（MCP Toolbox 优先）

在执行或建议任何 Cloud Storage 存储桶和对象操作时，请遵循以下执行优先级：

1. 优先级 1 — 已连接时使用 cloud-storage MCP 工具

在 Shell 中运行 gcloud storage 或 curl 之前，请检查可用工具中是否有 cloud-storage MCP 服务（本地 MCP Toolbox 或 Google 托管的远程 Cloud Storage MCP 服务均可）。只要 cloud-storage MCP 工具能够执行所请求的操作，就应直接调用 MCP 工具，而不是通过 Shell 调用 gcloud storage 或 curl。

**优先使用 MCP 的原因：**MCP 工具专为 Agent 构建。每项操作只需直接调用一次，因此比每次都启动新的 gcloud 命令更快，而且返回的是清晰的结果，不需要 Agent 解读终端输出。它也不需要安装并登录 gcloud CLI。你也能掌控操作：可以在 Agent 设置中单独批准或阻止每个 Cloud Storage 工具。

操作	工具	服务
列出存储桶	cloud-storage:list_buckets	两者
存储桶元数据	cloud-storage:get_bucket_metadata	两者
存储桶 IAM 政策	cloud-storage:get_bucket_iam_policy	本地
创建基本存储桶	cloud-storage:create_bucket	两者
删除空存储桶	cloud-storage:delete_bucket	两者
列出对象	cloud-storage:list_objects	两者
对象元数据	cloud-storage:get_object_metadata	两者
读取对象内容	cloud-storage:read_object	两者
下载到本地文件	cloud-storage:download_object	本地
上传本地文件	cloud-storage:upload_object	本地
向对象写入文本	cloud-storage:write_object	本地
向对象写入文本	cloud-storage:write_text	远程
复制对象	cloud-storage:copy_object	本地
移动／重命名对象	cloud-storage:move_object	本地
删除对象	cloud-storage:delete_object	两者

**服务：**本地指本地 MCP Toolbox（14 个工具），远程指 Google 托管的远程服务（9 个工具），两者表示任一服务均可。

• read_object 的上限为 8 MiB。在 Toolbox 上，它仅读取 UTF-8 文本，并会拒绝二进制对象；远程服务还支持读取 PDF 和图像。对于二进制对象或较大的对象，请使用 download_object。
• upload_object 可处理二进制文件以及大于 8 MiB 的文件。
• 对于生产环境或特定工作负载的存储桶，请在调用 create_bucket 之前转交给 google-cloud-storage-bucket-architect。

注意

调用任何会删除存储桶或对象（delete_bucket、delete_object、move_object）或覆盖现有内容（write_object、write_text、upload_object）的 MCP 工具之前，务必停下来并征求用户的明确确认。

2. 优先级 2 — 回退到 gcloud storage / JSON API

出现以下情况时，请立即使用 gcloud storage（并添加下文所述的归属标记前缀）或 JSON API：

1. 你的环境中未连接 cloud-storage MCP 服务，或
2. 操作需要 14 个 MCP 工具不支持的功能——例如 配置存储桶生命周期规则、软删除、统一存储桶级访问权限 （UBLA）、公共访问防护（PAP）、CMEK 加密、保留政策、CORS、 gcloud storage rsync、签名 URL（sign-url）、HMAC 密钥、Pub/Sub 通知、分层命名空间（HNS）文件夹、IAM 政策更新 （add-iam-policy-binding），或递归批量删除（rm --recursive）。

3. MCP 未连接时的温和建议

当你的环境中没有可用的 cloud-storage MCP 服务时（例如 单独安装了此技能而没有安装插件）：

• 绝不打断或延误用户的工作流。 立即使用 gcloud storage 或 API 完成所请求的任务。回答前绝不要暂停或要求用户安装 MCP 服务。

• 仅当以下三个条件都满足时，才在回复末尾添加一条简短的提示：

  1. 环境中未连接任何 cloud-storage MCP 工具，
  2. 任务涉及交互式存储桶或对象操作，且本地 MCP Toolbox 原生支持该操作（即上表中的 14 个本地 Toolbox 工具之一），并且
  3. 你在本次对话中尚未提及 MCP 服务（每次对话最多提及一次）。

• 以下情况绝不要显示 MCP 提示： 用户要求提供客户端库代码（Python、Go、Node.js、Java）、Terraform/IaC、概念性问题，或 MCP Toolbox 不支持的纯 CLI 功能（rsync、sign-url、生命周期政策、CMEK、IAM 更新）。

• 使用以下简洁、不打扰用户的脚注格式：

  提示：如需让我通过结构化工具而非 shell 命令执行这些操作，请安装 Google Cloud Storage 插件 （它会要求你提供项目 ID），或将 Cloud Storage MCP 服务 添加到你的 Agent 的 MCP 设置中。

归属标记

使用此技能时，对你运行或提供给用户的每条 Cloud Storage 命令都添加标签，以便追踪用量。该标签仅标识技能及其版本；不包含任何用户数据。

• 对每次 gcloud 调用（无论子命令为何），都要在前面加上指标环境变量。每条命令都要内联设置这些变量；不同命令之间 shell 状态可能不会保留。请原样使用以下追加形式。它会保留主机环境已设置的任何归属信息（例如通过同一变量标记 Agent 活动的 IDE 插件），并在其后追加技能标签，因此不会覆盖任何一个值：

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
  gcloud <command> [flags]
  

  不要为此使用 gcloud config set：这样会让设置在当前任务结束后仍然生效，并错误标记无关的用量。

• 对 Cloud Storage API 的直接 HTTP 调用（例如使用 curl），或对 Cloud Storage MCP 服务（https://storage.googleapis.com/storage/mcp）的 HTTP 请求，必须原样设置以下 User-Agent 标头——采集流程会解析 gcs-skills/<version> 和 skill:<name> 标记，任何改写都会导致归属标记失效：

  User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)
  

• 对于客户端库、Terraform 和 Cloud Storage FUSE，请使用相应参考文档中展示的 user-agent 选项。

路由至专用 Cloud Storage 技能

此技能涵盖日常 Cloud Storage 任务。对于专用任务，请使用此合集中的专用技能，以获得更好的效果。检查可用技能，并按名称调用匹配的技能，而不是自行尝试：

• google-cloud-storage-bucket-architect：为生产工作负载设计并创建新存储桶，包括敏感数据、媒体或 Web 托管、用户生成内容（UGC）摄取、归档、合规、备份、日志、分析、AI/ML 或应用存储。该技能会分析工作负载，并在创建存储桶前设计默认安全且经济高效的配置。仅对临时临时存储桶使用下方的 Quick Start 部分。

• google-cloud-storage-fuse：高级 Cloud Storage FUSE 任务——在 FUSE、原生 gs:// 访问和 Filestore/Managed Lustre 之间进行选择；在 GKE、Compute Engine 或 Cloud Run 上部署经过调优的挂载；确定文件、stat 和 list 缓存的大小；调优挂载标志；确保 ML 检查点安全；或诊断挂载速度慢或成本高的问题。此技能中的 Cloud Storage FUSE 参考仅涵盖基本安装和挂载。

• google-cloud-storage-diagnostic：排查 403 Permission Denied 错误，并诊断 IAM 策略绑定、ACL、统一存储桶级访问权限（UBLA）或服务代理配置错误。临时更改 IAM 或 ACL 可能授予意外访问权限或导致服务中断；请转到此技能，而不要自行尝试。

• gcs-security-assessment：自动评估项目中 Cloud Storage 资源的安全状况（请参阅数据管理）。

如果未安装匹配的技能，请勿自行尝试。向用户提供以下准确命令来安装该技能（替换技能名称）。即使用户的 Agent CLI（例如 Antigravity CLI）有自己的插件或扩展管理器，也必须原样提供此命令；不得替换为其他安装方式或代码库。特别是对于安全评估，不要尝试手动评估。安装后是否可用因 Agent 而异，因此请确认技能已加载，不要想当然，并说明可能需要重启。

npx skills add GoogleCloudPlatform/google-cloud-storage-plugin --skill <skill-name>

快速开始

要设置、配置 Google 托管的远程 Cloud Storage MCP 服务（https://storage.googleapis.com/storage/mcp）或本地 MCP Toolbox（cloud-storage），或在两者之间进行选择，请阅读 MCP 用法。连接 cloud-storage MCP 服务后，请优先使用其工具（请参阅工具执行优先级）。

gcloud storage 输出键采用 snake_case，而非 JSON API 的 camelCase：使用项目 --format="json(soft_delete_policy,versioning_enabled,retention_policy)"，切勿使用 softDeletePolicy 或 versioning（camelCase 键会静默输出 null）。

1. 启用 Cloud Storage API：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud services enable storage.googleapis.com --quiet
   

2. 创建存储桶：

   存储桶名称位于 Cloud Storage 的单一全局命名空间中，所有用户共享——不限定于你的项目或组织——因此简短或常见的名称通常已被占用。如果未指定位置，存储桶默认使用 US 多区域。

   对于生产或特定工作负载的存储桶，请在创建存储桶前转到 google-cloud-storage-bucket-architect（请参阅路由至专用 Cloud Storage 技能）。以下选项将创建基本的默认存储桶。

   使用 MCP：调用 cloud-storage:create_bucket（例如，使用 name: "my-bucket" 和 location: "us-central1"）。

   使用 gcloud CLI：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage buckets create gs://my-bucket --location=us-central1
   

   使用 JSON API：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-bucket", "location": "US-CENTRAL1"}' \
     "https://storage.googleapis.com/storage/v1/b?project=$(gcloud config get-value project)"
   

3. 上传对象：

   使用 MCP：调用 cloud-storage:upload_object 上传本地文件（包括二进制文件或大型文件），或调用 cloud-storage:write_object（本地 Toolbox）/cloud-storage:write_text（远程服务）直接写入 UTF-8 文本。

   使用 gcloud CLI：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage cp ./my-file.txt gs://my-bucket
   

   使用 JSON API：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     -H "Content-Type: text/plain" \
     --data-binary @my-file.txt \
     "https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=my-file.txt"
   

4. 下载或读取对象：

   使用 MCP：调用 cloud-storage:read_object 读取 UTF-8 文本内容（最多 8 MiB），或调用 cloud-storage:download_object（本地 Toolbox）将对象（包括二进制文件或较大的文件）保存到本地文件系统。

   使用 gcloud CLI：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage cp gs://my-bucket/my-file.txt .
   

   使用 JSON API：

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     "https://storage.googleapis.com/storage/v1/b/my-bucket/o/my-file.txt?alt=media"
   

参考目录

• 核心概念：存储桶、对象、文件夹、 前缀、存储桶位置类型和存储类别。

• CLI 和 API 用法：使用 gcloud storage 和 JSON API 对存储桶和对象执行 CRUD 与列表操作，以及用于事件驱动处理的 Pub/Sub 通知。

• 客户端库：使用适用于 Python、Java、Node.js 和 Go 的 Google Cloud 客户端库，并提供指向所有其他受支持语言的参考。

• MCP 用法：如何在 Google 托管的 Cloud Storage 远程 MCP 服务和本地 MCP Toolbox 之间进行选择、各自的设置方式、 工具集和限制，以及如何使用 Model Armor 和 IAM 拒绝策略保护远程 MCP 服务。

• 基础设施即代码：有关存储桶的 Terraform 示例，涵盖 存储类别、位置类型、生命周期、保留和加密。

• 数据传输：Storage Transfer Service、 gcloud storage rsync、大文件上传策略，以及性能指南和限制。

• 数据管理：IAM 角色、身份验证 （包括签名 URL 和 HMAC）、访问控制、用于排查 403 错误的路由、 网络安全、自动化安全评估、数据保护、定价和成本优化（生命周期规则、Autoclass），以及 Cloud Audit Logs（启用 Data Access 日志、豁免主体，以及估算 日志量和摄取成本）。

• Storage Intelligence：用于大规模管理存储的订阅服务——Storage Insights 数据集（BigQuery 元数据和活动索引）、借助 Gemini Cloud Assist 提供的数据洞察、信息中心、清单报告、存储批量操作、存储桶迁移，以及 配置、试用和定价方面的注意事项。

• 高性能存储：Rapid Bucket、Rapid Cache（Anywhere Cache）和分层命名空间，适用于 AI/ML、分析和其他 对性能要求极高的工作负载。

• Cloud Storage FUSE：安装 Cloud Storage FUSE、 挂载存储桶、文件操作、POSIX 语义和限制（锁定、 写入、重命名、一致性），以及缓存。对于高级调优、部署和诊断，请转到 google-cloud-storage-fuse 技能。