alpine/jmeter

docker-jmeter 镜像文档

1. 镜像概述和主要用途

alpine/jmeter 是基于 Alpine Linux 构建的轻量级 Docker 镜像，用于在容器环境中运行 Apache JMeter 性能测试工具。该镜像旨在提供便捷、一致的性能测试环境，支持多架构部署，适用于自动化测试流程与 CI/CD 集成。镜像同步跟进 JMeter 官方稳定版本，确保功能完整性与安全性。

2. 核心功能和特性

• 多架构支持：兼容 amd64、arm64 等主流架构，满足不同硬件环境需求。
• 轻量级设计：基于 Alpine Linux 构建，镜像体积小（通常比官方 Debian 基础镜像小 50% 以上），启动速度快。
• 版本同步：及时跟进 JMeter 官方版本更新，提供稳定的标签化版本（如 5.6-alpine、latest）。
• 灵活集成：支持挂载外部测试脚本、配置文件及结果目录，便于测试用例管理与结果持久化。

3. 使用场景和适用范围

• 自动化性能测试：集成至 CI/CD 流水线（如 Jenkins、GitLab CI），在应用发布前自动执行负载测试。
• 多环境一致性测试：确保开发、测试、生产环境中性能测试结果的一致性，消除环境差异影响。
• 临时负载测试：快速部署独立的 JMeter 环境，用于即时性能评估或问题排查。
• 资源受限环境：轻量级特性适合在边缘设备、嵌入式系统或资源紧张的服务器中运行。

4. 镜像标签说明

镜像标签遵循 [jmeter-version]-alpine 格式，具体版本可通过 https://hub.docker.com/r/alpine/jmeter/tags/ 查看。常用标签说明：

• latest：对应 JMeter 最新稳定版本，自动更新。
• 5.6-alpine：指定 JMeter 5.6 版本，基于 Alpine 构建（推荐生产环境使用固定版本标签以确保稳定性）。

5. 使用方法和配置说明

5.1 基本使用（docker run）

JMeter 通常以非 GUI 模式运行，基本命令格式如下：

bash
docker run --rm \
  -v $(pwd)/tests:/jmeter/tests \  # 挂载本地测试脚本目录至容器内 /jmeter/tests
  -v $(pwd)/results:/jmeter/results \  # 挂载结果输出目录
  alpine/jmeter:5.6-alpine \  # 指定镜像及版本
  -n -t /jmeter/tests/test-plan.jmx \  # -n: 非GUI模式；-t: 指定测试计划文件
  -l /jmeter/results/test-result.jtl \  # -l: 生成结果日志（JTL格式）
  -e -o /jmeter/results/html-report  # -e -o: 生成HTML测试报告

参数说明：

• --rm：测试完成后自动删除容器，避免残留。
• -v：挂载本地目录至容器，实现测试脚本、配置文件的外部管理及结果持久化。
• JMeter 核心参数：-n（非 GUI 模式）、-t（指定 .jmx 测试计划）、-l（结果日志输出）、-e -o（生成 HTML 报告）。

5.2 自定义 JMeter 配置

通过挂载 JMeter 配置文件（如 user.properties、system.properties）自定义测试行为：

bash
docker run --rm \
  -v $(pwd)/user.properties:/jmeter/bin/user.properties \  # 挂载自定义用户属性
  -v $(pwd)/tests:/jmeter/tests \
  alpine/jmeter \
  -n -t /jmeter/tests/test.jmx \
  -Juser.properties=/jmeter/bin/user.properties  # 通过 -J 传递系统属性，指定配置文件路径

说明：user.properties 可配置 JMeter 全局参数（如线程数、超时时间等），通过 -J 覆盖默认配置。

5.3 环境变量注入

通过 -e 选项传递环境变量，动态配置测试参数（如目标服务地址、端口等）：

bash
docker run --rm \
  -e TARGET_HOST=api.example.com \  # 注入目标服务地址
  -e TARGET_PORT=8080 \  # 注入目标服务端口
  -v $(pwd)/tests:/jmeter/tests \
  alpine/jmeter \
  -n -t /jmeter/tests/test.jmx \
  -Jtarget.host=${TARGET_HOST} \  # 将环境变量传递给 JMeter
  -Jtarget.port=${TARGET_PORT}

在测试计划中引用：在 JMeter 测试计划（.jmx）中通过 ${__P(target.host)} 或 ${__env(TARGET_HOST)} 引用环境变量。

5.4 docker-compose 配置示例

创建 docker-compose.yml 实现多服务协同测试（如 JMeter + 被测服务）：

yaml
version: '3.8'
services:
  jmeter:
    image: docker.xuanyuan.run/alpine/jmeter:5.6-alpine
    volumes:
      - ./tests:/jmeter/tests       # 测试脚本目录
      - ./results:/jmeter/results   # 结果输出目录
      - ./user.properties:/jmeter/bin/user.properties  # 自定义配置
    environment:
      - TARGET_HOST=app  # 被测服务在 compose 网络中的服务名
      - TARGET_PORT=8080
    command: >
      -n -t /jmeter/tests/load-test.jmx
      -l /jmeter/results/load-result.jtl
      -e -o /jmeter/results/load-report
    depends_on:
      - app  # 确保被测服务启动后再执行测试

  app:  # 被测服务示例（需替换为实际服务配置）
    image: docker.xuanyuan.run/my-app:latest
    ports:
      - "8080:8080"

6. 注意事项

• 目录权限：容器内默认以非 root 用户运行，挂载本地目录时需确保权限充足，可通过 --user $(id -u):$(id -g) 指定当前用户 ID 避免权限问题。
• 网络配置：测试本地主机服务时，Linux 环境可使用 --network host 共享主机网络；Windows/Mac 环境使用 host.docker.internal 访问主机 IP。
• 资源限制：性能测试可能消耗大量 CPU/内存，建议通过 --memory=4g --cpus=2 限制容器资源，避免影响主机稳定性。

7. 相关资源

• GitHub 仓库：https://github.com/alpine-docker/jmeter%EF%BC%88%E6%BA%90%E7%A0%81%E5%8F%8A%E6%9E%84%E5%BB%BA%E8%84%9A%E6%9C%AC%EF%BC%89
• Docker Hub 镜像：https://hub.docker.com/r/alpine/jmeter%EF%BC%88%E9%95%9C%E5%83%8F%E4%B8%8B%E8%BD%BD%E5%8F%8A%E6%A0%87%E7%AD%BE%E4%BF%A1%E6%81%AF%EF%BC%89
• 构建日志：https://app.circleci.com/pipelines/github/alpine-docker/jmeter%EF%BC%88%E6%9F%A5%E7%9C%8B%E9%95%9C%E5%83%8F%E6%9E%84%E5%BB%BA%E8%BF%87%E7%A8%8B%EF%BC%89
• JMeter 官方文档：https://jmeter.apache.org/usermanual/index.html%EF%BC%88%E6%B5%8B%E8%AF%95%E8%AE%A1%E5%88%92%E7%BC%96%E5%86%99%E5%8F%8A%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E%EF%BC%89