HAProxy 配置文件参数说明以及命令参数说明

河码匠2026-01-22 10:02

HAProxy（High Availability Proxy）是一款流行的开源软件，提供高可用性、负载均衡和 TCP 及 HTTP 应用的代理服务。由于其高性能、可靠性和灵活性，它被广泛使用

一、HAProxy 的核心功能

  1. 负载均衡

    • 支持多种负载均衡算法（如轮询、最少连接、源IP哈希等）。
    • 提升服务的性能和可用性，通过分发流量减少单点压力。

  2. 反向代理

    • 客户端通过 HAProxy 访问后端服务，隐藏后端真实 IP 地址，提高安全性。

  3. 高可用性

    • 配合健康检查机制，自动剔除故障节点。
    • 支持服务节点的动态上下线，保障服务可用性。

  4. 安全性

    • 支持 TLS/SSL 加密，保护敏感通信。
    • 可结合 ACL（访问控制列表）进行权限管控。

  5. 会话保持

    • 支持基于 cookie 或源 IP 的会话保持，保障用户请求一致性。

  6. 流量管理

    • 通过路由规则和 ACL，精准控制流量分发。
    • 提供限流、排队等功能，保护后端服务。

  7. 监控和统计

    • 提供内置的 Web 界面，实时监控流量和节点状态。

二、组件

  1. 前端（Frontend）

    • 接收客户端请求，决定将流量转发到哪个后端。
    • 可根据域名、路径、HTTP 头等进行规则匹配。

  2. 后端（Backend）

    • 定义后端服务器池及其负载均衡算法。
    • 配合健康检查功能，剔除异常的后端服务器。

  3. 服务器（Server）

    • 具体的后端服务器节点，可以是 Web 服务、数据库服务等。

  4. ACL（访问控制列表）

    • 根据规则匹配流量（如 IP、URL 路径、HTTP 方法），决定流量的路由或拒绝。

三、配置文件说明

复制代码 
global
    # 定义了日志记录的地址和级别
    log 127.0.0.1 local0 info

    # 将进程的根目录更改为指定目录，提高安全性
    chroot /containers/loadbalancer/xxxx/

    # 定义了统计信息的Unix套接字位置。
    # 通过这个套接字，你可以访问 HAProxy 的统计数据，包括连接数、会话数、错误率等，还可以进行一些管理操作，如启用或禁用服务器、调整参数等
    stats socket /containers/loadbalancer/xxxx/stats.sock

    # 指定运行 HAProxy 的用户和用户组。
    user haproxy
    group haproxy

    # 设置最大连接数为 100,000
    maxconn 100000

    # 调整最大接受连接数
    tune.maxaccept 100000

    # 设置默认的 DH 参数长度
    tune.ssl.default-dh-param 2048

    # 使 HAProxy 在后台运行
    daemon

    # 指定默认的 SSL 加密套件
    ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS

defaults
    # 不记录健康检查日志
    option dontlognull

    # 失败后重试 3 次。
    retries 3

    # 允许重新调度到其他服务器。
    option redispatch

    # 设置默认最大连接数为 100,000。
    maxconn 100000

    # 设置客户端连接超时时间为 50 秒。
    timeout client 50s

    # 设置服务器连接超时时间为 50 秒。
    timeout server 50s

    # 设置连接超时时间为 5 秒。
    timeout connect 5s

    # 设置隧道连接超时时间为 1 小时。
    timeout tunnel 1h

listen xxxx_443
    # 在所有 IPv4 和 IPv6 地址的 443 端口上监听。
    bind 0.0.0.0:443
    bind :::443

    # 设置为 TCP 模式。
    mode tcp

    # 使用轮询算法进行负载均衡。
    balance roundrobin

    # 禁用日志记录。
    no log

    # 设置客户端连接超时时间为 60 秒。
    timeout client 60s

    # 设置服务器连接超时时间为 60 秒。
    timeout server 60s

    # 定义了一个后端服务器，IP 为 10.1.16.58，端口为 443，权重为 10。健康检查间隔为 5000ms，连续 5 次成功认为服务器正常，连续 3 次失败认为服务器故障。
    server xxxx_443_vcir_443 10.1.16.58:443 weight 10 check inter 5000 rise 5 fall 3

