LibreNMS 26.10.0 部署指南

目标：用 Docker Compose 在单台服务器上部署一套完整的 LibreNMS 监控平台（Web + MariaDB + Redis + Dispatcher 四服务），完成首台设备纳管与登录验证。本篇为容器部署专题，全部命令与回显均在 Ubuntu 22.04 实测环境逐条采集；原生安装路线见《Ubuntu 22.04 安装 LibreNMS 26.10.0 指南》。

一、环境信息

实测环境与关键版本如下，供复现对照：

操作系统：Ubuntu 22.04（x86_64），Docker 29.x + Compose v2
LibreNMS 镜像：librenms/librenms:26.9.1.1（镜像内 LibreNMS 26.9.1、Laravel 12.64.0、PHP 8.4.21，lnms about 实测）
数据库镜像：mariadb:10.11；缓存镜像：redis:7.2-alpine
Compose 项目：librenms（4 个服务：db / redis / librenms / dispatcher）
专用网络：librenms-net（10.89.60.0/24，显式指定防冲突）
端口映射：宿主机 8140 → Web 容器 8000
数据目录：./data/librenms（应用数据）、./data/db（数据库），随 compose 项目落盘
管理员账号：admin / Adm1n@LibreNMS26

版本基准说明：本批次版本基准为 LibreNMS 26.10.0（2026-10-19 发布，GitHub Releases 实查）。截至 2026-10-20，Docker Hub 官方镜像 librenms/librenms 最新已发布 tag 为 26.9.1.1（Docker Hub tags 实查：latest, 26.9.1.1, edge, 26.8.2, ...），26.10.0 镜像尚未推送。本文按"镜像实际可得的最新稳定 tag"部署并如实记录版本差异；镜像跟进 26.10.0 后仅需把 image: 行替换为 librenms/librenms:26.10.0，编排结构不变。

二、镜像选型说明

官方镜像只有一个：librenms/librenms（对应 GitHub librenms/docker 仓库构建），一个镜像通过环境变量扮演多种角色（Web / Dispatcher / Syslog-ng / Snmptrapd 侧车）。可用 tag 与选型（Docker Hub 实查 2026-10-20）：

镜像 tag	性质	建议
`26.9.1.1`	最新已发布稳定版	本文采用，生产推荐锁定具体版本号
`latest`	跟随最新发布	可用，但重建时版本漂移，不利于回溯
`edge`	每日开发构建	仅测试，勿用于生产
`26.8.2` 等历史号	历史稳定版	回滚时使用

数据库镜像选 mariadb:10.11（官方 compose 示例使用 mariadb:10 大版本标签，为避免大版本漂移本文锁到 10.11）；Redis 镜像选 redis:7.2-alpine（队列与缓存后端，Alpine 变体体积小）。

💡 说明：LibreNMS 镜像内置 nginx + PHP-FPM + cron + 调度逻辑，Web 容器自身即可完成基础轮询；dispatcher 侧车容器（SIDECAR_DISPATCHER=1）把轮询/告警等后台任务从 Web 进程中剥离，属官方推荐形态，扩容时只需横向增加 dispatcher 实例。

三、前置条件

一台装有 Docker Engine（24+，实测 29.x）与 Compose v2 插件的 Linux 服务器。
服务器可拉取 Docker Hub 镜像；国内网络受限环境先为守护进程配置镜像加速或代理。
规划一个空闲网段与端口：本文用 10.89.60.0/24 与 8140（部署前用 docker network ls / ss -ltn 确认未被占用）。
目录准备：为 compose 项目建独立目录（本文 /opt/librenms-compose），数据落其下 data/ 子目录。

四、部署步骤

4.1 编写环境变量文件

在项目目录创建 .env（compose 的变量源，数据库凭据集中于此）：

mkdir -p /opt/librenms-compose/data/{librenms,db}
cd /opt/librenms-compose
cat > .env <<'EOF'
TZ=Asia/Shanghai
PUID=1000
PGID=1000
MYSQL_DATABASE=librenms
MYSQL_USER=librenms
MYSQL_PASSWORD=q1w2e3r4
EOF

4.2 编写 compose.yml

创建 compose.yml（四服务 + 显式子网 + 端口映射；PUID/PGID=1000 让容器内进程以普通用户运行）：

name: librenms

