Docker 搭建 LibreSpeed：自建网络测速服务实战指南

Docker 搭建 LibreSpeed：把测速服务装进容器，这件事比想象中值得折腾

前阵子帮朋友排查一条宽带的实际速率，用公共测速站点测出来的数字忽高忽低，同一时段换三个站点能差出三成，根本没法作为判断依据。后来索性自己动手，用 Docker 把 LibreSpeed 跑起来，前后不到二十分钟，一个完全受自己控制的测速服务就上线了。这件事让我意识到，很多人对"测速"的理解还停留在打开网页点一下按钮的阶段，却忽略了测速服务本身的部署位置、网络路径、服务端性能都会直接影响结果。LibreSpeed 是一个开源的网络测速工具，前端轻量、后端支持多种实现，配合 Docker 部署几乎没有环境依赖的烦恼，特别适合自建服务、内网验证、家庭宽带验收、机房链路巡检这些场景。这篇文章我会把从零搭建到调优排错的完整过程拆开讲，包括镜像怎么选、容器怎么配、参数为什么这么设、测出来的数字怎么读，以及我踩过的那些坑。不管你是刚接触容器的新手，还是想给团队搭一套内部测速工具的老手，都能从里面找到能直接抄作业的部分。

1. 先想清楚：为什么是 LibreSpeed，为什么用 Docker

1.1 自建测速服务到底解决什么问题

公共测速站点最大的问题不是不准，而是"不可控"。你无法知道测速服务器的物理位置离你多远、它当时的负载如何、中间经过了多少跳路由、有没有被限速策略影响。这些变量叠加在一起，测出来的数字只能当参考，不能当证据。自建测速服务把服务端放在你自己能掌控的位置——可以是家里的另一台机器、公司内网的一台服务器、云上的一台实例——这样测出来的结果反映的就是"你的客户端到你的服务端"这条链路的真实表现，变量少了一大半。

LibreSpeed 的价值在于它足够轻。整个前端就是几个静态文件，后端有 PHP、Go、Rust、Node 等多种实现可选，测速原理是基于 HTTP 的下载上传加延迟抖动测量，不依赖特殊的协议或插件。这意味着它对服务端资源要求很低，一台低配机器甚至树莓派都能跑起来。相比之下，一些商业测速方案要么需要专用客户端，要么服务端是个黑盒，出了问题只能等厂商。LibreSpeed 的代码是公开的，测速逻辑透明，你甚至可以自己改前端界面、调整测试时长、限制并发数。

用 Docker 部署的理由更直接：LibreSpeed 的后端实现依赖运行时环境（比如 PHP 需要 Web 服务器配合，Go 需要编译产物），手动装一遍要处理版本、扩展、权限一堆琐事。打成镜像之后，环境被固化，换台机器一条命令就能复现，升级回滚也简单。对于需要在内网多台机器上部署、或者想快速验证不同后端实现性能差异的场景，容器的优势非常明显。

1.2 三种常见后端实现怎么选

LibreSpeed 官方提供了多个后端实现，社区里最常被拿来用的是 PHP、Go 和 Rust 三个版本。选哪个不是拍脑袋决定的，得看你的实际约束。

我个人的选择逻辑是：如果只是家庭或小团队内部用，Go 版最省心，镜像体积小、启动秒级、没有额外的 Web 服务器要维护；如果公司已经有成熟的 PHP 运行环境，PHP 版能直接挂到现有站点的一个子目录下，省去单独维护一个服务的成本；Rust 版适合对性能有极致要求、或者想拿来做压测对比的场景。这篇文章的实操部分我会以 Go 版为主线，因为它的部署路径最短，同时会在关键处说明 PHP 版的差异，方便你对号入座。

提示：不要一上来就追求"性能最强"的后端。测速服务的瓶颈往往在带宽和网络路径，而不是后端语言。先用最简单的方案把服务跑通、把结果测准，再考虑换实现做优化。

1.3 部署前必须确认的三件事

动手之前有三件事必须先确认，否则后面大概率要返工。第一是宿主机的网络位置，测速服务应该部署在你想要测量的那条链路的"另一端"，比如你想测家里宽带的真实速率，服务端就不能放在同一台机器上，否则测的是本机回环，毫无意义。第二是端口占用，LibreSpeed 默认走 80 或 8080，先确认宿主机上这些端口没被别的服务占着。第三是防火墙和端口映射，容器内部端口和宿主机端口是两回事，映射关系没理清楚，服务起来了但外面访问不到，这种问题新手最容易卡住。

