Git Action上传Docker Hub镜像致嵌入文件损坏问题求助

问题背景 #

通过FastAPI构建LLM服务，配置Git Action实现代码推送主分支时自动构建并推送Docker镜像到Docker Hub。但部署拉取镜像启动容器后，出现safetensors文件损坏报错：

safetensors_rust.SafetensorError: Error while deserializing header: HeaderTooLarge

已确认：Git Action克隆后的本地文件正常，仅Action推送的镜像内文件损坏；本地直接执行docker push无异常。

解决方法 #

1. 修复Git克隆时的大文件处理 #

Git Action默认克隆未启用Git LFS，若safetensors是大文件，会被替换为LFS占位符，导致构建镜像时文件损坏。需在克隆步骤开启LFS：

- name: Checkout code
  uses: actions/checkout@v4
  with:
    lfs: true  # 启用Git LFS拉取大文件

同时确保仓库已配置Git LFS追踪safetensors文件（本地执行git lfs track "*.safetensors"并提交.gitattributes）。

2. 修正Docker构建的文件复制逻辑 #

• 避免使用ADD命令处理二进制文件（ADD会自动解压压缩包，可能误处理safetensors），改用COPY命令：

  # 正确示例：直接复制二进制文件
  COPY ./models/model.safetensors /app/models/
  

• 禁用构建缓存，避免复用损坏的文件层：
  在Action的Docker构建命令中添加--no-cache参数：

  docker build --no-cache -t your-dockerhub-username/your-image:latest .
  

3. 规范Git Action的Docker推送配置 #

优先使用官方Docker Action而非手动命令，确保推送流程稳定：

- name: Login to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

- name: Build and push
  uses: docker/build-push-action@v5
  with:
    context: .  # 确保构建上下文包含所有必要文件
    push: true
    tags: your-dockerhub-username/your-image:latest

4. 添加镜像内文件完整性校验 #

在Action中增加哈希对比步骤，推送前验证镜像内文件与本地文件是否一致：

- name: Verify file integrity
  run: |
    LOCAL_HASH=$(sha256sum ./models/model.safetensors | awk '{print $1}')
    IMAGE_HASH=$(docker run --rm your-dockerhub-username/your-image:latest sha256sum /app/models/model.safetensors | awk '{print $1}')
    if [ "$LOCAL_HASH" != "$IMAGE_HASH" ]; then
      echo "Error: safetensors file corrupted in image!"
      exit 1
    fi

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