问题排查

本页面介绍了您在使用 Cloud Storage 时可能会遇到的一些常见错误的问题排查方法。

如需了解影响 Google Cloud 服务（例如 Cloud Storage）的突发事件，请参阅 Google Cloud Service Health 信息中心。

记录原始请求

使用 gcloud 或 Cloud Storage 客户端库等工具时，大部分请求和响应信息由这些工具处理。不过，有时查看详情有助于排查问题，或者将问题发布到 Stack Overflow 等论坛也很有用。按照以下说明为您的工具返回请求和响应标头：

gcloud storage ls gs://my-bucket/my-object --log-http --verbosity=debug

import logging
import http.client

logging.basicConfig(level=logging.DEBUG)
http.client.HTTPConnection.debuglevel=5

ruby
Google::Apis.logger.level = Logger::DEBUG

添加自定义标头

向请求添加自定义标头是一种用于调试的常见工具，例如用于启用调试标头或跟踪请求。以下示例展示了如何为不同的 Cloud Storage 工具设置请求标头：

gcloud storage objects describe gs://my-bucket/my-object --additional-headers=HEADER_NAME=HEADER_VALUE

namespace gcs = google::cloud::storage;
gcs::Client client = ...;
client.AnyFunction(... args ..., gcs::CustomHeader("header-name", "value"));

using Google.Cloud.Storage.V1;

var client = StorageClient.Create();
client.Service.HttpClient.DefaultRequestHeaders.Add("custom-header", "custom-value");

var buckets = client.ListBuckets("my-project-id");
foreach (var bucket in buckets)

{
  Console.WriteLine(bucket.Name);
}

package main

import (
  "context"
  "io/ioutil"
  "log"
  "net/http"

  "cloud.google.com/go/storage"
  "google.golang.org/api/option"
  raw "google.golang.org/api/storage/v1"
  htransport "google.golang.org/api/transport/http"
)

func main() {

  ctx := context.Background()

  // Standard way to initialize client:
  // client, err := storage.NewClient(ctx)
  // if err != nil {
  //      // handle error
  // }

  // Instead, create a custom http.Client.
  base := http.DefaultTransport
  trans, err := htransport.NewTransport(ctx, base, option.WithScopes(raw.DevstorageFullControlScope),
            option.WithUserAgent("custom-user-agent"))
  if err != nil {
            // Handle error.
  }
  c := http.Client{Transport:trans}

  // Add RoundTripper to the created HTTP client.
  c.Transport = withDebugHeader{c.Transport}

  // Supply this client to storage.NewClient
  client, err := storage.NewClient(ctx, option.WithHTTPClient(&c))
  if err != nil {
              // Handle error.
  }

  // Use client to make a request
 }

type withDebugHeader struct {
  rt http.RoundTripper
}

func (wdh withDebugHeader) RoundTrip(r *http.Request) (*http.Response, error) {
  headerName := "X-Custom-Header"
  r.Header.Add(headerName, "value")
  resp, err := wdh.rt.RoundTrip(r)
  if err == nil {
    log.Printf("Resp Header: %+v, ", resp.Header.Get(headerName))
  } else {
    log.Printf("Error: %+v", err)
  }
  return resp, err
}

import com.google.api.gax.rpc.FixedHeaderProvider;
import com.google.api.gax.rpc.HeaderProvider;
import com.google.cloud.WriteChannel;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

import java.io.IOException;
import java.nio.ByteBuffer;
import static java.nio.charset.StandardCharsets.UTF_8;

public class Example {

  public void main(String args[]) throws IOException {
    HeaderProvider headerProvider =
            FixedHeaderProvider.create("custom-header", "custom-value");
    Storage storage = StorageOptions.getDefaultInstance()
            .toBuilder()
            .setHeaderProvider(headerProvider)
            .build().getService();
    String bucketName = "example-bucket";
    String blobName = "test-custom-header";

    // Use client with custom header
    BlobInfo blob = BlobInfo.newBuilder(bucketName, blobName).build();
    byte[] stringBytes;
    try (WriteChannel writer = storage.writer(blob)) {
      stringBytes = "hello world".getBytes(UTF_8);
      writer.write(ByteBuffer.wrap(stringBytes));
    }
  }
}

