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 格式，具体版本可通过 Docker Hub 标签页 查看。常用标签说明：

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

5. 使用方法和配置说明

5.1 基本使用（docker run）

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

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）自定义测试行为：

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 选项传递环境变量，动态配置测试参数（如目标服务地址、端口等）：

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 + 被测服务）：

version: '3.8'
services:
  jmeter:
    image: 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: 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 仓库：alpine-docker/jmeter（源码及构建脚本）
• Docker Hub 镜像：alpine/jmeter（镜像下载及标签信息）
• 构建日志：CircleCI 流水线（查看镜像构建过程）
• JMeter 官方文档：Apache JMeter User Manual（测试计划编写及参数说明）