zabbix-deploy

Zabbix 单机 Docker 部署（zabbix-deploy）

本仓库托管 Zabbix 服务器单机 Docker Compose 部署文件与配置审计说明。

组件与版本

• zabbix/zabbix-server-mysql:ubuntu-7.4.16
• zabbix/zabbix-web-nginx-mysql:ubuntu-7.4.16
• mysql:8.0.43

镜像均为精确版本锁定，避免 docker compose pull 时被悄悄升级到新大版本。

文件

• docker-compose.yaml —— 生产用编排文件（当前 7.4.16）
• compose-audit.md —— 原 compose 的问题审计与缓存容量重估说明
• bootstrap/zbx-bootstrap.py —— 「自监控-only」清理脚本（启动后摘除自身 agent 模板）
• bootstrap/docker-compose.bootstrap.yaml —— 可选叠加编排：随 up 自动运行上述脚本

自监控-only：服务器自身主机不挂 agent（2026-11 变更）

Zabbix 服务端首次启动会自动创建名为 Zabbix server 的自身监控主机，默认挂 Linux by Zabbix agent + Zabbix server health。由于本机不安装 zabbix-agent， agent 那批项永远空采，还会周期性尝试连本机 10050 而产生 "agent 不可用" 类无效告警/报错。

已做的调整（手工，一次）：

1. 解除自身主机上的 Linux by Zabbix agent 模板（连带其监控项/触发器），仅保留 Zabbix server health —— 即“自己监控自己、不连 agent”，不再报错。
2. 关闭了遗留的 "Linux: Zabbix agent is not available" 触发器。
3. 首页 Global view 中原引用 agent 项（Available memory / CPU utilization）的 svggraph 已改指向自身内部项 Configuration cache, % used / History write cache, % used （重命名为「Cache usage」），避免图报 "item not found"。

本机仍保留 11 个与未启用进程（IPMI/Java/Report/VMware/Connector 等）相关的内部项， 但已禁用，不会产生红点/报错。

启动即自动化（可选）：bootstrap 辅助容器

想让 docker compose up 时自动完成上面第 1 步（摘除自身 agent 模板），用附带的 叠加编排即可，无需改 Zabbix 源码：

# 启用（每次 up 自动跑一次；幂等）
docker compose -f docker-compose.yaml -f bootstrap/docker-compose.bootstrap.yaml up -d

# 手动单独重跑一次
docker compose -f docker-compose.yaml -f bootstrap/docker-compose.bootstrap.yaml run --rm zbx-bootstrap

• 原理：一次性容器 python:3.12-slim 运行 bootstrap/zbx-bootstrap.py，轮询等 API 就绪， 再用 API 把「服务器自身主机」（带 Zabbix server health 模板的那台）上的 Linux by Zabbix agent 模板摘除；已干净则跳过。
• 认证：默认 Admin/zabbix 登录；生产建议在 .env 设置 ZBX_API_TOKEN（API Token）， 脚本会优先使用它。
• 局限：python:3.12-slim 镜像首次拉取需外网；该步只负责“摘除自身 agent 模板”， 首页那张 CPU/内存图的重指向属展示层，可在 UI 手动改（见上）。

部署位置

• 服务器：10.160.10.213
• 部署目录：/opt/zabbix
• Web 访问：http://192.168.87.20:8080/

首次/变更部署步骤

cd /opt/zabbix
cp -f docker-compose.yaml docker-compose.yaml.bak_$(date +%s)   # 先备份
docker compose -f docker-compose.yaml config -q                 # 语法校验
docker compose -p zabbix up -d                                  # 重建生效
docker compose -p zabbix ps                                     # 查看状态

升级步骤（同大版本补丁升级，如 7.4.x → 7.4.y）

1. 备份数据库（务必）：

   docker exec -i zabbix-mysql sh -c \
    'MYSQL_PWD=****** mysqldump -uroot --single-transaction --quick \
     --routines --triggers --events --set-gtid-purged=OFF zabbix' \
    | gzip > /opt/zabbix/backup/zabbix_$(date +%Y%m%d_%H%M%S).sql.gz
   gzip -t /opt/zabbix/backup/zabbix_*.sql.gz   # 校验完整性
   

