安装 gsutil

本页面介绍了 gsutil 的安装和设置，该工具可让您从命令行使用 HTTPS 访问 Cloud Storage。

重要提示：在大多数情况下，想要通过 CLI 来使用 Cloud Storage 的用户不应使用 gsutil 工具，而应该使用 Google Cloud CLI 并使用 gcloud storage 命令。

只需安装 gsutil，您即可获得公共数据的读取和/或写入权限。向 Cloud Storage 服务进行身份验证，您可以获得与您共享的受保护数据的读取和/或写入权限。通过启用结算功能，您可以创建和管理自己的存储桶。

系统要求

• gsutil 工具在 Linux/Unix、Mac OS、Windows（XP 或更高版本）上运行。

• gsutil 5.0 版及更高版本需要使用 Python 3.5-3.11，您可以通过使用 Python 版本管理器或安装相应版本来获取。以下说明介绍了如何管理 Python 版本：

Linux

前提条件：安装 Python 版本管理器 (pyenv) 并安装合适的 Python 版本（推荐 3.11）。

1. 设置全局 Python 版本：
   • 如需将 Python 3.11.9 设置为全局版本，请运行以下命令：

     pyenv global 3.11.9

   • 或者，在本地为特定项目文件夹设置 Python 版本：

     pyenv local 3.11.9

2. 确认使用的是正确的 Python 版本：

   python --version

   您应该会看到：

   Python 3.11.9

macOS

方法 1：使用 Homebrew (brew)

前提条件：安装 Homebrew，并通过 Homebrew 安装合适的 Python 版本（建议使用 3.11）。

1. 将特定的 Python 版本设置为默认版本：
   • 将所需版本添加到 $PATH 中。例如，如需使用 Python 3.11，请运行以下命令：

     export PATH="/usr/local/opt/python@3.11/bin:$PATH"

   • 如需使此更改永久生效，请添加 shell 配置文件的路径（~/.bash_profile、~/.zshrc 或 ~/.bashrc）。
2. 确认使用的是正确的 Python 版本：

   python --version

   您应该会看到：

   Python 3.11.9

方法 2：使用 pyenv

前提条件：安装 Python 版本管理器 (pyenv) 并通过 pyenv 安装合适的 Python 版本（推荐 3.11）。

1. 设置全局 Python 版本：
   • 如需全局设置 Python 版本（适用于所有终端），请运行以下命令：

     pyenv global 3.11.9

   • 或者，在本地为特定项目文件夹设置 Python 版本：

     pyenv local 3.11.9

2. 确认使用的是正确的 Python 版本：

   python --version

   您应该会看到：

   Python 3.11.9

Windows

前提条件：安装 Python 版本管理器 (pyenv-win) 并通过 pyenv 安装合适的 Python 版本（推荐 3.11）。

1. 设置全局 Python 版本：
   • 如需将 Python 3.11.9 设置为全局版本，请运行以下命令：

     pyenv global 3.11.9

   • 或者，在本地为特定项目文件夹设置 Python 版本：

     pyenv local 3.11.9

2. 确认使用的是正确的 Python 版本：

   python --version

   您应该会看到：

   Python 3.11.9

• 如果您计划使用复合对象，则需要安装已编译的 crcmod。在 Windows 系统中，已编译的 crcmod 仅适用于 32 位 Python。如需详细了解 crcmod，请安装 gsutil 并使用 gsutil help crc32c 命令查看帮助主题。

警告：某些 Linux 发行版中预安装了另一个名为 gsutil 的工具（由 GrandStream BudgeTone 提供）。如果您运行此命令（而不是 Cloud Storage gsutil），它可能会输出类似于 "Choose one of -b, -d, -e, or -r to do something" 的错误消息。如果发生这种情况，您可以在 PATH 环境变量中将 Cloud Storage 版 gsutil 移到前面，或者，您也可以在运行 Cloud Storage gsutil 时指定完整路径（例如 /home/users/joan/gsutil/gsutil ls）。

安装 gsutil

注意：如果您之前安装了 Google Cloud CLI，则 gsutil 已包含在内。此外，Google Cloud CLI（包括 gsutil）默认安装在多个 Google Compute Engine 映像上；如需查看完整列表，请参阅操作系统详细信息。

官方支持的 gsutil 安装和更新方法已包含在 Google Cloud CLI 中。

将 gsutil 作为 Google Cloud CLI 的一部分进行安装

按照您的操作系统对应的说明操作，将 gsutil 作为 Google Cloud CLI 的一部分进行安装：

Linux

