1. 项目逻辑与前期规划
1.1 标题里的“装置配置”到底说的是什么
先纠正一个小笔误：标题里写的“装置配置”，结合项目场景来看，指的其实是“安装配置”。Zabbix Agent 在 Linux 平台上的安装配合，是所有基于 Zabbix 做监控的同学必经的一步。Zabbix 的监控体系是由服务端（Zabbix Server）、数据库、Web 前端以及被监控端上运行的 Agent 组成，Agent 的核心职责是：把一台 Linux 主机的 CPU、内存、磁盘、网络流量、进程状态等指标采集起来，再交给 Server 端统一汇总和告警。
“诺禾”这个代号，你可以理解成我们某个内部监控专项的代号。这个项目的核心就是给一批 Linux 主机批量部署 Zabbix Agent，并保证它们能正常上报数据、能被前端识别、告警能发出来。别看 Agent 安装只是一个包的事情，真正落地的时候有很多看不见的坑：版本不对、模式选错、Hostname 不一致、防火墙没放行、自定义监控项写错，任何一个环节出错，前端页面上就是一片灰色主机，数据永远为 0。
1.2 两种工作模式必须先想清楚
Zabbix Agent 有主动模式和被动模式之分，这是配置前必须想明白的第一件事。
被动模式（Passive Check）下，Zabbix Server 主动去连接 Agent 的 10050 端口，向 Agent 询问某个监控项的数据。这种模式对 Agent 来说是被动的，不需要主动找 Server，但要求 Server 能通过网络访问到 Agent 所在主机的 10050 端口。
主动模式（Active Check）下，Agent 每隔一段时间主动去连接 Zabbix Server 的 10051 端口，拉取自己需要执行的监控项列表，然后定时采集并发回结果。这种模式适合 Agent 数量多、网络拓扑复杂、或者 Server 无法直接访问 Agent 的场景。老实说，如果被监控主机数量可控，网络又干净，用被动模式最省事；如果主机数量大、经常有临时网络通断，主动模式更合适，因为 Agent 不需要暴露端口给外部扫描。
配置上的关键点在于：配置文件里有两个参数分别控制两种模式，一个是Server参数用于设置谁可以以被动模式来索取数据，一个是ServerActive参数用于设置 Agent 向谁发起主动连接。这里的名字很像，但作用完全不同，我第一次配置时就吃过没分清这两个参数的亏。
1.3 这次部署的基本架构
回到诺禾 Linux 平台的监控项目，我们当时的部署背景是：监控服务器端（Zabbix Server + 数据库）已经就绪，前端页面可以正常访问，剩下的事情是把遍布各个业务区域的几十台 Linux 主机逐步纳入监控。
被监控主机系统以 CentOS 7、Rocky Linux 8、Ubuntu 20.04/22.04 为主，既有内网 IP，也有少量走专线的主机。内网主机我们采用被动模式，Agent 装在业务机器上，放行 10050 端口即可；专线主机因为网段隔离，部分改成了主动模式，让 Agent 主动把数据推到监控 Server 的 10051 端口。这样架构清晰，Server 不需要反向去访问所有机器，也不需要在防火墙上开一堆暴露出入口。
2. 环境准备与 Agent 安装
2.1 系统与版本选型
先讲一个原则：Zabbix Agent 的版本最好和 Zabbix Server 的版本保持一致，至少主版本要一致。比如 Server 是 6.0 LTS，那 Agent 也尽量用 6.0，不要用 5.0 或者 6.4 去混搭。不同版本的协议虽然大体兼容，但某些新监控项、新参数在高版本 Agent 上才支持，混搭容易出现“这个监控项不支持”的报错，排查起来很费时间。
其次，安装方式有两条路：一是用官方 Zabbix 仓库安装，二是用系统自带的软件仓库安装。系统自带的仓库里版本通常比较老，比如 CentOS 默认的 zabbix-agent 可能停留在 4.x 甚至更早，功能缺一大截，所以我更推荐用官方 Zabbix 仓库。官方仓库的 RPM/DEB 包装好之后会自动处理好依赖，后续升级也方便，一条 yum update / apt upgrade 就能跟上补丁。
需要额外留意的是：Zabbix 官方仓库地址会根据发行版大版本有不同的包名，比如 CentOS 7 和 Rocky Linux 8 的 RPM 包就完全不同，千万不要下载错，否则装不上或者装完起不来。判断自己是哪个发行版大版本，最简单的方法是用cat /etc/os-release看VERSION_ID。
2.2 RedHat / CentOS 系安装过程
以 Rocky Linux 8 为例，安装步骤非常固定。先装官方仓库包：
rpm -Uvh https://repo.zabbix.com/zabbix/6.0/rhel/8/x86_64/zabbix-release-6.0-4.el8.noarch.rpm如果你在纯内网环境，RPM 包下载不了，可以提前在一个能上外网的机器上下载好 rpm 包，再拷贝到内网安装；Zabbix 的 rpm 包依赖很少，手动rpm -ivh一般可以搞定。仓库装好后清理下缓存：
dnf clean all dnf install zabbix-agent -yCentOS 7 的流程一模一样，只是仓库包名里的 el7 和架构要换成对应的版本。装完以后验证一下：
zabbix_agentd --version如果能看到 zabbix_agentd（Zabbix Agent）版本号，说明二进制已经就位。
注意：Zabbix 6.0 的 Agent 二进制名在部分发行版上可能显示为
zabbix_agent2、zabbix_agentd，无论是 Agent 还是 Agent2，概念相同，只是后者是重构版，配置文件位置一样，都在/etc/zabbix/下。
2.3 Debian / Ubuntu 系安装过程
Ubuntu 22.04 的安装过程类似，但仓库包是 deb 格式。网上很多教程喜欢让你直接编辑 sources.list 文件，其实没必要，官方提供了打包好的 deb 安装包：
wget https://repo.zabbix.com/zabbix/6.0/ubuntu/pool/main/z/zabbix-release/zabbix-release_6.0-4+ubuntu22.04_all.deb dpkg -i zabbix-release_6.0-4+ubuntu22.04_all.deb apt update apt install zabbix-agent -y装完之后，配置文件在/etc/zabbix/zabbix_agentd.conf，这和 RedHat 系是同一个位置。有意思的是 Ubuntu 22.04 自带的 systemd 服务名是zabbix-agent，而某些老版本是zabbix-agent或zabbix-agentd，操作的时候最好先systemctl status看一眼再决定。
2.4 安装后的基础校验
安装完成后，不要急着修改配置，先做三件小事：
第一，确认进程是否存在：
ps -ef | grep zabbix第二，确认默认配置目录是否正确：
zabbix_agentd -t -p 2>/dev/null || echo "配置文件可能不存在"这里-t选项会测试配置文件的正确性，如果有误，会直接抛出错误行号信息，非常实用。理论上刚安装完，系统还没有启用服务，所以进程看不到是正常的，关键是把二进制和配置文件路径摸清楚。
第三，检查日志目录：
ls -lt /var/log/zabbix/正常情况下会有一个zabbix_agentd.log文件，可能还是空的，没关系。这样做的目的是确认日志权限，因为 Agent 大部分运行问题只能靠这个日志文件定位，如果日志目录不存在或者权限不对，后面排查会很痛苦。
3. 配置核心项逐条拆解
3.1 最小可用配置长什么样
Zabbix Agent 的配置文件是/etc/zabbix/zabbix_agentd.conf，几百行注释，大多数参数保持默认就行。真正要改的其实就几个点。一个最小可用的被动模式配置大致如下：
# 允许哪些 Server 来主动获取数据，多个 IP 用逗号分隔 Server=10.10.20.1,10.10.20.2 # 主动模式下 Agent 去连接哪台 Server，不需要主动模式就别填 # ServerActive=10.10.20.1 # 主机名，必须和前端添加主机时填写的主机名完全一致 Hostname=prod-app-01 # 监听端口，默认就是 10050，一般不用动 ListenPort=10050 # 日志级别，0 是信息级，4 是调试级 LogLevel=3 # 日志文件位置 LogFile=/var/log/zabbix/zabbix_agentd.log注意一个细节：被动模式下Server里填的是 Zabbix Server 的 IP，而不是 Agent 所在机器的 IP。这是个非常常见的低级错误。你想让 Server 来查 Agent 数据，那你就要告诉 Agent“哪些 IP 是合法的 Server”，所以填的是 Server 端的 IP。
Hostname为什么重要？因为在 Zabbix 前端添加主机时，系统默认通过主机名来识别 Agent 上报的数据归属。如果前端添加的“主机名”和 Agent 配置里的Hostname不一致，前端就会一直显示“不可达”或“不支持”状态。我们项目里就出现过三五台机器配置的时候把主机名写成了 IP，结果页面上一排灰，排查了大半天才发现是主机名粗心写错了。
3.2 Server、ServerActive 与 Hostname 的匹配规则
很多人奇怪，为什么不把参数合并成一个，偏偏整出两个。原因是 Zabbix 允许同时开启主动和被动模式。被动模式下，Server 就像“来访白名单”；主动模式下，ServerActive 是“你要去找谁”，而 Hostname 则是你向 Server 自报家门时的身份标识。
它们三者的匹配规则可以概括成：
- Server：允许的被动轮询来源，写 Server IP 或网段，多个用逗号分隔。
- ServerActive：主动连接的目标 Zabbix Server 地址，可以带端口，形如
10.10.20.1:10051，不写端口默认 10051。 - Hostname / HostnameItem：主动模式下，Agent 连接 Server 后会使用这个主机名去注册并获取监控项列表，所以必须和前端页面的主机名完全一样。被动模式也会在 Agent 内部标识中使用它。
如果只想用被动模式，ServerActive可以完全留空，但我们当时为了保留扩展性，还是统一填写了 Server 地址，只不过大多数机器不需要真的走主动上报，也不会造成什么影响。
3.3 主动模式下的几个坑
主动模式没有想象中那么“高级”，但配置上更容易踩坑，值得单独说。
主动模式下的 Agent 会按照RefreshActiveChecks（默认 120 秒）的周期去 Server 端获取监控项列表。如果你在前端给某台主机新加了一个监控项，Agent 最多延迟 2 分钟才会看到，这是正常现象，不是故障。如果你等着立刻生效，可以手动重启 Agent 服务，或者把RefreshActiveChecks临时调小，但不建议长期调得过小，否则会无谓增加 Server 端的压力。
主动模式下的 Agent 日志里如果出现item not found或not supported，优先级最高的怀疑对象是主机名不匹配。可以手动用命令行验证一下：
zabbix_get -s 10.10.20.1 -p 10051 -k "agent.hostname"但要注意，zabbix_get默认连的是被动端口 10050，主动模式的验证方式不同，更直接的办法是看 Agent 日志中主动检查的注册信息。主动模式下，Agent 本身就扮演了一个小型“采集调度器”，它拿到监控项列表后按照各自的间隔执行命令，执行结果再批量推给 Server。所以如果你看到日志中有active checks started，说明主动链路已经建立。
3.4 自定义监控项
Linux 自带的内置监控项其实已经覆盖了 90% 的日常需求：CPU、内存、磁盘、网卡流量都有现成的 key，比如system.cpu.util、vfs.fs.size、net.if.in。但工程项目里总有例外，比如要监控某个业务端口是否正常监听、某个特殊进程的数量、某个临时文件的存活时间，这些就需要自定义键了。
自定义键的格式是：
UserParameter=key[*],command $1 $2key[*]中的*是通配符，允许你在前端监控项里传入参数。命令部分可以用$1、$2依次引用传入的参数。举两个我们实际用过的例子：
# 监控某个 Java 进程的数量 UserParameter=custom.java.process.count,pgrep -fc java # 监控某个指定端口是否处于 LISTEN 状态 UserParameter=custom.tcp.status[*],ss -ltn state listen sport = :$1 | wc -l第一行没带参数，简单直接；第二行带了[*]，在前端添加监控项时可以写成custom.tcp.status[8080]，这样一台主机只需要一个通配 key，就能通过不同参数监控无限个端口，非常灵活。
自定义键最需要注意的有两点。第一，命令执行权限：Zabbix Agent 默认以zabbix用户运行，遇到需要读取/var/log下某些受保护文件或执行sudo命令的时候，很容易失败。为了一个自定义键去开全量 sudo 权限不值得，我当时是把数据单独落到一个 Agent 用户可读的临时文件里，然后让自定义键去读这个文件。第二，UnsafeUserParameters参数：默认情况下，如果 key 中包含特殊字符会报错，如果是简单参数一般不用管，但如果你真的传了$、\、"之类的特殊字符，需要把UnsafeUserParameters=1打开。打开后有命令注入风险，非必要别开。
3.5 TLS 安全配置
如果 Agent 端口要暴露到交换机或公网段，建议开启 Zabbix 自带的 TLS/PSK 加密。配置其实不复杂：
# 启用加密传输 TLSConnect=psk TLSAccept=psk # PSK 标识 TLSPskIdentity=ProdServer005 # PSK 密钥 TLSPskFile=/etc/zabbix/zabbix_agentd.psk生成的 PSK 密钥可以这样生成：
openssl rand -hex 32 > /etc/zabbix/zabbix_agentd.psk chown zabbix:zabbix /etc/zabbix/zabbix_agentd.psk chmod 600 /etc/zabbix/zabbix_agentd.psk同时，在 Zabbix 前端添加主机时也要配置相同的 PSK 标识和密钥，否则会显示认证失败。这一步属于加分项，内网环境如果安全要求不高，可以之后再补，但如果你要过等保或客户安全审计，这一步基本是必须的。
4. 服务启动与连接验证
4.1 启动并设置自启
配置文件改完后，先做一次配置语法检查：
zabbix_agentd -t这个命令会读取默认配置文件并检查语法，顺利的话会输出类似zabbix_agentd.conf: ok的结果。然后启动服务：
systemctl restart zabbix-agent systemctl enable zabbix-agent systemctl status zabbix-agent --no-pagerstatus输出中只要看到active (running)，基本就是起来了。不过我一般还会再往日志里看一眼：
tail -n 50 /var/log/zabbix/zabbix_agentd.log如果日志里出现listener failed或者cannot send...之类的字样，说明配置有问题，需要回炉改配置。
4.2 防火墙规则
如果系统里开了 firewalld 或 ufw，需要放行对应端口。CentOS 系常见操作：
firewall-cmd --permanent --add-port=10050/tcp firewall-cmd --reloadUbuntu 系可以用：
ufw allow 10050/tcp这里想提醒一个容易被忽略的事情：如果使用的是云服务器或者虚拟化平台里的主机，除了系统防火墙，还要检查安全组是否放行了端口，云平台安全组和安全策略有时候比系统防火墙更严格，两头都要放行才能通。
4.3 zabbix_get 验证
配置文件改好、服务启动、防火墙放行之后，第三步就是在 Server 端用zabbix_get命令验证 Agent 能不能响应。
首先确认 Server 上安装了zabbix_get，如果没有就装一下：
yum install zabbix-get -y然后执行：
zabbix_get -s 10.10.20.55 -p 10050 -k agent.ping如果返回值是1，说明 Agent 链路没问题。再测几个常用 key：
zabbix_get -s 10.10.20.55 -p 10050 -k system.uptime zabbix_get -s 10.10.20.55 -p 10050 -k system.cpu.util[,idle]zabbix_get的优势是它完全模拟 Zabbix Server 的断路器逻辑：只要返回有数据，前端大概率就是好的；如果这条命令超时无输出，那问题肯定在网络或 Agent 侧，不用再往后端查。
4.4 在前端添加主机
到这一步，Zabbix 前端添加主机就熟门熟路了。步骤如下：
- 进入“配置 -> 主机 -> 创建主机”。
- 主机名称必须和 Agent 配置文件里的
Hostname一致。 - 群组选一个已有的或新建的监控组。
- 如果是被动模式，IP 地址这里需要填 Agent 机器的 IP；如果走 DNS，填对应的可解析域名。
- 模板里选择一个适合该主机的模板，比如
Linux by Zabbix agent。模板本质上就是一套预定义监控项和触发器，选对模板能省去大量手工造监控项的时间。 - 点击“添加”后稍等几秒，刷新页面，主机状态应该在绿色范围内，可用性 zabbix 图标变成绿色。
如果添加完几十秒后主机状态依旧是灰色，优先回去查Hostname是否一致，再查 IP 和端口连通性。
5. 高频问题与排查实录
5.1 从 Agent 日志开始
所有 Zabbix Agent 疑难杂症，第一现场永远在那个日志文件里。6.0 的日志默认路径是/var/log/zabbix/zabbix_agentd.log，配置里可以通过LogFile调整位置。调试时最实用的做法是把LogLevel=4临时打开，这时候日志非常详细，能看到键值采集过程、主动检查注册结果、链接信息等，问题定位完毕后再改回LogLevel=3，避免日志膨胀。
举个我们项目中的真实例子：有一台 Ubuntu 主机，前端显示“已断开”，从 Server 端zabbix_get也是超时，但系统防火墙明明没有拦截。最后打开LogLevel=4看到日志里有cannot accept incoming connection: connection from ...的信息，才意识到问题出在另一层网络策略上，并不是配置错误。这就是看日志的重要性。
5.2 典型问题速查表
下面这个表格里汇总了我在 Zabbix Agent 部署过程中遇到过的四类高频问题，基本可以覆盖大多数情况。
| 现象 | 可能原因 | 排查方式 | 解决办法 |
|---|---|---|---|
| 前端主机显示“不可达”灰色 | Agent 未启动 / 端口不通 / Server 地址写错 | Server 上执行zabbix_get -s 客户端IP -p 10050 -k agent.ping | 确认 Agent 启动；放行 10050 端口；核对 Server 参数 |
| 有数据但图标显示“不支持” | key 名称写错 / 命令不存在 / 权限不足 | 前端看“最新数据”的报错信息；Agent 日志查看not supported原因 | 修正 key；检查用户权限；确认路径存在 |
| 主动模式无数据 | Hostname 不一致 / ServerActive 未配置 / 刷新周期长 | Agent 日志查看active checks信息 | 核对前端主机名；重启 Agent 或等待 2 分钟 |
| 监控项值异常偏大或为 0 | 单位换算 / 模板参数错误 / 自定义键命令相互影响 | 命令行手动执行 key 对应的命令对比结果 | 调整单位；检查模板宏 |
5.3 几个容易忽略的细节
第一，Agent 运行用户是zabbix，不是 root。如果你自定义键的命令需要读取/etc/shadow或者写入受保护目录，那大概率会失败。别急着给 zabbix 用户开一堆权限，更稳妥的做法是写一个单独的可执行脚本，把需要的权限限制在脚本内部，并且用日志记录一下执行结果方便排查。
第二，Timeout参数值得注意。Agent 执行一个监控项命令默认最多等 3 秒，如果自定义键脚本执行时间超过 3 秒，就会被判定超时报TIMEOUT。我们曾有个脚本因为要抓取远程数据库状态，执行时间有时候需要 5 秒以上，前端一直显示“不支持”，后来把Timeout=10改上才恢复。同理，Zabbix Server 端也有对 Agent 的轮询超时时间，一般默认也在 3~5 秒左右，前后端需要配合调整。
第三，开启自启别忘了。有些主机重启后 Agent 没起来，原因是安装完直接改配置测试，却忘了执行systemctl enable zabbix-agent。这种事情一次两次没关系，机器多了以后，主机重启一遍，你就会发现前端一大片灰色，全是自启没配导致的。批量环境可以用systemctl is-enabled zabbix-agent扫一遍，把没启动的都补上。
6. 一套顺手的小脚本比什么都实用
最后分享一个我们在批量部署时用的土办法。几十台机器一台台走 SSM 登录改配置太浪费时间，后来自写了两个简单脚本，一个负责批量安装并覆盖配置，一个负责批量检查结果。其实不复杂，核心就是循环执行 SSH 命令：
for host in $(cat hosts.txt); do scp -p ./zabbix_agentd.conf $user@$host:/etc/zabbix/zabbix_agentd.conf ssh $user@$host "systemctl restart zabbix-agent && systemctl enable zabbix-agent" done然后验证的时候，在 Zabbix Server 上循环执行 zabbix_get：
for ip in $(cat hosts.txt); do result=$(zabbix_get -s $ip -p 10050 -k agent.ping 2>&1) echo "$ip -> $result" done这段逻辑非常朴素，但配合规范化配置模板，已经能解决 90% 的批量部署场景。等接入量更大之后，还可以考虑引入 Ansible、SaltStack 等配置管理工具，但监控 Agent 这种东西，配置稳定后就很少变动，脚本处理完全够用。
我个人在实际操作中最深刻的体会是：Zabbix Agent 的安装配置本身并不难，难点永远在于“细节一致”：版本一致、主机名一致、端口一致、用户权限一致。把这些一致性问题控制住，监控系统就跑得顺畅，前端那片绿色小方块也能一直保持。