# 定义一个名为xxxx_8445的监听器
listen xxxx_8445
    # 在所有IPv4地址的8445端口上监听
    bind 0.0.0.0:8445

    # 在所有IPv6地址的8445端口上监听
    bind :::8445

    # 设置为HTTP模式，用于处理HTTP请求
    mode http

    # 使用轮询算法进行负载均衡，将请求依次分发到后端服务器
    balance roundrobin

    # 使用全局日志设置
    log global

    # 定义自定义日志格式
    log-format "%Tl",%{+Q}ci,"%fi:%fp",%{+Q}bi,%{+Q}r,%ST,%B,%{+Q}hr,%Tt

    # 在请求头中添加X-Forwarded-For字段，记录客户端的原始IP地址
    option forwardfor

    # 在每个HTTP请求完成后，主动关闭服务器端的连接
    option http-server-close

    # 捕获HTTP请求头中的Host字段，最多记录255个字符
    capture request header Host len 255

    # 捕获HTTP请求头中的User-Agent字段，最多记录255个字符
    capture request header User-Agent len 255

    # 捕获HTTP请求头中的Referer字段，最多记录255个字符
    capture request header Referer len 255

    # 捕获HTTP请求头中的Cookie字段，最多记录255个字符
    capture request header Cookie len 255

    # 设置HTTP请求超时时间为10秒
    timeout http-request 10s

    # 设置HTTP保持连接超时时间为55秒
    timeout http-keep-alive 55s

    # xxxx_8445_xxx_8445: 服务器名称。
    # 192.168.10.3:8445: 服务器IP地址和端口号。
    # cookie xxx_8445: 设置用于会话保持的Cookie值。
    # weight 10: 设置服务器的权重，值越大，服务器获得的请求越多。
    # check: 启用对该服务器的健康检查。
    # inter 5000: 设置健康检查的间隔时间为5000毫秒（5秒）。
    # rise 5: 设置服务器被认为健康前必须连续成功的检查次数为5次。
    # fall 3: 设置服务器被认为不健康前必须连续失败的检查次数为3次。
    server xxxx_8445_xxx_8445 192.168.10.3:8445 cookie xxx_8445 weight 10 check inter 5000 rise 5 fall 3
    server xxxx_8445_xxx_8445 192.168.10.4:8445 cookie xxx_8445 weight 10 check inter 5000 rise 5 fall 3

四、配置文件参数选项说明

