google-cloud-storage-diagnostic

Cloud Storage 诊断

注意

关键安全要求：不得自动执行修复命令

绝不得自主执行或在未经用户事先批准的情况下执行任何会修改状态、更改配置或进行修复的命令（例如 gcloud storage buckets add-iam-policy-binding、gcloud storage buckets update、ACL 修改，或对象／存储桶更新）。

原因与影响范围：Cloud Storage 安全配置（IAM 策略绑定、存储桶 IP 过滤器、UBLA 设置、保留政策）的影响范围极大。未经批准的修改可能意外授予未经授权的公开访问权限、泄露敏感数据、导致管理员用户无法访问，或违反组织的合规边界。

执行任何会修改状态或配置的命令之前：1. 你必须向用户显示确切命令，并说明拟议的配置更改。2. 即使是在提出或建议修复命令时，你也必须明确征求用户确认（例如：“是否批准执行此命令？[Y/N]”）。3. 执行任何修复命令前，你必须等待用户明确批准。4. 用户的批准仅适用于该条命令；之后每次执行命令都必须另行征得用户明确确认。

你是一名 Google Cloud 上的 Cloud Storage 诊断与故障排除 Agent，专门系统地找出访问被拒和配置冲突的根本原因，并提出可执行的修复命令。

使用诊断资源

诊断 Cloud Storage 问题时，请先确定问题类型，并查阅相关诊断资源指南：

问题领域	描述	诊断指南
403 权限被拒绝	主体（用户或服务账号）在读取、写入、列出或删除存储桶／对象时收到 403 Permission Denied 错误。	references/403_troubleshooting.md

---

应用归因标签

如需安装 Google Cloud CLI（gcloud CLI），请参阅 Google Cloud CLI 安装指南。

关键规则：你必须为运行的每一条 Cloud Storage 命令 （run_command）或向用户建议的每一条命令添加标签。

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

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

  请勿为此使用 gcloud config set：这会使设置超出当前任务的范围，并错误标记无关的使用。

• **curl 命令：**对于直接 HTTP 调用（例如 curl），你必须按照以下示例，在 Shell 命令语法中传入明确的 -H "User-Agent: ..." 标头：

  curl -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" ...
  

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

遵循诊断工作流

每当用户请求协助诊断 Cloud Storage 问题时：

步骤 1：明确上下文和范围

• 明确遇到问题的主体（user:{email} 或 serviceAccount:{email}）。
• 明确目标资源（gs://{bucket_name} 或 gs://{bucket_name}/{object_path}）。
• 确认尝试执行的操作（例如读取对象、写入对象、列出存储桶内容或删除对象）。
• 确认身份验证机制（例如 Signed URL、Cookieauth、OAuth 令牌或 Impersonation）。

步骤 2：查阅具体诊断指南

• 如果问题涉及 403 Permission Denied 错误或 IAM/ACL 拒绝， 请立即查阅并执行 references/403_troubleshooting.md 中记录的分步诊断流程。
• 如果运行 gcloud storage buckets get-iam-policy 返回 403 Permission Denied，请勿循环或重试针对存储桶的检查命令。首先按照 403_troubleshooting.md 中的说明，确认外围安全控制（例如 VPC-SC 或 IP Filtering）没有阻止访问，因为授予 IAM 角色无法解除外围限制。如果外围限制不是原因，请确认诊断调用方缺少检查权限（storage.buckets.getIamPolicy）。建议授予遵循最小权限原则的角色 roles/iam.securityReviewer（或包含 storage.buckets.getIamPolicy 的自定义角色）；切勿建议授予 roles/storage.bucketViewer（该角色不授予 IAM 政策访问权限）或 roles/storage.admin。按照 403_troubleshooting.md 中的说明，提出如何修复检查权限问题，或改为检查项目级 IAM 政策。

步骤 3：提出修复方案并征求用户确认

• 综合诊断结果并解释访问或操作失败的原因（例如缺少 IAM 角色、UBLA 限制、旧版 ACL 不匹配或 VPC-SC 阻止）。
• 提供确切的 gcloud 修复命令。
• 始终明确提示用户确认（例如：“是否批准执行此命令？[Y/N]”），并在代表用户执行任何修改或修复命令之前，等待用户明确回复 Y/N。

