前两篇已经把 Zabbix 的整体架构和 Server 安装基线交代清楚了。从这一篇开始，监控平台真正进入“接入对象”的阶段。Zabbix Server 本身再稳定，如果 Agent 接入方式混乱、主机名不一致、TLS 没有统一、主动模式和被动模式随意混用，后面做监控项、触发器、告警和报表都会变得很难维护。

本文不把 Agent 当成一个简单的软件包来讲，而是把它当成主机监控接入的标准入口。读完之后，你应该能够回答几个实际问题：一台 Linux 或 Windows 主机应该使用 Agent 还是 Agent 2；主动模式和被动模式怎么选；配置文件里哪些参数必须纳入基线；如何用 TLS/PSK 保护通信；自定义监控项应该写到什么程度；批量接入后如何证明这批主机真的稳定上报。

本文以 Zabbix 7.0 LTS 和 Zabbix agent 2 为主要口径。Zabbix 7.4 已经发布，但很多生产环境仍会优先采用 7.0 LTS 作为长期维护版本。文中命令以官方包安装方式和常见 Linux systemd 环境为例，Windows 侧给出接入原则和 MSI 参数方向。具体包地址、发行版版本号和安装命令在落地时要以 Zabbix 官方下载页面为准。

Agent 是被监控主机与 Zabbix 平台之间的本地采集层。它不只是把 CPU、内存、磁盘这些指标送上来，还承担了主机身份、采集模式、安全认证、扩展脚本、批量接入和故障定位的边界约束。

先明确 Agent 的职责边界

Agent 的核心职责是从主机本地采集操作系统和应用运行数据，再把这些数据交给 Zabbix Server 或 Zabbix Proxy。它适合采集本机视角下的资源、进程、端口、日志、文件系统、系统服务和本地脚本结果。不适合让它承担所有监控任务，更不适合把它变成一个远程运维执行器。

在实践中，Agent 接入最容易出问题的地方不是安装命令，而是边界不清。有人会把所有业务探测都写成 UserParameter，最后脚本依赖、权限、超时、返回格式散落在每台机器上；有人为了省事打开远程命令，导致监控系统拥有了过大的执行权限；还有人只看 Zabbix 前端主机变绿，却没有检查主动检查列表、Agent 日志、数据延迟和模板匹配是否正确。

更稳妥的做法是把 Agent 分成四层来看。第一层是基础采集，负责 CPU、内存、文件系统、网络、进程、服务等通用指标。第二层是主机身份，负责 Hostname、主机组、模板、标签和资产字段的统一。第三层是安全通信，负责 Server 白名单、TLS/PSK、最小权限和脚本执行限制。第四层是扩展采集，只在模板无法覆盖、业务确有需要、返回值可以稳定解释时使用自定义脚本。

Zabbix Agent 内部模块

Zabbix agent 2 使用插件化方式组织采集能力。官方文档说明，Agent 2 以 Go 为主实现，目标包括减少 TCP 连接、改进检查并发、通过插件扩展采集能力，并兼容传统 Agent 的主要功能。这个变化对运维团队的意义是：新环境优先选择 Agent 2 更合适，尤其是需要数据库、Docker、Redis 等插件化采集能力时。

Agent 还是 Agent 2

新部署环境建议优先使用 zabbix-agent2。原因不是“新版本一定更好”这么简单，而是 Agent 2 的设计更适合现在的混合基础设施。它支持主动和被动检查，支持插件化采集，主动检查可以利用更灵活的调度能力和并发能力。对于需要逐步扩展数据库、中间件、容器运行时监控的环境，Agent 2 的后续治理成本更低。

传统 zabbix-agent 仍然可以在一些老系统里继续使用，例如发行版太旧、变更窗口有限、历史模板依赖老 Agent 行为时。这里要注意版本兼容关系：Agent 通常可以低于 Server 版本，但不应该高于 Server 主版本。对于长期运行的生产环境，不建议把 Agent 升级策略和 Server 升级策略完全拆开，否则可能出现某些新 key、插件或配置参数在旧 Server 上不可用。

一个实用选择规则是：新主机、标准 Linux、Windows Server、需要插件能力的场景，默认 Agent 2；存量老系统、厂商封装系统、极小化系统，先确认官方包支持和依赖，再决定是否继续传统 Agent；网络设备、存储和专用硬件，通常不要强行安装 Agent，而是使用 SNMP、IPMI、HTTP API 或厂商接口。

