LibreSpeed 测速系统部署指南

1. 环境准备

1.1 系统要求

项目	要求
操作系统	Rocky Linux 10.1 (Red Quartz) 或兼容的 RHEL 系发行版
Docker	26.10+
Docker Compose	2.0+
网络端口	80/TCP (Web 服务)

前置依赖

确保 Docker 和 Docker Compose 已正确安装。若 docker-compose 命令不可用，需先安装 Docker Compose 插件或独立二进制文件。

1.2 安装 Docker Compose (如未安装)

# 方式一：安装 Docker 官方插件 (推荐)
sudo dnf install docker-compose-plugin

# 方式二：使用独立二进制
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

1.3 创建工作目录

sudo mkdir -p /docker/librespeed/
cd /docker/librespeed/

2. 部署模式选择

LibreSpeed 支持两种部署模式，根据实际场景选择：

模式	适用场景	数据持久化	复杂度
Standalone	快速体验、临时测试	无	低
PostgreSQL	生产环境、Telemetry 数据收集	有	中

3. 模式一：Standalone 快速部署

3.1 编写 Compose 文件

sudo tee /docker/librespeed/docker-compose.yaml << 'EOF'
version: '3.7'

services:
  speedtest:
    container_name: speedtest
    image: ghcr.io/librespeed/speedtest:latest
    restart: always
    environment:
      MODE: standalone
      TITLE: "LibreSpeed 网络测速"
      # TELEMETRY: "false"
      # ENABLE_ID_OBFUSCATION: "false"
      # REDACT_IP_ADDRESSES: "false"
      # PASSWORD: "your_password"
      # GDPR_EMAIL: "[email protected]"
      # DISABLE_IPINFO: "false"
      # IPINFO_APIKEY: "your_api_key"
      # DISTANCE: "km"
      # WEBPORT: 8080
    ports:
      - "80:8080"  # host:container
EOF

配置说明

上述配置为最小可用配置。MODE: standalone 表示不依赖外部数据库，所有数据仅存于内存中，容器重启后测速记录丢失。注释掉的参数可根据需求启用。

端口映射格式

ports 字段必须正确缩进，且每个端口映射为独立列表项。错误格式会导致 Compose 解析失败。

3.2 启动服务

cd /docker/librespeed/
sudo docker compose up -d

3.3 验证状态

sudo docker compose ps
sudo docker compose logs -f speedtest

访问 http://<服务器IP> 即可使用测速服务。

4. 模式二：PostgreSQL 生产部署

4.1 架构概述

4.2 准备初始化 SQL

数据库初始化

生产模式需要 PostgreSQL 初始化脚本。从 LibreSpeed 官方仓库获取 telemetry_postgresql.sql 并放置到 ./init/ 目录。

# 创建初始化目录并下载 SQL 文件
sudo mkdir -p /docker/librespeed/init/

# 方式一：从官方仓库下载
sudo curl -L https://raw.githubusercontent.com/librespeed/speedtest/master/results/telemetry_postgresql.sql \
  -o /docker/librespeed/init/telemetry_postgresql.sql

# 方式二：若网络受限，手动复制已有文件到该路径

4.3 配置环境变量

密码安全

.env 文件包含数据库密码和测速后台密码，务必设置严格权限，避免泄露。

sudo tee /docker/librespeed/.env << 'EOF'
POSTGRES_PASSWORD=YourSecureDBPassword!
SPEEDTEST_PASSWORD=YourSecureAdminPassword!
[email protected]
EOF

# 设置文件权限，仅 root 可读
sudo chmod 600 /docker/librespeed/.env

4.4 编写生产 Compose 文件

sudo tee /docker/librespeed/docker-compose.yaml << 'EOF'
x-shared:
  speedtest-env: &speedtest-env
    TITLE: "上海交通大学医学院网络测速"
    TITLE_EN: "Shanghai Jiao Tong University School of Medicine — Network Speed Test"
    FOOTER_NOTICE: "本测速服务器位于上海交通大学医学院网络信息中心"
    FOOTER_NOTICE_EN: "Speed test server at Shanghai Jiao Tong University School of Medicine Network Information Center."
    PASSWORD: "${SPEEDTEST_PASSWORD}"
    EMAIL: "${SPEEDTEST_EMAIL}"
    ENABLE_ID_OBFUSCATION: "false"
    MODE: "standalone"
    REDACT_IP_ADDRESSES: "false"
    TELEMETRY: "true"
    TZ: "Asia/Shanghai"

services:
  pg:
    image: postgres:16-alpine
    container_name: librespeed-pg
    environment:
      POSTGRES_USER: librespeed
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRES_DB: librespeed
      TZ: Asia/Shanghai
      PGTZ: Asia/Shanghai
    volumes:
      - ./init/telemetry_postgresql.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U librespeed -d librespeed"]
      interval: 10s
      timeout: 5s
      retries: 5

  speedtest:
    container_name: librespeed-web
    # 镜像名称需与 docker load 后的实际镜像一致
    image: ghcr.io/librespeed/speedtest:latest
    environment:
      <<: *speedtest-env
      DB_TYPE: postgresql
      DB_HOSTNAME: pg
      DB_NAME: librespeed
      DB_USERNAME: librespeed
      DB_PASSWORD: "${POSTGRES_PASSWORD}"
    ports:
      - "80:8080"
    # 可选：自定义品牌标识时启用
    # volumes:
    #   - ./branding:/speedtest-branding:ro
    depends_on:
      pg:
        condition: service_healthy
    restart: unless-stopped

volumes:
  pg_data:
    driver: local
EOF

镜像替换

若使用 docker save 导出的离线镜像，需将 image 字段替换为实际加载后的镜像名称，或通过 docker tag 重命名为标准名称。

品牌挂载路径

若启用自定义品牌 (branding 卷挂载)，确保宿主机 ./branding 目录存在且包含正确的资源文件。注释掉的 volumes 块需取消注释并正确缩进到 speedtest 服务下。

4.5 启动生产环境

cd /docker/librespeed/
sudo docker compose up -d

4.6 验证服务状态

# 查看容器状态
sudo docker compose ps

# 查看数据库健康检查
sudo docker compose logs pg | grep "database system is ready"

# 查看测速服务日志
sudo docker compose logs -f speedtest

# 测试数据库连接
sudo docker compose exec pg pg_isready -U librespeed -d librespeed

5. 防火墙与 SELinux 配置

5.1 防火墙放行

# firewalld 放行 HTTP 端口
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

5.2 SELinux 设置 (如启用)

# 临时设置宽容模式（测试环境）
sudo setenforce 0

7. 故障排查

现象	可能原因	排查方法
容器启动后立即退出	数据库连接失败	docker compose logs speedtest
数据库初始化失败	SQL 文件缺失或权限不足	检查 ./init/ 目录及文件权限
端口 80 被占用	其他服务已占用	sudo ss -tlnp | grep :80
无法访问测速页面	防火墙未放行	sudo firewall-cmd --list-all
Telemetry 数据未记录	TELEMETRY 未启用或数据库异常	检查环境变量及数据库日志

日志排查

遇到问题时，优先查看容器日志：sudo docker compose logs -f <service_name>。speedtest 服务日志会明确提示数据库连接或配置错误。

8. 参考链接

• LibreSpeed 官方 GitHub
• LibreSpeed Docker 镜像文档