Ubuntu 22.04 安装 LibreNMS 26.10.0 指南

目标：在一台全新 Ubuntu 22.04 服务器上，从系统依赖到首台设备出数据，完整安装 LibreNMS 26.10.0（nginx + PHP-FPM 8.5 + MariaDB + snmpd 自监控 + 调度器定时任务），并以 validate.php 全部 OK 作为收尾验证。本文全部命令与回显均在 Ubuntu 22.04 实测环境逐条执行采集，路径为标准布局 /opt/librenms。

一、环境信息

本文在以下环境实测通过，关键版本与路径汇总如下，供复现时对照：

操作系统：Ubuntu 22.04.5 LTS（x86_64），主机名 librenms-server
LibreNMS：26.10.0（2026-10-19 官方发布，代码位于 /opt/librenms）
PHP：8.5.11（来自 Sury/ondrej PPA，fpm + cli 双 SAPI）
数据库：MariaDB 10.6.23（Ubuntu 22.04 官方源版本，库名 librenms）
Web 服务器：nginx 1.18.0（Ubuntu 官方源 nginx-full）
RRDTool：1.7.2；SNMP：net-snmp 5.9.1；Python：3.10.12；Composer：2.10.3
数据库 Schema 版本：2026_10_09_000000_reset_invalid_alert_schedule_behavior (408)（以 validate.php 实测输出为准）
时区：Asia/Shanghai（系统 + PHP 双侧一致）
监听端口：80（Web，HTTP）；161/UDP（本机 snmpd，仅自监控用）
管理员账号：admin / Adm1n@LibreNMS26（⚠️ 见第八章 8.2：LibreNMS 会拒绝常见弱口令，q1w2e3r4 实测被拒）

安装完成后涉及的服务组件与托管方式：

组件	服务/单元	托管方式	作用
MariaDB	`mariadb.service`	systemd	存储设备、端口、告警等结构化数据
PHP-FPM 8.5	`php8.5-fpm.service`	systemd	运行 Web 与 CLI（池 `librenms`，Unix socket）
nginx	`nginx.service`	systemd	Web 前端反代到 PHP-FPM
snmpd	`snmpd.service`	systemd	监控服务器自身（自监控第一台设备）
cron	`cron.service`	systemd	按秒级计划触发轮询/发现/告警脚本
调度器	`librenms-scheduler.timer` + `librenms-scheduler.service`	systemd	驱动 Laravel schedule（分钟级任务）

二、前置条件

安装前请确认以下事项，缺一项都会在后续步骤卡住：

一台全新 Ubuntu 22.04 服务器（物理机或云主机均可），拥有 root 权限或可 sudo 的账号；本文以 root 直接执行。
服务器可访问公网（apt 源、GitHub、packagist.org）。若需经代理出网，先导出会话级代理变量（后续 composer/pip 等命令才能联通）：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897

⚠️ 注意：cron 默认只继承极少量环境变量。若整台服务器必须走代理出网，除导出变量外，还需在完成安装后把代理配置写入 /opt/librenms/config.php（见第七章 7.3），否则每日自动更新与外部告警通道会失败。

时钟准确：LibreNMS 对时间敏感（轮询频率、告警判定、MySQL/PHP 时间一致性校验），先完成时间同步与时区设置（4.6 节）。
端口规划：Web 用 80/443；若防火墙启用需放行（Ubuntu 22.04 默认 ufw 未启用，无需操作；已启用者执行 ufw allow 80,443/tcp）。
监控目标侧：被监控设备需开启 SNMP（v2c/v3）。本机自监控由本机 snmpd 承担，无需外部设备即可完成全部验证。

三、版本选型说明

LibreNMS 采用年月滚动版本号（YY.MM），没有传统意义的 LTS。版本基准实查于官方 GitHub Releases（https://github.com/librenms/librenms/releases.atom，查询日期 2026-10-20）：

