haproxy 通过 lua 脚本实现可编程负载均衡，需编译时启用 use_lua=1 并验证版本（lua 5.3+），在配置中用 lua-load 加载脚本，通过 core.register_action 或 core.register_balancer 注册逻辑，支持上下文感知路由、动态权重、灰度发布等扩展场景。
确认 Lua 环境已就绪
运行 haproxy -vv 查看输出中是否包含 Lua 和对应版本号（要求 Lua 5.3+）。若无，说明当前 HAProxy 未启用 Lua 模块，需重新编译：指定 LUA_INC 和 LUA_LIB 路径，例如：
- make TARGET=linux-glibc USE_LUA=1 LUA_INC=/usr/local/lua/src/ LUA_LIB=/usr/local/lua/src/
- 确保 Lua 解释器本身已安装并可通过 lua -v 验证
在配置中加载并注册 Lua 动作
全局段用 lua-load 引入脚本，再在 frontend 或 backend 中通过 http-request use-service lua.xxx 或 balance lua.xxx 触发逻辑：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 脚本内用 core.register_action("name", {"http-req"}, func) 注册可被调用的动作
- 若用于负载均衡，需用 core.register_balancer("name", func)，函数返回后端服务器名
- 动作可读取客户端 IP、HTTP 头、URL、变量，也可设置事务级变量供后续规则使用
常见扩展场景与写法要点
不必重写全部逻辑，从轻量改造入手更可靠：
- IP 哈希增强版：不只取 client IP，还可结合 User-Agent 或请求路径做复合哈希，提升会话稳定性
- 权重动态调整：在 Lua 中调用 core.tcp("127.0.0.1:8080", ...) 查询 Prometheus 或本地指标接口，按 CPU/延迟实时更新 srv.weight
- 灰度路由：检查请求头中 X-Env: staging，匹配则强制转发到特定 backend，其余走默认策略
- 健康检查补强：在 http-response 钩子中解析后端返回的 JSON，若含 "status":"degraded"，临时降低该节点权重而非直接下线
调试与上线注意事项
Lua 错误不会导致 HAProxy 启动失败，但会使对应动作静默失效，务必验证：
- 启动时加 -d 参数启用调试模式，观察日志中是否有 Lua error 提示
- 脚本中用 core.log(...) 输出关键变量值，日志级别需在 global 段设为 debug
- 避免在 Lua 中执行阻塞操作（如同步 HTTP 请求），推荐用非阻塞 TCP 连接或缓存结果
- 生产环境建议将 Lua 函数封装为独立模块，用 require("mybalancer") 加载，便于复用和测试