services:
  db:
    image: mariadb:10.11
    container_name: librenms-2691-db
    command:
      - "mysqld"
      - "--innodb-file-per-table=1"
      - "--lower-case-table-names=0"
      - "--character-set-server=utf8mb4"
      - "--collation-server=utf8mb4_unicode_ci"
    networks:
      - librenms-net
    volumes:
      - "./data/db:/var/lib/mysql"
    environment:
      - "TZ=${TZ}"
      - "MARIADB_ROOT_PASSWORD=q1w2e3r4"
      - "MYSQL_DATABASE=${MYSQL_DATABASE}"
      - "MYSQL_USER=${MYSQL_USER}"
      - "MYSQL_PASSWORD=${MYSQL_PASSWORD}"
    restart: unless-stopped

  redis:
    image: redis:7.2-alpine
    container_name: librenms-2691-redis
    networks:
      - librenms-net
    environment:
      - "TZ=${TZ}"
    restart: unless-stopped

  librenms:
    image: librenms/librenms:26.9.1.1
    container_name: librenms-2691-web
    hostname: librenms
    cap_add:
      - NET_ADMIN
      - NET_RAW
    networks:
      - librenms-net
    ports:
      - "8140:8000"
    depends_on:
      - db
      - redis
    volumes:
      - "./data/librenms:/data"
    environment:
      - "TZ=${TZ}"
      - "PUID=${PUID}"
      - "PGID=${PGID}"
      - "DB_HOST=db"
      - "DB_NAME=${MYSQL_DATABASE}"
      - "DB_USER=${MYSQL_USER}"
      - "DB_PASSWORD=${MYSQL_PASSWORD}"
      - "DB_TIMEOUT=60"
      - "CACHE_DRIVER=redis"
      - "SESSION_DRIVER=redis"
      - "REDIS_HOST=redis"
    restart: unless-stopped

  dispatcher:
    image: librenms/librenms:26.9.1.1
    container_name: librenms-2691-dispatcher
    hostname: librenms-dispatcher
    cap_add:
      - NET_ADMIN
      - NET_RAW
    networks:
      - librenms-net
    depends_on:
      - librenms
      - redis
    volumes:
      - "./data/librenms:/data"
    environment:
      - "TZ=${TZ}"
      - "PUID=${PUID}"
      - "PGID=${PGID}"
      - "DB_HOST=db"
      - "DB_NAME=${MYSQL_DATABASE}"
      - "DB_USER=${MYSQL_USER}"
      - "DB_PASSWORD=${MYSQL_PASSWORD}"
      - "DB_TIMEOUT=60"
      - "DISPATCHER_NODE_ID=dispatcher1"
      - "SIDECAR_DISPATCHER=1"
      - "CACHE_DRIVER=redis"
      - "SESSION_DRIVER=redis"
      - "REDIS_HOST=redis"
    restart: unless-stopped

networks:
  librenms-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

⚠️ 注意：dispatcher 的 REDIS_HOST=redis 不可省略。实测漏配时 dispatcher 启动即报错重启：ERROR: REDIS_HOST or REDIS_SENTINEL must be defined。DISPATCHER_NODE_ID 在多 dispatcher 扩容时每个实例取不同值。

4.3 启动与状态确认

docker compose up -d

实测回显：

 Container librenms-2691-redis Started
 Container librenms-2691-db Started
 Container librenms-2691-web Starting
 Container librenms-2691-web Started
 Container librenms-2691-dispatcher Starting
 Container librenms-2691-dispatcher Started

约 1 分钟后（首次启动含建库、迁移）确认四容器状态与网络：

$ docker compose ps
NAME                      STATUS
librenms-2691-db          Up
librenms-2691-dispatcher  Up
librenms-2691-redis       Up
librenms-2691-web         Up

$ docker network inspect librenms_librenms-net --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
10.89.60.0/24

验证 Web 端口响应（302 跳登录页为正常）：

$ curl -s -o /dev/null -w "GET :8140 -> %{http_code} loc=%{redirect_url}\n" http://localhost:8140/
GET :8140 -> 302 loc=http://localhost:8140/login

4.4 创建管理员账号

镜像默认无预置账号，首次从 Web 向导创建，或直接在容器内用 CLI 创建（本文实测后者，可脚本化）：

docker exec librenms-2691-web lnms user:add admin \
  --password='Adm1n@LibreNMS26' --role=admin --no-ansi

实测回显：

Marked all notifications as read for user admin
Successfully added user: admin

4.5 纳管首台设备并验证出数

把 Web 容器自身作为第一台设备（ICMP ping 监控，--ping-fallback 表示 SNMP 不通时退化为 ping 监控）：

docker exec librenms-2691-web lnms device:add localhost --ping-fallback --no-ansi

实测回显：

Added device localhost (1)

等待 dispatcher 自动轮询一轮后（约 1–5 分钟），查看设备清单：

$ docker exec librenms-2691-web lnms report:devices --no-ansi
+-----------+-----+
| hostname  | ip  |
+-----------+-----+
| localhost | ::1 |
+-----------+-----+

4.6 登录验证

浏览器访问 http://<服务器IP>:8140/ 用 admin 登录；命令行等价验证（取登录页 CSRF token → 提交 → 首页 200）：