1. option 启用或禁用一些预定义的选项
参数 说明
dontlognull 不记录空连接的日志。 空连接通常是指连接建立后没有发送任何数据就关闭的连接，这种连接通常没有意义，所以不记录可以减少日志的冗余信息。
redispatch 如果请求在重试时，当前服务器已不可用，则将其重新分配到其他可用的服务器。 这对于避免请求失败非常有用。
http-server-close 在完成每个请求后，主动关闭服务器端的连接。 这有助于节省资源，特别是在长时间保持的连接上。
forwardfor [except <network>] [header <name>] 在请求头中添加 X-Forwarded-For 字段，用于记录原始客户端的 IP 地址。 可选地，可以排除某些网络或使用自定义的请求头名。
httpclose 在每个 HTTP 请求完成后，主动关闭客户端的连接。 这对某些需要短连接的应用有帮助。
httplog 使用 HTTP 格式记录日志信息，包含详细的 HTTP 请求和响应信息。
tcplog 使用 TCP 格式记录日志信息，适用于 TCP 模式下的流量。
log-separate-errors 将错误信息单独记录到日志中，便于分析和排查问题。
tcp-smart-accept 启用智能接受功能，优化 TCP 连接的处理。
tcp-smart-connect 启用智能连接功能，优化 TCP 连接的建立。
2. balance 指定负载均衡算法，决定如何在后端服务器之间分配传入的请求
负载均衡算法 说明 示例
roundrobin 按顺序将请求分发给每个服务器，这是最简单的负载均衡算法，适用于负载较均匀的场景。 balance roundrobin
leastconn 将请求分发给当前连接数最少的服务器。适用于长连接应用，如数据库连接。 balance leastconn
source 基于请求源 IP 地址进行负载均衡。 相同 IP 的请求会分发给同一台服务器，适用于需要保持会话的应用。 balance source
uri 基于请求的 URI（Uniform Resource Identifier）进行负载均衡。 相同 URI 的请求会分发给同一台服务器，适用于需要缓存的应用。 balance uri `balance uri whole
url_param 基于请求的 URL 参数进行负载均衡。 相同参数值的请求会分发给同一台服务器。 balance url_param <parameter> <parameter> 指定 URL 中的参数名。
hdr 基于指定 HTTP 头进行负载均衡。 相同 HTTP 头的请求会分发给同一台服务器。 balance hdr(<header>) <header> 指定 HTTP 头的名称。
rdp-cookie 基于 Microsoft Remote Desktop Protocol (RDP) Cookie 进行负载均衡。 适用于 RDP 服务。 balance rdp-cookie <name> <name> 指定 RDP Cookie 的名称。
3. mode 指定处理流量的模式
参数 说明 特性
http 处理 HTTP 流量。 适用于需要解析 HTTP 请求和响应的场景。 可以使用 HTTP 头进行路由和负载均衡。 支持 HTTP 重写和重定向。 支持 HTTP 缓存。
tcp 处理 TCP 流量。 适用于基于 TCP 协议的应用，如数据库、邮件服务器等。 不解析应用层数据，只处理传输层的 TCP 流量。 更适合需要低延迟和高吞吐量的场景。
health 用于健康检查。 主要用于检查后端服务器的健康状态，而不是实际转发流量。 仅用于健康检查，不转发任何应用流量。 可以配置简单的 HTTP 或 TCP 健康检查。
4. capture 捕获并记录HTTP请求和响应中的特定字段
参数 说明 示例
capture request header 捕获 HTTP 请求头中的指定字段。 语法: capture request header <name> len <length> 示例: capture request header Host len 20 捕获 HTTP 请求头中的 Host 字段，最多记录 20 个字符。
capture response header 捕获 HTTP 响应头中的指定字段。 语法: capture response header <name> len <length> 示例: capture response header Set-Cookie len 100 捕获 HTTP 响应头中的 Set-Cookie 字段，最多记录 100 个字符。
capture request cookie 捕获 HTTP 请求中的指定 Cookie。 语法: capture request cookie <name> len <length> 示例: capture request cookie session_id len 30 捕获HTTP请求中的 session_id Cookie，最多记录 30 个字符。
capture response cookie 捕获 HTTP 响应中的指定 Cookie。 语法: capture response cookie <name> len <length> 示例: capture response cookie auth_token len 50 捕获 HTTP 响应中的 auth_token Cookie，最多记录 50 个字符。
5. timeout 定义各种操作的超时时间
参数 说明 示例
client 定义客户端连接的最大空闲时间。 如果客户端在指定时间内没有发送任何数据，连接将被关闭。 示例: timeout client 50s 解释: 设置客户端连接的超时时间为50秒。
server 定义服务器连接的最大空闲时间。 如果服务器在指定时间内没有发送任何数据，连接将被关闭。 示例: timeout server 50s 解释: 设置服务器连接的超时时间为50秒。
connect 定义连接到后端服务器的最大时间。 如果在指定时间内无法建立连接，连接将失败。 示例: timeout connect 5s 解释: 设置连接到服务器的超时时间为5秒。
http-request 定义 HTTP 请求的最大处理时间。 如果在指定时间内请求未完成，连接将被关闭。 示例: timeout http-request 10s 解释: 设置 HTTP 请求的超时时间为10秒。
http-keep-alive 定义 HTTP 保持连接的最大空闲时间。 如果在指定时间内没有新的请求到达，连接将被关闭。 示例: timeout http-keep-alive 55s 解释: 设置 HTTP 保持连接的超时时间为55秒。
tunnel 定义隧道模式连接的最大时间，适用于长时间运行的连接，如 WebSocket 或 TCP 隧道。 示例: timeout tunnel 1h 解释: 设置隧道模式连接的超时时间为1小时。
queue 定义请求在队列中等待的最大时间。 如果请求在指定时间内未能分配到后端服务器，连接将失败。 示例: timeout queue 30s 解释: 设置队列超时时间为30秒。
tarpit 定义 tarpit 超时时间，用于延迟处理恶意请求。 连接将在指定时间内保持打开，然后被关闭。 示例: timeout tarpit 60s 解释: 设置tar pit的超时时间为60秒。
client-fin 定义在客户端关闭连接后，等待客户端发送 FIN 报文的最大时间。 示例: timeout client-fin 5s 解释: 设置等待客户端 FIN 报文的超时时间为5秒。
server-fin 定义在服务器关闭连接后，等待服务器发送 FIN 报文的最大时间。 示例: timeout server-fin 5s 解释: 设置等待服务器 FIN 报文的超时时间为5秒。
6. 日志

  • log 参数说明

    log

    <facility> [<level>]

参数 说明
<address> 指定日志服务器的地址，可以是 IP 地址或 Unix 域套接字。
<facility> 指定日志设施，用于分类日志信息。 常见的设施包括: local0 到 local7: 用户自定义日志设施。系统管理员可以将不同的应用程序或服务的日志信息发送到不同的 local 设施，以便于日志管理和分析。 daemon: 通常用于守护进程（后台服务）的日志。适用于系统级别的服务或应用程序 auth 和 authpriv: 用于认证和授权日志。适用于记录登录、身份验证等相关事件。 cron: 用于定时任务（cron jobs）的日志。适用于记录定时任务的执行情况。 kern: 用于内核消息的日志。适用于记录与内核相关的事件和错误。 mail: 用于邮件系统的日志。适用于记录邮件服务器和邮件传输相关的事件。 syslog: 用于 syslog 守护进程的日志。适用于记录 syslog 服务本身的活动。 user: 用于一般用户级消息的日志。适用于记录普通用户应用程序的事件。 uucp: 用于 Unix-to-Unix 复制协议（UUCP）系统的日志。适用于记录 UUCP 活动。 ftp: 用于FTP服务的日志。适用于记录FTP服务器的活动和错误。
<level> 可选参数，指定日志级别，用于过滤日志信息。 常见的级别包括： emerg 系统不可用。 alert 必须立即处理的问题。 crit 严重问题。 err 错误事件。 warning 警告事件。 notice 正常但需要注意的事件。 info 信息事件。 debug 调试信息。 默认情况下，所有级别的日志信息都会被记录。
  • log-format 定义自定义日志格式。
参数 说明
%Tl 日志时间戳（本地时间）。
%ci 客户端 IP 地址。
%cp 客户端端口。
%t 日期和时间。
%ft 前端名称。
%b 后端名称。
%s 服务器名称。
%TR 等待服务器响应的时间。
%Tw 等待服务器连接的时间。
%Tc 等待HTTP请求的时间。
%Tr 等待客户端读取的时间。
%Ta 总时间。
%ST HTTP 状态码。
%B 发送的字节数。
%tsc 日志的状态代码。
%ac 活动连接数。
%fc 前端的连接数。
%bc 后端的连接数。
%sc 服务器的连接数。
%rc 重试的连接数。
%sq 等待队列中的请求数（服务器）。
%bq 等待队列中的请求数（后端）。
%hr HTTP 请求头。
%hs HTTP 响应头。
7. server 后端服务器定义参数说明
复制代码 
server <name> <address>[:port] [param*]

param 参数说明

参数 说明 示例
weight <value> 设置服务器的权重，值越大，服务器获得的请求越多。 默认值是 1。 weight 10
check 启用对该服务器的健康检查。 如果服务器不可用，HAProxy 将不会将请求转发给它。 check
inter <interval> 设置健康检查的间隔时间，单位是毫秒。 默认值是 2000ms。 inter 5000
rise <count> 设置服务器被认为健康前必须连续成功的检查次数。 rise 3
fall <count> 设置服务器被认为不健康前必须连续失败的检查次数。 fall 2
maxconn <number> 设置服务器的最大连接数。 maxconn 100
backup 将服务器标记为备份服务器，只有在主服务器不可用时才会使用。 backup
ssl 启用 SSL/TLS 加密连接。 ssl
`verify [none optional required]`
redir <url> 将请求重定向到指定的 URL。 redir https://www.example.com

四、haproxy 命令参数说明

参数 说明 示例
-f <config_file> 指定 HAProxy 的配置文件。 haproxy -f /etc/haproxy/haproxy.cfg
-D 使 HAProxy 以守护进程模式运行。 haproxy -D
-p <pid_file> 指定 PID 文件的路径。 haproxy -p /run/haproxy.pid
-sf <pid1> [<pid2> ...] 进行优雅重启或关闭。 haproxy -sf 12345
-q 安静模式，禁用启动消息。 haproxy -q
-V 详细模式，显示启动过程中的详细信息。 haproxy -V
-c 仅检查配置文件的语法。 haproxy -c -f /etc/haproxy/haproxy.cfg
-n <maxconn> 设置最大连接数。 haproxy -n 2000
-db 禁用后台模式，强制前台运行。 haproxy -db
-d 启用调试模式。 haproxy -d
-m <value> 设置内存分配的上限（单位 MB）。 haproxy -m 512
-L <localpeer> 为进程设置本地名称。 haproxy -L myproxy
-x <socket> 指定一个现有的 HAProxy 统计套接字。 haproxy -x /run/haproxy/admin.sock
-v 显示版本信息。 haproxy -v
-vv 显示已知的构建选项。 haproxy -vv
-dM[<byte>] 使用指定字节填充内存（默认为0x50）。 haproxy -dM0x50
-C <dir> 在加载文件之前更改工作目录。 haproxy -C /path/to/dir
-W 启用主-工作模式。 haproxy -W
-Ws 启用具有 systemd 通知支持的主-工作模式。 haproxy -Ws
-N <maxconn> 设置每个代理的默认最大连接数。 haproxy -N 2000
-de 禁用 epoll() 使用，即使可用。 haproxy -de
-dp 禁用 poll() 使用，即使可用。 haproxy -dp
-dS 禁用 splice 使用（在旧内核上可能有问题）。 haproxy -dS
-dG 禁用 getaddrinfo() 使用。 haproxy -dG
-dR 禁用 SO_REUSEPORT 使用。 haproxy -dR
-dr 忽略服务器地址解析失败。 haproxy -dr
-dV 禁用服务器端的 SSL 验证。 haproxy -dV

五、示例

假设我们有一个 HAProxy 配置文件在 /etc/haproxy/haproxy.cfg，并且我们希望以守护进程模式启动 HAProxy，同时将进程 ID 写入 /run/haproxy.pid，使用以下命令：

复制代码 
haproxy -f /etc/haproxy/haproxy.cfg -D -p /run/haproxy.pid

如果我们需要在不实际启动 HAProxy 的情况下检查配置文件的语法，可以使用以下命令：

复制代码 
haproxy -c -f /etc/haproxy/haproxy.cfg

如果我们想要在启动 HAProxy 时启用详细模式，并设置最大连接数为 2000，可以使用

复制代码 
haproxy -f /etc/haproxy/haproxy.cfg -V -n 2000
相关推荐
遇见火星15 天前
RabbitMQ 高可用：HAProxy 负载均衡实战指南
分布式·消息队列·rabbitmq·负载均衡·haproxy
Red丶哞1 个月前
LVS+Keepalived+HAProxy
lvs·keepalived·haproxy
像风一样!3 个月前
HAproxy负载均衡详细介绍
负载均衡·haproxy
ZYMFZ3 个月前
HAProxy 简介及配置
linux·负载均衡·haproxy
chen_note4 个月前
LVS集群
nginx·lvs·haproxy·ipvsadm·lvs四种模式
误入运维泥潭4 个月前
LVS、Nginx与HAProxy负载均衡技术对比介绍
nginx·lvs·haproxy·keealived
wsx_iot5 个月前
haproxy安装和使用
负载均衡·haproxy·反向代理·主动健康检查
laoma-cloud5 个月前
HAProxy 负载均衡全解析：从基础部署、负载策略到会话保持及性能优化指南
运维·负载均衡·haproxy
Deutsch.6 个月前
负载均衡Haproxy
运维·负载均衡·haproxy
热门推荐
01GitHub 镜像站点02OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)03在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）04AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南052025 Telegram 最新免费社工库机器人（LetsTG可[特殊字符]）搭建指南（含 Python 脚本）06UV安装并设置国内源07安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）08BongoCat - 跨平台键盘猫动画工具09Linux下V2Ray安装配置指南10Claude Code Skills 实用使用手册