gsutil 命令行工具安装、配置与使用说明

本文档提供 gsutil 命令行工具的详细操作指南，涵盖从安装、配置到数据管理的全过程。gsutil 是 Google Cloud SDK 的核心组件，用于通过命令行与 Google Cloud Storage 进行交互。

1. 安装 Google Cloud SDK (包含 gsutil)

通过官方 apt 软件源进行安装，可确保后续的便捷更新。此流程适用于 Ubuntu/Debian 及其衍生系统。

1.1 安装依赖包

执行以下命令，更新系统软件包列表并安装 HTTPS 传输支持。

sudo apt update
sudo apt install -y apt-transport-https ca-certificates gnupg curl

1.2 导入 Google Cloud 公钥

为保证软件包的安全性，需导入 Google Cloud 的 GPG 密钥。

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

1.3 添加 SDK 软件源

将 Google Cloud SDK 的软件源地址添加到系统的源列表中。

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

1.4 执行安装

更新软件包列表以包含新添加的源，并安装 Google Cloud SDK。

sudo apt update
sudo apt install -y google-cloud-sdk

2. 初始化与身份验证

安装完成后，需执行一次性初始化，以登录 Google 账户并授权 SDK。

2.1 执行初始化命令

在终端中运行以下命令启动配置流程。

gcloud init

2.2 完成身份验证

该命令将引导完成以下步骤：

1. 在浏览器中打开一个 Google 账户登录页面。
2. 选择用于 Google Cloud 的账户并登录。
3. 授权 Google Cloud SDK 访问账户数据。
4. 授权成功后，认证信息将自动传递回终端。

注：在无图形界面的服务器环境中，可使用 gcloud auth login –no-launch-browser 命令，通过复制粘贴链接和授权码的方式完成验证。

3. 项目配置 (Config)

gcloud 命令行工具在一个指定的“项目 (Project)”上下文中运行。必须配置一个默认项目。

3.1 列出可用项目

执行以下命令，查看当前账户下所有可用的项目及其 PROJECT_ID。

gcloud projects list

3.2 设置默认项目

从上一步的列表中，选择一个 PROJECT_ID，并执行以下命令将其设为默认项目。

gcloud config set project [PROJECT_ID]
# *示例：gcloud config set project ragbuild*

3.3 验证当前配置

执行以下命令，检查当前的配置信息，确保 project 字段已正确设置。

gcloud config list

4. 访问网页版 Cloud Storage 浏览器

Google Cloud 提供图形化界面用于管理存储桶和数据。

4.1 打开方式

• 直接链接: 访问 https://console.cloud.google.com/storage/browser
• 通过导航:
  1. 访问 Google Cloud Console 主页 (https://console.cloud.google.com/)。
  2. 点击左上角的导航菜单 (☰)。
  3. 在菜单中找到 “Cloud Storage” 分类，点击 “存储桶 (Buckets)”。

4.2 项目选择

进入网页浏览器后，务必确认页面顶部的项目选择器显示的是当前需要操作的正确项目。项目不匹配是导致找不到文件的常见原因。

5. gsutil 基本数据操作

5.1 创建存储桶 (Bucket)

存储桶是存放数据的顶级容器，其名称全局唯一。

# 语法: gcloud storage buckets create gs://[BUCKET_NAME] --project=[PROJECT_ID] --location=[LOCATION]
gcloud storage buckets create gs://duojiechen-central-data-storage --project=ragbuild --location=asia-east1

5.2 上传数据

• 上传单个文件: 使用 gsutil cp 命令。

  # 语法: gsutil cp [LOCAL_FILE_PATH] gs://[BUCKET_NAME]/[DESTINATION_PATH]
  gsutil cp ./report.pdf gs://duojiechen-central-data-storage/documents/

• 同步整个目录: 使用 gsutil rsync 命令，此方法效率更高，仅同步差异文件。

  # 语法: gsutil -m rsync -r [LOCAL_DIRECTORY_PATH] gs://[BUCKET_NAME]/[DESTINATION_DIRECTORY]
  # -m: 开启多线程，提升性能
  # -r: 递归同步
  gsutil -m rsync -r ~/Projects/Central_Data gs://duojiechen-central-data-storage/Central_Data

5.3 下载数据

• 下载单个文件: 使用 gsutil cp 命令。

  # 语法: gsutil cp gs://[BUCKET_NAME]/[OBJECT_PATH] [LOCAL_DESTINATION_PATH]
  gsutil cp gs://duojiechen-central-data-storage/documents/report.pdf ./

• 同步整个目录: 使用 gsutil rsync 命令。

  # 语法: gsutil -m rsync -r gs://[BUCKET_NAME]/[SOURCE_DIRECTORY] [LOCAL_DESTINATION_DIRECTORY]
  gsutil -m rsync -r gs://duojiechen-central-data-storage/Central_Data ~/Backup/Central_Data

5.4 数据管理

• 列出内容 (List): 使用 gsutil ls 命令。

  # 列出所有存储桶
  gsutil ls
  
  # 列出特定存储桶内的内容
  gsutil ls -r gs://duojiechen-central-data-storage

• 移动/重命名 (Move/Rename): 使用 gsutil mv 命令。

  # 语法: gsutil mv gs://[BUCKET_NAME]/[SOURCE_OBJECT] gs://[BUCKET_NAME]/[DESTINATION_OBJECT]
  gsutil mv gs://duojiechen-central-data-storage/report.pdf gs://duojiechen-central-data-storage/documents/final_report.pdf

• 删除 (Remove): 使用 gsutil rm 命令。

  # 删除单个文件
  gsutil rm gs://duojiechen-central-data-storage/documents/final_report.pdf
  
  # 递归删除整个文件夹及其内容
  gsutil rm -r gs://duojiechen-central-data-storage/old_data