1. 确认您拥有受支持的 Python 版本。Google Cloud CLI 需要 Python 3.8 到 3.12。请注意，x86_64 Linux 软件包中包含默认首选的捆绑式 Python 解释器。如需了解如何选择和配置 Python 解释器，请参阅 gcloud topic startup。
2. 下载以下内容之一：
   注意：如需确定您的 Linux 平台，请在命令行中运行 uname -a。

   平台	软件包名称	大小	SHA256 校验和
   Linux 64 位 (x86_64)	google-cloud-cli-linux-x86_64.tar.gz	131.3 MB	4fb56340c88901489d52f0d4895dce25c5ed39b7e63743bc8c4cf1af6c4da367
   Linux 64 位 (Arm)	google-cloud-cli-linux-arm.tar.gz	53.5 MB	d669f9974c82182afbf769ef07ce3feca933c3145999457c717adfff275e5bcc
   Linux 32 位 (x86)	google-cloud-cli-linux-x86.tar.gz	53.5 MB	9832e1a3891bed93d9ea6f1dae4ca5ee592ac2305decd47de649f3338ab86640

   如需下载 Linux 归档文件，请运行以下命令：

   curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

   请参阅上表并将 google-cloud-cli-linux-x86_64.tar.gz 替换为适用于您的配置的 *.tar.gz 软件包名称。

3. 如需将文件内容解压缩到文件系统（最好是解压缩到您的主目录），请运行以下命令：

   tar -xf google-cloud-cli-linux-x86_64.tar.gz

   可选：如需替换现有安装，请移除现有的 google-cloud-sdk 目录，然后将归档解压缩到同一位置。
4. 将 gcloud CLI 添加到路径中。使用以下命令从解压缩到的文件夹的根目录运行安装脚本：

   ./google-cloud-sdk/install.sh

   也可以通过提供偏好设置作为标志以非交互方式（例如使用脚本）完成此操作。如需查看可用标志，请运行以下命令：

   ./google-cloud-sdk/install.sh --help

   可选：
   • 如需发送匿名使用情况统计信息以帮助改进 gcloud CLI，请在出现提示时回答 Y。
   • 如需将 gcloud CLI 添加到您的 PATH 并启用命令补全功能，请在出现提示时回答 Y。
5. 打开新终端，以使更改生效。
6. 如需初始化 gcloud CLI，请运行 gcloud init：

./google-cloud-sdk/bin/gcloud init

7. 可选：使用组件管理器安装其他组件。

Debian/Ubuntu

注意：根据您的设置，您可以选择其他安装方法：

• 如果您希望 gcloud 自动更新到最新版本，并且您运行的是使用快照软件包管理器的较新 Ubuntu 版本，则可以将 Google Cloud CLI 作为快照软件包进行安装。
• 如果您使用的是 Compute Engine 上的实例，则 gcloud CLI 会默认安装在多个操作系统映像上。如需查看完整列表，请参阅操作系统详细信息。

软件包内容

对于 Debian 和 Ubuntu 系统，可以通过软件包格式的 gcloud CLI 进行安装。此软件包仅包含 gcloud、gcloud alpha、gcloud beta、gsutil、和 bq 命令，而不包括 kubectl 或使用 gcloud 命令部署应用所需的 App Engine 扩展程序。如果您需要这些组件，则必须单独安装。

准备工作

在安装 gcloud CLI 之前，请确保您的操作系统满足以下要求：

• 这是尚未达到服务终止期限的 Ubuntu 版本或尚未达到服务终止期限的 Debian 稳定版本
• 它最近更新了其软件包：

  sudo apt-get update

• 它安装了 apt-transport-https 和 curl：

  sudo apt-get install apt-transport-https ca-certificates gnupg curl

安装

1. 导入 Google Cloud 公钥。

   • 对于较新的发行版（Debian 9+ 或 Ubuntu 18.04+），请运行以下命令：

     curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg

   • 对于较旧的发行版，请运行以下命令：

     curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

   • 如果您的发行版的 apt-key 命令不支持 --keyring 参数，请运行以下命令：

     curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

   • 如果您由于密钥过期而无法获取最新更新，请获取最新的 apt-get.gpg 密钥文件。

2. 添加 gcloud CLI 发行版 URI 作为软件包源。
   • 对于较新的发行版（Debian 9+ 或 Ubuntu 18.04+），请运行以下命令：

     echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

   • 对于不支持 signed-by 选项的旧发行版，请运行以下命令：

     echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

   注意：请确保您在 /etc/apt/sources.list.d/google-cloud-sdk.list 中没有重复的 cloud-sdk 代码库条目。
