AzCopy边缘节点到ADLS文件拷贝测试环境运行异常问题咨询

问题现象 #

• 相同AzCopy配置与执行脚本在开发（Dev）环境可正常完成边缘节点到ADLS存储的文件复制，切换至测试环境后执行失败
• 服务主体认证相关环境变量配置与登录代码如下：

export AZCOPY_AUTO_LOGIN_TYPE="SPN"
export AZCOPY_SPA_APPLICATION_ID="$client_id"
export AZCOPY_SPA_CLIENT_SECRET="$client_secret"
export AZCOPY_TENANT_ID="$tenant_id"
az login --service-principal -u $client_id --tenant $tenant_id -p $client_secret

• AzCopy文件拷贝执行命令：

azcopy cp --overwrite "True" "$src_file_path" "$dest_file_path" --put-md5

排查思路与可行解决方案 #

注意：AzCopy自身的SPN认证体系和Azure CLI的az login认证完全独立，脚本同时配置两套认证逻辑时，环境差异很容易触发认证优先级不匹配、权限错位问题，按以下顺序逐一定位：

• 校验测试环境服务主体凭证与权限有效性
  先在测试环境边缘节点单独执行服务主体登录命令，确认凭证本身可用：

  az login --service-principal -u $client_id --tenant $tenant_id -p $client_secret
  # 登录成功后执行以下命令，验证服务主体对目标ADLS的访问权限
  az storage fs directory list -f <目标ADLS容器名> --account-name <目标ADLS存储账户名> --auth-mode login
  

  若该步骤报错，直接对应处理：
  • 若提示凭证无效：核对测试环境使用的client_id/client_secret/tenant_id三个参数是否正确，排查是否误用Dev环境凭证、测试环境服务主体密钥是否过期
  • 若提示无权限：给对应服务主体分配目标存储账户的存储Blob数据参与者角色，注意不要只分配管理平面的普通参与者角色，ADLS数据面读写操作必须配置数据平面角色权限
• 排除两套认证逻辑冲突问题
  当前脚本同时配置AzCopy自带的SPN自动登录环境变量、又执行Azure CLI服务主体登录，AzCopy默认优先读取自身环境变量的认证信息，不会复用Azure CLI的登录态，很容易出现两边配置不一致的问题。执行复制命令前先清空AzCopy自带的SPN配置，显式指定复用Azure CLI登录态即可排除该问题：

  # 清空AzCopy独立SPN认证配置
  unset AZCOPY_AUTO_LOGIN_TYPE AZCOPY_SPA_APPLICATION_ID AZCOPY_SPA_CLIENT_SECRET AZCOPY_TENANT_ID
  # 显式指定AzCopy使用Azure CLI登录凭证
  export AZCOPY_AUTO_LOGIN_TYPE="AZCLI"
  # 重新执行复制命令
  azcopy cp --overwrite "True" "$src_file_path" "$dest_file_path" --put-md5
  

• 校验测试环境网络连通性
  开发环境和测试环境的网络策略通常存在差异，先在边缘节点验证ADLS端点连通性：

  # 替换为测试环境目标ADLS存储账户名
  nslookup <存储账户名>.dfs.core.windows.net
  telnet <存储账户名>.dfs.core.windows.net 443
  

  若连通失败，逐一排查：边缘节点出站安全组规则是否放通443端口、目标存储账户防火墙是否将边缘节点出口IP加入允许列表、是否存在代理拦截ADLS端点请求。
• 校验路径配置正确性
  核对测试环境源、目标路径是否符合要求：
  • 本地源路径：确认执行AzCopy的操作系统用户对源文件有读取权限
  • ADLS目标路径：必须使用dfs端点，标准格式为https://<存储账户名>.dfs.core.windows.net/<容器名>/<目标文件路径>，禁止误用blob.core.windows.net端点；若目标路径包含多层未创建的目录，补充--recursive参数执行
• 校验版本与参数兼容性
  分别在Dev、测试环境边缘节点执行azcopy --version核对版本，若测试环境版本低于Dev环境1个以上大版本，先升级AzCopy到和Dev环境一致的稳定版，规避旧版本的认证、MD5计算已知bug。
  若去掉--put-md5参数后复制可正常执行，说明是MD5计算环节报错，给执行AzCopy的用户授予系统临时目录的读写权限即可，旧版本AzCopy计算MD5时需要写入临时文件，临时目录权限不足会直接中断复制流程。

内容的提问来源于stack exchange，提问作者Reddy