graal-maven-docker 镜像文档

1. 镜像概述和主要用途

1.1 概述

graal-maven-docker 是一个基于 debian:buster-slim 轻量级基础镜像，通过 sdkman 包管理器集成 GraalVM 和 Maven 的 Docker 镜像。该镜像旨在提供一站式 Java 开发与构建环境，尤其优化了 GraalVM 原生镜像（Native Image）的构建能力。

1.2 主要用途

• 提供标准化的 Java 开发环境，简化依赖管理
• 支持通过 Maven 执行项目构建、测试及打包流程
• 集成 GraalVM native-image 工具，实现 Java 应用的原生镜像编译
• 适用于本地开发、CI/CD 流水线或容器化部署场景

2. 核心功能和特性

3. 使用场景和适用范围

3.1 典型场景

• Java 应用开发：作为本地开发环境，执行代码编译、单元测试等流程
• Maven 项目构建：通过容器化方式运行 mvn 命令，统一团队构建环境
• GraalVM 原生镜像构建：使用 native-image 工具将 Java 应用编译为原生二进制文件（提升启动速度、降低内存占用）
• CI/CD 集成：在持续集成流程中作为构建节点，执行自动化构建、测试及原生镜像打包

3.2 适用范围

• Java 开发者（需 GraalVM 或 Maven 环境）
• 需构建 GraalVM 原生镜像的应用（如微服务、命令行工具）
• 追求环境一致性的团队或 CI/CD 流程

4. 详细使用方法和配置说明

4.1 镜像获取

从 Docker 镜像仓库拉取镜像（具体标签需参考镜像仓库说明，如指定 GraalVM/Maven 版本）：

docker pull softinstigate/graal-maven-docker:latest

4.2 基础使用示例

4.2.1 启动交互式终端

进入容器内交互式 shell，用于手动执行命令或调试：

docker run -it --rm softinstigate/graal-maven-docker /bin/bash

4.2.2 执行 Maven 构建命令

挂载本地项目目录至容器，运行 Maven 命令（如打包项目）：

# 挂载当前目录到容器内 /app 路径，执行 mvn clean package
docker run --rm \
  -v "$(pwd)":/app \  # 挂载本地项目目录
  -w /app \            # 设置工作目录为 /app
  softinstigate/graal-maven-docker \
  mvn clean package    # Maven 构建命令

4.2.3 构建 GraalVM 原生镜像

通过 native-image 工具直接编译 JAR 包为原生可执行文件（需项目已打包为 JAR）：

docker run --rm \
  -v "$(pwd)":/app \
  -w /app \
  softinstigate/graal-maven-docker \
  native-image -jar target/your-app.jar  # 生成原生可执行文件 your-app

4.2.4 集成 Maven 原生插件构建

若项目中已集成 native-maven-plugin（GraalVM 官方 Maven 插件），可通过 Maven 命令触发原生镜像构建：

docker run --rm \
  -v "$(pwd)":/app \
  -w /app \
  softinstigate/graal-maven-docker \
  mvn package -Pnative  # 激活 native 配置文件，执行原生构建

4.3 配置说明

4.3.1 环境变量

容器默认配置以下环境变量（可通过 -e 参数覆盖）：

4.3.2 自定义 Maven 配置

挂载本地 Maven 配置文件（settings.xml）覆盖容器默认配置（如私服地址、镜像源）：

docker run --rm \
  -v "$(pwd)":/app \
  -v "$HOME/.m2/settings.xml":/root/.m2/settings.xml \  # 挂载本地 settings.xml
  -w /app \
  softinstigate/graal-maven-docker \
  mvn clean package

4.4 权限处理

容器默认以 root 用户运行，挂载本地目录时可能导致生成文件的权限为 root。可通过 --user 参数指定当前用户 ID 避免权限问题：

docker run --rm \
  -u "$(id -u):$(id -g)" \  # 使用当前用户 ID 运行容器
  -v "$(pwd)":/app \
  -w /app \
  softinstigate/graal-maven-docker \
  mvn clean package

5. 注意事项

• 镜像标签：不同标签对应不同版本的 GraalVM 和 Maven，使用前需查阅镜像仓库（如 Docker Hub）的标签说明，选择匹配版本（例如 graalvm-22.3.1_maven-3.8.6）。
• 原生镜像依赖：构建 GraalVM 原生镜像时可能需要系统库（如 libz、glibc），若提示依赖缺失，可在容器内通过 apt 安装（需 root 权限）：

  docker run -it --rm softinstigate/graal-maven-docker /bin/bash
  apt update && apt install -y zlib1g-dev  # 示例：安装 zlib 开发库
  

• 资源限制：原生镜像构建耗资源，建议通过 --memory 和 --cpus 参数限制容器资源（如 --memory 4g --cpus 2）。