HAProxy 3.4.4 中文文档 on PIG.CENTER

入门指南

Mon, 01 Jan 0001 00:00:00 +0000

负载均衡基础

Mon, 01 Jan 0001 00:00:00 +0000

本文旨在向所有尚未了解 HAProxy 的用户以及希望重新认识该软件（尤其是熟悉旧版本的用户）提供入门引导。本文主要目的在于为用户提供充分信息，以判断 HAProxy 是否符合其需求。高级用户可能在此发现某些解决方案的片段，仅因此前未意识到某项新功能的存在。此外，本文还提供了部分容量规划信息，说明了产品的生命周期，并对部分功能重叠的产品进行了对比。

HAProxy 是什么及其实现原理

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 用于指代产品，而 HAProxy 用于指代可执行程序、软件包或进程。然而，两者常被互换使用，且均发音为 H-A-Proxy。早期，“HAProxy”曾代表“高可用性代理”，名称以两个独立单词书写，但如今其含义已仅限于“HAProxy”。

基本功能

Mon, 01 Jan 0001 00:00:00 +0000

本段将列举 HAProxy 实现的若干功能，其中部分功能是现代负载均衡器普遍具备的特性，另一些则是 HAProxy 架构带来的直接优势。更高级的功能将在下一节中详细说明。

标准功能

Mon, 01 Jan 0001 00:00:00 +0000

在本段中，列举了一些在 HAProxy 中非常常见但未必存在于其他负载均衡器上的功能。

3.4.1. 标准功能：采样与信息转换

HAProxy 支持使用多种“样本提取函数”进行信息采样。其原理是提取称为样本的信息片段，以供即时使用。该机制用于实现会话粘性、构建条件判断、生成日志信息或丰富 HTTP 头。

高级功能

Mon, 01 Jan 0001 00:00:00 +0000

3.5.1. 高级功能：系统管理

HAProxy 旨在在常规生产环境中保持极高的稳定性与安全性。它以单个可执行文件的形式提供，无需任何安装过程。多个版本可轻松共存，因此建议按重要性顺序逐步升级实例，而非一次性全部迁移。配置文件易于版本化。配置检查可在离线状态下完成，无需重启可能失败的服务。在配置检查过程中，可检测到多种高级错误（例如规则相互隐藏，或无法生效的会话粘性），并提供详细的警告信息与配置建议以修复问题。配置文件的向后兼容性极为持久，版本 1.5 仍完全支持 13 年前为版本 1.1 编写的配置，而 1.6 仅移除了几乎不再使用、已过时的关键词，这些功能可通过其他方式实现。配置与软件升级机制平滑且无中断，允许旧版与新版进程在系统中共存，各自处理自身的连接。启动时会报告系统状态、构建选项及库兼容性信息。

性能与容量规划

Mon, 01 Jan 0001 00:00:00 +0000

典型 CPU 使用率数据显示，在 TCP 或 HTTP 关闭模式下，HAProxy 占用约 15% 的处理时间，内核占用约 85%；在 HTTP 持久连接模式下，HAProxy 占用约 30%，内核占用约 70%。这表明操作系统及其调优对整体性能有显著影响。

发布、软件包与升级

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 是一个采用 GPLv2 许可证的开源项目，这意味着只要在请求时提供源代码，任何人都可以自由分发该软件，尤其是当进行了任何修改时。

HAProxy 以名为“master”或“mainline”的主开发分支持续演进，当代码被认为稳定后，便会从该分支衍生出新的分支。许多网站自愿在生产环境中运行开发分支，或为参与项目，或因需要前沿功能，其反馈对修复缺陷、评估所开发版本的整体质量与稳定性具有极高价值。

文档与社区

Mon, 01 Jan 0001 00:00:00 +0000

1. 可用文档

HAProxy 的完整文档由以下文件组成。请先查阅与问题相关的文档，以节省时间并获得最准确的答案。如果这些文档已经给出答案，请勿再向邮件列表重复提问。

配置手册

Mon, 01 Jan 0001 00:00:00 +0000

1. 快速 HTTP 提示

Mon, 01 Jan 0001 00:00:00 +0000

本文涵盖上述指定版本中实现的配置语言。本文不提供任何提示、示例或建议。如需此类文档，请参阅参考手册或架构手册。编号章节在 HAProxy 扁平侧边栏中按顺序排列，支持直接导航。