还有一点容易被忽略：测速会产生较大的流量。一次完整的下载加上传测试，视测试时长和带宽而定，可能消耗几百 MB 到几个 GB 的流量。如果部署在按流量计费的云主机上，务必先算清楚成本，或者把测试时长调短、限制单次测试的数据量。这个细节后面讲参数配置时我会具体说。

2. 核心细节拆解：镜像、端口与目录的那些门道

2.1 镜像从哪来，标签怎么选

LibreSpeed 的容器镜像在公共镜像仓库里有多个来源，有官方维护的，也有社区打包的。选镜像时我优先看两点：更新时间和拉取量。更新时间太久的镜像可能对应的是老版本前端，测速逻辑或界面有差异；拉取量太低的镜像缺乏验证，出问题不好排查。标签方面，尽量用明确的版本号而不是 latest，latest 会在你不知情的时候变成另一个版本，某天重启容器发现行为变了，排查成本很高。

拉取镜像的命令很直接：

docker pull 镜像仓库地址/librespeed/librespeed:版本号

实际执行时把镜像仓库地址和版本号替换成你确认过的来源。拉完之后用docker images看一眼体积，Go 版的镜像通常在几十 MB 量级，如果看到几百 MB 甚至上 GB，说明基础镜像选得比较重，可以考虑换更精简的标签。镜像体积不影响测速结果，但影响拉取速度和磁盘占用，在边缘设备上部署时这点很关键。

2.2 端口映射：容器内外的对应关系

LibreSpeed 容器内部通常监听 8080 端口（具体以镜像说明为准）。端口映射的写法是-p 宿主机端口:容器端口，比如-p 8080:8080表示把宿主机的 8080 映射到容器的 8080。这里有个常见误区：很多人以为改了前面的数字服务就换端口了，其实容器内部还是监听原来的端口，只是外部访问入口变了。如果你想让服务走 80 端口对外，写成-p 80:8080即可，容器内部不用动。

端口选择上有个经验：如果这台机器上还跑着别的 Web 服务，别抢 80 和 443，用一个不冲突的高位端口，比如 8088、9090 这类，然后在前面挂一个反向代理统一入口。反向代理的好处是能顺便加上访问控制、限流、日志，测速服务本身不需要暴露在公网上，加一层保护更稳妥。反向代理配置时要注意允许较大的请求体，因为上传测试会发送大文件，代理默认的请求体大小限制可能会把上传测试拦掉，表现为上传测速一直失败或数值异常偏低。

2.3 数据目录与配置持久化

LibreSpeed 的前端页面、后端脚本、以及可选的测速结果记录都涉及文件。容器是无状态的，容器删了里面的改动就没了，所以需要把关键目录挂载出来。通常要挂的是存放前端静态文件的目录和存放配置的目录，具体路径以镜像文档为准。挂载命令形如：

-v /宿主机路径/config:/容器内配置路径 -v /宿主机路径/前端目录:/容器内前端路径

挂载之后，你想改前端界面上的标题、logo、默认测试时长，直接改宿主机上的文件，重启容器就生效，不用进容器里折腾。这里有个细节：挂载目录的权限要和容器内运行用户的权限匹配，否则容器启动后读写文件报权限错误。我遇到过挂载后前端页面 403 的情况，查了半天是宿主机目录属主不对，容器内进程没权限读。解决办法是把宿主机目录的属主改成容器内运行用户的 UID，或者放宽目录权限（仅限内网可信环境）。

注意：不要把整个容器根目录挂载出来，也不要用特权模式跑测速容器。测速服务只需要网络和少量文件读写权限，给多了是安全隐患。

2.4 环境变量：那些影响测速行为的开关

不少 LibreSpeed 镜像支持通过环境变量调整行为，比如是否启用结果记录、默认测试时长、是否显示 IP 信息等。这些开关的具体名称各镜像可能不同，使用前务必对照镜像说明。我一般会关注这几类：测试时长相关的（影响单次测试消耗的流量和时间）、结果存储相关的（要不要把每次测速结果落库）、界面展示相关的（显示哪些指标、是否允许用户改测试参数）。

环境变量在docker run里用-e 变量名=值传入，在 compose 文件里写在 environment 段落下。改完环境变量必须重建容器才生效，docker restart不够，因为环境变量是在容器创建时注入的。这一点很多人会搞混，改了半天没反应，其实是没重建。

3. 实操过程：从零把服务跑起来