const storage = new Storage();

storage.interceptors.push({
  request: requestConfig => {
    Object.assign(requestConfig.headers, {
      'X-Custom-Header': 'value',
      });
    return requestConfig;
  },
});

use Google\Cloud\Storage\StorageClient;

$client = new StorageClient([
   'restOptions' => [
       'headers' => [
           'x-foo' => 'bat'
       ]
   ]
]);

$bucket = $client->bucket('my-bucket');

$bucket->info([
   'restOptions' => [
       'headers' => [
           'x-foo' => 'bar'
       ]
   ]
]);

from google.cloud import storage

client = storage.Client(
    extra_headers={
        "x-custom-header": "value"
    }
)

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

storage.add_custom_headers { 'X-Custom-Header'=> 'value' }

使用 CORS 配置访问存储桶

如果您已在存储桶上设置了 CORS 配置，并发现来自客户端浏览器的传入请求失败，请尝试以下问题排查步骤：

1. 查看目标存储桶上的 CORS 配置。如果存在多个 CORS 配置条目，请确保用于问题排查的请求值会映射到单个 CORS 配置条目中的值。

2. 在测试发出 CORS 请求时，请确保您没有向 storage.cloud.google.com 端点发出请求，该端点不允许 CORS 请求。如需详细了解 CORS 支持的端点，请参阅 Cloud Storage CORS 支持。

3. 使用您自己选择的工具查看请求和响应。在 Chrome 浏览器中，您可以使用标准开发者工具来查看此信息：

   1. 点击浏览器工具栏上的 Chrome 菜单 (more_vert)。
   2. 选择更多工具 > 开发者工具。
   3. 点击网络标签页。
   4. 通过您的应用或命令行发送请求。
   5. 在显示网络活动的窗格中，找到相应请求。
   6. 在名称列中，点击与相应请求对应的名称。
   7. 点击标头标签以查看响应标头，或点击响应标签以查看响应内容。

   如果您没有看到请求和响应，可能是由于您的浏览器缓存了先前尝试失败的预检请求。清除浏览器的缓存应该也会清除预检缓存。如果预检缓存未被清除，请将您的 CORS 配置中的 MaxAgeSec 值设置为低于默认值 1800（30 分钟），按照旧 MaxAgeSec 值所指定的时长耐心等待，然后重新尝试该请求。此时将执行新的预检请求，以提取新的 CORS 配置并完全清除缓存条目。调试完您的问题后，请将 MaxAgeSec 重新提升至较高值，以减少发往您的存储桶的预检流量。

4. 确保请求包含 Origin 标头，且该标头的值至少与存储桶 CORS 配置中的一个 Origins 值相匹配。请注意，这些值的架构、主机和端口必须完全匹配。下面提供了一些可以接受的匹配项示例：

   • http://origin.example.com 匹配 http://origin.example.com:80（因为 80 是默认的 HTTP 端口），但不匹配 https://origin.example.com、http://origin.example.com:8080、http://origin.example.com:5151 或 http://sub.origin.example.com。

   • https://example.com:443 匹配 https://example.com，但不匹配 http://example.com 或 http://example.com:443。

   • http://localhost:8080 仅与 http://localhost:8080 完全匹配，但与 http://localhost:5555 或 http://localhost.example.com:8080 不匹配。

5. 对于简单请求，请确保请求的 HTTP 方法与存储桶 CORS 配置中的至少一个 Methods 值相匹配。对于预检请求，请确保 Access-Control-Request-Method 中指定的方法至少与其中一个 Methods 值匹配。

6. 对于预检请求，请检查它是否包含一个或多个 Access-Control-Request-Header 标头。如果是这样，请确保每个 Access-Control-Request-Header 值与存储桶 CORS 配置中的一个 ResponseHeader 值匹配。Access-Control-Request-Header 中指定的所有标头必须包含在 CORS 配置中，才能使预检请求成功并使 CORS 标头包含在响应中。

