kurtosistech/files-artifacts-expander

文件制品卷展开工具镜像

镜像概述

该镜像专注于将文件制品（如压缩包、静态文件集合）处理并展开到Docker卷中，旨在简化容器化应用的文件部署流程，尤其适用于需要在容器初始化阶段或运行时将文件持久化到卷的场景。

核心功能与特性

• 文件制品处理：支持主流压缩格式（tar、tar.gz、zip）的自动识别与解压，无需额外依赖
• 卷部署支持：直接将处理后的文件写入指定Docker卷，确保数据持久化
• 轻量级设计：基于最小化基础镜像构建，降低资源占用与部署时间
• 灵活配置：通过环境变量自定义制品路径、目标卷路径及处理规则
• 兼容性：适配Docker官方卷驱动及主流第三方卷插件

使用场景

• 容器初始化：部署静态资源（前端代码、配置文件、模板）到持久卷，供应用容器读取
• 数据迁移：将备份文件或历史数据展开到新卷，实现容器间数据共享
• CI/CD集成：在流水线中自动处理构建产物并部署至目标卷，简化发布流程
• 多环境适配：根据不同环境配置（如开发/生产）展开对应版本的制品文件

使用方法

基本使用（docker run）

bash
docker run --rm \
  -v /host/path/to/artifacts:/artifacts \  # 挂载包含制品的本地目录
  -v target-volume:/target \               # 挂载目标Docker卷
  -e ARTIFACT_PATH="/artifacts/app.tar.gz" \  # 指定制品文件路径
  -e TARGET_VOLUME_PATH="/target/www" \       # 指定卷内目标路径
  your-image-name

说明：执行后，镜像会解压/artifacts/app.tar.gz并将内容写入target-volume卷的/www目录

环境变量配置

Docker Compose集成示例

yaml
version: '3.8'

volumes:
  app-static-volume:  # 定义目标卷

services:
  artifact-expander:
    image: your-image-name
    volumes:
      - ./build/artifacts:/artifacts  # 挂载本地制品目录
      - app-static-volume:/target     # 挂载目标卷
    environment:
      - ARTIFACT_PATH="/artifacts/frontend-build.tar.gz"
      - TARGET_VOLUME_PATH="/static"
      - UNCOMPRESS_FORMAT="tar"
    restart: "no"  # 执行完成后自动退出

  web-app:
    image: nginx:alpine
    volumes:
      - app-static-volume:/usr/share/nginx/html  # 读取卷中展开的静态文件
    ports:
      - "80:80"
    depends_on:
      - artifact-expander  # 确保文件展开完成后启动应用

注意事项

1. 确保目标卷已提前创建（通过docker volume create或Compose定义）
2. 制品文件需具备可读权限，避免因权限不足导致处理失败
3. 大文件处理时建议增加--memory限制（如docker run --memory=512m）
4. 若使用第三方卷驱动，需确保驱动支持文件写入操作

常见问题

• Q：制品解压后文件权限异常？
  A：可通过添加-e FILE_PERMISSIONS="644"环境变量自定义文件权限（需镜像支持）。

• Q：如何处理多个制品文件？
  A：目前支持单制品处理，多制品场景建议通过脚本批量调用或扩展镜像功能。