GCS 跨区域传输 Demo
VM + Private Google Access + Storage Transfer Service

日期:2026-06-23
平台:Google Cloud Platform · GCE · GCS · STS
源端:asia-southeast1(新加坡)
目的端:europe-west4(荷兰)
关键技术:Private Google Access · Cloud NAT · IAP SSH · STS Python SDK

文档说明:本文档演示如何通过 Python SDK,使用 GCE VM (Private Google Access) 写数据到 GCS,再通过 Storage Transfer Service (STS) 将数据传输到另一个 Region 的 GCS 桶。所有步骤均经过实际验证。

全局变量(请先修改)

请根据自己的环境修改以下变量,后续所有步骤均直接引用这些变量,复制粘贴即可执行。

# ============================================================
#  ↓↓↓ 请根据自己的环境修改以下变量 ↓↓↓
# ============================================================

# GCP 项目 ID
export PROJECT_ID="gpu-launchpad-playground"

# 源端(新加坡)
export SRC_REGION="asia-southeast1"
export SRC_ZONE="asia-southeast1-b"
export SRC_BUCKET="sts-demo-singapore-src"

# 目的端(荷兰)
export DST_REGION="europe-west4"
export DST_BUCKET="sts-demo-netherlands-dst"

# VM 配置
export VM_NAME="sts-demo-vm"
export MACHINE_TYPE="n2d-standard-4"
export NETWORK="default"
export SUBNET="default"

# ============================================================
#  ↑↑↑ 以上变量修改完毕后,后续步骤直接复制粘贴即可 ↑↑↑
# ============================================================

1. 架构概述

┌───────────────────────────────────────────────────────────────────────┐
│                        GCP Project                                    │
│                                                                       │
│  ┌──────────────────────────────┐       ┌──────────────────────┐     │
│  │ asia-southeast1 (新加坡)      │       │ europe-west4 (荷兰)  │     │
│  │                              │       │                      │     │
│  │  ┌────────────────────────┐  │  STS  │  ┌────────────────┐  │     │
│  │  │  GCS Bucket (Source)   │  │ ───▶ │  │  GCS Bucket    │  │     │
│  │  └───────▲────────────────┘  │ 传输   │  │  (Destination) │  │     │
│  │          │                   │       │  └────────────────┘  │     │
│  │   Private Google Access      │       │                      │     │
│  │   (内网直连 GCS API)          │       │                      │     │
│  │          │                   │       │                      │     │
│  │  ┌───────┴────────────────┐  │       │                      │     │
│  │  │  VM (无外部 IP)         │  │       │                      │     │
│  │  │  n2d-standard-4        │  │       │                      │     │
│  │  └───────┬────────────────┘  │       │                      │     │
│  │          │                   │       │                      │     │
│  │   Cloud NAT                  │       │                      │     │
│  │   (访问 PyPI/apt 等外网)      │       │                      │     │
│  └──────────────────────────────┘       └──────────────────────┘     │
└───────────────────────────────────────────────────────────────────────┘

关键点:

2. 前置条件

# 启用所需 API
gcloud services enable \
  storage.googleapis.com \
  storagetransfer.googleapis.com \
  iap.googleapis.com \
  compute.googleapis.com \
  --project=$PROJECT_ID

3. Step 1: 创建 GCS 存储桶

# 源桶(新加坡)
gcloud storage buckets create gs://$SRC_BUCKET \
  --location=$SRC_REGION \
  --project=$PROJECT_ID \
  --uniform-bucket-level-access

# 目的桶(荷兰)
gcloud storage buckets create gs://$DST_BUCKET \
  --location=$DST_REGION \
  --project=$PROJECT_ID \
  --uniform-bucket-level-access

4. Step 2: 配置 Private Google Access 并创建 VM

4.1 确认子网已启用 Private Google Access

gcloud compute networks subnets describe $SUBNET \
  --region=$SRC_REGION \
  --project=$PROJECT_ID \
  --format="get(privateIpGoogleAccess)"

如果返回 False,执行以下命令启用:

gcloud compute networks subnets update $SUBNET \
  --region=$SRC_REGION \
  --enable-private-ip-google-access \
  --project=$PROJECT_ID

4.2 创建 VM(无外部 IP)

gcloud compute instances create $VM_NAME \
  --project=$PROJECT_ID \
  --zone=$SRC_ZONE \
  --machine-type=$MACHINE_TYPE \
  --network-interface=network=$NETWORK,subnet=$SUBNET,no-address \
  --scopes=cloud-platform \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud \
  --boot-disk-size=50GB \
  --boot-disk-type=pd-balanced
关键参数说明:

4.3 通过 IAP 隧道 SSH 到 VM

gcloud compute ssh $VM_NAME \
  --zone=$SRC_ZONE \
  --project=$PROJECT_ID \
  --tunnel-through-iap

5. Step 3: 配置 Cloud NAT 并安装 Python 依赖

VM 没有外部 IP,无法直接访问 PyPI 或 apt 仓库。通过配置 Cloud NAT,VM 可以访问外网安装依赖,同时写 GCS 的流量继续走 Private Google Access 内网。

Cloud NAT 与 Private Google Access 的关系:两者可以同时启用,互不冲突。发往 Google API(如 storage.googleapis.com)的流量始终走 Private Google Access 内网路径,不经过 Cloud NAT。参考:Cloud NAT 概述

5.1 创建 Cloud Router 和 Cloud NAT

# 创建 Cloud Router
gcloud compute routers create nat-router-$SRC_REGION \
  --project=$PROJECT_ID \
  --network=$NETWORK \
  --region=$SRC_REGION

# 创建 Cloud NAT 网关
gcloud compute routers nats create nat-config-$SRC_REGION \
  --router=nat-router-$SRC_REGION \
  --region=$SRC_REGION \
  --project=$PROJECT_ID \
  --nat-all-subnet-ip-ranges \
  --auto-allocate-nat-external-ips

5.2 在 VM 上安装 Python 依赖

Cloud NAT 生效后(通常 1-2 分钟),VM 即可访问外网安装包:

gcloud compute ssh $VM_NAME --zone=$SRC_ZONE \
  --project=$PROJECT_ID --tunnel-through-iap --command="
sudo apt-get update -y && sudo apt-get install -y python3-pip
pip3 install google-cloud-storage google-cloud-storage-transfer
"

6. Step 4: 生成 Mock 数据并上传到 GCS

SSH 到 VM 后执行以下命令,生成 100GB 测试数据并上传到 GCS:

