haproxy: 镜像文档

镜像概述和主要用途

本镜像基于官方 haproxy:<sameTag> 构建，继承了 HAProxy 的全部功能特性。HAProxy 是一款高性能的 TCP/HTTP 负载均衡器和代理服务器，主要用于在多个后端服务实例之间分发网络流量，实现流量调度、服务高可用保障和性能优化。适用于需要提升服务可用性、扩展服务处理能力的场景。

核心功能和特性

核心功能

• 多协议支持：同时支持 TCP 层（四层）和 HTTP 层（七层）负载均衡
• 灵活负载均衡算法：包括轮询（roundrobin）、加权轮询（weighted roundrobin）、源IP哈希（source）、URI哈希（uri）等
• 健康检查机制：自动检测后端服务健康状态，剔除异常节点并在恢复后重新纳入
• 会话持久性：支持基于 Cookie、源IP 等方式的会话保持
• SSL/TLS 终止：提供 HTTPS 终端服务，卸载后端服务的加密/解密负载

主要特性

• 高性能：低资源消耗，单机可处理数十万并发连接
• 高可靠性：支持热配置重载，配置更新无需重启服务
• 扩展性：支持自定义配置文件，灵活适配复杂业务场景
• HTTP 高级功能：支持请求重写、重定向、压缩、缓存控制等
• 监控能力：内置 stats 页面，提供实时流量和后端状态监控

使用场景和适用范围

典型使用场景

• Web 服务负载均衡：在多个 Web 服务器间分发 HTTP/HTTPS 请求
• API 网关：作为微服务架构的入口，统一处理认证、限流、路由
• 数据库读写分离：基于请求类型分发读写流量至不同数据库节点
• 高可用集群：配合 Keepalived 实现负载均衡器自身的高可用部署

适用范围

• 中小型企业服务集群流量调度
• 大型分布式系统的流量入口层
• 开发/测试环境的服务代理和流量模拟
• 需要实现服务高可用和横向扩展的业务场景

使用方法和配置说明

配置文件基础结构

HAProxy 核心配置通过 haproxy.cfg 文件定义，主要包含以下配置段：

# 全局配置
global
    log /dev/log local0 info
    maxconn 4096
    daemon

# 默认配置
defaults
    mode http
    log global
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

# 前端配置（接收客户端请求）
frontend http_front
    bind *:80
    default_backend http_back

# 后端配置（定义后端服务集群）
backend http_back
    balance roundrobin  # 使用轮询算法
    server web1 192.168.1.10:80 weight 3  # 后端服务1，权重3
    server web2 192.168.1.11:80 weight 1  # 后端服务2，权重1
    server web3 192.168.1.12:80 backup   # 备份服务，仅在主服务全部异常时启用

Docker 运行命令示例

基础运行（挂载自定义配置文件）

docker run -d \
  --name haproxy \
  -p 80:80 \
  -v /host/path/to/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \
  haproxy:<sameTag>

带监控页面的运行（暴露 stats 页面）

1. 配置文件中添加 stats 配置：

listen stats
    bind *:1936
    stats enable
    stats uri /haproxy-stats
    stats auth admin:admin123  # 监控页面认证

2. 运行命令（映射监控端口）：

docker run -d \
  --name haproxy \
  -p 80:80 \
  -p 1936:1936 \
  -v /host/path/to/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \
  haproxy:<sameTag>

Docker Compose 配置示例

version: '3'
services:
  haproxy:
    image: haproxy:<sameTag>
    container_name: haproxy
    restart: always
    ports:
      - "80:80"       # HTTP 服务端口
      - "443:443"     # HTTPS 服务端口（如需）
      - "1936:1936"   # 监控页面端口
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
      - ./ssl:/etc/haproxy/ssl:ro  # SSL 证书目录（如需）
    networks:
      - backend-network

networks:
  backend-network:
    driver: bridge

配置重载

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

docker exec haproxy haproxy -f /usr/local/etc/haproxy/haproxy.cfg -c  # 验证配置
docker exec haproxy haproxy -f /usr/local/etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid)  # 重载配置

环境变量说明

本镜像本身不依赖固定环境变量，但可通过环境变量动态注入配置参数。例如，可结合 envsubst 实现配置文件模板化：

1. 创建配置模板文件 haproxy.template.cfg，包含变量占位符：

backend http_back
    balance roundrobin
    server web1 ${BACKEND_WEB1}:80 weight 3
    server web2 ${BACKEND_WEB2}:80 weight 1

2. 运行容器时注入环境变量并生成配置：

docker run -d \
  --name haproxy \
  -e BACKEND_WEB1=192.168.1.10 \
  -e BACKEND_WEB2=192.168.1.11 \
  -v $(pwd)/haproxy.template.cfg:/tmp/haproxy.template.cfg \
  haproxy:<sameTag> \
  sh -c "envsubst < /tmp/haproxy.template.cfg > /usr/local/etc/haproxy/haproxy.cfg && haproxy -f /usr/local/etc/haproxy/haproxy.cfg"