最新稳定版：26.10.0，发布时间 2026-10-19T12:41:01Z；上一稳定版为 26.9.1/26.9.1.1（2026-09-21/22）。
官方安装文档已明确各发行版推荐 PHP 版本；validate.php 实测提示：2026 年 10 月起最低支持 PHP 8.4，建议 8.5（原文见第八章 8.1）。Ubuntu 22.04 官方源最高只有 PHP 8.1，必须通过 Sury（ondrej/php PPA）获取 8.5。

本篇实测各组件版本与来源：

组件	实测版本	来源	说明
LibreNMS	26.10.0	GitHub（git clone / tag）	主程序，含 Web、CLI、轮询器
PHP	8.5.11	Sury PPA php8.5-*	满足 2026-10 起最低 8.4、建议 8.5
MariaDB	10.6.23	Ubuntu 22.04 官方源	满足官方最低要求，无需第三方源
nginx	1.18.0	Ubuntu 22.04 官方源 nginx-full	官方文档同款 Web 服务器
rrdtool	1.7.2	Ubuntu 22.04 官方源	时序绘图数据文件引擎
net-snmp	5.9.1	Ubuntu 22.04 官方源	snmpd/snmpwalk
Python	3.10.12	Ubuntu 22.04 官方源	poller-wrapper 等脚本运行时
Composer	2.10.3	getcomposer.org 官方 phar	PHP 依赖管理

关键差异与如何选：操作系统版本决定 PHP 获取方式——Ubuntu 22.04 走 Sury PPA（本文），Ubuntu 24.04/26.04 可用系统源新 PHP；数据库在 MariaDB 10.6 与 MySQL 8 之间无强偏好，但 MariaDB 在 Ubuntu 上开箱即用且为官方文档主线，本文按官方推荐采用 MariaDB。LibreNMS 版本按「最新稳定版跟随」策略安装，后续依赖 daily.sh 滚动更新（详见方案 A）。

四、方案 A：Git 在线安装（官方推荐）

本方案是官方文档的标准路径：git 拉取主程序 + composer 装 PHP 依赖 + 手工完成数据库/Web/调度器配置。全程约 15–30 分钟（视网络而定），完成后即为一台可长期运行、可自动更新的监控服务器。

4.1 安装系统依赖

先加装 Sury PHP 仓库（Ubuntu 22.04 必须，原因见第三章），再一次性装齐系统依赖：

apt update
apt install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
apt update
apt install -y acl curl fping git mariadb-client mariadb-server mtr-tiny nginx-full nmap php8.5-cli php8.5-curl php8.5-fpm php8.5-gd php8.5-gmp php8.5-mbstring php8.5-mysql php8.5-snmp php8.5-xml php8.5-zip rrdtool snmp snmpd whois python3-pymysql python3-dotenv python3-redis python3-setuptools python3-systemd python3-pip unzip cron

实测依赖装完后的关键版本回显：

$ php8.5 -v
PHP 8.5.11 (cli) (built: Sep 24 2026 13:49:08) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.5.11, Copyright (c) Zend Technologies

$ mariadb --version
mariadb  Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

$ nginx -v
nginx version: nginx/1.18.0 (Ubuntu)

💡 说明：Ubuntu 22.04 官方源 PHP 最高 8.1，而 LibreNMS 自 2026-10 起最低要求 PHP 8.4（validate.php 实测原文见 8.1），因此 add-apt-repository ppa:ondrej/php 是 22.04 上的必做步骤；Ubuntu 24.04/26.04 可直接使用系统源 PHP。

4.2 创建 librenms 系统用户

LibreNMS 以专用系统账号运行（轮询、调度均以该用户身份执行），创建时不建主目录（-M，主目录由程序目录兼任）、以 -r 建为系统用户：

useradd librenms -d /opt/librenms -M -r -s "$(which bash)"

验证用户已创建：

$ getent passwd librenms
librenms:x:999:999::/opt/librenms:/usr/bin/bash

4.3 下载 LibreNMS 源码

官方推荐克隆 master 分支（LibreNMS 为滚动发布，master 即当前稳定线）。克隆到 /opt/librenms：

cd /opt
git clone https://github.com/librenms/librenms.git

实测回显（17273 个文件，约 1 分钟，视带宽）：

