监控体系里Zabbix 负责采集、告警Grafana 负责把数据画成看得顺眼的大屏这对组合在运维圈子里用得很广。这篇博文就按项目标题来完整走一遍用 Docker 部署 Zabbix 6.2.7 加 Grafana 的流程从方案选型、Compose 编排、初始化配置到接入第一台机器、Grafana 拉数据源最后把高频报错一并梳理出来。整个过程记录的是实际部署时的思路不只是命令复制粘贴适合刚接触容器化监控、或者想从传统包安装迁到 Docker 的朋友参考。1. 部署方案与架构选型为什么是这三件套1.1 Zabbix 负责数据闭环Grafana 负责“好看”先想清楚一个前提Zabbix 和 Grafana 不是竞品是互补关系。Zabbix 的核心价值集中在采集、存储、触发器、告警通知这一整套闭环它自带的 Web 界面在“能用”层面完全没问题配置主机、定义触发器、看最新数据、开报表都顺手。但一旦涉及多团队的大屏展示、业务视角的数据面板Zabbix 原生 UI 就显得朴素自定义图表也麻烦。Grafana 补的正是这一块数据源插件生态成熟直接把 Zabbix 的 API 接进来就能用统一的图表体系做聚合视图、对比分析、大屏轮播。很多团队的实际分工就是Zabbix 管监控和告警Grafana 管展示和汇报。用 Docker 部署这套组合最大的好处是“可复现”。传统 rpm 或源码安装依赖关系复杂升级一次心惊胆战换成镜像编排后环境差异被收敛到 Compose 文件里换台机器拉起来就是同一套环境。所以这个方案的核心价值不是“省事”而是“一致性和可维护性”。1.2 Docker 部署的代价数据持久化必须亲自管Docker 部署监控系统有个常被忽略的坑——容器是比进程还“轻浮”的东西。容器删除或重建后容器内的数据默认直接消失。Zabbix 的配置、历史数据、告警记录全部落在数据库里Grafana 的 dashboards 也存在自己的数据库里这些都必须通过 volume 挂载到宿主机。这是整套部署里最不能省的一步后面第 2 章会单独展开。另外一个取舍是网络模式。很多入门教程图省事直接--network host或者把端口全部映射到宿主机这样能跑但 port 冲突和安全性都欠佳。我倾向于用自定义 bridge 网络容器之间用服务名互相访问数据库端口不暴露到宿主机只在需要时把 Web 和 Grafana 端口映射出来这样风险面小得多。1.3 版本选择的冷知识6.2.7 不是 LTS项目标题指定了 Zabbix 6.2.7这里就要说句实在话。Zabbix 的版本策略里6.0、6.4、7.0 这些属于 LTS长期支持版本6.2 属于标准版本生命周期比 LTS 短。也就是说6.2.7 这套镜像在功能上演示没问题但如果真是生产环境长期跑更稳妥的选型是 6.0 LTS 或 6.4 LTS。我个人的建议是如果你的目的是学习、尝试新功能、或者短中期项目按标题用 6.2.7 完全可以如果是要搭建至少跑两三年的监控底座把镜像 tag 换成 6.4 系列部署方式几乎一模一样。这个决定没有对错但一定要提前知情别等部署完才被版本节奏打一个措手不及。Grafana 版本同样要注意。我建议选 10.x 或 11.x 的 oss 镜像老版本可能在插件兼容性上出问题。Zabbix 连接 Grafana 靠的是 alexanderzobnin-zabbix-app 这个社区插件它对 Grafana 版本有要求版本不对就会出现“插件装了但加载不出来”的情况。2. 环境准备、端口规划与持久化设计2.1 Docker 与 Compose 环境确认开始之前先确认宿主机上有 Docker 和 Compose。比较新的 Docker 桌面版或 Docker Engine 都自带 Compose V2命令是docker compose中间有空格老项目里那种docker-compose单独二进制的方式在新环境里不推荐了。验证命令很简单docker version docker compose version如果输出正常说明基础环境没问题。我用的是 CentOS 7.9 的服务器Docker 版本 24.xCompose V2.20 左右这套配置在 Ubuntu、Debian、Rocky Linux 上都能直接复现。Windows 下面如果用 Docker Desktop要在设置里把 WSL2 后端和虚拟化支持打开这部分问题在第 6 章案例里详聊。内存方面建议至少给 4GBZabbix Server 加 PostgreSQL 加 Grafana 跑起来2GB 会有点紧容易触发 OOM。磁盘没有特殊要求但历史数据会持续增长数据库挂载目录尽量放在空间充足的盘上。2.2 组件清单与端口分配整套环境一共起了这么几个容器组件镜像作用端口PostgreSQLpostgres:15-alpineZabbix 元数据库容器内 5432不暴露宿主机Zabbix Serverzabbix/zabbix-server-pgsql:6.2.7-ubuntu核心采集、告警引擎容器内 10051只对 agent 和 web 开放Zabbix Webzabbix/zabbix-web-nginx-pgsql:6.2.7-ubuntu管理界面、前端展示宿主机 8080 - 容器 8080Zabbix Agentzabbix/zabbix-agent:6.2.7-ubuntu被监控端采集器宿主机 10050 - 容器 10050Grafanagrafana/grafana-oss:10.4.0可视化面板宿主机 3000 - 容器 3000端口规划上有两个细节。第一PostgreSQL 端口不要映射到宿主机数据库只服务容器内部的 Zabbix Server 和 Web暴露出去等于把数据库裸奔在网络上没必要。第二Zabbix Web 我映射到 8080 而不是 80是因为 80 端口经常被宿主机上其他服务占掉8080 冲突概率小访问时带个端口并不影响使用。关于镜像 tagZabbix 官方镜像分-ubuntu和-alpine两种。alpine 版镜像小但个别依赖模块不完整比如某些 SNMP 扩展和字体处理会出问题。这里选了-ubuntu版本牺牲一点磁盘空间换取后面排障时的省心。2.3 目录挂载与数据安全设计这是我反复强调的一环。以下目录必须挂载到宿主机./data/postgres:/var/lib/postgresql/data ./data/grafana:/var/lib/grafanaZabbix 的配置本身可以靠环境变量重建但数据库和 Grafana 的配置、面板数据必须持久化。有个经典事故是有人跑了一段时间清理容器时顺手docker rm了数据库容器整年的历史监控数据直接蒸发。所以不管容器怎么重建数据目录的状况直接决定你晚上能不能睡安稳。除此之外Zabbix Server 和 Web 还需要把时区文件挂进去。容器里默认是 UTC 时间不处理的话监控图的时间会比北京时间慢 8 小时排查问题时特别别扭。挂载两个只读文件就能解决- /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro如果你是在没有 /etc/timezone 的发行版上部署有些精简系统只有 localtime可以只挂 localtime或在环境变量里补齐 PHP_TZ。整体目录设计放在后文的 Compose 文件里一起看。3. docker-compose 编排与核心配置全解3.1 完整 Compose 文件示例直接给一套能在绝大多数 Linux 环境跑通的配置。我把它起名为docker-compose.yml放在项目目录如/opt/monitor下version: 3.8 networks: zbx-net: driver: bridge services: postgres: image: postgres:15-alpine container_name: zbx-postgres networks: - zbx-net environment: POSTGRES_USER: zabbix POSTGRES_PASSWORD: zabbix_pwd POSTGRES_DB: zabbix volumes: - ./data/postgres:/var/lib/postgresql/data - /etc/localtime:/etc/localtime:ro restart: unless-stopped zabbix-server: image: zabbix/zabbix-server-pgsql:6.2.7-ubuntu container_name: zbx-server networks: - zbx-net environment: DB_SERVER_HOST: postgres POSTGRES_USER: zabbix POSTGRES_PASSWORD: zabbix_pwd POSTGRES_DB: zabbix ZBX_JAVAGATEWAY: zabbix-java-gateway ZBX_JAVAGATEWAY_ENABLE: true ports: - 10051:10051 volumes: - ./data/server-externalscripts:/usr/lib/zabbix/externalscripts:rw - /etc/localtime:/etc/localtime:ro depends_on: - postgres restart: unless-stopped zabbix-web: image: zabbix/zabbix-web-nginx-pgsql:6.2.7-ubuntu container_name: zbx-web networks: - zbx-net environment: ZBX_SERVER_HOST: zabbix-server DB_SERVER_HOST: postgres POSTGRES_USER: zabbix POSTGRES_PASSWORD: zabbix_pwd POSTGRES_DB: zabbix PHP_TZ: Asia/Shanghai ports: - 8080:8080 volumes: - ./data/web-nginx:/etc/ssl/nginx:ro - /etc/localtime:/etc/localtime:ro depends_on: - zabbix-server restart: unless-stopped zabbix-agent: image: zabbix/zabbix-agent:6.2.7-ubuntu container_name: zbx-agent networks: - zbx-net environment: ZBX_SERVER_HOST: zabbix-server ZBX_HOSTNAME: docker-host ZBX_PASSIVESERVERS: zabbix-server ports: - 10050:10050 volumes: - /etc/localtime:/etc/localtime:ro depends_on: - zabbix-server restart: unless-stopped zabbix-java-gateway: image: zabbix/zabbix-java-gateway:6.2.7-ubuntu container_name: zbx-java-gateway networks: - zbx-net restart: unless-stopped grafana: image: grafana/grafana-oss:10.4.0 container_name: zbx-grafana networks: - zbx-net environment: GF_INSTALL_PLUGINS: alexanderzobnin-zabbix-app GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS: alexanderzobnin-zabbix-app ports: - 3000:3000 volumes: - ./data/grafana:/var/lib/grafana - /etc/localtime:/etc/localtime:ro restart: unless-stopped3.2 核心配置项逐段讲解这个 Compose 文件里有几个地方即使能跑起来也建议你理解含义。第一个是网络。所有容器都挂在zbx-net这个自定义 bridge 网络上所以 Zabbix Server 访问数据库时可以直接写主机名postgresWeb 访问 Server 时写zabbix-server。自定义网络自带 DNS 解析这是容器编排里非常重要的一点。第二个是数据库环境变量。PostgreSQL 容器里的POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB是初始化数据库时用的Zabbix Server 和 Web 里的同名变量必须与它保持一致。如果不一致Web 界面登录后极大概率会报类似access denied for user replace_userlocalhost的错误这个在“常见问题”里细说。第三个是 Java Gateway。如果你的监控对象里有 Tomcat、Kafka 这类需要 JMX 协议的中间件Zabbix Server 需要走 Java Gateway 做代理采集。我这里提前把ZBX_JAVAGATEWAY_ENABLE打开容器也只是空跑不影响基础监控后续要监控 JMX 时直接就能用。第四个是 Zabbix Agent 的配置。ZBX_SERVER_HOST指定 Agent 主动连接哪个 ServerZBX_PASSIVESERVERS指定允许哪个 Server 主动连回来采集。在 bridge 网络里这两个都要填zabbix-server否则可能出现“主机状态正常但拿不到数据”的奇怪现象。Grafana 这边重点在GF_INSTALL_PLUGINS容器首次启动时会自动安装社区 Zabbix 插件省去了手工grafana-cli的步骤。旁边的GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS是保险项因为部分版本插件签名校验不稳提前允许加载能避免插件装完却被禁用的情况。3.3 启动、初始化和前端设置准备就绪后在/opt/monitor目录下执行docker compose up -d第一次启动要拉取镜像时间取决于网络状况。拉完后可以用docker compose ps观察容器状态STATUS 列全都变成Up并且没有频繁重启就说明基础环境没问题。想让 Web 界面能访问还需要给它一点初始化时间。Zabbix Server 首次启动时会自动建表、导入初始数据这个阶段数据库连接已经在跑但未必马上可用。一个很实用的观察方法是看日志docker compose logs -f zabbix-server看到类似server started或监听 10051 的日志就说明 Server 起好了。接着打开浏览器访问http://服务器IP:8080Zabbix Web 会先进入安装向导数据库连接信息其实已经由环境变量填好直接点下一步、确认配置即可。Zabbix 6.2 默认管理员账号是Admin初始密码是zabbix首次登录后会强制要求改密码。这里要提醒Grafana 数据源后面用的就是这组账号密码建议改成好记但强度足够的密码并把账号密码统一记到密码管理工具里不然监控搭完几个月后想切数据源忘了密码会卡很久。3.4 怎样验证整套环境是否健康登录 Web 界面后先看右上角有没有红色报错。如果提示Zabbix server is not running说明 Web 起来但 Server 没就绪这时不要急着查浏览器先回到命令行看docker compose logs zabbix-server。一个更直接的验证方式是查看 Web 后台的“报告 → 系统信息”页面它会列出 Server 运行状态、数据库版本、同步进程是否正常。同步进程那几项必须都是绿色才说明采集链路是通的。再检查 Grafana访问http://服务器IP:3000默认账号admin/admin首次登录会引导设置新密码。如果能看到 Grafana 首页说明容器、数据卷、插件安装都正常。到这里整套监控平台的地基就算打完了。4. 接入第一台被监控主机4.1 Agent 的容器化部署与宿主机探测Zabbix 的 Agent 有两种工作模式被动模式是 Server 定期连到 Agent 的 10050 端口拉数据主动模式是 Agent 自己连到 Server 的 10051 端口推数据。默认推荐使用主动模式因为 Agent 主动上报能减轻 Server 的连接压力也更容易穿过防火墙。如果你希望被监控对象就是宿主机本身有两个选择。第一个选择是在宿主机直接安装 Agent 二进制包rpm/deb这是最直观的方式监控项的采集能力也最完整因为 Agent 直接跑在宿主机上能看到全部进程和网络状态。第二个选择是用 Compose 文件里的 Agent 容器但容器隔离会导致部分系统指标如磁盘IO、进程列表采集不完整。实际项目中我通常这样分配宿主机采用原生安装 Agent 并配置成主动模式其他容器化应用比如 MySQL、Redis 容器通过挂载宿主机路径或改用容器内 Agent 来实现监控。对于这台演示环境我们先在 Zabbix Web 里添加“当前 Docker 宿主”这块配置让 Server 先通过 Agent 容器探测宿主机的基本状态。想用容器方式监控宿主机系统信息需要给 Agent 容器挂载宿主机的关键文件系统volumes: - /proc:/host/proc:ro - /sys:/host/sys:ro - /:/host/root:ro然后在 Web 端配置主机时自定义的监控项里路径要指向/host/proc等挂载点。这个配置对新手偏进阶如果只是想快速看到数据建议先用原生安装 Agent 的方式。4.2 在 Zabbix Web 添加主机、链接模板进入 Zabbix Web 后台依次操作打开“数据采集 → 主机”点“创建主机”。主机名称填docker-host必须和 Agent 里的ZBX_HOSTNAME一致。“由 Agent 监控的主接口”填写被监控机器的 IP端口默认 10050。“接入”选择“启用”确保状态是已启用。在“模板”区域搜索Linux by Zabbix agent active添加到选中模板列表。保存。保存后等一两分钟回到“主机”列表如果看到主机状态后面的可用性变成绿色说明 Server 已经能从 Agent 拉到数据了。再点进“检测 → 最新数据”筛选主机就能看到 CPU、内存、网络、磁盘等监控项的数据源源不断进来。如果是主动模式模板不需要给 Agent 手动开放端口但 Agent 必须能访问 Server 的 10051如果用了被动模板则反过来要求 Server 能访问 Agent 的 10050。这个方向千万别搞反我见过太多“明明主机显示正常最新数据却一直是空的”案例最后都是模式对应错了。4.3 常见坑主动/被动模式与 SNMP 扩展把主机加进来之后最常见的问题是最新数据一直为空。排查思路按顺序来第一步看“主机”页面可用性标签是不是红色或灰色红色代表 Server 连不上 Agent灰色代表 Agent 没有上报都有明确含义。第二步看 Agent 日志。容器方式可以用docker compose logs zbx-agent重点搜索no active checks、connection refused、cannot connect to这类关键词能直接告诉你网络方向哪里断了。第三步检查模板是否匹配。Linux 模板分 active 和 passive 两个版本链接了 passive 模板却开了主动模式效果也一样采集不到数据。原则是主机的“可用性”走通了但数据是空的九成是模式不匹配。另一个高频需求是监控网络设备比如交换机、路由器。Zabbix 对网络设备走的是 SNMP 协议在创建主机时不需要填 Agent 接口改成填 SNMP 接口版本 v2c 填写团体名通常是public模板选择Net-SNMP或厂商专用模板。做这一步前先确认网络设备上 SNMP 已开启且允许这台监控服务器访问否则界面上一样显示不支持。5. Grafana 接入 Zabbix 数据源与可视化大屏5.1 安装 Zabbix 插件Compose 文件里已经定义了GF_INSTALL_PLUGINS所以 Grafana 启动时插件会自动装上。如果因为某种原因没装上或者你想手动确认可以在容器里执行docker exec -it zbx-grafana grafana-cli plugins install alexanderzobnin-zabbix-app docker restart zbx-grafana插件装完必须重启 Grafana这是很多人漏掉的步骤。装了插件但一直找不到入口重启一下基本就好了。插件安装完成以后从 Grafana 左侧菜单依次进入“Administration → Plugins”应该能看到 Zabbix 插件的卡片图标是一个小方块包含 Z 字标识。如果这里显示的是灰色且标注“unsigned”就需要确认GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS环境变量有没有生效。5.2 配置数据源从 Grafana 左侧菜单进入“Connections → Data sources”搜索Zabbix选择后进入配置页。这里有几个关键字段字段填写值说明URLhttp://zabbix-server/api_jsonrpc.php容器间走网络名不要写 localhostUsernameAdmin 或自定义用户名Zabbix Web 登录账号Password对应密码Zabbix Web 登录密码第一次接触这套配置的人最容易犯的错误是URL 写成了http://localhost/api_jsonrpc.php。如果 Grafana 是容器它访问 localhost 访问到的是自己容器内部不是宿主机的端口。正是因为 Grafana 和 Zabbix Server 在同一个自定义网络里这里直接写服务名zabbix-server才是通的。填好后点击“Save test”如果账号密码和网络正常会返回成功提示并看到 Zabbix API 版本信息。这个测试成功代表 Grafana 已经能调用 Zabbix 的全部数据接口。5.3 导入仪表盘与中文乱码处理数据源配置好后最爽的体验就是直接用社区做好的大屏。Grafana 官网 Dashboards 页面有很多 Zabbix 主题面板图省事的话可以直接搜一张“Zabbix”或“Zabbix Host”相关的面板复制 ID 在 Grafana 里按 Import 导入。不过导入面板有个高频坑面板里用的数据源 UID 可能和实际数据源对不上导入后所有图表都是datasource not found或显示红字报错。解决办法是编辑每个图表把数据源下拉框重新选择成你刚配好的 Zabbix 数据源保存后图表就会恢复。热搜词里那句datasource im7_otuvz was not found基本就是这个场景。内存占用实在紧张的话也可以从零开始配一两个面板选择 Zabbix 数据源查询类型选“Item”或“Trends”通过“Host”和“Item”下拉框直接把某个监控项拖到图上操作路径比想象中简单。还有个绕不开的体验问题Zabbix Web 里的中文监控项名称、主机名在 Grafana 里显示正常但如果 Zabbix Web 本身界面出现方块乱码那是 Zabbix Web 容器缺少中文字体。处理方法参考官网方案在 Web 容器里装fonts-wqy-microhei字体包或者把宿主机的 wqy 字体文件复制到容器的新字体目录再替换/usr/share/zabbix/assets/fonts软链接。Grafana 侧字体是前端渲染基本不用动。6. 高频报错与排查实录6.1 “Zabbix server is not running”的排查思路登录 Web 时右上角出现这句提示是部署阶段最常碰到的报错之一。它说的是 Web 进程没能和 Server 建立正常通信。先不要猜按下面的顺序排查docker compose ps docker compose logs --tail100 zabbix-server docker compose exec zabbix-web sh -c nc -vz zabbix-server 10051docker compose ps看容器是不是反复重启logs看 Server 初始化时有没有数据库连接异常第三条命令测试 Web 容器能不能连上 Server 的 10051 端口。这个组合基本能定位是数据库问题、网络问题还是 Server 进程问题。有一个很容易忽略的点是Zabbix Server 启动需要访问数据库而数据库首次初始化可能要 1-2 分钟。如果 Web 容器比 Server 先完全启动就会出现短暂的这个提示等一会儿刷新页面就恢复了。一看到报错就着急重启容器反而容易把初始化进程打断。6.2 数据库连接失败类问题数据库相关的报错五花八门但根源基本都指向两个密码不匹配或者环境变量没传进容器。比如热搜词里的zabbix access denied for user replace_userlocalhost那个replace_user其实是镜像里环境变量的默认占位符说明 Compose 里没有正确设置 POSTGRES_USER导致 Web 拿了个无效用户名去连数据库。遇到这类问题进入 PostgreSQL 容器里直接测一把docker compose exec postgres psql -U zabbix -d zabbix -c select 1;能查出来说明数据库密码是对的。如果这个命令都报认证失败那就把 Compose 里所有POSTGRES_PASSWORD统一修改然后docker compose down -v清空旧数据卷再重新初始化注意-v删除的是数据卷如果里面有存量数据一定要先备份。6.3 Docker Desktop 在 Windows 上的启动失败如果您是在 Windows 上用 Docker Desktop 做本地演练经常碰到的报错是Virtualization support not detected或者failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。前者说明 BIOS 里虚拟化没开后者说明 Docker Desktop 的后台进程没起来。虚拟化没开的问题要去主板 BIOS 开启 Intel VT-x 或 AMD-VWSL2 模式下还要执行wsl --status如果 WSL 内核版本太老Docker Desktop 也会启动异常执行wsl --update更新内核。这类问题大多是环境问题而不是监控配置问题先把 Docker 跑起来后面的 Compose 配置才谈得上。6.4 Grafana 数据源和面板报错Grafana 侧的高频问题集中在插件和数据源两块。插件加载不出来先看容器日志里有没有插件签名相关的报错或者插件版本和 Grafana 版本不匹配的信息。处理方式在前面已经提过确认GF_INSTALL_PLUGINS环境变量、重启容器、必要时手动安装一次。数据源测试成功但面板没数据通常是面板查询条件里选错了主机或监控项。Zabbix 采集数据的 key 名里带空格和方括号复制过来时要注意别损坏。建议先在 Zabbix Web 的“最新数据”里确认这个监控项确实有数据再回 Grafana 核对查询条件。还有一个常见问题面板导入时报错提示数据源不存在这是 UID 不一致导致的把面板里每个图表的 data source 切换到当前的 Zabbix 数据源并保存即可。修改面板时顺手把时间范围调大一些避免默认最近 6 小时没数据而误判。最后分享一个我自己的习惯整套环境跑顺之后我会把docker compose ps的输出和几个关键容器的健康状态打到日常巡检脚本里每天扫一眼。另外Grafana 插件重启才能生效这点我真的踩过好几次坑所以每次升级 Grafana 后都会顺手docker restart zbx-grafana一下。这套组合的部署难度不算高真正的功夫都在数据积累、告警策略和面板设计上祝各位一次跑通。