Appearance
HAProxy 完全指南
一份面向产品团队和开发者的 HAProxy 知识文档，涵盖核心概念、配置实践与运维要点。
💡 适用版本：HAProxy 2.0+（涵盖 2.4 / 2.6 / 2.8 LTS）
1. 概述
1.1 什么是 HAProxy？
HAProxy（High Availability Proxy）是一款开源的、高性能的 TCP/HTTP 反向代理和负载均衡器。它采用单进程、事件驱动、非阻塞架构，能够在极低资源消耗下稳定处理海量并发连接（单机轻松支撑数万至数十万并发），是互联网基础设施中极其成熟可靠的组件。
1.2 核心功能速览
| 功能模块 | 具体能力 |
|---|---|
| 负载均衡 | 支持轮询（roundrobin）、最少连接（leastconn）、源 IP 哈希（source）、URI 哈希等多种算法 |
| 健康检查 | 主动探测后端服务状态，自动隔离故障节点，恢复后无缝加入 |
| 7 层路由 | 基于 URL 路径、HTTP 头部、Cookie、请求方法等条件进行精细化流量分发 |
| 会话保持 | 通过 Cookie 注入或源 IP 哈希，确保同一用户的请求始终落到同一后端 |
| SSL/TLS 卸载 | 在代理层集中处理 HTTPS 加密解密，减轻后端压力 |
| 高可用支持 | 配合 Keepalived 实现主备热切换，消除单点故障 |
| 广泛协议支持 | 既支持 HTTP/HTTPS，也支持 TCP 原生代理（MySQL、Redis、SMTP 等） |
1.3 典型应用场景
- Web 应用负载均衡：将海量用户请求分发到多台 Web 服务器，提升吞吐量与可用性
- 微服务网关 / K8s Ingress：作为 Kubernetes 集群的入口控制器，实现基于域名和路径的路由
- 数据库 / 缓存代理：为 MySQL、Redis、PostgreSQL 等提供连接负载均衡和故障转移
- API 网关：对外部 API 请求进行限流、认证前置、版本路由
- 服务网格数据面：充当 Sidecar 代理，处理服务间通信的负载均衡与熔断
2. 核心概念
理解 HAProxy 必须先掌握三个核心配置块：
2.1 frontend（前端）
定义客户端如何接入。它指定监听的 IP 地址和端口，并决定接收到的流量如何处理、匹配哪些规则后转发到哪个后端。
haproxy
frontend web_frontend
bind *:80
mode http
default_backend app_backend2.2 backend（后端）
定义一组真实服务器（称为 server），并配置负载均衡算法、健康检查策略和会话保持方式。
haproxy
backend app_backend
mode http
balance roundrobin
option httpchk GET /health
server web1 192.168.1.10:8080 check
server web2 192.168.1.11:8080 check2.3 listen（监听）
listen 是 frontend + backend 的简化组合写法，适用于简单场景（如单一端口代理到一组后端）。
haproxy
listen mysql_cluster
bind *:3306
mode tcp
balance leastconn
server db1 10.0.0.1:3306 check
server db2 10.0.0.2:3306 check3. 负载均衡算法详解
HAProxy 支持多种算法，选择哪种取决于业务特点：
| 算法 | 关键字 | 适用场景 |
|---|---|---|
| 轮询 | roundrobin | 服务器性能相近，请求均匀分发（默认，支持动态调整权重） |
| 最少连接 | leastconn | 长连接场景（如数据库连接、WebSocket），分配给当前活跃连接数最少的后端 |
| 源 IP 哈希 | source | 会话保持需求，同一来源 IP 始终去往同一后端（适用于无 Cookie 场景） |
| URI 哈希 | uri | 缓存友好，相同 URI 请求命中同一后端，提高缓存命中率 |
| URL 参数哈希 | url_param | 根据 URL 中指定参数（如 user_id）做哈希分发 |
| 随机 | random | 配合 hash-balance-factor 可实现近似均匀分布，适合大规模后端池 |
示例：
haproxy
backend myapp
balance leastconn # 长连接场景优先
# balance source # 如需会话保持可切换
server app1 10.0.0.1:8080 check
server app2 10.0.0.2:8080 check4. 配置详解（实战级示例）
4.1 全局配置（global）
设置进程运行参数、日志、最大连接数、用户/组等。
haproxy
global
log /dev/log local0 # 日志输出到 syslog
maxconn 40000 # 单进程最大连接数
user haproxy
group haproxy
daemon # 后台运行
stats socket /var/run/haproxy.sock mode 600 level admin # 管理接口
tune.ssl.default-dh-param 20484.2 默认配置（defaults）
为 frontend、backend 和 listen 提供默认值，减少重复配置。
haproxy
defaults
mode http
log global
option httplog # 记录 HTTP 请求详细日志
option dontlognull # 不记录空连接
retries 3
timeout connect 5000ms # 连接后端超时
timeout client 50000ms # 客户端空闲超时
timeout server 50000ms # 服务端空闲超时
errorfile 400 /etc/haproxy/errors/400.http
errorfile 503 /etc/haproxy/errors/503.http4.3 完整 Web 负载均衡实例
场景：对外提供 HTTPS 服务，将请求按 URL 路径分流到两套后端（API 和静态资源），并启用健康检查。
haproxy
global
log /dev/log local0
maxconn 30000
user haproxy
group haproxy
daemon
defaults
mode http
log global
option httplog
option dontlognull
retries 3
timeout connect 5s
timeout client 30s
timeout server 30s
# ---------- HTTPS 前端 ----------
frontend https_in
bind *:443 ssl crt /etc/ssl/certs/myapp.pem
reqadd X-Forwarded-Proto:\ https
default_backend api_servers
# 根据路径转发：静态资源去 static 后端
use_backend static_servers if { path_beg /static/ /images/ /css/ /js/ }
# ---------- API 后端 ----------
backend api_servers
balance roundrobin
option httpchk GET /api/health
server api1 192.168.1.10:8080 check rise 2 fall 3
server api2 192.168.1.11:8080 check rise 2 fall 3
server api3 192.168.1.12:8080 check rise 2 fall 3 backup # 备用节点
# ---------- 静态资源后端 ----------
backend static_servers
balance source # 源 IP 哈希，提高缓存命中率
option httpchk HEAD /index.html
server static1 192.168.1.20:80 check
server static2 192.168.1.21:80 check5. 健康检查配置
健康检查是保证高可用的关键，HAProxy 支持多种检查方式：
| 检查类型 | 配置方式 | 适用场景 |
|---|---|---|
| TCP 端口检查 | check（默认） | 仅检测端口是否监听 |
| HTTP 层检查 | option httpchk + http-check | 验证应用返回状态码（2xx/3xx 视为健康） |
| 自定义脚本检查 | external-check | 执行外部脚本，用于复杂业务校验 |
| 被动检查 | observe + error-limit | 通过观察请求失败次数被动判定健康状态 |
进阶示例：对 API 服务做精细检查——要求返回体包含特定字符串。
haproxy
backend api_backend
option httpchk GET /health
http-check expect string "OK"
server api1 10.0.0.1:8080 check inter 2000 rise 2 fall 3参数说明：
inter 2000：每 2 秒检查一次rise 2：连续成功 2 次标记为健康fall 3：连续失败 3 次标记为故障
6. ACL（访问控制列表）
ACL 是 HAProxy 7 层路由的核心，可以基于各种条件匹配请求，再决定转发策略。
常用 ACL 条件：
| 条件 | 示例 |
|---|---|
| 路径前缀 | { path_beg /api /v1 } |
| 路径后缀 | { path_end .jpg .png .css } |
| 域名 | { hdr(host) -i example.com } |
| HTTP 方法 | { method POST } |
| 请求头 | { hdr(user-agent) -i mobile } |
| 源 IP | { src 192.168.1.0/24 } |
| URL 参数 | { url_param(user_id) 12345 } |
实战场景：根据来源 IP 做灰度发布。
haproxy
frontend web
bind *:80
use_backend canary_backend if { src 10.0.10.0/24 } # 内网测试 IP 走灰度
default_backend prod_backend7. 会话保持（Sticky Sessions）
对于需要保持会话状态的应用（如购物车），可用以下方式实现：
方式一：Cookie 注入（推荐）
HAProxy 在首次响应时插入 SERVERID Cookie，后续请求据此路由。
haproxy
backend app
balance roundrobin
cookie SERVERID insert indirect nocache
server app1 10.0.0.1:80 cookie app1 check
server app2 10.0.0.2:80 cookie app2 check方式二：源 IP 哈希
haproxy
backend app
balance source
hash-type consistent # 一致性哈希，减少节点变动时重新映射
server app1 10.0.0.1:80 check
server app2 10.0.0.2:80 check8. 高可用架构（Keepalived 集成）
HAProxy 自身无主备机制，需配合 Keepalived 实现 VIP（虚拟 IP）漂移。
简单部署架构：
Keepalived 配置要点（主节点）：
vrrp_instance VI_1 {
state MASTER
interface eth0
virtual_router_id 51
priority 100
advert_int 1
authentication {
auth_type PASS
auth_pass 1234
}
virtual_ipaddress {
10.0.0.100/24
}
}备节点将
state改为BACKUP，priority降低（如 90）。
9. 监控与统计页面
HAProxy 内置统计页面，极大方便运维观察：
haproxy
frontend stats
bind *:8080
stats enable
stats uri /stats
stats refresh 10s
stats auth admin:password
stats show-legends
stats show-node访问 http://your-haproxy:8080/stats 即可看到每个 frontend/backend/server 的实时流量、连接数、健康状态等。
集成 Prometheus 监控：
- 通过
stats socket暴露指标，使用haproxy_exporter采集 - 或启用 Prometheus 内置端点（HAProxy 2.0+）：haproxy
frontend prometheus bind *:8404 http-request use-service prometheus-exporter if { path /metrics }
10. 性能调优建议
| 调优维度 | 建议 |
|---|---|
| 内核参数 | 调整 net.core.somaxconn、net.ipv4.ip_local_port_range、net.ipv4.tcp_tw_reuse 等 |
| 连接超时 | 根据业务设置合理的 timeout client/server，过短影响长连接，过长浪费资源 |
| 最大连接数 | maxconn 根据内存（约 1~2MB/连接）和业务量设定 |
| 线程模式 | HAProxy 2.0+ 支持多线程，通过 nbproc 和 cpu-map 绑定 CPU 核心 |
| 零拷贝 | 启用 tune.bufsize 和 tune.pipesize 提升大文件传输效率 |
| 日志采样 | 高并发时使用 log-sampler 降低日志量，避免 syslog 成为瓶颈 |
11. 常见问题排查
| 问题现象 | 可能原因 | 检查方法 |
|---|---|---|
| 后端健康检查失败 | 后端服务未启动/防火墙阻断 | curl 手工检查健康端点，查看 HAProxy 日志 "Health check failed" |
| 请求 503 错误 | 所有后端均不可用 | 检查 stats 页面服务器状态，检查 default_backend 是否正确 |
| 会话频繁丢失 | Cookie 未正确设置/哈希算法变动 | 确认 cookie 配置或 hash-type consistent |
| 高 CPU 占用 | 日志过多/SSL 握手密集 | 减少日志级别，启用 SSL 会话缓存 ssl.cachesize |
| 连接数耗尽 | maxconn 设置过低或后端响应慢 | 调大 maxconn，优化后端响应时间 |
12. 版本升级与维护
- 版本选择：生产环境建议使用最新 LTS（长期支持）版本，如 2.4 LTS 或 2.6 LTS
- 平滑重载：使用
haproxy -f /etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid)实现无缝加载新配置 - 配置检查：每次修改后执行
haproxy -c -f /etc/haproxy/haproxy.cfg验证语法
13. 企业实践案例
- DigitalOcean：将 HAProxy 作为其负载均衡即服务（LBaaS）的核心引擎，承载海量云租户流量
- Microsoft Yammer：运行超过 60,000 个 HAProxy 实例，峰值处理 45 万请求/秒
- Clover：利用 HAProxy 的权重路由实现"彩虹部署"，精准将不同客户流量导向不同版本
- DoubleVerify：从 F5 硬件迁移至 HAProxy，每日处理数十亿请求，显著降低 TCO
14. 快速参考卡片
| 操作 | 命令 |
|---|---|
| 启动 HAProxy | haproxy -f /etc/haproxy/haproxy.cfg |
| 平滑重载 | haproxy -f haproxy.cfg -sf $(pidof haproxy) |
| 检查配置语法 | haproxy -c -f haproxy.cfg |
| 查看统计页面 | 浏览器访问 http://haproxy_ip:8080/stats（需配置 stats） |
| 查看实时连接数 | echo "show info" | socat /var/run/haproxy.sock - |
| 查看服务器状态 | echo "show servers state" | socat /var/run/haproxy.sock - |