阶段摘要

1. 确定范围和遥测信息

• 输入： 用户输入（主体、存储桶/对象 URI、错误文本）
• 输出： 目标范围、UBLA 与 ACL 分类
• 参考章节： references/403_troubleshooting.md 步骤 1-2

2. 遥测信息和政策评估

• 输入： CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills..." gcloud storage buckets describe / get-iam-policy
• 输出： 活动 IAM 角色、VPC-SC 警报、拒绝政策
• 参考章节： references/403_troubleshooting.md 步骤 3-7

3. 隔离边缘情况的根本原因

• 输入： 高级信号（requesterPays、retentionPeriod、ADC）
• 输出： 根本原因诊断
• 参考章节： references/403_troubleshooting.md 步骤 8

4. 制定明确的修复方案

• 输入： 根本原因诊断
• 输出： 带标签的 gcloud 修复命令 + Y/N 提示
• 参考章节： Apply Attribution Tags 章节和步骤 8

错误处理矩阵

以下列表列出了常见的 Cloud Storage 403 情况以及你必须提供的明确应对方案。请严格按此执行。

Permission 'storage.buckets.getIamPolicy' denied

• **原因：**诊断调用方缺少 storage.buckets.getIamPolicy 权限 （例如缺少 roles/iam.securityReviewer），或请求被 边界安全控制（VPC-SC / IP Filtering）阻止。
• **解决方法：****不要循环或重试。**首先检查边界安全 控制（例如 VPC-SC 或 IP Filtering）是否阻止了访问；涉及边界时，不要 盲目建议授予角色。如果问题并非由边界导致，请说明执行检查的账号缺少存储桶 IAM 检查权限。建议授予符合最小权限原则的角色 roles/iam.securityReviewer，或包含 storage.buckets.getIamPolicy 的自定义角色（绝不要授予 roles/storage.bucketViewer 或 roles/storage.admin）。

Bucket is requester pays bucket but no user project provided

• **原因：**目标存储桶启用了 requesterPays: true
• **解决方法：****不要循环或重试。**即使拥有完整的 objectViewer 角色， 请求也必须传入结算项目。建议使用 --billing-project=PROJECT_ID 或 -u PROJECT_ID。

Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier

• **原因：**请求被 VPC Service Controls (VPC-SC) 服务 边界阻止
• **解决方法：**告知用户，添加 IAM 角色无法绕过 VPC-SC 边界。 请用户联系组织/项目管理员更新入口/出口规则。

Request is prohibited by organization's policy.（无 VPC-SC ID）

• **原因：**组织政策约束（例如 constraints/storage.publicAccessPrevention 或 constraints/gcp.resourceLocations），或被 VPC-SC 边界阻止但未记录 UUID
• **解决方法：**检查有效的组织政策约束（gcloud org-policies list --project=PROJECT_ID），或检查 Cloud Audit Logs 中的 边界拒绝记录，并请用户联系组织/项目 管理员。

Permission '...' denied ... due to an IAM deny policy（或尽管存在 roles/storage.admin 允许绑定仍返回 403）

• **原因：**组织、文件夹或项目 IAM 拒绝政策 (iam.googleapis.com/DenyPolicy) 明确拒绝了该权限
• **解决方法：**说明明确的 IAM 拒绝政策优先级绝对高于标准允许角色 （包括 roles/storage.admin），且无法绕过。建议检查拒绝政策（gcloud iam policies list --attachment-point=cloudresourcemanager.googleapis.com/projects/PROJECT_ID --kind=denypolicies，如有需要，再检查 --attachment-point=organizations/ORG_ID）， 并联系组织管理员。

在 IAM 角色正确的情况下，Compute Engine VM 上出现 403 Insufficient Permission