3. 更新并安装 gcloud CLI：

   sudo apt-get update && sudo apt-get install google-cloud-cli

   如需了解其他 apt-get 选项（例如停用提示或试运行），请参阅 apt-get 手册页面。

   Docker 提示：如果安装 Docker 映像中的 gcloud CLI，请改用单个 RUN 步骤：

   RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && apt-get update -y && apt-get install google-cloud-cli -y
       

   对于不支持 gpg --dearmor 命令的旧基础映像：

   RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && apt-get install google-cloud-cli -y
         

4. （可选）安装以下任何其他组件：
   • google-cloud-cli
   • google-cloud-cli-anthos-auth
   • google-cloud-cli-app-engine-go
   • google-cloud-cli-app-engine-grpc
   • google-cloud-cli-app-engine-java
   • google-cloud-cli-app-engine-python
   • google-cloud-cli-app-engine-python-extras
   • google-cloud-cli-bigtable-emulator
   • google-cloud-cli-cbt
   • google-cloud-cli-cloud-build-local
   • google-cloud-cli-cloud-run-proxy
   • google-cloud-cli-config-connector
   • google-cloud-cli-datastore-emulator
   • google-cloud-cli-firestore-emulator
   • google-cloud-cli-gke-gcloud-auth-plugin
   • google-cloud-cli-kpt
   • google-cloud-cli-kubectl-oidc
   • google-cloud-cli-local-extract
   • google-cloud-cli-minikube
   • google-cloud-cli-nomos
   • google-cloud-cli-pubsub-emulator
   • google-cloud-cli-skaffold
   • google-cloud-cli-spanner-emulator
   • google-cloud-cli-terraform-validator
   • google-cloud-cli-tests
   • kubectl

   例如，google-cloud-cli-app-engine-java 组件可以按以下方式安装：

   sudo apt-get install google-cloud-cli-app-engine-java

5. 运行 gcloud init 以开始执行初始化操作：

   gcloud init

降级 gcloud CLI 版本

如需还原到特定版本的 gcloud CLI（其中 VERSION 为 123.0.0 形式），请运行以下命令：

sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

仓库中始终提供最新的十个版本。

注意：对于 371.0.0 之前的版本，该软件包名称为 google-cloud-sdk

Red Hat/Fedora/CentOS

注意：如果您使用的是 Compute Engine 上的实例，则 Google Cloud CLI 默认安装在多个操作系统映像上。如需查看完整列表，请参阅操作系统详细信息。

软件包内容

对于 Red Hat Enterprise Linux 7、8 和 9、Fedora 33 和 34 以及 CentOS 7 和 CentOS 8 系统，可以通过软件包格式的 gcloud CLI 进行安装。此软件包仅包含 gcloud、gcloud alpha、gcloud beta、gsutil、和 bq 命令，而不包括 kubectl 或使用 gcloud 命令部署应用所需的 App Engine 扩展程序，您可以按照本部分稍后所述的方法单独安装。

安装

1. 使用 gcloud CLI 仓库信息更新 DNF。以下示例命令适用于与 Red Hat Enterprise Linux 9 兼容的安装，但请务必根据您的配置的需要更新设置：

   sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
   [google-cloud-cli]
   name=Google Cloud CLI
   baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
   enabled=1
   gpgcheck=1
   repo_gpgcheck=0
   gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
   EOM

2. 如果您要在 Fedora 34 或 35 上安装，请安装 libxcrypt-compat.x86_64。

   sudo dnf install libxcrypt-compat.x86_64

3. 安装 gcloud CLI：

   sudo dnf install google-cloud-cli

注意：如果您的系统尚未迁移到 dnf，则可以改用 yum 运行这些命令。

您还可以在提供的命令中使用 dnf/yum 选项，例如停用提示或试运行。