错误代码

下面是您可能会遇到的常见 HTTP 状态代码。

301：永久移动

问题：我设置了一个静态网站，访问目录路径时返回一个空对象和 301 HTTP 响应代码。

解决方案：如果在访问目录（例如 http://www.example.com/dir/）时，您的浏览器下载了一个零字节对象，并且收到 301 响应代码，则您的存储桶很可能包含具有该名称的空对象。如需检查是否存在此问题并解决问题，请执行以下操作：

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 点击 Google Cloud 控制台顶部的激活 Cloud Shell 按钮。
3. 运行 gcloud storage ls --recursive gs://www.example.com/dir/。如果输出内容包含 http://www.example.com/dir/，则表明该位置存在一个空对象。
4. 使用以下命令移除空对象：gcloud storage rm gs://www.example.com/dir/

您现在可以访问 http://www.example.com/dir/ 并让它返回该目录的 index.html 文件（而不是空对象）。

400：错误请求

问题：在执行可续传上传时，我收到了此错误和消息 Failed to parse Content-Range header.

解决方案：您在 Content-Range 标头中使用的值无效。例如，Content-Range: */* 无效，您应将其指定为 Content-Range: bytes */*。如果您收到此错误，表示当前的可续传上传不再有效，您必须启动新的可续传上传。

401：未经授权

问题：直接或使用 Cloud CDN 对公共存储桶发出的请求会失败，并返回 HTTP 401: Unauthorized 和 Authentication Required 响应。

解决方案：检查您的客户端或任何中间代理是否没有将 Authorization 标头添加到对 Cloud Storage 发出的请求中。任何包含 Authorization 标头（即使该标头为空）的请求都将作为一项身份验证尝试进行验证。

403：账号已停用

问题：我尝试创建存储桶，但收到 403 Account Disabled 错误。

解决方案：此错误表示您没有为关联项目启用结算功能。如需了解启用结算功能的步骤，请参阅为项目启用结算功能。

如果已启用结算功能，但是您仍然收到此错误消息，您可以与支持部门联系并提供您的项目 ID 和问题描述。

403：已禁止

问题：我应该有权限访问特定的存储桶或对象，但如果您尝试执行此操作，我会收到 403 - Forbidden 错误，并显示类似于以下内容的消息：example@email.com does not have storage.objects.get access to the Google Cloud Storage object。

解决方案：您缺少完成请求所需的存储桶或对象的 IAM 权限。如果您预期能够发出请求但无法做到，请执行以下检查：

1. 错误消息中提及的授权对象是否是您预期收到的错误消息？如果错误消息中提及了意外的电子邮件地址或“匿名调用者”，则表示您的请求未使用预期的凭据。这可能是因为您用于发出请求的工具是使用其他别名或实体的凭据设置的，或者这可能是因为该请求是服务账号代表您发出的。

2. 错误消息中提及的权限是否是您需要的权限？如果不是预期的权限，可能是因为您正在使用的工具需要额外的访问权限才能完成您的请求。例如，为了批量删除存储桶中的对象，gcloud 必须先构建存储桶中要删除的对象的列表。批量删除操作的这一部分需要 storage.objects.list 权限，鉴于目标是删除对象，这通常只需要 storage.objects.delete 权限，因此您可能会感到意外。如果这是出现错误消息的原因，请确保您具有拥有其他必要权限的 IAM 角色。

3. 您是否被授予预期资源或父资源的 IAM 角色？例如，如果您被授予项目的 Storage Object Viewer 角色，并且您尝试下载对象，请确保该对象位于项目中的存储桶中：您可能会无意中拥有其他项目的 Storage Object Viewer 权限。