2. 配置 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

2.1. 配置文件格式

HAProxy 的配置过程涉及三个主要参数来源：

命令行参数，始终具有最高优先级
配置文件，其格式在此处描述
运行进程的环境，若显式引用了某些环境变量

配置文件采用一种相对简单的分层格式，遵循若干基本规则：

3. 全局段

Mon, 01 Jan 0001 00:00:00 +0000

“global” 段中的参数为进程级配置，通常与操作系统相关。这些参数通常只需一次性设置，一旦配置正确便无需再修改。部分参数在命令行中也有对应选项。

4. 代理

Mon, 01 Jan 0001 00:00:00 +0000

代理配置可位于一组段中：

defaults [<name>] [ from <defaults_name> ]
frontend <name> [ from <defaults_name> ]
backend <name> [ from <defaults_name> ]
listen <name> [ from <defaults_name> ]

前端段描述了一组用于接收客户端连接的监听套接字。

后端段描述了一组代理将连接以转发传入连接的服务器。

5. 绑定与服务器选项

Mon, 01 Jan 0001 00:00:00 +0000

“bind”、“server” 和 “default-server” 关键字支持多种设置，具体取决于构建选项以及 HAProxy 所基于的系统。这些设置通常由一个单词组成，有时后接一个值，与 “bind” 或 “server” 语句位于同一行。所有这些选项均在本节中描述。

6. 缓存

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 提供一个缓存，专为小型对象（如 favicon、CSS 等）的缓存而设计。这是一个极简且低维护成本的缓存，运行于内存中。

缓存基于所有线程共享的内存区域，并划分为 1kB 的块。

7. ACL 与样本提取

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 可从请求或响应流、客户端或服务器信息、表格、环境信息等来源提取数据。提取此类数据的动作称为获取样本。获取后，这些样本可用于多种用途，例如作为粘性表的键，但最常见的用法是将其与称为模式的预定义常量数据进行匹配。

8. 日志记录

Mon, 01 Jan 0001 00:00:00 +0000

本文的强项之一无疑是其精确的日志记录。它可能为这类产品提供了最详尽的信息级别，这对排查复杂环境中的问题至关重要。日志中提供的标准信息包括客户端端口、TCP/HTTP 状态定时器、流在终止时的精确状态以及精确的终止原因，关于将流量导向服务器的决策信息，当然还包括捕获任意头字段的能力。

9. 支持的过滤器

Mon, 01 Jan 0001 00:00:00 +0000

以下是官方支持的过滤器及其所接受的参数列表。根据编译选项的不同，部分过滤器可能不可用。可用过滤器的列表将在 HAProxy -vv. 中报告。

另请参见：“过滤器”

10. FastCGI 应用程序

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 可以向 Responder FastCGI 应用发送 HTTP 请求。此功能自 HAProxy 2.1 版本起引入。为此，必须将服务器配置为使用 FastCGI 协议（在服务器行中使用关键字 “proto fcgi”），且后端管理这些服务器时，必须配置并使用一个 FastCGI 应用（在代理段中使用关键字 “use-fcgi-app”）。可以定义多个 FastCGI 应用，但每个后端在同一时间只能使用其中一个。

11. 粘性表与对等节点

Mon, 01 Jan 0001 00:00:00 +0000

在 HAProxy 中，stick-table 是一种机制，允许将一定数量的信息和指标与特定类型的键关联，并在最后一次更新后持续一定时间。这可视为表格中的一行多列数据，其中行号由键值决定，各列代表不同的衡量标准。

12. 其他配置段

Mon, 01 Jan 0001 00:00:00 +0000

以下所述段落使用频率较低，通常仅支持少量参数。它们之间不存在隐式关联。所有段均通过单一关键字启动。在 “global” 段之前禁止出现任何此类段。部分段的支持可能受构建选项限制（例如与 SSL 相关的任何功能）。

管理指南

Mon, 01 Jan 0001 00:00:00 +0000

1. 先决条件

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍如何启动、停止、管理 HAProxy 及排查其故障，也会说明一些已知限制和应避免的陷阱。本文不涉及 HAProxy 的配置方法；相关内容请参阅 configuration.txt 。