$ curl -s -c jar.txt http://localhost:8140/login -o l.html
$ TOK=$(grep -oE "name=\"_token\" value=\"[^\"]+" l.html | sed 's/.*value="//')
$ curl -s -b jar.txt -c jar.txt -o /dev/null -w "POST :8140/login -> %{http_code} loc=%{redirect_url}\n" \
    -d "username=admin" --data-urlencode "password=Adm1n@LibreNMS26" \
    --data-urlencode "_token=$TOK" http://localhost:8140/login
POST :8140/login -> 302 loc=http://localhost:8140/
$ curl -s -b jar.txt -o h.html -w "GET :8140/ -> %{http_code} " http://localhost:8140/
GET :8140/ -> 200
$ grep -oE "<title>[^<]*" h.html
<title>Overview | LibreNMS

五、数据持久化说明

数据	宿主机路径	容器路径	说明
应用数据（rrd/logs/配置）	`./data/librenms`	`/data`	性能数据与日志，重建容器不丢
MariaDB 数据	`./data/db`	`/var/lib/mysql`	设备/告警等结构化数据
环境变量	`./.env`	—	compose 变量源

数据落 compose 项目目录（/opt/librenms-compose/data/），升级镜像只需 docker compose pull && docker compose up -d，数据卷原样保留。备份即打包两个 data 子目录（数据库建议先 docker exec librenms-2691-db mysqldump -uroot -pq1w2e3r4 librenms > librenms.sql 再停写）。

六、环境变量表

librenms / dispatcher 服务常用变量（官方 README 与镜像 entrypoint 实测归纳）：

变量	实测取值	作用	必填
`DB_HOST`	`db`	数据库主机（服务名）	是
`DB_NAME` / `DB_USER` / `DB_PASSWORD`	`librenms` / `librenms` / `q1w2e3r4`	库名/用户/密码	是
`DB_TIMEOUT`	`60`	数据库连接超时（秒）	否
`REDIS_HOST`	`redis`	Redis 主机，dispatcher 必需	是（dispatcher）
`CACHE_DRIVER` / `SESSION_DRIVER`	`redis`	缓存/会话驱动	否
`SIDECAR_DISPATCHER`	`1`	以 Dispatcher 角色运行	侧车必填
`DISPATCHER_NODE_ID`	`dispatcher1`	调度节点标识，多实例需互异	侧车必填
`PUID` / `PGID`	`1000` / `1000`	容器内进程运行 UID/GID	否
`TZ`	`Asia/Shanghai`	时区	建议
`LIBRENMS_SNMP_COMMUNITY`	`librenmsdocker`	官方示例自带，探测 community	否
`SIDECAR_SYSLOGNG`	`1`	以 Syslog-ng 角色运行（可选服务）	可选
`SIDECAR_SNMPTRAPD`	`1`	以 Snmptrapd 角色运行（可选服务）	可选

七、配置参数说明