3.1 用 docker run 快速验证

第一次部署我建议先用docker run跑一个临时容器，验证镜像能起来、端口通、页面能打开，确认没问题再转成正式配置。命令结构如下：

docker run -d \ --name librespeed-test \ -p 8088:8080 \ --restart unless-stopped \ 镜像仓库地址/librespeed/librespeed:版本号

逐段解释一下。-d是后台运行，不加的话容器会占着当前终端。--name给容器起个名字，方便后续管理，不起名的话 Docker 会随机分配一个，回头你都找不到哪个是哪个。-p 8088:8080是端口映射，宿主机 8088 对外，容器内 8080。--restart unless-stopped让容器在宿主机重启后自动拉起，除非你手动停过它，这个对长期运行的服务很重要，不然机器一重启服务就没了。

跑起来之后用docker ps确认容器状态是 Up，然后用浏览器访问http://宿主机IP:8088。如果页面能打开、点开始测试能跑出数字，说明基础链路通了。如果页面打不开，先docker logs 容器名看日志有没有报错，再检查宿主机防火墙有没有放行 8088 端口。这一步别急着往下走，基础不通后面全是白费。

3.2 转成 compose 配置，方便长期维护

临时容器验证通过后，我会把它删掉，改用 compose 管理。原因很简单：docker run的参数一长串，时间久了自己都记不住当时怎么配的，compose 文件把配置固化下来，改起来直观，迁移时复制文件就行。一个基础的 compose 配置长这样：

services: librespeed: image: 镜像仓库地址/librespeed/librespeed:版本号 container_name: librespeed ports: - "8088:8080" volumes: - ./config:/容器内配置路径 - ./frontend:/容器内前端路径 environment: - TZ=Asia/Shanghai restart: unless-stopped

几个要点。volumes里的./config是相对 compose 文件所在目录的路径，第一次启动前要先手动建好这两个目录，否则 Docker 可能会以 root 身份自动创建，导致权限问题。TZ环境变量设成你所在时区，影响日志和结果记录里的时间戳，不设的话默认是 UTC，看日志时差八小时容易懵。restart策略和前面说的一样。

启动命令是docker compose up -d，停止是docker compose down，看日志是docker compose logs -f。这套命令建议记熟，日常运维基本就靠它们。

3.3 参数计算：测试时长和流量消耗怎么估

测速的流量消耗是可以估算的，心里有个数才不会在按流量计费的机器上翻车。下载测试的流量约等于"测试时长 × 实际带宽"，上传测试同理。假设你的链路是 100Mbps，测试时长设 15 秒，那么单次下载测试大约消耗 100Mbps × 15s ÷ 8 ≈ 187MB，加上上传测试再来一遍，单次完整测试接近 400MB。如果链路是千兆，同样的时长单次测试就能吃掉 3GB 以上。

所以测试时长的设置要结合链路带宽和流量成本来定。内网环境带宽高、流量免费，时长可以设长一点，比如 15 到 30 秒，结果更稳定；公网按流量计费的场景，时长压到 5 到 10 秒，或者干脆限制单次测试的最大数据量。LibreSpeed 的前端一般允许在配置里调整这些参数，具体字段名对照你用的版本说明。我的经验是：默认时长设 10 秒是个比较平衡的值，既能跑出有参考意义的数字，又不至于一次测试消耗太多流量。

3.4 验证测速结果是否可信

服务跑起来不等于结果可信。验证方法有几个。第一，在同一内网的两台机器之间测，理论上应该接近内网交换机的实际吞吐，如果测出来远低于预期，可能是服务端机器性能不够（比如 CPU 跑满导致处理不过来）或者网卡协商速率不对。第二，用不同的客户端设备测同一服务端，结果应该在同一量级，差异过大说明客户端侧有问题。第三，对比服务端机器自己用命令行工具做的吞吐测试，两者应该大致吻合，偏差过大说明测速服务的配置或路径有问题。

我遇到过一次测出来上传速率只有下载的十分之一，排查发现是反向代理的请求体大小限制把上传测试截断了，调整代理配置后恢复正常。所以看到异常数字，先别怀疑网络，先查服务端配置和中间链路。

4. 常见问题与排查技巧实录

4.1 页面能打开但测速一直失败