本文假定读者具备类 Unix 操作系统的管理能力，日常使用 shell，并熟悉 strace、tcpdump 等故障排查工具。

2. HAProxy 架构

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 是一个多线程、事件驱动、非阻塞的守护进程。它使用事件多路复用机制调度所有活动，而不依赖系统在多项活动之间切换调度。大多数情况下，HAProxy 只运行一个进程，因此在系统上执行 “ps aux” 时通常只会看到一个 “haproxy” 进程；平滑重载期间是例外，此时旧进程会与新进程并行完成剩余工作。因此，使用 strace 始终可以轻松跟踪其活动。为利用多个处理器，HAProxy 默认会为每个允许使用的处理器启动一个工作线程。除非另有明确配置，传入流量会均匀分配给所有线程，每个线程运行相同的事件循环。HAProxy 将线程间依赖严格控制在最低水平，以实现近乎线性的扩展能力。这也意味着每条连接只由一个线程处理。因此，要充分利用全部处理能力，连接数至少应与线程数相当；实际环境几乎总能满足这一条件。

3. 启动 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 通过在命令行中传入若干参数来调用 “haproxy” 程序启动。实际语法如下：

$ haproxy [<options>]*

其中 [<options>]* 为任意数量的选项。每个选项均以 ‘-’ 开头，后接一个或多个字母，可选地跟随一个或多个额外参数。若未指定任何选项，HAProxy 将显示帮助页面，并提示支持的选项。可用选项可能因操作系统略有差异。其中相当一部分选项与 “global” 段中的等效选项重叠。在此情况下，命令行选项始终优先于配置文件，以便可通过命令行快速强制设置，而无需修改配置文件。当前选项列表如下：

4. 停止与重启 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 支持优雅停止和强制停止。强制停止操作简单：当向 HAProxy 进程发送 SIGTERM 信号时，进程立即退出，所有已建立的连接将被关闭。优雅停止通过向 HAProxy 进程发送 SIGUSR1 信号触发，其操作仅包括解除对监听端口的绑定，但会继续处理现有连接，直至所有连接关闭。当最后一个连接关闭后，进程退出。

5. 文件描述符限制

Mon, 01 Jan 0001 00:00:00 +0000

为确保所有传入连接均能成功处理，HAProxy 在加载时会计算进程生命周期内所需的文件描述符总数。常规 Unix 进程默认被授予 1024 个文件描述符，特权进程可自行提升该限制。这是以 root 身份启动 HAProxy 并由其自行调整限制的原因之一。默认的 1024 个文件描述符大致可支持约 500 个并发连接的处理。该计算基于全局 maxconn 参数，该参数限制每个进程的总连接数，同时考虑监听器数量、启用健康检查的服务器数量、代理检查、对等节点、日志记录器以及可能的其他技术需求。对该数值的粗略估算方法为：将 maxconn 值翻倍，并额外增加数十个，即可得到所需的文件描述符近似数量。

6. 内存管理

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 采用简单、快速的池式内存管理。由于 HAProxy 只使用少量不同的对象类型，从已经包含适当大小对象的内存池中获取新对象，远比针对每种大小分别调用 malloc() 高效。内存池按栈或 LIFO 方式组织，新分配的对象会优先取自刚刚释放、仍在 CPU 缓存中的对象。大小相近的内存池会合并，以减少内存碎片。

7. CPU 使用率

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 通常大部分时间运行在系统空间，仅小部分时间运行在用户空间。经过精细调优的 3.5 GHz CPU 在单核满载 100% 时，每秒可维持约 80000 次端到端连接的建立与关闭。当单核达到饱和时，典型数值为：

8. 日志记录

Mon, 01 Jan 0001 00:00:00 +0000

对于日志记录，HAProxy 始终依赖 syslog 服务器，因为它不执行任何文件系统访问。标准用法是通过 UDP 将日志发送至日志服务器（默认端口为 514）。通常情况下，该配置会指向 127.0.0.1，即本地 syslog 守护进程运行的位置，但也常通过网络将日志发送至集中式服务器。在主动-主动场景中，集中式服务器尤其具有优势，可确保日志按到达顺序合并。HAProxy 也可使用 Unix 套接字将日志发送至本地 syslog 守护进程，但强烈不建议使用，因为当 syslog 服务器重启而 haproxy 仍在运行时，套接字将被替换，新日志将丢失。由于 HAProxy 将被隔离在 chroot 环境中，它将无法重新连接至新的套接字。现场观察表明，Unix 套接字使用的日志缓冲区非常小，即使在极轻负载下也可能导致消息丢失。不过，这在测试环境中可以接受。

