此页面由 Cloud Translation API 翻译。

存储和管理构建日志

运行构建时，Cloud Build 会收集并存储构建日志。本页面介绍了如何存储、查看和删除构建日志。

选择存储构建日志的位置

您可以配置 Cloud Build 以将构建日志存储在 Cloud Logging 或 Cloud Storage 中，方法是在 Cloud Build 配置文件中添加 logging 字段。如果您未在构建配置文件中指定 logging 字段，则 Cloud Build 会将构建日志同时存储在 Logging 和 Cloud Storage 中。

以下步骤仅将构建日志存储在 Logging 中：

在构建配置文件中，将 logging 的值设置为 CLOUD_LOGGING_ONLY：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.']
options:
  logging: CLOUD_LOGGING_ONLY

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "build",
      "-t",
      "us-east1-docker.pkg.dev/myproject/myimage",
      "."
    ]
  }
  ],
  "options": {
    "logging": "CLOUD_LOGGING_ONLY"
  }
}

使用构建配置文件来使用命令行，API 或触发器启动构建。

将 build 日志字段映射到日志条目字段

您可以配置构建日志的 JSON，以便在将构建日志发送到 Logging 时，指定的构建日志字段映射到 LogEntry 字段。例如，如果 build 日志包含 message，则消息会显示在生成的日志条目的 textPayload 或 jsonPayload.message 中。无法映射的 build 日志字段会显示在日志条目 jsonPayload 中。

如需在 build 日志中启用字段映射，请将 BuildOptions 字段 enableStructuredLogging 设置为 TRUE。

下表显示了与日志条目字段对应的 build 日志字段：

BuildLog 字段 (JSON) LogEntry 字段说明备注

BuildLog 字段 (JSON)	LogEntry 字段	说明	备注
`message`	`textPayload` 或 `jsonPayload.message`	允许用户设置日志消息	必须是字符串。如果 build 日志仅包含可映射的字段，则消息会显示在 `textPayload` 中。否则，该消息会显示在 `jsonPayload.message` 中。如果 build 日志包含多个步骤，则步骤标识符会显示在消息开头。
`severity`	`severity`	允许用户设置日志严重级别。	必须是 `LogSeverity` 的枚举。

message

textPayload 或 jsonPayload.message

允许用户设置日志消息

必须是字符串。

如果 build 日志仅包含可映射的字段，则消息会显示在 textPayload 中。否则，该消息会显示在 jsonPayload.message 中。

如果 build 日志包含多个步骤，则步骤标识符会显示在消息开头。

severity severity 允许用户设置日志严重级别。必须是 LogSeverity 的枚举。

以下 build 日志字段无法映射，如果它们出现在 build 日志中，将从日志条目中移除：

httpRequest
logging.googleapis.com/insertId
logging.googleapis.com/labels
logging.googleapis.com/operation
logging.googleapis.com/sourceLocation
logging.googleapis.com/spanId
logging.googleapis.com/trace
logging.googleapis.com/trace_sampled
time
timestamp
timestampSeconds
timestampNanos

所有其他 build 日志字段都将显示在日志条目的 jsonPayload 中。

将构建日志存储在 Google 创建的默认存储分区中

默认情况下，Cloud Build 会将构建日志存储在 Google 创建的 Cloud Storage 存储分区中。您可以查看存储在 Google 创建的 Cloud Storage 存储分区中的构建日志，但无法对其执行任何其他更改。如果您需要完全控制日志存储分区，请将日志存储在用户创建的 Cloud Storage 存储分区中。

将构建日志存储在用户创建的存储分区中

IAM 权限：

如需将构建日志存储在您自己的 Cloud Storage 存储分区中，您必须先向您用于构建的服务账号授予必要的 IAM 权限：

如果您的 Cloud Storage 存储分区与 Cloud Build 位于同一 Google Cloud 项目中，并且您使用的是 Cloud Build 旧版服务账号，则默认情况下，Cloud Build 旧版服务账号具有必要的 IAM 权限。您无需授予任何其他权限。
在任何其他情况下，请向您用于 build 的服务账号授予 Storage Admin 角色：
1. 打开 Cloud Storage 存储分区所在的项目中的 IAM 页面：
  
  打开 IAM 页面