4. 您是否通过便利值授予了访问特定存储桶或对象的权限？移除授予便捷值的访问权限可能会导致之前启用的主账号失去对资源的访问权限。

   例如，假设 jane@example.com 拥有名为 my-example-project 的项目的 Owner (roles/owner) 基本角色，并且该项目的 IAM 政策将 Storage Object Creator (roles/storage.objectCreator 角色授予便利值 projectOwner:my-example-project。这意味着 jane@example.com 具有与 my-example-project 中存储桶的 Storage Object Creator 角色相关联的权限。如果此授权被移除，jane@example.com 会失去与 Storage Object Creator 角色关联的权限。

   在这种情况下，您可以通过授予自己执行相关操作所需的存储桶级层或对象级层权限来重新获得对存储桶或对象的访问权限。

5. 是否有 IAM 拒绝政策阻止您使用某些权限？您可以联系您的组织管理员，了解是否已实施 IAM 拒绝政策。

409：冲突

问题：我尝试创建存储桶，但收到以下错误：

409 Conflict. Sorry, that name is not available. Please try a different one.

解决方案：您尝试使用的存储桶名称（例如 gs://cats 或 gs://dogs）已被占用。Cloud Storage 使用全局命名空间，因此您不能将存储桶命名为与现有存储桶相同的名称。请选择未使用的名称。

412：违反了自定义限制条件

问题：我的请求被拒绝，并显示 412 orgpolicy 错误。

问题：我的请求被拒绝，并显示 412 Multiple constraints were violated 错误。

解决方案：联系您的安全管理员团队，查看请求发送到的存储桶是否受到使用自定义限制条件的组织政策的影响。您的存储桶也可能受到相互冲突的不同组织政策的影响。例如，一项政策指定存储桶必须具有 Standard Storage 类别，另一项政策指定存储桶必须具有 Coldline Storage 类别。

429：请求数过多

问题：我的请求被拒绝，并显示 429 Too Many Requests 错误。

解决方案：您即将达到 Cloud Storage 允许的给定资源的请求数限制。如需了解 Cloud Storage 中的限制，请参阅 Cloud Storage 配额。

• 如果工作负载每秒对存储桶发出 1,000 个请求，请参阅请求速率和访问分配准则以了解最佳实践，包括逐步增加工作负载并避免使用顺序文件名。

• 如果工作负载可能使用流向特定位置的 50 Gbps 或更多网络出站流量，请检查您的带宽使用量，以确保不会达到带宽配额。

诊断 Google Cloud 控制台错误

问题：使用 Google Cloud 控制台执行操作时，我收到了一条一般性错误消息。例如，我在尝试删除存储桶时看到错误消息，但看不到操作失败的原因。

解决方案：使用 Google Cloud 控制台的通知查看有关失败操作的详细信息：

1. 点击 Google Cloud 控制台顶部的通知按钮 (notifications)。

   下拉列表会显示 Google Cloud 控制台最近执行的操作。

2. 点击您要详细了解的操作项。

   此时将打开一个页面，其中显示了有关该操作的详细信息。

3. 点击各行即可展开详细的错误信息。

问题：使用 Google Cloud 控制台时，我没有看到特定列。

解决方案：如需看到 Google Cloud 控制台中显示特定列，请点击列显示选项图标 (view_column)，然后选择您想要显示的列。

模拟的文件夹和托管式文件夹

问题：我删除了存储桶中的某些对象，现在包含这些对象的文件夹不显示在 Google Cloud 控制台中。

解决方案：虽然 Google Cloud 控制台会显示存储桶的内容，就好像存在目录结构一样，但 Cloud Storage 中从根本上来说不存在文件夹。因此，当您从存储桶中移除具有共用前缀的所有对象时，Google Cloud 控制台中将不再显示代表该组对象的文件夹图标。

问题：我无法创建托管文件夹。

解决方案：如需创建托管文件夹，请确保满足以下要求：

• 您具有包含 storage.managedfolders.create 权限的 IAM 角色，例如 Storage Object Admin (roles/storage.objectAdmin) 角色。如需了解如何授予角色，请参阅使用 IAM 权限。

• 在要创建托管文件夹的存储桶上启用了统一存储桶级访问权限。

• 存储桶或项目上没有任何 IAM Conditions 条件使用存储桶资源类型 (storage.googleapis.com/Bucket) 或对象资源类型 (storage.googleapis.com/Object)。如果项目内的任何存储桶的 IAM Conditions 条件使用上述任一资源类型，则无法在该项目的任何存储桶中创建托管文件夹，即使稍后移除条件也是如此。

问题：我无法停用统一存储桶级访问权限，因为我的存储桶中有托管文件夹。

解决方案：如果存储桶中有托管文件夹，则无法停用统一存储桶级访问权限。如需停用统一存储桶级访问权限，您需要先删除存储桶中的所有托管文件夹。

静态网站错误

设置存储桶来托管静态网站时可能遇到的常见问题如下。

HTTPS 传送

问题：我想在不使用负载均衡器的情况下通过 HTTPS 传送我的内容。

解决方案：您可以使用 https://storage.googleapis.com/my-bucket/my-object 等直接 URI 通过 HTTPS 传送静态内容。对于通过 SSL 使用自定义网域传送内容的其他选项，您可以：

• 结合使用第三方内容分发网络和 Cloud Storage。
• 从 Firebase Hosting 而非 Cloud Storage 传送静态网站内容。

网域验证

问题：我无法验证我的域名。

解决方案：通常，Search Console 中的验证过程会指示您将文件上传到您的网域，但是，如果没有相关的存储桶（您只能在执行域名验证后创建），您可能无法执行此操作。

在这种情况下，请使用域名提供程序验证方法来验证所有权。有关相关操作步骤，请参阅所有权验证。您可以在创建存储桶之前完成此验证。

页面无法访问

问题：我的网站提供的网页向我发出 Access denied 错误消息。

解决方案：检查对象是否已被公开共享。如果没有，请参阅公开数据以了解如何执行此操作。

如果您之前上传并共享了一个对象，但随后上传了该对象的新版本，则您必须以公开方式重新共享该对象。这是因为，上传新的版本后，公开权限会被替换。

权限更新失败

问题：我在尝试公开我的数据时收到错误消息。

解决方案：确保您拥有 storage.buckets.setIamPolicy 权限或 storage.objects.setIamPolicy 权限。例如，您可以在 Storage Admin (roles/storage.admin) 角色中授予这些权限。如果您拥有 storage.buckets.setIamPolicy 权限或 storage.objects.setIamPolicy 权限，但仍然收到错误消息，则您的存储桶可能受到禁止公开访问制约，这可能不允许访问 allUsers 或 allAuthenticatedUsers。您可以直接对存储桶设置禁止公开访问，也可以通过在更高级层设置的组织政策来强制实施这种禁止。

内容下载

问题：系统提示我下载我的页面内容，而不能在浏览器中查看。

解决方案：如果您将 MainPageSuffix 指定为对象并且该对象的类型不是 Web 内容，系统会提示网站访问者下载内容，而不是提供网页内容。如需解决此问题，请将 Content-Type 元数据条目更新为合适的值，例如 text/html。如需了解相关说明，请参阅修改对象元数据。

延迟时间

下面是您可能会遇到的常见延迟问题。此外，Google Cloud Service Health 信息中心会提供有关影响 Google Cloud 服务（例如 Cloud Storage）的突发事件的相关信息。

上传或下载延迟时间

问题：我看到上传或下载的延迟时间有所增加。

解决方案：请考虑以下常见的上传和下载延迟时间原因：

• CPU 或内存限制：受影响的环境的操作系统应使用工具来衡量本地资源消耗量，例如 CPU 用量和内存用量。

• 磁盘 IO 限制：性能影响可能是由本地磁盘 IO 引起的。

• 地理位置距离：性能可能受到 Cloud Storage 存储桶物理分离和不利环境的影响，尤其是在跨大洲的情况下。使用与不利环境位于同一区域的存储桶进行测试，可以确定地理位置分离对延迟时间的影响程度。

  • 如果适用，受影响环境的 DNS 解析器应使用 EDNS(0) 协议，以便来自该环境的请求通过适当的 Google Front End 前端路由。

CLI 或客户端库延迟时间

问题：我在使用 Google Cloud CLI 或某个客户端库访问 Cloud Storage 时看到延迟时间增加。

解决方案：gcloud CLI 和客户端库会在有需要时自动重试请求，并且这种行为可能显著增加最终用户看到的延迟时间。使用 Cloud Monitoring 指标 storage.googleapis.com/api/request_count 查看 Cloud Storage 是否一致地提供可重试的响应代码，例如 429 或 5xx。

代理服务器

问题：我要通过代理服务器进行连接，我需要做些什么？

解决方案：如需通过代理服务器访问 Cloud Storage，您必须有权访问以下网域：

• accounts.google.com，用于创建 OAuth2 身份验证令牌
• oauth2.googleapis.com，用于执行 OAuth2 令牌交换
• *.googleapis.com，用于执行存储请求

如果您的代理服务器或安全政策不支持按网域列入许可名单，而是仅支持按 IP 网络块列入许可名单，我们强烈建议您为所有 Google IP 地址范围配置代理服务器。您可以通过在 ARIN 上查询 WHOIS 数据来查找地址范围。最佳做法是定期查看代理设置，以确保它与 Google 的 IP 地址相匹配。

我们不建议您使用单次查询 oauth2.googleapis.com 和 storage.googleapis.com 所获得的单个 IP 地址来配置代理。由于 Google 服务通过 DNS 名称进行呈现，而这些名称映射到了可能随时间变化的大量 IP 地址，因此，如果基于单次查询来配置代理，可能会导致您无法连接到 Cloud Storage。

如果您的请求通过代理服务器进行路由，您可能需要与网络管理员联系，以确保代理不会删除包含您的凭据的 Authorization 标头。如果没有 Authorization 标头，您的请求将被拒绝，并且您会收到 MissingSecurityHeader 错误。

存储空间分析错误

问题：我的资产清单报告配置每天生成多个资产清单报告。

解决方案：如果您的存储桶中的对象超过 100 万个，则可以生成多个资产清单报告作为分片。资产清单报告配置为存储桶中的每 100 万个对象生成一个资产清单报告。例如，如果您的存储桶包含 350 万个对象，该存储桶上的资产清单报告配置将根据您指定的频率生成 4 个资产清单报告分片以及一个清单文件，该文件中包含生成的资产清单报告分片数量及其文件名。

问题：资产清单报告未显示在目标存储桶中。

解决方案：如果您已创建资产清单报告配置，但在目标存储桶中未看到生成的资产清单报告，请检查以下内容：

• 确保资产清单报告配置中指定的开始日期与资产清单报告的预期生成日期一致。如需了解如何指定开始日期，请参阅创建资产清单报告配置。

• 查看资产清单报告历史记录，以检查是否存在失败及其根本原因。如需查看资产清单报告历史记录，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
     

     进入“存储桶”

  2. 在存储桶列表中，点击包含资产清单报告配置的源存储桶的名称。

  3. 在存储桶详细信息页面上，点击库存报告标签页。

  4. 在资产清单报告配置列表中，点击生成您要检查的报告的资产清单报告配置的 UUID。

  5. 在资产清单报告历史记录部分中检查失败情况。将指针悬停在帮助 (help) 上，即可详细了解失败的原因。

• 确保向项目级层服务代理授予读取和写入资产清单报告所需的 IAM 角色。如需查看相关说明，请参阅向服务代理授予所需的角色。

问题：生成资产清单报告时出现随机延迟。

解决方案：生成资产清单报告之间的时间间隔可能会有所不同。您可能会看到延迟长达一天的时间。

后续步骤

• 在 Cloud Storage 常见问题解答中查找其他问题的解答。
• 了解支持选项。
• 探索 Error Reporting 如何帮助您识别和了解 Cloud Storage 错误。