compose-unpacker 镜像文档

镜像概述和主要用途

compose-unpacker 是 Portainer 提供的专用工具镜像，用于从 Git 仓库获取 Docker Compose 堆栈配置，并自动部署到远程环境。该工具旨在简化基于 Git 版本控制的 Compose 堆栈部署流程，实现配置即代码（Configuration as Code）理念，支持远程环境（如 Docker Engine、Kubernetes 集群等）的自动化部署与更新。

核心功能和特性

核心功能

• Git 仓库集成：支持通过 HTTP/HTTPS、SSH 协议拉取 Git 仓库中的 Compose 配置文件。
• Compose 文件处理：自动解析仓库中的 Compose 文件（支持 v2、v3 格式），支持环境变量替换和模板渲染。
• 远程环境部署：对接 Portainer 管理的远程环境，执行 Compose 堆栈的创建、更新或删除操作。
• 版本控制支持：可指定 Git 分支、标签或提交哈希，部署特定版本的 Compose 配置。

关键特性

• 多协议认证：支持 Git 仓库的 SSH 密钥认证、HTTP 基本认证（用户名/密码）及令牌认证（如 GitHub Personal Access Token）。
• 部署策略配置：支持覆盖现有堆栈、保留数据卷、忽略未变更配置等精细化部署策略。
• 轻量级设计：基于 Alpine 基础镜像，体积小，资源占用低，适合嵌入 CI/CD 流水线或边缘设备。
• 日志与审计：输出详细部署日志，支持与 Portainer 审计系统集成，追踪配置变更记录。

使用场景和适用范围

典型使用场景

• CI/CD 流水线集成：在代码提交或合并后，自动触发 compose-unpacker 从 Git 拉取最新配置并部署到测试/生产环境。
• 多环境一致性部署：通过同一 Git 仓库管理开发、测试、生产环境的 Compose 配置，确保环境一致性。
• 远程设备批量更新：对边缘计算设备、分布式节点，通过 Git 集中管理 Compose 配置，实现批量部署与更新。
• 团队协作管理：开发团队通过 Git 协作维护 Compose 配置，由 compose-unpacker 自动同步至运行环境。

适用范围

• 支持 Portainer 管理的所有远程环境：Docker Standalone、Docker Swarm、Kubernetes。
• 支持标准 Docker Compose v2/v3 语法的配置文件。
• 兼容主流 Git 服务：GitHub、GitLab、Bitbucket、Gitea 及自建 Git 服务器。

使用方法和配置说明

环境准备

1. 已安装 Docker 引擎（20.10+）或 Docker Compose（v2+）。
2. 已部署 Portainer 实例，并添加目标远程环境（获取环境 ID 及访问令牌）。
3. Git 仓库中存放有效的 Compose 文件（如 docker-compose.yml）。

Docker 部署示例

1. 基础 docker run 命令

bash
docker run -d \
  --name compose-unpacker \
  -e PORTAINER_URL="[***]" \
  -e PORTAINER_TOKEN="pt_xxxxxx" \
  -e GIT_REPO_URL="[***]" \
  -e GIT_BRANCH="main" \
  -e REMOTE_ENV_ID="1" \
  -e COMPOSE_FILE_PATH="stacks/prod/docker-compose.yml" \
  -v /path/to/ssh-key:/root/.ssh/id_rsa:ro \  # 若使用 SSH 认证
  portainer/compose-unpacker:latest

2. Docker Compose 配置示例

yaml
version: '3.8'
services:
  compose-unpacker:
    image: portainer/compose-unpacker:latest
    container_name: compose-unpacker
    environment:
      # Portainer 连接配置
      PORTAINER_URL: "[***]"  # Portainer 实例 URL（必填）
      PORTAINER_TOKEN: "pt_xxxxxx"                   # Portainer 访问令牌（必填，需具备环境管理权限）
      
      # Git 仓库配置
      GIT_REPO_URL: "***:example/compose-stacks.git"  # Git 仓库 URL（必填，支持 HTTP/SSH）
      GIT_BRANCH: "main"                                         # 分支/标签/提交哈希（可选，默认 main）
      GIT_SSH_KEY_PATH: "/root/.ssh/id_rsa"                      # SSH 密钥路径（可选，用于 SSH 认证）
      GIT_USERNAME: "git-user"                                   # HTTP 用户名（可选，用于 HTTP 认证）
      GIT_PASSWORD: "git-pass"                                   # HTTP 密码/令牌（可选，用于 HTTP 认证）
      
      # 部署目标配置
      REMOTE_ENV_ID: "1"                                         # Portainer 远程环境 ID（必填，在 Portainer 环境列表中查看）
      COMPOSE_FILE_PATH: "docker-compose.yml"                    # 仓库内 Compose 文件路径（可选，默认根目录 docker-compose.yml）
      
      # 部署策略配置
      DEPLOY_STRATEGY: "replace"                                 # 部署策略（可选：replace/merge，默认 replace）
      KEEP_VOLUMES: "true"                                       # 是否保留数据卷（可选：true/false，默认 true）
      SKIP_TLS_VERIFY: "false"                                   # 是否跳过 Portainer TLS 验证（可选：true/false，默认 false）
    volumes:
      - /local/path/to/ssh-key:/root/.ssh/id_rsa:ro  # 挂载 SSH 密钥（若使用 SSH 认证）
    restart: unless-stopped

核心配置参数详解

环境变量（必填项）

环境变量（可选项）

部署流程说明

1. 拉取 Git 仓库：根据 GIT_REPO_URL 及认证信息克隆仓库，切换至 GIT_BRANCH 指定版本。
2. 解析 Compose 文件：读取 COMPOSE_FILE_PATH 路径的文件，处理环境变量替换（若文件中包含 ${VAR} 格式变量）。
3. 连接 Portainer：通过 PORTAINER_URL 和 PORTAINER_TOKEN 认证 Portainer 实例。
4. 部署至远程环境：根据 REMOTE_ENV_ID 定位目标环境，按 DEPLOY_STRATEGY 执行堆栈部署/更新。
5. 输出部署结果：日志中返回部署状态（成功/失败）及堆栈 ID，失败时输出详细错误信息。

注意事项

• Portainer 权限：PORTAINER_TOKEN 需关联具备“环境管理”和“堆栈管理”权限的用户。
• Git 认证优先级：SSH 认证（GIT_SSH_KEY_PATH）优先于 HTTP 认证（GIT_USERNAME/GIT_PASSWORD）。
• Compose 兼容性：仅支持 Docker Compose v2/v3 语法，不兼容 v1。
• 网络要求：容器需能访问 Portainer 实例、Git 仓库及目标远程环境（网络策略需放行对应端口）。