Cloning into 'librenms'...
Updating files: 100% (17273/17273), done.

4.4 设置目录权限

程序目录归 librenms 用户所有；同时用 ACL 让 Web 组可写运行时目录（rrd、logs、缓存、storage），这是 Web 界面能正常读写的前提：

chown -R librenms:librenms /opt/librenms
chmod 771 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/

4.5 安装 PHP 依赖（composer）

官方提供两种装法：包装脚本（composer_wrapper.php）或全局安装 composer 后直接执行。若服务器经代理出网，包装脚本会失败（官方文档明确注明），此时用手动方式。为通用起见，本文采用手动全局安装：

curl -s https://getcomposer.org/composer-stable.phar -o /usr/bin/composer
chmod +x /usr/bin/composer
composer --version

实测回显：

Composer version 2.10.3 2026-08-27 13:34:23

以 librenms 用户身份安装 PHP 依赖（首次运行会下载数百个包，约 2–5 分钟）：

su - librenms
composer install --no-dev
exit

实测回显节选（实测首尾）：

$ composer install --no-dev
Installing dependencies from lock file (including requiring packages section)
Package operations: 184 installs, 0 updates, 0 removals
  - Installing symfony/polyfill-php85 (v1.35.0): Extracting archive
  ...（中略数百行 Installing xxx）...
  - Installing symfony/yaml (v7.4.20): Extracting archive
  - Installing tightenco/ziggy (v2.6.4): Extracting archive
Generating optimized autoload files
   INFO  Discovering packages.
74 packages you are using are looking for funding.
> @php artisan config:clear
   INFO  Configuration cache cleared successfully.

4.6 设置时区

PHP 的 fpm 与 cli 两个 SAPI 都要设置 date.timezone（否则 Web 与命令行时间不一致，validate.php 会报 MySQL and PHP time mismatch）。编辑以下两个文件，把 ;date.timezone 一行改为：

date.timezone = Asia/Shanghai

vi /etc/php/8.5/fpm/php.ini
vi /etc/php/8.5/cli/php.ini

系统时区一并设置并验证：

timedatectl set-timezone Asia/Shanghai

实测回显：

$ timedatectl | head -3
               Local time: Tue 2026-10-20 05:18:07 CST
           Universal time: Mon 2026-10-19 21:18:07 UTC
                 RTC time: n/a

4.7 配置 MariaDB

先加两行必需参数（LibreNMS 的表结构与查询依赖这两项），编辑 /etc/mysql/mariadb.conf.d/50-server.cnf，在 [mysqld] 节内添加：

[mysqld]
innodb_file_per_table=1
lower_case_table_names=0

⚠️ 注意：节名按实际文件为准。Ubuntu 22.04 的 50-server.cnf 使用 [mysqld]（实测）；较新版本的 MariaDB 包使用 [mariadbd]，以 grep -n "^\[" /etc/mysql/mariadb.conf.d/50-server.cnf 输出为准，参数加错节名不会生效。

启用并重启 MariaDB：

systemctl enable mariadb
systemctl restart mariadb

实测回显：

$ systemctl is-active mariadb
active

建库并授权（把 q1w2e3r4 换成你的实际密码；示例密码仅演示用）：

mysql -u root

CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit

验证建库结果：

$ mysql -u root -e "SHOW DATABASES;"
+--------------------+
| Database           |
+--------------------+
| librenms           |
| mysql              |
| performance_schema |
| sys                |
+--------------------+

4.8 配置 PHP-FPM 池

为 LibreNMS 建独立 FPM 池（不复用默认 www 池），复制默认池配置后改四处：池名、运行用户、运行组、监听 socket：

cp /etc/php/8.5/fpm/pool.d/www.conf /etc/php/8.5/fpm/pool.d/librenms.conf
vi /etc/php/8.5/fpm/pool.d/librenms.conf

把 [www] 改为 [librenms]，user/group 改为 librenms，listen 改为独立 socket 路径：

[librenms]
user = librenms
group = librenms
listen = /run/php-fpm-librenms.sock

本机如无其他 PHP 应用，可删除 www 池节省资源（本文实测删除）：