这是最常见的问题，表现是页面加载正常，点开始测试后进度条卡住或者直接报错。排查顺序建议这样：先看浏览器开发者工具的网络面板，看是哪个请求失败了、返回什么状态码。如果是 4xx，多半是路径或权限问题，检查挂载目录里的文件是否完整、容器内进程有没有读权限。如果是 5xx，看容器日志有没有后端报错。如果是请求超时，检查反向代理的超时设置，测速请求耗时较长，代理默认超时可能不够。

还有一种情况是跨域问题。如果前端和后端不在同一个源下（比如前端挂在 A 域名，后端接口在 B 域名），浏览器的同源策略会拦截请求。解决办法是让前后端同源部署，或者在后端配置里允许跨域。自建场景下最简单的做法就是同源，别给自己找麻烦。

4.2 测出来的数字明显偏低

数字偏低的原因很多，按可能性从高到低排：服务端机器性能不足（CPU 或网卡成为瓶颈）、中间链路有限速、客户端侧有干扰、测速参数设置不合理。排查时先排除服务端，在服务端本机用命令行工具测一下到客户端的吞吐，如果命令行也低，说明是链路或服务端硬件问题；如果命令行正常但 LibreSpeed 低，说明是服务配置问题。

服务端性能这块容易被忽视。测速服务在处理大流量时对 CPU 有一定要求，尤其是加密传输（HTTPS）场景，低配机器可能跑不满带宽。如果发现 CPU 在测速时打满，考虑换性能更好的机器，或者关掉不必要的加密、降低测试并发。

4.3 容器重启后配置丢失

前面强调过挂载的重要性，这里再具体说下症状和解决。症状是改过的前端标题、测试参数在容器重启后变回默认值。原因是改动写在了容器内部，容器重建时内部文件系统被重置。解决办法是把要改的文件放到宿主机挂载目录里，让容器读挂载目录。已经改在容器里的，用docker cp把文件拷出来放到宿主机对应目录，再确认挂载路径正确。

4.4 常见问题速查表

4.5 几个我踩过的坑

第一个坑是镜像架构不匹配。在一种 CPU 架构的机器上拉了一个为另一种架构构建的镜像，容器起不来或者起来后行为异常。拉镜像前确认宿主机架构，拉取时注意镜像是否支持多架构。第二个坑是挂载目录权限，前面提过，容器内用户和宿主机目录属主不一致导致读写失败，表现可能是页面 403 或者配置改不动。第三个坑是反向代理的缓冲设置，代理默认会缓冲响应，测速这种持续大流量的场景下缓冲会引入额外延迟甚至中断，需要在代理配置里关掉对应路径的缓冲。

提示：每次改完配置，先用docker compose config检查语法，再up -d重建，最后看日志确认没有报错。养成这个习惯能省掉大量"改了没生效"的困惑。

5. 进阶：让这套服务更好用

5.1 加一层访问控制

测速服务暴露在内网或公网时，建议加访问控制，避免被无关的人拿来消耗流量。最简单的方式是在反向代理层加基础认证，配置几行就能实现。如果不想动代理，也可以在网络层限制来源 IP，只允许特定网段访问。LibreSpeed 本身也支持一些访问相关的配置项，具体看版本说明。访问控制不是必须的，但在公网环境部署时强烈建议加上，否则你的服务可能变成别人的免费测速工具。

5.2 结果记录与趋势观察

LibreSpeed 支持把每次测速结果记录下来，存到数据库或文件里。这个功能对长期观察链路质量很有用，比如你想知道家里宽带在晚高峰是否稳定，可以定时跑测试、记录结果，过一段时间看趋势。启用结果记录需要在配置里指定存储方式和连接信息，具体字段对照版本说明。存储选型上，轻量场景用文件或轻量数据库就够，别为了记几个数字上一套重型数据库，维护成本不划算。

5.3 多节点部署做对比

如果条件允许，在不同网络位置各部署一个测速节点，从同一客户端分别测，对比结果能帮你定位问题出在哪一段链路。比如家里到公司内网节点慢、到云上节点快，说明问题可能出在家庭出口或运营商侧。多节点部署时注意各节点的配置保持一致，否则对比没有意义。节点多了之后，可以用一个简单的页面或脚本汇总各节点的测速结果，方便一眼看全。

这套东西搭下来，最大的收获不是多了一个测速工具，而是对"网络质量"这件事有了更具体的感知。以前看到"网速慢"只能凭感觉，现在能拿出具体数字、能对比不同时段、能定位是哪一段出了问题。工具本身不复杂，难的是想清楚为什么要测、测出来的数字怎么用。把这两点想明白，剩下的就是照着步骤配置的事了。