日期:2026-06-23
平台:Google Cloud Platform · GCE · GCS · STS
源端:asia-southeast1(新加坡)
目的端:europe-west4(荷兰)
关键技术:Private Google Access · Cloud NAT · IAP SSH · STS Python SDK
请根据自己的环境修改以下变量,后续所有步骤均直接引用这些变量,复制粘贴即可执行。
# ============================================================
# ↓↓↓ 请根据自己的环境修改以下变量 ↓↓↓
# ============================================================
# 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"
# ============================================================
# ↑↑↑ 以上变量修改完毕后,后续步骤直接复制粘贴即可 ↑↑↑
# ============================================================
┌───────────────────────────────────────────────────────────────────────┐
│ 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 等外网) │ │ │ │
│ └──────────────────────────────┘ └──────────────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
关键点:
roles/storage.admin(GCS 桶创建和数据读写)roles/storagetransfer.admin(STS 任务创建和管理)roles/compute.instanceAdmin(创建 VM)roles/compute.networkAdmin(创建 Cloud Router 和 Cloud NAT)# 启用所需 API
gcloud services enable \
storage.googleapis.com \
storagetransfer.googleapis.com \
iap.googleapis.com \
compute.googleapis.com \
--project=$PROJECT_ID
# 源桶(新加坡)
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
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
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
no-address:不分配外部 IP,确保写 GCS 时走 Private Google Access 内网路径--scopes=cloud-platform:授予 VM 完整的 GCP API 访问权限gcloud compute ssh $VM_NAME \
--zone=$SRC_ZONE \
--project=$PROJECT_ID \
--tunnel-through-iap
VM 没有外部 IP,无法直接访问 PyPI 或 apt 仓库。通过配置 Cloud NAT,VM 可以访问外网安装依赖,同时写 GCS 的流量继续走 Private Google Access 内网。
storage.googleapis.com)的流量始终走 Private Google Access 内网路径,不经过 Cloud NAT。参考: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
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
"
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
使用以下脚本创建 STS 传输任务并监控状态: sts_transfer.py
在 VM 上执行:
python3 sts_transfer.py
| 操作 | 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() | 获取任务定义和最新操作名称 |
适用于需要持续跟踪传输进度的场景。代码见
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: 源端总字节数
适用于需要快速判断传输是否完成以决定下一步动作的场景。代码见
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("传输仍在进行中...")
| 状态 | 含义 |
|---|---|
QUEUED | 排队等待执行 |
IN_PROGRESS | 正在传输中 |
PAUSED | 已暂停 |
SUCCESS | 传输成功完成 |
FAILED | 传输失败 |
ABORTED | 传输被取消 |
| 字段 | 说明 |
|---|---|
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 | 传输失败的对象数 |
使用 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 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!
除了上述 Python SDK 的方式外,也可以通过 Google Cloud Console UI 创建和管理 STS 传输任务:
# 删除 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
| 主题 | 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 API | cloud.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 |
| 包名 | PyPI |
|---|---|
google-cloud-storage | pypi.org/project/google-cloud-storage/ |
google-cloud-storage-transfer | pypi.org/project/google-cloud-storage-transfer/ |
| 示例 | 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