rm /etc/php/8.5/fpm/pool.d/www.conf
systemctl restart php8.5-fpm

验证服务与 socket：

$ systemctl is-active php8.5-fpm
active
$ ls -l /run/php-fpm-librenms.sock
srw-rw---- 1 www-data www-data 0 Oct 20 05:18 /run/php-fpm-librenms.sock

4.9 配置 nginx

创建站点配置 /etc/nginx/conf.d/librenms.conf，server_name 按你的域名或 IP 修改：

server {
 listen      80;
 server_name librenms.example.com;
 root        /opt/librenms/html;
 index       index.php;

 charset utf-8;
 gzip on;
 gzip_types text/css application/javascript text/javascript application/x-javascript image/svg+xml text/plain text/xsd text/xsl text/xml image/x-icon;
 location / {
  try_files $uri $uri/ /index.php?$query_string;
 }
 location ~ [^/]\.php(/|$) {
  fastcgi_pass unix:/run/php-fpm-librenms.sock;
  fastcgi_split_path_info ^(.+\.php)(/.+)$;
  include fastcgi.conf;
 }
 location ~ /\.(?!well-known).* {
  deny all;
 }
}

删除默认站点并重启 nginx：

rm -f /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default
nginx -t
systemctl restart nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

$ systemctl is-active nginx
active

验证 Web 已能响应（未初始化完成前跳转登录页属正常）：

$ curl -s -o /dev/null -w "HTTP %{http_code} redirect=%{redirect_url}\n" http://localhost/
HTTP 302 redirect=http://localhost/login

4.10 写入数据库连接配置

LibreNMS 的运行时配置主体是 /opt/librenms/.env（安装依赖时已自动生成，内含 APP_KEY 等自动值），把其中默认注释掉的四个数据库项改为实际值：

DB_HOST=localhost
DB_DATABASE=librenms
DB_USERNAME=librenms
DB_PASSWORD=q1w2e3r4

vi /opt/librenms/.env

💡 说明：.env 中还可能有 INSTALL=true 一行（标记"安装向导未完成"）。用命令行方式完成初始化时，建好管理员账号后应删除该行，Web 端才会正常进入登录页而非安装向导（见 4.12）。官方 Web 安装器（访问 http://<服务器>/install）会在完成时自动处理 .env 与配置文件，两种方式任选其一。

4.11 执行数据库迁移

以 librenms 用户执行迁移，创建全部数据表（数百张，输出较长，节选首尾）：

su - librenms
php lnms migrate --force --no-ansi

实测回显节选（实测首尾）：

  2018_07_03_091314_create_access_points_table ..................... 12.34ms DONE
  ...（中略数百行迁移记录）...
  2026_09_16_120000_widen_ent_physical_rev_columns ................ 5.10ms DONE
  2026_09_26_000000_drop_unused_device_columns .................... 6.44ms DONE
  2026_10_07_000000_create_jobs_table ............................ 4.22ms DONE
  2026_10_07_000001_create_failed_jobs_table ..................... 3.95ms DONE
  2026_10_09_000000_reset_invalid_alert_schedule_behavior ........ 0.42ms DONE

⚠️ 注意：命令必须以 librenms 用户在 /opt/librenms 内执行（su - librenms 带连字符会自动落到 /opt/librenms 主目录）。用 root 或在错误目录执行会报 Could not open input file 或权限错误（实测案例见 8.5）。

4.12 创建管理员账号

用 lnms user:add 创建管理员（--role=admin 授予管理员角色）：

su - librenms
php lnms user:add admin --password='Adm1n@LibreNMS26' --role=admin --email=admin@example.com --full-name="LibreNMS Admin"

实测回显：

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

若使用 admin、q1w2e3r4 等常见弱口令，会收到实测如下的拒绝提示（LibreNMS 内置弱口令校验，改用强口令即可）：

$ php lnms user:add admin --password=q1w2e3r4 --role=admin
The given password has appeared in a data leak. Please choose a different password.

删除 .env 中的 INSTALL=true 行（如存在），然后验证 Web 登录页可访问：

