HAProxy Docker镜像文档

重要说明

此镜像为官方haproxy镜像的amd64架构专用仓库。有关更多信息，请参见官方镜像文档中的“非amd64架构？”和官方镜像FAQ中的“Git中的镜像源已更改，现在该怎么办？”。

快速参考

维护者

Docker社区

获取帮助

Docker社区Slack、Server Fault、Unix & Linux或Stack Overflow

支持的标签及对应的Dockerfile链接

• 3.3-dev9, 3.3-dev, 3.3-dev9-trixie, 3.3-dev-trixie
• 3.3-dev9-alpine, 3.3-dev-alpine, 3.3-dev9-alpine3.22, 3.3-dev-alpine3.22
• 3.2.6, 3.2, latest, lts, 3.2.6-trixie, 3.2-trixie, trixie, lts-trixie
• 3.2.6-alpine, 3.2-alpine, alpine, lts-alpine, 3.2.6-alpine3.22, 3.2-alpine3.22, alpine3.22, lts-alpine3.22
• 3.1.9, 3.1, 3.1.9-trixie, 3.1-trixie
• 3.1.9-alpine, 3.1-alpine, 3.1.9-alpine3.22, 3.1-alpine3.22
• 3.0.12, 3.0, 3.0.12-trixie, 3.0-trixie
• 3.0.12-alpine, 3.0-alpine, 3.0.12-alpine3.22, 3.0-alpine3.22
• 2.8.16, 2.8, 2.8.16-trixie, 2.8-trixie
• 2.8.16-alpine, 2.8-alpine, 2.8.16-alpine3.22, 2.8-alpine3.22
• 2.6.23, 2.6, 2.6.23-trixie, 2.6-trixie
• 2.6.23-alpine, 2.6-alpine, 2.6.23-alpine3.22, 2.6-alpine3.22
• 2.4.30, 2.4, 2.4.30-trixie, 2.4-trixie
• 2.4.30-alpine, 2.4-alpine, 2.4.30-alpine3.22, 2.4-alpine3.22

快速参考（续）

问题反馈

[***]

支持的架构

(更多信息)
amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x

镜像制品详情

repo-info仓库的repos/haproxy/目录 (历史记录)
（包含镜像元数据、传输大小等）

镜像更新

official-images仓库的library/haproxy标签
official-images仓库的library/haproxy文件 (历史记录)

此描述的来源

docs仓库的haproxy/目录 (历史记录)

什么是HAProxy？

HAProxy是一款免费开源的高可用性解决方案，通过在多台服务器间分发请求，为基于TCP和HTTP的应用提供负载均衡和代理服务。它采用C语言编写，以快速高效（在处理器和内存使用方面）而闻名。

***.org/wiki/HAProxy

!logo

如何使用此镜像

由于HAProxy的用户配置需求各不相同，此镜像不包含默认配置。

有关配置HAProxy的详细信息，请参考上游官方文档。也可查看上游的examples/目录获取示例。

创建Dockerfile

FROM amd64/haproxy:2.3
COPY haproxy.cfg /usr/local/etc/haproxy/haproxy.cfg

构建容器

$ docker build -t my-haproxy .

测试配置文件

$ docker run -it --rm --name haproxy-syntax-check my-haproxy haproxy -c -f /usr/local/etc/haproxy/haproxy.cfg

运行容器

$ docker run -d --name my-running-haproxy --sysctl net.ipv4.ip_unprivileged_port_start=0 my-haproxy

需要内核版本在4.11或更高才能使用--sysctl net.ipv4.ip_unprivileged_port_start=0。如需将HAProxy监听的端口暴露到主机，需使用-p选项，例如-p 8080:80将容器的80端口映射到主机的8080端口。确保使用的端口未被占用。

注意：2.4+版本的容器默认以USER haproxy身份运行（因此需要上述--sysctl参数），而旧版本为保持兼容性仍默认使用root；如要在旧版本中以非root身份运行，可使用--user haproxy（或其他UID）。

通过绑定挂载直接运行

$ docker run -d --name my-running-haproxy -v /path/to/etc/haproxy:/usr/local/etc/haproxy:ro --sysctl net.ipv4.ip_unprivileged_port_start=0 amd64/haproxy:2.3

注意，主机的/path/to/etc/haproxy目录需包含名为haproxy.cfg的文件。如果配置文件引用了该目录下的其他文件（如400.http、404.http等模板文件），需确保这些文件也存在。不过，许多最小化配置不需要额外文件。

重新加载配置

如果使用绑定挂载方式且已修改haproxy.cfg，可通过向容器发送SIGHUP信号实现HAProxy的平滑重载：

$ docker kill -s HUP my-running-haproxy

镜像中的入口点脚本会检查haproxy命令，并替换为HAProxy上游提供的haproxy-systemd-wrapper，该工具负责信号处理以实现平滑重载。其底层使用haproxy的-sf选项，因此“在高负载下，可能会有两个几毫秒的小窗口出现少量连接失败”（参见停止和重启HAProxy）。

镜像变体

amd64/haproxy镜像提供多种变体，适用于不同场景。

amd64/haproxy:<version>

这是默认镜像。如不确定需求，建议使用此版本。它既可用作临时容器（挂载源码并启动），也可作为构建其他镜像的基础。

部分标签包含trixie等名称，这些是Debian的发行版代号，表示镜像基于该Debian版本构建。如需要在镜像中安装额外软件包，建议显式指定发行版代号以减少版本更新带来的问题。

amd64/haproxy:<version>-alpine

此镜像基于流行的Alpine Linux项目（来自alpine官方镜像）。Alpine Linux比大多数发行版基础镜像小得多（约5MB），因此生成的镜像更精简。

此变体适用于对最终镜像大小有严格要求的场景。需注意它使用musl libc而非glibc，部分软件可能因libc依赖而出现兼容性问题。有关更多讨论，请参见Hacker News评论。

为最小化镜像大小，Alpine基础镜像通常不包含额外工具（如git或bash）。如需添加，可在自定义Dockerfile中安装（参见alpine镜像说明了解安装方法）。

许可证

查看此镜像包含的软件的许可证信息。

与所有Docker镜像一样，此镜像可能包含其他软件，这些软件可能具有不同的许可证（如基础发行版中的Bash等，以及主软件的直接或间接依赖）。

部分自动检测到的额外许可证信息可在repo-info仓库的haproxy/目录中找到。

对于任何预构建镜像的使用，镜像用户有责任确保其使用符合所有包含软件的相关许可证要求。