2. 修改 docker-compose.yaml 中 server / web 镜像 tag 到目标版本。

3. docker compose -p zabbix up -d，server 启动时会自动执行数据库结构升级（日志中可见 starting automatic database upgrade ... fully completed）。

4. 校验：docker exec zabbix-server zabbix_server -V，以及 Web HTTP 200、采集速率恢复正常。

注意：补丁升级可能推进数据库 optional 版本（例如 7.4.2→7.4.16 为 07040000→07040011），回滚需还原备份，因此第 1 步不可省略。

关键环境变量（可在 .env 覆盖）

• MYSQL_ROOT_PASSWORD / MYSQL_PASSWORD（默认已内置，建议外部 .env 管理）
• TZ（默认 UTC，可按需设为 Africa/Casablanca 等）
• 缓存：ZBX_CACHESIZE、ZBX_VALUECACHESIZE、ZBX_TRENDCACHESIZE、ZBX_HISTORYCACHESIZE、ZBX_TRENDSINDEXCACHESIZE 等
• 采集进程：ZBX_STARTSNMPPOLLERS、ZBX_STARTLLDWORKERS、ZBX_STARTPREPROCESSORS

端口

• Zabbix Server：10051
• Web（nginx）：容器内 8080 / 8443
• MySQL：容器内 3306（不对外暴露）

L2 物理拓扑（WecomCenter 模块扩展）

模块 web-modules/WecomCenter 现包含 L2 物理拓扑 功能（展示页 + 配置页 + 采集器 + 历史库）：

• 展示页：Monitoring → L2 Topology（只读）。一张全局大拓扑图：从左到右固定为 核心（可多个）→ 各网络主交换 → 各车间汇聚/分布 → 接入，一级交换机一列，不再拆成卡片或车间详情页。 每个车间一个框（包住该车间的汇聚+接入），框内再按 GRD→1F→3F→4F→7F 楼层画小框；同一车间若跨网络 则拆成两个独立框，只连接各自网络的上游。所有链路均为单段直线，从上级标签左缘中点画到下级标签左缘中点， 上级标签可遮盖出口，目标标签不被遮挡；接入下还有接入时按层级向右加一列（不改协议连接关系）。 含时间轴/终端/离线/搜索/速率&延迟&告警着色；正常在线链路带从核心向下游流动的数据动画（速率越高流动越快）， 右上角「导出图片」始终按日间模式导出 PNG（导出图为静态实线，不把动画虚线烘焙进图片）。 PoE 交换机由采集器读取华为 POE MIB / RFC3621 判定，名称前自动加 ⚡️。 主题自动跟随 Zabbix 明暗模式，无手动深色开关。
• 配置页：Administration → ROMAN 定制中心 → 「L2 拓扑」（采集模板、刷新/采集间隔、速率配色、 延迟阈值、分组规则、根框名、物理网络定义、核心交换机定义等）。物理网络按每行 KEY | 显示名称 | 名称/IP关键字 | 颜色 配置，交换机归入第一个名称或 IP 包含关键字的网络； 核心交换机按行选择网络并填写名称/IP 匹配规则，同一网络可定义多个核心，全部固定在左侧核心列。
• 数据：每次全量采集把快照 gzip 写入 MySQL l2_topology_history（保留 7 天，可回看任意时间）； 配置存 l2_topology_config，并镜像 assets/l2topology/config.json。
• 表结构：L2Store::ensureSchema() 幂等建表；wecom-module-init 侧车在 up 时也会建表。

docker-compose 一键启用

up -d 时：web-modules/ 挂入 web 容器 → wecom-module-init 自动登记并启用模块、创建 L2 表。 全新环境无需进 UI 点启用。WEB_MODULES_DIR 可覆盖挂载源路径。

采集器（宿主机）

采集器在 collector/，需装到 /opt/zabbix/l2collector/ 并用 cron 调度（容器无法直接读交换机 SNMP）。 详见 docs/使用说明.md 第 10 章。只采集配置页所选模板（默认 Huawei VRP by SNMP (walk)）的主机。