sed -i '/^INSTALL=true/d' /opt/librenms/.env

$ curl -s -o /dev/null -w "GET /login -> %{http_code}\n" http://localhost/login
GET /login -> 200

4.13 配置定时任务与调度器

轮询、发现、告警由两套机制驱动：cron 文件（分钟级脚本入口）+ systemd 调度器（Laravel schedule）。三步完成托管：

cp /opt/librenms/dist/librenms.cron /etc/cron.d/librenms
cp /opt/librenms/dist/librenms-scheduler.service /opt/librenms/dist/librenms-scheduler.timer /etc/systemd/system/
systemctl daemon-reload
systemctl enable librenms-scheduler.timer
systemctl start librenms-scheduler.timer

实测回显：

Created symlink /etc/systemd/system/timers.target.wants/librenms-scheduler.timer → /etc/systemd/system/librenms-scheduler.timer.

$ systemctl is-active librenms-scheduler.timer
active

cron 文件内容节选（实测首部，可见轮询/发现/告警的触发频率）：

33   */6  * * *   librenms    /opt/librenms/cronic /opt/librenms/discovery-wrapper.py 1
*/5  *    * * *   librenms    /opt/librenms/lnms device:discover new >> /dev/null 2>&1

*/5  *    * * *   librenms    /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16
*    *    * * *   librenms    /opt/librenms/alerts.php >> /dev/null 2>&1

再启用日志轮转（/opt/librenms/logs 会持续增长），并为 lnms 命令建立全局软链接与 Tab 补全：

cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
ln -s /opt/librenms/lnms /usr/bin/lnms
cp /opt/librenms/misc/lnms-completion.bash /etc/bash_completion.d/

4.14 配置 snmpd 自监控

把服务器自身作为第一台监控设备（SNMP v2c），用官方示例配置起步：

cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf

把示例中的 RANDOMSTRINGGOESHERE 替换为你的 community（本文用 librenms-community）：

com2sec readonly  default         librenms-community

下载官方 distro 探测脚本（用于识别发行版/内核），启用并重启 snmpd：

curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd

用 snmpwalk 验证本机 SNMP 可读（返回真实系统信息即成功）：

$ snmpwalk -v 2c -c librenms-community localhost .1.3.6.1.2.1.1.1
iso.3.6.1.2.1.1.1.0 = STRING: "Linux librenms-server 6.8.0-138-generic #138~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Fri Aug  7 13:43:15 UTC  x86_64"

$ snmpwalk -v 2c -c librenms-community localhost .1.3.6.1.2.1.1.5
iso.3.6.1.2.1.1.5.0 = STRING: "librenms-server"

4.15 添加首台设备并验证出数

把 localhost 加入监控（-2 表示 SNMP v2c，-c 指定 community，与 4.14 一致）：

su - librenms
php lnms device:add localhost -2 -c librenms-community

实测回显：

Added device localhost (1)

执行首轮单设备轮询（-r -f 为跳过外部输出通道的快速模式，输出末尾给出各子系统耗时统计）：

php poller.php -h localhost -r -f

实测回显节选（实测尾部）：

>>> Polled localhost (1) in 1.332 seconds <<<
INFO: device:poll localhost (1) polled in 1.332s
#### Start Alerts ####
#### End Alerts (0.0049s) ####

### Start Device Groups ###
### End Device Groups (0.0008s) ###

FPING [1/1.00s]: Ping[1/1.00s]
SNMP [19/0.20s]: Snmpget[16/0.17s] Snmpwalk[3/0.03s]
SQL [135/0.04s]: Select[51/0.02s] Insert[62/0.02s] Delete[16/0.00s] Update[6/0.00s]
RRD [144/0.05s]: Create[72/0.04s] Update[72/0.01s]

⚠️ 注意：poller.php 在新版中已标记废弃（运行时会打印 Warning: poller.php is deprecated! Use lnms device:poll instead.），日常等价命令为 php lnms device:poll localhost，两者输出一致。

验证 RRD 数据文件已生成（/opt/librenms/rrd/localhost/，节选）：

