gsutil-rsync Docker镜像文档

概述

gsutil-rsync是一个基于gsutil工具的Docker镜像，专门用于实现本地文件系统与Google Cloud Storage (GCS)存储桶之间的数据同步。该镜像封装了gsutil的rsync命令，提供了便捷的配置方式和定时同步功能，适用于需要定期从GCS同步数据的场景。

核心功能与特性

• 高效同步：利用gsutil的rsync算法实现增量同步，只传输变更的文件
• 定时任务：支持配置定时同步任务，满足定期数据同步需求
• 日志记录：完整记录同步过程，便于问题排查和审计
• 灵活配置：通过环境变量自定义同步参数和行为
• 轻量级：基于 Alpine Linux，镜像体积小，资源占用低

使用场景

• 作为数据备份工具，定期从GCS同步重要数据到本地
• 作为镜像站点维护工具，同步GCS上的开源软件仓库
• 作为数据预处理流程的一部分，定期获取GCS中的原始数据
• 构建CI/CD流程中，从GCS获取构建依赖或部署资源

使用方法

基本用法

docker run -d \
  -e GCS_SRC=gs://my-bucket/path \
  -e LOCAL_DEST=/data \
  -v /path/to/local/data:/data \
  ***/gsutil-rsync

定时同步

docker run -d \
  -e GCS_SRC=gs://my-bucket/path \
  -e LOCAL_DEST=/data \
  -e CRON="0 */6 * * *" \  # 每6小时同步一次
  -v /path/to/local/data:/data \
  ***/gsutil-rsync

Docker Compose配置

version: '3'
services:
  gsutil-sync:
    image: ***/gsutil-rsync
    restart: always
    environment:
      - GCS_SRC=gs://my-bucket/path
      - LOCAL_DEST=/data
      - CRON="0 */12 * * *"  # 每12小时同步一次
      - SYNC_OPTIONS=-r -c -d
      - LOG_LEVEL=info
    volumes:
      - /path/to/local/data:/data
      - /path/to/service-account.json:/etc/gcs/service-account.json
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

环境变量配置

权限配置

为了访问GCS存储桶，需要提供有效的GCP服务账号密钥：

1. 创建GCP服务账号并授予适当权限（至少需要存储对象查看者权限）
2. 下载JSON格式的密钥文件
3. 通过卷挂载将密钥文件挂载到容器中，默认路径为/etc/gcs/service-account.json

同步选项详解

SYNC_OPTIONS环境变量可配置的常用参数：

• -r: 递归同步子目录
• -c: 基于文件内容（而非时间戳和大小）进行比较
• -d: 删除本地存在但GCS中不存在的文件
• -n: 执行"干运行"，只显示将要执行的操作而不实际执行
• -P: 保留文件的权限和时间戳
• -q: 安静模式，减少输出信息

完整的选项列表可参考gsutil rsync文档

日志管理

容器会将同步日志输出到标准输出和指定的日志文件（默认/var/log/gsutil-rsync.log）。建议通过Docker的日志驱动配置日志轮转，避免日志文件过大。

注意事项

• 确保服务账号具有足够的权限访问指定的GCS存储桶
• 对于大型数据集，首次同步可能需要较长时间，请适当设置超时时间
• 使用-d选项时要格外小心，可能会删除本地文件
• 定期检查同步日志，确保同步任务正常运行