mfinelli/azcopy

docker-azcopy

!https://github.com/mfinelli/docker-azcopy/workflows/Lint/badge.svg !Image Size

镜像概述与主要用途

概述

docker-azcopy 是基于 Alpine Linux 构建的轻量级容器镜像，封装了微软 Azure 官方的 Azcopy 工具。Azcopy 是一款用于 Azure 存储服务间高效数据传输的命令行工具，支持多种存储类型间的批量数据迁移与同步。

主要用途

提供无需本地安装依赖的 Azcopy 运行环境，适用于各类 Docker 兼容场景下的 Azure 存储数据传输操作，包括数据迁移、备份、同步及自动化流程集成等。

核心功能与特性

Azcopy 工具核心功能

• 多存储类型支持：兼容 Azure Blob Storage（块/页/追加 Blob）、File Storage、Data Lake Storage Gen2 等服务
• 高效传输能力：支持断点续传、并行传输（可配置并发数）、增量同步（仅传输变更数据）
• 灵活认证机制：支持 SAS 令牌、Azure AD 认证、服务主体（SPN）等多种身份验证方式
• 完整命令集：提供 copy（复制）、sync（同步）、remove（删除）、jobs（任务管理）等核心操作命令

容器化特性

• 轻量级基础：基于 Alpine Linux，镜像体积小，资源占用低
• 环境隔离：独立运行环境，避免系统依赖冲突，简化跨平台部署
• 即开即用：无需预配置，拉取镜像后可直接执行 Azcopy 命令
• 兼容性广：支持 Docker、Kubernetes 等容器运行时，适配 Linux/macOS/Windows 系统

使用场景与适用范围

典型使用场景

• Azure 存储数据迁移：在不同存储账户、容器或服务间批量迁移数据（如 Blob 到 Data Lake）
• 自动化备份：通过定时任务（如 cron）执行容器命令，实现 Azure 存储数据定期备份
• CI/CD 流程集成：在持续部署管道中传输构建产物至 Azure 存储（如静态资源上传至 Blob）
• 多环境一致性：确保开发/测试/生产环境使用相同版本的 Azcopy，避免版本差异导致的兼容性问题

适用范围

• 无本地 Azcopy 安装权限的环境（如共享服务器、受限工作站）
• Docker/Kubernetes 集群环境下的 Azure 数据操作
• 轻量级服务器或边缘设备（低资源环境需求）
• 临时任务场景（如一次性数据迁移，容器退出后自动清理）

使用方法与配置说明

基本用法

容器镜像可直接作为 Azcopy 命令行工具使用，语法与原生 Azcopy 一致。基本命令格式：

shell
docker run --rm -it mfinelli/azcopy [azcopy-command] [options]

常用示例

• 查看版本：

  shell
  docker run --rm -it mfinelli/azcopy --version
  

• 查看帮助（列出所有命令）：

  shell
  docker run --rm -it mfinelli/azcopy help
  

• 获取具体命令帮助（如 copy 命令）：

  shell
  docker run --rm -it mfinelli/azcopy help copy
  

挂载本地目录（文件共享）

若需访问本地文件或持久化配置，需通过 -v 参数挂载本地目录至容器：

shell
# 示例：传输本地文件至 Azure Blob（挂载当前目录至容器内 /data）
docker run --rm -it -v $(pwd):/data mfinelli/azcopy copy \
  "/data/local-file.txt" \
  "https://<storage-account>.blob.core.windows.net/<container>/remote-file.txt?<sas-token>"

关键挂载路径：

• 数据目录：挂载本地文件存储路径（如 -v ./data:/data）
• 配置目录：挂载 ~/.azcopy 以持久化任务状态、日志及认证缓存（如 -v ~/.azcopy:/root/.azcopy）

环境变量配置

Azcopy 支持通过环境变量传递认证信息及运行参数，容器中可通过 -e 设置：

示例：服务主体认证传输

shell
docker run --rm -it \
  -e AZCOPY_SPA_CLIENT_ID="your-spn-client-id" \
  -e AZCOPY_SPA_TENANT_ID="your-tenant-id" \
  -e AZCOPY_SPA_CLIENT_SECRET="your-spn-secret" \
  mfinelli/azcopy copy \
  "https://source-account.dfs.core.windows.net/source-container" \
  "https://dest-account.dfs.core.windows.net/dest-container" \
  --recursive  # 递归传输目录内容

Docker 部署方案示例

1. 基础 docker run 命令

shell
# 查看 Azcopy 帮助文档
docker run --rm -it mfinelli/azcopy help

# 递归同步本地目录至 Azure Blob（挂载本地目录+SAS认证）
docker run --rm -it -v $(pwd)/docs:/docs mfinelli/azcopy sync \
  "/docs" \
  "https://myaccount.blob.core.windows.net/mycontainer?sp=racwdl&st=2024-01-01T00:00:00Z&se=2024-12-31T00:00:00Z&spr=https&sv=2023-01-03&sr=c&sig=xxx" \
  --recursive --delete-destination true

2. docker-compose 配置（持久化场景）

适用于需固定挂载目录及环境变量的场景（如定期任务）：

yaml
version: '3'
services:
  azcopy:
    image: mfinelli/azcopy
    volumes:
      - ./local-data:/data               # 本地数据目录（需传输的文件）
      - ./azcopy-config:/root/.azcopy    # 持久化 Azcopy 配置（任务状态、日志）
    environment:
      - AZCOPY_LOG_LOCATION=/root/.azcopy/logs  # 日志存储路径
      - AZCOPY_JOB_PLAN_LOCATION=/root/.azcopy/jobs  # 任务计划路径
    command: ["sync", "/data", "https://myaccount.blob.core.windows.net/mycontainer?<sas-token>", "--recursive"]

启动命令：docker-compose run --rm azcopy

关键参数说明

• --rm：容器退出后自动删除，避免残留容器文件
• -it：启用交互模式并分配终端，支持命令行输入（如确认操作）
• -v <local>:<container>：挂载本地目录至容器，实现文件共享
• -e <KEY>=<VALUE>：设置环境变量，传递认证信息或配置参数
• Azcopy 原生参数：如 --recursive（递归传输）、--delete-destination（删除目标端多余文件）等，完整列表见 Azcopy 官方文档

注意事项

• 权限问题：本地挂载目录权限需允许容器用户（默认 root）访问，建议设置目录权限为 755
• 网络配置：传输大量数据时，建议配置 Docker 网络 MTU 与宿主机一致，避免分片性能损耗
• 版本控制：通过镜像标签指定 Azcopy 版本（如 mfinelli/azcopy:10.19），避免自动升级导致兼容性问题（标签列表见 https://hub.docker.com/r/mfinelli/azcopy/tags%EF%BC%89