$ ls /opt/librenms/rrd/localhost/ | head -6
availability-2592000.rrd
availability-31536000.rrd
availability-604800.rrd
availability-86400.rrd
hr_processes.rrd
hr_users.rrd

验证 Web 登录（用 4.12 的管理员账号）：

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

浏览器访问 http://<服务器IP>/，用 admin 登录即可看到 Overview 仪表盘与 localhost 设备数据。

4.16 validate.php 最终验证

官方定义的安装健康检查：以 librenms 用户执行，全部 OK 即安装完成：

su - librenms
php validate.php

实测完整回显：

===========================================
Component | Version
--------- | -------
LibreNMS  | 26.10.0 (2026-10-19T20:41:01+08:00)
DB Schema | 2026_10_09_000000_reset_invalid_alert_schedule_behavior (408)
PHP       | 8.5.11
Python    | 3.10.12
Database  | MariaDB 10.6.23-MariaDB-0ubuntu0.22.04.1
RRDTool   | 1.7.2
SNMP      | 5.9.1
===========================================

[OK]    Composer Version: 2.10.3
[OK]    Dependencies up-to-date.
[OK]    Database Connected
[OK]    Database Schema is current
[OK]    SQL Server meets minimum requirements
[OK]    lower_case_table_names is enabled
[OK]    MySQL engine is optimal
[OK]    Database and column collations are correct
[OK]    Database schema correct
[OK]    MySQL and PHP time match
[OK]    Active pollers found
[OK]    Dispatcher Service not detected
[OK]    Locks are functional
[OK]    Python poller wrapper is polling
[OK]    Redis is unavailable
[OK]    No errors found with polling frequencies.
[OK]    rrd_dir is writable
[OK]    rrdtool version ok

💡 说明：「Dispatcher Service not detected」与「Redis is unavailable」为 OK 态提示，不是故障——Dispatcher（集中式轮询调度进程）与 Redis 是分布式/大规模部署的可选组件，单机部署用 cron + poller-wrapper 即可（相关内容见《LibreNMS 26.10.0 常用 CLI 命令与工具详解》）。

五、方案 B：固定版本安装（tag 检出）

方案 A 跟随 master 滚动更新，适合"保持最新"的监控平台；若你受变更管控要求锁定版本（如只允许 26.10.0），改用 tag 检出。本方案与方案 A 仅 4.3 下载一步不同，其余步骤完全一致（已实测可正常完成安装与出数）。

5.1 下载固定版本源码

cd /opt
git clone --branch 26.10.0 --depth 1 https://github.com/librenms/librenms.git

--branch 直接检出 26.10.0 标签，--depth 1 只拉当前快照（仓库全量历史较大，浅克隆显著提速）。

5.2 已知副作用与修复

tag 检出后 git 处于 detached HEAD 状态，validate.php 会实测给出如下提醒（不影响功能）：

[WARN]  Your local git branch is not master, this will prevent automatic updates.
        [FIX]:
        You can switch back to master with git checkout master

从当前标签创建本地 master 分支即可消除该提醒（实测通过，版本保持 26.10.0）：

cd /opt/librenms
su librenms -c "git checkout -b master"

实测回显：

Switched to a new branch 'master'

💡 说明：建立本地 master 后，后续 daily.sh 会尝试拉取官方 master 滚动更新，版本可能越过 26.10.0。若要长期锁版本，需关闭自动更新（在 /opt/librenms/config.php 中加 $config['update'] = 0;），升级改为手工执行（见第七章 7.2）。

六、多方案对比与选择建议

维度	方案 A：master 在线安装	方案 B：tag 固定版本安装
获取方式	`git clone`（master 分支）	`git clone --branch <tag> --depth 1`
版本形态	滚动稳定线（当前即 26.10.0）	锁定 26.10.0 快照
日常更新	`daily.sh` 自动更新（默认开启）	需手工升级或关闭自动更新
validate.php 提示	无分支警告	初始有 branch not master 警告（可修复）
适用场景	通用生产监控平台	变更管控/内网审计要求锁版本
复杂度	低（官方默认路径）	低（仅下载步骤不同）

