【HAProxy 数据面】Runtime API：可热改边界与必须 reload 的配置面
内容提要
本文阐述HAProxy Runtime API与reload的运维分界：Runtime API通过stats socket可热修改服务器权重、状态、stick-table、ACL/Map条目及前端开关，但仅内存生效；结构变更如新增bind、frontend或规则树需修改配置并reload。Master CLI用于多进程管理，强调热改适合运行态调整，结构变更走文件，并需注意持久化纪律。
延伸解读
热改与结构变更的分界
HAProxy 的 Runtime API 只能修改运行态对象，如权重、状态、表条目，而新增 bind、frontend 或规则树等结构变更必须修改配置文件并 reload。这种设计源于其“启动时解析、生命周期内结构固定”的模型，与 Envoy 的 xDS 资源树不同。理解这一分界有助于避免误用 Runtime API 进行结构性调整，从而减少配置与内存状态不一致的风险。
持久化纪律与运维门禁
Runtime 变更默认仅存于内存，reload 后丢失，因此关键变更需回写配置或使用 state 文件。文章建议建立门禁：结构变更需通过 haproxy -c 校验，Runtime 变更需审计并定期回写，长期仅存于内存的状态视为债务。这有助于维护 Git 与线上配置的一致性，避免事故时出现“配置漂移”。
Master CLI 的排障价值
在 reload 窗口期，新旧 worker 可能并存，仅连接默认 worker socket 可能看到不完整状态。Master CLI 可通过 PID 定向发送命令，分别查看 current 与 leaving worker 的状态，避免误判。但 Master CLI 不能用于 retrieve listening sockets，且对 leaving worker 的变更无意义，因此排障时应优先使用只读命令。
Q&A
HAProxy Runtime API 可以热修改哪些配置？
HAProxy Runtime API 通过 stats socket 可以热修改服务器权重、状态（ready/drain/maint）、地址端口，动态增删服务器，管理 stick-table 条目，增删 ACL/Map 条目，以及开关前端和调整 maxconn。这些修改仅作用于内存，reload 后默认丢失。
HAProxy 中哪些变更必须通过修改配置文件并 reload 才能生效？
必须通过配置文件并 reload 的变更包括：新增或删除 bind、frontend、backend 段，修改 ACL/use_backend/http-request 规则树结构，调整全局参数（如 tune.*、线程布局、日志目标），以及健康检查探针定义等与解析期绑定的对象。
HAProxy 的 drain 和 maint 状态有什么区别？
drain 状态表示服务器不再接收新请求，但继续处理存量连接，适合发布前摘流；maint 状态则完全停止流量，适合故障隔离或即将删除服务器。两者在调度和健康检查交互上不同，自动化应使用 state 命令而非仅改权重。
HAProxy 中如何动态添加服务器？需要注意什么？
可以使用 add server 命令在已声明且满足动态算法约束的 backend 上动态添加服务器。但动态添加的服务器在 reload 后不会自动保留，除非配置文件中有对应条目或配合 state 持久化流程。因此，热加只解决当前进程内的扩容，不替代配置文件作为真相源。
HAProxy 的 Master CLI 有什么用途？与 stats socket 有何区别？
Master CLI 用于管理 master-worker 模式下的所有进程，包括当前 worker 和 soft-stop 尚未退出的 leaving worker。它可以通过 @!PID 前缀向指定进程发送命令，并支持 show proc 查看进程列表。与 stats socket 相比，Master CLI 更适合在 reload 窗口期进行多进程可见性核对，但不能用于 retrieve listening sockets。日常自动化仍以 stats socket 为主。
HAProxy 中 stick-table 的热修改有哪些操作？
可以通过 show table 查看表或条目，使用 clear table 按 key、data 条件或 ptr 清除条目。这些操作适用于限流、粘滞、封禁等场景的急救，但不改变规则本身。表类型、容量和 peers 复制等属于配置面，需通过配置文件管理。
HAProxy 中 ACL/Map 的热修改与规则树修改有何区别？
ACL/Map 的热修改（如 add acl、del acl、set map）只改变已声明 pattern 文件或内联表的内容，不改变规则树结构。而新增 ACL 表达式、修改匹配字段或 http-request 动作链结构则属于结构变更，必须修改配置文件并 reload。
HAProxy 中如何实现大表替换的原子性？
可以使用 prepare/commit 命令进行版本化更新：先在新版本中填充条目，再切换命中版本，避免清表到填完的窗口期策略空洞。这应被视为一个事务，而不是多个独立的 add 操作。