主动模式与被动模式怎么选

Zabbix Agent 主动模式与被动模式

主动模式和被动模式不是优劣关系，而是网络方向、容量压力和安全策略不同。

被动模式下，Zabbix Server 或 Proxy 主动连接 Agent 的监听端口，通常是 10050，向 Agent 请求某个 key 的当前值。这个模式直观，便于 Server 控制采集节奏，适合网络边界简单、主机数量不大、Server 到主机方向可达的内网环境。它的问题也明显：每台主机需要开放入站端口，Server 或 Proxy 要承担大量连接调度，跨安全区时防火墙规则会变多。

主动模式下，Agent 主动连接 Server 或 Proxy 的 10051 端口，获取主动检查列表，然后按照列表采集并上报数据。这个模式更适合大规模主机、云主机、NAT 后主机、跨机房主机和安全边界较严格的网络。主机只需要出站访问监控入口，不需要让监控平台主动打到每台主机。缺点是主机名必须严格匹配，主动检查列表下发失败时，前端可能看起来配置存在，但数据迟迟不上来。

生产环境里常见做法是：同一区域内部由 Proxy 承接主机接入；普通系统指标优先主动模式；需要即时拉取或临时诊断的少量 key 可以保留被动模式；跨公网或跨安全区时优先主动模式并启用 TLS/PSK。不要在没有说明的情况下让同一批主机一半主动、一半被动，否则排障时很难判断问题发生在网络方向、主机名匹配还是模板配置。

配置基线先于安装动作

Zabbix Agent 安全防护层

Agent 的配置基线至少要包含八类参数：Server 地址、主动 Server 地址、主机名、监听地址、日志路径、超时、TLS 参数和自定义脚本包含路径。只要这几类参数没有标准化，批量接入就会变成“每台机器看起来都装了，但行为都不一样”。

下面是一份面向 Agent 2 的最小配置片段，字段需要根据实际环境替换：

