haproxytech/haproxy-qns

HAProxy QUIC 互操作性测试镜像文档

一、镜像概述和主要用途

本镜像为 HAProxy 的 QUIC 协议互操作性测试提供标准化运行环境，包含预配置的 HAProxy 实例、常用互操作性测试工具及可复现的测试场景。主要用途是简化 HAProxy 与其他 QUIC 协议实现（客户端/服务端）的兼容性验证流程，支持快速部署、执行及分析 QUIC 互操作性测试。

二、核心功能和特性

核心功能

• 预配置 HAProxy 环境，默认启用 QUIC/HTTP/3 支持
• 集成 QUIC 互操作性测试工具（如 quic-interop-runner、h3-client 等）
• 内置多种标准化测试场景（基础连接建立、流多路复用、流量控制、版本协商等）
• 支持测试结果自动记录与导出

特性

• 轻量级：基于 Alpine 基础镜像，镜像体积小
• 可定制：支持自定义 HAProxy 配置、测试参数及场景
• 可复现：固定版本依赖，确保测试环境一致性
• 多模式：支持客户端模式（测试 HAProxy 服务端）和服务端模式（测试 HAProxy 客户端）

三、使用场景和适用范围

使用场景

• HAProxy QUIC 协议实现的兼容性验证（与主流 QUIC 客户端/服务端）
• 不同 QUIC 版本（如 RFC 9000、draft-32 等）及扩展的互操作性测试
• QUIC 连接建立、数据传输、关闭等关键流程的功能验证
• 高并发场景下的 QUIC 性能基准测试（吞吐量、延迟、连接复用等）

适用范围

• HAProxy 开发者（验证 QUIC 功能迭代的兼容性）
• 网络协议测试工程师（自动化 QUIC 互操作性测试流程）
• QUIC 协议研究人员（快速对比不同实现的行为差异）

四、详细使用方法和配置说明

4.1 获取镜像

4.1.1 从 Docker Hub 拉取（推荐）

bash
docker pull haproxytech/quic-interop-test:latest

4.1.2 本地构建

bash
# 克隆仓库
git clone https://github.com/haproxytech/quic-interop-test.git
cd quic-interop-test
# 构建镜像
docker build -t haproxy-quic-interop-test:local .

4.2 基本使用

4.2.1 启动容器（默认配置）

bash
docker run -d \
  --name haproxy-quic-test \
  -p 443:443/udp  # QUIC 标准端口 \
  -p 8080:8080/tcp  # 测试状态监控端口 \
  haproxytech/quic-interop-test:latest

4.2.2 查看测试日志

bash
docker logs -f haproxy-quic-test

4.3 测试场景示例

4.3.1 客户端模式（测试 HAProxy 服务端与外部 QUIC 客户端的互操作性）

bash
docker run -d \
  --name haproxy-quic-server-test \
  -p 443:443/udp \
  -e TEST_MODE=server \  # 启用服务端模式
  -e CLIENT_ADDR=192.168.1.100:4433 \  # 外部 QUIC 客户端地址
  -v ./custom-haproxy.cfg:/etc/haproxy/haproxy.cfg \  # 挂载自定义 HAProxy 配置
  haproxytech/quic-interop-test:latest

4.3.2 服务端模式（测试 HAProxy 客户端与外部 QUIC 服务端的互操作性）

bash
docker run -d \
  --name haproxy-quic-client-test \
  -e TEST_MODE=client \  # 启用客户端模式
  -e SERVER_ADDR=192.168.1.200:443 \  # 外部 QUIC 服务端地址
  -v ./test-results:/tmp/test-results \  # 持久化测试结果
  haproxytech/quic-interop-test:latest

4.4 配置说明

4.4.1 环境变量

4.4.2 卷挂载

• 配置文件挂载：通过 -v /host/path/to/haproxy.cfg:/etc/haproxy/haproxy.cfg 自定义 HAProxy 配置（如 QUIC 版本、流控参数等）。
• 测试结果持久化：通过 -v /host/path/to/results:/tmp/test-results 将测试日志、性能数据导出到宿主机。

4.4.3 端口映射

4.5 自定义测试参数

通过修改 HAProxy 配置文件（默认路径 /etc/haproxy/haproxy.cfg）调整 QUIC 测试参数，例如：

haproxy
# 示例：启用 QUIC 版本协商测试
frontend quic-test-frontend
  bind *:443 quic alpn h3-29,h3-30,h3  # 支持多个 ALPN 协商
  mode http
  default_backend quic-test-backend

backend quic-test-backend
  server test-server 127.0.0.1:8081
  http-response set-header Alt-Svc 'h3=":443"; ma=86400'  # 发送 Alt-Svc 头部

五、Docker 部署方案示例

5.1 docker run 完整示例（自定义配置+结果持久化）

bash
docker run -d \
  --name haproxy-quic-custom-test \
  -p 443:443/udp \
  -p 8080:8080/tcp \
  -e TEST_MODE=server \
  -e LOG_LEVEL=debug \
  -e RESULT_EXPORT_PATH=/tmp/results \
  -v $(pwd)/my-haproxy.cfg:/etc/haproxy/haproxy.cfg \  # 挂载自定义配置
  -v $(pwd)/test-output:/tmp/results \  # 持久化测试结果
  haproxytech/quic-interop-test:latest

5.2 docker-compose 配置示例

yaml
version: '3.8'
services:
  haproxy-quic-test:
    image: haproxytech/quic-interop-test:latest
    container_name: haproxy-quic-test
    ports:
      - "443:443/udp"
      - "8080:8080/tcp"
    environment:
      - TEST_MODE=client
      - SERVER_ADDR=quic-server:443  # 连接 compose 网络内的 quic-server 服务
      - LOG_LEVEL=info
      - RESULT_EXPORT_PATH=/tmp/results
    volumes:
      - ./haproxy-config:/etc/haproxy  # 挂载配置目录
      - ./test-results:/tmp/results    # 挂载结果目录
    networks:
      - quic-test-net
    depends_on:
      - quic-server  # 依赖外部 QUIC 服务端（示例）

  quic-server:  # 示例外部 QUIC 服务端（可替换为实际测试目标）
    image: nginx:latest  # 假设 nginx 已配置 QUIC 支持
    container_name: quic-server
    ports:
      - "443:443/udp"
    networks:
      - quic-test-net

networks:
  quic-test-net:
    driver: bridge

六、注意事项

• 镜像默认包含 HAProxy 开发版（支持 QUIC），生产环境需替换为稳定版本配置。
• QUIC 协议依赖 UDP 传输，确保宿主机/容器网络环境未屏蔽 UDP 端口。
• 高并发测试场景下建议调整宿主机 UDP 缓冲区大小（sysctl -w net.core.rmem_max=26214400）。
• 测试结果文件默认格式为 JSON，可通过 jq 工具解析分析（容器内已预装 jq）。