Docker Compose部署Zabbix监控平台：完整步骤与避坑指南

简介一套面向运维人员与开发者的 Docker 安装 Zabbix 指南代码包覆盖 Docker Compose 与传统宝塔面板两种部署路线适合在已有服务器或容器环境中快速搭建监控平台。Zabbix 无需在被监控端安装客户端可监控服务器 CPU、内存、磁盘、网络流量及各类网络服务也支持自定义脚本与模板出现异常时通过页面或告警实时提示便于快速定位故障。资源包采用 zip 格式整体仅 11KB解压后共 5 个文件以 Compose 服务编排文件、Markdown 说明文档、HTML 预览页和配套配置文件为主其中编排文件负责定义 Zabbix Server、MySQL 与前端容器说明文档则给出环境变量、端口映射及启动步骤结构清晰、可按需参照。已有 41 人学习适合希望快速掌握容器化监控部署的初学者和运维人员。借助这套资料可少走弯路直接复用两种部署方案的关键配置并在此基础上扩展自定义监控模板与告警规则快速形成可落地的监控能力。1. 为什么用Docker跑Zabbix——先想清楚再动手监控系统这件事我前前后后折腾过好几轮了。最早是在裸机上编译安装Zabbix依赖关系一团乱麻PHP扩展、MySQL版本、前端资源文件任何一个环节版本对不上都能让你耗掉一整天。后来切到 Docker 方式部署思路一下就顺了——镜像拉下来、compose 文件一写、容器启动半小时内就能看到一个能用的监控平台。这篇文章就以 Docker 安装 Zabbix 为主线把完整的部署步骤、参数选型逻辑和真实踩坑记录都整理出来给正要上手的人一条能直接走通的路。1.1 容器化解决了传统部署的哪些痛点传统编译安装 Zabbix 的痛苦经历过的人都懂。Zabbix Server 依赖的编译选项、PHP 扩展版本、前端和数据库之间的字符集匹配任何一个环节出了偏差页面要么白屏要么报错信息看不懂。更别说升级的时候数据迁移和配置备份都像走钢丝。Docker 把这些依赖全部封装进镜像里底层环境不一致的问题直接从根源上消失。容器化的另一个优势是“可丢弃、可重建”。测试环境里配坏了容器删掉重来几分钟恢复原状这个体验在传统部署里是想都不敢想的。我自己的习惯是先在本地或测试机用 Docker 把整套平台跑通验证监控模板、告警策略都符合需求之后再考虑要不要搬到生产环境。这个流程里 Docker 扮演的角色就是一个“快速验证器”帮你在正式落地之前把所有坑都提前踩一遍。1.2 哪些场景适合容器化部署不是所有场景都适合 Docker 跑 Zabbix这个话我得说在前面。我个人的判断标准很简单如果业务监控规模在几百台设备以内Docker 方式完全够用如果设备量到了几千甚至上万台还是建议老老实实用物理机或虚拟机部署方便做资源隔离和性能调优。具体来说适合容器化部署的场景主要有这么几类开发测试环境、中小型企业的统一监控平台、需要快速交付给客户演示的 POC 项目、以及想学习 Zabbix 功能但没有专属服务器的个人用户。不适合的场景则包括已有大规模监控体系需要平滑迁移的生产环境以及对数据安全要求极其严格、必须物理隔离的内网环境。判断清楚场景再动手能帮你省掉后面很多不必要的麻烦。2. 部署前的准备工作——环境规划和版本选型部署之前先把环境理清楚能避免后面大部分问题。这里说的环境不只是硬件和操作系统还包括你对“要用哪个版本、跑哪些组件、数据放哪里”这些问题的明确答案。2.1 服务器配置要求与 Docker 环境检查Zabbix 由多个组件组成最核心的三个是 Server负责数据采集和计算、Database存储配置和历史数据、Web 前端负责展示和配置。这三者如果全跑在一台机器上我建议配置至少 4 核 CPU、8G 内存磁盘根据监控数据量决定历史数据默认保留 90 天的话100 台设备大概需要 40GB 到 80GB 的存储空间。Docker 本身需要操作系统内核版本大于 3.10CentOS 7 和 Ubuntu 16.04 以上的系统基本都满足条件。安装完成后先用两条命令验证一下环境docker --version docker compose version如果docker compose version提示找不到命令说明你的 Docker 版本较老或者没有安装 Compose 插件。2.x 版本的 Docker 已经内置了 Compose 插件直接用docker compose注意中间没有短横线即可如果你还在用老版本建议直接升级 Docker而不是单独折腾 docker-compose 二进制文件。2.2 镜像版本选择与网络规划Zabbix 官方镜像分为两个大的 tag 系列Alpine 版和 Ubuntu 版。Alpine 版体积小、资源占用低适合生产部署Ubuntu 版兼容性更好、里面带的调试工具更全适合拿来排查问题。两个版本功能上没有任何差异我建议生产环境用 Alpine 版省资源。版本号方面目前主流选择是 6.4 LTS 和 7.0 LTS。7.0 是最新的大版本界面和功能都有不少更新新部署直接选 7.0 就行。我这里以 Zabbix 7.0 LTS 为例你需要准备以下这些镜像zabbix/zabbix-server-mysql:7.0-alpine核心监控服务zabbix/zabbix-web-nginx-mysql:7.0-alpineWeb 前端 Nginxzabbix/zabbix-java-gateway:7.0-alpine可选组件用于监控 Java 应用JMXmysql:8.0数据库端口规划方面默认情况下需要占用宿主机 80 端口Web 界面、10051 端口Server 监听 Agent 数据、10052 端口Java Gateway。如果宿主机 80 端口已经被占用可以在映射时改成其他端口例如8080:80。数据库 3306 端口建议不要暴露到宿主机只在容器间通讯这样更安全。3. Docker Compose 完整部署 Zabbix——从零到能访问部署方式我强烈推荐用 Docker Compose而不是一个个docker run去敲。原因很简单Zabbix 这套系统组件之间存在明确的启动顺序和依赖关系Compose 可以帮你一次性定义好所有服务并自动处理依赖关系。以后要停止、重启、查看日志一条命令搞定。3.1 编写 docker-compose.yml 文件先创建项目目录和配置文件mkdir -p /opt/zabbix cd /opt/zabbix vim docker-compose.yml以下是完整的docker-compose.yml文件内容我加了详细注释方便你理解每个字段的作用version: 3.8 services: mysql: image: mysql:8.0 container_name: zabbix-mysql command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_bin - --default-authentication-pluginmysql_native_password environment: MYSQL_DATABASE: zabbix MYSQL_USER: zabbix MYSQL_PASSWORD: zabbix_pwd MYSQL_ROOT_PASSWORD: root_pwd volumes: - ./data/mysql:/var/lib/mysql restart: always zabbix-server: image: zabbix/zabbix-server-mysql:7.0-alpine container_name: zabbix-server environment: DB_SERVER_HOST: mysql MYSQL_DATABASE: zabbix MYSQL_USER: zabbix MYSQL_PASSWORD: zabbix_pwd ZBX_JAVAGATEWAY: zabbix-java-gateway ZBX_JAVAGATEWAY_ENABLE: 1 ports: - 10051:10051 volumes: - ./data/alertscripts:/usr/lib/zabbix/alertscripts - ./data/externalscripts:/usr/lib/zabbix/externalscripts depends_on: - mysql restart: always zabbix-java-gateway: image: zabbix/zabbix-java-gateway:7.0-alpine container_name: zabbix-java-gateway restart: always zabbix-web: image: zabbix/zabbix-web-nginx-mysql:7.0-alpine container_name: zabbix-web environment: ZBX_SERVER_HOST: zabbix-server DB_SERVER_HOST: mysql MYSQL_DATABASE: zabbix MYSQL_USER: zabbix MYSQL_PASSWORD: zabbix_pwd PHP_TZ: Asia/Shanghai ports: - 80:8080 depends_on: - zabbix-server - mysql restart: always有几个细节需要特别说明。第一MySQL 8.0 默认的认证插件是caching_sha2_password而 Zabbix Server 的某些版本连接 MySQL 8.0 时会因为认证方式不兼容而报错所以我在 MySQL 的 command 里显式指定了--default-authentication-pluginmysql_native_password这是从 5.x 时代过来的人都知道的老坑新版虽然默认用新插件但兼容性考虑还是加上放心。第二ZBX_JAVAGATEWAY_ENABLE这个参数在 6.0 之后的版本可以省略因为默认就启动写上也不影响但如果你要监控 Java 应用比如 Tomcat、Kafka就一定要保留。第三Web 容器内部监听的是 8080 端口映射到宿主机 80访问http://IP即可不用带端口号。3.2 启动服务并验证所有容器状态配置文件写好后启动命令非常简单docker compose up -d-d参数表示后台运行。第一次启动需要拉取镜像时间取决于网络状况耐心等待即可。启动完成后查看容器状态docker compose ps正常情况下四个容器都应该是running状态。用docker compose logs -f zabbix-server查看 Server 日志看到类似server #0 started [main process]的信息说明 Server 已经正常启动了。这里有个小技巧MySQL 容器初始化数据库需要一段时间如果 Zabbix Server 在 MySQL 完全初始化之前就尝试连接它会在日志里反复报连接失败的错误这是正常的容器会自动重试。看到这个报错不用慌等一两分钟再看日志连接成功后就正常了。3.3 初始化 Web 界面并完成基础设置容器全部启动后打开浏览器访问http://你的服务器IP首次访问会进入 Zabbix Web 安装向导。这一步虽然简单但有两个需要注意的地方。第一步是数据库连接信息配置界面上的数据库主机要填mysql也就是 compose 文件里的服务名而不是localhost或127.0.0.1。因为 Web 容器是独立于宿主机运行的它访问数据库是通过 Docker 内部网络直接用服务名mysql才能正确解析到数据库容器的 IP。这是我见过初学者最容易犯错的地方填了localhost会一直提示无法连接数据库。第二步是 Zabbix Server 地址配置填zabbix-server服务名即可。这两个核心地址填对之后后面的步骤基本就是一路下一步。初始化完成后默认管理员账号是Admin注意大写 A密码是zabbix。登录后第一件事建议点击右上角头像把语言改为中文。如果界面上中文显示为方块乱码那是中文字体缺失的问题下面的实战排坑章节会专门讲怎么处理。3.4 数据持久化与日常备份容器的一个特点是“临时性”——容器删掉里面的数据也没了。为了让监控数据不随容器销毁我在 compose 文件里挂载了三个数据卷MySQL 的数据目录、告警脚本目录用于自定义告警和外部脚本目录用于自定义监控项。日常备份建议只备份 MySQL 数据卷即可。用docker compose exec mysql mysqldump -uzabbix -pzabbix_pwd zabbix /backup/zabbix_backup.sql导出数据库或者直接打包挂载出来的./data/mysql目录虽然不够优雅但胜在简单适合快速恢复场景。告警脚本和外部脚本因为是我们自己维护的文件备份的时候别忘了把这两个目录也带上。4. 核心配置与实战排坑——那些文档里不会写的事部署只是一个开始真正让 Zabbix 用起来配置和排坑才是重头戏。这一节我把实践中反复遇到的问题整理出来分门别类地讲清楚原因和解决办法。4.1 Zabbix 中文乱码与时间时区问题中文乱码是 Zabbix 使用中文界面时最常见的问题根源在于 Zabbix Web 镜像默认没有安装中文字体。解决办法是找一个中文字体文件放到容器里并刷新字体缓存。# 下载一个开源中文字体比如思源黑体 wget https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/SourceHanSansSC-Bold.otf # 复制到 Web 容器内 docker cp SourceHanSansSC-Bold.otf zabbix-web:/usr/share/zabbix/assets/fonts/ # 进入容器刷新字体缓存 docker exec -it zabbix-web sh cd /usr/share/zabbix/assets/fonts rm -f graphfont.ttf ln -s SourceHanSansSC-Bold.otf graphfont.ttf exit做完这些回到 Web 界面刷新中文乱码就解决了。注意一定要用软链接的方式因为 Zabbix 代码里写死了字体文件名叫graphfont.ttf替换文件名而不更新软链接是无效的。时区问题则是在 compose 文件中设置PHP_TZAsia/Shanghai环境变量。如果不设置前端页面上显示的图表时间会默认使用 UTC 时间比北京时间慢 8 小时监控数据时间对不上排查起来非常头疼。这个参数在部署时就要留好后面改要重建容器才能生效。4.2 钉钉机器人告警配置的完整思路告警是监控系统的灵魂Zabbix 的告警方式从最初的邮件、短信到现在国内用得最多的钉钉机器人。钉钉告警的原理是Zabbix Server 在告警触发时执行一个脚本脚本调用钉钉开放平台的 Webhook 接口把消息推送到钉钉群。配置过程分三步走。第一步在钉钉群里添加一个自定义机器人得到一个 Webhook 地址形如https://oapi.dingtalk.com/robot/send?access_tokenxxxxxx。第二步在宿主机上准备告警脚本/opt/zabbix/data/alertscripts/dd.py脚本内容核心就是调用 Webhook 接口发送 HTTP POST 请求。第三步在 Zabbix Web 端配置“告警媒介类型”Media Type把脚本路径和参数告诉 Zabbix。我分享一个精简版的 Python 脚本可以直接保存为dd.py使用#!/usr/bin/env python3 import sys import requests import json webhook_url https://oapi.dingtalk.com/robot/send?access_token你的TOKEN def send_message(msg): headers {Content-Type: application/json} data { msgtype: text, text: { content: msg } } try: r requests.post(webhook_url, headersheaders, datajson.dumps(data)) print(r.text) except Exception as e: print(Send failed: %s % str(e)) if __name__ __main__: send_message(sys.argv[1])脚本写好后记得chmod x dd.py并在宿主机上先手动测试一下能不能正常发消息确认没问题了再配置到 Zabbix 里。4.3 常见问题速查表根据社区里大家反馈最多的问题我整理了一张速查表这些问题我基本全都遇到过问题现象根本原因解决方案Web 界面“无法连接数据库”数据库主机地址填错确认 Web 端 DB 主机填的是mysql服务名不是 localhostdocker compose报权限错误当前用户不在 docker 用户组执行sudo usermod -aG docker $USER后重新登录或直接使用 sudo 执行验证失败/Zabbix Server 未运行Server 容器反复重启用docker compose logs zabbix-server查看日志重点排查 DB 连接配置图表显示时间差 8 小时未设置 PHP_TZ重建 Web 容器并设置PHP_TZAsia/Shanghai监控中文字体乱码容器内缺少中文字体按 4.1 的方法替换 graphfont.ttfDocker 镜像下载缓慢默认使用官方源配置国内镜像加速器推荐阿里云或腾讯云的镜像源History syncer processes 超过 75%历史数据量大写入跟不上调大HistoryCacheSize参数或清理历史数据zabbix server: utilization of history syncer processes over 75%这个告警几乎是每个 Zabbix 运维都会遇到的经典问题。它表示 Server 接收到的监控数据量超过了历史数据同步进程的处理能力。最直接的解决方案是加大HistoryCacheSize配置默认值是 16M可以调到 128M 或更高同时在 MySQL 层面优化历史表的写入性能。如果数据量持续增长还是建议从监控频率上做优化——把不必要的监控项采集间隔调大减轻 Server 压力。4.4 镜像下载慢的解决与 Docker 权限问题的根治国内拉取 Docker 官方镜像的速度之慢相信大家都深有体会。解决方法是配置镜像加速器。以阿里云为例登录阿里云容器镜像服务控制台每个账号都有一个专属加速地址在/etc/docker/daemon.json里配置{ registry-mirrors: [https://你的专属加速地址.mirror.aliyuncs.com] }配置完执行sudo systemctl restart docker重启 Docker 服务再拉镜像速度会快很多。这个配置建议在部署 Zabbix 之前就做好否则等拉mysql:8.0这种几百兆的镜像时那种干着急的感觉确实不好受。Docker 权限的问题则是在 Linux 环境下运行docker命令报permission denied while trying to connect to the docker api at unix:///var/run/docker.sock。这个报错的原因是当前用户不在docker用户组执行sudo usermod -aG docker $USER把用户加进去然后退出重新登录即可。需要注意的是添加用户组不会对当前已存在的会话立即生效一定要重新登录或者newgrp docker切换一下。5. 让监控真正生效——添加主机与自定义监控项部署好平台只是第一步接入监控设备才算真正开始发挥价值。添加主机这一步的操作路径是进入“数据采集”-“主机”-“创建主机”。需要填写的核心信息有主机名称、可见名称可选、监控方式默认 Agent、Agent 客户端的 IP 地址和端口默认 10050、以及把要应用的主机组和模板关联上。模板相当于一组预定义的监控项、触发器和图形。比如监控一台 Linux 服务器关联Linux by Zabbix agent模板系统就会自动采集 CPU、内存、磁盘、网络等几十项基础指标。如果你是从 5.x 时代过来的老用户会注意到 7.0 版本里模板列表里带上了“by Zabbix agent”的新命名规范实际用起来没有本质差别。对于支持 SNMP 的网络设备交换机、路由器、防火墙在添加主机时把监控方式改为 SNMP填好团体名Community默认 public或 SNMP v3 的认证信息再关联对应的设备模板即可。这一步的关键是要确保监控服务器和设备之间的网络是通的且设备的 SNMP 服务已开启。很多人在这一步卡住其实 90% 的原因就是防火墙挡了 UDP 161 端口检查连通性时记得用snmpwalk而不是ping。6. 日常运维技巧——让 Zabbix 更省心部署完成、监控上线之后日常运维主要围绕备份、升级和容量管理三件事展开。备份策略我在 3.4 已经提过这里补充两个升级相关的注意事项。升级 Zabbix 容器版本时一定先备份数据库。Zabbix 升级时会自动执行数据库迁移脚本一旦出问题很难回滚。升级步骤是把 compose 文件里镜像的 tag 从7.0-alpine改为7.2-alpine假设你要升级到 7.2然后执行docker compose pull拉取新镜像再docker compose up -d重建容器。重建后观察日志确认数据库迁移成功、Server 正常启动后再继续使用。容量管理方面Zabbix 的 MySQL 数据增长非常快尤其是历史数据表history和trends这两张表。建议定期查看这两张表的大小如果磁盘空间紧张可以通过 Zabbix 的“维护”功能缩短数据保留周期或者在 MySQL 层面手动清理过期数据但更推荐的做法是开启 Zabbix 自带的分区功能或使用timescaledb扩展来管理超大数据集。最后再分享一个我个人的小习惯在 Zabbix Web 界面右上角的“配置”-“用户”里把管理员密码改掉并建立一个“只读”权限的普通用户给同事查看监控大屏用。这样既能保证系统安全又避免别人手滑把监控项配置改乱了。另外Docker 容器的日志会持续增长建议把 compose 文件里的服务都加上logging配置限制单个日志文件的大小否则跑半年下来docker logs的输出文件能轻松占用几个 GB 磁盘空间这个细节知道的人确实不多。本文还有配套的精品资源点击获取