用Docker Compose快速部署LibreNMS网络监控系统：从零到生产环境实战

1. 聊两句为什么我最终选了LibreNMS加Docker这套组合做运维这些年监控系统的选型一直是个头疼事。Zabbix功能全但配置重Prometheus灵活但学习曲线陡商业监控产品又贵得离谱。直到我接触了LibreNMS才发现原来开源网络监控可以做得这么顺手。它基于PHP和MySQL原生支持SNMP自动发现设备、自动绘制流量图几百台设备的网络环境完全扛得住最关键的是它对新手极其友好部署完基本不用写什么配置就能跑起来。但LibreNMS有个老毛病——手动部署挺折腾。PHP扩展、Composer依赖、数据库初始化、权限设置每一步都可能出幺蛾子。我早期部署的时候光是环境依赖就折腾了大半天。后来改用Docker部署整个流程被压缩到5分钟以内而且迁移、备份、升级都变得异常轻松。这篇文章把我实战中沉淀下来的部署流程、中文配置方法和踩坑记录全整理出来不管你是刚接触网络监控的新手还是想优化现有监控方案的老手照着做就能少走很多弯路。我假设你已经对Docker有基本了解知道自己在这台机器上要装什么服务、开放哪些端口。如果完全是Docker小白也没关系我会把每一条命令和参数都解释清楚你按着顺序复制执行就行。2. 部署前的思路拆解Docker Compose怎么省掉90%的配置工作2.1 一条命令启动整套系统的秘密LibreNMS依赖好几个服务核心有三个PHP运行环境、MySQL数据库、Nginx或者Apache。手动部署得分别装、分别配、分别启动任何一个环节版本不兼容就卡住。Docker Compose把这一切变成了声明式配置你要做的就是写一个docker-compose.yml文件把你需要的镜像和配置写进去然后一条命令全部拉起来。这个思路和搬家很像。手动部署就像你一件一件把家具扛进新家还要自己接水管、拉电线Docker Compose则是直接找了一个精装好的房子家具家电全配齐钥匙一交拎包入住。LibreNMS官方维护的Docker镜像底层已经把PHP扩展、Composer依赖、定时任务、SNMP工具链都预装好了你不需要关心这些底层细节。2.2 官方镜像和自定义镜像该怎么选LibreNMS官方在Docker Hub上维护了两个镜像librenms/librenms发行版镜像和librenms/librenms:latest开发版镜像。生产环境我强烈推荐用带版本号的发行版镜像例如librenms/librenms:24.2.0这样明确的tag而不是直接用latest。原因很简单latest跟着上游更新哪天官方推了一个带bug的新版本你重建容器就中招了。固定的版本tag让每次升级都是受控操作出了兼容性问题也方便回滚。数据库镜像我用的是mariadb:10.5。这里有个容易被忽略的细节LibreNMS对MySQL 8.0有个兼容性坑——默认的密码认证插件是caching_sha2_password老版本的PHP mysqli驱动不认。用MariaDB 10.5就没这个问题这也是官方文档推荐的搭配。2.3 目录映射和网络模式的设计考量容器是无状态的所有需要持久化的数据必须映射到宿主机目录。LibreNMS需要持久化的就两个东西数据库文件和监控数据。我的做法是在宿主机上建一个专门的项目目录里面分db和librenms两个子目录分别挂载给数据库和LibreNMS。网络模式我选择了桥接模式并显式映射端口。这里有个技巧把Web端口映射成8000:8000避免和宿主机上可能存在的Nginx或Apache冲突。如果你要监控的设备和这台宿主机不在同一网段记得在防火墙里放行对应端口否则LibreNMS的自动发现功能会全部失败。注意LibreNMS容器默认用的是8000端口不是80端口。很多新手在这个地方卡住浏览器打开80端口死活不通实际上人家监听在8000。3. 手把手实操从零到监控界面跑起来3.1 准备阶段目录结构和默认参数先规划好目录我习惯把所有Docker应用统一放在/opt下面和系统自带的服务区分开。执行以下命令创建项目目录mkdir -p /opt/librenms/{db,librenms} cd /opt/librenms然后找一个顺手的环境变量值。数据库密码、API令牌这类敏感信息统一放在.env文件里管理标准docker-compose.yml再用变量引用。这样可以避免密钥硬编码在部署文件里也方便多人协作时做权限控制。下面是我用的.env文件你根据实际情况修改密码MYSQL_ROOT_PASSWORDyour_strong_root_password MYSQL_DATABASElibrenms MYSQL_USERlibrenms MYSQL_PASSWORDyour_strong_db_password3.2 docker-compose.yml核心配置逐行解读在/opt/librenms目录下创建docker-compose.yml内容如下version: 3.8 services: db: image: mariadb:10.5 container_name: librenms_db restart: unless-stopped environment: - MYSQL_ROOT_PASSWORD${MYSQL_ROOT_PASSWORD} - MYSQL_DATABASE${MYSQL_DATABASE} - MYSQL_USER${MYSQL_USER} - MYSQL_PASSWORD${MYSQL_PASSWORD} - TZAsia/Shanghai command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_unicode_ci volumes: - ./db:/var/lib/mysql networks: - librenms_net librenms: image: librenms/librenms:24.2.0 container_name: librenms_app restart: unless-stopped depends_on: - db ports: - 8000:8000 environment: - TZAsia/Shanghai - PUID1000 - PGID1000 - APP_NAMELibreNMS volumes: - ./librenms:/data networks: - librenms_net networks: librenms_net: driver: bridge每个关键配置背后的考量我简单说明一下restart: unless-stopped保证宿主机重启后监控服务能自动恢复。运维监控这个场景服务可用性是硬指标手动重启不可接受。depends_on确保数据库先启动LibreNMS后启动。但注意这个配置只保证启动顺序不保证数据库初始化完成。如果第一次启动时LibreNMS报连不上数据库通常重启一下librenms容器就好。TZAsia/Shanghai时区配置这个必须设置。不设置的话容器默认UTC时间设备流量图上显示的时间比你本地时间晚8个小时排查故障时非常容易混淆。PUID/PGID挂载目录的文件属主。保持和宿主机当前用户一致避免容器写入的文件让你在宿主机上没权限处理。3.3 启动与初始化配置写好后启动就两条命令的事docker compose up -d-d参数是detached模式让容器在后台运行。第一次执行会自动拉取镜像耗时取决于网速一般几分钟。启动后等30秒左右让数据库完成初始化然后打开浏览器访问http://你的服务器IP:8000你应该能看到LibreNMS的Web安装向导页面。如果页面一直打不开先检查容器状态和日志docker compose ps docker compose logs librenms初始化向导会让你填数据库连接信息。注意这里的主机名不要填localhost或者宿主机IP要填compose服务名db。在Docker自定义网络中容器之间通过服务名互联这是新手最容易搞混的地方。数据库名、用户名、密码对应.env里配置的值。3.4 后台任务和定时器很多人漏掉的一环Web界面能打开只算完成了一半。LibreNMS核心能力依赖后台定时任务每5分钟执行一次设备发现每60秒拉取一次性能数据。官方提供了librenms-service.py这个服务来管理这些定时任务。在Docker镜像里定时任务默认已经配好了。但我在实际使用中发现一个问题容器内默认的调度器在某些重负载场景下会超时。解决办法是进入容器手动确认定时任务配置是否正确docker exec -it librenms_app sh crontab -l正常情况下你应该看到类似*/5 * * * * /usr/bin/php ...的条目。如果crontab是空的说明定时任务没有生效接下来所有自动发现和流量采集都不会工作监控系统就成了一个空壳。修正方法是执行容器内的/scripts/install-cron.sh脚本。4. 中文配置从界面语言到数据展示的细节处理4.1 Web界面切换中文语言包LibreNMS早期版本只支持英文界面后来加入了国际化支持。切换到中文界面的路径是登录后点击右上角用户头像进入Edit Profile编辑个人资料在Language下拉框里选择zh-CN简体中文保存后刷新页面即可。这里有个坑如果镜像里没下载对应的语言包文件即便选了中文界面依然是英文。新版镜像一般自带了zh-CN语言包如果切换后没生效进入容器确认语言文件是否存在docker exec -it librenms_app ls /opt/librenms/lang/zh-CN/如果目录为空需要下载语言包或者换用较新的镜像版本。我在实践中用24.x版本的镜像中文语言包是完整的界面上几乎所有菜单都能正常显示中文包括仪表盘、设备列表、告警规则这些高频功能。4.2 时区、日期格式和中文时间显示界面语言切了中文但时间和日期格式还是英文习惯看起来很别扭。LibreNMS的日期格式在用户设置里可以调整路径是Edit Profile - Date format。我通常设置为Y-m-d H:i:s这样时间显示为2025-01-15 14:30:45符合我们日常阅读习惯。同时在系统配置里把默认时区选为Asia/Shanghai确保所有设备的采集时间统一。还有一个容易被忽略的细节图表的X轴坐标时间格式。在Settings - General - Graphs配置里把x-axis timezone设为当前时区否则你看到的流量图横轴时间可能偏移8小时。这个偏移问题在跨时区排查故障时非常致命明明告警说的是下午3点图上显示的是凌晨3点直接就判断错方向了。4.3 网卡名称和状态的中文化适配中文界面下设备端口列表里显示的还是英文物理标识比如Gi0/0/1、Eth-Trunk1。这个不用强求汉化保留设备原生命名反而更利于和网络设备厂商的配置命令对照。但可以把端口描述别名Description设置成方便自己识别的中文标识在设备详情页的端口列表里逐条修改或者用批量导入功能从CSV导入。例如把连接公司出口防火墙上联口的描述改成出口防火墙-上联口把连接核心交换机的端口描述改成核心交换机-互联口排查链路故障时一眼就能定位。4.4 邮件告警模板中的中文字符编码告警是监控系统的灵魂。LibreNMS配置邮件告警时SMTP服务器、发件人、收件人邮箱都好填但中文字符用于邮件主题和正文时偶尔会遇到乱码。这个问题的根源是邮件编码不匹配。在配置告警模板时确保模板文件保存为UTF-8编码同时把Alerting - Mail配置里的字符集选为UTF-8。SMTP服务器那边一般不用特殊处理主流邮件服务器都默认支持UTF-8。5. 常见问题排查部署和运行阶段的高频坑5.1 数据库连接失败大多数新手都卡在这一步现象是Web安装向导第一步就报错提示SQLSTATE[HY000] [2002] Connection refused。遇到这个报错优先检查三处第一compose服务名是否写对。在容器里的LibreNMS应用连数据库时主机名必须是db而不是localhost或127.0.0.1。用localhost会导致尝试连接容器内部的MySQL而容器里根本没有MySQL进程。第二数据库容器是否正常启动。执行docker compose ps查看db服务的状态如果显示Restarting大概率是数据库初始化失败。用docker compose logs db查看日志常见原因包括数据目录权限不对、密码设置不符合MariaDB安全策略等。第三数据库用户和密码是否匹配。LibreNMS安装向导填写的用户名密码必须是docker-compose.yml里MYSQL_USER和MYSQL_PASSWORD对应的值不是MYSQL_ROOT_PASSWORD。root账号在容器里默认只允许从localhost连接不能用于跨容器访问。5.2 Web界面默认账号密码拜了个拜你应该这么做第一次打开LibreNMS时不要浪费时间去猜默认密码。LibreNMS没有默认账号安装向导最后一步会让你创建管理员用户和密码。如果安装过程中断导致账号没创建成功可以进入容器用命令重新初始化docker exec -it librenms_app sh php /opt/librenms/scripts/auth/adduser.php admin 你的密码 10这条命令会创建用户名为admin、权限等级10管理员权限的账号。10是LibreNMS中的管理员级别等级越高权限越大。5.3 设备添加不上SNMP探测失败排查思路添加设备是LibreNMS的核心操作。在Devices - Add Device页面填入网络设备的IP如果提示SNMP探测失败按这个顺序排查先确认网络设备的SNMP是否已开启命令验证一下snmpwalk -v2c -c public 192.168.1.1 sysDescrpublic是设备上的SNMP读团体字符串实际环境要换成你自己配置的值。snmpwalk命令在宿主机上如果没装可以进容器里执行。再确认网络设备是否允许来自LibreNMS容器IP的SNMP请求。很多交换机默认只允许特定管理网段访问SNMP你在设备ACL里要放行监控服务器的IP。这里有个坑Docker容器的IP是动态的重启容器后IP可能变化导致授权失效。稳妥的做法是在docker-compose.yml里给容器配置固定IP或者在网络设备的SNMP ACL里放行整个网段。最后确认防火墙端口。SNMP协议的基础端口是UDP 161确保宿主机和容器间的网络策略没阻断这个端口。5.4 流量图全为空采集链路断在哪了界面正常、设备显示在线但流量图一片空白这是运维朋友问得最多的问题。流量采集依赖RRDTool数据文件一般存在/data/rrd目录。排查思路有三步第一步确认设备的流量数据是否被采集。在设备详情页点击Polling标签手动触发一次轮询观察返回结果。如果显示SNMP timeout之类的错误说明网络设备侧响应超时需要检查SNMP版本、超时时间配置。默认SNMP超时时间是1秒较慢的设备可以适当调大到3秒。第二步确认RRD文件是否生成。进入容器查看/data/rrd/主机名/目录看有没有.rrd后缀的文件。如果没有说明采集任务压根没执行回到上面说的定时任务排查。第三步确认图表渲染依赖的PHP模块。一般镜像内置完整如果是基于官方镜像修改过的自定义镜像缺了php-rrd扩展就会导致图表生成失败。执行php -m | grep rrd确认。5.5 磁盘和内存占用越来越高用Docker跑LibreNMS容器log文件会持续收集数据如果监控的设备量大磁盘占用增长很快。我遇到过跑两个月后磁盘撑满的情况。除了定时清理过期的RRD文件外还要注意Docker本身的日志管理。默认情况下容器日志是无限增长的需要配置logrotate或者Docker的json-file日志驱动对日志做大小限制。在docker-compose.yml的librenms服务下加一段logging: driver: json-file options: max-size: 50m max-file: 3这样单个容器日志最多占用150MB避免日志文件无限制增长导致磁盘告警。5.6 主机名解析导致性能下降我用LibreNMS监控了几百台设备后发现一个有意思的问题设备轮询变慢、页面加载迟钝。排查定位到DNS解析——LibreNMS在轮询时会尝试反向解析IP为主机名。如果内部网络没有配置反向DNS每次轮询都要等DNS超时才能继续。解决方式是关闭反查或者优化DNS配置。在Settings - General - Device settings里把Force IP to hostname lookup关闭或者在/etc/hosts里把监控设备的主机名和IP手动映射。实测这个改动让轮询时间从几十秒降到了几秒效果立竿见影。6. 用顺手之后我建议你重点使用的几个能力LibreNMS不只是画流量图的工具它是一套完整的网络运维平台。部署完成后我建议优先体验这几个核心能力。告警规则配置在Alerts - Rules里可以创建基于阈值条件的告警。比如端口利用率超过80%触发告警、设备Ping不通触发告警、温度传感器超限触发告警。规则可以用CLI表达式写逻辑类似%ports.ifInOctets_rate / %ports.ifSpeed * 100 80这样的条件组合触发后会通过邮件、Telegram、Slack等多种渠道通知。我的日常运维基本靠这套告警网线断了、光模块劣化、带宽打满都靠它第一时间感知。自动发现功能在Settings - Network - Autodiscovery里配置IP地址段后LibreNMS会自动扫描并识别SNMP可达的设备自动添加并采集数据。扫描机制包括底层发现、ARP发现、路由发现多种模式。对于几百台设备的园区网络手动逐台添加不现实自动发现是刚需。多用户权限管理LibreNMS支持细粒度的用户权限控制。可以给合作伙伴只读账号、给一线网工分配特定设备组的操作权限、给领导分配汇总仪表盘视图。这些在User Management里都能配置避免了所有运维人共用一套admin账号的安全隐患。API接口集成LibreNMS提供了完整的REST API可以很方便地把监控数据集成到自己的运维平台或者工单系统。比如每天早上自动拉取所有设备的告警汇总生成日报发到内部群或者当新设备上线时通过API自动注册到CMDB系统。7. 一点自己的心得体会从第一次部署LibreNMS到现在我用它监控过的设备种类包括核心交换机、路由器、防火墙、无线控制器、服务器、UPS电源加起来超过五百台。这套Docker部署方式陪着我从测试环境走到了生产环境最大的体会是监控方案不是越复杂越好可维护性和可扩展性往往比功能数量更重要。如果在部署过程中遇到问题我的建议是别急着到处乱查先看日志。docker compose logs是第一个该执行的命令九成问题都能在日志里找到线索。其次是根据报错信息搜索官方GitHub的Issue区相当多的问题官方已经给出了答案。最后一个小技巧docker compose的编排文件如果每次都要手敲很容易出错建议保存一份模板以后部署别的应用改改基础配置就能复用。我自己就是一套模板同时管着LibreNMS、Grafana、Zabbix三套监控系统迁移服务器的时候直接把整个目录打包带走到新机器上解压、执行docker compose up -d监控系统就原地复活了。这种便利性就是Docker生态最吸引人的地方。