4. （可选）安装以下任何其他组件：
   • google-cloud-cli
   • google-cloud-cli-anthos-auth
   • google-cloud-cli-app-engine-go
   • google-cloud-cli-app-engine-grpc
   • google-cloud-cli-app-engine-java
   • google-cloud-cli-app-engine-python
   • google-cloud-cli-app-engine-python-extras
   • google-cloud-cli-bigtable-emulator
   • google-cloud-cli-cbt
   • google-cloud-cli-cloud-build-local
   • google-cloud-cli-cloud-run-proxy
   • google-cloud-cli-config-connector
   • google-cloud-cli-datastore-emulator
   • google-cloud-cli-firestore-emulator
   • google-cloud-cli-gke-gcloud-auth-plugin
   • google-cloud-cli-kpt
   • google-cloud-cli-kubectl-oidc
   • google-cloud-cli-local-extract
   • google-cloud-cli-minikube
   • google-cloud-cli-nomos
   • google-cloud-cli-pubsub-emulator
   • google-cloud-cli-skaffold
   • google-cloud-cli-spanner-emulator
   • google-cloud-cli-terraform-validator
   • google-cloud-cli-tests
   • kubectl

   例如，google-cloud-cli-app-engine-java 组件可以按以下方式安装：

   sudo dnf install google-cloud-cli-app-engine-java

5. 运行 gcloud init 以开始执行初始化操作：

   gcloud init

降级 gcloud CLI 版本

如果您想还原到特定版本的 gcloud CLI（其中 VERSION 的格式为 123.0.0），请运行 sudo dnf downgrade google-cloud-cli-VERSION。仓库中始终提供最新的十个版本。注意：对于 371.0.0 之前的版本，该软件包名称为 google-cloud-sdk

macOS

1. 确认您拥有受支持的 Python 版本：
   • 如需查看当前的 Python 版本，请运行 python3 -V 或 python -V。支持的版本是 Python 3.8 到 3.12。
   • 主安装脚本可安装 CPython 的 Python 3.11。
   • 否则，如需安装支持的 Python 版本，请访问 Python.org 适用于 macOS 的 Python 版本。
   • 如果您的机器上安装了多个 Python 解释器，请在 shell 中设置 CLOUDSDK_PYTHON 环境变量，使其指向首选解释器的路径。
   • 如需详细了解如何选择和配置 Python 解释器，请参阅 gcloud topic startup。
2. 下载以下内容之一：
   注意：如需确定机器硬件名称，请从命令行运行 uname -m。

平台	软件包	大小	SHA256 校验和
macOS 64 位 (x86_64)	google-cloud-cli-darwin-x86_64.tar.gz	53.6 MB	9525b9e7affb5447fdd22c8b7fc5e14f486793a835b07eeabe9311f66e939207
macOS 64 位 (ARM64, Apple M1 silicon)	google-cloud-cli-darwin-arm.tar.gz	53.5 MB	388e0289be5e2ca4ec2aeab3172fe28891080a11db9907a9502bd2a01c4896dd
macOS 32 位 (x86)	google-cloud-cli-darwin-x86.tar.gz	52.2 MB	56faf55a2882d85f4f3b7e27110a9bba258084df22a80bf5276706ed998a6505

1. 将归档解压缩到文件系统上的任意位置（最好是解压缩到您的主目录）。在 macOS 上，此操作可通过打开下载到首选位置的 .tar.gz 归档文件来实现。

   如需替换现有安装，请移除现有的 google-cloud-sdk 目录，然后将归档解压缩到同一位置。

2. （可选）使用安装脚本将 gcloud CLI 工具添加到您的 PATH。您还可以选择为 shell 启用命令补全功能、使用情况统计信息收集功能，并安装 Python 3.11。

   使用以下命令运行脚本（从您在上一步中解压缩的文件夹的根目录运行）：

   ./google-cloud-sdk/install.sh

   也可以通过提供偏好设置作为标志以非交互方式（例如使用脚本）完成此操作。如需描述可用标志，请运行以下命令：

   ./google-cloud-sdk/install.sh --help

   如需在开启屏幕阅读器模式的情况下运行安装脚本，请运行以下命令：

   ./google-cloud-sdk/install.sh --screen-reader=true

   打开新终端，以使更改生效。
3. 如需初始化 gcloud CLI，请运行 gcloud init：

./google-cloud-sdk/bin/gcloud init

4. 可选。使用组件管理器安装其他组件。

Windows

Google Cloud CLI 可在 Windows 8.1 及更高版本和 Windows Server 2012 及更高版本上运行。

