timoreymann/deterministic-zip

deterministic-zip Docker 镜像文档

镜像概述

deterministic-zip 是一个专注于创建确定性 ZIP 文件的工具，其核心特性是确保相同内容的文件在任何环境下压缩后都能生成具有固定哈希值的 ZIP 文件。该工具通过移除所有文件元数据（如修改时间、权限等）实现这一目标，同时支持 SOURCE_DATE_EPOCH 环境变量统一设置文件修改日期，是构建可重现软件包、服务器less代码压缩及需要稳定哈希值场景的理想选择。

核心功能与特性

• ZIP 替代品：可直接作为传统 zip 命令的替代品，支持常见压缩场景
• 元数据移除：自动清除所有平台下文件的元数据（修改时间、权限、所有者等）
• 不可变 ZIP：相同内容生成完全一致的 ZIP 文件，哈希值仅由文件内容决定
• SOURCE_DATE_EPOCH 支持：通过环境变量统一设置 ZIP 内文件的修改日期，符合可重现构建标准
• 轻量级镜像：仅包含工具二进制文件，无额外系统依赖，适合容器化集成

适用场景

• 可重现构建：在 CI/CD 流水线中确保不同构建环境生成相同的软件包
• Serverless 开发：压缩云函数代码（如 AWS Lambda、Azure Functions）时保证部署包一致性
• 备份与同步：生成固定哈希的 ZIP 文件，优化 rsync 等工具的增量同步效率
• 容器镜像集成：作为基础工具嵌入构建镜像，简化确定性压缩流程

使用方法

直接运行容器

镜像默认工作目录为 /workspace，需将待压缩文件挂载至此目录。容器仅包含 deterministic-zip 二进制文件，运行时需指定具体压缩命令。

bash
# 查看工具帮助
docker run --rm timoreymann/deterministic-zip:latest -h

# 压缩当前目录下的文件至 output.zip
docker run --rm -v $PWD:/workspace timoreymann/deterministic-zip:latest -r output.zip .

# 使用 SOURCE_DATE_EPOCH 设置统一修改日期
docker run --rm -e SOURCE_DATE_EPOCH=1609459200 -v $PWD:/workspace timoreymann/deterministic-zip:latest -r output.zip src/

集成至 Dockerfile

可通过多阶段构建将工具二进制文件复制到目标镜像中，实现本地化调用：

dockerfile
# 基础构建镜像
FROM base-image:tag

# 从 deterministic-zip 镜像复制工具至系统路径
COPY --from=timoreymann/deterministic-zip:latest /deterministic-zip /usr/local/bin/

# 后续构建步骤中使用 deterministic-zip 压缩文件
RUN deterministic-zip -r /app/package.zip /app/src

镜像特性说明

• 最小化设计：镜像仅包含 deterministic-zip 二进制文件，无操作系统或额外依赖
• 权限说明：默认以 root 用户运行，确保对挂载文件系统有足够访问权限
• 版本控制：通过标签指定版本（如 :latest、:v1.0.0），可配合依赖更新工具（如 Renovate）自动同步最新版本

环境变量

注意事项

• 挂载目录时确保文件权限正确，避免因权限不足导致压缩失败
• 如需自定义用户身份运行，可在 docker run 中添加 --user 参数，但需确保用户对挂载目录有读写权限
• 工具支持 glob 模式匹配文件，可通过 -i/--include 和 -x/--exclude 参数筛选文件

示例：CI/CD 流水线集成

在 GitHub Actions 中使用容器化工具压缩构建产物：

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Compress with deterministic-zip
        run: |
          docker run --rm -v $PWD:/workspace timoreymann/deterministic-zip:latest \
            -r build-output.zip \
            --exclude "*.log" \
            --exclude "tmp/" \
            dist/
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: build-zip
          path: build-output.zip