HAProxy Docker镜像文档

镜像概述与主要用途

本镜像是一个通用的HAProxy Docker镜像，可用于非EEA相关项目。基于Debian Bullseye系统，集成HAProxy 2.9版本，默认暴露5000端口，提供高性能的TCP/HTTP负载均衡与反向代理能力。

核心功能与特性

• 基础环境：基于Debian Bullseye，HAProxy 2.9稳定版
• 自动配置：通过环境变量动态生成HAProxy配置文件，无需手动编写
• 动态后端：支持DNS解析后端服务器（通过DNS_ENABLED），适配动态服务发现场景（如Docker Swarm、Kubernetes）
• 健康检查：内置HTTP健康检查机制，支持自定义检查路径与参数
• 统计监控：提供Web统计页面，支持身份验证，实时监控后端状态
• 配置热重载：支持不重启容器重载配置文件
• 多版本支持：提供多个稳定不可变标签，适配不同HAProxy版本需求

使用场景与适用范围

• Web应用负载均衡：为多实例Web服务提供请求分发，提升可用性与吞吐量
• 微服务反向代理：作为微服务架构的入口，实现请求路由与负载均衡
• 容器集群负载：适配Docker Compose、Rancher等容器编排工具，动态发现并负载后端容器
• 高可用架构：配合Keepalived等工具实现负载均衡器自身的高可用
• 快速原型验证：通过环境变量快速配置后端，无需编写复杂配置文件

支持的标签与版本

最新标签

• :latest Dockerfile
  • 基础系统：Debian Bullseye
  • HAProxy版本：2.9

稳定不可变标签

更多历史版本见旧版本列表

安装前提

1. 安装Docker
2. 安装Docker Compose

使用方法

Docker Compose部署

以下是使用eeacms/haproxy镜像的基础docker-compose.yml示例：

version: "2"
services:
  haproxy:
    image: eeacms/haproxy
    depends_on:
      - webapp
    ports:
      - "80:5000"    # 前端服务端口映射
      - "1936:1936"  # 统计页面端口映射
    environment:
      BACKENDS: "webapp"         # 后端服务名称（与下方webapp服务对应）
      DNS_ENABLED: "true"        # 启用DNS解析后端
      LOG_LEVEL: "info"          # 日志级别

  webapp:
    image: eeacms/hello          # 示例后端服务

服务扩展：可通过docker-compose scale扩展后端实例数量：

$ docker-compose up -d --scale webapp=4  # 将webapp扩展至4个实例

验证：

• 访问http://localhost，多次刷新可观察后端服务器IP变化（负载均衡效果）
• 访问http://localhost:1936查看统计页面，默认登录凭据为admin:admin（通过STATS_AUTH配置）

注意：由于DNS_TTL默认值限制，后端服务可能需要最多1分钟完成自动发现。

通过环境变量指定后端

使用BACKENDS环境变量快速启动容器，直接指定后端服务器列表：

# 静态IP后端示例
$ docker run --env BACKENDS="192.168.1.5:80 192.168.1.6:80" eeacms/haproxy

# DNS动态解析后端示例（适用于Rancher等动态服务发现场景）
$ docker run --link=webapp -e BACKENDS="webapp" -e DNS_ENABLED=true eeacms/haproxy

• BACKENDS格式：server_ip:port，多服务器用空格分隔（需用引号包裹）
• DNS_ENABLED=true：启用DNS解析，当后端存在多个DNS记录时（如容器集群），会负载所有解析结果

使用自定义配置文件

通过挂载卷加载自定义haproxy.cfg：

$ docker run -v /本地路径/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg eeacms/haproxy:latest

配置热重载：修改配置后无需重启容器，可通过以下命令重载：

$ docker exec <容器名称> reload  # <容器名称>为实际运行的HAProxy容器名

扩展镜像自定义配置

通过Dockerfile扩展基础镜像，内置自定义配置：

FROM eeacms/haproxy:latest
COPY ./conf.d/haproxy.cfg /usr/local/etc/haproxy/haproxy.cfg  # 复制自定义配置
# 可选：添加额外依赖
# RUN apt-get update && apt-get install -y <依赖包>

构建并运行自定义镜像：

$ docker build -t my-haproxy:v1 .  # 构建镜像
$ docker run my-haproxy:v1         # 运行自定义镜像

配置参数与环境变量

日志配置

默认行为

容器内置rsyslog服务，日志默认输出至容器日志（UDP 127.0.0.1:514），默认日志级别为notice（仅记录重要事件）。

自定义配置

• 调整日志级别：通过LOG_LEVEL环境变量设置，如LOG_LEVEL=info
• 自定义日志输出：通过LOGGING环境变量指定外部日志服务器，如LOGGING=logs.example.com:5005（需确保目标服务器监听UDP对应端口）

版权与许可

• 原始代码所有者：欧洲环境署（EEA）
• 许可协议：GNU通用公共许可证（GPL）v2或更高版本
• 源码地址：github.com/eea/eea.docker.haproxy
• 变更日志：CHANGELOG.md

资助

本项目由欧洲环境署（EU）资助。