# 生成 100GB 测试数据(1000 个 100MB 文件)
mkdir -p /tmp/mock_data
for i in $(seq -w 0 999); do
  dd if=/dev/urandom of=/tmp/mock_data/chunk_${i}.bin bs=1M count=100 2>/dev/null
  # 每 100 个文件打印一次进度
  if [ $(( 10#$i % 100 )) -eq 0 ]; then echo "Generated $i / 999"; fi
done

# 上传到 GCS(自动并行,走 Private Google Access 内网)
gcloud storage cp -r /tmp/mock_data/* gs://$SRC_BUCKET/mock_data/
说明:gcloud storage cp 底层自动并行上传,速度远快于 Python SDK 逐文件上传(实测 235 MB/s vs 102 MB/s)。此处流量通过 Private Google Access 内网直连 GCS,不经过 Cloud NAT 和公网。

也可使用我们提供的自动化脚本: upload_mock_data.py

7. Step 5: 通过 STS SDK 跨区域传输数据

使用以下脚本创建 STS 传输任务并监控状态: sts_transfer.py

在 VM 上执行:

python3 sts_transfer.py

关键 API 说明

操作API 方法说明
创建任务client.create_transfer_job()创建一个传输任务定义
运行任务client.run_transfer_job()立即触发已创建的传输任务
查询操作列表client.transport.operations_client.list_operations()列出任务的所有操作记录
查询最新操作client.transport.operations_client.get_operation()获取单个操作的详细状态
获取任务信息client.get_transfer_job()获取任务定义和最新操作名称

8. Step 6: 查询 STS 任务状态

8.1 方法一:轮询 list_operations(实时进度监控)

适用于需要持续跟踪传输进度的场景。代码见 sts_transfer.py 中的 poll_transfer_status() 函数。

核心调用方式(来自官方示例 transfer_check.py):

ops_client = client.transport.operations_client
job_filter = json.dumps({"projectId": PROJECT_ID, "jobNames": [job_name]})
response = ops_client.list_operations("transferOperations", job_filter)

for op in response:
    metadata = storage_transfer.TransferOperation.deserialize(op.metadata.value)
    status = storage_transfer.TransferOperation.Status(metadata.status)
    counters = metadata.counters
    # status.name: QUEUED / IN_PROGRESS / SUCCESS / FAILED / ABORTED
    # counters.bytes_copied_to_sink: 已复制字节数
    # counters.bytes_found_from_source: 源端总字节数

8.2 方法二:check_latest_operation(判断是否完成)

适用于需要快速判断传输是否完成以决定下一步动作的场景。代码见 sts_transfer.py 中的 check_latest_operation() 函数。

核心调用方式(来自官方示例 check_latest_transfer_operation.py):

transfer_job = client.get_transfer_job({"project_id": PROJECT_ID, "job_name": job_name})
if transfer_job.latest_operation_name:
    response = client.transport.operations_client.get_operation(
        transfer_job.latest_operation_name
    )
    metadata = storage_transfer.TransferOperation.deserialize(response.metadata.value)

使用示例:根据完成状态执行下一步

client = storage_transfer.StorageTransferServiceClient()
is_complete, status, metadata = check_latest_operation(client, "transferJobs/YOUR_JOB_ID")

if is_complete and status == "SUCCESS":
    print("传输完成,可以进行下一步操作!")
    print(f"  传输数据量: {metadata.counters.bytes_copied_to_sink / (1024**3):.2f} GB")
    duration = metadata.end_time.timestamp() - metadata.start_time.timestamp()
    print(f"  传输耗时: {duration:.1f}s")
elif is_complete:
    print(f"传输失败,状态: {status}")
else:
    print("传输仍在进行中...")

TransferOperation 状态值

状态含义
QUEUED排队等待执行
IN_PROGRESS正在传输中
PAUSED已暂停
SUCCESS传输成功完成
FAILED传输失败
ABORTED传输被取消

TransferCounters 关键字段

字段说明
bytes_found_from_source源端发现的总字节数
bytes_copied_to_sink已复制到目的端的字节数
objects_found_from_source源端发现的对象数
objects_copied_to_sink已复制到目的端的对象数
objects_from_source_skipped_by_sync因已存在跳过的对象数
objects_from_source_failed传输失败的对象数

9. 实际运行结果

数据上传(VM → GCS,通过 Private Google Access 内网)

使用 gcloud storage cp 上传 100GB 模拟数据(1000 个 100MB 文件):

$ gcloud storage cp -r /tmp/mock_data/* gs://sts-demo-singapore-src/mock_data/

Copying file:///tmp/mock_data/chunk_0000.bin to gs://sts-demo-singapore-src/mock_data/chunk_0000.bin
...
Copying file:///tmp/mock_data/chunk_0999.bin to gs://sts-demo-singapore-src/mock_data/chunk_0999.bin

Average throughput: 202.2 MiB/s
Completed in 8m19s
速度对比:gcloud storage cp 自动并行上传,实测 ~202 MiB/s,比 Python SDK 逐文件上传(~102 MB/s)快约 2 倍,推荐使用。

STS 跨区域传输(新加坡 → 荷兰,100GB)

============================================================
STS Transfer Demo: Singapore -> Netherlands
============================================================
Created transfer job: transferJobs/13757290643445801766
Transfer operation started. Polling for completion...

Polling transfer status (every 10s):
  Status: QUEUED       | Progress:   0.0% | Copied: 0.00/0.00 GB   | Objects: 0/0       | Speed: ~0.0 MB/s
  Status: IN_PROGRESS  | Progress:   0.0% | Copied: 0.00/97.66 GB  | Objects: 0/1001    | Speed: ~0.0 MB/s
  Status: IN_PROGRESS  | Progress:   0.0% | Copied: 0.00/97.66 GB  | Objects: 1/1001    | Speed: ~0.0 MB/s
  Status: IN_PROGRESS  | Progress:  76.9% | Copied: 75.13/97.66 GB | Objects: 434/1001  | Speed: ~7693.2 MB/s
  Status: IN_PROGRESS  | Progress: 100.0% | Copied: 97.65/97.66 GB | Objects: 999/1001  | Speed: ~2306.0 MB/s
  Status: SUCCESS      | Progress: 100.0% | Copied: 97.66/97.66 GB | Objects: 1001/1001 | Speed: ~0.8 MB/s

Transfer completed successfully!
------------------------------------------------------------
Final Transfer Statistics:
  Bytes found from source:  97.66 GB
  Bytes copied to sink:     97.66 GB
  Objects found:            1001
  Objects copied:           1001
  Objects skipped (sync):   0
  Objects failed:           0
  Duration:                 53.2s
  Average speed:            1881.4 MB/s
------------------------------------------------------------

--- Completion Check Demo ---
  is_complete = True
  status      = SUCCESS
  -> Ready for next step!
STS 性能:100GB 跨区域传输仅耗时 53.2 秒,平均速度 ~1.84 GB/s,峰值速度 ~7.7 GB/s。STS 是 Google 服务端传输,不经过本地网络,传输速度远超客户端上传。

10. 使用 Console UI 创建传输任务(替代方案)

除了上述 Python SDK 的方式外,也可以通过 Google Cloud Console UI 创建和管理 STS 传输任务:

11. 清理资源

# 删除 Cloud NAT 和 Cloud Router
gcloud compute routers nats delete nat-config-$SRC_REGION \
  --router=nat-router-$SRC_REGION \
  --region=$SRC_REGION --project=$PROJECT_ID --quiet

gcloud compute routers delete nat-router-$SRC_REGION \
  --region=$SRC_REGION --project=$PROJECT_ID --quiet

# 删除 VM
gcloud compute instances delete $VM_NAME \
  --zone=$SRC_ZONE --project=$PROJECT_ID --quiet

# 清空并删除存储桶
gcloud storage rm -r gs://$SRC_BUCKET --project=$PROJECT_ID
gcloud storage rm -r gs://$DST_BUCKET --project=$PROJECT_ID

12. 官方参考文档与源码

官方文档

主题URL
Private Google Access 配置cloud.google.com/vpc/docs/configure-private-google-access
Cloud NAT 概述cloud.google.com/nat/docs/overview
Cloud NAT 配置cloud.google.com/nat/docs/set-up-manage-network-address-translation
Cloud Router 创建cloud.google.com/network-connectivity/docs/router/how-to/create-router-vpc-network
Storage Transfer Service 概述cloud.google.com/storage-transfer/docs/overview
STS 创建传输任务(SDK)cloud.google.com/storage-transfer/docs/create-transfers
STS 创建传输任务(Console UI)cloud.google.com/storage-transfer/docs/create-manage-transfer-console
STS transferOperations REST APIcloud.google.com/storage-transfer/docs/reference/rest/v1/transferOperations
GCS 上传对象cloud.google.com/storage/docs/uploading-objects
STS Python 客户端库参考cloud.google.com/python/docs/reference/storagetransfer/latest
IAP TCP 转发(SSH 隧道)cloud.google.com/iap/docs/using-tcp-forwarding

Python SDK PyPI 包

包名PyPI
google-cloud-storagepypi.org/project/google-cloud-storage/
google-cloud-storage-transferpypi.org/project/google-cloud-storage-transfer/

官方 Python 示例代码(GitHub)

示例URL
STS 示例目录github.com/.../storagetransfer
创建传输任务nearline_request.py
查询传输操作状态transfer_check.py
查询最新传输操作check_latest_transfer_operation.py
STS Python SDK 源码github.com/.../google-cloud-storage-transfer

GCP GPU Infrastructure Documentation Hub