# 4. 代理 > 默认设置、前端、后端、监听器、代理关键字及动作引用 --- LLMS 索引： [llms.txt](/zh/llms.txt) --- 代理配置可位于一组段中： - defaults [``] [ from `` ] - frontend `` [ from `` ] - backend `` [ from `` ] - listen `` [ from `` ] 前端段描述了一组用于接收客户端连接的监听套接字。 后端段描述了一组代理将连接以转发传入连接的服务器。 段 “listen” 定义了一个完整的代理，其前端和后端部分合并于同一段中。该配置通常适用于仅 TCP 流量的场景。 “defaults” 段将所有设置重置为文档中定义的默认值，并为后续段落预设新的默认值。所有“frontend”、“backend”和“listen”段始终从一个“defaults”段获取初始设置，默认情况下使用在新创建段之前出现的最新一个“defaults”段。可以通过在段行中使用可选关键字“from”后指定名称，显式指定某个特定的“defaults”段作为初始设置来源。尽管“defaults”段不强制命名，但建议命名以提高可读性。这也是唯一一种指定使用特定段而非默认前一个段的方式。由于“defaults”段名称为可选，因此默认对名称采用非常宽松的校验，甚至允许名称重叠。然而，若某个“defaults”段被其他段引用，则其名称必须符合所有代理名称的语法要求，且在所有“defaults”段中必须唯一。请注意，尽管当前允许重复段名称，但建议一般情况下避免重复，并遵循与代理名称相同的命名语法。此规则未来版本中可能被强制执行。此外，若某个“defaults”段被某个代理显式引用，同时又因是最后一个定义的段而被另一个代理隐式引用，将发出警告。强烈建议避免混合使用显式引用和隐式引用，应始终使用显式引用，或添加一个专用于所有隐式引用的最后通用“defaults”段。 请注意，defaults 段甚至可以从另一个 defaults 段获取初始设置，从而跨多个层级的 defaults 段继承设置。这种方式可以方便地建立特定的配置模板，以承载一组默认设置（例如 TCP 与 HTTP 或短超时与长超时），但可能很快变得难以追踪。 默认情况下，命名的 defaults 段会在配置解析后保留，以便创建动态后端时复用。可通过全局关键字 `tune.defaults.purge` 改变此行为。 所有代理名称必须由大写字母、小写字母、数字、"-"（连字符）、'\_'（下划线）、'.'（点号）和 ":"（冒号）组成。ACL 名称区分大小写，这意味着 "www" 和 "WWW" 是两个不同的代理。 历史上，当满足某些条件时（例如，当代理不具备相同的前端/后端能力时），所有代理名称之间可以重叠，但这曾导致日志中出现过多问题，以及在 CLI 操作、stick-table 名称和统计信息检索方面造成混淆。现在，无论代理的具体能力如何，两个代理的名称必须不同。 目前，HAProxy 支持两种主要代理模式：“tcp”（也称为第 4 层）和 “http”（也称为第 7 层）。在第 4 层模式下，HAProxy 仅在两端之间转发双向流量。在第 7 层模式下，HAProxy 会分析协议，并可根据任意条件，对请求或响应中的任意内容执行允许、阻止、切换、添加、修改或移除操作。 在 HTTP 模式下，通过连接传输的请求和响应所应用的处理方式，取决于前端的 HTTP 选项与后端选项的组合。HAProxy 支持三种连接模式： - KAL：持久连接（"option http-keep-alive"）为默认模式：所有请求和响应均被处理，连接在响应与新请求之间保持打开状态但处于空闲状态。 - SCL：服务端关闭（"option http-server-close"）：在收到响应结束后，关闭面向服务器的连接，但保持面向客户端的连接打开。 - CLO：关闭（“option httpclose”）：在响应结束之后关闭连接，并在两个方向上附加 "Connection: close"。 通过前端和后端的连接所采用的有效模式，可根据两个代理模式按以下矩阵确定，但简而言之，模式具有对称性，持久连接为最弱选项，关闭为最强选项。 Backend mode ```text | KAL | SCL | CLO ----+-----+-----+---- KAL | KAL | SCL | CLO ----+-----+-----+---- 模式 SCL | SCL | SCL | CLO ----+-----+-----+---- CLO | CLO | CLO | CLO ``` 可以将 TCP 前端与 HTTP 后端串联使用。若仅处理 HTTP 流量，则此举毫无意义。但可用于在同一个前端中处理多种协议。在此情况下，客户端连接首先作为原始 TCP 连接处理，随后升级为 HTTP。升级前，内容处理基于原始数据进行。升级后，数据将使用一种称为 HTX 的内部表示形式进行解析和存储，此时不再可能依赖原始表示形式。无法回退。 有两种升级方式：就地升级和破坏性升级。第一种涉及从 TCP 升级至 HTTP/1。在 HTTP/1 中，请求处理是串行的，因此应用层流可以被保留。第二种涉及从 TCP 升级至 HTTP/2。由于 HTTP/2 是多路复用协议，应用层流无法与任何 HTTP/2 流关联，因而被破坏。当 HAProxy 在底层 H2 多路复用器中接收到新的 HTTP/2 流时，会创建新的应用层流。理解这一差异至关重要，因为它会显著改变数据处理方式。执行 HTTP/1 升级时，对原始数据已执行的应用层处理既不会丢失也不会重新执行；而执行 HTTP/2 升级时，应用层流彼此独立，每个流都会系统性地重新评估所有前端规则。如前所述，第一个流（即 TCP 流）会被破坏，但仅在前端规则评估完成后。 当在 TCP 代理中执行 HTTP 处理时，还有一个重要点需要理解。 虽然 HAProxy 能够在 tcp-request 内容规则中实时解析 HTTP/1，但无法解析 HTTP/2。 仅能解析 HTTP/2 的前导信息（preface）。这在 TCP 环境下的 HTTP 内容分析中是一个重大限制。 具体而言，仅能判断接收到的数据是否为 HTTP。例如，无法根据 Host 头的值选择后端，而这一操作在 HTTP/1 中极为简单。 值得庆幸的是，存在一种解决方案可缓解此缺陷。 有两种方式执行 HTTP 升级。第一种是传统方法，即选择一个 HTTP 后端。当后端被设置时，升级即发生。因此，在就地升级场景下，仅考虑后端配置对 HTTP 数据处理的影响。在破坏性升级场景下，应用流被销毁，其处理过程也随之停止。采用此方法时，选择支持 HTTP/2 连接的后端的可能性极为有限，如上所述，且基本无实际意义，因为流已被销毁。第二种方法是在 tcp-request content 规则评估期间，通过 "switch-mode http" 动作执行升级。在此情况下，升级在前端上下文中进行，可以在该前端中定义 HTTP 指令。对于就地升级，可尽早获得 HTTP 分析的全部功能。其行为与 HTTP 前端非常接近。对于破坏性升级，除无法基于有限信息选择后端外，其余无实质影响。此方法为推荐方案。因此，仅需在 tcp-request content 规则中检测请求协议以执行 HTTP 升级即可。其余所有 HTTP 操作可移至前端 http-request 规则集。请注意，tcp-request content 规则始终在每个流上评估，此行为不可更改。 ## 4.1. 代理关键字矩阵 {#section-4-1} 以下关键词列表受支持。大多数关键词仅可在有限的段类型中使用。部分关键词标有“已弃用”，因其继承自旧语法，可能造成混淆或功能受限，现已推荐使用新关键词替代。标有“(\*)”的关键词可选择性地通过“no”前缀进行反转，例如“no option contstats”。当某选项默认已启用，而需在特定实例中禁用时，此用法有意义。此类选项还可使用“default”前缀，以恢复默认设置，无论此前“defaults”段中如何配置。标有“(!)”的关键词仅在命名的“defaults”段中受支持，不适用于匿名段。 请注意：部分危险且不推荐使用的指令故意未列在下表中。此举出于刻意。这些指令已有文档说明，但不在下方列出，也是为了进一步劝阻用户使用。 ```text 关键字 defaults frontend listen backend ------------------------------------+----------+----------+---------+--------- acl X (!) X X X backlog X X X - balance X - X X be-unpublished - - X X bind - X X - capture cookie - X X - capture request header - X X - capture response header - X X - clitcpka-cnt X X X - clitcpka-idle X X X - clitcpka-intvl X X X - compression X X X X cookie X - X X crt - X X - declare capture - X X - default-server X - X X default_backend X X X - description - X X X disabled X X X X dispatch (deprecated) - - X X email-alert from X X X X email-alert level X X X X email-alert mailers X X X X email-alert myhostname X X X X email-alert to X X X X enabled X X X X errorfile X X X X errorfiles X X X X errorloc X X X X errorloc302 X X X X -- keyword -------------------------- defaults - frontend - listen -- backend - errorloc303 X X X X error-log-format X X X - external-check command X - X X external-check path X - X X force-persist - - X X force-be-switch - X X - filter - X X X fullconn X - X X guid - X X X hash-balance-factor X - X X hash-preserve-affinity X - X X hash-type X - X X http-after-response X (!) X X X http-check comment X - X X http-check connect X - X X http-check disable-on-404 X - X X http-check expect X - X X http-check send X - X X http-check send-state X - X X http-check set-var X - X X http-check unset-var X - X X http-error X X X X http-request X (!) X X X http-response X (!) X X X http-reuse X - X X http-send-name-header X - X X id - X X X ignore-persist - - X X load-server-state-from-file X - X X log (*) X X X X log-format X X X - log-format-sd X X X - log-tag X X X X log-steps X X X - max-keep-alive-queue X - X X max-session-srv-conns X X X - maxconn X X X - mode X X X X monitor fail - X X - monitor-uri X X X - option abortonclose (*) X X X X option allbackups (*) X - X X option checkcache (*) X - X X option clitcpka (*) X X X - option contstats (*) X X X - option disable-h2-upgrade (*) X X X - option dontlog-normal (*) X X X - option dontlognull (*) X X X - -- keyword -------------------------- defaults - frontend - listen -- backend - option external-check X - X X option forwardfor X X X X option forwarded (*) X - X X option h1-case-adjust-bogus-client (*) X X X - option h1-case-adjust-bogus-server (*) X - X X option http-buffer-request (*) X X X X option http-drop-request-trailers (*) X - - X option http-drop-response-trailers (*) X - X - option http-ignore-probes (*) X X X - option http-keep-alive (*) X X X X option http-no-delay (*) X X X X option http-pretend-keepalive (*) X - X X option http-restrict-req-hdr-names X X X X option http-server-close (*) X X X X option http-use-proxy-header (*) X X X - option httpchk X - X X option httpclose (*) X X X X option httplog X X X - option httpslog X X X - option idle-close-on-response (*) X X X - option independent-streams (*) X X X X option ldap-check X - X X option log-health-checks (*) X - X X option log-separate-errors (*) X X X - option logasap (*) X X X - option mysql-check X - X X option nolinger (*) X X X X option originalto X X X X option persist (*) X - X X option pgsql-check X - X X option prefer-last-server (*) X - X X option redispatch (*) X - X X option redis-check X - X X option smtpchk X - X X option socket-stats (*) X X X - option splice-auto (*) X X X X option splice-request (*) X X X X option splice-response (*) X X X X option spop-check X - X X option srvtcpka (*) X - X X option ssl-hello-chk X - X X -- keyword -------------------------- defaults - frontend - listen -- backend - option tcp-check X - X X option tcp-smart-accept (*) X X X - option tcp-smart-connect (*) X - X X option tcpka X X X X option tcplog X X X - option transparent (deprecated) (*) X - X X option use-small-buffers (*) X - X X persist rdp-cookie X - X X quic-initial X (!) X X - rate-limit sessions X X X - redirect - X X X -- keyword -------------------------- defaults - frontend - listen -- backend - retries X - X X retry-on X - X X server - - X X server-state-file-name X - X X server-template - - X X source X - X X srvtcpka-cnt X - X X srvtcpka-idle X - X X srvtcpka-intvl X - X X stats admin - X X X stats auth X X X X stats enable X X X X stats hide-version X X X X stats http-request - X X X stats realm X X X X stats refresh X X X X stats scope X X X X stats show-desc X X X X stats show-legends X X X X stats show-node X X X X stats show-version X X X X stats uri X X X X -- keyword -------------------------- defaults - frontend - listen -- backend - stick match - - X X stick on - - X X stick store-request - - X X stick store-response - - X X stick-table - X X X tcp-check comment X - X X tcp-check connect X - X X tcp-check expect X - X X tcp-check send X - X X tcp-check send-lf X - X X tcp-check send-binary X - X X tcp-check send-binary-lf X - X X tcp-check set-var X - X X tcp-check unset-var X - X X tcp-request connection X (!) X X - tcp-request content X (!) X X X tcp-request inspect-delay X (!) X X X tcp-request session X (!) X X - tcp-response content X (!) - X X tcp-response inspect-delay X (!) - X X timeout check X - X X timeout client X X X - timeout client-fin X X X - timeout client-hs X X X - timeout connect X - X X timeout http-keep-alive X X X X timeout http-request X X X X timeout queue X - X X timeout server X - X X timeout server-fin X - X X timeout tarpit X X X X timeout tunnel X - X X transparent (deprecated) X - X X unique-id-format X X X X unique-id-header X X X - use_backend - X X - use-fcgi-app - - X X use-server - - X X ------------------------------------+----------+----------+---------+--------- keyword defaults frontend listen backend ``` ## 4.2. 按字母顺序排序的关键字参考 {#section-4-2} 本段描述了每个关键字及其用法。 **`acl [flags] [operator] ...`** ```haproxy acl [flags] [operator] ... ``` 声明或完成访问控制列表。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes 该指令仅可在命名的 defaults 段中使用，不可在匿名段中使用。在 defaults 段中定义的 ACL 不可被使用该段的其他段访问。 示例： ```text acl invalid_src src 0.0.0.0/7 224.0.0.0/3 acl invalid_src src_port 0:1023 acl local_dst hdr(host) -i localhost ``` 请参阅 [第 7 节](/zh/docs/haproxy/acls-and-samples/) 了解 ACL 的使用方法。 **`backlog `** ```haproxy backlog ``` 向系统提供关于期望监听队列大小的近似提示 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是待处理的连接数。根据操作系统，它可表示已确认的连接数、未确认的连接数，或两者之和。 ``` 此选项仅对流监听器（包括 QUIC 监听器）有意义。然而，其行为与 QUIC 实例并不完全相同。 对于除 QUIC 以外的所有监听器，为防范 SYN 洪水攻击，一种解决方案是增大系统的 SYN 队列长度。根据系统不同，该参数有时可通过系统参数调整，有时则完全不可调，有时系统会依赖应用程序在调用 listen() 系统调用时提供的提示。默认情况下，HAProxy 会将前端的 maxconn 值传递给 listen() 系统调用。在能够利用该值的系统上，有时指定不同的值会更有用，因此引入了 backlog 参数。 在 Linux 2.4 上，该参数会被系统忽略。在 Linux 2.6 上，它作为提示使用，系统最多接受小于等于最小大于该值的 2 的幂次，且永远不会超过某些限制（通常为 32768）。 对于 QUIC 监听器，backlog 为活跃握手的最大数量和待接受连接的数量设定了共享上限。握手阶段主要依赖于与远端对等节点的网络延迟，而第二阶段则完全取决于 HAProxy 的负载。当任一限制达到时，HAProxy 将开始丢弃 INITIAL 数据包的接收，阻止任何新连接的分配，直至连接数量超出部分开始下降。此情况可能导致浏览器静默降级 HTTP 版本并切换至 TCP。 另请参阅：“maxconn”以及目标操作系统的调优指南。 **`balance [ ]`** ```haproxy balance [ ] balance url_param [check_post] ``` 定义后端所使用的负载均衡算法。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是负载均衡时选择服务器的算法，仅在没有可用的会话保持信息， 或连接被重分派到另一服务器时应用。 可为以下值之一： roundrobin 按权重轮流使用各服务器。服务器处理时间分布均衡时，这是最平滑、公平的算法。 此算法为动态算法，可在运行时调整服务器权重，例如用于慢启动。 按设计，每个后端最多支持 4095 个活跃服务器。在某些大型服务器群中， 服务器短暂离线后重新上线，偶尔可能需要数百个请求才重新加入并开始接收流量。 这是正常但十分罕见的情况，在此说明以免遇到时产生疑虑。 注意：LOG 模式后端忽略权重。 static-rr 按权重轮流使用各服务器。与 roundrobin 类似，但为静态算法， 因而运行时更改服务器权重无效。其服务器数量没有设计上限， 服务器上线后，一旦完整映射重新计算完毕，便立即重新加入服务器群。 运行时 CPU 消耗也略低（约 -1%）。此算法不可用于 LOG 模式。 leastconn 连接数最少的服务器接收连接。负载相同的服务器组内采用轮询，以确保各服务器均被使用。 推荐用于预期会话很长的场景，如 LDAP、SQL、TSE 等，但不太适合 HTTP 等短会话协议。 此算法为动态算法，可在运行时调整权重，例如用于慢启动。 除已建立连接外，还考虑排队连接数，以尽量减少排队。此算法不可用于 LOG 模式。 first 第一个具有可用连接槽位的服务器接收连接。按数值标识符从低到高选择服务器 （参见服务器参数 "id"），默认标识符为服务器在群组中的位置。 服务器达到 maxconn 后使用下一服务器，未设置 maxconn 时使用此算法没有意义。 目的是始终使用最少的服务器，以便在非繁忙时段关闭多余服务器。 此算法忽略权重，更适合 RDP 或 IMAP 等长会话，但 HTTP 场景也可能受益。 为高效使用，建议云控制器定期检查服务器使用情况，关闭未使用的服务器， 并定期检查后端队列，在队列膨胀时启动新服务器。 也可使用 "http-check send-state" 向服务器通告负载。此算法不可用于 LOG 模式。 hash 接受普通样本表达式作为参数。每个请求均对表达式求值，并按配置的 hash-type 计算哈希。 将哈希结果按运行中服务器的总权重取模，以确定接收请求的服务器。 可代替 "source"、"uri"、"hdr()"、"url_param()"、"rdp-cookie"， 以使用转换器、细化求值，或从本地变量提取数据。数据不可用时采用轮询。 默认是静态算法，运行时更改权重无效，但可通过 "hash-type" 改变这一行为。 不可用于 LOG 模式后端，此时请改用 "log-hash"。 source 对源 IP 地址计算哈希，再按运行中服务器的总权重取模，以确定接收请求的服务器。 只要没有服务器上线或离线，同一客户端 IP 地址就始终到达同一服务器。 若运行中服务器数量变化导致哈希结果改变，许多客户端将被导向不同服务器。 通常用于无法插入 Cookie 的 TCP 模式，也可在互联网上为拒绝会话 Cookie 的客户端 尽力提供粘性。默认是静态算法，运行时更改权重无效，但可通过 "hash-type" 改变。 另见上方 "hash" 选项。此算法不可用于 LOG 模式后端。 uri 对 URI 左侧部分（问号之前）或完整 URI（使用 "whole" 参数时）计算哈希， 再按运行中服务器的总权重取模，以确定接收请求的服务器。 只要没有服务器上线或离线，同一 URI 就始终导向同一服务器。 用于代理缓存和防病毒代理，以提高缓存命中率。仅可用于 HTTP 后端。 默认是静态算法，运行时更改权重无效，但可通过 "hash-type" 改变。 支持两个可选参数 "len" 和 "depth"，均后接正整数。 仅需根据 URI 开头部分进行负载均衡时，这些选项可能有用。 "len" 指定仅使用 URI 开头的相应字符数计算哈希。 由于大多数 URI 以 "/" 开头，将 "len" 设为 1 通常没有意义。 "depth" 指定计算哈希时使用的最大目录深度，每个斜杠计为一级。 同时指定两个参数时，达到其中任意一个限制便停止求值。 "path-only" 指定哈希键从路径的第一个 '/' 开始， 可忽略绝对 URI 的 authority 部分，并确保 HTTP/1 和 HTTP/2 URI 生成相同哈希。 另见上方 "hash" 选项。 url_param 在每个 HTTP GET 请求的查询字符串中查找参数指定的 URL 参数。 使用 "check_post" 修饰符时，若未在 URL 问号（'?'）之后的查询字符串中找到参数， 则在 HTTP POST 请求实体中查找。只有收到声明的数据量或请求缓冲区已满时， 才开始分析消息体。若少见地使用分块编码，则仅扫描首个块。 参数值跨越块边界时，可能被随机均衡，甚至可能无法处理。 此关键字曾支持可选的 参数，目前会忽略该参数。 找到参数，且其后有等号（'='）和值时，对该值计算哈希， 再按运行中服务器的总权重取模，以确定接收请求的服务器。 用于跟踪请求中的用户标识符，确保只要没有服务器上线或离线， 同一用户 ID 始终发送到同一服务器。未找到值或参数时，应用轮询算法。 仅可用于 HTTP 后端。默认是静态算法，运行时更改权重无效， 但可通过 "hash-type" 改变。另见上方 "hash" 选项。 hdr() 在每个 HTTP 请求中查找 HTTP 头 。与等效的 ACL 'hdr()' 函数一样， 括号中的头名称不区分大小写。头不存在或不包含值时，改用 roundrobin 算法。 可选参数 'use_domain_only' 可针对 'Host' 等特定头，只用主域名部分计算哈希。 例如，Host 值为 "haproxy.1wt.eu" 时，仅考虑 "1wt"。 默认是静态算法，运行时更改权重无效，但可通过 "hash-type" 改变。 另见上方 "hash" 选项。 random random() 将随机数作为一致性哈希函数的键，因而遵守服务器权重， 动态权重变更和新增服务器均立即生效。随机负载均衡适用于大型服务器群， 或服务器频繁增删的情况，可避免此时 roundrobin 或 leastconn 可能导致的集中冲击。 hash-balance-factor 指令可进一步改善公平性，尤其在服务器响应时间差异很大时。 提供 参数时，其值必须为大于或等于一的整数，表示抽取多少个服务器后， 从中选择负载最小的服务器。已证明，只从两个服务器中选择负载较小者， 就足以显著改善公平性，避免选择群组中负载最高的服务器， 并消除一致性列表分布不均造成的偏差。更高的 N 会排除 N-1 个负载较高的候选服务器， 但以性能为代价。值极高时，结果趋近 leastconn，但速度慢得多。 对于负载很低或完全均衡的大型服务器群，比较负载时常出现并列。 若所有采样服务器负载相等，则比较它们在上一秒的请求速率， 以类似 roundrobin 的方式平衡长期使用率，并缓解一致性哈希的不公平性。 默认值为 2，通常兼顾分布和性能。大型服务器群负载较低时 （每台服务器每秒少于几个请求），提高到 3 或 4 可能有帮助。 此算法又称 Power of Two Random Choices，说明见： http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf 对于 LOG 模式后端，由于没有服务器负载的概念，忽略抽取次数，只抽取一个随机数。 随机日志均衡适用于大型服务器群，或可用服务器池频繁增删的情况， 可避免此时 roundrobin 可能导致的集中冲击。 rdp-cookie rdp-cookie() 对每个传入 TCP 请求查找 RDP Cookie （省略时为 "mstshash"），并计算哈希。 与等效的 ACL 'req.rdp_cookie()' 函数一样，名称不区分大小写。 此机制可作为退化的会话保持模式，让同一用户或同一会话 ID 始终发送到同一服务器。 未找到 Cookie 时，改用普通 roundrobin 算法。 为使此机制正常工作，前端必须确保请求缓冲区中已有 RDP Cookie。 必须使用 'tcp-request content accept' 规则与 'req.rdp_cookie_cnt' ACL 组合。 默认是静态算法，运行时更改权重无效，但可通过 "hash-type" 改变。 另见上方 "hash" 选项。 log-hash 接受以逗号分隔的转换器列表作为参数。转换器依次应用于输入的日志消息， 将结果转换为字符串，再按配置的 hash-type 计算哈希。 使用最终哈希从日志后端声明的服务器中选择目标。 目的是通过字符串转换器从最终日志消息中提取键，再利用哈希保持使用同一服务器。 目前仅支持 "map-based" 哈希。仅可用于 LOG 模式后端，其他后端请改用 "hash"。 sticky 尽可能保持使用同一服务器。可用服务器列表中的第一个服务器接收所有日志消息。 服务器变为 DOWN 时，列表中的下一服务器接替。 此前 DOWN 的服务器恢复 UP 时，添加到列表末尾， 因而当前粘性目标在变为 DOWN 之前不会改变。 是可选的参数列表，部分算法可能需要。目前仅 "url_param"、"uri" 和 "log-hash" 支持可选参数。 ``` 当后端未设置其他算法、模式或选项时，其负载均衡算法默认为“random”。每个后端的算法只能设置一次。 对于需要同一连接的认证方案（如 NTLM），不得使用基于 URI 的算法，否则后续请求可能被路由至不同的后端服务器，从而破坏 NTLM 所依赖的无效假设。 TCP/HTTP 示例： ```text balance roundrobin balance url_param userid balance url_param session_id check_post 64 balance hdr(User-Agent) balance hdr(host) balance hdr(Host) use_domain_only balance hash req.cookie(clientid) balance hash var(req.client_id) balance hash req.hdr_ip(x-forwarded-for,-1),ipmask(24) ``` 日志后端示例： ```text global log backend@mylog-rrb local0 # send all logs to mylog-rrb backend log backend@mylog-hash local0 # send all logs to mylog-hash backend backend mylog-rrb mode log balance roundrobin server s1 udp@127.0.0.1:514 # will receive 50% of log messages server s2 udp@127.0.0.1:514 backend mylog-hash mode log # extract "METHOD URL PROTO" at the end of the log message, # and let haproxy hash it so that log messages generated from # similar requests get sent to the same syslog server: balance log-hash 'field(-2,\")' # server list here server s1 127.0.0.1:514 #... ``` 请注意：在使用 "check_post" 扩展与 "url_param" 时，必须考虑以下注意事项和限制： - 所有 POST 请求都会纳入考虑，因为无法判断参数是否位于可能包含二进制 数据的正文或实体中。因此，可能需要另一种方法来排除正文中没有 URL 参数的 POST 请求。（参见 acl http_end） - 使用大于请求缓冲区大小的 `` 值没有意义，也没有用处。缓冲 区大小在构建时设定，默认为 16 kB。 - 不支持 Content-Encoding，参数搜索很可能失败；负载均衡将回退为 轮询（Round Robin）。 - 不支持 Expect: 100-continue，负载均衡将回退为轮询（Round Robin）。 - Transfer-Encoding（RFC7230 3.3.1）仅在第一个块中受支持。如果完整 的参数值未出现在第一个块中，服务器的选择将是未定义的（实际上， 取决于第一个块中实际出现了多少内容）。 - 此功能不支持生成 100、411 或 501 响应。 - 在某些情况下，请求 "check_post" 可能会尝试扫描报文正文的全部内容。 扫描通常在遇到线性空白字符或控制字符时终止，这表明可能的 URL 参数 列表已经结束。对于 SGML 类型的报文正文，这大概不是问题。 另请参阅："dispatch"、"cookie"、"transparent"、"hash-type"。 **`be-unpublished`** ```haproxy be-unpublished ``` 指示后端以未发布状态启动。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend no \| no \| yes \| yes 使用此指令后，其他代理中引用当前代理的 `use_backend` 和 `default_backend` 规则会被忽略，并继续评估后续的内容切换规则。不过，`force-be-switch` 规则可以绕过这一限制。 该状态与禁用状态类似，但有几点不同。首先，未发布的后端仍会完整初始化，包括继续运行服务器健康检查。其次，可通过 CLI 的 `publish backend` 命令将后端公开发布。详见管理手册。 另请参阅：`force-be-switch` **`bind [
]: [, ...] [param*]`** ```haproxy bind [
]: [, ...] [param*] bind / [, ...] [param*] ``` 在前端中定义一个或多个监听地址和/或端口。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text
是可选参数，可为主机名、IPv4 地址、IPv6 地址或 '*'，指定前端监听的地址。 未设置时，监听系统的所有 IPv4 地址；'*' 或系统特殊地址 "0.0.0.0" 也有相同效果。 IPv6 对应地址为 '::'。注意，UDP 绑定多个地址时，需要特定的操作系统（OS）功能， 才能确保响应使用正确的网络接口和源地址。因此，QUIC 监听器仅应在足够新的系统上绑定多个地址。 可在地址前添加地址族前缀，忽略地址格式并强制使用指定地址族， 例如指定不包含斜杠（'/'）的 unix 套接字路径时可能有用。目前支持的前缀包括： - 'ipv4@' -> 地址始终为 IPv4 - 'ipv6@' -> 地址始终为 IPv6 - 'udp@' -> 地址解析为 IPv4 或 IPv6，使用 UDP 协议；目前仅在 log-forward 段支持此类监听器。 - 'udp4@' -> 地址始终为 IPv4，使用 UDP 协议；目前仅在 log-forward 段支持此类监听器。 - 'udp6@' -> 地址始终为 IPv6，使用 UDP 协议；目前仅在 log-forward 段支持此类监听器。 - 'unix@' -> 地址是本地 unix 套接字路径 - 'abns@' -> 地址位于抽象命名空间（仅 Linux） - 'abnsz@' -> 地址位于抽象命名空间（仅 Linux），但显式以零终止， 不使用 \0 填充 sun_path；适合连接未实现 haproxy 默认 abns 命名逻辑的程序。 - 'fd@' -> 使用从父进程继承的文件描述符 。fd 必须已绑定，可以已经监听，也可以尚未监听。 - 'sockpair@'-> 类似 fd@，但必须使用已连接的 unix 套接字或 socketpair 的 fd。 bind 等待通过 unix 套接字收到 FD，并将其当作 accept() 返回的 FD 使用。应谨慎使用。 - 'quic4@' -> 地址解析为 IPv4，使用 UDP 协议。大流量下为获得最佳性能， 应保持 "tune.quic.fe.sock-per-conn default-on"。否则 QUIC 连接会在监听套接字上复用。 另一种方法是在多个线程上复制 QUIC 监听器实例，例如通过 "shards" 关键字至少减少线程竞争。 - 'quic6@' -> 地址解析为 IPv6，使用 UDP 协议；QUIC over IPv4 的性能说明同样适用。 - 'rhttp@' [ EXPERIMENTAL ] -> 用于反向 HTTP。地址必须是格式为 '/' 的服务器。 使用此服务器实例化到远程地址的连接。监听器尝试保持 "nbconn" 个连接。 这是实验性功能，要求在此 bind 之前的一行中启用 "expose-experimental-directives"。 地址参数可能需要引用环境变量，参见第 2.3 节的环境变量说明。 是单个 TCP 端口或端口范围，代理将在上述 IP 地址上接受这些端口的连接。 TCP 监听器必须指定端口。IPv6 地址的端口始终是最后一个冒号（':'）之后的数值。 范围可以是： - 数值端口（例如 '80'） - 用连字符分隔，显式指定上下限且包含两端的端口范围（例如 '2000-2100'）。 使用端口范围时须格外谨慎：每个 组合占用一个套接字（即一个文件描述符）， 简单的范围就可能消耗大量描述符并耗尽套接字。 同一系统运行的所有实例之间，每个 组合只能使用一次。 绑定低于 1024 的端口通常需要程序启动时具有特殊权限，与 'uid' 参数无关。 是以斜杠（'/'）开头的 UNIX 套接字路径，可替代 TCP 监听端口。 HAProxy 在此位置的套接字上接收 UNIX 连接。路径必须以斜杠开头，默认是绝对路径， 也可相对于 global 段中 "unix-bind" 定义的前缀。 前缀与套接字路径的总长度不能超过 UNIX 套接字的系统限制，通常为 107 个字符。 是同一行声明的所有套接字共用的参数列表。 参数众多，取决于操作系统（OS）和构建选项，有专门的一节完整介绍。详情见第 5 节。 ``` 可以指定以逗号分隔的地址：端口组合列表。前端将在此列出的所有地址上监听。前端可监听的地址和端口数量没有固定限制，同时前端中“bind”语句的数量也没有限制。 示例： ```text listen http_proxy bind :80,:443 bind 10.0.0.1:10080,10.0.0.1:10443 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy listen http_https_proxy bind :80 bind :443 ssl crt /etc/haproxy/site.pem listen http_https_proxy_explicit bind ipv6@:80 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem bind unix@ssl-frontend.sock user root mode 600 accept-proxy listen external_bind_app1 bind "fd@${FD_APP1}" listen h3_quic_proxy bind quic4@10.0.0.1:8888 ssl crt /etc/mycrt ``` 请注意：关于 Linux 的抽象命名空间套接字，“abns” HAProxy 套接字使用 sun_path 的完整长度作为地址长度。其他一些程序（如 socat）默认仅使用字符串长度。如需使 socat 的抽象套接字定义与 HAProxy 兼容，请向 socat 的任意抽象套接字定义传递选项 ",unix-tightsocklen=0"，或改用 "abnsz" HAProxy 套接字族。 另请参阅：“source”、“option forwardfor”、“unix-bind”以及 PROXY 协议文档，以及关于绑定选项的[第 5 节](/zh/docs/haproxy/bind-and-server-options/)。 **`capture cookie len `** ```haproxy capture cookie len ``` 捕获并记录请求和响应中的 Cookie。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text 是要捕获的 Cookie 名称的起始部分。要精确匹配名称，只需在末尾添加等号（'='）。 日志中显示完整名称，适合会同时调整 Cookie 名称和值的应用服务器（例如 ASPSESSIONXXX）。 是在日志中报告的最大字符数，包含 Cookie 名称、等号和值，采用标准的 "name=value" 形式。 字符串长度超过 时，从右侧截断。 ``` 仅捕获第一个 Cookie。同时监控“cookie”请求头和“set-cookie”响应头。此功能特别适用于检查应用程序缺陷导致的用户间会话交叉或会话窃取问题，因为通常情况下用户的 Cookie 仅在登录页面发生变更。 当客户端未提供 Cookie 时，相关日志列将报告“-”。当请求未导致服务器分配 Cookie 时，响应列将报告“-”。 捕获操作仅在前端执行，因为必须确保某个前端的日志格式不随后端变化而改变。此行为未来可能会调整。请注意，一个前端中只能存在一条“capture cookie”语句。捕获的最大长度由全局 "tune.http.cookielen" 设置决定，默认值为 63 个字符。无法在“defaults”段中指定捕获。 示例： ```text capture cookie ASPSESSION len 32 ``` 另请参阅：“capture request header”、“capture response header”，以及关于日志记录的 [第 8 节](/zh/docs/haproxy/configuration-logging/)。 **`capture request header len `** ```haproxy capture request header len ``` 捕获并记录指定请求头的最后一次出现。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text 是要捕获的头名称。头名称不区分大小写，但通常按其在请求中出现的形式书写， 每个单词的首字母大写。日志中不显示头名称，仅报告其值，但保留其在日志中的位置。 是从值中提取并在日志中报告的最大字符数。字符串长度超过 时，从右侧截断。 ``` 捕获最后一个出现的头的完整值。该值将被添加到日志中，用大括号（'{}'）括起。若捕获多个头，它们将按配置中声明的顺序以竖线（'\|'）分隔，并依次出现。不存在的头将被记录为空字符串。请求头捕获的常见用途包括：在虚拟主机环境中捕获“Host”字段，在支持上传时捕获“Content-length”，通过“User-agent”快速区分真实用户与机器人，以及在代理环境中捕获“X-Forwarded-For”以确定请求来源。 请注意，捕获如 "User-agent" 等头时，日志中可能包含空格，这会使日志分析更加困难。因此，如果已知日志解析器不够智能，无法依赖大括号解析，请谨慎选择记录的内容。 对捕获的请求头数量和长度均无限制，但建议保持较低数量以降低每流的内存使用量。为确保同一前端的日志格式一致，头捕获只能在前端段中声明。无法在“defaults”段中指定捕获。 示例： ```text capture request header Host len 15 capture request header X-Forwarded-For len 15 capture request header Referer len 15 ``` 另请参阅：“capture cookie”、“capture response header”，以及关于日志记录的 [第 8 节](/zh/docs/haproxy/configuration-logging/)。 **`capture response header len `** ```haproxy capture response header len ``` 捕获并记录指定响应头的最后一次出现。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text 是要捕获的头名称。头名称不区分大小写，但通常按其在响应中出现的形式书写， 每个单词的首字母大写。日志中不显示头名称，仅报告其值，但保留其在日志中的位置。 是从值中提取并在日志中报告的最大字符数。字符串长度超过 时，从右侧截断。 ``` 最后一次出现的头字段的完整值将被捕获。捕获结果将被添加到日志中，位于捕获的请求头之后，用大括号（'{}'）括起。若捕获了多个头字段，它们将以竖线（'\|'）分隔，并按配置中声明的顺序出现。不存在的头字段将被记录为空字符串。响应头捕获的常见用途包括“Content-length”头，用于指示预期返回的字节数，以及“Location”头，用于追踪重定向。 对响应头的捕获数量和长度均无限制，但建议保持较低数量以控制每流的内存使用量。为确保同一前端的日志格式一致，头捕获只能在前端中声明。无法在“defaults”段中指定捕获。 示例： ```text capture response header Content-length len 9 capture response header Location len 15 ``` 另请参阅：“capture cookie”、“capture request header”，以及关于日志记录的 [第 8 节](/zh/docs/haproxy/configuration-logging/)。 **`clitcpka-cnt `** ```haproxy clitcpka-cnt ``` 设置 TCP 在客户端侧丢弃连接前应发送的最大保活探测次数。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是保活探测的最大次数。 ``` 此关键字对应套接字选项 TCP_KEEPCNT。若未指定此关键字，则使用系统级 TCP 参数（tcp_keepalive_probes）。该设置的可用性取决于操作系统。已知其在 Linux 上可用。 另请参阅：“option clitcpka”、“clitcpka-idle”、“clitcpka-intvl”。 **`clitcpka-idle `** ```haproxy clitcpka-idle ``` 设置连接在 TCP 开始发送保活探测前需保持空闲的时间，若启用，则在客户端侧发送 TCP 保活数据包。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是连接保持空闲多久后 TCP 开始发送保活探测的时间。默认单位为秒， 也可在数值后添加单位后缀，使用其他单位，详见本文开头的说明。 ``` 此关键字对应套接字选项 TCP_KEEPIDLE。若未指定此关键字，则使用系统级 TCP 参数（tcp_keepalive_time）。该设置的可用性取决于操作系统。已知其在 Linux 上可用。 另请参阅：“option clitcpka”、“clitcpka-cnt”、“clitcpka-intvl”。 **`clitcpka-intvl `** ```haproxy clitcpka-intvl ``` 设置客户端侧单个 keepalive 探测之间的时间间隔。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是两次保活探测之间的时间。默认单位为秒，也可在数值后添加单位后缀， 使用其他单位，详见本文开头的说明。 ``` 此关键字对应套接字选项 TCP_KEEPINTVL。若未指定此关键字，则使用系统级 TCP 参数（tcp_keepalive_intvl）。该设置的可用性取决于操作系统。已知其在 Linux 上可用。 另请参阅：“option clitcpka”、“clitcpka-cnt”、“clitcpka-idle”。 **`compression algo ...`** ```haproxy compression algo ... compression algo-req compression algo-res compression type ... ``` 启用 HTTP 压缩。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text algo 后接受支持的响应压缩算法列表（旧版关键字）。 algo-req 后接请求压缩算法（仅提供一种）。 algo-res 后接受支持的响应压缩算法列表。 type 后接要压缩的响应 MIME 类型列表（旧版关键字）。 type-req 后接要压缩的请求 MIME 类型列表。 type-res 后接要压缩的响应 MIME 类型列表。 ``` 当前支持的算法如下： ```text identity 主要用于调试，曾用于开发压缩功能。Identity 不对数据作任何修改。 gzip 应用 gzip 压缩，仅在编译时启用了 zlib 或 libslz 支持时可用。 deflate 与 "gzip" 相同，但使用 deflate 算法和 zlib 格式。 许多浏览器对此算法的支持含糊不清，近期浏览器甚至完全不支持。 强烈建议仅用于实验。仅在编译时启用了 zlib 或 libslz 支持时可用。 raw-deflate 与 "deflate" 相同，但不使用 zlib 封装，在浏览器要求 "deflate" 时用作替代方案。 所有主流浏览器均能理解它；尽管违反标准，已知它至少在 MSIE 和某些 Safari 版本中 比 "deflate" 工作得更好。不要与 "deflate" 同时使用，二者只能择一， 因为都会响应同一个 Accept-Encoding 词元。仅在编译时启用了 zlib 或 libslz 支持时可用。 ``` 压缩功能将根据请求头中的 Accept-Encoding 决定是否启用。若设置为 identity，则忽略该请求头。若后端服务器支持 HTTP 压缩，这些指令将无操作：HAProxy 会识别已压缩的响应，不再进行二次压缩。若后端服务器不支持 HTTP 压缩，且请求中包含 Accept-Encoding 头，则 HAProxy 将对匹配的响应进行压缩。 当满足以下任一条件时，压缩功能将被禁用： - 请求未在 "Accept-Encoding" 头中声明支持的压缩算法 - 响应消息的协议版本低于 HTTP/1.1 - HTTP 状态码不是 200、201、202 或 203 之一 - 响应既不包含 "Content-Length" 头，也不包含 "Transfer-Encoding" 头且其最后一个值不是 "chunked" - 响应包含 "Content-Type" 头，且其首个值以 "multipart" 开头 - 响应包含 "Cache-control" 头且其值包含 "no-transform" - User-Agent 匹配 "Mozilla/4"，除非其为 MSIE 6 且运行于 XP SP2，或 MSIE 7 及更高版本 - 响应包含 "Content-Encoding" 头，表明响应已压缩（参见压缩卸载） - 响应包含无效的 "ETag" 头或多个 ETag 头 - 负载大小小于最小大小（参见 compression minsize-res） 请注意：压缩功能不会发出 Warning 头。 示例： ```text compression algo gzip compression type text/html text/plain ``` 另请参阅：“compression offload”、“compression direction”、“compression minsize-req”和“compression minsize-res” **`compression minsize-req `** ```haproxy compression minsize-req compression minsize-res ``` 设置应用压缩功能的最小负载大小（以字节为单位）。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 小于该大小的负载将不会被压缩，以避免对无法显著受益于压缩的数据造成不必要的 CPU 开销。“minsize-req” 适用于请求，“minsize-res” 适用于响应。默认值为 0。 **`compression offload`** ```haproxy compression offload ``` 使 HAProxy 仅作为压缩卸载器工作。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| yes offload 设置会使 HAProxy 移除 Accept-Encoding 头，以防止后端服务器对响应进行压缩。强烈建议不要执行此操作，因为这意味着所有压缩工作都将集中于 HAProxy 所在的单一节点上。然而在某些部署场景中，HAProxy 可能位于存在缺陷的网关前端，而该网关的 HTTP 压缩实现存在缺陷且无法关闭。在此情况下，HAProxy 可用于防止该网关发出无效负载。在这种场景下，仅在配置中移除头信息无效，因为该操作在头信息被解析前执行，从而阻止了 HAProxy 自身进行压缩。此时应使用 offload 设置。 如果在 defaults 段中使用此设置，将发出警告并忽略该选项。 另请参阅：“压缩类型”、“压缩算法”、“压缩方向” **`compression direction (deprecated)`** ```haproxy compression direction (deprecated) ``` 使 HAProxy 能够压缩请求和响应。有效值为 "request"，仅压缩请求；"response"，仅压缩响应；或 "both"，当需要同时压缩请求和响应时使用。默认值为 "response"。 该指令仅在启用旧版“过滤器压缩”时才相关，因为当显式使用 comp-req 和 comp-res 过滤器时，压缩方向已冗余。 可用于以下上下文：http 另请参阅："compression type"、"compression algo"、"compression offload" **`cookie [ rewrite | insert | prefix ] [ indirect ] [ nocache ]`** ```haproxy cookie [ rewrite | insert | prefix ] [ indirect ] [ nocache ] [ postonly ] [ preserve ] [ httponly ] [ secure ] [ domain ]* [ maxidle ] [ maxlife ] [ dynamic ] [ attr ]* ``` 在后端中启用基于 Cookie 的持久性。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是为实现会话保持而监控、修改或插入的 Cookie 名称。 通过响应中的 "Set-Cookie" 头发送给客户端，再由客户端在所有请求的 "Cookie" 头中带回。 应谨慎选择名称，避免与应用可能使用的 Cookie 冲突。 同一客户端可能使用相同后端（例如 HTTP/HTTPS）时， 若不希望在后端之间保持会话，应为各后端使用不同的 Cookie 名称。 rewrite 表示由服务器提供 Cookie，HAProxy 修改其值，将服务器标识符写入其中。 将复杂的 "Set-cookie" 与 "Cache-control" 头组合交给应用管理时，此模式十分方便。 应用可自行决定是否适合发送会话保持 Cookie。 由于必须监控所有响应，此模式不适用于 HTTP 隧道模式。 除非应用行为十分复杂或存在缺陷，否则不建议新部署从此模式开始。 此关键字与 "insert"、"prefix" 不兼容。 insert 若客户端尚未具有能让其访问此服务器的 Cookie，则由 HAProxy 在服务器响应中插入会话保持 Cookie。 未使用 "preserve" 选项时，服务器发送的同名 Cookie 会在处理前移除， 因此可用此模式升级原先采用 "rewrite" 模式的配置。 插入的 Cookie 仅为会话 Cookie，不存储到客户端磁盘。 默认情况下，除非添加 "indirect" 选项，否则服务器会看到客户端发送的 Cookie。 考虑缓存影响，通常应添加 "nocache" 或 "postonly"（见下文）。 "insert" 与 "rewrite"、"prefix" 不兼容。 prefix 表示不依赖专用的会话保持 Cookie，而是补充现有 Cookie。 某些特殊环境中，客户端仅支持单个 Cookie，且应用已需要该 Cookie，此模式可能有用。 服务器设置名为 的 Cookie 时，在其值前添加服务器标识符和分隔符。 所有客户端请求中的该前缀会被移除，使服务器仍能读到原先发送的 Cookie。 由于所有请求和响应均可能被修改，此模式不适用于隧道模式。 "prefix" 与 "rewrite"、"insert" 不兼容。 注意：强烈建议不要将 "indirect" 与 "prefix" 组合，否则服务器更新的 Cookie 不会发送给客户端。 indirect 已有对应处理请求的服务器的有效 Cookie 时，不再向客户端发送 Cookie。 服务器自行设置此类 Cookie 时，会将其移除，除非同时设置 "preserve"。 在 "insert" 模式下，还会从发往服务器的请求中移除 Cookie， 从应用的角度使会话保持机制完全透明。 注意：强烈建议不要将 "indirect" 与 "prefix" 组合，否则服务器更新的 Cookie 不会发送给客户端。 nocache 客户端与 HAProxy 之间存在缓存时，推荐与插入模式组合。 需要插入 Cookie 时，确保将本可缓存的响应标记为不可缓存。 例如，若所有会话保持 Cookie 都在可缓存的主页中插入，所有用户会从外部缓存获取页面， 并共享同一会话保持 Cookie，导致一台服务器接收远多于其他服务器的流量。 另见 "insert" 和 "postonly"。 postonly 确保仅在 POST 请求的响应中插入 Cookie，可替代 "nocache"。 POST 响应不可缓存，因而会话保持 Cookie 不会被缓存。 大多数站点在首次 POST（通常为登录请求）之前不需要会话保持， 因此此方法可高效优化缓存，而不必担心缓存中出现会话保持 Cookie。 另见 "insert" 和 "nocache"。 preserve 仅可与 "insert" 和/或 "indirect" 组合，允许服务器自行发送会话保持 Cookie。 响应中存在该 Cookie 时，HAProxy 不修改它，例如可用于在登出请求后结束会话保持。 服务器只需发送值无效（如空值）或日期已过期的 Cookie。 与 "disable-on-404" 检查选项组合，可实现完全优雅关闭， 因为用户登出后会确定离开该服务器。 httponly 告诉 HAProxy 在插入 Cookie 时添加 "HttpOnly" 属性， 防止用户代理与非 HTTP 组件共享 Cookie。此属性详情见 RFC6265。 secure 告诉 HAProxy 在插入 Cookie 时添加 "Secure" 属性， 防止用户代理通过不安全通道发送该 Cookie；带此标志的 Cookie 仅通过 SSL/TLS 连接发送。 此属性详情见 RFC6265。 domain 指定插入 Cookie 的域，必须且只能接受一个参数：有效域名。 域名以点号开头时，浏览器可将 Cookie 用于所有以此名称结尾的主机。 可重复使用此选项指定多个域名。某些浏览器可能限制域名数量，应谨慎使用。 作为参考，向 MSIE 6 或 Firefox 2 发送 10 个域名可以正常工作。 maxidle 允许在空闲一段时间后忽略插入的 Cookie，仅适用于插入模式。 向客户端发送 Cookie 时，同时发送其发出日期。 客户端再次提供 Cookie 时，若日期超过参数指定的时长（秒），则忽略该 Cookie； 否则，在响应发送给客户端时按需刷新。 适合防止永不关闭浏览器的用户在同一服务器上停留过久，例如服务器群规模变更后。 设置此选项且 Cookie 没有日期时，始终接受，但在响应中刷新，以保留管理员访问站点的能力。 日期超过当前时间向后 24 小时的 Cookie 会被忽略， 以便管理员修复时区问题，而不冒着将用户踢出站点的风险。 maxlife 允许在存活一段时间后忽略插入的 Cookie，无论其是否正在使用，仅适用于插入模式。 首次向客户端发送 Cookie 时，同时发送其发出日期。 客户端再次提供 Cookie 时，若日期超过参数指定的时长（秒），则忽略该 Cookie。 请求的 Cookie 没有日期时，接受该 Cookie 并设置日期。 日期超过当前时间向后 24 小时的 Cookie 会被忽略， 以便管理员修复时区问题，而不冒着将用户踢出站点的风险。 与 maxidle 不同，此值不会刷新，仅首次访问日期有效。maxidle 和 maxlife 可同时使用。 适合防止永不关闭浏览器的用户在同一服务器上停留过久，例如服务器群规模变更后。 比 maxidle 更强，因为经过固定时长后强制重分派。 dynamic 启用动态 Cookie。根据服务器 IP、端口及 "dynamic-cookie-key" 后端指令指定的密钥， 为每台服务器动态创建会话 Cookie。IP 地址每次变化时重新生成，仅针对 IPv4/IPv6 生成。 attr 告诉 HAProxy 在插入 Cookie 时添加额外属性。 属性值可包含除控制字符和 ";" 以外的任何字符。此选项可重复使用。 ``` 每个 HTTP 后端只能有一个持久性 cookie，该 cookie 可在 defaults 段中声明。cookie 的值将为服务器语句中 "cookie" 关键字后指定的值。若未为某个服务器声明 cookie，则不会设置 cookie。 示例： ```text cookie JSESSIONID prefix cookie SRV insert indirect nocache cookie SRV insert postonly indirect cookie SRV insert indirect nocache maxidle 30m maxlife 8h ``` 另请参阅：“balance source”、“capture cookie”、“server”和“ignore-persist”。 **`declare capture [ request | response ] len `** ```haproxy declare capture [ request | response ] len ``` 声明一个捕获槽。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text 是允许捕获的长度。 ``` 此声明仅可在前端或 listen 段中使用，但预留的槽位可在后端中使用。“request”关键字用于为请求分配一个捕获槽位，“response”关键字用于为响应分配一个捕获槽位。 另请参阅：“capture-req”、“capture-res”（样本转换器）、"capture.req.hdr"、"capture.res.hdr"（样本提取）、“http-request capture”和“http-response capture”。 **`default-server [param*]`** ```haproxy default-server [param*] ``` 更改后端中服务器的默认选项 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是此服务器的参数列表。"default-server" 关键字支持大量选项，有专门的一节完整介绍。 更多详情见第 5 节。 ``` 示例： ```text default-server inter 1000 weight 13 ``` 另请参阅：“server”以及 [第 5 节](/zh/docs/haproxy/bind-and-server-options/) 中关于服务器选项的内容 **`default_backend `** ```haproxy default_backend ``` 当未匹配任何 "use_backend" 规则时，指定要使用的后端。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是要使用的后端名称。 ``` 使用 "use_backend" 关键字在前端与后端之间进行内容切换时，通常需要明确指定当无规则匹配时将使用的后端。这通常是动态后端，用于捕获所有未确定的请求。 如果后端被禁用或未发布，针对该后端的 default_backend 规则将被忽略，流处理将继续在原始代理上进行。 示例： ```text use_backend dynamic if url_dyn use_backend static if url_css url_img extension_img default_backend dynamic ``` 另请参阅："use_backend" **`description `** ```haproxy description ``` 描述一个 listen、frontend 或 backend。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| yes 参数：string 允许在 HAProxy HTML 统计信息页面中为相关对象添加描述语句。描述内容将显示在所描述对象名称的右侧。`` 参数中无需转义空格。 **`disabled`** ```haproxy disabled ``` 禁用代理、前端或后端。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 “disabled” 关键字用于禁用实例，主要用于释放监听端口或临时停用服务。实例仍将被创建并进行配置检查，但将以“已停止”状态创建，并在统计信息中显示为已停止状态。该实例不会接收任何流量，也不会发送健康检查或日志。可以通过在“defaults”段中添加“disabled”关键字，一次性禁用多个实例。 默认情况下，无法选择已禁用的后端进行内容切换。然而，当使用 "force-be-switch" 时，部分流量可忽略此限制。 另请参阅："enabled"，"force-be-switch" **`dispatch
: (deprecated)`** ```haproxy dispatch
: (deprecated) ``` 设置默认服务器地址 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| no \| yes \| yes 参数： ```text
是默认服务器的 IPv4 地址。也支持可解析的主机名，但该名称在启动期间解析。 是必需的端口参数。所有连接均发送到此端口，不允许像普通服务器那样使用端口偏移。 ``` dispatch 指令 "dispatch" 指令用于指定在无法连接到其他服务器时使用的默认服务器。过去，该指令曾用于将非持久连接转发至辅助负载均衡器。由于其语法简单，也曾被用于实现简单的 TCP 中继。为提高配置清晰度，建议不再使用该指令，而应改用 "server" 指令。 该关键字已在 3.3 版本中弃用，并将在 3.5 版本中移除，原因在于存在一些内部限制（例如不支持 SSL 或空闲连接等）。使用该关键字将发出警告，可通过在全局段启用指令 "expose-deprecated-directives" 来静默此警告。 正确做法是，不使用该指令时，只需声明一个地址和端口相同的服务器。如果“dispatch”指令与其他服务器混合使用，则应将这些服务器的权重配置为零，以确保负载均衡算法永远不会选择它们。 示例： ```text backend deprecated_setup dispatch 192.168.100.100:80 # external load balancer's address server s1 192.168.100.1:80 cookie S1 check server s2 192.168.100.2:80 cookie S2 check backend modern_setup server external_lb 192.168.100.100:80 server s1 192.168.100.1:80 cookie S1 check weight 0 server s2 192.168.100.2:80 cookie S2 check weight 0 ``` 另请参阅："server" **`dynamic-cookie-key `** ```haproxy dynamic-cookie-key ``` 为后端设置动态 Cookie 密钥。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：用于的密钥。 当启用动态 cookie（参见 cookie 指令中的 "dynamic" 选项）时，将为每个服务器创建一个动态 cookie（除非在 "server" 指令中显式指定），该 cookie 通过服务器的 IP 地址、TCP 端口和密钥的哈希值生成。这样可确保在多个负载均衡器之间实现会话持久性，即使服务器动态添加或移除也能保持会话连续。 **`enabled`** ```haproxy enabled ``` 启用代理、前端或后端。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 "enabled" 关键字用于显式启用实例，当默认值已设为 "disabled" 时使用。此用法极为罕见。 另请参阅："be-unpublished"、"disabled" **`errorfile `** ```haproxy errorfile ``` 返回文件内容，而非 HAProxy 生成的错误信息 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是 HTTP 状态码。目前 HAProxy 可生成的状态码为 200、400、401、403、404、405、407、408、410、413、414、425、429、431、500、501、502、503 和 504。 指定包含完整 HTTP 响应的文件。建议遵循常见做法，在文件名末尾添加 ".http"， 避免将响应与 HTML 错误页面混淆；还应使用绝对路径，因为文件在执行 chroot 之前读取。 ``` 必须理解，该关键字并非用于重写服务器返回的错误，而是用于重写 HAProxy 检测并返回的错误。这也是为何支持的错误列表被限制在较小的集合中。 状态码 200 在响应匹配 "monitor-uri" 规则的请求时发出。 HAProxy 启动时会解析这些文件，且必须符合 HTTP 规范。文件大小不得超过配置的缓冲区大小（BUFSIZE），通常为 16 kB，否则将返回内部错误。建议不要引用本地内容（例如图片），以避免在所有服务器均不可用时，客户端与 HAProxy 之间产生循环，导致返回错误而非图片。最后，响应大小不得超过（tune.bufsize - tune.maxrewrite），以确保“http-after-response”规则仍有操作空间（参见 "tune.maxrewrite"）。 文件在读取配置的同时被加载并保留在内存中。因此，即使进程已执行 chroot，错误仍会持续返回，且在进程运行期间不会考虑文件的任何变更。开发这些文件的一种简单方法是将其与 403 状态码关联，并查询一个被阻止的 URL。 另请参阅："http-error", "errorloc", "errorloc302", "errorloc303" 示例： ```text errorfile 400 /etc/haproxy/errorfiles/400badreq.http errorfile 408 /dev/null # work around Chrome pre-connect bug errorfile 403 /etc/haproxy/errorfiles/403forbid.http errorfile 503 /etc/haproxy/errorfiles/503sorry.http ``` **`errorfiles [ ...]`** ```haproxy errorfiles [ ...] ``` 导入在 `` http-errors 段中定义的错误文件，可全部或部分导入。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是已存在的 http-errors 段的名称。 是 HTTP 状态码，可列出多个。目前 HAProxy 可生成的状态码为 200、400、401、403、404、405、407、408、410、413、414、425、429、431、500、501、502、503 和 504。 ``` 在 http-errors 段中定义的名称为 `` 的错误会被导入当前代理。 若未指定状态码，则导入 http-errors 段中的所有错误文件。否则，仅导入与所列状态码关联的错误文件。这些错误文件将覆盖代理中已定义的自定义错误，且可能被后续导入的错误文件覆盖。 在功能上，这与手动使用 "errorfile" 指令声明所有错误文件完全相同。 有关 HTTP 错误的更多信息，请参阅 "http-error"、"errorfile"、"errorloc"、"errorloc302"、"errorloc303" 以及 [第 12.4 节](/zh/docs/haproxy/other-sections/#section-12-4)。 示例： ```text errorfiles generic errorfiles site-1 403 404 ``` **`errorloc `** ```haproxy errorloc errorloc302 ``` 返回 HTTP 重定向至指定 URL，而非 HAProxy 生成的错误 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是 HTTP 状态码。目前 HAProxy 可生成的状态码为 200、400、401、403、404、405、407、408、410、413、414、425、429、431、500、501、502、503 和 504。 是 "Location" 头的确切内容，可以是同一站点错误页面的相对 URI， 或另一站点错误页面的绝对 URI。使用相对 URI 时应格外谨慎， 避免 URI 本身产生同样的错误（例如 500）而导致重定向循环。 ``` 必须理解，该关键字并非用于重写服务器返回的错误，而是用于重写 HAProxy 检测并返回的错误。这也是为何支持的错误列表被限制在较小的集合中。 状态码 200 在响应匹配 "monitor-uri" 规则的请求时发出。 请注意，这两个关键字均返回 HTTP 302 状态码，指示客户端使用相同的 HTTP 方法获取指定的 URL。在使用非 GET 方法（如 POST）时，这可能会造成问题，因为发送给客户端的 URL 可能不允许用于除 GET 以外的其他方法。为规避此问题，请使用 "errorloc303"，该关键字发送 HTTP 303 状态码，指示客户端必须使用 GET 请求获取该 URL。 另请参阅："http-error"、"errorfile"、"errorloc303" **`errorloc303 `** ```haproxy errorloc303 ``` 返回 HTTP 重定向至指定 URL，而非 HAProxy 生成的错误 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是 HTTP 状态码。目前 HAProxy 可生成的状态码为 200、400、401、403、404、405、407、408、410、413、414、425、429、431、500、501、502、503 和 504。 是 "Location" 头的确切内容，可以是同一站点错误页面的相对 URI， 或另一站点错误页面的绝对 URI。使用相对 URI 时应格外谨慎， 避免 URI 本身产生同样的错误（例如 500）而导致重定向循环。 ``` 必须理解，该关键字并非用于重写服务器返回的错误，而是用于重写 HAProxy 检测并返回的错误。这也是为何支持的错误列表被限制在较小的集合中。 状态码 200 在响应匹配 "monitor-uri" 规则的请求时发出。 请注意，这两个关键字均返回 HTTP 303 状态码，该码指示客户端使用相同的 HTTP GET 方法获取指定的 URL。这解决了与“errorloc”和 302 状态码相关联的常见问题。尽管可能存在一些在 HTTP/1.1 之前设计的老旧浏览器不支持此行为，但截至目前尚未报告此类问题。 另请参阅："http-error"、"errorfile"、"errorloc"、"errorloc302" **`email-alert from `** ```haproxy email-alert from ``` 声明用于邮件警报信封和头中的发件人地址。此地址即为邮件警报的发送来源。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是发送邮件告警时使用的发件人邮箱地址。 ``` 还要求设置 "email-alert mailers" 和 "email-alert to"，若已设置，则为该代理启用邮件告警功能。 另请参阅：“email-alert level”、“email-alert mailers”、“email-alert myhostname”、“email-alert to”，以及关于邮件发送器的[第 12.3 节](/zh/docs/haproxy/other-sections/#section-12-3)。 **`email-alert level `** ```haproxy email-alert level ``` 声明将发送邮件告警的消息最大日志级别。这将作为邮件告警发送的过滤器。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 为 8 个 syslog 级别之一： emerg alert crit err warning notice info debug 上述 syslog 级别按从低到高的顺序排列。 ``` 默认级别为 alert 还要求设置 "email-alert from"、"email-alert mailers" 和 "email-alert to"，若已设置，则为该代理启用邮件告警功能。 当满足以下条件时发送告警： - 未暂停的服务器被标记为不可用，且 `` 的日志级别为 alert 或更低 - 暂停的服务器被标记为不可用，且 `` 的日志级别为 notice 或更低 - 服务器被标记为可用或进入 drain 状态，且 `` 的日志级别为 notice 或更低 - 启用了 "option log-health-checks"，`` 的日志级别为 info 或更低，且发生健康检查状态更新 另请参阅：“email-alert from”、“email-alert mailers”、“email-alert myhostname”、“email-alert to”，以及关于邮件发送器的[第 12.3 节](/zh/docs/haproxy/other-sections/#section-12-3)。 **`email-alert mailers `** ```haproxy email-alert mailers ``` 声明用于发送邮件告警的邮件发送器 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是用于发送邮件告警的 mailers 段的名称。 ``` 还要求设置 "email-alert from" 和 "email-alert to"，若已设置，则为该代理启用邮件告警功能。 另请参阅："email-alert from"、"email-alert level"、"email-alert myhostname"、"email-alert to"，以及关于邮件发送器的[第 12.3 节](/zh/docs/haproxy/other-sections/#section-12-3)。 **`email-alert myhostname `** ```haproxy email-alert myhostname ``` 声明用于与邮件发送器通信时的主机名地址。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是与 mailers 通信时使用的主机名。 ``` 默认情况下，使用系统的主机名。 还要求设置 "email-alert from"、"email-alert mailers" 和 "email-alert to"，若已设置，则为该代理启用邮件告警功能。 另请参阅：“email-alert from”、“email-alert level”、“email-alert mailers”、“email-alert to”，以及关于邮件发送器的[第 12.3 节](/zh/docs/haproxy/other-sections/#section-12-3)。 **`email-alert to `** ```haproxy email-alert to ``` 声明邮件警报信封中的收件人地址以及邮件头中的收件人地址。 此地址为邮件警报的发送目标。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是发送邮件告警时使用的收件人邮箱地址。 ``` 还要求设置 "email-alert mailers" 和 "email-alert to"，若已设置，则为该代理启用邮件告警功能。 另请参阅："email-alert from"、"email-alert level"、"email-alert mailers"、"email-alert myhostname"，以及关于邮件发送器的 [第 12.3 节](/zh/docs/haproxy/other-sections/#section-12-3)。 **`error-log-format `** ```haproxy error-log-format ``` 指定在前端发生连接错误时所使用的日志格式字符串。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 该指令指定用于记录与错误、超时、重试、重分派或 HTTP 状态码 5xx 相关信息的日志格式字符串。该格式将简要用于所有受“log-separate-errors”选项影响的日志行，包括 [第 8.2.5 节](/zh/docs/haproxy/configuration-logging/#section-8-2-5)中描述的连接错误。 若该指令在 defaults 段中使用，则后续所有前端均将采用相同的日志格式。请参见 [第 8.2.6 节](/zh/docs/haproxy/configuration-logging/#section-8-2-6)，其中详细介绍了自定义日志格式字符串。 "error-log-format" 指令会覆盖之前的 "error-log-format" 指令。 **`force-persist { if | unless } `** ```haproxy force-persist { if | unless } ``` 声明一个条件，以强制对已关闭的服务器保持持久性 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| no \| yes \| yes 默认情况下，请求不会被分派至处于关闭状态的服务器。可以使用“option persist”强制分派，但该选项无条件生效，若设置了“option redispatch”，则会在有可用服务器时进行重分派。这使得强制某些请求到达因维护操作而被人为标记为关闭的服务器变得几乎不可能。 "force-persist" 语句允许声明多种基于 ACL 的条件，当这些条件满足时，请求将忽略服务器的宕机状态，仍尝试与其建立连接。这使得可以在服务器启动后，仍对健康检查返回错误，同时使用经过特殊配置的浏览器来测试服务。其中一种便捷的方法是使用特定的源 IP 地址，或特定的 Cookie。Cookie 的优势在于，可通过测试页面轻松地在浏览器中添加或移除。服务验证完成后，即可通过向健康检查返回有效响应，将服务对公众开放。 当满足 "if" 条件时，强制持久化功能被启用，或在满足 "unless" 条件时被禁用。使用此功能时，最终的重分派始终被禁用。 另请参阅：“option redispatch”、“ignore-persist”、“persist”以及[第 7 节](/zh/docs/haproxy/acls-and-samples/)中关于 ACL 使用的说明。 **`external-check command `** ```haproxy external-check command ``` 执行外部检查时运行的可执行文件 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是要运行的外部命令。 ``` 传递给命令的参数如下： `` `` `` `` `` 和 `` 由首个 IPv4、IPv6 或 Unix 套接字类型的监听器推导得出。若监听器为 Unix 套接字，则代理地址（proxy_address）为套接字路径，`` 的值为字符串 "NOT_USED"。在后端段中，无法确定监听器，因此 `` 和 `` 的值均为字符串 "NOT_USED"。 部分值也可通过环境变量提供。 环境变量： ```text HAPROXY_PROXY_ADDR 第一个 bind 地址（若可用）；不适用时为空，例如在 "backend" 段中。 HAPROXY_PROXY_ID 后端 ID。 HAPROXY_PROXY_NAME 后端名称。 HAPROXY_PROXY_PORT 第一个 bind 端口（若可用）；不适用时为空，例如在 "backend" 段中或使用 UNIX 套接字时。 HAPROXY_SERVER_ADDR 服务器地址。 HAPROXY_SERVER_CURCONN 服务器当前连接数。 HAPROXY_SERVER_ID 服务器 ID。 HAPROXY_SERVER_MAXCONN 服务器最大连接数。 HAPROXY_SERVER_NAME 服务器名称。 HAPROXY_SERVER_PORT 服务器端口（若可用）；UNIX 套接字时为空。 HAPROXY_SERVER_SSL 未使用 SSL 时为 "0"，使用时为 "1"。 HAPROXY_SERVER_PROTO 服务器使用的协议，可为 "cli"（haproxy CLI）、"syslog"（syslog TCP 服务器）、 "peers"（peers TCP 服务器）、"h1"（HTTP/1.x 服务器）、"h2"（HTTP/2 服务器） 或 "tcp"（任何其他 TCP 服务器）。 PATH 执行命令时使用的 PATH 环境变量，可通过 "external-check path" 设置。 ``` 如果执行的命令退出状态为零，则认为检查通过；否则认为检查失败。 示例： ```text external-check command /bin/true ``` 另请参阅："external-check"、"option external-check"、"external-check path" **`external-check path `** ```haproxy external-check path ``` 运行外部检查时所使用的 PATH 环境变量的值 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是执行外部命令时使用的路径。 ``` 默认路径为空字符串。 示例： ```text external-check path "/usr/bin:/bin" ``` 另请参阅："external-check"、"option external-check"、"external-check command" **`force-be-switch { if | unless } `** ```haproxy force-be-switch { if | unless } ``` 允许内容切换选择已禁用或未发布的后端实例。此规则可供管理员在将服务对外暴露前，用于测试流量。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 另请参阅："disabled" **`filter [param*]`** ```haproxy filter [param*] ``` 在附加到代理的过滤器列表中添加过滤器 ``。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| yes 参数： ```text 是过滤器名称。官方支持的过滤器见第 9 节。 是过滤器 接受的参数列表，其解析由过滤器负责。 所有支持的参数详情见相应过滤器的文档（第 9 节）。 ``` 同一代理可多次使用过滤器行。如需，同一过滤器可被多次引用。 示例： ```text listen bind *:80 filter trace name BEFORE-HTTP-COMP filter compression filter trace name AFTER-HTTP-COMP compression algo gzip compression offload server srv1 192.168.0.1:80 ``` 另请参阅：[第 9 节](/zh/docs/haproxy/filters/)。 **`fullconn `** ```haproxy fullconn ``` 指定后端负载达到多少时，服务器将达到最大连接数 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是让服务器使用最大连接数时所需的后端连接数。 ``` 当服务器配置了 "maxconn" 参数时，表示其并发连接数将不会超过该值。此外，若同时配置了 "minconn" 参数，则表示该限制为动态值，随后端负载变化而调整。此时，服务器将始终至少接受 `` 个连接，且不会超过 `` 个连接，当后端并发连接数低于 `` 时，该限制将在两个数值之间动态调整。这使得在正常负载下可限制服务器负载，而在重要负载时可适度提升负载能力，同时在异常负载情况下避免服务器过载。 由于很难准确设置该值，HAProxy 会自动将其设为所有可能转向此后端的前端（基于 "use_backend" 和 "default_backend" 规则）的 maxconns 之和的 10%。因此，可以安全地不显式设置该值。然而，涉及动态名称的 "use_backend" 不会被计入，因为无法判断其是否可能匹配。 示例： ```shell # The servers will accept between 100 and 1000 concurrent connections each # and the maximum of 1000 will be reached when the backend reaches 10000 # connections. backend dynamic fullconn 10000 server srv1 dyn1:80 minconn 100 maxconn 1000 server srv2 dyn2:80 minconn 100 maxconn 1000 ``` 另请参阅：“maxconn”、“server” **`guid `** ```haproxy guid ``` 为该代理指定一个区分大小写的全局唯一 ID。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| yes `` 必须在所有 HAProxy 配置中针对每种对象类型保持唯一。格式未作限定，以允许用户自行选择命名策略。唯一限制是其长度不得超过 127 个字符。所有字母数字字符以及 '.'、':'、'-' 和 '\_' 均为有效字符。参见“shm-stats-file”。 **`hash-balance-factor `** ```haproxy hash-balance-factor ``` 指定有界负载一致性哈希的均衡因子 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| no \| yes 参数： ```text 控制发送到服务器的最大并发请求数，表示为所有活跃服务器平均并发请求数的百分比。 ``` 为使用 "hash-type consistent" 的服务器指定 "hash-balance-factor" 可启用一种算法，该算法可防止任一服务器在短时间内接收过多请求，即使某些哈希桶接收的请求远多于其他桶。将 `` 设置为 0（默认值）可禁用此功能。否则，`` 必须为大于 100 的百分比。例如，若 `` 为 150，则任一服务器的负载不得超过平均负载的 1.5 倍。若使用服务器权重，将予以尊重。 如果首选服务器被排除，算法将根据请求哈希选择另一台服务器，直至找到具有额外容量的服务器。较高的 `` 会导致服务器间负载不平衡程度增加，而较低的 `` 意味着平均需检查的服务器数量更多，从而影响性能。合理的取值范围为 125 至 200。 此设置也由“balance random”使用，后者内部依赖一致性哈希机制。 另请参阅：“balance” 和 “hash-type”。 **`hash-preserve-affinity { always | maxconn | maxqueue }`** ```haproxy hash-preserve-affinity { always | maxconn | maxqueue } ``` 指定在服务器已饱和或队列已满时，使用哈希负载均衡将流分配至服务器的方法。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 以下值可以指定： - "always"：这是默认策略。无论服务器当前是否饱和，都基于哈希将流 分配给服务器。 - "maxconn"：选用时，已设置 "maxconn" 且当前已饱和的服务器将被跳过， 并沿哈希环选取另一台服务器。这对未设置 "maxconn" 的服务 器没有影响。若所有服务器均已饱和，请求将被排入哈希环中 位于初始选定服务器之前的最后一台服务器的队列。 - "maxqueue"：选用时，已设置 "maxconn"、"maxqueue" 为非零值（受限队列 大小）且当前队列已满的服务器将被跳过。并沿哈希环选取另一 台服务器。这对未同时设置 "maxconn" 和 "maxqueue" 的服务 器没有影响。 另请参阅："maxconn"、"maxqueue"、"hash-balance-factor" **`hash-type `** ```haproxy hash-type ``` 指定用于将哈希映射到服务器的方法 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是从 计算的哈希中选择服务器的方法： map-based 哈希表是包含所有存活服务器的静态数组。哈希分布十分平滑，且考虑权重， 但服务器上线期间的权重变更会被忽略，因此不支持慢启动。 由于按数组位置选择服务器，服务器数量变化时大多数映射会改变。 服务器上线、离线或新增时，大多数连接被重新分配到不同服务器，这对缓存等场景可能不便。 consistent 哈希表是树，每台服务器在树中出现多次。在树中查找哈希键，选择最接近的服务器。 此哈希是动态的，支持服务器上线期间更改权重，因而兼容慢启动。 服务器上线或离线时，仅移动其关联关系；新增服务器时，仅重新分配少量映射，十分适合缓存。 但其原理决定了分布不会十分平滑，有时需调整服务器权重或 ID 以改善均衡。 要在多个负载均衡器上得到相同分布，所有服务器必须具有完全相同的 ID。 注意：未指定哈希函数时，一致性哈希使用 sdbm 和 avalanche。 是要使用的哈希函数： sdbm 最初为 sdbm 数据库库设计，该库是 ndbm 的公有领域重新实现。 此函数擅长打散位，改善键的分布并减少分裂，也是一种分布良好的通用哈希函数。 但服务器总权重为 64 的倍数时，使用 avalanche 修饰符可能有帮助。 djb2 多年前由 Dan Bernstein 在 comp.lang.c 首次提出。 研究表明，某些工作负载下分布优于 sdbm。通常适合文本输入， 但仅包含数值的输入或服务器总权重为 33 的倍数时，性能可能极差，除非同时使用 avalanche。 wt6 过去测试其他函数时为 HAProxy 设计。分布不如其他函数平滑， 但对输入数据集或服务器数量远不那么敏感。 一致性哈希或对源 IP 地址、URL 参数中的访客标识符等数值数据计算哈希时， 可作为 sdbm+avalanche 或 djb2+avalanche 的替代方案。 crc32 Ethernet、gzip、PNG 等使用的常见 CRC32 实现。 比其他函数慢，但可能提供更好的分布或更难预测的结果，尤其用于字符串时。 none 不对键计算哈希，直接将键作为哈希值。 适合先用转换器自行计算哈希，再让 haproxy 直接使用结果。 若键尚未为字符串，先将其转换为字符串，再解析为整数，以该值作为键。 某些输入键类型可能不适用，例如 IP 地址。 指定对键计算哈希后应用的可选方法： avalanche 表示不直接使用上述函数的原始结果，而先应用 4 字节的完整雪崩哈希。 目的是混合前一个哈希得到的位，避免输入仅包含有限数值， 或服务器数量为哈希某个组成部分的倍数时产生不良影响（SDBM 为 64，DJB2 为 33）。 启用后，结果通常更难预测，但不如原始函数平滑。某些工作负载可能需要测试。 此哈希是 Bob Jenkins 提出的众多算法之一。 ``` 默认哈希类型为“基于映射”（map-based），适用于大多数使用场景。默认函数为“sdbm”，函数的选择应基于被哈希值的取值范围。 另请参阅：“balance”、“hash-balance-factor”、“hash-preserve-affinity”、“server” **`http-after-response [ { if | unless } ]`** ```haproxy http-after-response [ { if | unless } ] ``` 对所有第 7 层响应（服务器、应用程序/服务及内部响应）的访问控制。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes 第 7 层处理中，`http-after-response` 语句定义了一组规则。这些规则在前端、监听或后端段中按声明顺序进行评估。由于这些规则作用于响应，因此先应用后端规则，再应用前端规则。任何规则均可选择性地跟随一个基于 ACL 的条件，此时仅当该条件为真时才进行评估。 与 http-response 规则不同，此类规则适用于所有响应，包括服务器响应以及 HAProxy 生成的所有响应。这些规则在响应分析结束时进行评估，位于数据转发阶段之前。 条件在动作执行前进行评估，且该动作仅执行一次。因此，即使某个动作改变了作为条件一部分的元素，也不会造成问题。这也意味着多个动作可以依赖同一条件，只要首个改变条件评估结果的动作执行后，其余动作便会自动隐式禁用。例如，当变量为空时，从多个来源为其赋值，即采用此机制。每个实例中对“http-after-response”语句的数量无限制。 在语法中，“http-after-response”之后的第一个关键字是规则的动作，可选地后接该动作所需的若干参数。支持的动作及其相应语法详见 [第 4.3 节](/zh/docs/haproxy/proxies/#section-4-3) “动作”（请查找标记为“HTTP Aft”的动作）。 该指令仅在命名的 defaults 段中可用，不可用于匿名段。在关联的代理段之前，将先评估 defaults 段中定义的规则。为避免歧义，在此情况下，同一 defaults 段不可同时被具备前端能力的代理和具备后端能力的代理使用。这意味着，listen 段不可使用定义了此类规则的 defaults 段。 请注意：在请求解析早期阶段产生的错误由多路复用器在较低层级处理，早于任何 HTTP 分析阶段。因此，这些错误不会触发 http-after-response 规则集的评估。 示例： ```text http-after-response set-header Strict-Transport-Security "max-age=31536000" http-after-response set-header Cache-Control "no-store,no-cache,private" http-after-response set-header Pragma "no-cache" ``` **`http-check comment `** ```haproxy http-check comment ``` 为后续的 http-check 规则定义注释，若该规则执行失败，将在日志中报告。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是后续 http-check 规则失败时添加到日志中的注释消息。 ``` 仅适用于 connect、send 和 expect 规则。可用于生成用户友好的错误报告。 另请参阅：“option httpchk”、“http-check connect”、“http-check send”和“http-check expect”。 **`http-check connect [default] [port ] [addr ] [send-proxy]`** ```haproxy http-check connect [default] [port ] [addr ] [send-proxy] [via-socks4] [ssl] [sni ] [alpn ] [linger] [proto ] [comment ] ``` 打开一个新连接以执行 HTTP 健康检查 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text comment 定义规则求值失败时报告的消息。 default 使用 server 行的默认选项进行健康检查，仅使用未被重新定义的服务器选项。 port 未设置时，使用检查端口或服务器端口，指定 HAProxy 连接的位置。 必须为 1 到 65535 的有效 TCP 端口整数，或样本提取表达式。 addr 定义健康检查使用的 IP 地址。 send-proxy 发送 PROXY 协议字符串。 via-socks4 通过上游 socks4 代理执行出站健康检查。 ssl 打开加密连接。 sni 指定通过 SSL 执行健康检查时使用的 SNI。 alpn 定义通过 ALPN 通告的协议。协议列表由逗号分隔的协议名称组成， 例如 "h2,http/1.1"。未设置时使用服务器的 ALPN。 proto 强制此连接使用指定的多路复用器协议，必须为可在后端侧使用的 HTTP 复用协议。 可用协议列表通过 haproxy -vv 报告。 linger 干净地关闭连接，而非仅发送 RST。 ``` 与 tcp-check 健康检查类似，可配置用于执行 HTTP 健康检查的连接。该指令还应用于描述涉及多个请求/响应交互的场景，这些交互可能在不同端口上进行，或涉及不同的服务器。 当服务器行中未配置 TCP 端口，且未使用 server port 指令时，http-check 序列的第一步必须使用 "http-check connect" 指定端口。 在 http-check 规则集中，必须包含一个 'connect' 规则，且规则集必须以 'connect' 规则开头。此举旨在确保管理员清楚了解其操作意图。 当连接必须启动规则集时，仍可由 set-var、unset-var 或 comment 规则先行。 示例： ```shell # check HTTP and HTTPs services on a server. # first open port 80 thanks to server line port directive, then # tcp-check opens port 443, ciphered and run a request on it: option httpchk http-check connect http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu http-check expect status 200-399 http-check connect port 443 ssl sni haproxy.1wt.eu http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu http-check expect status 200-399 server www 10.0.0.1 check port 80 ``` 另请参阅：“option httpchk”、“http-check send”、“http-check expect” **`http-check disable-on-404`** ```haproxy http-check disable-on-404 ``` 在健康检查返回 HTTP/404 响应时启用维护模式 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当启用此选项时，返回 HTTP 状态码 404 的服务器将不再参与后续的负载均衡，但仍会接收持久连接。这为 Web 管理员提供了一种非常便捷的服务器优雅关闭方式。需要注意的是，处于此模式下检测到失败的服务器不会触发告警，仅生成通知。若服务器再次返回 2xx 或 3xx 响应，将立即被重新加入服务器池。统计信息页面中，该服务器的状态显示为“NOLB”。请注意，此选项仅在与“httpchk”选项配合使用时生效。若与“http-check expect”选项一同使用，则本选项具有更高优先级，即 404 响应仍被视为软停止。此外，已停止的服务器即使返回 404，仍将持续处于停止状态。此选项仅对运行中的服务器进行评估。 另请参阅：“option httpchk” 和 “http-check expect”。 **`http-check expect [min-recv ] [comment ]`** ```haproxy http-check expect [min-recv ] [comment ] [ok-status ] [error-status ] [tout-status ] [on-success ] [on-error ] [status-code ] [!] ``` 使 HTTP 健康检查考虑响应内容或特定状态码 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text comment 定义规则求值失败时报告的消息。 min-recv 是可选参数，定义对当前 expect 规则求值所需的最少数据量。 接收字节数低于此限制时，检查等待更多数据。可用于消除匹配规则的歧义， 或避免对已知尚不完整的内容执行昂贵的正则匹配。 使用精确字符串时，取字符串长度与此参数的较小值。 设为 -1 时忽略此参数；expect 规则不匹配时，检查等待更多数据。 设为 0 时，求值结果始终是确定的。 ok-status 是可选参数，在 expect 规则求值成功且为 tcp-check 规则集的最后一条规则时， 设置检查状态。支持 "L7OK"、"L7OKC"、"L6OK" 和 "L4OK"： - L7OK : 第 7 层检查通过 - L7OKC: 第 7 层检查有条件通过，将服务器设为 NOLB 状态 - L6OK : 第 6 层检查通过 - L4OK : 第 4 层检查通过 默认使用 "L7OK"。 error-status 是可选参数，在 expect 规则求值发生错误时设置检查状态。 支持 "L7OKC"、"L7RSP"、"L7STS"、"L6RSP" 和 "L4CON"： - L7OKC: 第 7 层检查有条件通过，将服务器设为 NOLB 状态 - L7RSP: 第 7 层响应无效：协议错误 - L7STS: 第 7 层响应错误，例如 HTTP 5xx - L6RSP: 第 6 层响应无效：协议错误 - L4CON: 第 1-4 层连接问题 默认使用 "L7RSP"。 tout-status 是可选参数，在 expect 规则求值超时时设置检查状态。 支持 "L7TOUT"、"L6TOUT" 和 "L4TOUT"： - L7TOUT: 第 7 层（HTTP/SMTP）超时 - L6TOUT: 第 6 层（SSL）超时 - L4TOUT: 第 1-4 层超时 默认使用 "L7TOUT"。 on-success 是可选参数，在 expect 规则求值成功且为 tcp-check 规则集的最后一条规则时， 自定义日志中报告的信息消息。 为自定义日志格式字符串（参见第 8.2.6 节）。 on-error 是可选参数，在 expect 规则求值发生错误时，自定义日志中报告的信息消息。 为自定义日志格式字符串（参见第 8.2.6 节）。 status-code 是可选参数，设置成功或错误时在日志中报告的检查状态码。 是标准 HAProxy 表达式，由样本提取后接若干转换器构成。 指定如何在响应中查找特定模式，可为 "status"、"rstatus"、"hdr"、"fhdr"、"string" 或 "rstring"。 关键字前可加感叹号（"!"）来反转匹配。感叹号与关键字之间允许空格。 所支持关键字的更多详情见下文。 是要查找的模式，可为字符串、正则表达式或包含多个参数的复杂模式。 字符串模式包含空格时，必须使用通常的反斜杠（'\'）转义。 ``` 默认情况下，“option httpchk”认为响应状态码为 2xx 和 3xx 时有效，其余状态码为无效。当使用“http-check expect”时，它将定义何为有效或无效。一个后端中仅支持一条“http-check”语句。若服务器无响应或超时，检查显然会失败。可用的匹配项包括： ```text status : 解析 字符串，检查其中的状态码。 必须为逗号分隔的状态码或状态码范围列表。响应状态码匹配任一状态码， 或落入任一范围时，健康检查响应视为有效。 "status" 前加 "!" 时，状态码匹配则将响应视为无效。 rstatus : 对 HTTP 状态码进行正则表达式检查。响应状态码匹配表达式时，健康检查响应视为有效。 "rstatus" 前加 "!" 时，状态码匹配则将响应视为无效。主要用于检查多个状态码。 hdr { name | name-lf } [ -m ] [ { value | value-lf } [ -m ] : 对 HTTP 响应头检查指定的头模式。名称模式为必需项，值模式为可选项。 未指定值模式时，仅检查头是否存在。 是应用于头名称或头值的匹配方法。 支持 "str"（精确匹配）、"beg"（前缀匹配）、"end"（后缀匹配）、 "sub"（子串匹配）或 "reg"（正则匹配），未指定时使用精确匹配。 使用 "name-lf" 时，将 作为自定义日志格式字符串求值（参见第 8.2.6 节）； 使用 "value-lf" 时，将 作为日志格式字符串求值。 这些参数不能与正则匹配方法组合。头值被视为逗号分隔的列表。 注意，头名称匹配不区分大小写。 fhdr { name | name-lf } [ -m ] [ { value | value-lf } [ -m ] : 对 HTTP 响应头检查指定的完整头模式，与 "hdr" 完全相同， 但检查完整的头值，不将逗号视为分隔符。 string : 检查 HTTP 响应体中的精确字符串匹配。 响应体包含此字符串时，健康检查响应视为有效。 "string" 前加 "!" 时，响应体包含此字符串则将响应视为无效。 可用于检查动态页面末尾必须出现的词，或在检查页面出现特定错误（如堆栈跟踪）时检测故障。 rstring : 对 HTTP 响应体进行正则表达式检查。 响应体匹配表达式时，健康检查响应视为有效。 "rstring" 前加 "!" 时，响应体匹配则将响应视为无效。 可用于检查动态页面末尾必须出现的词，或在检查页面出现特定错误（如堆栈跟踪）时检测故障。 string-lf : 在 HTTP 响应体中匹配自定义日志格式字符串（参见第 8.2.6 节）。 响应体包含对 按日志格式规则求值得到的字符串时，健康检查响应视为有效。 前加 "!" 时，响应体包含此字符串则将响应视为无效。 ``` 请注意，响应大小将受到全局 "tune.bufsize" 选项的限制，该选项默认值为 16384 字节。因此，使用 "string" 或 "rstring" 时，过大的响应可能不包含必需的模式。若确实需要处理大响应，可通过设置全局变量更改默认最大大小。但需注意，解析非常大的响应可能会浪费部分 CPU 周期，尤其是在使用正则表达式时，且始终建议将检查聚焦于较小的资源。 在 http-check 规则集中，最后一个 expect 规则可以是隐式的。如果在最后一个 "http-check send" 之后未指定 expect 规则，则会定义一个隐式的 expect 规则，用于匹配 2xx 或 3xx 状态码。这意味着，即使完全未设置 "http-check" 规则，仅设置了 "option httpchk" 时，该规则同样会被定义。 最后，如果将“http-check expect”与“http-check disable-on-404”结合使用，则当服务器响应 404 时，后者具有优先权。 示例： ```shell # only accept status 200 as valid http-check expect status 200,201,300-310 # be sure a sessid coookie is set http-check expect hdr name "set-cookie" value -m beg "sessid=" # consider SQL errors as errors http-check expect ! string SQL\ Error # consider status 5xx only as errors http-check expect ! rstatus ^5 # check that we have a correct hexadecimal tag before /html http-check expect rstring ``` 另请参阅：“option httpchk”、“http-check connect”、“http-check disable-on-404”和“http-check send”。 **`http-check send [meth ] [{ uri | uri-lf }>] [ver ]`** ```haproxy http-check send [meth ] [{ uri | uri-lf }>] [ver ] [hdr ]* [{ body | body-lf }] [comment ] ``` 在 HTTP 健康检查发送的请求中添加可能的头字段列表和/或请求体。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text comment 定义规则求值失败时报告的消息。 meth 是请求使用的可选 HTTP 方法。未设置时使用 "OPTIONS"，因为该方法通常处理开销较低， 且易于从日志中过滤掉。可使用任何方法，但不建议自行创建非标准方法。 uri 是可选参数，将 HTTP 请求引用的 URI 设为字符串 。 默认值为 "/"，几乎任何服务器均默认可访问；也可改为任何其他 URI，允许查询字符串。 uri-lf 是可选参数，使用自定义日志格式 （参见第 8.2.6 节）设置 HTTP 请求引用的 URI。 默认值为 "/"，几乎任何服务器均默认可访问；也可改为任何其他 URI，允许查询字符串。 ver 是可选的 HTTP 版本字符串，默认值为 "HTTP/1.0"。 某些服务器在 HTTP 1.0 下可能行为异常，改用 HTTP/1.1 有时会有帮助。 注意，HTTP/1.1 要求必须提供 Host 字段，可使用 "hdr" 参数添加。 hdr 添加 HTTP 头，名称由 指定，值由 定义， 遵循第 8.2.6 节所述的自定义日志格式规则。 body 将 定义的消息体添加到 HTTP 健康检查发送的请求中。 定义此项时，自动添加 "Content-Length" 头。 body-lf 将自定义日志格式 （参见第 8.2.6 节）定义的消息体添加到 HTTP 健康检查发送的请求中。 定义此项时，自动添加 "Content-Length" 头。 ``` 除了由 "option httpchk" 指令定义的请求行外，以下方式是向 HTTP 健康检查请求中添加头字段并可选地添加请求体的正确方法。若定义了请求体，则会自动添加相应的 "Content-Length" 头字段。因此，在 "http-check send" 提供的请求中，不应包含该头字段或 "Transfer-encoding" 头字段，否则将被忽略。在 "option httpchk" 行中版本字符串后添加头字段的旧方法现已弃用。 此外，“http-check send” 不支持 HTTP 持久连接。请注意，除非通过 hdr 条目已配置 Connection 头，否则它会自动附加一个 "Connection: close" 头。 请注意，当 Host 头和请求授权信息均被定义时，二者会自动同步。这意味着在发送 HTTP 请求时，若在请求中插入 Host 头，则请求授权信息会相应更新。因此，若发现 Host 头值覆盖了配置的请求授权信息，无需感到意外。 请注意，目前在 HTTP/1.1 及以上版本的请求中，不会自动添加 Host 头。应显式添加。 另请参阅：“option httpchk”、“http-check send-state”和“http-check expect”。 **`http-check send-state`** ```haproxy http-check send-state ``` 启用 HTTP 健康检查时发送状态头 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当启用此选项时，HAProxy 会始终向每个服务器发送一个特殊头字段 "X-Haproxy-Server-State"，其中包含一组参数，用于指示 HAProxy 对各服务器的当前状态判断。例如，当服务器在未访问 HAProxy 的情况下被操作时，管理员可借此确认 HAProxy 是否仍认为该服务器处于运行状态，或该服务器是否为某服务器组中的最后一个成员。 头由分号分隔的字段组成，第一个字段为一个单词（"UP"、"DOWN"、"NOLB"），后接状态转换前的有效检查数与总检查数（格式与统计信息界面中显示的一致，如 2/3）。后续字段格式为 "``=``"，以任意顺序表示统计信息界面中可用的某些值：- 变量 "address"，包含后端服务器的地址。该值对应服务器声明中的 `
` 字段。对于 Unix 域套接字，其值为 "unix"。 - 变量 "port"，包含后端服务器的端口。对应服务器声明中的 `` 字段。对于 Unix 域套接字，其值为 "unix"。 - 变量 "name"，包含后端名称，后接斜杠（"/"）和服务器名称。当一台 服务器在多个后端中接受检查时，可以使用该变量。 - 变量 "node"，包含 HAProxy 节点的名称，即全局 "node" 变量中设置的 值；未指定时使用系统主机名。 - 变量 "weight"，指示服务器的权重，后接斜杠（"/"）和服务器组的总 权重（仅统计可用的服务器）。这有助于了解当该服务器发生故障时， 是否有其他服务器可用于承担负载。 - 变量 "scur"，指示服务器上当前的并发连接数，后接斜杠（"/"）和同一 后端中所有服务器的连接总数。 - 变量 "qcur"，指示服务器队列中当前的请求数。 应用服务器接收到的头示例： ```shell >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \ scur=13/22; qcur=0 ``` 另请参阅：“option httpchk”、“http-check disable-on-404” 和 “http-check send”。 **`http-check set-var([,...]) `** ```haproxy http-check set-var([,...]) http-check set-var-fmt([,...]) ``` 此操作用于设置变量的内容。变量在行内声明。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是变量名称。仅可使用 "proc"、"sess" 和 "check" 作用域。详情见第 2.8 节的变量说明。 是一组条件，必须全部为真才会实际设置变量（例如 "ifnotempty"、"ifgt" 等）。 所有可用条件见 set-var 转换器的说明。 是样本提取表达式，其后可接转换器。 是以自定义日志格式表示的值（参见第 8.2.6 节的自定义日志格式）。 ``` 示例： ```text http-check set-var(check.port) int(1234) http-check set-var-fmt(check.port) "name=%H" ``` **`http-check unset-var()`** ```haproxy http-check unset-var() ``` 释放变量在其作用域内的引用。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是变量名称。仅可使用 "proc"、"sess" 和 "check" 作用域。详情见第 2.8 节的变量说明。 ``` 示例： ```text http-check unset-var(check.port) ``` **`http-error status [content-type ]`** ```haproxy http-error status [content-type ] [ { default-errorfiles | errorfile | errorfiles | ``` file `` | lf-file `` | string `` | lf-string `` } ] [ hdr `` `` ]* 定义自定义错误消息，用于替代 HAProxy 生成的错误信息。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text status 是 HTTP 状态码，必须指定。HAProxy 目前可生成的状态码为 200、400、401、403、404、405、407、408、410、413、414、425、429、431、500、501、502、503 和 504。 content-type 是响应内容类型，例如 "text/plain"。 配置了 errorfile 或负载为空时，忽略此参数，应省略；其他情况下必须定义。 default-errorfiles 重置当前代理此前为状态 定义的错误消息。 用于后端时，使用前端定义的错误消息（若有）；用于前端时，使用默认错误消息。 errorfile 指定包含完整 HTTP 响应的文件。建议在文件名末尾添加 ".http"， 避免与 HTML 错误页面混淆；还应使用绝对路径，因为文件在执行 chroot 之前读取。 errorfiles 指定从哪个 http-errors 段导入状态码 对应的错误消息。 未找到此类消息时，使用代理的错误消息。 file 指定用作响应负载的文件。文件非空时，必须使用 "content-type" 参数设置其内容类型； 否则忽略任何 "content-type" 参数。 视为原始字符串。 string 指定用作响应负载的原始字符串，必须始终使用 "content-type" 参数设置内容类型。 lf-file 指定用作响应负载的文件。文件非空时，必须使用 "content-type" 参数设置其内容类型； 否则忽略任何 "content-type" 参数。 按自定义日志格式求值（参见第 8.2.6 节）。 lf-string 指定用作响应负载的日志格式字符串，必须始终使用 "content-type" 参数设置内容类型。 hdr 添加 HTTP 响应头，名称由 指定，值由 定义， 遵循自定义日志格式规则（参见第 8.2.6 节）。使用 errorfile 时忽略此参数。 ``` 此指令可用于替代 "errorfile"，以定义自定义错误消息。与 "errorfile" 指令相同，它用于处理 HAProxy 检测并返回的错误。若定义了 errorfile，则 HAProxy 启动时会对其进行解析，且必须符合 HTTP 标准。生成的响应不得超过配置的缓冲区大小（BUFFSIZE），否则将返回内部错误。最后，若考虑使用某些 http-after-response 规则来重写这些错误，应确保预留的缓冲区空间可用（参见 "tune.maxrewrite"）。 配置文件与之同时读取并保留在内存中。因此，即使进程已执行 chroot，错误仍会持续返回，且在进程运行期间不会考虑任何文件变更。 请注意：在请求解析早期阶段产生的 400/408/500 错误由多路复用器在较低层级处理。此层级不支持自定义格式化。因此，仅支持使用 "errorfile" 指令定义的静态错误消息。然而，此限制仅存在于请求头解析期间或两次事务之间。 另请参阅：“errorfile”、“errorfiles”、“errorloc”、“errorloc302”、“errorloc303”以及 [第 12.4 节](/zh/docs/haproxy/other-sections/#section-12-4) 关于 http-errors 的内容。 **`http-request [options...] [ { if | unless } ]`** ```haproxy http-request [options...] [ { if | unless } ] ``` 第 7 层请求的访问控制 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes 第 7 层处理中，`http-request` 语句用于定义一组规则。这些规则在前端、监听或后端段中按声明顺序进行评估。每条规则可选择性地跟随一个基于 ACL 的条件，此时仅当该条件求值为真时，规则才会被评估。 条件在动作执行前进行评估，且该动作仅执行一次。因此，即使某个动作改变了作为条件一部分的元素，也不会造成问题。这也意味着多个动作可以依赖同一条件，只要首个改变条件评估结果的动作执行后，其余动作便会自动隐式禁用。例如，当变量为空时，从多个来源为其赋值，即采用此机制。每个实例中“http-request”语句的数量无限制。 在 "http-request" 语法中，首个关键字为规则的动作，可选地后接该动作所需的若干参数。支持的动作及其对应语法详见 [第 4.3 节](/zh/docs/haproxy/proxies/#section-4-3) “动作”（请查找标记为“HTTP Req”的动作）。 该指令仅在命名的 defaults 段中可用，不可用于匿名段。在关联的代理段之前，将先评估 defaults 段中定义的规则。为避免歧义，在此情况下，同一 defaults 段不可同时被具备前端能力的代理和具备后端能力的代理使用。这意味着，listen 段不可使用定义了此类规则的 defaults 段。 示例： ```text acl nagios src 192.168.129.3 acl local_net src 192.168.0.0/16 acl auth_ok http_auth(L1) http-request allow if nagios http-request allow if local_net auth_ok http-request auth realm Gimme if local_net auth_ok http-request deny ``` 示例： ```text acl key req.hdr(X-Add-Acl-Key) -m found acl add path /addacl acl del path /delacl acl myhost hdr(Host) -f myhost.lst http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del ``` 示例： ```text acl value req.hdr(X-Value) -m found acl setmap path /setmap acl delmap path /delmap use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value http-request del-map(map.lst) %[src] if delmap ``` 另请参阅：“stats http-request”，[第 12.2 节](/zh/docs/haproxy/other-sections/#section-12-2) 关于 userlists 的说明，以及 [第 7 节](/zh/docs/haproxy/acls-and-samples/) 关于 ACL 使用的说明。 **`http-response [ { if | unless } ]`** ```haproxy http-response [ { if | unless } ] ``` 第 7 层响应的访问控制 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes 第 7 层处理中，`http-response` 语句定义了一组规则。这些规则在前端、监听或后端段中按声明顺序进行评估。由于这些规则作用于响应，因此先应用后端规则，再应用前端规则。任何规则均可选择性地跟随一个基于 ACL 的条件，此时仅当该条件求值为真时才进行评估。 条件在动作执行前进行评估，且该动作仅执行一次。因此，即使某个动作改变了作为条件一部分的元素，也不会造成问题。这也意味着多个动作可以依赖同一条件，只要首个改变条件评估结果的动作执行后，其余动作便会自动隐式禁用。例如，当变量为空时，从多个来源为其赋值，即采用此机制。每个实例中“http-response”语句的数量无限制。 在语法中，“http-response”之后的第一个关键字是规则的动作，可选地后接该动作所需的若干参数。支持的动作及其各自语法详见 [第 4.3 节](/zh/docs/haproxy/proxies/#section-4-3)“动作”（请查找标记为“HTTP Res”的动作）。 该指令仅在命名的 defaults 段中可用，不可用于匿名段。在关联的代理段之前，将先评估 defaults 段中定义的规则。为避免歧义，在此情况下，同一 defaults 段不可同时被具备前端能力的代理和具备后端能力的代理使用。这意味着，listen 段不可使用定义了此类规则的 defaults 段。 示例： ```text acl key_acl res.hdr(X-Acl-Key) -m found acl myhost hdr(Host) -f myhost.lst http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl ``` 示例： ```text acl value res.hdr(X-Value) -m found use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value http-response del-map(map.lst) %[src] if ! value ``` 另请参阅：“http-request”，[第 12.2 节](/zh/docs/haproxy/other-sections/#section-12-2) 关于 userlists 的说明以及 [第 7 节](/zh/docs/haproxy/acls-and-samples/) 关于 ACL 使用的说明。 **`http-reuse { never | safe | aggressive | always }`** ```haproxy http-reuse { never | safe | aggressive | always } ``` 声明空闲 HTTP 连接在请求之间如何共享 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 为避免为每个 HTTP 请求建立与后端服务器的新连接所带来的开销，HAProxy 会在使用后尽量保持这些空闲连接处于打开状态。这些连接与特定服务器相关，并存储在一个称为连接池的列表中，且根据一组共同的关键属性进行分组。后续的 HTTP 请求将触发对关联连接池中具有相同属性的兼容连接的查找，从而复用该连接，而非建立新的连接。 可通过服务器关键字 "pool-max-conn" 指定服务器上保持的空闲连接数量上限。未使用的连接将根据 "pool-purge-delay" 间隔周期性地清除。 以下连接属性用于确定空闲连接在特定请求上是否可重用： - 源地址和目标地址 - PROXY 协议 - TOS 和 mark 套接字选项 - 连接名称，由 "pool-conn-name" 表达式求值结果确定，若该表达式不存在，则由 "sni" 表达式确定，其默认值为 "req.hdr(host),field(1,:)"，即使用入站请求的 "Host" 头字段，不包含冒号和端口号。 在某些情况下，由于额外的限制，不会执行连接查找或复用。这由通过关键字参数指定的复用策略决定： - "never"：空闲连接从不在会话之间共享。可以强制使用此模式，以取消从 defaults 段继承的其他策略，或用于故障排查。例如，某个老旧 的有缺陷的应用程序认为同一连接上的多个请求来自同一客户端， 且无法修复该应用程序时，可能需要在单个后端中禁用连接共享。 此类应用程序的一个例子是使用 cookie 插入且处于隧道模式的 旧版 HAProxy，它不检查第一个之后的任何请求。 - "safe"：这是默认且推荐的策略。会话的第一个请求始终通过其自身的 连接发送，只有后续请求才可能通过其他现有连接分派。这确保 了在服务器于请求发送期间关闭连接的情况下，浏览器可以决定 静默重试。由于这完全等同于常规持久连接，因此不应有任何 副作用。对于使用受队头阻塞（Head-of-line blocking）影响的 协议（后端为 h2 或 fcgi）的连接，还有特殊处理：此时，只要 至少有一个流正在处理，所使用的连接就会被保留用于处理同一 会话的流；当不再有流处理时，连接会被释放并可以复用。 - "aggressive"：此模式可能适用于并非所有服务器都已知、且希望大多数 首个请求通过现有连接交付的 Web 服务环境。此时，首个请求 仅通过至少被复用过一次的现有连接交付，以证明服务器正确 支持连接复用。只有当确定客户端能够偶尔重试失败的请求， 且激进连接复用的收益显著大于偶发连接故障的缺点时，才应 使用此模式。 - "always"：仅当已知通往服务器的路径绝不会在释放连接后很快断开现有 连接时，才推荐使用此模式。它允许会话的第一个请求通过现有 连接发送。当后端是缓存服务器集群时，相比 "safe" 策略，这 可以带来显著的性能提升，因为此类组件的行为往往一致，并能 从连接共享中受益。在此模式下，建议保持较低的 "http-keep-alive" 超时，以免失效连接仍可使用。在大多数 情况下，这会带来与 "aggressive" 相同的性能收益，但风险 更高。仅当其效果优于 "aggressive" 时才应使用。 请注意，使用某些依赖连接的伪造认证机制（如 NTLM）的连接，若可能将被标记为私有，且永不共享。然而，当使用具备多路复用能力的协议，并启用大于默认“安全”策略的重用模式级别时，情况将不同，此时无法阻止连接已被共享。 决定在处理完成后是否保持空闲连接打开或关闭的规则，同样由 "tune.pool-low-fd-ratio"（默认值：20%）和 "tune.pool-high-fd-ratio"（默认值：25%）控制。这两个参数分别对应于空闲连接所占用的总文件描述符比例阈值，当超过该阈值时，HAProxy 将分别停止在响应后保持连接打开，或主动终止空闲连接。某些配置中空闲连接比例极高，可能是由于全局 "maxconn" 值过低，或前端存在大量 HTTP/2 或 HTTP/3 流量（连接数少），而后端使用 HTTP/1 连接，可能导致连接复用率下降，因为保持打开的连接过少。在此情况下，调整这些阈值或简单地提高全局 "maxconn" 值可能是有益的。 在某些罕见情况下，当主机名用于区分出站 TLS 连接（例如正向代理）且大多数请求的目标主机不同时，连接复用率会非常低。此时，在连接有机会被复用之前，系统可能已触发对使用频率较低连接的自动淘汰机制。这是因为该机制会持续测量维持服务所需的平均连接数，以避免资源耗尽。在此类场景中，将“pool-low-conn”设置为接近预期空闲连接平均数的值，有助于通过鼓励线程建立自己的连接，而非尝试选取其他线程的连接，从而减少可用连接池的收缩，保留更多连接。 如果本地托管的服务器使用单个证书（包含多个主机名或通配符）并运行多个站点，建议在“server”行上使用“no-sni-auto”而非保留对单一主机名的连接，以提升连接复用率。部分服务器可能在主机名与 SNI 之间执行过多检查，导致拒绝后续请求，因此该选项需预先验证。默认行为（“sni-auto”）旨在确保与此类服务器的兼容性，更为安全。 当显式启用线程组时，需注意空闲连接仅可在同一组内的线程之间复用。因此，组间负载不均可能导致需要更多空闲连接，从而降低复用率。可采用相同解决方案（增加全局 "maxconn" 值或提高池比例）。 另请参阅："option http-keep-alive"、"pool-conn-name"、"pool-max-conn"、"pool-purge-delay"、"server maxconn"、"sni"、"thread-groups"、"tune.pool-high-fd-ratio"、"tune.pool-low-fd-ratio" **`http-send-name-header [
]`** ```haproxy http-send-name-header [
] ``` 将服务器名称添加到请求中。使用由 `
` 提供的头字符串 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text
是用于发送服务器名称的头字符串。 ``` “http-send-name-header” 语句会导致名为 `
` 的头字段在请求即将通过网络发送时被设置为目标服务器的名称。该头字段中任何已存在的实例均会被移除。在重试和重分派过程中，该头字段会更新，始终反映当前尝试连接的服务器。由于该头字段在连接建立过程的后期才被修改，可能对已修改的其他头字段产生意外影响。例如，与传输层头（如 connection、content-length、transfer-encoding 等）一起使用时，很可能导致向服务器发送无效请求。因此，以下头字段被禁止使用：host、content-length、transfer-encoding 和 connection。 另请参阅："server" **`id `** ```haproxy id ``` 为代理设置持久化 ID。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| yes 参数：无 为代理设置一个持久化 ID。该 ID 必须唯一且为正数。若未设置，将自动分配一个未使用的 ID。由于历史行为，除非显式设置，否则值 1 不会被使用。因此，自动分配的最小值为 2。该 ID 当前仅在统计信息中返回。 **`ignore-persist { if | unless } `** ```haproxy ignore-persist { if | unless } ``` 声明一个条件以忽略持久性 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| no \| yes \| yes 默认情况下，启用 cookie 持久性后，所有包含该 cookie 的请求将无条件保持持久性（前提是目标服务器处于运行状态）。 本节中的 "ignore-persist" 语句允许声明多种基于 ACL 的条件，当这些条件满足时，将导致请求忽略持久性。这在对静态文件请求进行负载均衡时有时很有用，因为这类请求通常不需要持久性。该功能也可用于针对特定 User-Agent 完全禁用持久性（例如，某些网络爬虫机器人）。 当满足 "if" 条件时，持久性将被忽略，或除非满足 "unless" 条件。 示例： ```text acl url_static path_beg /static /images /img /css acl url_static path_end .gif .png .jpg .css .js ignore-persist if url_static ``` 另请参阅：“force-persist”、“cookie”以及 [第 7 节](/zh/docs/haproxy/acls-and-samples/) 中关于 ACL 使用的说明。 **`load-server-state-from-file { global | local | none }`** ```haproxy load-server-state-from-file { global | local | none } ``` 允许 HAProxy 无缝重载 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 本指令用于指定 HAProxy 从何处加载前一次运行进程保存的服务器状态文件。这样，在启动过程中、处理流量之前，新进程可以将旧状态精确地应用到服务器上，如同未发生重载一般。`load-server-state-from-file` 指令的作用是告知 HAProxy 使用哪个文件。目前，该指令仅支持两个参数：一个用于禁止加载状态，另一个用于从包含所有后端和服务器状态的文件中加载状态。状态文件可通过在统计信息套接字上执行命令 `show servers state` 并重定向输出生成。 文件格式已版本化，且非常具体。如需理解，请阅读“show servers state”命令的文档（管理指南第 9.3 章）。 参数： ```text global 加载全局指令 "server-state-file" 指向的文件的内容。 local 若设置了 "server-state-file-name" 指令，则加载它指向的文件； 否则以后端名称作为文件名。 none 不加载此后端的任何状态。 ``` 注意：默认情况下，服务器的 IP 地址在重载过程中得以保留，但可通过服务器的 "init-addr" 设置更改其顺序。这意味着通过 CLI 在运行时执行的 IP 地址变更将被保留，且若启用了状态文件，对本地解析器（例如 /etc/hosts）的任何更改可能不会产生效果。 - 除非服务器的权重在新旧配置文件之间发生了更改，否则将沿用之前运行 进程中的服务器权重。 示例：最小配置 global stats socket /tmp/socket server-state-file /tmp/server_state defaults load-server-state-from-file global backend bk server s1 127.0.0.1:22 check weight 11 server s2 127.0.0.1:22 check weight 12 然后可以运行： ```text socat /tmp/socket - <<< "show servers state" > /tmp/server_state ``` /tmp/server_state 文件的内容应如下所示： ```shell 1 # 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 ``` 示例：最小配置 global stats socket /tmp/socket server-state-base /etc/haproxy/states defaults load-server-state-from-file local backend bk server s1 127.0.0.1:22 check weight 11 server s2 127.0.0.1:22 check weight 12 然后可以运行： ```text socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk ``` /etc/haproxy/states/bk 文件内容如下： ```shell 1 # 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 ``` 另请参阅：“server-state-file”、“server-state-file-name”和“show servers state” **`log global`** ```haproxy log global log [len ] [format ] [sample :] [profile ] [ []] no log ``` 启用每个实例的事件和流量日志记录。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 前缀： ```text no 用于需要清空日志记录器列表的情况，例如不希望继承默认列表时。 此前缀不接受参数。 ``` 参数： ```text global 实例日志参数与全局参数相同时使用，这是最常见的用法。 "global" 将所有日志参数替换为 "global" 段中日志条目的参数。 每个实例仅能使用一条 "log global" 语句，且此形式不接受其他参数。 指定日志发送位置，格式与 "global" 段的日志相同，可为： - IPv4 地址，可选地后接冒号（':'）和 UDP 端口。未指定时默认使用 514（标准 syslog 端口）。 - IPv6 地址，后接冒号（':'）及可选 UDP 端口。未指定时默认使用 514（标准 syslog 端口）。 - UNIX 域套接字的文件系统路径。需考虑 chroot（确保路径在 chroot 内可访问） 和 uid/gid（确保路径具有适当写权限）。 - "fd@" 形式的文件描述符，可指向管道、终端或套接字。 此时使用无缓冲日志，每条日志调用一次 writev()，开销稍高，但大多数工作负载可接受。 消息不会截断，但可能丢弃，此时 DroppedLogs 计数器递增。 对不超过 PIPE_BUF 的消息，writev() 即使写入管道也具有原子性。 POSIX 建议此大小至少为 512，大多数现代操作系统为 4096 字节。 更大的消息可能与其他进程的消息交错。仅为调试，可将文件描述符指向文件， 但非阻塞调用会被忽略，显著降低 HAProxy 速度；不重启进程也无法清理或轮转该文件。 配置的 syslog 格式仍保留，输出适合 TCP syslog 服务器。另见下方 "short" 和 "raw" 格式。 - "stdout" / "stderr"，分别是 "fd@1" 和 "fd@2" 的别名，见上文。 - "ring@" 形式的环形缓冲区，对应内存中的环形缓冲区， 可通过 CLI 的 "show events" 命令访问；该命令也列出已有环及其大小。 缓冲区在重载或重启时丢失，但作为补充手段，可立即获取日志，帮助故障排查。详情见第 12.5 节。 - "backend@" 形式的日志后端，将消息发送到对应日志后端， 由其按负载均衡设置发送到适当服务器。日志后端是设置 "mode log" 的 backend 段 （更多信息见 "mode"）。 - "tcp@"、"tcp6@"、"tcp4@" 或 "uxst@" 等显式流地址前缀， 会分配隐式环形缓冲区及指向该地址的流转发服务器。 地址参数可能需要引用环境变量，参见第 2.3 节。 是可选的最大行长度。超过此值的日志行在发送前截断，因为 syslog 服务器对行长度处理不同。 所有服务器支持默认值 1024，但某些服务器直接丢弃更长的行，其他服务器仍能记录。 支持长行时，可设置此值避免截断；丢弃长行时，最好在发送前截断。 接受 80 到 65535（含两端），默认 1024 通常适合标准用法。 长捕获或 JSON 日志可能需要更大的值。请求 URI 被截断时，可能还需增大 "tune.http.logurilen"。 是逗号分隔的范围列表，确定采样哪些日志，以均衡发送到日志服务器的负载。 范围边界不能为零，从 1 开始编号。采样大小或周期（日志条数）须通过 设置。 是均衡日志负载时考虑的采样日志条数，用于均衡发送到 syslog 服务器的负载。 必须大于或等于各范围上界的最大值（另见 ）。 是生成 syslog 消息时使用的日志格式，可为： local 类似 rfc3164 syslog 消息格式，但去除主机名字段。这是默认值。 注意："log-send-hostname" 会将默认值切换为 rfc3164。 rfc3164 RFC3164 syslog 消息格式。 (https://tools.ietf.org/html/rfc3164) rfc5424 RFC5424 syslog 消息格式。 (https://tools.ietf.org/html/rfc5424) priority 仅包含尖括号内的级别与 syslog facility 之和，如 '<63>'，以及其后的文本。 省略 PID、日期、时间、进程名称和系统名称，适用于本地日志服务器。 short 仅包含尖括号内的级别，如 '<3>'，以及其后的文本。 省略 PID、日期、时间、进程名称和系统名称，适用于本地日志服务器，兼容 systemd 日志记录器。 timed 仅包含尖括号内的级别，如 '<3>'，以及其后的 ISO 日期和文本。 省略 PID、进程名称和系统名称，适用于本地日志服务器。 iso 仅包含 ISO 日期及其后的文本，省略 PID、进程名称和系统名称，适用于本地日志服务器。 raw 仅包含文本，省略级别、PID、日期、时间、进程名称和系统名称。 适用于容器或开发环境，严重程度仅取决于使用的文件描述符（stdout/stderr）。 是可选的 "log-profile" 段名称，在构建日志时覆盖部分选项。 更多信息见 "8.3.5. Log profiles"。 必须为 24 个标准 syslog facility 之一： kern user mail daemon auth syslog lpr news uucp cron auth2 ftp ntp audit alert cron2 local0 local1 local2 local3 local4 local5 local6 local7 "short" 和 "raw" 格式忽略 facility，但仍要求提供此位置参数。 此时推荐用 "daemon"，明确表示仅用于本地。 是可选参数，用于过滤出站消息，默认发送全部消息。 指定级别后，仅发送严重程度至少达到该级别的消息。 还可指定可选的最低级别；超过该严重程度的日志会被限制在该级别， 避免某些默认 syslog 配置将 "emerg" 消息发送到所有终端。支持八个级别： emerg alert crit err warning notice info debug ``` 请注意，决定从连接中记录哪些内容的是前端，若发生内容切换，则后端生成的日志条目将被忽略。连接日志记录级别为 "info"。 然而，后端日志声明定义了服务器状态变更的记录方式和位置。状态变为“上线”时使用级别“notice”记录，收到终止信号或服务永久终止时使用级别“warning”记录，服务器宕机时使用级别“alert”记录。 请注意：根据 RFC3164，消息在发出前会被截断至 1024 字节。 示例： ```text log global log stdout format short daemon # send log to systemd log stdout format raw daemon # send everything to stdout log stderr format raw daemon notice # send important events to stderr log 127.0.0.1:514 local0 notice # only send important events log tcp@127.0.0.1:514 local0 notice notice # same but limit output # level and send in tcp log "${LOCAL_SYSLOG}:514" local0 notice # send to local server ``` **`log-format `** ```haproxy log-format ``` 指定用于流量日志的自定义日志格式字符串 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 该指令指定将用于通过此行配置的前端处理流量所产生的所有日志的日志格式字符串。若该指令在 defaults 段中使用，则后续所有前端将采用相同的日志格式。请参见 [第 8.2.6 节](/zh/docs/haproxy/configuration-logging/#section-8-2-6)，其中详细介绍了自定义日志格式字符串。 也可定义仅在连接错误情况下使用的特定日志格式，详见 "error-log-format" 选项。 "log-format" 指令会覆盖之前的 "option tcplog"、"log-format"、"option httplog" 和 "option httpslog" 指令。 **`log-format-sd `** ```haproxy log-format-sd ``` 指定用于生成 RFC5424 结构化数据的自定义日志格式字符串 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 该指令指定 RFC5424 结构化数据日志格式字符串，该字符串将用于通过此行配置的前端处理流量所产生的所有日志。若该指令在 defaults 段中使用，则后续所有前端均将采用相同的日志格式。请参见 [第 8.2.6 节](/zh/docs/haproxy/configuration-logging/#section-8-2-6)，其中深入介绍了日志格式字符串。 有关 RFC5424 结构化数据部分的更多信息，请参见 。 请注意：此日志格式字符串仅适用于将日志格式设置为 "rfc5424" 的记录器。 示例： ```text log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"] ``` **`log-steps `** ```haproxy log-steps ``` 指定在事务处理过程中应在哪些步骤生成日志。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 在处理 TCP/HTTP 事务时，HAProxy 可能在处理过程的不同阶段生成日志（例如：接受连接、建立连接、接收请求、发送响应、关闭连接）。 默认情况下，HAProxy 每个事务仅生成一条日志，且仅在日志格式表达式中使用的所有项均满足后才发出日志，这意味着在实际应用中，日志通常在事务结束时发出（HTTP 为响应结束后，TCP 为连接结束后），除非使用了 "option logasap"。 指令 "log-steps" 允许精确控制日志的输出时机，甚至支持为同一事务输出多条日志。特殊值 "all" 可用于启用所有可用的日志来源，从而实现从连接接收至连接关闭的完整事务追踪。也可通过用逗号分隔的名称指定个别日志来源，以选择性地启用日志输出。 常见的日志来源包括：accept、connect、request、response、close。 示例： ```text frontend myfront option httplog log-steps accept,close #only log accept and close for the txn ``` 可直接在日志配置文件中使用以“logging steps”（如 accept、close）指定的日志来源（在 'on' 指令之后）。将“log-steps”与日志配置文件结合使用，能够对 HAProxy 在事务处理过程中自动生成的日志实现细粒度控制，具有很高的实用价值。 此设置仅对前端有效，后端将忽略该设置。 另请参阅："log-profile" **`log-tag `** ```haproxy log-tag ``` 指定用于所有出站日志的日志标签 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 设置 syslog 头中的标签字段为该字符串。默认值为全局段中设置的 log-tag，否则为从命令行启动时的程序名称，通常为 "HAProxy"。在同一个主机上运行多个进程时，或在同一个进程中运行多个客户实例时，有时需要加以区分。在后端中，关于服务器启停的日志将使用此标签。作为提示，可以在 defaults 段中设置与托管客户相关的 log-tag，然后将该客户的全部前端和后端配置放在此段中，再在新的 defaults 段中开始配置另一个客户。参见全局段中的 "log-tag" 指令。 **`max-keep-alive-queue `** ```haproxy max-keep-alive-queue ``` 设置用于维持持久连接的服务器队列最大大小 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes HTTP 持久连接会尽可能复用相同的服务器连接，但在某些情况下可能适得其反，例如当某些服务器连接数较多而其他服务器处于空闲状态时。这一点在静态服务器上尤为明显。 本设置的目的是设定一个队列中连接数量的阈值，当超过该阈值时，HAProxy 停止尝试复用同一台服务器，转而优先选择其他服务器。默认值 -1 表示无限制。值为 0 表示持久连接永远不会被排队。对于延迟较低、且对中断持久连接不敏感的近距离服务器，建议使用较低的值（例如，本地静态服务器可使用 10 或更小的值）。对于延迟较高的远程服务器，可能需要更高的值以弥补延迟和/或选择其他服务器的开销。 请注意，此设置对连续发送至同一服务器的响应无影响，即使这些响应需被排队。在收到 401 响应后，它们仍会发送至同一服务器。 另请参阅：“option http-server-close”、“option prefer-last-server”、服务器“maxconn”和 cookie 持久性。 **`max-session-srv-conns `** ```haproxy max-session-srv-conns ``` 设置单个客户端会话可保持空闲的最大出站连接数。默认值为 5（精确等于在编译时定义的 MAX_SRV_LIST）。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no **`maxconn `** ```haproxy maxconn ``` 设定前端的最大并发连接数 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是前端接受并提供服务的最大并发连接数。超出的连接由系统排入套接字的监听队列， 在已有连接关闭后再提供服务。 ``` 如果系统支持，对于大型站点而言，将此限制值设得非常高可能很有用，以便 HAProxy 管理连接队列，而非让客户端处于未响应的连接尝试状态。该值不应超过全局 maxconn。同时请注意，每个连接包含两个 tune.bufsize（默认为 16 kB）的缓冲区，以及一些其他数据，导致每个已建立的连接大约消耗 33 kB 的内存。这意味着，经过适当调优的中等规模系统，配备 1 GB 内存时，可承受约 20000 至 25000 个并发连接。 此外，当 `` 设置为较大值时，服务器可能无法承受如此高的负载，因此通常建议为其分配合理的连接限制。 当该值设置为零时（即默认值），将使用全局的 "maxconn" 值。 另请参阅："server"、global 段的 "maxconn"、"fullconn" **`mode { tcp|http|log|spop }`** ```haproxy mode { tcp|http|log|spop } ``` 设置实例的运行模式或协议。 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text tcp 实例以纯 TCP 模式工作，在客户端与服务器之间建立全双工连接，不进行第 7 层检查。 这是默认模式，适用于 SSL、SSH、SMTP 等。 http 实例以 HTTP 模式工作，在连接任何服务器之前深入分析客户端请求。 不符合 RFC 的请求将被拒绝，可进行第 7 层过滤、处理和切换。 这是最能体现 HAProxy 价值的模式。 haterm 前端以 haterm HTTP 基准测试模式工作。后端不支持此模式。详情见 doc/haterm.txt。 log 在 backend 段中使用时，将其转换为日志后端。通过 "backend@" 语法， 此类后端可作为任意 "log" 指令的日志目标。日志消息按可通过 "balance" 关键字配置的 负载均衡设置分发给后端服务器。在服务器地址前添加 "udp@" 前缀，可支持 UDP 服务器。 支持通用的后端和服务器功能，但不支持 TCP 或 HTTP 专用功能。 spop 在 backend 段中使用时，将其转换为 spop 后端。后端包含 SPOA 服务器时必须使用此模式； 但在 tcp 模式下检测到此类服务器时，会自动转换为 spop 模式。 ``` 进行内容切换时，前端和后端必须处于相同模式（通常为 HTTP），否则配置将被拒绝。 示例： ```text defaults http_instances mode http ``` **`monitor fail { if | unless } `** ```haproxy monitor fail { if | unless } ``` 为监控 HTTP 请求添加一个失败报告条件。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend no \| yes \| yes \| no 参数： ```text if 条件满足时监控请求失败，否则成功。该条件应描述一个组合测试， 在全部条件满足时触发失败，例如后端及其备用后端的服务器数量均较少。 unless 仅当条件满足时监控请求成功，否则失败。 此条件可基于检查一组后端中是否有最低数量的活跃服务器。 ``` 此语句添加一个条件，可强制对监控请求的响应报告失败。默认情况下，当外部组件查询专用于监控的 URI 时，将返回 200 响应。当满足上述任一条件时，HAProxy 将返回 503 而非 200。此机制对于向外部组件报告站点故障非常有用，外部组件可能基于 HAProxy 报告的可用性状态在多个站点间进行路由通告。在此场景中，应依赖包含 "nbsrv" 条件的 ACL。请注意，"monitor fail" 仅在 HTTP 模式下有效。如需调整，可使用 "errorfile" 或 "errorloc" 自定义状态消息。 示例： ```text frontend www mode http acl site_dead nbsrv(dynamic) lt 2 acl site_dead nbsrv(static) lt 2 monitor-uri /site_alive monitor fail if site_dead ``` 另请参阅："monitor-uri"、"errorfile"、"errorloc" **`monitor-uri `** ```haproxy monitor-uri ``` 拦截外部组件监控请求所使用的 URI 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 是要拦截的确切 URI，用于返回 HAProxy 的健康状态，而非转发请求。 ``` 当在前端接收到引用 `` 的 HTTP 请求时，HAProxy 不会转发该请求，也不会记录日志，而是返回“HTTP/1.0 200 OK”或“HTTP/1.0 503 Service unavailable”，具体取决于通过“monitor fail”定义的故障条件。通常情况下，任何前端 HTTP 探针均可据此判断服务处于正常运行状态，而无需将请求转发至后端服务器。请注意，HTTP 方法、版本及所有头字段均被忽略，但请求在 HTTP 层面必须至少有效。该关键字仅可与 HTTP 模式前端一同使用。 监控请求在解析后立即处理，甚至早于任何 "http-request" 规则。在此之前仅应用了 tcp-request 规则集。这些请求无法被记录，这是设计目的。监控仅可配置一个 URI；当存在多个 "monitor-uri" 语句时，最后一个将决定所使用的 URI。它们仅用于向高层组件报告 HAProxy 的健康状态，除此之外无其他用途。然而，可以使用 "monitor fail" 和 ACLs 添加任意数量的条件，从而根据任何可设想的检查结果进行调整（最常见的场景是后端中可用服务器的数量）。 请注意：如果 `` 以斜杠（'/'）开头，则匹配将基于请求路径而非请求 URI 执行。此做法为一种变通方案，用于使 HTTP/2 请求能够匹配 monitor-uri。在 HTTP/2 中，客户端被建议仅发送绝对 URI。 示例： ```shell # Use /haproxy_test to report HAProxy's status frontend www mode http monitor-uri /haproxy_test ``` 另请参阅：“monitor fail” **`option abortonclose`** ```haproxy option abortonclose no option abortonclose ``` 启用或禁用客户端关闭时对未开始处理的早期中止 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 TCP 连接支持在每个方向上独立关闭，仅单向关闭的连接通常被称为“半关闭”。最初，在 HTTP 生态系统主要采用“关闭模式”时，每个连接仅传输一次请求和一次响应后即关闭，此时脚本化客户端发送请求后关闭发送方向，等待响应，接收关闭指示后即完成操作的情况十分常见。然而，随着持久连接及更高级协议的出现，这种做法已基本消失。目前，客户端在未收到响应前关闭连接的情况，本质上仅出现在用户希望中止传输，或超时触发导致连接被关闭的场景中。 这两种情况（半关闭与中止）从服务器端（此处为 HAProxy 监听器）无法区分。这是一个问题，因为当客户端中止连接后仍保持连接并继续处理请求，会消耗大量资源，尤其是当连接关闭是由于用户点击“重载”按钮所致时，意味着新请求被排队，而先前的请求并未被中止。反之，若在遇到此类半关闭情况时一律中止连接，将导致大量 TCP 应用程序以及部分内部网络中与旧版代理交互的 HTTP 应用程序无法正常工作。 "abortonclose" 选项允许选择期望的行为：当该选项存在于前端时，将避免处理处于半关闭连接上的待处理 TLS 握手。这可能是由于用户在高负载下执行 HTTPS 请求时触发“重载”操作，例如在主 HAProxy 节点与备用节点之间发生 VRRP 故障转移时：所有客户端同时重新连接至新节点，且所有客户端均需执行开销较高的完整 TLS 握手。若该过程耗时超过数秒，很可能导致部分用户放弃连接，此时继续为其执行握手将毫无意义。鉴于 TLS 握手的 CPU 开销较高，建议在面向互联网的前端上保持该选项启用。对于入站 TLS 连接，此为默认行为。 - 当该选项存在于后端时，将使半关闭连接尝试中止尚未发送至服务器的 请求（即该请求仍在队列中等待或正在尝试建立连接时）。如果请求已由 某台服务器处理，则与该服务器的连接也会相应切换为半关闭状态，以向 服务器表明同样的情况，由服务器决定后续如何处理。对于 HTTP 模式的 后端，此为默认行为。 建议在面向互联网的 TLS 终端节点和 HTTP 服务上启用此选项，并在纯 TCP 服务以及未暴露的旧环境里禁用。HTTP 后端中默认启用此选项，可通过在后端段或其继承的“defaults”段中前置“no”关键字强制禁用。TLS 监听器也默认启用此选项，同样可通过在前端段或其继承的“defaults”段中指定“no option abortonclose”强制禁用。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“timeout queue” 以及服务器的 “maxconn” 和 “maxqueue” 参数 **`option accept-invalid-http-request (deprecated)`** ```haproxy option accept-invalid-http-request (deprecated) no option accept-invalid-http-request (deprecated) ``` 启用或禁用对 HTTP 请求解析的宽松处理 “accept-invalid-http-request” 关键字已弃用，请改用 “option accept-unsafe-violations-in-http-request”。 **`option accept-invalid-http-response (deprecated)`** ```haproxy option accept-invalid-http-response (deprecated) no option accept-invalid-http-response (deprecated) ``` 启用或禁用对 HTTP 响应解析的宽松处理 "accept-invalid-http-response" 关键字已弃用，请改用 "option accept-unsafe-violations-in-http-response"。 **`option accept-unsafe-violations-in-http-request`** ```haproxy option accept-unsafe-violations-in-http-request no option accept-unsafe-violations-in-http-request ``` 启用或禁用对 HTTP 请求解析的宽松处理 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 默认情况下，HAProxy 会遵循不同的 HTTP RFC 规范进行消息解析。这意味着消息解析非常严格，对于格式错误的消息会向客户端返回错误。这种行为是期望的，因为格式错误的消息本质上常被用于利用服务器弱点的攻击，或绕过安全过滤。有时，由于某种原因（配置、实现等），某些存在缺陷的浏览器可能不遵守这些 RFC，而问题不会立即得到修复。在此情况下，可以通过指定该选项来放宽 HAProxy 的解析规则，以接受部分无效请求。大多数规则出于历史原因主要针对 H1 解析。较新的 HTTP 版本趋向于更加规范，应用程序也更严格地遵循这些协议。 当设置此选项时，遵循以下规则： * 仅在 H1 中，头名称中的无效字符（包括 NULL 字符）不会被拒绝；但该头 将被丢弃。 * 仅在 H1 中，头值中的 NULL 字符将被接受； * 仅在 H1 中，URI 中大于 127 的字符将被接受。URI 中允许出现的字符 列表由 RFC3986 明确定义，字符 0-31、32（空格）、34（'"'）、60 （'<'）、62（'>'）、92（'\'）、94（'^'）、96（'`'）、123（'{'）、 124（'|'）、125（'}'）、127（delete）及以上的字符通常不被允许。在 H1 中，介于（0..32）与 127 之间的所有字符始终会被阻止。大于 127 （不含）的所有字符也会被阻止，除非启用了此选项。其他字符（33..126） 则完全不会被检查。 * 在 H1 和 H2 中，包含片段引用（位于路径之后的 '#'）的 URL 将被接受； * 仅在 H1 中，不会对 CONNECT 请求的授权部分（authority）执行检查； * 仅在 H1 中，不会对授权部分与 Host 头的值执行检查。 * 仅在 H1 中，对 HTTP 版本的测试将放宽。它允许 HTTP/0.9 的 GET 请求 通过（不指定版本），也允许不同的协议名称（例如 RTSP），以及主版本 号和次版本号使用多个数字。 * 仅在 H1 中，未能提供有效 "Sec-Websocket-Key" 头字段的 WebSocket （RFC6455）请求将被接受。 此选项默认情况下绝不可启用，因为它会隐藏应用程序的缺陷和安全漏洞。仅在确认问题存在后方可部署。 启用此选项后，无效但被接受的 H1 请求将被捕获，以便后续通过 UNIX 统计套接字上的 "show errors" 请求进行分析。执行此操作还有助于确认问题已解决。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option accept-unsafe-violations-in-http-response”以及统计套接字上的 “show errors”。 **`option accept-unsafe-violations-in-http-response`** ```haproxy option accept-unsafe-violations-in-http-response no option accept-unsafe-violations-in-http-response ``` 启用或禁用对 HTTP 响应解析的宽松处理 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 与“option accept-unsafe-violations-in-http-request”类似，此选项可用于放宽对 HTTP 响应的解析规则。仅当目标服务器为可信的旧版服务器时，才应启用此选项以接受部分无效响应。大多数规则出于历史原因针对 H1 解析。较新的 HTTP 版本通常更为规范，应用程序也更严格遵循这些协议。 当设置此选项时，遵循以下规则： * 仅在 H1 中，长度超过 3 位数字但数值可容纳于 16 位的状态码不会被 拒绝。 * 仅在 H1 中，头名称中的无效字符（包括 NULL 字符）不会被拒绝；但该头 将被丢弃。 * 仅在 H1 中，头值中的 NULL 字符将被接受； * 仅在 H1 中，Transfer-Encoding 头的空值或多个 "chunked" 值出现将被 接受； * 仅在 H1 中，不会对授权部分与 Host 头的值执行检查。 * 仅在 H1 中，对 HTTP 版本的测试将放宽。它允许不同的协议名称（例如 RTSP），以及主版本号和次版本号使用多个数字。 * 仅在 H1 中，未能提供有效 "Sec-Websocket-Accept" 头字段的 WebSocket （RFC6455）响应将被接受。 此选项默认情况下绝不可启用，因为它会隐藏应用程序的缺陷和安全漏洞。仅在确认问题存在后方可部署。 启用此选项后，响应中的错误头名称仍会被接受，但会完整捕获响应内容，以便后续通过 UNIX 统计套接字上的 "show errors" 请求进行分析。执行此操作还有助于确认问题已解决。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option accept-unsafe-violations-in-http-request”以及统计套接字上的 “show errors”。 **`option allbackups`** ```haproxy option allbackups no option allbackups ``` 可同时使用所有备用服务器，或仅使用第一个备用服务器。 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 默认情况下，当所有正常服务器均不可用时，首个处于运行状态的备用服务器将接收全部流量。 有时可能更希望同时使用多个备用服务器，因为仅使用一个可能不够。当启用 "option allbackups" 时，若所有正常服务器均不可用，负载均衡将在所有备用服务器之间进行。将使用相同的负载均衡算法，并尊重服务器的权重。因此，备用服务器之间将不再存在优先级顺序。 该选项通常用于静态服务器集群，当应用程序完全离线时，返回“抱歉”页面。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 **`option checkcache`** ```haproxy option checkcache no option checkcache ``` 分析所有服务器响应，并阻止包含可缓存 Cookie 的响应 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 某些高级框架会在所有位置设置应用 Cookie，且并不总是为开发者提供足够的控制权，以管理响应的缓存方式。当缓存对象返回会话 Cookie 时，用户通过相同缓存时发生会话交叉或窃取的风险极高。在某些情况下，阻止响应比让敏感会话信息暴露在外更为妥当。 选项 "checkcache" 启用对所有服务器响应的深度检查，以确保其严格符合 HTTP 规范中关于可缓存性的要求。该选项会仔细检查服务器响应中的 "Cache-Control"、"Pragma" 和 "Set-Cookie" 头，以判断是否存在客户端代理缓存 Cookie 的风险。启用此选项后，仅以下响应可传递给客户端： - 所有不含 "Set-Cookie" 头的响应； - 所有返回码非 200、203、204、206、300、301、404、405、410、414、501 的响应，前提是服务器未设置 "Cache-Control: public" 头字段； - 所有通过非 GET、HEAD、OPTIONS、TRACE 方法发起的请求所导致的响应，前提是服务器未设置 "Cache-Control: public" 头字段； - 所有包含 "Pragma: no-cache" 头的响应； - 所有包含 "Cache-Control: private" 头的响应； - 所有包含 "Cache-Control: no-store" 头的响应； - 所有包含 "Cache-Control: max-age=0" 头的响应； - 所有包含 "Cache-Control: s-maxage=0" 头的响应； - 所有包含 "Cache-Control: no-cache" 头的响应； - 所有包含 "Cache-Control: no-cache=\"set-cookie\"" 头的响应； - 所有包含 "Cache-Control: no-cache=\"set-cookie," 头的响应（允许 "set-cookie" 之后包含其他字段）； - 所有既不包含新鲜度信息（带有 "max-age" 或 "s-maxage" 的 "Cache-control" 头，或 "Expires" 头），也不包含验证器（"ETag" 或 "Last-Modified" 头）的响应，因为符合规范的缓存不会存储此类响应。 如果响应不满足这些要求，则其将被阻止，效果等同于来自 "http-response deny" 规则的响应，返回 "HTTP 502 bad gateway"。会话状态显示为 "PH--"，表示代理在处理头时阻断了响应。此外，日志中将发送告警，以便管理员知晓需进行修复。 由于该选项对应用影响较大，应用在上线生产环境前应充分测试启用该选项的情况。在测试过程中，即使生产环境不使用该选项，也建议始终启用，以便报告潜在危险的应用行为。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 **`option clitcpka`** ```haproxy option clitcpka no option clitcpka ``` 启用或禁用在客户端侧发送 TCP keepalive 数据包 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 当客户端与服务器之间存在防火墙或其他会话感知组件，且协议涉及长时间会话及较长空闲期（例如远程桌面）时，中间组件可能因会话空闲时间过长而决定终止该会话，从而带来风险。 启用套接字级别的 TCP 持久连接可使系统定期向连接的另一端发送数据包，从而保持连接处于活跃状态。持久连接探测之间的延迟由系统控制，且取决于操作系统及其调优参数。 必须理解，持久连接报文不会在应用层发出或接收，仅网络协议栈能够感知到它们。因此，即使代理的一端已使用持久连接来维持连接活跃，这些持久连接报文也不会被转发至代理的另一端。 请注意，这与 HTTP 持久连接无关。 使用选项 "clitcpka" 可在连接的客户端一侧启用 TCP 持久连接探测，当 HAProxy 与客户端之间的会话超时被察觉时，此功能应能提供帮助。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option srvtcpka”、“option tcpka” **`option contstats`** ```haproxy option contstats ``` 启用持续的流量统计信息更新 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 默认情况下，用于统计信息计算的计数器仅在流结束时才递增。在提供小对象时，该机制工作良好；但在处理大对象（例如大型图片或归档文件）或音视频流时，由 HAProxy 计数器生成的图表会呈现类似刺猬的形态。启用此选项后，计数器会在流过程中频繁递增，通常每 5 秒一次，这通常足以生成清晰的图表。由于重新计数会直接触碰热点路径，因此默认不启用，因为这可能导致会话数量极大时产生大量唤醒，从而造成轻微性能下降。 **`option disable-h2-upgrade`** ```haproxy option disable-h2-upgrade no option disable-h2-upgrade ``` 启用或禁用从 HTTP/1.x 客户端连接隐式升级至 HTTP/2。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 默认情况下，HAProxy 能够在从特定 HTTP 连接接收到的首个请求与 HTTP/2 连接前缀匹配时，隐式将 HTTP/1.x 客户端连接升级为 HTTP/2 连接（即字符串 "PRI \* HTTP/2.0\r\n\r\nSM\r\n\r\n"）。 通过这种方式，可在非 SSL 连接上同时支持 HTTP/1.x 与 HTTP/2 客户端。 必须使用此选项以禁用隐式升级。 请注意，此隐式升级仅支持 HTTP 代理，因此该选项也仅适用于 HTTP 代理。 此外，可通过在 bind 行指定 "proto h2" 强制在明文连接上启用 HTTP/2。 最后，此选项适用于所有 bind 行。 如需禁用特定 bind 行的隐式 HTTP/2 升级，可使用 "proto h1"。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 **`option dontlog-normal`** ```haproxy option dontlog-normal no option dontlog-normal ``` 启用或禁用正常、成功的连接日志记录 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 某些大型站点每秒需处理数千个连接，日志记录成为一大难题。部分站点甚至被迫关闭日志功能，无法对生产环境问题进行调试。启用此选项后，正常连接（即未发生错误、超时、重试或重分派的连接）将不会被记录。此举可为异常情况保留磁盘空间。在 HTTP 模式下，将检查响应状态码，状态码为 5xx 的响应仍会被记录。 强烈不建议使用此选项，因为大多数情况下，复杂问题的关键信息存在于常规日志中，而这些日志不会在此处记录。如需分离日志，请改用 `log-separate-errors` 选项。 另请参阅：“log”、“dontlognull”、“log-separate-errors”以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 中关于日志记录的内容。 **`option dontlognull`** ```haproxy option dontlognull no option dontlognull ``` 启用或禁用空连接日志记录 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 在某些环境中，存在一些组件会定期连接到各个系统，以确保其仍处于活跃状态。这可能是来自另一台负载均衡器，也可能是来自监控系统。默认情况下，即使是一个简单的端口探测或扫描也会产生日志。如果这些连接导致日志过于冗杂，可以启用选项 `dontlognull`，以指示未传输任何数据的连接将不会被记录，这通常对应于此类探测。请注意，错误仍会返回给客户端，并计入统计信息。若不希望如此，可改用选项 `http-ignore-probes`。 在不受控制的环境（例如互联网）中，通常不建议使用此选项，否则扫描及其他恶意活动将不会被记录。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“log”、“http-ignore-probes”、“monitor-uri”以及关于日志记录的[第 8 节](/zh/docs/haproxy/configuration-logging/)。 **`option external-check`** ```haproxy option external-check ``` 使用外部进程进行服务器健康检查 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 可以使用外部命令测试服务器的健康状态。这通过运行使用 "external-check command" 设置的可执行文件来实现。 必须设置全局选项 "external-check"。 另请参阅："external-check"、"external-check command"、"external-check path" **`option forwarded [ proto ]`** ```haproxy option forwarded [ proto ] [ host | host-expr ] [ by | by-expr ] [ by_port | by_port-expr ] [ for | for-expr ] [ for_port | for_port-expr ] no option forwarded ``` 启用在发送至服务器的请求中插入 rfc 7239 forwarded 头 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 可选参数，指定自定义样本表达式，将其结果用作 'host' 参数值。 可选参数，指定自定义样本表达式，将其结果用作 'by' 参数的节点名称值。 可选参数，指定自定义样本表达式，将其结果用作 'for' 参数的节点名称值。 可选参数，指定自定义样本表达式，将其结果用作 'by' 参数的节点端口值。 可选参数，指定自定义样本表达式，将其结果用作 'for' 参数的节点端口值。 ``` 由于 HAProxy 以反向代理模式运行，服务器会丢失部分请求上下文（例如请求来源：客户端 IP 地址、所用协议等...） 一种常见的应对此限制的方法是使用广为人知的 X-Forwarded-For 和 X-Forwarded-* 等头字段，将部分上下文信息暴露给底层服务器或应用程序。尽管过去该方法曾有效且广泛部署，但并未得到 IETF 的官方支持，可能引发互操作性及安全问题。 为解决此问题，IETF 已定义了一种新的 HTTP 扩展：forwarded 头（RFC7239）。更多信息请参见 此单一头字段的使用可在同一头中传递大量信息，且最重要的是，解决了代理链问题。（RFC 允许多个级联代理向已存在的头字段追加各自的值。） 该选项可在 defaults、listen 或 backend 段中指定，但在 frontend 段中将被忽略。 设置选项 forwarded 且不带参数时，将使用默认隐式行为。默认行为启用 proto 参数，并注入原始客户端 IP。 等效的显式/手动配置如下： ```text option forwarded proto for ``` 关键字 'by' 用于在转发头中启用 'by' 参数（"nodename"）。该功能允许嵌入请求代理信息。若不可用（例如：UNIX 监听器），'by' 值将设为 "unknown"。 关键字 'by-expr' 用于在转发头中启用 'by' 参数（"nodename"）。它允许嵌入请求代理信息。若样本表达式 `` 有效，则 'by' 值将被设置为该表达式的计算结果；否则，将被设置为 "unknown"。 关键字 'for' 用于在转发头中启用 'for' 参数（"nodename"）。它允许嵌入请求客户端信息。若不可用（例如：UNIX 监听器），'for' 值将设为 "unknown"。 关键字 'for-expr' 用于在转发头中启用 'for' 参数（"nodename"）。它允许嵌入请求客户端信息。若样本表达式 `` 有效，则 'for' 值将被设置为该表达式的计算结果；否则，将被设置为 "unknown"。 关键字 'by_port' 用于向 'by' 参数提供“nodeport”信息。'by_port' 要求必须设置 'by' 或 'by-expr'，否则将被忽略。若可用，“nodeport”将被设为代理（目标）端口，否则将被忽略。 关键字 'by_port-expr' 用于向 'by' 参数提供“nodeport”信息。'by_port-expr' 要求必须设置 'by' 或 'by-expr'，否则将被忽略。若样本表达式 `` 有效，“nodeport”将被设置为该表达式的计算结果，否则将被忽略。 关键字 'for_port' 用于向 'for' 参数提供“nodeport”信息。'for_port' 要求必须设置 'for' 或 'for-expr'，否则将被忽略。“nodeport”将在可用时设为客户端（源）端口，否则将被忽略。 关键字 'for_port-expr' 用于向 'for' 参数提供“nodeport”信息。'for_port-expr' 要求必须设置 'for' 或 'for-expr'，否则将被忽略。“nodeport”将被设置为样本表达式 `` 的结果（若有效），否则将被忽略。 示例： ```shell # Those servers want the ip address and protocol of the client request # Resulting header would look like this: # forwarded: proto=http;for=127.0.0.1 backend www_default mode http option forwarded #equivalent to: option forwarded proto for # Those servers want the requested host and hashed client ip address # as well as client source port (you should use seed for xxh32 if ensuring # ip privacy is a concern) # Resulting header would look like this: # forwarded: host="haproxy.org";for="_000000007F2F367E:60138" backend www_host mode http option forwarded host for-expr src,xxh32,hex for_port # Those servers want custom data in host, for and by parameters # Resulting header would look like this: # forwarded: host="host.com";by=_haproxy;for="[::1]:10" backend www_custom mode http option forwarded host-expr str(host.com) by-expr str(_haproxy) for for_port-expr int(10) # Those servers want random 'for' obfuscated identifiers for request # tracing purposes while protecting sensitive IP information # Resulting header would look like this: # forwarded: for=_000000002B1F4D63 backend www_for_hide mode http option forwarded for-expr rand,hex ``` 另请参阅："option forwardfor"、"option originalto" **`option forwardfor [ except ] [ header ] [ if-none ]`** ```haproxy option forwardfor [ except ] [ header ] [ if-none ] ``` 启用向发送至服务器的请求插入 X-Forwarded-For 头 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是可选参数，对匹配 的源禁用此选项。 是可选参数，指定不同的 "X-Forwarded-For" 头名称。 ``` 由于 HAProxy 以反向代理模式运行，服务器看到的客户端地址为其 IP 地址。 当服务器日志需要记录客户端的真实 IP 地址时，这种情况有时会造成困扰。为解决此问题，HAProxy 可在发送至服务器的所有请求中添加知名的 HTTP 头 “X-Forwarded-For”。该头包含表示客户端 IP 地址的值。由于此头始终被追加到现有头列表的末尾，服务器必须配置为仅使用该头的最后一个出现位置。请参阅服务器手册，了解如何启用对这一标准头的使用。请注意，仅应使用该头的最后一个出现位置，因为客户端可能已携带了该头。 关键字 "header" 可用于指定一个不同的头名称，以替代默认的 "X-Forwarded-For"。当可能已从其他应用（例如 stunnel）接收到 "X-Forwarded-For" 头时，此功能非常有用，可确保保留原有头信息。此外，若后端服务器不使用 "X-Forwarded-For" 头，而需要其他头（例如 Zeus Web 服务器要求使用 "X-Cluster-Client-IP"），也可通过此方式指定。 有时，同一个 HAProxy 实例可能同时用于直接客户端访问和反向代理访问（例如，当使用 SSL 反向代理解密 HTTPS 流量时）。可以通过添加 "except" 关键字并指定网络地址，禁用对已知源地址或网络的头信息添加。在此情况下，任何与该网络匹配的源 IP 都不会触发该头信息的添加。常见用法包括私有网络或 127.0.0.1。支持 IPv4 和 IPv6。 此外，关键字 "if-none" 表示仅当该头不存在时才添加该头。 此选项仅应在完全可信的环境中使用，因为如果传入 HAProxy 的头由终端用户控制，可能会引发安全问题。 该选项可在前端或后端中指定。若其中至少一个使用了该选项，将添加对应头信息。请注意，若前端和后端均定义了该头信息的子参数，则后端的设置优先于前端。对于 "if-none" 参数，若前端或后端中至少有一方未指定该参数，则其要求添加操作为强制性，因此该方优先。 示例： ```shell # Public HTTP address also used by stunnel on the same machine frontend www mode http option forwardfor except 127.0.0.1 # stunnel already adds the header # Those servers want the IP Address in X-Client backend www mode http option forwardfor header X-Client ``` 另请参阅：“option httpclose”、“option http-server-close”、“option http-keep-alive” **`option h1-case-adjust-bogus-client`** ```haproxy option h1-case-adjust-bogus-client no option h1-case-adjust-bogus-client ``` 启用或禁用向伪造客户端发送的 HTTP/1 头的大小写调整 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 由于 RFC7230 明确指出，头名称没有标准大小写形式，因此其大小写不敏感。 应用程序必须以不区分大小写的方式处理头名称。 但某些不合规的应用程序违反标准，错误地依赖浏览器通常使用的大小写形式。 这一问题在 HTTP/2 中变得尤为关键，因为所有头名称必须以小写形式传输，HAProxy 也遵循相同约定。 无论 HTTP 版本为何，所有头名称均以小写形式发送给客户端和服务器。 当 HAProxy 收到 HTTP/1 响应时，其头名称会被转换为小写形式，经处理后以该格式发送给客户端。若已知某客户端违反 HTTP 标准，且无法正确处理来自 HAProxy 的响应，则可通过启用此选项，并使用全局指令 h1-case-adjust 或 h1-case-adjust-file 指定需重新格式化的头列表，将小写头名称转换为其他格式后再发送给客户端。此操作仅应作为临时解决方案，待客户端修复期间使用，因为依赖此类 workaround 的客户端可能易受内容伪装攻击，必须彻底修复。 请注意，此选项不会影响符合标准的客户端。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option h1-case-adjust-bogus-server”、“h1-case-adjust”、“h1-case-adjust-file”。 **`option h1-case-adjust-bogus-server`** ```haproxy option h1-case-adjust-bogus-server no option h1-case-adjust-bogus-server ``` 启用或禁用向伪造服务器发送的 HTTP/1 头的大小写调整 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 由于 RFC7230 明确指出，头名称没有标准大小写形式，因此其大小写不敏感。 应用程序必须以不区分大小写的方式处理头名称。 但某些不合规的应用程序违反标准，错误地依赖浏览器通常使用的大小写形式。 这一问题在 HTTP/2 中变得尤为关键，因为所有头名称必须以小写形式传输，HAProxy 也遵循相同约定。 无论 HTTP 版本为何，所有头名称均以小写形式发送给客户端和服务器。 当 HAProxy 收到 HTTP/1 请求时，其请求头名称会被转换为小写形式，并以该格式发送至服务器。若已知某服务器违反 HTTP 标准，无法正确处理来自 HAProxy 的请求，则可通过启用此选项，并使用全局指令 `h1-case-adjust` 或 `h1-case-adjust-file` 指定需重新格式化的请求头列表，将小写请求头名称转换为其他格式后再发送至服务器。此操作仅应作为临时解决方案，用于等待服务器修复的过渡期间，因为依赖此类 workaround 的服务器可能易受内容伪装攻击，必须彻底修复。 请注意，此选项不会影响符合标准的服务器。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option h1-case-adjust-bogus-client”、“h1-case-adjust”、“h1-case-adjust-file”。 **`option http-buffer-request`** ```haproxy option http-buffer-request no option http-buffer-request ``` 启用或禁用在继续处理前等待接收完整的 HTTP 请求体 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 有时需要在获取 HTTP 请求体之后再做出决策。例如，“balance url_param” 就是这样做的。第一个用例是在连接到服务器之前，缓冲来自慢速客户端的请求。第二个用例是根据请求体的内容做出路由决策。在前端或后端中设置此选项，将强制 HTTP 处理等待，直到接收完整个请求体或请求缓冲区已满。对于某些滥用 HTTP 协议、期望前端与后端之间实现无缓冲传输的应用程序，此选项可能产生不良副作用，因此应务必避免默认启用。 另请参阅：“option http-no-delay”、“timeout http-request”、“http-request wait-for-body” **`option http-drop-request-trailers`** ```haproxy option http-drop-request-trailers no option http-drop-request-trailers ``` 从请求发送至服务器时移除 HTTP trailers 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| no \| yes 参数：无 启用此选项后，请求中发现的任何 HTTP 追随者（trailers）将在发送至服务器前被丢弃。 RFC9110#section-6.5.1 指出，尾部字段可以与头字段合并。这应为有意为之，但可能对某些应用程序造成问题，尤其是当恶意客户端将敏感头字段隐藏在尾部部分，而某些中间节点在未进行特定检查的情况下将其与头字段合并时。在此情况下，可在后端启用此选项，以在将请求发送至服务器前丢弃任何发现的尾部字段。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option http-drop-response-trailers" **`option http-drop-response-trailers`** ```haproxy option http-drop-response-trailers no option http-drop-response-trailers ``` 从响应中移除 HTTP trailers 后再发送给客户端 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 此选项与“option http-drop-request-trailers”类似，但必须用于在向客户端发送响应前丢弃响应中的尾部字段。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option http-drop-request-trailers" **`option http-ignore-probes`** ```haproxy option http-ignore-probes no option http-ignore-probes ``` 启用或禁用对空连接和请求超时的日志记录 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 最近，一些浏览器开始实现“预连接”功能，即在用户可能访问最近浏览过的网站时，预先建立连接。这导致大量连接被建立到网站，若超时先触发，则结果为 408 请求超时；若浏览器先决定关闭连接，则结果为 400 错误请求。这些情况会污染日志并增加错误计数器。虽然已有“option dontlognull”，但在此场景下仍不充分。相反，此选项执行以下操作：— 若连接关闭前未收到任何数据，则阻止向客户端发送任何 400/408 消息；— 在此情况下阻止生成任何日志；— 阻止任何错误计数器被递增 这样，空连接将被静默忽略。请注意，除非明确需要，否则不建议使用此选项，因为它会隐藏真实问题。未收到请求并看到 408 错误的最常见原因是客户端与中间设备（如 VPN）之间存在 MTU 不一致，导致过大数据包被阻断。此类问题通常也出现在 POST 请求以及携带大 Cookie 的 GET 请求中。日志通常是检测此类问题的唯一途径。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“log”、“dontlognull”、“errorfile”以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 中关于日志记录的内容。 **`option http-keep-alive`** ```haproxy option http-keep-alive no option http-keep-alive ``` 启用或禁用客户端到服务器的 HTTP/1.x 连接中的 HTTP 持久连接 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 默认情况下，HAProxy 以持久连接模式处理 HTTP/1.x 的持久连接：对于每个连接，它会处理每个请求和响应，并在两端保持连接空闲。可通过多个选项更改此模式，例如“option http-server-close”或“option httpclose”。此选项可恢复持久连接模式，当在 defaults 段中使用了其他模式时，此功能尤为有用。 设置 "option http-keep-alive" 可在客户端和服务器端启用 HTTP 持久连接模式。该模式在客户端侧可实现最低延迟（尤其适用于慢速网络），在服务器侧可实现最快会话复用，但需以维持与服务器的空闲连接为代价。通常情况下，使用此选项可使小对象的请求速率大约达到 "http-server-close" 选项的两倍。此选项主要适用于以下两种场景： - 当服务器不遵循 HTTP 规范且对连接而非请求进行认证时（例如 NTLM 认证）； - 当与服务器的连接建立开销相较于从服务器获取相关对象的开销更为显著 时。 最后一种情况可能出现在服务器是快速静态缓存服务器时。 目前，日志不会标明请求是否来自同一会话。日志中报告的接受时间对应于前一个请求的结束时间，请求时间对应于等待新请求所花费的时间。若未设置，持久连接的请求时间仍受 "timeout http-keep-alive" 或 "timeout http-request" 定义的超时限制。 此选项会禁用并替换任何先前配置的 "option httpclose" 或 "option http-server-close"。 另请参阅：“option httpclose”、“option http-server-close”、“option prefer-last-server”和“option http-pretend-keepalive”。 **`option http-no-delay`** ```haproxy option http-no-delay no option http-no-delay ``` 指示系统在 HTTP 中优先考虑较低的交互延迟，而非性能。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 在 HTTP 中，每个数据负载均为单向传输，且不涉及交互性概念。任何代理都应合理地对数据进行排队，以保证较低的延迟。极少数服务器到服务器的应用程序滥用 HTTP 协议，期望数据负载阶段具有高度交互性，即在单个请求中双向交错传输大量数据块。这完全不符合 HTTP 规范，且在大多数代理或服务器上无法正常工作。当此类应用程序通过 HAProxy 尝试实现时，虽然可以运行，但由于网络优化机制倾向于通过等待足够数据以发送完整数据包来提升性能，因此会遭遇显著延迟。典型延迟约为每往返一次 200 毫秒。请注意，这种情况仅出现在异常使用场景中。正常使用场景，如 CONNECT 请求或 WebSocket，不受影响。 当“option http-no-delay”出现在连接所使用的前端或后端中时，所有此类优化都将被禁用，以实现最快的数据交换。当然，这并不能保证功能正常，因为可能在其他任何位置出现故障。但如果应用程序通过 HAProxy 可以正常工作，那么其性能将达到最优。该选项不应默认启用，除非发现存在此类缺陷的应用程序，否则不应使用。启用该选项会导致带宽和 CPU 使用率上升，在高延迟环境中可能显著降低性能。 另请参阅："option http-buffer-request" **`option http-pretend-keepalive`** ```haproxy option http-pretend-keepalive no option http-pretend-keepalive ``` 定义 HAProxy 是否向服务器通告 HTTP/1.x 连接的保持连接状态。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当启用 "option http-server-close" 或 "option httpclose" 时，HAProxy 会在转发至服务器的 HTTP/1.x 请求中添加 "Connection: close" 头。不幸的是，当某些服务器检测到该头时，会自动停止对长度未知的响应使用分块编码，而这一行为与实际无关。结果是，客户端或缓存可能接收到不完整的响应却未察觉，误认为响应已完整。 通过设置 "option http-pretend-keepalive"，HAProxy 会令服务器误以为连接将保持活跃。服务器因此不会回退到上述异常的非期望状态。当 HAProxy 收到完整的响应后，将关闭与服务器的连接，其行为与启用 "option httpclose" 时一致。这样，客户端可获得正常的响应，且服务器端的连接得以正确关闭。 建议默认情况下不要启用此选项，因为大多数服务器在收到最后一个数据包后会更高效地自行关闭连接，并略微提前释放其缓冲区。此外，网络中增加的数据包可能会略微降低整体峰值性能。然而需要注意的是，启用此选项后，HAProxy 需要完成的工作量会略微减少。因此，如果 HAProxy 是整个架构中的性能瓶颈，启用此选项可能节省少量 CPU 周期。 该选项可在后端和 listen 段中设置。在前端段中使用将被忽略，并在启动时报告警告。此选项与后端相关，因此在前端设置并无实际意义。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option httpclose”、“option http-server-close” 和 “option http-keep-alive” **`option http-restrict-req-hdr-names { preserve | delete | reject }`** ```haproxy option http-restrict-req-hdr-names { preserve | delete | reject } ``` 设置 HAProxy 对包含非 "[a-zA-Z0-9-]" 字符集字符的 HTTP 请求头名称的处理策略 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text preserve 禁用过滤。这是未配置 FastCGI 应用程序的 HTTP 代理的默认模式。 delete 移除头名称包含 "[a-zA-Z0-9-]" 字符集以外字符的请求头。 这是配置了 FastCGI 应用程序的 HTTP 后端的默认模式。 reject 若请求的头名称包含 "[a-zA-Z0-9-]" 字符集以外的字符，则以 403-Forbidden 响应拒绝请求。 ``` 此选项可用于限制请求头名称仅包含字母、数字和连字符字符（[A-Za-z0-9-]）。在与不遵循 HTTP 协议的服务器互操作时，此限制可能是必须的，因为这些服务器无法正确处理头名称中的某些字符。对于 FastCGI 应用程序而言，此限制也可能为必须，因为头名称中所有非字母数字字符均会被下划线替换（'\_'）。因此，很容易混淆头名称并绕过某些规则。例如，“X-Forwarded-For” 和 "X_Forwarded-For" 头均会被转换为 "HTTP_X_FORWARDED_FOR"。 请注意，此选项按代理逐个评估，且在完成 http-request 规则评估之后进行。 **`option http-server-close`** ```haproxy option http-server-close no option http-server-close ``` 在服务器端启用或禁用 HTTP/1.x 连接关闭 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 默认情况下，HAProxy 以持久连接模式运行，针对持久的 HTTP/1.x 连接：对于每个连接，HAProxy 会处理每个请求和响应，并在两端保持连接空闲。可通过多个选项更改此模式，例如“option http-server-close”或“option httpclose”。设置“option http-server-close”可在服务器端启用 HTTP connection-close 模式，同时保留客户端侧支持 HTTP 持久连接和流水线化的能力。该模式可实现客户端侧（慢速网络）最低延迟，并在服务器端实现最快会话复用，以节省服务器资源，与“option httpclose”效果类似。此外，只要服务器符合 RFC7230 的要求，该模式还允许非持久连接能力的服务器以持久连接模式向客户端提供服务。请注意，部分服务器在收到请求中的“Connection: close”时，可能并不完全符合这些要求。其结果是持久连接将永远无法使用。一种解决方法是启用“option http-pretend-keepalive”。 目前，日志不会标明请求是否来自同一会话。日志中报告的接受时间对应于前一个请求的结束时间，请求时间对应于等待新请求所花费的时间。若未设置，持久连接的请求时间仍受 "timeout http-keep-alive" 或 "timeout http-request" 定义的超时限制。 该选项可在前端和后端中设置。若持有连接的前端或后端中至少有一个启用了此选项，则该选项生效。启用后将禁用并替换任何先前配置的“option httpclose”或“option http-keep-alive”。请查阅 [第 4 节](/zh/docs/haproxy/proxies/)（“代理”）了解当前端与后端选项不同时，此选项如何与其他选项协同工作。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option httpclose”、“option http-pretend-keepalive” 和 “option http-keep-alive”。 **`option http-use-proxy-header`** ```haproxy option http-use-proxy-header no option http-use-proxy-header ``` 使用非标准的 Proxy-Connection 头代替 Connection 头 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 根据 RFC7230 明确规定，HTTP/1.1 代理必须使用 Connection 头来表明其希望维持持久连接或非持久连接。然而，浏览器和代理在代理连接中均忽略该头，并改用未公开、非标准的 Proxy-Connection 头。当尝试在浏览器与此类代理之间部署负载均衡器时，问题便随之产生，因为 HAProxy 所理解的行为与客户端和代理之间所达成的共识存在差异。 通过在前端中设置此选项，HAProxy 可在检测到代理请求时自动切换至使用该非标准头。此处定义的代理请求是指 URI 既不以 '/' 也不以 '\*' 开头的请求。此选项与 HTTP 隧道模式不兼容。请注意，该选项只能在前端中指定，并将影响请求的整个生命周期。 此外，当设置此选项时，若请求需要认证，且该请求本身是通过代理转发的，则会自动切换为使用代理认证头。这使得可在现有代理前端检查或强制执行认证。 此选项通常不应使用，仅在代理前端使用时例外。 另请参阅：“option httpclose” 和 “option http-server-close”。 **`option httpchk`** ```haproxy option httpchk option httpchk option httpchk option httpchk option httpchk ``` 启用 HTTP 协议检查服务器健康状态 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是请求使用的可选 HTTP 方法。未设置时使用 "OPTIONS"，因为此方法通常处理开销较低， 且容易从日志中过滤掉。可使用任何方法，但不建议自行创建非标准方法。 是 HTTP 请求引用的 URI，默认值为 " / "，几乎任何服务器均默认可访问； 也可改为任何其他 URI，允许包含查询字符串。 是可选的 HTTP 版本字符串，默认值为 "HTTP/1.0"。 某些服务器在 HTTP 1.0 下可能行为异常，改用 HTTP/1.1 有时会有帮助。 注意，HTTP/1.1 要求必须提供 Host 字段。 是可选的 HTTP Host 头值，默认未设置。它是日志格式字符串。 ``` 默认情况下，服务器健康检查仅包含尝试建立 TCP 连接。当指定 "option httpchk" 时，在建立 TCP 连接后会发送完整的 HTTP 请求，响应码为 2xx 或 3xx 被视为有效，而所有其他响应均表示服务器故障，包括无任何响应的情况。 与 "http-check" 指令结合使用时，可自定义 HTTP 健康检查期间发送的请求，或配置对响应的匹配规则。也可配置 send/expect 序列，方式与 TCP 健康检查中的 "tcp-check" 指令相同。 默认情况下，服务器配置用于打开连接以执行 HTTP 健康检查。也可通过使用 "http-check connect" 规则覆盖服务器参数。 `httpchk` 选项并不要求必须使用 HTTP 后端，它同样适用于普通的 TCP 后端。这在使用 inetd 守护进程绑定到特定端口的简单脚本检测时尤为有用。然而，它始终内部依赖 HTX 多路复用器。因此，这意味着请求格式化和响应解析将严格遵循规范。 示例： ```shell # Relay HTTPS traffic to Apache instance and check service availability # using HTTP request "OPTIONS * HTTP/1.1" on port 80. backend https_relay mode tcp option httpchk OPTIONS * HTTP/1.1 http-check send hdr Host www server apache1 192.168.1.1:443 check port 80 ``` 另请参阅：`option ssl-hello-chk`、`option smtpchk`、`option mysql-check`、`option pgsql-check`、`http-check` 以及 `check`、`port` 和 `inter` 服务器选项。 **`option httpclose`** ```haproxy option httpclose no option httpclose ``` 启用或禁用 HTTP/1.x 连接关闭 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 默认情况下，HAProxy 以持久连接模式运行，针对持久的 HTTP/1.x 连接：每个连接在处理完每个请求和响应后，会在两端保持空闲状态。可通过多个选项更改此模式，例如 "option http-server-close" 或 "option httpclose"。 若设置 "option httpclose"，HAProxy 将根据该选项的设置位置关闭客户端或服务器连接。前端用于客户端连接，后端用于服务器连接。若在监听器上设置该选项，则同时作用于客户端和服务器连接。HAProxy 会检查每个方向是否已设置 "Connection: close" 头，若缺失则添加。 此选项还可与 "option http-pretend-keepalive" 一同使用，该选项将禁用发送 "Connection: close" 请求头，但接收完整响应后仍会关闭连接。 它会禁用并替换任何先前配置的 "option http-server-close" 或 "option http-keep-alive"。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option http-server-close"。 **`option httplog [ clf ]`** ```haproxy option httplog [ clf ] ``` 启用 HTTP 请求、流状态和计时器的日志记录 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text clf 添加 "clf" 参数后，输出采用 CLF 格式，而非 HAProxy 默认的 HTTP 格式。 当需要将 HAProxy 日志交给仅支持 CLF 格式且无法扩展的特定日志分析器时，可使用此项。 ``` 默认情况下，日志输出格式非常简陋，仅包含源地址和目标地址以及实例名称。通过指定 "option httplog"，每行日志将变为更丰富的格式，包括但不限于：HTTP 请求、连接计时器、流状态、连接数量、捕获的头字段和 Cookie、前端、后端及服务器名称，当然还包括源地址和端口。 仅指定 "option httplog" 时，将自动清除默认设置的 'clf' 模式。 "option httplog" 会覆盖之前设置的 "log-format" 指令。 另请参阅 [第 8 节](/zh/docs/haproxy/configuration-logging/) 中关于日志记录的内容。 **`option httpslog`** ```haproxy option httpslog ``` 启用 HTTPS 请求、流状态及计时器的日志记录 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 默认情况下，日志输出格式非常简陋，仅包含源地址和目标地址以及实例名称。通过指定 "option httpslog"，每行日志将变为更丰富的格式，包括但不限于：HTTP 请求、连接计时器、流状态、连接数量、捕获的头和 Cookie、前端、后端和服务器名称、SSL 证书验证状态和 SSL 握手状态，以及当然的源地址和端口。 "option httpslog" 会覆盖之前所有的 "log-format" 指令。 另请参阅 [第 8 节](/zh/docs/haproxy/configuration-logging/) 中关于日志记录的内容。 **`option idle-close-on-response`** ```haproxy option idle-close-on-response no option idle-close-on-response ``` 如果正在进行软停止，则避免关闭空闲的前端连接 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 默认情况下，软停止期间空闲连接将被关闭。在某些环境中，客户端与代理之间可能已建立一些空闲连接，以便稍后发送请求。如果未对写入错误进行适当的重试，这可能导致 HAProxy 重载时出现错误。尽管正确的实现应在连接或写入错误时重试，但此选项的引入是为了支持与 2.4 版本之前 HAProxy 的向后兼容性。事实上，在 2.4 版本之前，HAProxy 会在关闭连接前等待最后一个请求和响应，并添加 "Connection: close" 头，从而通知客户端该连接不可重用。 在实际案例中，此行为曾在 AWS 环境下观察到，即在 HAProxy 前端部署 ALB 时出现。最终结果为 ALB 在 HAProxy 重载期间返回 502 错误。 请注意，使用此选项可能导致连接空闲时间过长时旧进程数量增加。在频繁重载的情况下，可能需要相应调整客户端超时设置和/或“hard-stop-after”参数。 另请参阅：“timeout client”、“timeout client-fin”、“timeout http-request”、“hard-stop-after” **`option independent-streams`** ```haproxy option independent-streams no option independent-streams ``` 启用或禁用双向独立超时处理 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 默认情况下，当通过套接字发送数据时，该套接字的写超时和读超时都会被刷新，因为我们认为该套接字存在活动，且没有其他方式判断是否应接收数据。 当大多数应用程序均期望此默认行为时，仍存在一种情形下希望禁用该行为，仅在有传入数据时才刷新读取超时。这种情况常见于超时时间较长且交换数据量较小的流，例如 telnet 会话。若服务器突然消失，输出数据会累积在系统的套接字缓冲区中，两个超时均会被正确刷新，但无法得知服务器是否已无法接收这些数据，因此不会触发超时。然而，当底层协议始终回显已发送的数据时，仅通过读取超时即可自行检测该问题。请注意，该问题不会出现在更冗余的协议中，因为数据不会在套接字缓冲区中长时间累积。 当此选项在前端设置时，将禁用向客户端发送数据时的读取超时更新。此情况可能用途有限。当此选项在后端设置时，将禁用向服务器发送数据时的读取超时更新。此举通常会导致慢速链路上的大规模 HTTP 上传失败，因此应谨慎使用。 另请参阅：“timeout client”、“timeout server” 和 “timeout tunnel” **`option ldap-check`** ```haproxy option ldap-check ``` 使用 LDAPv3 健康检查测试服务器 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 可以测试服务器是否正确使用 LDAPv3 协议，而不仅仅是测试其是否接受 TCP 连接。启用此选项后，会向服务器发送 LDAPv3 匿名简单绑定消息，并分析响应以确认是否收到 LDAPv3 绑定响应消息。 仅当 LDAP 响应包含成功 resultCode（）时，服务器才被视为有效。 绑定请求的日志记录取决于服务器，具体配置方法请参阅相关文档。 示例： ```text option ldap-check ``` 另请参阅："option httpchk" **`option log-health-checks`** ```haproxy option log-health-checks no option log-health-checks ``` 启用或禁用健康检查状态更新的日志记录 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 默认情况下，当服务器处于 UP 状态时，会记录失败的健康检查；当服务器处于 DOWN 状态时，会记录成功的健康检查，因此额外信息的记录量有限。 当启用此选项时，健康检查状态或服务器健康状况的任何变化都将被记录，从而能够知晓某服务器在崩溃前是否曾间歇性地检查失败，或确切地了解其何时未能响应有效的 HTTP 状态，何时端口开始拒绝连接，以及何时服务器完全停止响应。 请注意，由健康检查以外的原因引起的状态变更（例如通过 CLI 执行的启用/禁用操作）不会被此选项记录。 另请参阅：“option httpchk”、“option ldap-check”、“option mysql-check”、“option pgsql-check”、“option redis-check”、“option smtpchk”、“option tcp-check”、“log”以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 关于日志记录的内容。 **`option log-separate-errors`** ```haproxy option log-separate-errors no option log-separate-errors ``` 更改非完全成功连接的日志级别 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 有时在日志中查找错误并不容易。此选项可提升包含潜在重要信息的日志级别，例如错误、超时、重试、重分派或 HTTP 状态码 5xx。日志级别将从“info”提升至“err”。这使得大多数 syslog 守护进程能够将这些日志单独记录到不同的文件中。请注意，不要从原始文件中移除这些日志，否则将丢失顺序信息，而顺序信息提供了非常重要的上下文。 使用此选项，处理每秒数千个连接的大型站点可将正常流量日志记录至循环缓冲区，仅归档较小的错误日志。 另请参阅：“log”、“dontlognull”、“dontlog-normal”以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 中关于日志记录的内容。 **`option logasap`** ```haproxy option logasap no option logasap ``` 启用或禁用早期日志记录。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 默认情况下，当日志格式别名和样本提取项在日志格式字符串定义中全部返回值，或流终止时，将输出日志。这使得内置日志格式字符串能够计入传输时间，或日志消息中的字节数。 当处理长连接（如大文件传输或 RDP）时，请求或连接在日志中出现可能需要较长时间。使用 "option logasap" 选项后，日志消息将在 TCP 模式下服务器连接建立时，或 HTTP 模式下服务器发送完整头信息时立即生成。日志中缺失的信息包括总字节数，该值仅反映消息生成前已传输的数据量，以及总时间，该值未计入连接剩余生命周期或传输时间。对于 HTTP 情况，建议捕获 Content-Length 响应头，以便日志至少能指示预期传输的字节数。 示例： ```text listen http_proxy 0.0.0.0:80 mode http option httplog option logasap log 192.168.2.200 local3 ``` ```text >>> Feb 6 12:14:14 localhost \ haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \ "GET /image.iso HTTP/1.0" ``` 另请参阅："option httplog"、"capture response header"，以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 关于日志记录的内容。 **`option mysql-check [ user [ { post-41 | pre-41 | post-80 } ] ]`** ```haproxy option mysql-check [ user [ { post-41 | pre-41 | post-80 } ] ] ``` 使用 MySQL 健康检查对服务器进行测试 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是连接 MySQL 服务器时使用的用户名。 post-41 发送兼容 v4.1 之后客户端的检查（默认值）。 pre-41 发送兼容 v4.1 之前客户端的检查。 post-80 发送兼容 v8.0 之后客户端的检查，设置 CLIENT_PLUGIN_AUTH 能力， 并使用 mysql_native_password 认证插件。 连接 MySQL 8.0+ 服务器且健康检查用户使用 mysql_native_password 认证时，使用此选项。例如： CREATE USER 'haproxy'@'%' IDENTIFIED WITH mysql_native_password BY ''; ``` 若指定用户名，检查过程将发送两个 MySQL 数据包：一个客户端认证数据包和一个 QUIT 数据包，以正确关闭 MySQL 会话。随后，解析 MySQL 握手初始化数据包和/或错误数据包。这是一种基础但实用的测试，不会在服务器端产生错误或中断连接。然而，该测试要求存在一个未锁定且无密码的授权用户。要在 MySQL 中创建一个基本的受限用户并可选地设置资源限制： ```text CREATE USER ''@'' /*!50701 WITH MAX_QUERIES_PER_HOUR 1 MAX_UPDATES_PER_HOUR 0 */ /*M!100201 MAX_STATEMENT_TIME 0.0001 */; ``` 如果不指定用户名（该做法已弃用且不推荐），检查仅包括解析 MySQL 握手初始化数据包或错误数据包，此模式下不会发送任何内容。有报告指出，若检查频率过高和/或流量不足，可能导致锁定。实际上，在此情况下，需检查 MySQL "max_connect_errors" 值，即如果在前一次连接中断后，服务器在少于 MySQL "max_connect_errors" 次尝试内成功建立连接，则该主机的错误计数将被清零。若 HAProxy 服务器被阻塞，“FLUSH HOSTS” 语句是解除阻塞的唯一方法。 请注意，这不会检查数据库是否存在或数据库一致性。如需执行此类检查，可以使用 xinetd 等外部检查工具。 该检查要求 MySQL 版本 ≥ 3.22，对于较旧版本，请使用 TCP 检查。 通常情况下，传入的 MySQL 服务器需要看到客户端的 IP 地址，以实现多种用途，包括 IP 权限匹配和连接日志记录。在可能的情况下，建议在通过 "source" 关键字的 "usesrc" 参数连接服务器时，对客户端 IP 地址进行伪装，这需要透明代理功能已编译启用，并且 MySQL 服务器需通过运行 HAProxy 的主机来路由客户端连接。 另请参阅："option httpchk" **`option nolinger`** ```haproxy option nolinger no option nolinger ``` 启用或禁用会话关闭后立即清理资源 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 当客户端或服务器以非正常方式中止连接（例如，物理断开连接）时，会话超时将被触发，会话随之关闭。但该会话将在系统中保持 FIN_WAIT1 状态一段时间，占用部分资源，并可能限制建立新连接的能力。 当发生此情况时，可以启用“option nolinger”选项，强制系统在关闭连接时立即清除套接字中待处理的数据。此时会发出 TCP RST，待处理数据被截断，会话将立即从系统的表中清除。对客户端而言，通常可见的效果是：若关闭操作发生在最后一个数据块时（例如重定向或错误响应），响应数据会被截断。在服务器端，当通过隧道转发时，若客户端中断连接，该选项有助于立即释放源端口。两种情况下均会发出 TCP 重置，由于会话被立即销毁，因此不会发生重传。在丢包率较高的网络中，这可能加剧问题，尤其是在丢包侧存在防火墙时，因为防火墙可能接收到并处理该重置（从而清除其会话状态），并阻止该会话的后续流量，包括来自另一侧的重传数据。因此，若另一侧未收到该重置，将永远无法再次接收 RST，而防火墙可能会记录大量被阻断的数据包。 出于上述所有原因，强烈建议不要使用此选项，除非在万不得已的情况下作为最后手段。在大多数场景中，使用 "client-fin" 或 "server-fin" 超时可实现类似效果，且行为更加可靠。在 Linux 上，还可选择使用 "tcp-ut" 绑定或服务器设置。 该选项可在前端和后端中使用，具体取决于其所需的位置。 在前端使用以处理客户端，在后端使用以处理服务器。 尽管该选项在“defaults”段中技术上受支持，但应避免在此处使用，以免意外传播至本不应使用该选项的段，从而引发问题。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“timeout client-fin”、“timeout server-fin”、“tcp-ut” 绑定或服务器关键字。 **`option originalto [ except ] [ header ]`** ```haproxy option originalto [ except ] [ header ] ``` 启用向发送至服务器的请求中插入 X-Original-To 头 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数： ```text 是可选参数，对匹配 的源禁用此选项。 是可选参数，指定不同的 "X-Original-To" 头名称。 ``` 由于 HAProxy 可以工作在透明模式下，客户端的每个请求都可能被重定向至代理，而 HAProxy 本身可将每个请求转发至复杂的 SQUID 环境，此时 SO_ORIGINAL_DST 的目标主机将丢失。当需要基于目标 IP 地址设置访问规则时，这种情况会带来困扰。为解决此问题，HAProxy 可向发送至服务器的所有请求添加新的 HTTP 头 "X-Original-To"。该头包含表示原始目标 IP 地址的值。必须配置为仅使用该头的最后一次出现。请注意，仅应使用该头的最后一次出现，因为客户端可能已携带了该头。 关键字 "header" 可用于指定一个不同的头名称，以替换默认的 "X-Original-To"。当可能已从其他应用接收了 "X-Original-To" 头，且需要保留该头时，此功能非常有用。此外，若后端服务器不使用 "X-Original-To" 头，而需要其他头名称时，也可使用此功能。 有时，同一个 HAProxy 实例可能同时用于直接客户端访问和反向代理访问（例如，当使用 SSL 反向代理解密 HTTPS 流量时）。可以通过添加 "except" 关键字并指定网络地址，禁用对已知目标地址或网络的头字段添加。在此情况下，任何与该网络匹配的目标 IP 都不会触发该头字段的添加。常见用法包括私有网络或 127.0.0.1。支持 IPv4 和 IPv6。 该选项可在前端或后端中指定。若其中至少一个使用了该选项，将添加该头。请注意，若前后端均定义了该头的子参数，后端的设置将优先于前端。 示例： ```shell # Original Destination address frontend www mode http option originalto except 127.0.0.1 # Those servers want the IP Address in X-Client-Dst backend www mode http option originalto header X-Client-Dst ``` 另请参阅：“option httpclose”、“option http-server-close”。 **`option persist`** ```haproxy option persist no option persist ``` 启用或禁用对已关闭服务器的强制持久化 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当 HTTP 请求到达一个包含引用已失效服务器的 cookie 的后端时，默认情况下会将其重分派至另一台服务器。若确实需要，可使用“option persist”强制请求首先发送至该已失效服务器。常见应用场景为服务器处于极端负载状态，导致其频繁波动。在此情况下，用户仍会被引导至其会话初始连接的服务器，以期获得正确服务。建议与该选项配合使用“option redispatch”，以便在无法连接至该服务器（服务器已彻底失效）时，最终将客户端重定向至另一台有效服务器。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：“option redispatch”、“retries”、“force-persist” **`option pgsql-check user `** ```haproxy option pgsql-check user ``` 使用 PostgreSQL 健康检查对服务器进行测试 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是连接 PostgreSQL 服务器时使用的用户名。 ``` 该检查发送一个 PostgreSQL StartupMessage，并等待收到 Authentication request 或 ErrorResponse 消息。这是一种基础但实用的测试，不会在服务器端产生错误或中断连接。此检查与 "mysql-check" 完全相同。 另请参阅："option httpchk" **`option prefer-last-server`** ```haproxy option prefer-last-server no option prefer-last-server ``` 允许多个负载均衡的请求保持在同一个服务器上 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当所使用的负载均衡算法不具备确定性时，若此前请求已发送至 HAProxy 仍保持连接的服务器，则在同一会话中尽可能将后续请求也发送至同一服务器，有时是可取的。请注意，这与持久性不同，因为此处仅表示一种偏好，HAProxy 会尝试应用该偏好，但不提供任何形式的保证。此功能的实际用途在于对服务器发起的持久连接。启用该选项后，HAProxy 将尝试复用与服务器关联的现有连接，而非重新均衡至另一服务器，从而避免关闭连接。该机制对静态文件服务器具有实际意义。与哈希算法结合使用时，此选项意义不大。请注意，当负载均衡算法不具备确定性时，HAProxy 已自动尝试保持与返回 401 响应的服务器或返回 407 响应的代理（需认证）的连接。在处理存在缺陷的 NTLM 认证挑战时，此行为为强制要求，且对排查部分异常应用具有显著帮助。在这些环境中，启用 prefer-last-server 选项也可能有益，以避免每次响应后重新分配流量。 本文档中明确指出，哪些负载均衡算法属于确定性算法较为有用。 确定性算法在可用服务器集合未发生变化的前提下，对给定客户端数据始终选择相同的服务器。通常情况下，确定性算法通过哈希或查找传入请求中的信息来选择目标服务器。然而，这并非总是成立；例如，“static-rr”算法也可视为确定性算法，因为服务器选择基于服务器的静态权重，使得选择结果可预测。“sticky”算法为返回客户端提供确定性路由。 对于非确定性算法，这些算法根据动态服务器状态或简单轮询选择服务器，因此两个连续的请求无法保证落在同一台服务器上。option prefer-last-server 专门为此类算法设计。roundrobin 和 leastconn 即为这类算法的示例。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option http-keep-alive" **`option redispatch`** ```haproxy option redispatch option redispatch no option redispatch ``` 在连接失败时启用或禁用会话重分派 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是可选的整数值，控制连接重试时重分派的频率。 正值 P 表示每第 P 次重试发生重分派；负值 N 表示在最终重试之前倒数第 N 次重试发生重分派。 例如，默认值 -1 保留原有行为，在最后一次重试时重分派； 正值 1 表示每次重试都重分派；正值 3 表示每第三次重试重分派。 值为 0 时禁用重分派。 ``` 在 HTTP 模式下，如果客户端通过 Cookie 指定的服务器宕机，客户端可能会持续连接到该服务器，例如使用 "option persist" 或 "force-persist" 时，因为客户端无法清除 Cookie，将无法再访问服务。 启用 "option redispatch" 可使代理打破基于 cookie 或一致性哈希的持久性，将请求重新分派至可用的服务器。 从可用服务器列表的子集中选择活跃服务器。未处于宕机或维护状态（即未进行健康检查，或已被检查为“正常”）的活跃服务器，按以下顺序进行选择： ```text 1. 任何活跃的非备用服务器（若有），否则 2. 若未设置 "allbackups" 选项，则为列表中的第一个备用服务器，否则 3. 若设置了 "allbackups" 选项，则为任何备用服务器。 ``` 重试时，HAProxy 会尝试选择除上一次以外的另一台服务器。新服务器将从当前服务器列表中选取。 有时，如果在重试期间更新了列表（例如，发生大量重试且耗时超过检查服务器是否已宕机所需的时间，导致将其从列表中移除并回退到备用服务器列表），连接仍可能被重定向至备用服务器。 它还允许在发生多次连接失败时，重试连接到另一台服务器。当然，这要求将“retries”设置为非零值。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option persist"、"force-persist"、"retries" **`option redis-check`** ```haproxy option redis-check ``` 使用 Redis 健康检查对服务器进行测试 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 可以测试服务器是否正确使用 REDIS 协议，而不仅仅是测试其是否接受 TCP 连接。启用此选项后，HAProxy 会向服务器发送 PING REDIS 命令，并分析响应以查找 "+PONG" 响应消息。 示例： ```text option redis-check ``` 另请参阅："option httpchk"、"option tcp-check"、"tcp-check expect" **`option smtpchk`** ```haproxy option smtpchk option smtpchk ``` 使用 SMTP 健康检查测试服务器 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是可选参数，指定使用的 "hello" 命令，可为 "HELO"（SMTP）或 "EHLO"（ESMTP）。 所有其他值均转换为默认命令（"HELO"）。 是向服务器通告的域名，仅在指定了 hello 命令时才能设置（此时必须设置）。 默认使用 "localhost"。 ``` 当设置 "option smtpchk" 时，健康检查将包含 TCP 连接后跟一个 SMTP 命令。默认情况下，该命令为 "HELO localhost"。服务器返回的响应码将被分析，仅以 "2" 开头的响应码被视为有效。所有其他响应，包括无响应的情况，均视为错误，并表示服务器已失效。 此测试适用于 SMTP 服务器或中继。根据请求的不同，某些服务器可能不会记录每次连接尝试，因此建议进行试验以优化行为。使用 telnet 连接端口 25 通常比调整配置更简便。 大多数情况下，传入的 SMTP 服务器需要查看客户端的 IP 地址，以实现多种目的，包括垃圾邮件过滤、防伪造和日志记录。在可能的情况下，建议在使用 "source" 关键字的 "usesrc" 参数连接服务器时，对客户端 IP 地址进行伪装，这需要编译时启用透明代理功能。 示例： ```text option smtpchk HELO mydomain.org ``` 另请参阅："option httpchk"、"source" ```haproxy option socket-stats no option socket-stats ``` 启用或禁用为每个套接字单独收集和提供统计信息。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 **`option splice-auto`** ```haproxy option splice-auto no option splice-auto ``` 启用或禁用套接字在两个方向上的自动内核加速 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 当在前端或后端启用此选项时，HAProxy 将自动评估是否可利用内核 TCP 拼接技术在客户端与服务器之间双向转发数据。HAProxy 使用启发式算法估算拼接是否可能提升性能。两个方向的处理相互独立。请注意，所采用的启发式算法并不激进，以避免拼接的过度使用。此选项要求在编译时启用拼接功能，并可通过全局选项 "nosplice" 全局禁用。由于拼接使用管道，因此使用该功能需确保有足够的空闲管道。 重要提示：基于内核的 TCP 拼接是 Linux 特有的功能，最早出现在内核 2.6.25 版本中。该功能通过在内核层面直接在套接字之间传输数据，无需将数据复制到用户空间，从而显著提升性能并节省 CPU 周期。由于早期实现存在缺陷，可能导致数据损坏或效率低下，因此该功能默认未启用，使用时应格外谨慎。尽管无法检测实现的正确性，但 2.6.29 版本是首个提供正确实现的版本。如有疑问，可使用全局配置项 "nosplice" 全局禁用拼接功能。 示例： ```text option splice-auto ``` 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：`option splice-request`、`option splice-response` 以及全局选项 `nosplice` 和 `maxpipes` **`option splice-request`** ```haproxy option splice-request no option splice-request ``` 启用或禁用请求的套接字自动内核加速 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 当在前端或后端启用此选项时，HAProxy 将尽可能使用内核 TCP 拼接技术，将客户端到服务器的数据直接转发。若无可用的管道资源，仍可能采用 recv/send 方式。此选项需在编译时启用拼接功能，且可通过全局选项 "nosplice" 全局禁用。由于拼接依赖管道，使用该功能要求系统具备足够的空闲管道资源。 请注意：有关使用限制，请参阅“option splice-auto”。 示例： ```text option splice-request ``` 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option splice-auto"、"option splice-response" 以及全局选项 "nosplice" 和 "maxpipes" **`option splice-response`** ```haproxy option splice-response no option splice-response ``` 启用或禁用对响应的套接字自动进行内核加速 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 当在前端或后端启用此选项时，HAProxy 将尽可能使用内核 TCP 拼接技术，将数据从服务器转发至客户端。若无可用的管道资源，仍可能采用 recv/send 方式。此选项需在编译时启用拼接功能，且可通过全局选项 "nosplice" 全局禁用。由于拼接依赖管道，使用该功能要求系统具备足够的空闲管道资源。 请注意：有关使用限制，请参阅“option splice-auto”。 示例： ```text option splice-response ``` 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option splice-auto"、"option splice-request" 以及全局选项 "nosplice" 和 "maxpipes" **`option spop-check`** ```haproxy option spop-check ``` 使用 SPOP 健康检查对服务器进行测试 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 可以测试服务器是否正确地使用 SPOP 协议，而不仅仅是测试其是否接受 TCP 连接。启用此选项后，HAProxy 与服务器之间将执行 HELLO 握手，随后分析响应以检查是否报告了错误。 示例： ```text option spop-check ``` 另请参阅："option httpchk" **`option srvtcpka`** ```haproxy option srvtcpka no option srvtcpka ``` 启用或禁用在服务器端发送 TCP keepalive 数据包 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当客户端与服务器之间存在防火墙或其他会话感知组件，且协议涉及长时间会话及较长空闲期（例如远程桌面）时，中间组件可能因会话空闲时间过长而决定终止该会话，从而带来风险。 启用套接字级别的 TCP 持久连接可使系统定期向连接的另一端发送数据包，从而保持连接处于活跃状态。持久连接探测之间的延迟由系统控制，且取决于操作系统及其调优参数。 必须理解，持久连接报文不会在应用层发出或接收，仅网络协议栈能够感知到它们。因此，即使代理的一端已使用持久连接来维持连接活跃，这些持久连接报文也不会被转发至代理的另一端。 请注意，这与 HTTP 持久连接无关。 使用选项 "srvtcpka" 可在连接的服务器端启用 TCP 持久连接探测，当 HAProxy 与服务器之间的会话超时被察觉时，此功能应能提供帮助。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option clitcpka"、"option tcpka" **`option ssl-hello-chk`** ```haproxy option ssl-hello-chk ``` 使用 SSLv3 客户端问候消息进行服务器健康检查 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 当通过 HAProxy 以 TCP 模式中继某些基于 SSL 的协议时，可以测试服务器是否正确地使用 SSL 通信，而不仅仅是测试其是否接受 TCP 连接。当设置 "option ssl-hello-chk" 时，连接建立后会向服务器发送一个纯 SSLv3 客户端问候消息，然后分析响应以查找 SSL 服务器问候消息。只有当响应中包含该服务器问候消息时，才认为服务器有效。 所有服务器均经过测试，确保其能正确响应 SSLv3 客户端握手消息，且大多数服务器甚至不会记录仅包含握手消息的请求，这一点值得肯定。 请注意，即使 HAProxy 未编译 SSL 支持，此健康检查仍可正常工作，因为它会伪造 SSL 消息。当 SSL 支持可用时，建议使用原生 SSL 健康检查，而非此方法。 另请参阅：“option httpchk”、“check-ssl” **`option tcp-check`** ```haproxy option tcp-check ``` 使用 tcp-check send/expect 序列执行健康检查 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 此健康检查方法旨在与“tcp-check”命令列表结合使用，以支持发送/期望类型的健康检查序列。 TCP 健康检查目前支持 4 种操作模式： - 无 "tcp-check" 指令：健康检查仅包含一次连接尝试，此为默认模式。 - 仅提及 "tcp-check send" 或 "tcp-check send-binary"：用于在建立连接的 同时发送一个字符串。对于某些协议，例如发送 "QUIT" 消息可避免服务器 为每次健康检查记录连接错误。检查结果仍仅基于能否打开连接。 - 仅提及 "tcp-check expect"：用于测试欢迎横幅（banner）。连接打开后， HAProxy 等待服务器呈现一些内容，这些内容必须通过某些规则的校验。 检查结果将基于内容与规则之间的匹配情况。适用于 POP、IMAP、SMTP、 FTP、SSH、TELNET。 - 同时提及 "tcp-check send" 和 "tcp-check expect"：用于测试 hello 类 协议。HAProxy 发送消息，服务器作出响应，随后分析该响应。检查结果 将基于响应内容与规则之间的匹配情况。这通常适用于需要绑定或请求/ 响应模型的协议。LDAP、MySQL、Redis 和 SSL 就是此类协议的例子，尽管 它们均已具有对相应协议理解更深入的专用检查。在此模式下，可以发送 多个问题，并分析多个应答。 第五种模式可用于在脚本的不同步骤中插入注释。 对于每个创建的 tcp-check 规则，可以添加一个 "comment" 指令，后接一个字符串。该字符串将在日志中以及调试模式下的 stderr 中输出。此功能有助于实现用户友好的错误报告。"comment" 指令为可选。 在执行健康检查期间，可通过使用 "tcp-check set-var" 操作，提供变量作用域以存储数据样本。可使用 "tcp-check unset-var" 释放这些变量。 示例： ```shell # perform a POP check (analyze only server's banner) option tcp-check tcp-check expect string +OK\ POP3\ ready comment POP\ protocol # perform an IMAP check (analyze only server's banner) option tcp-check tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol # look for the redis master server after ensuring it speaks well # redis protocol, then it exits properly. # (send a command then analyze the response 3 times) option tcp-check tcp-check comment PING\ phase tcp-check send PING\r\n tcp-check expect string +PONG tcp-check comment role\ check tcp-check send info\ replication\r\n tcp-check expect string role:master tcp-check comment QUIT\ phase tcp-check send QUIT\r\n tcp-check expect string +OK 构造一个 HTTP 请求，然后分析响应 （分析前发送多个头） option tcp-check tcp-check comment forge\ and\ send\ HTTP\ request tcp-check send HEAD\ /\ HTTP/1.1\r\n tcp-check send Host:\ www.mydomain.com\r\n tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n tcp-check send \r\n tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response ``` 另请参阅：“tcp-check connect”、“tcp-check expect” 和 “tcp-check send”。 **`option tcp-smart-accept`** ```haproxy option tcp-smart-accept no option tcp-smart-accept ``` 启用或禁用在连接建立过程中保存一个 ACK 数据包 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数：无 当 HTTP 连接请求到达时，系统会代表 HAProxy 进行确认，随后客户端立即发送请求，系统在通知 HAProxy 新连接的同时也对该请求进行确认。HAProxy 随后读取请求并发送响应。这意味着系统会额外发送一次 TCP ACK，而该 ACK 实际上是多余的，因为 HAProxy 完全可以在发送响应时一并确认该请求。 因此，在 HTTP 模式下，HAProxy 会自动请求系统在支持该功能的平台（目前至少包括 Linux）上避免发送此无用的 ACK。这不会造成任何问题，因为如果响应耗时超过预期，系统将在 40 毫秒后仍会发送该 ACK。 在复杂的网络故障排查会话中，可能需要禁用此优化，因为延迟确认（delayed ACKs）会使排查数据包延迟位置时更加复杂。此时可通过指定“no option tcp-smart-accept”恢复到正常行为。 也可以通过简单地指定“option tcp-smart-accept”来强制对非 HTTP 代理生效。例如，对于 SMTP 等某些服务，服务器会先发起通信，此时该选项可能具有实际意义。 建议避免在 defaults 段中强制设置此选项。如有疑问，可通过在该选项前添加 "default" 关键字将其恢复为自动值，或使用 "no" 关键字禁用该选项。 另请参阅："option tcp-smart-connect" **`option tcp-smart-connect`** ```haproxy option tcp-smart-connect no option tcp-smart-connect ``` 启用或禁用在连接过程中保存一个 ACK 数据包 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 在某些系统（至少为 Linux）上，HAProxy 可以请求内核在收到连接请求时，不立即发送空的 ACK，而是直接发送缓冲区请求。此举可减少网络中一个数据包的传输，从而提升性能。对于某些服务器而言，此机制也具有实用性，因为它们能随连接建立立即获取请求数据。 当后端中设置 "option tcp-smart-connect" 时，此功能被启用。由于该功能会增加网络故障排查的复杂性，因此默认情况下未启用。 仅在客户端率先发起通信的协议（如 HTTP）中启用此功能才有意义。在其他情况下，若无数据可替代 ACK 发送，则发送正常的 ACK。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅："option tcp-smart-accept" **`option tcpka`** ```haproxy option tcpka ``` 启用或禁用在两端发送 TCP keepalive 数据包 可用于以下上下文：tcp、http、log 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes 参数：无 当客户端与服务器之间存在防火墙或其他会话感知组件，且协议涉及长时间会话及较长空闲期（例如远程桌面）时，中间组件可能因会话空闲时间过长而决定终止该会话，从而带来风险。 启用套接字级别的 TCP 持久连接可使系统定期向连接的另一端发送数据包，从而保持连接处于活跃状态。持久连接探测之间的延迟由系统控制，且取决于操作系统及其调优参数。 必须理解，持久连接报文不会在应用层发出或接收，仅网络协议栈能够感知到它们。因此，即使代理的一端已使用持久连接来维持连接活跃，这些持久连接报文也不会被转发至代理的另一端。 请注意，这与 HTTP 持久连接无关。 启用选项 "tcpka" 可在连接的客户端和服务器两端均发送 TCP 持久连接探测。请注意，此选项仅在 "defaults" 或 "listen" 段中有效。若在前端中使用此选项，仅客户端会启用持久连接；若在后端中使用此选项，仅服务器端会启用持久连接。因此，强烈建议在配置跨前端和后端分布时，显式使用 "option clitcpka" 和 "option srvtcpka"。 另请参阅："option clitcpka"、"option srvtcpka" **`option tcplog [clf]`** ```haproxy option tcplog [clf] ``` 启用 TCP 连接的高级日志记录，包括流状态和计时器信息 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text clf 添加 "clf" 参数后，输出采用 CLF 格式，而非 HAProxy 默认的 TCP 格式。 当需要将 HAProxy 日志交给仅支持 CLF 格式且无法扩展的特定日志分析器时，可使用此项。 由于此格式要求 HTTP 格式，部分值已预设：HTTP 请求显示为 TCP，响应码显示为 000。 ``` 默认情况下，日志输出格式非常简陋，仅包含源地址和目标地址以及实例名称。通过指定“option tcplog”，每条日志行将变为更丰富的格式，包含但不限于连接计时器、流状态、连接数量、前端、后端和服务器名称，以及源地址和端口。该选项适用于纯 TCP 代理，以便确定是客户端还是服务器端断开连接或超时。对于常规 HTTP 代理，建议使用“option httplog”，其信息更为完整。 "option tcplog" 会覆盖之前所有的 "log-format" 指令。 另请参阅：“option httplog”，以及 [第 8 节](/zh/docs/haproxy/configuration-logging/) 关于日志记录的内容。 **`option transparent (deprecated)`** ```haproxy option transparent (deprecated) no option transparent (deprecated) ``` 启用客户端透明代理 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数：无 此选项的引入旨在为第 3 层负载均衡器提供第 7 层持久性。其原理是利用操作系统将来自远程地址的入站连接重定向至本地进程（此处为 HAProxy），并让该进程知晓最初请求的地址。启用此选项后，未携带 Cookie 的会话将被转发至入站请求的原始目标 IP 地址（该地址应与另一台设备的地址匹配），而携带 Cookie 的请求仍会被转发至相应的服务器。 请注意，与普遍认知相反，此选项并不会在建立连接时向服务器呈现客户端的 IP 地址。 从 3.3 版本开始，该选项已被弃用，因其曾存在多项内部技术限制。使用该选项将发出警告，如确需使用，可通过全局关键字 "expose-deprecated-directives" 避免警告。 正确做法是在地址 0.0.0.0 上声明一个服务器，该服务器将负责连接到预期的目标地址。服务器还将正确处理与目标服务器的空闲连接。 示例： ```shell # option transparent ## before 3.3 server transparent 0.0.0.0 ``` 另请参阅“source”关键字的“usesrc”参数，以及“bind”关键字的“transparent”选项。 option use-small-buffers [ queue \| l7-retries \| check ]\* 为指定类别启用小缓冲区支持。 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 此选项可用于在不同位置启用小缓冲区支持，以节省内存。默认情况下，不带参数时，尽可能在所有可能的位置使用小缓冲区。否则，可将其限制为仅在以下位置启用： - queue：启用后，若连接被排队，将使用小缓冲区存储请求，前提是请求足够小。 - l7-retries：启用后，启用 L7 重试时将使用小缓冲区保存请求。 - check：启用后，健康检查请求将使用小缓冲区。 启用后，将使用小缓冲区，但仅在可行时。若数据过大，则自动改用常规缓冲区。小缓冲区的大小可通过 "tune.bufsize.small" 全局设置进行配置。 如果该选项在“defaults”段中已启用，可以在特定实例中通过在其前添加“no”关键字来禁用。 另请参阅：tune.bufsize.small **`persist rdp-cookie`** ```haproxy persist rdp-cookie persist rdp-cookie() ``` 启用基于 RDP 会话 Cookie 的持久性 可用于以下上下文：tcp 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| no \| yes \| yes 参数： ```text 是可选的要检查的 RDP Cookie 名称，省略时使用默认名称 "msts"。 目前没有合理的理由更改该名称。 ``` 此语句启用基于 RDP Cookie 的会话保持功能。RDP Cookie 包含在已知服务器列表中定位服务器所需的所有信息。因此，当在后端中设置此选项时，请求将被分析；若发现 RDP Cookie，则对其进行解码。若解码结果匹配某个仍处于 UP 状态的已知服务器（或已设置 "option persist"），则连接将被转发至该服务器。 请注意，此配置仅在 TCP 后端中有效，但要使其生效，前端必须等待足够长的时间，以确保 RDP Cookie 已存在于请求缓冲区中。这与使用“rdp-cookie”负载均衡方法的要求相同。因此，强烈建议将所有配置项置于单一的“listen”段中。 此外，必须理解，仅当终端服务器配置为“令牌重定向模式”时，才会发出此 RDP 令牌，这意味着已禁用“IP 地址重定向”选项。 示例： ```text listen tse-farm bind :3389 # wait up to 5s for an RDP cookie in the request tcp-request inspect-delay 5s tcp-request content accept if RDP_COOKIE # apply RDP cookie persistence persist rdp-cookie # if server is unknown, let's balance on the same cookie. # alternatively, "balance leastconn" may be useful too. balance rdp-cookie server srv1 1.1.1.1:3389 server srv2 1.1.1.2:3389 ``` 另请参阅："balance rdp-cookie"、"tcp-request" 以及 "req.rdp_cookie" ACL。 **`quic-initial [ { if | unless } ]`** ```haproxy quic-initial [ { if | unless } ] ``` 对传入的 QUIC Initial 数据包执行一个动作。与 "tcp-request connection" 不同，该动作在任何连接元素实例化之前、SSL 握手启动和完成之前执行，因此在需要拒绝连接尝试时效率更高。 可用于以下上下文：http 可出现在以下段中：defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| no 参数： ```text 定义条件成立时执行的动作，参见下文。 是仅基于第4层的标准 ACL 条件（参见第 7 节）。 但 QUIC initial 规则执行得过早，即使某些第4层样本提取方法没有配置警告， 也可能产生未定义的运行时行为，不过不会导致崩溃。 目前仅应视内部样本和第4层的 "src*"、"dst*" 为受支持的方法。 ``` 此动作在 QUIC 数据包解析的早期阶段执行。因此，仅支持极少量的动作： - accept - dgram-drop - reject - send-retry **`rate-limit sessions `** ```haproxy rate-limit sessions ``` 在前端上设置每秒可接受的新会话数量限制 可用于以下上下文：tcp、http 可出现在以下段中：defaults \| frontend \| listen \| backend yes \| yes \| yes \| no 参数： ```text 参数是整数，表示前端每秒接受的新会话数上限。 ``` 当前端每秒新建会话数达到指定数量时，将停止接受新的连接，直至速率再次低于限制。在此期间，待处理的会话将保留在套接字的连接队列（系统缓冲区）中，HAProxy 甚至不会察觉到会话正在等待。在对高负载服务设置极低限制时，建议使用 "backlog" 关键字增加套接字的连接队列长度。 该功能在阻止基于连接的攻击或对脆弱服务器的服务滥用方面尤为高效。由于会话速率每毫秒测量一次，因此精度极高。此外，限制立即生效，无需任何延迟即可检测到阈值。 示例：将 SMTP 的连接速率限制为每秒最多 10 次 ```haproxy listen smtp mode tcp bind :25 rate-limit sessions 10 server smtp1 127.0.0.1:1025 ``` 请注意：当达到最大速率时，前端的状态不会改变，但如果启用了“socket-stats”选项，其套接字将在统计信息中显示为“WAITING”。 另请参阅：`backlog` 关键字以及 "fe_sess_rate" ACL 条件。 **`redirect location [code ]