选择建议：可联网的通用服务器直接用方案 A（官方默认、支持自动更新）；有版本变更管控要求的团队用方案 B 起步，并配合关闭 $config['update']；两种方案共享同一套系统依赖与配置步骤，切换成本只有一次 git 操作。

七、配置说明

7.1 运行时配置文件位置

/opt/librenms/.env：主配置（数据库连接、APP_KEY、VAPID 密钥等）。改完数据库相关项后无需重启（CLI 每次新进程生效；Web 端可执行 php lnms config:clear 清配置缓存）。
/opt/librenms/config.php：可选的覆盖式配置（PHP 数组形式）。安装器未创建时按需自建（参考同目录 config.php.default 的注释模板），常用项：$config['snmp']['community']（默认探测团体字）、$config['base_url']、$config['update']（0 关闭每日自动更新）。创建后修正属主：
```
chown librenms:librenms /opt/librenms/config.php
```
运行时数据目录：/opt/librenms/rrd/（性能数据）、/opt/librenms/logs/（日志）、/opt/librenms/bootstrap/cache/ 与 /opt/librenms/storage/（框架缓存）。

7.2 日常更新与升级

滚动更新由 cron 中的 daily.sh 承担（每天自动执行更新、清理、维护）。手工执行一次完整维护的实测回显：

$ su - librenms
$ bash daily.sh
Clearing caches                                    OK
Updating to latest codebase                        OK
Updating Composer packages                         OK
Updating SQL-Schema                                OK
Cleaning up DB                                     OK

更新失败时先查网络与代理（见 7.3），再查看 /opt/librenms/logs/daily.log。

7.3 代理支持（按需）

整机走代理的环境，在 /opt/librenms/config.php 中加入（hostname:port 按实际填写）：

$config['callback_proxy'] = "192.168.1.62:7897";

cron 环境不继承 shell 的 http_proxy，Web 界面的更新检查同样读该配置，务必落盘而非只在 shell 导出。

7.4 防火墙

Ubuntu 22.04 默认未启用 ufw，无需操作。已启用环境放行 Web 端口：

ufw allow 80,443/tcp

八、常见问题（FAQ）

Q1：validate.php 提示 PHP 版本不再受支持怎么办？

实测现象：PHP 8.3 环境下 validate 输出：

[WARN]  PHP version 8.4 is the minimum supported version as of October, 2026. We recommend you update PHP to a supported version (8.5 suggested) to continue to receive updates. If you do not update PHP, LibreNMS will continue to function but stop receiving bug fixes and updates.

解决：升级到 Sury 源的 php8.5 全家桶（apt install php8.5-cli php8.5-curl php8.5-fpm ...），把 FPM 池与 php.ini 的 timezone 配置在 /etc/php/8.5/ 下重做一遍，systemctl restart php8.5-fpm 后 validate 恢复 OK（实测升级后显示 PHP 8.5.11，警告消失）。

Q2：lnms user:add 报 "The given password has appeared in a data leak."

实测现象见 4.12。原因：LibreNMS 内置弱口令校验，q1w2e3r4 等高频口令会被直接拒绝。解决：改用强口令（大小写+数字+符号，≥12 位）。这也是本文示例口令为 Adm1n@LibreNMS26 的原因。

Q3：validate.php 报 "The poller is not running" / "No python wrapper pollers found" / Python 模块缺失

实测现象（PHP 依赖装完、cron 已配但未跑过轮询时）：

[FAIL]  The poller is not running. No poller ran in the last 300 seconds.
[FAIL]  No python wrapper pollers found
[FAIL]  Python3 module issue found: 'Required packages: ['PyMySQL!=1.0.0', 'python-dotenv', 'redis>=4.0', 'setuptools', 'psutil>=5.9.6', 'command_runner>=1.3.0']
Package not found: The 'command_runner>=1.3.0' distribution was not found and is required by the application'
        [FIX]:
        pip3 install -r /opt/librenms/requirements.txt

定位与解决（三步，全部实测）：