9. 统计信息与监控

Mon, 01 Jan 0001 00:00:00 +0000

可以查询 HAProxy 的运行状态。最常用的机制是 HTTP 统计信息页面。该页面还提供了一种用于监控工具的替代 CSV 输出格式。相同的格式也通过 Unix 套接字提供。

10. 简化配置管理

Mon, 01 Jan 0001 00:00:00 +0000

组成集群的两个 HAProxy 节点通常使用完全相同的配置，只有少数地址不同。与其为每个节点分别维护一份最终必然产生差异的重复配置，不如在配置中引用环境变量。这样，多个配置实例便可共用同一个文件，只需在系统级环境变量中保留少量差异。此功能始于 1.5 版，当时只有地址可以包含环境变量；1.6 版进一步支持在所有位置使用环境变量。其语法与 UNIX shell 相同：变量以美元符号（’$’）开头，后接左花括号（’{’）、变量名和右花括号（’}’）。除地址外，环境变量只在双引号包围的参数中解析；这是为了避免破坏使用含美元符号正则表达式的现有配置。

11. 应避免的常见陷阱

Mon, 01 Jan 0001 00:00:00 +0000

有时会有人报告：系统重启后 HAProxy 服务没有启动，但手动启动又能正常工作。这通常出现在使用 keepalived 等集群 IP 地址机制、只把服务 IP 分配给主节点的环境中。HAProxy 绑定 0.0.0.0 时一切正常，改为绑定虚拟 IP 后却无法启动。原因是服务启动时，本地节点尚未持有该虚拟 IP；HAProxy 尝试绑定时，系统会因其不是本地 IP 地址而拒绝操作。正确的解决办法不是推迟 HAProxy 服务启动——这无法应对服务重启——而是把系统配置为允许绑定非本地地址。在 Linux 上，将 net.ipv4.ip_nonlocal_bind sysctl 设为 1 即可。如果需要透明截获经 HAProxy 转发到特定目标地址的 IP 流量，也必须启用此设置。

12. 调试与性能问题

Mon, 01 Jan 0001 00:00:00 +0000

当 HAProxy 以 “-d” 选项启动时，它将以前台模式运行，并为每个事件打印一行输出，例如接收到的连接、连接结束，以及每个请求或响应头行。此调试输出在内容被处理前发出，因此不会考虑本地修改。主要用途是无需运行网络嗅探器即可查看请求和响应。当多个连接并行处理时，输出可读性会降低，但位于 examples/ 目录中的 “debug2ansi” 和 “debug2html” 脚本可显著改善此问题，通过为输出着色提升可读性。

13. 安全注意事项

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 旨在以极低的权限运行。使用它的标准方式是将其隔离到 chroot 环境中，并将其权限降级为非 root 用户，且该用户在该环境内没有任何权限，从而确保未来若发现任何漏洞，其被攻破也不会影响系统其余部分。

HAProxy 3.4.4 中文文档 on PIG.CENTER

入门指南

负载均衡基础

HAProxy 是什么及其实现原理

基本功能

标准功能

3.4.1. 标准功能：采样与信息转换

高级功能

3.5.1. 高级功能：系统管理

性能与容量规划

发布、软件包与升级

相关产品与替代方案

4.1. Apache HTTP 服务器

文档与社区

1. 可用文档

配置手册

1. 快速 HTTP 提示

2. 配置 HAProxy

2.1. 配置文件格式

3. 全局段

4. 代理

5. 绑定与服务器选项

6. 缓存

7. ACL 与样本提取

8. 日志记录

9. 支持的过滤器

10. FastCGI 应用程序

11. 粘性表与对等节点

12. 其他配置段

管理指南

1. 先决条件

2. HAProxy 架构

3. 启动 HAProxy

4. 停止与重启 HAProxy

5. 文件描述符限制

6. 内存管理

7. CPU 使用率

8. 日志记录

9. 统计信息与监控

10. 简化配置管理

11. 应避免的常见陷阱

12. 调试与性能问题

13. 安全注意事项