1. 下载 Google Cloud CLI 安装程序。

   或者，打开 PowerShell 终端，然后运行以下 PowerShell 命令：

   (New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/", "$env:Temp\GoogleCloudSDKInstaller.exe")
   
   & $env:Temp\GoogleCloudSDKInstaller.exe
       

2. 启动安装程序并按提示操作。安装程序已经过 Google LLC 签名。

   如果您使用的是屏幕阅读器，请选中启用屏幕阅读器模式复选框。此选项会将 gcloud 配置为使用状态跟踪器而不是 Unicode 旋转图标，以百分比表示显示进度和展开的表。如需了解详情，请参阅无障碍功能指南。

3. Google Cloud CLI 要求安装 Python；受支持的版本是 Python 3.8 到 3.12。默认情况下，Windows 版本的 Google Cloud CLI 捆绑了 Python 3。如需使用 Google Cloud CLI，您的操作系统必须能够运行受支持的 Python 版本。

   安装程序会安装所有必需的依赖项（包括所需的 Python 版本）。虽然 Google Cloud CLI 默认安装和管理 Python 3，但您可以根据需要通过取消选中“安装捆绑的 Python”选项来使用已安装的 Python。请参阅 gcloud topic startup，了解如何使用现有 Python 安装。

4. 安装完成后，安装程序会为您提供创建开始菜单和桌面快捷方式、启动 Google Cloud CLI shell 以及配置 gcloud CLI 的选项。确保已选择用于启动 shell 并配置安装的选项。安装程序会启动终端窗口并运行 gcloud init 命令。

5. 默认安装不包括使用 gcloud 命令部署应用所必需的 App Engine 扩展程序。您可以使用 gcloud CLI 组件管理器安装这些组件。

问题排查提示：

• 如果由于 find 命令未被识别而导致安装失败，请确保您的 PATH 环境变量设置为将包含 find 的文件夹包括在内。通常，此文件夹为 C:\WINDOWS\system32;。
• 如果您卸载了 gcloud CLI，则必须先重新启动系统，然后才能再次安装 gcloud CLI。
• 如果解压缩失败，请以管理员身份运行安装程序。

使用 components update 命令执行更新操作：gcloud components update。

设置凭据以访问受保护的数据

如需访问受保护的数据或向受保护的存储桶写入数据，您需要设置凭据（身份验证）。例如，如果其他人创建了 Cloud Storage 账号并上传了只有您或其他特定人员可访问的数据，您必须向 Cloud Storage 服务设置凭据才能访问此数据。

将 gsutil 作为 Google Cloud CLI 的一部分时，系统将使用 OAuth2 来对 Cloud Storage 资源访问进行身份验证和授权。如需建立访问，请运行命令 gcloud init 并按照命令行中提供的说明操作，包括登录用户账号。请注意，如果您已完成上面的安装步骤，则可能已经执行了此设置。如果您之前运行过 gcloud init，则再次运行该命令时，系统会询问您是要重新初始化配置还是要创建新配置。如需了解详情，请参阅初始化 Google Cloud CLI。

大功告成！您已准备好访问受保护的数据。如需查看 gsutil 命令列表，请在命令提示符处输入 gsutil。

问题排查

如果您尝试使用 gcloud init 命令对 gsutil 进行身份验证，但仍无法访问预期的存储桶或对象，则您的系统可能同时安装了独立的旧版 gsutil 和 Google Cloud CLI 捆绑式 gsutil 版本。请运行 gsutil version -l 命令并检查 using cloud sdk 的值。如果为 False，则说明在您运行命令时，系统使用的是独立版 gsutil。建议您从系统中移除独立版 gsutil；但是，您也可以使用 gsutil config -a 或 gsutil config -e 进行身份验证。

使用 HMAC 进行身份验证

虽然我们建议您使用 OAuth 2.0 对 gsutil 进行身份验证，但您也可以将 HMAC 密钥用于您的凭据。如需使用 HMAC 进行身份验证，请使用以下命令：

gsutil config -a

使用此命令后，系统会引导您完成一个身份验证过程，在该过程中，系统会提示您输入与 HMAC 密钥关联的访问 ID 和密文。

使用 HMAC 密钥进行身份验证时，您应使用以下命令停用从 Google Cloud CLI 传递的凭据：gcloud config set pass_credentials_to_gsutil false。

启用 mTLS

您可能还需要启用双向 TLS (mTLS)。在设备上启用 mTLS 后，您的设备会尝试连接到 storage.mtls.googleapis.com。在允许连接之前，Cloud Storage 会验证您设备上的证书。

注意：仅当 gsutil 通过 Cloud Storage JSON API 发出请求时，才能使用此功能。

获取证书的最简单方法是使用 Google Cloud CLI。您可以手动在 .boto 文件的“Credentials”下设置以下值以设置一个证书：

1. use_client_certificate：用于控制是否使用 mTLS 的标志。
2. cert_provider_command：一个 shell 命令，用于将证书输出到 stdout，供 gsutil 读取。

自行试用

如果您是 Google Cloud 新手，请创建一个账号来评估 Cloud Storage 在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费试用 Cloud Storage