优先用官方仓库安装，离线环境才考虑二进制或源码编译；严禁混用zabbix-agent与zabbix-agent2的配置文件或service单元。
zabbix-agent2 安装不难，但选错方式或忽略环境细节，后续连不上 Server、插件不生效、服务起不来都是大概率事件。直接说结论：**优先用官方仓库安装，离线环境才考虑二进制或源码编译；千万别混用 zabbix-agent 和 zabbix-agent2 的配置文件或 service 单元**。
用 yum/apt 装 zabbix-agent2 时，仓库版本必须对得上系统和 Zabbix Server 版本
CentOS/RHEL 8+ 和 Ubuntu 20.04+ 用户最容易踩的坑是仓库 URL 里写错了发行版代号或 Zabbix 大版本。比如 Server 是 7.0，你却用了 6.0 的 repo，zabbix-agent2 能装上，但某些新 key（如 systemd.unit.state）会报 ZBX_NOTSUPPORTED。
- 查清你的 Server 版本：
zabbix_server -V或 Web 界面右下角 - CentOS 8/9 对应
rhel/8或rhel/9，不是centos/8—— 官方已弃用 centos 命名 - Ubuntu 22.04 要用
ubuntu22.04，不能沿用 20.04 的 deb 包，否则systemd依赖可能缺失 - 装完检查二进制路径：
which zabbix_agent2应该是/usr/sbin/zabbix_agent2，不是/usr/sbin/zabbix_agentd
zabbix_agent2.conf 里 Server 和 ServerActive 不是随便填 IP 就行
这两个参数决定通信模式，填错会导致数据单向丢失。被动模式（Server）靠 Server 主动来拉，主动模式（ServerActive）由 Agent2 定期推——但两者都要求网络策略放行，且 Hostname 必须严格一致。
-
Server是被动模式白名单，只接受列表里 IP 的请求；若留空或写错，zabbix_get直接拒绝连接 -
ServerActive后面跟的是IP:Port格式，默认端口 10051；如果 Server 开了 TLS，这里必须写tls://IP:10051，否则连接被静默丢弃 -
Hostname必须和 Zabbix Web 中“配置 → 主机”里填的一模一样，大小写、下划线、点号都不能差——这是 Agent2 认领主机的唯一依据 - 改完配置一定要
systemctl restart zabbix-agent2，reload不生效
启动失败常见原因：端口冲突、用户权限、SELinux 干预
systemctl status zabbix-agent2 显示 failed 时，90% 不是配置写错了，而是底层环境卡住了。
- 端口 10050 被占：运行
ss -tlnp | grep :10050，确认没其他zabbix_agentd或测试进程在跑 - 用户权限问题：默认用
zabbix用户跑，但如果你手动改过zabbix_agent2.conf里的LogFileSize或LogFile路径，确保/var/log/zabbix/目录属主是zabbix:zabbix - SELinux 拦截：CentOS/RHEL 默认开启，
setsebool -P zabbix_can_network on是必须项，否则即使防火墙放行，TCP 连接也会被拒绝 - 日志定位：直接看
journalctl -u zabbix-agent2 -n 50 -f，比翻/var/log/zabbix/zabbix_agent2.log更快看到真实错误
想用 Docker 插件或自定义 Go 插件，必须确认安装包带 plugin 支持
官方仓库的 zabbix-agent2 包默认不含插件，zabbix-agent2-plugin-docker 是独立子包，漏装就永远拿不到 docker.info 这类 key。
- Debian/Ubuntu：
apt install zabbix-agent2-plugin-docker - RHEL/CentOS：
yum install zabbix-agent2-plugin-docker - 插件启用要改配置：
Plugins.Docker.Endpoint=unix:///var/run/docker.sock，且zabbix用户必须在docker组里（usermod -aG docker zabbix） - 验证插件是否加载：
zabbix_agent2 -p | grep docker，有输出才算成功
zabbix_get -s 127.0.0.1 -k agent.ping 返回值正常，但 system.cpu.util[,idle] 却超时——这种问题往往卡在 SELinux 上下文、cgroup 权限、或 Go 插件的 socket 文件访问控制上，得一层层剥开看，不能只盯着 conf 文件改。 