容器内 LibreNMS 配置与原生安装一致（.env + config 覆盖机制），差异在于容器把 .env 自动生成好了，自定义项推荐用 YAML 覆盖文件：把配置写在 /data/config/*.yaml（挂载到宿主机 ./data/librenms/config/），容器每次启动自动合入。例如关闭每日自动更新，新建 ./data/librenms/config/update.yaml：

update: false

⚠️ 注意：如需强制把 YAML 配置重新压回（覆盖 Web 界面已改的值），设环境变量 REAPPLY_YAML_CONFIG=1 后重建容器（官方 README 说明）。

八、配置文件挂载

除 *.yaml 配置外，还可按需挂载：

宿主机文件	容器路径	用途
`./data/librenms/config/*.yaml`	`/data/config/*.yaml`	LibreNMS 配置覆盖
自定义 nginx 配置	`/etc/nginx/conf.d/librenms.conf`	改 Web 端口/加 TLS（默认不建议动）
`./data/librenms/rrd`	`/data/rrd`	性能数据（已含在 /data 内）

九、等价 docker run

不用 Compose 时，等价的最小化启动序列（按依赖顺序，实际仍建议用 Compose 管理生命周期）：

# 数据库
docker run -d --name librenms-db --network librenms-net \
  -v /opt/librenms-compose/data/db:/var/lib/mysql \
  -e TZ=Asia/Shanghai -e MARIADB_ROOT_PASSWORD=q1w2e3r4 \
  -e MYSQL_DATABASE=librenms -e MYSQL_USER=librenms -e MYSQL_PASSWORD=q1w2e3r4 \
  mariadb:10.11 mysqld --innodb-file-per-table=1 --lower-case-table-names=0 \
  --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

# Redis
docker run -d --name librenms-redis --network librenms-net \
  -e TZ=Asia/Shanghai redis:7.2-alpine

# Web
docker run -d --name librenms-web --network librenms-net -p 8140:8000 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/librenms-compose/data/librenms:/data \
  -e TZ=Asia/Shanghai -e PUID=1000 -e PGID=1000 \
  -e DB_HOST=librenms-db -e DB_NAME=librenms -e DB_USER=librenms \
  -e DB_PASSWORD=q1w2e3r4 -e DB_TIMEOUT=60 \
  -e CACHE_DRIVER=redis -e SESSION_DRIVER=redis -e REDIS_HOST=librenms-redis \
  librenms/librenms:26.9.1.1

# Dispatcher 侧车
docker run -d --name librenms-dispatcher --network librenms-net \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/librenms-compose/data/librenms:/data \
  -e TZ=Asia/Shanghai -e PUID=1000 -e PGID=1000 \
  -e DB_HOST=librenms-db -e DB_NAME=librenms -e DB_USER=librenms \
  -e DB_PASSWORD=q1w2e3r4 -e DB_TIMEOUT=60 \
  -e REDIS_HOST=librenms-redis -e DISPATCHER_NODE_ID=dispatcher1 \
  -e SIDECAR_DISPATCHER=1 \
  librenms/librenms:26.9.1.1

十、常用运维命令

docker compose ps                 # 四服务状态
docker compose logs -f librenms   # 跟看 Web 容器日志
docker compose logs -f dispatcher # 跟看调度器日志（轮询/告警执行记录）
docker compose restart librenms   # 重启 Web
docker compose pull && docker compose up -d   # 升级镜像（数据保留）
docker compose down               # 停止并移除容器（数据卷保留）
docker compose down -v            # 连同命名卷删除（bind mount 数据仍需手动删）
docker exec librenms-2691-web lnms about --no-ansi   # 查看版本与运行时信息

lnms about 实测回显节选（镜像内版本核对）：

  Application Name .................................................. LibreNMS
  Laravel Version .................................................... 12.64.0
  PHP Version ......................................................... 8.4.21
  Composer Version .................................................... 2.10.3
  Environment ..................................................... production
  Timezone ..................................................... Asia/Shanghai

dispatcher 正常工作时日志可见任务循环（实测节选）：

Billing(INFO):Calculating billing
Billing(INFO):Completed billing run for calculate in 0.28s
Alerting(INFO):Completed alerting run for alerts in 0.29s

十一、常见问题（FAQ）

Q1：dispatcher 反复重启，日志报 "ERROR: REDIS_HOST or REDIS_SENTINEL must be defined"

实测现象见 4.2 警示。原因：Dispatcher 角色强依赖 Redis（任务队列）。解决：给 dispatcher（建议连同 librenms 服务）补 REDIS_HOST=redis、CACHE_DRIVER=redis、SESSION_DRIVER=redis 后 docker compose up -d 重建。

Q2：镜像 tag 没有想要的版本号（如 26.10.0）

Docker Hub 发布滞后于 GitHub Release 属常态（2026-10-20 实查最新镜像为 26.9.1.1）。解决：先用已发布的最新 tag 部署，跟踪 librenms/librenms tags 页，出现目标版本后改 image: 行执行 docker compose pull && docker compose up -d 即可原地升级。

Q3：首次启动 Web 502/白屏

多为 db 未就绪或首次迁移未完成。确认顺序：docker compose logs db 出现 "ready for connections" 后等 1–2 分钟再看 Web；dispatcher 报 "Waiting 60s for database to be ready..." 属正常等待逻辑（实测该提示后自动继续）。

Q4：添加 SNMP 设备后不出数据

容器内轮询目标需网络可达：被监控设备的 SNMP 161/UDP 必须对容器网段（10.89.60.0/24）放行；先用容器内命令验证连通性：docker exec librenms-2691-web lnms device:ping <目标IP>，再检查 community 与 ACL。跨网段监控时在防火墙上放行容器网段源地址。

Q5：端口 8140 与已有服务冲突

改 compose.yml 中 ports: "8140:8000" 左侧宿主机端口为空闲端口后 docker compose up -d；右侧 8000 是容器内固定监听口，不要改。

十二、参考链接

官方 Docker 仓库（镜像构建与示例编排）：https://github.com/librenms/docker
官方 compose 示例：https://github.com/librenms/docker/tree/master/examples/compose
Docker Hub 镜像页：https://hub.docker.com/r/librenms/librenms
LibreNMS 官方安装文档：https://docs.librenms.org/Installation/Install-LibreNMS/
Dispatcher 服务文档：https://docs.librenms.org/Advanced/Dispatcher-Service/
本站原生安装实战：《Ubuntu 22.04 安装 LibreNMS 26.10.0 指南》
本站选型认知：《LibreNMS 26.10.0 介绍与选型指南》
本站命令实战：《LibreNMS 26.10.0 常用 CLI 命令与工具详解》