conf
Server=10.10.10.20,10.10.10.21
ServerActive=10.10.10.20:10051
Hostname=app-prod-001
ListenPort=10050
LogFile=/var/log/zabbix/zabbix_agent2.log
Timeout=10
Include=/etc/zabbix/zabbix_agent2.d/*.conf

Server 用于被动检查白名单，只允许这些 Server 或 Proxy 连接 Agent。ServerActive 用于主动检查，表示 Agent 到哪里获取主动检查列表。Hostname 必须与 Zabbix 前端主机名一致，或者与自动注册规则生成的主机名一致。Include 用于把自定义 key、插件参数、业务脚本配置拆分到独立文件，避免主配置文件越来越难审计。

不要把主机名交给操作系统默认 hostname 随意决定。对于企业环境，更推荐使用一套可解释的命名规则，例如 业务-环境-序号、站点-角色-序号 或来自 CMDB 的唯一资产编号。名称不是为了好看，而是为了让告警、资产、变更、日志和工单能对得上。

Linux 与 Windows Agent 安装路径

安装动作本身应尽量来自官方仓库或官方 MSI。Linux 侧可以通过 Zabbix 官方下载页选择版本、发行版、数据库和 Web 组件后生成仓库包安装命令。Agent 机器只需要安装 zabbix-agent2，不需要安装 Server、Frontend 和数据库组件。Windows 侧可以使用 MSI 图形安装，也可以通过静默参数完成批量部署。

下面的命令是操作路径示例，不代表当前机器已经执行过。实际使用前要到官方下载页面按 Zabbix 版本和系统版本重新确认包地址。

bash
# Ubuntu/Debian 示例：安装官方仓库包后再安装 agent2
sudo apt update
sudo apt install zabbix-agent2
sudo systemctl enable --now zabbix-agent2
sudo systemctl status zabbix-agent2
bash
# RHEL/Rocky/Alma 示例：启用官方仓库后安装 agent2
sudo dnf install zabbix-agent2
sudo systemctl enable --now zabbix-agent2
sudo systemctl status zabbix-agent2

Windows 静默安装的重点不是记住某个 MSI 文件名，而是把 SERVER、SERVERACTIVE、HOSTNAME、TLS 参数和服务启动方式纳入统一发布脚本。安装后要检查 Windows 服务状态、配置文件路径、事件日志和 Zabbix 前端最新数据时间。

主机接入流程

Agent 安装完成后，不代表主机已经完成接入。完整流程应该包括主机创建、接口配置、模板关联、标签设置、数据验证和告警验证。

在 Zabbix 前端创建主机时，先选择主机组。主机组不仅用于分类展示，也会影响权限、动作条件和维护窗口。然后配置 Agent 接口，如果主要使用主动模式，接口地址仍建议填写真实地址或资产地址，方便后续定位，但关键是 Hostname 和主动检查列表匹配。接着关联模板，例如 Linux 主机可以先关联官方 Linux by Zabbix agent 模板，再根据业务角色追加 Nginx、MySQL、Redis、Docker 等模板。

对于大规模环境，不建议手工创建每台主机。可以使用主动自动注册、网络发现、API 从 CMDB 同步、配置管理工具下发 Agent。自动注册尤其适合云主机和弹性节点，但必须处理好主机名唯一性、PSK 安全、模板匹配和退役清理。否则短生命周期主机会在 Zabbix 里留下大量无效对象。

一个可执行的接入验收标准可以这样定义：主机在 Zabbix 前端存在；主机组、模板、标签符合规范；agent.ping 有最新数据；CPU、内存、磁盘至少连续上报三个采集周期；Agent 日志没有持续认证失败、主动检查列表为空、unsupported item 等错误；模拟一个低风险触发器能产生事件并恢复；主机退役流程能清理 Agent 服务和 Zabbix 对象。

TLS/PSK 通信配置

TLS PSK 通信配置流程

监控数据里通常包含主机名、进程、路径、端口、服务状态，有时还会包含业务日志摘要。跨安全区、跨机房、云上环境或任何不完全可信的网络，都应该启用 TLS。Zabbix 支持基于证书和基于预共享密钥的加密。对于多数中小规模运维团队，PSK 更容易标准化；对于已有内部 CA 和证书生命周期管理能力的组织，证书方式更适合长期治理。

PSK 的关键点有三个。第一，PSK 本身要足够随机，不能使用主机名、业务名、手机号、日期这类可猜测字符串。第二，PSK identity 不要包含敏感信息，因为它用于告诉接收端选择哪把密钥，本身不应承载秘密。第三，一台主机的 PSK 不要在大量主机之间共享，否则单点泄露会扩大影响范围。

Agent 侧配置示例：

conf
TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=psk-app-prod-001
TLSPSKFile=/etc/zabbix/zabbix_agent2.psk

PSK 文件权限应该只允许 Agent 运行用户读取：

bash
sudo install -o zabbix -g zabbix -m 0400 /tmp/zabbix_agent2.psk /etc/zabbix/zabbix_agent2.psk
sudo systemctl restart zabbix-agent2

Zabbix 前端的主机配置也要同步设置相同的 PSK identity 和 PSK 值，并指定连接方向允许 PSK。只改 Agent 或只改前端都会导致握手失败。变更时建议先在测试主机验证，再分批推广到同一主机组。启用 TLS 后，第一时间检查 Server、Proxy 和 Agent 日志，确认没有 TLS handshake、unknown PSK identity、connection rejected 等持续错误。

UserParameter 的使用边界

UserParameter 与自定义监控项

UserParameter 是 Agent 扩展能力里最常用也最容易失控的功能。它允许定义自定义 key，由 Agent 执行本地命令或脚本并返回结果。官方文档明确说明，UserParameter 是由 Zabbix agent 执行的命令，Unix 系统下通常通过 /bin/sh 解释，返回内容受 Agent 检查超时约束，超时后进程会被终止。

适合使用 UserParameter 的场景包括：官方模板没有覆盖的本地业务状态；只能从本机读取的应用运行指标；简单、稳定、低成本的脚本输出；需要与现有本地巡检脚本复用的单值指标。不适合的场景包括：耗时很长的全量巡检；需要访问大量远程系统的复杂任务；返回结构不稳定的文本；需要高权限或可能修改系统状态的命令。

一个较好的 UserParameter 应该满足四个条件：返回单一、明确、可解析的值；正常和异常路径都有固定输出；执行时间显著小于 Agent Timeout；脚本不依赖交互式环境变量。示例：

conf
UserParameter=app.health,/usr/local/bin/check_app_health.sh
UserParameter=app.queue.depth[*],/usr/local/bin/check_queue_depth.sh "$1"

脚本返回值应尽量简单：

bash
#!/usr/bin/env bash
set -euo pipefail

curl -fsS --max-time 3 http://127.0.0.1:8080/health >/dev/null && echo 1 || echo 0

如果确实需要参数，必须在脚本内做白名单校验，不能把用户输入直接拼到 shell 命令里。对于需要读取特权文件的脚本，优先考虑最小化 sudo 规则，例如只允许 zabbix 用户执行某一个固定脚本，而不是允许执行一类系统命令。监控脚本的职责是观测，不是修复；修复动作应该放在自动化平台、工单系统或经过审批的运维脚本里。

配置参数治理

Agent 配置参数治理

Agent 配置不要靠手工编辑长期维护。至少要把配置分成三类：平台统一参数、环境参数和业务扩展参数。平台统一参数包括日志、超时、Include、TLS 基线和危险能力限制；环境参数包括 Server、Proxy、主机命名、主机组和模板；业务扩展参数包括 UserParameter、插件配置和业务脚本路径。

这种拆分带来的好处是变更影响可控。比如监控入口从 Server 切到 Proxy，只需要调整环境参数；开启 TLS 只需要调整统一参数和密钥分发；新增某个业务应用的监控，只需要下发对应的扩展配置文件。不要让每个应用团队直接修改主配置文件，否则最后没有人能说清哪一行参数是平台基线，哪一行参数是临时例外。

对配置管理工具而言，Agent 是非常适合纳入模板化管理的组件。Ansible、SaltStack、Puppet、Chef 或企业内部发布系统都可以完成包安装、配置渲染、密钥分发、服务重启和接入验证。关键是每次变更后都要有机器可读的验收动作，例如运行 zabbix_agent2 -t agent.ping、检查服务状态、检查日志关键字、调用 Zabbix API 查询最新数据时间。

批量接入与高可用场景

批量接入与高可用排障

主机数量达到几十台以后，就不应该再把 Agent 接入当成单机安装任务。批量接入要先定义主机生命周期：创建、纳管、模板关联、告警启用、维护窗口、退役。缺少生命周期设计时，Zabbix 里最常见的问题不是漏监控，而是“曾经存在过的主机”越来越多，告警对象和资产对象对不上。

在多站点或多安全区环境里，推荐通过 Zabbix Proxy 承接区域内主机。主机到本区域 Proxy，Proxy 再到 Server，既减少跨区域连接，也降低 Server 的直接连接压力。Agent 侧的 Server 和 ServerActive 应指向本区域 Proxy，而不是所有主机都直接访问中心 Server。这样网络故障时，影响面也更容易判断：是主机到 Proxy，还是 Proxy 到 Server。

高可用不是简单把多个地址写进配置就结束。需要明确 Agent 主动检查连接哪个入口，入口故障后如何切换，DNS 是否可靠，Proxy 是否有容量冗余，Server 端是否能识别同一主机，监控数据是否会重复或中断。对于关键系统，可以在变更窗口里做一次主动故障演练：暂停一个 Proxy 或阻断一条网络路径，观察 Agent 日志、Proxy 队列、Server 最新数据时间和告警噪音。

Windows 主机接入要单独治理

Windows Agent 接入不能直接套用 Linux 的思路。Linux 上多数配置路径、服务管理、日志路径和权限模型都比较一致，而 Windows 环境里会遇到域控策略、杀毒软件、主机防火墙、服务账号、安装目录、PowerShell 执行策略和重启窗口等额外约束。把 Windows 主机简单当成“另一种命令格式”处理，后期排障成本会很高。

Windows 侧建议优先使用官方 MSI 包，并通过软件分发系统或域策略统一下发。静默安装参数至少要包含 Server、ServerActive、Hostname 和 TLS 相关配置。安装后要检查 Windows 服务是否自动启动，配置文件是否写入预期目录，主机防火墙是否允许需要的方向，Zabbix 前端主机接口是否与实际地址一致。对于主动模式，重点仍然是 Hostname 匹配和 active checks 获取结果。

Windows 的监控模板也要避免过度采集。基础模板可以覆盖 CPU、内存、磁盘、网络、服务、性能计数器等信息，但不同业务服务器的服务名、进程名、日志路径和磁盘分区差异很大。建议先定义 Windows 基线模板，再按角色补充 IIS、SQL Server、中间件、备份客户端、安全软件等模板。不要把所有 Windows 主机都关联同一个“全量模板”，否则 unsupported item 和无意义告警会非常多。

服务监控要特别注意名称。Windows 服务有显示名和服务名，Zabbix 采集通常依赖服务名。运维记录里如果只写“监控某某服务”，但模板里使用了错误的显示名，很容易出现服务实际异常但监控没有触发，或者服务已经改名但模板仍然指向旧名称。接入时应从系统命令或服务管理界面确认服务名，并写入模板说明。

日志监控同样要谨慎。Windows 事件日志可以提供丰富状态，但不是所有事件都应该进入告警。更合理的做法是先确定关键事件 ID、来源、级别和业务影响，再建立少量明确的触发器。大量泛化的错误事件告警会迅速制造噪音，尤其是在域策略、补丁安装、安全软件扫描和驱动更新频繁的服务器上。

自动注册的设计

主动自动注册适合弹性主机和批量装机场景，但它不是“让主机自己出现”这么简单。自动注册规则要解决五个问题：主机怎么命名，进哪个主机组，挂哪些模板，打哪些标签，如何防止未授权主机混入监控平台。

安全自动注册应结合 PSK。官方文档说明，自动注册可以通过基于 PSK 的加密连接增强安全性。实际设计时，可以为不同环境、不同区域或不同业务组使用不同的 PSK identity 和密钥，不要把所有主机共用同一把密钥。自动注册动作里也不要直接给新主机关联过多高噪音模板，先接入基础模板和主机标签，确认主机身份后再由 CMDB 或审批流程补充业务模板。

自动注册的主机名生成规则要稳定。云主机经常会重建，容器宿主机可能会重装，虚拟机可能会克隆。如果主机名只来自临时 hostname，Zabbix 中就会不断产生新对象，历史数据也无法连续。更好的方式是从 CMDB、云实例 ID、资产编号或发布系统里取唯一标识，再映射成可读名称。对于短生命周期节点，可以明确保留策略，例如退役后保留三十天历史，再由清理任务删除。

自动注册还要考虑反向流程。主机下线后，Agent 停止上报会触发 nodata 或 availability 告警，但这不等于对象已经退役。退役流程应该由资产系统或发布系统触发，修改维护状态、移除模板、归档历史、删除主机对象或标记为 retired。否则 Zabbix 前端会长期混杂真实故障主机和已经不存在的历史主机。

自定义脚本的发布规范

只要用了 UserParameter，就必须把脚本发布规范讲清楚。脚本应该放在固定目录，例如 /usr/local/lib/zabbix/scripts，由配置管理工具发布，属主和权限固定，脚本版本可追踪。不要把脚本散落在 /tmp、个人 home 目录或应用目录里，也不要让应用发布流程随意覆盖监控脚本。

脚本输出要适合监控系统消费。数值型指标只输出数字，不要混入单位、描述和调试信息；文本型指标要控制长度；发现规则要输出符合 Zabbix LLD 要求的 JSON；失败时要返回明确状态，而不是堆栈、HTML 页面或空字符串。对于需要区分异常类型的场景，可以返回枚举值，再在 Zabbix 里用 value mapping 或触发器表达式解释。

脚本要有本地测试方式。每个自定义 key 在上线前都应该能用 zabbix_agent2 -t 本地验证，并记录正常返回、异常返回和超时行为。复杂脚本还应有独立命令行参数，例如 --check、--timeout、--target，便于脱离 Agent 排障。监控脚本最怕只能在 Agent 环境里运行，一旦出问题就很难判断是脚本逻辑、权限、环境变量还是 Zabbix 配置导致。

脚本依赖要显式声明。比如依赖 curl、jq、数据库客户端、云厂商 CLI 或某个 Python 包，就要写入发布清单，并由配置管理工具安装。不要假设所有主机都已经具备这些依赖。依赖缺失导致的 unsupported item 往往会在大规模接入后集中出现，最终让平台维护者误以为 Zabbix 本身不稳定。

变更演练与回滚

Agent 配置变更看起来影响小，但批量操作时风险并不低。修改 ServerActive、启用 TLS、调整 Hostname、替换模板、修改 Include 路径、变更 Timeout，都可能让一批主机停止上报。生产变更前应至少选一台测试主机、一台普通生产主机和一台关键业务主机做分层验证。

一次合格的 Agent 变更应包含变更前快照、变更动作、验证动作和回滚动作。变更前快照包括 Agent 版本、配置文件摘要、服务状态、最新数据时间、关键 item 支持状态。变更动作应由脚本或配置管理工具执行，避免人工编辑。验证动作包括本地 -t 测试、服务日志检查、Zabbix 前端最新数据检查和关键触发器状态检查。回滚动作应能恢复旧配置、旧密钥或旧入口，并重新启动服务。

启用 TLS/PSK 时尤其要小心。最稳妥的路径是先在 Zabbix 前端允许未加密和 PSK 两种连接，Agent 侧切到 PSK 并验证成功，再逐步收紧为只允许 PSK。不要在同一个变更窗口同时修改主机名、ServerActive、TLS 和模板，否则失败后很难定位是哪一项造成的。

对于大规模批量变更，可以按主机组分批。第一批选择非关键系统，第二批选择普通生产系统，最后处理关键系统。每批之间至少观察几个采集周期，并检查 Zabbix Server 或 Proxy 的队列、Agent 日志错误数量、unsupported item 增量和告警数量。批量变更的目标不是“尽快推完”，而是确保问题在小范围内被发现。

与后续文章的衔接

Agent 管理做得好，后续监控项和触发器才有稳定地基。监控项依赖 key 的可用性、采集周期和返回类型；触发器依赖数据连续性、时间窗口和异常语义；告警依赖主机组、标签、严重级别和维护状态。如果 Agent 接入时没有统一这些信息，后面每一层都会用临时规则补洞。

因此，本文的输出不应该只是“某台机器装好了 Agent”。更准确的输出是：主机已经以明确身份进入 Zabbix，采集模式清晰，通信安全可验证，模板关联有依据，自定义脚本受控，验收记录可追溯，退役路径可执行。做到这一步，Zabbix 才真正具备持续扩展的基础。

一个接入案例

假设现在要接入一个生产订单系统的三台应用服务器，名称分别为 mes-prod-app-001、mes-prod-app-002、mes-prod-app-003。这三台机器位于生产区，不能被中心 Server 直接访问，只允许出站访问本区域 Proxy。此时接入设计应选择 Agent 2、主动模式、连接本区域 Proxy、启用 PSK，并关联 Linux 基线模板和订单系统应用模板。

实施前先在 CMDB 中确认三台主机的资产编号、业务负责人、系统等级、维护窗口和退役责任人。然后由配置管理工具下发 Agent 包、配置文件和 PSK 文件。Agent 配置中的 Hostname 与 Zabbix 前端主机名保持一致，ServerActive 指向生产区 Proxy，TLSConnect 设置为 psk。Zabbix 前端预先创建主机对象，挂载基础模板，添加业务标签 system=mes、env=prod、role=app。

变更执行后，不应只看主机可用性图标。验收人需要检查每台主机的最新数据时间是否在两个采集周期内更新，CPU、内存、根分区、系统负载、Agent ping 是否都有值；检查 Agent 日志中没有持续认证失败和 active checks 为空；检查 Proxy 队列没有明显堆积；检查订单系统自定义 key 是否能在 Agent 本地和 Zabbix 前端同时看到结果。只有这些检查都通过，才能把主机纳入正式告警范围。

如果其中一台主机没有数据，排查顺序应先看 Agent 日志是否提示主机名不存在，再看 PSK identity 是否和前端一致，然后看 Proxy 地址和端口是否可达，最后检查模板中 item 类型是否为主动检查。这个顺序比直接改防火墙或重装 Agent 更可靠，因为主动模式失败最常见原因往往是身份和加密配置，而不是软件包损坏。

验收记录建议

Agent 接入完成后，建议在变更记录或知识库中留下结构化验收记录。记录内容至少包括：接入日期、Zabbix 版本、Agent 版本、主机清单、接入模式、Proxy 或 Server 入口、TLS 策略、模板清单、自定义 key 清单、验证命令、前端最新数据截图或数据时间、异常项处理结果、回滚方案和负责人。

这份记录的价值会在后续故障中体现出来。比如某台主机突然停止上报，团队可以先确认它原本是主动模式还是被动模式，应该连接哪个 Proxy，PSK identity 是什么，模板中哪些 key 是自定义的，最近是否做过 Agent 版本升级。没有记录时，排障人员只能从现场猜测；有记录时，排障可以从明确基线开始。

验收记录还应该进入定期复审。Agent 版本、Server 版本、TLS 策略、模板内容和业务归属都会变化，三个月左右复查一次比较合适。复查时重点看存量主机是否仍在上报、退役主机是否已经清理、PSK 是否存在共用过大的情况、自定义脚本是否仍由负责人维护、模板是否出现大量 unsupported item。复审不是形式动作，而是防止监控体系在长期运行中逐步偏离基线。

退役治理也要纳入复审范围。主机下线后如果只停止 Agent，不清理模板、维护期、自动注册规则和密钥，后续会留下误报、空对象和安全隐患。规范的做法是由资产状态驱动监控状态变化，让 Zabbix 对象生命周期跟随真实资产生命周期，并保留可追溯的责任记录和复核审计记录。

验证与排障

Agent 接入验证路径

Agent 排障要按链路走，不要只盯着前端红绿状态。第一步看服务是否运行，第二步看配置是否加载，第三步看网络方向是否可达，第四步看主机名是否匹配，第五步看模板和 item 是否支持，第六步看数据是否按预期进入历史表。

常用检查包括：

bash
systemctl status zabbix-agent2
journalctl -u zabbix-agent2 -n 100 --no-pager
zabbix_agent2 -t agent.ping
zabbix_agent2 -t system.cpu.load

如果使用被动模式，可以在 Server 或 Proxy 上用 zabbix_get 测试：

bash
zabbix_get -s 192.0.2.10 -k agent.ping
zabbix_get -s 192.0.2.10 -k system.hostname

如果使用主动模式，重点看 Agent 日志里是否成功获取 active checks。常见错误包括主机名不存在、主机名大小写不一致、ServerActive 地址不可达、TLS 参数不匹配、前端没有配置主动类型 item。主动模式下，agent.ping 变绿不一定代表所有主动 item 都正常，必须看最新数据和 unsupported items。

Unsupported item 不能简单关闭。它通常说明 key 不支持、参数写错、权限不足、脚本超时、依赖命令缺失或模板与系统类型不匹配。处理顺序应是先确认模板适配，再在 Agent 本地用 -t 测试 key，然后看脚本权限和超时，最后才考虑调整模板或禁用不适用的 item。

安全与权限建议

Agent 默认应以低权限用户运行。不要为了采集方便让它拥有 root 常驻权限，也不要把大量 sudo 权限直接授予 zabbix 用户。真正需要特权的采集项，应通过固定脚本、固定参数和最小 sudo 规则实现，并把脚本纳入版本管理。

远程命令能力要谨慎。很多团队早期会把 Zabbix 当作“顺手执行修复命令”的入口，但这会把监控平台变成高权限操作平台，一旦账号、模板、动作规则或脚本被误改，影响会很大。更合理的做法是：Zabbix 负责发现问题、聚合上下文、触发工单或通知；自动修复交给具备审批、审计和回滚能力的自动化系统。

日志采集也要有边界。Agent 可以采集日志类 item，但不要把大体量业务日志原样塞进 Zabbix。Zabbix 更适合状态和指标，日志全文检索应交给日志平台。对于少量关键错误日志，可以只提取错误计数、最后错误时间、关键状态码，而不是保存大量文本内容。

团队交付清单

一批 Agent 接入完成后，至少应交付以下内容：主机清单、主机组和模板映射、Server 或 Proxy 入口、Agent 版本、主动或被动模式、TLS 策略、PSK 管理方式、自定义 key 清单、脚本路径、最小权限说明、接入验收结果、回滚方法和退役规则。

接入记录最好能回答三个问题。第一，谁负责这台主机的监控模板维护；第二，哪些指标属于平台基线，哪些指标属于业务团队自定义；第三，当这台主机退役或迁移时，谁负责同步清理 Zabbix 对象和密钥。没有这些信息，Zabbix 很快会从监控平台变成历史主机仓库。

小结

Zabbix Agent 的价值不在于“装上一个采集程序”，而在于建立一套可复制、可验证、可审计的主机接入标准。Agent 2、主动模式、Proxy 分区、TLS/PSK、自定义 key 和批量配置管理，都是为了让主机接入在规模变大后仍然可控。

下一篇会进入监控项与触发器。只有 Agent 接入稳定，监控项才有可信的数据来源；只有主机身份、模板和采集模式清晰，触发器才不会因为数据延迟、key 不支持或主机名不匹配产生大量误判。

参考资料