补齐 Python 依赖：pip3 install -r /opt/librenms/requirements.txt（走代理环境加 -i 国内源或导出 https_proxy；实测安装了 command_runner-1.7.6 psutil-7.2.2 redis-8.1.0 等）。

手动触发一次 wrapper 轮询确认链路：su - librenms 后 python3 poller-wrapper.py 16，实测输出：

2026-10-20 05:21:25,062 :: INFO :: starting the poller check at 2026-10-20 05:21:25 with 1 threads for 1 devices
2026-10-20 05:21:26,554 :: INFO :: worker Thread-2 (poll_worker) finished device 1 in 1 seconds
2026-10-20 05:21:26,554 :: INFO :: poller-wrapper checked 1 devices in 1 seconds with 1 workers with 0 errors

生产环境由 cron 每 5 分钟自动跑 poller-wrapper.py 16（见 4.13），后续 validate 恒为 [OK] Active pollers found / [OK] Python poller wrapper is polling。

Q4：validate.php 报 "Scheduler is not running"

实测现象（timer 未配置时）：

[FAIL]  Scheduler is not running
        [FIX]:
        sudo cp /opt/librenms/dist/librenms-scheduler.service /opt/librenms/dist/librenms-scheduler.timer /etc/systemd/system/
        sudo systemctl enable librenms-scheduler.timer
        sudo systemctl start librenms-scheduler.timer

解决：按提示执行三步（即 4.13 的调度器托管），systemctl list-timers | grep librenms 能看到调度器行即恢复。

Q5：以 root 执行 validate.php 报 "Could not open input file: validate.php"

实测现象：root 在家目录执行 su librenms -c "php validate.php" 时报 Could not open input file: validate.php。原因：不带连字符的 su librenms 不切换工作目录/环境，当前目录不在 /opt/librenms。解决：统一用 su - librenms（带连字符），或先 cd /opt/librenms。

Q6：MariaDB 参数加到 [mariadbd] 节不生效

Ubuntu 22.04 的 /etc/mysql/mariadb.conf.d/50-server.cnf 实测只有 [mysqld] 节（grep -n "^\[" 可验证），参数写在 [mariadbd] 下不生效。validate.php 会报 lower_case_table_names is enabled 失败，改写到实际存在的节并 systemctl restart mariadb 即可。

Q7：代理环境下 composer_wrapper 失败

官方文档明确注明：经代理上网时 composer_wrapper.php 可能失败。解决（实测通过）：手动全局安装 composer（4.5 的 curl phar 方式）后直接 composer install --no-dev。

九、卸载与清理

按依赖顺序完整卸载（数据库数据不可恢复，请先确认）：

systemctl disable --now librenms-scheduler.timer
rm -f /etc/systemd/system/librenms-scheduler.service /etc/systemd/system/librenms-scheduler.timer
systemctl daemon-reload
rm -f /etc/cron.d/librenms /etc/logrotate.d/librenms /etc/nginx/conf.d/librenms.conf /etc/php/8.5/fpm/pool.d/librenms.conf
systemctl disable --now snmpd nginx php8.5-fpm
mysql -u root -e "DROP DATABASE librenms; DROP USER 'librenms'@'localhost';"
userdel librenms
rm -rf /opt/librenms

如需回滚系统依赖（一般不必）：apt purge php8.5-* mariadb-server nginx-full rrdtool snmp snmpd && apt autoremove。

十、参考链接

LibreNMS 官方安装文档（含 Ubuntu 24.04/26.04、Debian、RHEL 分支）：https://docs.librenms.org/Installation/Install-LibreNMS/
官方 GitHub 仓库与 Releases：https://github.com/librenms/librenms
26.10.0 发布页：https://github.com/librenms/librenms/releases/tag/26.10.0
Composer 官方下载：https://getcomposer.org/download/
Sury PHP 仓库：https://github.com/oerdnj/deb.sury.org
LibreNMS Dispatcher 服务（分布式部署）：https://docs.librenms.org/Support/Dispatcher-Service/
官方配置文档：https://docs.librenms.org/Support/Configuration/