2. 点击授予访问权限。
3. 输入服务账号的电子邮件地址。
4. 选择 Cloud Storage > Storage Admin。
5. 点击保存。

要指定 Cloud Storage 存储分区以存储构建日志，请执行以下操作：

在您的 Google Cloud 项目中，创建一个 Cloud Storage 存储分区，并未设置保留政策，以存储构建日志。

在构建配置文件中，添加一个 logsBucket 字段，其指向您为存储构建日志而创建的 Cloud Storage 存储分区。以下示例构建配置文件包含构建容器映像并将构建日志存储在名为 mylogsbucket 的存储分区中的说明：

YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ]
    logsBucket: 'gs://mylogsbucket'
    options:
      logging: GCS_ONLY

JSON

    {
      "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "us-east1-docker.pkg.dev/myproject/myimage",
           "."
         ]
       }
       ],
       "logsBucket": "gs://mylogsbucket",
       "options": {
         "logging": "GCS_ONLY"
       }
    }

使用构建配置文件来使用命令行，API 或触发器启动构建。

构建完成后，Cloud Build 会将日志存储在您在构建配置文件中指定的 Cloud Storage 存储分区中。

将构建日志存储在用户拥有且区域化的存储分区中

默认情况下，Cloud Build 会将构建日志存储在 Google 指定的区域，该区域可能与您运行构建的位置不同。借助 defaultLogsBucketBehavior 选项，您可以配置 Cloud Build 以使用您自己项目中与 build 位于同一区域的默认日志存储分区。通过此配置，您可以更好地控制日志数据的位置，这有助于您遵守数据驻留要求。

您需要为在自己的项目中存储日志支付费用。如需了解价格详情，请参阅 Cloud Storage 价格。

配置 Cloud Build 以使用用户拥有的区域性日志：

授予必要的 IAM 权限。
- 如果您使用的是 Cloud Build 旧版服务账号，则默认情况下，Cloud Build 旧版服务账号具有必要的 IAM 权限。您无需授予任何其他权限。
- 对于其他服务账号，请向您用于 build 的服务账号授予 Storage Admin 角色。如需了解如何向服务账号授予角色，请参阅授予项目的角色。

在构建配置中，添加 defaultLogsBucketBehavior 选项并将其值设置为 REGIONAL_USER_OWNED_BUCKET：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
    }
}

使用构建配置文件来使用命令行、API 或触发器启动构建。

运行构建时，Cloud Build 会在您执行构建的区域中创建新的日志存储分区，然后将构建日志存储在此存储分区中。默认情况下，同一项目和区域中的后续 build 将使用现有存储分区。

如果您设置 defaultLogsBucketBehavior 选项，然后在多个区域创建 build，Cloud Build 会为 build 日志创建多个存储分区。

存储在您自己的项目中的区域化 build 日志没有保留政策。此设置不可更改。

日志设置之间的优先级

如果您要向现有 build 配置文件添加 defaultLogsBucketBehavior 选项，并且之前已配置 logging 或 logsBucket 选项，我们建议您删除这些设置，以免设置之间发生冲突。

具体而言，如果您配置了以下内容，defaultLogsBucketBehavior 将无法正常运行：

logging: CLOUD_LOGGING_ONLY 以便在 Cloud Logging 中存储构建日志。
logging: NONE 关闭日志记录。

如果您在运行构建时未在构建配置中设置任何日志记录选项，Cloud Build 会设置 logging: LEGACY 并将日志存储在 Google 创建的默认 Cloud Storage 存储分区中。如果您添加 defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET，此选项会替换 logging: LEGACY。

查看构建日志

IAM 权限：

如果您的构建日志位于 Logging 中，请向要查看构建日志的主账号授予针对在其中配置构建的项目的 Logs Viewer 角色：
1. 打开 IAM 页面：
  
  打开 IAM 页面
2. 选择您的项目，然后点击打开。
3. 在权限表中，找到主账号的电子邮件 ID，然后点击铅笔图标。
4. 选择 Logging > Logs Viewer 角色。
5. 点击保存。
如果构建日志位于 Google 创建的默认 Cloud Storage 存储分区中，请将其中配置了构建的项目的 Project Viewer 角色授予想要查看构建日志的主账号：
1. 打开 IAM 页面：
  
  打开 IAM 页面
