有段时间我接了一个网关类小项目要求所有入口流量都打到HAProxy上同时每个实例的指标要直接对接Prometheus。官方镜像跑起来当然没问题但当我想把2.9分支的某些新特性编译进二进制、把用不到的模块裁掉、最终镜像压到尽可能小时才发现与其在各种脚本里打补丁不如老老实实自己写一个Dockerfile来构建HAProxy镜像。这篇文章就是把那段从零构建、踩坑、上压测的完整过程记录下来内容适用的是需要定制HAProxy编译项、自己做镜像版本管理、又不想被官方镜像牵着走的场景。如果你是第一次手写这类镜像或者只是想知道“官方包一行docker run就行为什么还要折腾”这篇应该能给你一个比较具体的答案。1. 为什么自建HAProxy镜像三个绕不开的动机先要把话说清楚官方镜像真的不是不能用甚至大部分场景下够用。我自己也不是从第一天就开始自建而是在三个需求同时出现之后才决定动手。1.1 官方镜像做得很好但定制能力有限官方维护的haproxy镜像做得相当克制直接拉下来挂配置就能用。它的核心优势是稳定、标签清晰、有人跟踪漏洞修复。但问题也恰恰出在“稳定”上——官方镜像的编译参数一般围绕通用场景prometheus指标支持、Lua脚本支持、某些底层优化开关在默认镜像里不一定都打开。举个例子新版HAProxy编译时可以通过USE_PROMEX1把Prometheus指标收集直接编进二进制这样就不需要另外起exporter进程。官方镜像虽然也带了指标能力但版本和编译选项都比较固定。你要是想基于2.9分支的最新patch版做构建同时把OpenSSL版本也锁定到自己审计过的版本官方镜像就没那么好说话了。1.2 自建的核心收益编译项、体积、依赖可控自建镜像的收益可以拆成三块来理解编译参数可控。哪些功能编译进去、哪些不需要全由make参数决定。业务里只用四层转发就可以把一堆用不到的模块裁掉要用Lua脚本做复杂路由就把USE_LUA打开。体积可控。多阶段构建能把编译工具链全部隔离在构建阶段最终运行镜像通常只有二三十MB。这也是很多人自建的动力之一。依赖可控。基础镜像、动态库、CA证书全都在Dockerfile里显式声明出现CVE也好排查、好升级。说白了官方镜像是“帮你选择”自建镜像是“你自己选择”。前者求稳后者求适配。1.3 动手之前先判断你的场景是否真的需要我见过不少团队兴致勃勃自建HAProxy镜像最后发现业务就是简单的四层转发官方镜像一分钟就能跑通。自建不是目的解决问题才是。需求场景官方镜像表现自建的价值基本HTTP/TCP负载均衡完全够用不大需要锁定版本和依赖做安全审计依赖官方组合高需要Prometheus指标、Lua脚本等特性不一定完整开启高镜像体积有严格要求尚可高需要反复调整编译选项不支持很高我的结论是如果你只是“想练手”或者“觉得自建更高级”建议直接用官方镜像。如果手头确实有编译项、安全、版本锁定的需求那自建才值得投入。2. 基础镜像选型Alpine的轻量vs兼容性取舍基础镜像一旦选错后面编译和运行时都会很痛苦。HAProxy是纯C项目对运行时其实算友好但它依赖OpenSSL、pcre2、zlib这些动态库所以镜像里的libc实现和包管理方式会直接影响编译和运行。2.1 三种常见基础镜像的差异镜像基础体积libc包管理编译目标适合度alpine:3.19很小muslapklinux-musl推荐debian:bookworm-slim中等glibcaptlinux-glibc也推荐ubuntu:jammy-slim较大glibcaptlinux-glibc偏重一般体积排序大体是alpine显著小于debian slimdebian slim又小于ubuntu。如果只是做一个基础镜像相差十几MB影响不大但在大规模部署环境里每一MB都可能影响分发时间和启动速度。2.2 musl不是魔咒但要提前给预期很多人一听到musl就皱眉担心跟业务里常用的C扩展库不兼容。HAProxy项目自己在官方文档里就支持TARGETlinux-muslAlpine上的编译路径非常成熟。真正需要担心的是那些需要外部C模块配合的场景比如某些Lua库或私有插件可能只针对glibc发布预编译包。如果你所在的团队大量使用Debian系基础镜像认证、监控、SDK全都围绕glibc构建那选debian slim反而更顺。我最终选了Alpine理由很简单构建依赖用apk add一行就能装齐体积又小。HAProxy本身对musl的支持没有历史包袱。最终镜像里需要带的runtimes包也很少。2.3 构建阶段和运行阶段的基础镜像版本必须一致这是我自己第一次踩到的小坑。Builder阶段用alpine:3.19跑编译运行时阶段图省事用了alpine:3.20结果运行阶段二进制启动时报错大概率是动态库里某个符号版本对不上。后来我把两个阶段的base tag统一锁死为alpine:3.19问题就消失了。所以Dockerfile里基础镜像的tag不要图省事写latest编译和运行阶段尽量保持一致。这样能避免很多“我明明编译成功了进容器却跑不起来”的诡异问题。3. Dockerfile核心设计多阶段构建与编译参数逐项拆解这一节给核心示例和完整解释。多阶段构建是这个Dockerfile的地基它能同时解决“编译需要完整工具链”和“运行镜像需要尽量干净”的矛盾。3.1 一个可用的完整Dockerfile# syntaxdocker/dockerfile:1.7 ARG HAPROXY_VERSION2.9.7 # ---------- 阶段一编译 ---------- FROM alpine:3.19 AS builder ARG HAPROXY_VERSION ARG BUILD_NPROC4 RUN apk add --no-cache \ build-base \ curl \ tar \ linux-headers \ openssl-dev \ pcre2-dev \ zlib-dev WORKDIR /build RUN curl -fsSL https://www.haproxy.org/download/2.9/src/haproxy-${HAPROXY_VERSION}.tar.gz -o haproxy.tar.gz \ tar -xzf haproxy.tar.gz \ rm haproxy.tar.gz WORKDIR /build/haproxy-${HAPROXY_VERSION} RUN make -j${BUILD_NPROC} \ TARGETlinux-musl \ USE_OPENSSL1 \ USE_PCRE21 \ USE_PCRE2_JIT1 \ USE_ZLIB1 \ USE_PROMEX1 \ USE_CPU_AFFINITY1 \ USE_TFO1 \ USE_GETADDRINFO1 \ make install-bin # ---------- 阶段二精简运行 ---------- FROM alpine:3.19 ARG HAPROXY_VERSION RUN apk add --no-cache \ libgcc \ openssl \ zlib \ pcre2 \ ca-certificates \ addgroup -S haproxy \ adduser -S -G haproxy haproxy COPY --frombuilder /usr/local/sbin/haproxy /usr/local/sbin/haproxy RUN mkdir -p /usr/local/etc/haproxy /var/lib/haproxy \ chown -R haproxy:haproxy /var/lib/haproxy # 默认保留root启动haproxy.cfg里通过 user/group 指令降权 # 这样可以绑定低端口又不会让worker进程长期跑在root下 ENTRYPOINT [/usr/local/sbin/haproxy] CMD [-f, /usr/local/etc/haproxy/haproxy.cfg]这段不是不可变化的真理而是一个可跑的起点。你要用2.6分支就把版本和下载路径改成2.6要用多核编译把BUILD_NPROC调大不需要prometheus就把USE_PROMEX1从编译参数里拿掉。3.2 编译参数逐个说清楚别只抄参数编译参数作用什么时候可以关掉USE_OPENSSL1支持HTTPS终结、TLS双向认证纯四层转发不需要USE_PCRE21USE_PCRE2_JIT1支持正则表达式JIT提升正则匹配性能配置里完全不用正则可关USE_ZLIB1HTTP响应压缩支持后端自己压缩或不需要压缩时USE_PROMEX1直接把Prometheus指标端点编进HAProxy已有独立指标采集方案时USE_CPU_AFFINITY1线程绑定CPU核降低调度抖动容器CPU配额不固定时可关USE_TFO1TCP Fast Open降低短连接握手耗时网络设备不支持TFO时USE_GETADDRINFO1使用getaddrinfo做DNS解析极简环境可关这里特别注意USE_LUA。HAProxy的Lua支持很有用但编入Lua需要给编译器指明头文件和库文件的准确路径。在Alpine这种把Lua按版本拆包的发行版里直接USE_LUA1很容易找不到lua.h。常见做法是安装lua5.4-dev然后用LUA_INC和LUA_LIB把路径指过去RUN make -j4 TARGETlinux-musl USE_LUA1 \ LUA_INC/usr/include/lua5.4 \ LUA_LIB/usr/lib/liblua5.4.so \ ...路径以你实际apk安装的Lua版本为准先find /usr -name liblua*.so看清楚再写比硬抄路径靠谱。3.3 运行阶段为什么不能只COPY一个二进制编译完成的haproxy几乎都是动态链接不是静态二进制。你拿ldd /usr/local/sbin/haproxy看一眼就会看到它依赖openssl的so、pcre2的so、zlib的so。所以运行阶段必须把这些运行库装进镜像否则启动时会报“shared library not found”。这也是多阶段构建的另一个价值构建阶段里那几百MB的gcc、make、头文件全都不进最终镜像运行镜像只保留二进制本身和运行库。二进制体积一般就几MB最终镜像整体压到20-30MB是很正常的。如果你要严格锁定供应链建议在下载源码之后加一层校验。比如先在官网记录sha256然后在Dockerfile里用sha256sum -c验证下载文件的完整性。这一步对生产环境很有意义镜像一旦构建出来就会被反复分发源头可信是最基本的一环。4. 容器里的运行时PID 1、日志、reload与健康检查镜像构建只是开始HAProxy在容器里跑得好不好取决于你怎么处理进程、日志和配置更新方式。4.1 让HAProxy自己当前台进程别包一层shellHAProxy默认行为是在前台运行。这意味着Dockerfile里的ENTRYPOINT直接指向haproxy二进制是最合理的做法不需要包一层sh -c haproxy ...。直接exec的好处是信号能准确传给HAProxy进程docker stop发来的SIGTERM能被它捕获从而优雅关闭。下面这个写法就值得避免ENTRYPOINT [sh, -c, /usr/local/sbin/haproxy -f /etc/haproxy/haproxy.cfg]除非脚本里必须做模板替换否则永远让容器里1号进程是真正的haproxy。4.2 日志输出到stdout容器平台才收得到默认情况下HAProxy会把日志写向系统日志设施这在容器里会变得很难处理。更好的做法是在global段里把日志直接指到stdoutglobal log stdout format raw local0 maxconn 50000 user haproxy group haproxy然后在defaults段打开全局日志defaults log global option httplog这样docker logs就能直接看到访问日志和错误日志不需要在容器里额外跑rsyslog或者syslog-ng。尤其是接入日志采集平台时stdout是成本最低的出口。4.3 容器里的配置更新常规手段是滚动替换不是信号reloadHAProxy确实支持优雅重载经典做法是启动新进程并让新老进程共享监听socket完成流量切换。但在容器编排环境里我越来越倾向于不依赖这种机制后端节点调整可以走runtime API动态增删server全程不重载配置。监听端口、路由规则这类大改动直接构建新容器滚动替换。反复在容器内部做复杂reload会让问题定位变得困难。如果你确实需要在容器里reloadHAProxy的master-worker模式可以配合信号实现但这不是容器场景的主流玩法。主流玩法是把配置更新动作交给上层编排系统保持镜像和容器本身不可变。4.4 HEALTHCHECK验证进程活着就够了别让它承担业务探活Docker的HEALTHCHECK建议检查HAProxy自身是否正常工作不需要等后端全部健康。最轻量的探活就是TCP connect到监听端口HEALTHCHECK --interval10s --timeout2s --start-period10s --retries3 \ CMD nc -z 127.0.0.1 8080如果你的监听端口是80就把8080换成80。后端服务的健康状态交给HAProxy自己的httpchk去维护不需要在容器层面重复判断。5. 配置与目录设计挂载式管理haproxy.cfgHAProxy镜像里最难“标准化”的部分其实是配置。二进制可以通过编译参数定制配置则是每个环境一套逻辑。5.1 镜像内置基础配置运行时挂载覆盖我的做法是镜像里内置一份能启动的最小配置文件保证裸跑也能起来不至于一个docker run就报“配置文件不存在”。真实业务的配置则通过volume挂载进去并且挂载成只读docker run -d \ --name haproxy-demo \ -p 8080:8080 \ -p 8404:8404 \ -v $(pwd)/conf/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \ my/haproxy:2.9.7只读挂载可以防止运行期意外修改配置也符合容器不可变的原则。5.2 推荐的目录结构和最小配置镜像内的固定目录大致这样规划/usr/local/etc/haproxy/ ├── haproxy.cfg └── errors/ ├── 400.http ├── 403.http ├── 503.http └── 504.httperrors目录放自定义错误页需要时挂载覆盖即可。下面是一份常见配置参考global log stdout format raw local0 maxconn 50000 user haproxy group haproxy defaults log global mode http option httplog option dontlognull option http-server-close timeout connect 5s timeout client 15s timeout server 15s frontend http-in bind *:8080 default_backend web-servers backend web-servers balance roundrobin option httpchk GET /healthz server web1 10.0.0.11:8080 check inter 3s fall 2 rise 3 server web2 10.0.0.12:8080 check inter 3s fall 2 rise 3 listen stats bind *:8404 stats enable stats uri /stats stats refresh 10s这里有几个容易忽视的点option http-server-close适合短连接较多的HTTP场景能释放半连接。check inter 3s fall 2 rise 3表示每3秒一次健康检查连续2次失败摘除节点连续3次成功恢复节点。按后端实际情况调。stats页面一定要加访问控制否则就是管理接口裸奔。5.3 多环境配置用模板和环境变量生成同一套镜像要部署到测试、预发、生产配置不可能完全一样。常见做法是准备一份模板文件配合envsubst在启动时生成最终配置envsubst /usr/local/etc/haproxy/haproxy.cfg.tpl /usr/local/etc/haproxy/haproxy.cfg exec /usr/local/sbin/haproxy -f /usr/local/etc/haproxy/haproxy.cfg这种脚本写法注意两点一是生成配置前保留备份二是启动前用haproxy -c验证语法错了就不要用坏配置启动服务。把这两步写进entrypoint脚本能帮你省掉大量低级事故。6. 实测记录构建、启动与压测踩坑光看Dockerfile还不行真正跑一遍才能暴露问题。下面是我实际构建和启动过程中踩过的几类坑。6.1 docker build阶段最常见的四类报错报错现象根因处理方法make: command not foundbuilder阶段没装build-base安装build-base它会把gcc、make、libc-dev都带进来openssl/ssl.h: No such file or directory缺少OpenSSL头文件安装openssl-dev而不是只装opensslpcre2.h相关报错缺少pcre2开发包安装pcre2-dev编译时提示unknown targetTARGET填写错误确认用linux-musl不要用linux-generic这种模糊目标编译参数如果设错HAProxy的Makefile一般会给出比较明确的提示照着提示补依赖就好。另外如果机器核数多-j太高有可能遇到内存不足构建卡死或OOM这时把BUILD_NPROC调小重试即可。6.2 容器启动首分钟最容易翻车的三件事第一件是端口绑定失败。如果用的是root之外的用户启动进程又想监听80这种低端口通常会被拒绝。要么用root启动然后在配置文件里降权要么给二进制加cap_net_bind_service能力要么干脆把容器内监听端口换到高位。我示例里的bind *:8080就是为了让你绕开低端口问题。第二件是配置文件里写的目录不存在。比如runtime socket要写到/var/lib/haproxy但镜像里没建这个目录启动直接失败。所以Dockerfile里提前mkdir -p并设好属主是一个容易被忽略的关键步骤。第三件是配置文件语法正确性。在启动容器前养成习惯先跑一下docker run --rm -v $(pwd)/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \ my/haproxy:2.9.7 -c -f /usr/local/etc/haproxy/haproxy.cfg-c参数只检查配置不启动进程能过滤掉绝大多数低级错误。6.3 压测怎么读结果怎么看日志镜像跑起来后先看启动日志和访问日志docker logs -f haproxy-demo再拿压测工具打一下流量wrk -t4 -c200 -d30s http://127.0.0.1:8080/压测过程里重点关注三类现象后端节点健康状态。打开http://127.0.0.1:8404/stats看后端server是UP还是DOWN。如果一直DOWN多半是httpchk探活路径不对或者后端端口没开。响应码分布。如果大量503基本是后端不可用大量504是后端响应太慢导致超时。连接数和并发数。回到stats页面看CurrConns如果连接数卡在maxconn附近说明需要调大全局maxconn同时注意宿主机的文件描述符限制。压测数据本身会受到机器、网络、后端应用影响不用迷信绝对数值。真正有价值的是横向比较同一份配置调大timeout、切换balance算法、打开连接复用之后QPS和延迟曲线有没有改善。7. 最后的安全加固非root与能力裁剪镜像能跑起来之后就该考虑怎么让它跑得更稳、更安全了。7.1 三种权限模型按需选择模型方式优点缺点root启动降权root进程监听低端口config里user haproxy降权简单兼容低端口1号进程还是root攻击面较大非root高位端口Dockerfile里USER haproxy监听8080这类端口符合容器最小权限外部发布时要映射端口非rootcapability二进制加cap_net_bind_serviceUSER haproxy监听80兼顾低端口和非root需要额外安装libcap构建稍复杂我个人最常用第二种。容器内部的端口号本身不影响外部访问-p 80:8080就能把宿主的80映射到容器内的8080。这样镜像安全性更高代码也更简单。7.2 只读根文件系统和小工具链运行阶段可以尽量少装东西。示例里我装了curl是为了方便调试如果你依赖镜像极简完全可以把curl换成wget或者干脆只保留核心二进制和busybox自带工具。更进一步docker run时可以加--read-only参数挂载只读根文件系统只给必要的目录开写入权限docker run -d \ --name haproxy-demo \ --read-only \ --tmpfs /var/lib/haproxy:rw \ --tmpfs /run:rw \ -p 8080:8080 \ ...这样即使容器被攻破能写入的位置也被限制住了。最后建议在CI流水线里加镜像扫描比如trivy这种SAST工具把高危CVE在镜像构建阶段就拦下来。别等到部署上线后再被安全团队喊回去改那成本就不一样了。关于自建HAProxy镜像我的总原则很简单能标准化成Dockerfile里的层就别在运行时用脚本补救能在构建阶段验证的就别等启动阶段报错。编译参数、基础镜像、运行时权限这三块一旦定好后续维护成本就很低了。我现在习惯每次改完配置先跑一遍haproxy -c再考虑构建和发布这个习惯帮我挡掉了不少夜间紧急事故。 
长河君 · 2026/10/22 9:55:09 · 阅读 1.2k 自建HAProxy Docker镜像：从编译参数到多阶段构建实践
有段时间我接了一个网关类小项目要求所有入口流量都打到HAProxy上同时每个实例的指标要直接对接Prometheus。官方镜像跑起来当然没问题但当我想把2.9分支的某些新特性编译进二进制、把用不到的模块裁掉、最终镜像压到尽可能小时才发现与其在各种脚本里打补丁不如老老实实自己写一个Dockerfile来构建HAProxy镜像。这篇文章就是把那段从零构建、踩坑、上压测的完整过程记录下来内容适用的是需要定制HAProxy编译项、自己做镜像版本管理、又不想被官方镜像牵着走的场景。如果你是第一次手写这类镜像或者只是想知道“官方包一行docker run就行为什么还要折腾”这篇应该能给你一个比较具体的答案。1. 为什么自建HAProxy镜像三个绕不开的动机先要把话说清楚官方镜像真的不是不能用甚至大部分场景下够用。我自己也不是从第一天就开始自建而是在三个需求同时出现之后才决定动手。1.1 官方镜像做得很好但定制能力有限官方维护的haproxy镜像做得相当克制直接拉下来挂配置就能用。它的核心优势是稳定、标签清晰、有人跟踪漏洞修复。但问题也恰恰出在“稳定”上——官方镜像的编译参数一般围绕通用场景prometheus指标支持、Lua脚本支持、某些底层优化开关在默认镜像里不一定都打开。举个例子新版HAProxy编译时可以通过USE_PROMEX1把Prometheus指标收集直接编进二进制这样就不需要另外起exporter进程。官方镜像虽然也带了指标能力但版本和编译选项都比较固定。你要是想基于2.9分支的最新patch版做构建同时把OpenSSL版本也锁定到自己审计过的版本官方镜像就没那么好说话了。1.2 自建的核心收益编译项、体积、依赖可控自建镜像的收益可以拆成三块来理解编译参数可控。哪些功能编译进去、哪些不需要全由make参数决定。业务里只用四层转发就可以把一堆用不到的模块裁掉要用Lua脚本做复杂路由就把USE_LUA打开。体积可控。多阶段构建能把编译工具链全部隔离在构建阶段最终运行镜像通常只有二三十MB。这也是很多人自建的动力之一。依赖可控。基础镜像、动态库、CA证书全都在Dockerfile里显式声明出现CVE也好排查、好升级。说白了官方镜像是“帮你选择”自建镜像是“你自己选择”。前者求稳后者求适配。1.3 动手之前先判断你的场景是否真的需要我见过不少团队兴致勃勃自建HAProxy镜像最后发现业务就是简单的四层转发官方镜像一分钟就能跑通。自建不是目的解决问题才是。需求场景官方镜像表现自建的价值基本HTTP/TCP负载均衡完全够用不大需要锁定版本和依赖做安全审计依赖官方组合高需要Prometheus指标、Lua脚本等特性不一定完整开启高镜像体积有严格要求尚可高需要反复调整编译选项不支持很高我的结论是如果你只是“想练手”或者“觉得自建更高级”建议直接用官方镜像。如果手头确实有编译项、安全、版本锁定的需求那自建才值得投入。2. 基础镜像选型Alpine的轻量vs兼容性取舍基础镜像一旦选错后面编译和运行时都会很痛苦。HAProxy是纯C项目对运行时其实算友好但它依赖OpenSSL、pcre2、zlib这些动态库所以镜像里的libc实现和包管理方式会直接影响编译和运行。2.1 三种常见基础镜像的差异镜像基础体积libc包管理编译目标适合度alpine:3.19很小muslapklinux-musl推荐debian:bookworm-slim中等glibcaptlinux-glibc也推荐ubuntu:jammy-slim较大glibcaptlinux-glibc偏重一般体积排序大体是alpine显著小于debian slimdebian slim又小于ubuntu。如果只是做一个基础镜像相差十几MB影响不大但在大规模部署环境里每一MB都可能影响分发时间和启动速度。2.2 musl不是魔咒但要提前给预期很多人一听到musl就皱眉担心跟业务里常用的C扩展库不兼容。HAProxy项目自己在官方文档里就支持TARGETlinux-muslAlpine上的编译路径非常成熟。真正需要担心的是那些需要外部C模块配合的场景比如某些Lua库或私有插件可能只针对glibc发布预编译包。如果你所在的团队大量使用Debian系基础镜像认证、监控、SDK全都围绕glibc构建那选debian slim反而更顺。我最终选了Alpine理由很简单构建依赖用apk add一行就能装齐体积又小。HAProxy本身对musl的支持没有历史包袱。最终镜像里需要带的runtimes包也很少。2.3 构建阶段和运行阶段的基础镜像版本必须一致这是我自己第一次踩到的小坑。Builder阶段用alpine:3.19跑编译运行时阶段图省事用了alpine:3.20结果运行阶段二进制启动时报错大概率是动态库里某个符号版本对不上。后来我把两个阶段的base tag统一锁死为alpine:3.19问题就消失了。所以Dockerfile里基础镜像的tag不要图省事写latest编译和运行阶段尽量保持一致。这样能避免很多“我明明编译成功了进容器却跑不起来”的诡异问题。3. Dockerfile核心设计多阶段构建与编译参数逐项拆解这一节给核心示例和完整解释。多阶段构建是这个Dockerfile的地基它能同时解决“编译需要完整工具链”和“运行镜像需要尽量干净”的矛盾。3.1 一个可用的完整Dockerfile# syntaxdocker/dockerfile:1.7 ARG HAPROXY_VERSION2.9.7 # ---------- 阶段一编译 ---------- FROM alpine:3.19 AS builder ARG HAPROXY_VERSION ARG BUILD_NPROC4 RUN apk add --no-cache \ build-base \ curl \ tar \ linux-headers \ openssl-dev \ pcre2-dev \ zlib-dev WORKDIR /build RUN curl -fsSL https://www.haproxy.org/download/2.9/src/haproxy-${HAPROXY_VERSION}.tar.gz -o haproxy.tar.gz \ tar -xzf haproxy.tar.gz \ rm haproxy.tar.gz WORKDIR /build/haproxy-${HAPROXY_VERSION} RUN make -j${BUILD_NPROC} \ TARGETlinux-musl \ USE_OPENSSL1 \ USE_PCRE21 \ USE_PCRE2_JIT1 \ USE_ZLIB1 \ USE_PROMEX1 \ USE_CPU_AFFINITY1 \ USE_TFO1 \ USE_GETADDRINFO1 \ make install-bin # ---------- 阶段二精简运行 ---------- FROM alpine:3.19 ARG HAPROXY_VERSION RUN apk add --no-cache \ libgcc \ openssl \ zlib \ pcre2 \ ca-certificates \ addgroup -S haproxy \ adduser -S -G haproxy haproxy COPY --frombuilder /usr/local/sbin/haproxy /usr/local/sbin/haproxy RUN mkdir -p /usr/local/etc/haproxy /var/lib/haproxy \ chown -R haproxy:haproxy /var/lib/haproxy # 默认保留root启动haproxy.cfg里通过 user/group 指令降权 # 这样可以绑定低端口又不会让worker进程长期跑在root下 ENTRYPOINT [/usr/local/sbin/haproxy] CMD [-f, /usr/local/etc/haproxy/haproxy.cfg]这段不是不可变化的真理而是一个可跑的起点。你要用2.6分支就把版本和下载路径改成2.6要用多核编译把BUILD_NPROC调大不需要prometheus就把USE_PROMEX1从编译参数里拿掉。3.2 编译参数逐个说清楚别只抄参数编译参数作用什么时候可以关掉USE_OPENSSL1支持HTTPS终结、TLS双向认证纯四层转发不需要USE_PCRE21USE_PCRE2_JIT1支持正则表达式JIT提升正则匹配性能配置里完全不用正则可关USE_ZLIB1HTTP响应压缩支持后端自己压缩或不需要压缩时USE_PROMEX1直接把Prometheus指标端点编进HAProxy已有独立指标采集方案时USE_CPU_AFFINITY1线程绑定CPU核降低调度抖动容器CPU配额不固定时可关USE_TFO1TCP Fast Open降低短连接握手耗时网络设备不支持TFO时USE_GETADDRINFO1使用getaddrinfo做DNS解析极简环境可关这里特别注意USE_LUA。HAProxy的Lua支持很有用但编入Lua需要给编译器指明头文件和库文件的准确路径。在Alpine这种把Lua按版本拆包的发行版里直接USE_LUA1很容易找不到lua.h。常见做法是安装lua5.4-dev然后用LUA_INC和LUA_LIB把路径指过去RUN make -j4 TARGETlinux-musl USE_LUA1 \ LUA_INC/usr/include/lua5.4 \ LUA_LIB/usr/lib/liblua5.4.so \ ...路径以你实际apk安装的Lua版本为准先find /usr -name liblua*.so看清楚再写比硬抄路径靠谱。3.3 运行阶段为什么不能只COPY一个二进制编译完成的haproxy几乎都是动态链接不是静态二进制。你拿ldd /usr/local/sbin/haproxy看一眼就会看到它依赖openssl的so、pcre2的so、zlib的so。所以运行阶段必须把这些运行库装进镜像否则启动时会报“shared library not found”。这也是多阶段构建的另一个价值构建阶段里那几百MB的gcc、make、头文件全都不进最终镜像运行镜像只保留二进制本身和运行库。二进制体积一般就几MB最终镜像整体压到20-30MB是很正常的。如果你要严格锁定供应链建议在下载源码之后加一层校验。比如先在官网记录sha256然后在Dockerfile里用sha256sum -c验证下载文件的完整性。这一步对生产环境很有意义镜像一旦构建出来就会被反复分发源头可信是最基本的一环。4. 容器里的运行时PID 1、日志、reload与健康检查镜像构建只是开始HAProxy在容器里跑得好不好取决于你怎么处理进程、日志和配置更新方式。4.1 让HAProxy自己当前台进程别包一层shellHAProxy默认行为是在前台运行。这意味着Dockerfile里的ENTRYPOINT直接指向haproxy二进制是最合理的做法不需要包一层sh -c haproxy ...。直接exec的好处是信号能准确传给HAProxy进程docker stop发来的SIGTERM能被它捕获从而优雅关闭。下面这个写法就值得避免ENTRYPOINT [sh, -c, /usr/local/sbin/haproxy -f /etc/haproxy/haproxy.cfg]除非脚本里必须做模板替换否则永远让容器里1号进程是真正的haproxy。4.2 日志输出到stdout容器平台才收得到默认情况下HAProxy会把日志写向系统日志设施这在容器里会变得很难处理。更好的做法是在global段里把日志直接指到stdoutglobal log stdout format raw local0 maxconn 50000 user haproxy group haproxy然后在defaults段打开全局日志defaults log global option httplog这样docker logs就能直接看到访问日志和错误日志不需要在容器里额外跑rsyslog或者syslog-ng。尤其是接入日志采集平台时stdout是成本最低的出口。4.3 容器里的配置更新常规手段是滚动替换不是信号reloadHAProxy确实支持优雅重载经典做法是启动新进程并让新老进程共享监听socket完成流量切换。但在容器编排环境里我越来越倾向于不依赖这种机制后端节点调整可以走runtime API动态增删server全程不重载配置。监听端口、路由规则这类大改动直接构建新容器滚动替换。反复在容器内部做复杂reload会让问题定位变得困难。如果你确实需要在容器里reloadHAProxy的master-worker模式可以配合信号实现但这不是容器场景的主流玩法。主流玩法是把配置更新动作交给上层编排系统保持镜像和容器本身不可变。4.4 HEALTHCHECK验证进程活着就够了别让它承担业务探活Docker的HEALTHCHECK建议检查HAProxy自身是否正常工作不需要等后端全部健康。最轻量的探活就是TCP connect到监听端口HEALTHCHECK --interval10s --timeout2s --start-period10s --retries3 \ CMD nc -z 127.0.0.1 8080如果你的监听端口是80就把8080换成80。后端服务的健康状态交给HAProxy自己的httpchk去维护不需要在容器层面重复判断。5. 配置与目录设计挂载式管理haproxy.cfgHAProxy镜像里最难“标准化”的部分其实是配置。二进制可以通过编译参数定制配置则是每个环境一套逻辑。5.1 镜像内置基础配置运行时挂载覆盖我的做法是镜像里内置一份能启动的最小配置文件保证裸跑也能起来不至于一个docker run就报“配置文件不存在”。真实业务的配置则通过volume挂载进去并且挂载成只读docker run -d \ --name haproxy-demo \ -p 8080:8080 \ -p 8404:8404 \ -v $(pwd)/conf/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \ my/haproxy:2.9.7只读挂载可以防止运行期意外修改配置也符合容器不可变的原则。5.2 推荐的目录结构和最小配置镜像内的固定目录大致这样规划/usr/local/etc/haproxy/ ├── haproxy.cfg └── errors/ ├── 400.http ├── 403.http ├── 503.http └── 504.httperrors目录放自定义错误页需要时挂载覆盖即可。下面是一份常见配置参考global log stdout format raw local0 maxconn 50000 user haproxy group haproxy defaults log global mode http option httplog option dontlognull option http-server-close timeout connect 5s timeout client 15s timeout server 15s frontend http-in bind *:8080 default_backend web-servers backend web-servers balance roundrobin option httpchk GET /healthz server web1 10.0.0.11:8080 check inter 3s fall 2 rise 3 server web2 10.0.0.12:8080 check inter 3s fall 2 rise 3 listen stats bind *:8404 stats enable stats uri /stats stats refresh 10s这里有几个容易忽视的点option http-server-close适合短连接较多的HTTP场景能释放半连接。check inter 3s fall 2 rise 3表示每3秒一次健康检查连续2次失败摘除节点连续3次成功恢复节点。按后端实际情况调。stats页面一定要加访问控制否则就是管理接口裸奔。5.3 多环境配置用模板和环境变量生成同一套镜像要部署到测试、预发、生产配置不可能完全一样。常见做法是准备一份模板文件配合envsubst在启动时生成最终配置envsubst /usr/local/etc/haproxy/haproxy.cfg.tpl /usr/local/etc/haproxy/haproxy.cfg exec /usr/local/sbin/haproxy -f /usr/local/etc/haproxy/haproxy.cfg这种脚本写法注意两点一是生成配置前保留备份二是启动前用haproxy -c验证语法错了就不要用坏配置启动服务。把这两步写进entrypoint脚本能帮你省掉大量低级事故。6. 实测记录构建、启动与压测踩坑光看Dockerfile还不行真正跑一遍才能暴露问题。下面是我实际构建和启动过程中踩过的几类坑。6.1 docker build阶段最常见的四类报错报错现象根因处理方法make: command not foundbuilder阶段没装build-base安装build-base它会把gcc、make、libc-dev都带进来openssl/ssl.h: No such file or directory缺少OpenSSL头文件安装openssl-dev而不是只装opensslpcre2.h相关报错缺少pcre2开发包安装pcre2-dev编译时提示unknown targetTARGET填写错误确认用linux-musl不要用linux-generic这种模糊目标编译参数如果设错HAProxy的Makefile一般会给出比较明确的提示照着提示补依赖就好。另外如果机器核数多-j太高有可能遇到内存不足构建卡死或OOM这时把BUILD_NPROC调小重试即可。6.2 容器启动首分钟最容易翻车的三件事第一件是端口绑定失败。如果用的是root之外的用户启动进程又想监听80这种低端口通常会被拒绝。要么用root启动然后在配置文件里降权要么给二进制加cap_net_bind_service能力要么干脆把容器内监听端口换到高位。我示例里的bind *:8080就是为了让你绕开低端口问题。第二件是配置文件里写的目录不存在。比如runtime socket要写到/var/lib/haproxy但镜像里没建这个目录启动直接失败。所以Dockerfile里提前mkdir -p并设好属主是一个容易被忽略的关键步骤。第三件是配置文件语法正确性。在启动容器前养成习惯先跑一下docker run --rm -v $(pwd)/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \ my/haproxy:2.9.7 -c -f /usr/local/etc/haproxy/haproxy.cfg-c参数只检查配置不启动进程能过滤掉绝大多数低级错误。6.3 压测怎么读结果怎么看日志镜像跑起来后先看启动日志和访问日志docker logs -f haproxy-demo再拿压测工具打一下流量wrk -t4 -c200 -d30s http://127.0.0.1:8080/压测过程里重点关注三类现象后端节点健康状态。打开http://127.0.0.1:8404/stats看后端server是UP还是DOWN。如果一直DOWN多半是httpchk探活路径不对或者后端端口没开。响应码分布。如果大量503基本是后端不可用大量504是后端响应太慢导致超时。连接数和并发数。回到stats页面看CurrConns如果连接数卡在maxconn附近说明需要调大全局maxconn同时注意宿主机的文件描述符限制。压测数据本身会受到机器、网络、后端应用影响不用迷信绝对数值。真正有价值的是横向比较同一份配置调大timeout、切换balance算法、打开连接复用之后QPS和延迟曲线有没有改善。7. 最后的安全加固非root与能力裁剪镜像能跑起来之后就该考虑怎么让它跑得更稳、更安全了。7.1 三种权限模型按需选择模型方式优点缺点root启动降权root进程监听低端口config里user haproxy降权简单兼容低端口1号进程还是root攻击面较大非root高位端口Dockerfile里USER haproxy监听8080这类端口符合容器最小权限外部发布时要映射端口非rootcapability二进制加cap_net_bind_serviceUSER haproxy监听80兼顾低端口和非root需要额外安装libcap构建稍复杂我个人最常用第二种。容器内部的端口号本身不影响外部访问-p 80:8080就能把宿主的80映射到容器内的8080。这样镜像安全性更高代码也更简单。7.2 只读根文件系统和小工具链运行阶段可以尽量少装东西。示例里我装了curl是为了方便调试如果你依赖镜像极简完全可以把curl换成wget或者干脆只保留核心二进制和busybox自带工具。更进一步docker run时可以加--read-only参数挂载只读根文件系统只给必要的目录开写入权限docker run -d \ --name haproxy-demo \ --read-only \ --tmpfs /var/lib/haproxy:rw \ --tmpfs /run:rw \ -p 8080:8080 \ ...这样即使容器被攻破能写入的位置也被限制住了。最后建议在CI流水线里加镜像扫描比如trivy这种SAST工具把高危CVE在镜像构建阶段就拦下来。别等到部署上线后再被安全团队喊回去改那成本就不一样了。关于自建HAProxy镜像我的总原则很简单能标准化成Dockerfile里的层就别在运行时用脚本补救能在构建阶段验证的就别等启动阶段报错。编译参数、基础镜像、运行时权限这三块一旦定好后续维护成本就很低了。我现在习惯每次改完配置先跑一遍haproxy -c再考虑构建和发布这个习惯帮我挡掉了不少夜间紧急事故。