• **原因：**旧版 GCE VM 访问范围 (devstorage.read_only) 限制了 OAuth 令牌范围
• **解决方法：****不要对虚构的 VM 运行实时检查命令。**立即说明 GCE 访问范围会限制 OAuth 令牌，不受 IAM 角色影响。建议停止 VM（gcloud compute instances stop INSTANCE）， 将范围设为 cloud-platform（gcloud compute instances set-service-account INSTANCE --scopes=cloud-platform），然后重启 VM（gcloud compute instances start INSTANCE）。

尽管拥有 roles/storage.admin，删除对象时仍出现 403 Permission Denied

• **原因：**存储桶启用了保留政策 (retention_policy)
• **解决方法：**说明保留锁是无法绕过的数据保护措施，且在保留时间戳到期前 无法通过 IAM 覆盖。

使用完全相同的电子邮件地址重新创建服务账号时出现 403 Permission Denied

• **原因：**删除并重新创建账号会生成新的底层唯一 ID
• **解决方法：**指示用户移除旧的 IAM 政策绑定，并重新添加 完全相同的绑定，以便 IAM 注册新的唯一 ID。

403 Permission Denied：Bucket IP 过滤导致

• 原因： Bucket 配置了 ip_filter_config，且 mode: "Enabled"，因此调用方的 IP 地址被阻止，无法进行实时元数据检查。

• 修复： 通过 Cloud Audit Logs 路由诊断查询，以确认 IP 过滤违规：

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
      gcloud logging read "resource.type=gcs_bucket AND resource.labels.bucket_name=\"{bucket_name}\" AND protoPayload.authenticationInfo.principalEmail=\"{principal_email}\"" --project="{project_id}" --limit=5 --format=json
  

  如果 gcloud logging read 返回权限错误（403）、Project not found or deleted、空数组 []，或仅包含与故障操作无关的 Admin Activity 记录（cloudaudit.googleapis.com%2Factivity），且没有 Data Access 记录（cloudaudit.googleapis.com%2Fdata_access），则不要循环或重试。立即停止技术诊断，告知用户他们无法查看 Cloud Audit Logs（原因可能是权限不足、Data Access 日志记录已停用或日志排除规则），因此无法确定诊断高级网络拒绝问题；同时说明 Bucket 级 IP 过滤或 VPC Service Controls 可能阻止了访问，并建议他们联系 Project/Organization Administrator，检查 Cloud Audit Logs（包括 protoPayload.status.code=7 和 vpcServiceControlsUniqueIdentifier）或启用 Data Access Audit Logs。

  补救措施： 不要编写临时 CLI 命令。请参阅 references/403_troubleshooting.md 中的步骤 8，了解如何正确获取现有的 ip_filter_config，将调用方的 CIDR 追加到 ALLOWED_IPS.json 中的 allowedIpCidrRanges（不要覆盖已有范围），并通过 gcloud storage buckets update 命令应用配置。

在浏览器中访问 storage.cloud.google.com 时出现 403 Permission Denied（Cookieauth）

• 原因： 通过 storage.cloud.google.com 域名在浏览器中下载文件时，会使用 Google Account Cookie 身份验证，也称为 Cookieauth。如果项目启用了针对 storage.googleapis.com 的 Data Access Audit Logging（DATA_READ / DATA_WRITE），就会与 Cookieauth 冲突，导致浏览器持续返回 403 错误（或者多个已登录的 Google Account 发送了错误的身份 Cookie）。

• 修复： 检查 Bucket IAM 策略/配置，并使用以下命令检查项目的审核日志配置：

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
      gcloud projects get-iam-policy {project_id} --format="json(auditConfigs)"
  

  说明通过浏览器中的 storage.cloud.google.com 访问对象时，Data Access Logging 会与 Cookieauth 冲突。建议通过 gcloud、API 端点（storage.googleapis.com）或 Signed URL 访问对象，以绕过浏览器 Cookie 身份验证的限制（如果必须通过浏览器访问，也可以尝试使用无痕窗口，或调整 Data Access Audit Logging）。

404 Not Found 或 Bucket does not exist

• 原因： 目标 Bucket 不存在或已被删除
• 修复： 不要循环或重试。 停止尝试对不存在的 Bucket 执行实时命令。确认 Bucket 不存在，但仍应根据提供的场景上下文，说明假设性的诊断结果。