2. 选择您的项目，然后点击打开。
3. 在权限表中，找到主账号的电子邮件 ID，然后点击铅笔图标。
4. 选择 Project > Viewer 角色。
5. 点击保存。
注意： Project Owner 和 Project Editor 角色还允许主账号查看默认 Cloud Storage 存储分区中的构建日志。这是因为 Owner 角色包含 Editor 角色的权限，而 Editor 角色包含 Viewer 角色的权限。如需查看默认 Cloud Storage 存储分区中的构建日志，我们建议您授予 Project Viewer 角色，以遵循最小权限安全原则。
注意：为避免授予基本 Project Viewer 角色，请将构建日志存储在用户指定的存储分区中。我们推荐这种做法（尤其是如果您的构建是使用触发器调用的，并且您只想授予调用构建和查看构建进度的权限时）。

如果构建日志位于用户创建或用户拥有的 Cloud Storage 存储分区中，请将 Storage Object Viewer 角色授予要查看构建日志的主账号：
1. 打开 IAM 页面：
  
  打开 IAM 页面
2. 选择您的项目，然后点击打开。
3. 在权限表中，找到主账号的电子邮件 ID，然后点击铅笔图标。
4. 选择 Cloud Storage > Storage Object Viewer 角色。
5. 点击保存。

如需在 Cloud Build 中查看构建日志，请执行以下操作：

控制台

打开 Google Cloud 控制台中的 Cloud Build 页面。

打开 Cloud Build 页面
选择您的项目，然后点击打开。
在区域下拉菜单中，选择 build 的区域。
在构建记录页面中，点击特定 build。
在构建详情页面的步骤下，点击构建摘要以查看整个构建的构建日志，或点击某个构建步骤查看该步骤的构建日志。
如果您的日志存储在 Logging 中，请在构建日志面板中点击图标，以在 Logs Explorer 中查看日志。

gcloud

运行 gcloud builds log 命令，其中 build-id 是您要获取构建日志的构建的 ID。运行 gcloud builds submit 时将在构建提交过程结束时显示构建 ID，或者在运行 gcloud builds list 时将显示在 ID 列中。

gcloud builds log build-id

如需在 GitHub 和 GitHub Enterprise 中查看构建日志，请执行以下操作：

如果您创建了 GitHub 或 GitHub Enterprise 触发器，并将 --include-logs-with-status 指定为选项，则可以在 GitHub 和 GitHub Enterprise 中查看构建日志。

如需在 GitHub 和 GitHub Enterprise 中查看构建日志，请执行以下操作：

前往与触发器关联的代码库。
前往提交内容列表。
找到您要查看其构建日志的提交所在的行。
点击提交内容所在行的结果图标。

您会看到与您的提交关联的检查列表。
点击要查看 build 日志的行的详情。

您会看到与提交关联的摘要页面。如果您使用 --include-logs-with-status 标志创建了触发器，则会在该页面的详情部分下看到构建日志。

删除 build 日志

您不能删除位于 Google 创建的日志存储分区中的构建日志。

如需删除位于用户创建的日志存储分区中的构建日志，请执行以下操作：

将 Storage Object Admin 角色授予要删除日志的用户或服务账号。
按照删除对象中关于删除 Cloud Storage 对象的说明，来删除构建日志。

如需删除用户创建的日志存储分区，请执行以下操作：

将 Storage Admin 角色授予要删除日志存储分区的用户或服务账号。
按照删除存储分区中关于删除存储分区的说明，来删除日志存储分区。

存储和管理构建日志

选择存储构建日志的位置

YAML

JSON

将 build 日志字段映射到日志条目字段

将构建日志存储在 Google 创建的默认存储分区中

将构建日志存储在用户创建的存储分区中

YAML

JSON

将构建日志存储在用户拥有且区域化的存储分区中

YAML

JSON

日志设置之间的优先级

查看构建日志

控制台

gcloud

删除 build 日志

后续步骤