Главная Обзор Помощь
Вход
FlyingRome
/
zabbix-deploy
2
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: master
Ветки Метки
zabbix-deploy
/
docs
/
使用说明.md

使用说明.md 22 KB
Постоянная ссылка История Исходник

ROMAN 定制中心 — 使用与部署说明

适用版本：Zabbix 7.4.x（已在 7.4.16 / MySQL 8.0.43 验证）。 一个自包含、多语言的 Zabbix 前端模块（custom module / plugin）。加载后会在 Administration → ROMAN 定制中心 增加一个定制页面，分 告警 / 优化 / 日常维护 / L2 拓扑 四个标签页。

1. 它能做什么（一句话版）

标签页 关键能力
告警 Alert 企业微信群机器人 key 设置与测试；5 套告警策略预设（先预览 → 再应用）；手动勾选会通知的严重度；一键刷新（写入模板触发器 / 触发器原型 / 已发现触发器，全部节点生效）。
优化 Optimization 服务端调优参数生成（只生成 .env/compose 片段与重建命令，不落地，运维自行重建）；真实华为模板 →「导入」→「切换」迁移设备；Geomap 单点标记。
日常维护 Maintenance 按类别批量改告警等级；按单个触发器精确调整：勾选开关告警 + 行尾下拉改严重度；保存后页面自动刷新。
L2 拓扑 Topology 一张只读全局物理拓扑；STP/MAC 协议关系、7 天快照历史、单面板时间选择器；PNG 导出、终端端口矩阵、告警/离线/延迟/速率着色。

所有改动都走 Zabbix 官方 API / 受控 SQL 写进数据库，所以换机器、重建容器、升级镜像，配置都在——只要「加载插件」即可复用。

2. 部署

2.1 全新 Zabbix（推荐，一条命令就有插件）

仓库自带的 docker-compose.yaml 已经把「插件随仓库走 + 自动启用」做好：

git clone <本仓库地址> zabbix-deploy
cd zabbix-deploy

# （可选）已有环境的模块目录在别处时，用环境变量覆盖，默认是仓库同级的 ./web-modules
# export WEB_MODULES_DIR=/opt/zabbix/zabbix-server/web-modules

docker compose up -d

启动后：

  • 文件层面：./web-modules/WecomCenter 被挂到容器 /usr/share/zabbix/modules/WecomCenter。
  • 数据层面：一次性服务 wecom-module-init 会等 MySQL 和 Zabbix 的 module 表就绪后，把 wecom_center 登记为 已启用（status=1），并创建 L2 两张表。脚本是幂等的：已存在就不动，重复 up 也安全；不会因首次建库时序而失败。

也就是说：全新环境 up -d 完，什么都不用点，插件已经在了。

2.2 已有 Zabbix（手动装）

  1. 确认 web 容器挂载了持久化的 modules 目录（否则重建容器文件会丢）：

    zabbix-web-nginx-mysql:
 volumes:
   - /opt/zabbix/zabbix-server/web-modules:/usr/share/zabbix/modules

  2. 把 web-modules/WecomCenter 整个目录拷到宿主那台目录下（即 .../web-modules/WecomCenter/）。

    • 也可用自带脚本：cd web-modules && ./install.sh（自动探测运行中的 zabbix-* web 容器并复制进去；或 ./install.sh /usr/share/zabbix/modules）。脚本会顺带建 L2 表，并在 module 表已就绪时自动登记/启用 wecom_center；复制前还会扫描 PHP/JS 源文件，发现 UTF-8 双重编码乱码会直接报错退出。

  3. docker compose up -d 重建 web 容器使挂载生效（只重启 web，数据不动）。

  4. 若脚本提示 module 表尚未就绪，等 Zabbix 首次启动完成后，进 Administration → General → Modules → Scan directory → 启用 WecomCenter；也可以手工执行：

    SET @nid := (SELECT COALESCE(MAX(moduleid),0)+1 FROM module);
INSERT INTO module(moduleid,id,relative_path,status,config)
SELECT @nid,'wecom_center','modules/WecomCenter',1,'[]'
WHERE NOT EXISTS (SELECT 1 FROM module WHERE id='wecom_center');

2.3 换环境 / 升级镜像

  • 换机器：把仓库（含 web-modules/）拉过去，按 2.1 或 2.2 重来即可；数据库卷保留则配置不丢。
  • 升级镜像：镜像锁定精确版本（ubuntu-7.4.16），up -d 重建后插件仍在（文件在挂载目录、启用记录在 DB）。

2.4 部署验证

  1. 左侧菜单出现 Administration → ROMAN 定制中心，点开能看到四个标签页（告警 / 优化 / 日常维护 / L2 拓扑）即成功。
  2. 打开 日常维护 页能搜到触发器、每行右侧有严重度下拉，说明读写链路正常。
  3. 看 /opt/zabbix/zabbix-server/web-modules/WecomCenter/manifest.json 与 DB 的 module 行（id=wecom_center,status=1）。

3. 首次初始化（告警链路一键补全）

安装后第一次打开 ROMAN 定制中心 → 告警 页，会显示 First-time setup / 首次配置：

  1. 粘贴企业微信群机器人 webhook 的 Key（就是 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=... 里 key= 后面那串）。
  2. 点 初始化环境 / Initialise（自检）。它会自动补齐整条告警链路，缺啥建啥、已存在则复用，可反复点当作自检：
对象 作用
全局宏 {$WECOM_KEY} 存放机器人 key（换机器人只改这一格）
媒体类型 WeCom Group Robot type=4 webhook，内置发送脚本（markdown，失败回退 text）
机器人用户 wecomrobot 挂上面这个媒体类型，severity = High + Disaster
触发器动作 Send alarm by Wecom Robot 告警发红字、恢复发绿字，均带 {$ZBX_URL} 直达详情链接

群机器人就是「往群里发一条消息」，没有收件人账号/接收目标的概念，所以这里不设真人接收者，只维护一个机器人账号承载媒介。

拓扑初始化：同一次「初始化 / 自检」也会幂等创建 L2 拓扑的 l2_topology_history / l2_topology_config，并在配置行缺失时写入默认配置（已有配置绝不覆盖）。如果只想初始化拓扑、不碰告警链路，到 ROMAN 定制中心 → L2 拓扑 顶部点 「初始化 / 自检 L2 存储」 即可。采集器 cron 仍需按 10.4 在宿主机安装，容器不会替你做 SNMP 采集。

4. 页面使用详解

4.1 告警 Alert

  • 机器人 key：单字段读写全局宏 {$WECOM_KEY}；点 发送测试 会直接打企微接口，返回 errcode:0 即通。
  • 告警策略预设：内置 5 套（稳健运维 / 只保命 / 全量观察 / 夜间降噪 / 核心从严）。
    • 先「预览」(dry-run，不写库)：按类别列出将改动多少触发器。
    • 再「应用」：①设媒介严重度阈值；②把「模板触发器、触发器原型、已发现(LLD)触发器」按类别批量改严重度。必告警类别一律钉到灾难 Disaster(5)，所以阈值再高也必然发出。可重复执行、可回滚。
  • 手动阈值：勾选「会通知」的严重度 + 总开关（写媒介 severity 位掩码 / active）。
  • 一键刷新：应用/保存后，改动通过 API 立即下发模板、通过受控 SQL 写已发现触发器；所有探测节点（模板 → 主机）都会同步。前端读库即时可见，Zabbix server 配置缓存约 60 秒内自动同步到告警判定。

4.2 优化 Optimization

  • 服务端调优生成器：选 小/中/大 规模，生成 StartSNMPPollers 等 .env/compose 参数与重建命令。只生成、不落地，由运维复制到主机自行 docker compose up -d 重建 server（零风险、零特权）。
  • 模板导入：内置的是真实的华为模板 Huawei VRP by SNMP walk（导出文件在 templates/），点「导入」即导入 Zabbix（已存在则就地更新，新模板则新建）。
  • 模板切换（迁移设备）：选「旧模板 → 新模板」→ 预览列出受影响设备 → 确认切换，把每台设备的模板链接替换为新模板（保留其它链接、去重）。
  • 地图标记：以 单点（Zabbix server 主机） 作代表点设置经纬度。 > Geomap 底图需浏览器能访问外网加载 OSM 瓦片；纯内网底图会空白，但标记点逻辑正确。

4.3 日常维护 Maintenance（本次重点）

A. 按类别批量改告警等级

  1. 「Trigger class」选一个类别（设备离线 / 硬件故障 / 重启 / 核心链路 / 接口 down / 性能 …；other 不参与）。
  2. 「Set severity to」选目标严重度（Not classified … Disaster）。
  3. 点 Apply。会把该类别下的模板触发器、触发器原型、已发现(LLD)触发器一次性改到该等级，并自动刷新列表。
    • 与「策略引擎」同一套写入逻辑，完全可逆；适合「把某一类警报统一拉高/压低」。

B. 按单个触发器精确调整

  1. 顶部搜索框输入关键字（如 Temperature）→ 点 Search（最多显示 200 条；全库可能有数万个触发器）。
  2. 每一行：
    • 左侧 勾选框：勾选 = 启用告警，取消 = 停用该触发器（写 trigger.status，0 启用 / 1 停用）；
    • 右侧 下拉框：直接选该触发器的严重度（0–5）。
  3. 改完点 Save，页面自动刷新，结果立即列出；server 配置缓存约 60 秒内同步到告警判定。

所有调整只改 triggers.priority / triggers.status，不删除任何对象。对「已发现(LLD)触发器」因 Zabbix API 不允许改其 priority，改用受控 SQL 精确更新，可逆。

5. 严重度对照

等级 priority 媒介位掩码
未分类 Not classified 0 1
信息 Information 1 2
警告 Warning 2 4
一般严重 Average 3 8
严重 High 4 16
灾难 Disaster 5 32
  • 触发器「是否告警」= trigger.status（0 启用 / 1 停用）。
  • 媒介「是否生效」= media.active（0 启用 / 1 停用），严重度用位掩码。

6. 多语言

  • 共 35 个语言文件，覆盖 Zabbix 全部 locale（en_GB/en_US 共用英文），与 Zabbix 语言数量一致。
  • 已人工翻译：zh_CN、zh_TW、ja_JP、ko_KR、ru_RU、de_DE、fr_FR、es_ES、pt_BR、it_IT、pl_PL、tr_TR。
  • 其余语言文件存在，运行时自动回退英文（页面照常工作，不报错）。
  • 模块按当前用户界面语言自动切换。新增/完善某语言：复制 locale/en.php 为 locale/<lang>.php，只改 value、键名不变即可。

7. 常见问题（FAQ）

Q：改完严重度，为什么告警没立刻变？ A：页面（读数据库）会立刻显示新值；Zabbix server 的「配置缓存」约 60 秒（CacheUpdateFrequency）刷新后才作用于告警判定。这是 Zabbix 机制，不是插件问题。

Q：地图是空白的？ A：Geomap 底图依赖浏览器访问外网 OSM 瓦片；纯内网会空白，但标记点逻辑正确。

Q：会不会误伤生产触发器？ A：不会。所有操作都要你主动点 Apply / Save 才写库；「预览」不写库；改动仅限 priority / status，不删对象，且可用备份回滚。

Q：换机器人 key 要改哪里？ A：只改页面「机器人 key」一处（即全局宏 {$WECOM_KEY}），或 Administration → Macros。

Q：能在非 docker 的 Zabbix 上用吗？ A：可以。把 WecomCenter/ 放到 modules 目录、启用模块即可（见 2.2）。

Q：升级 Zabbix 会丢插件吗？ A：不会。插件文件在宿主持久化目录、启用记录在数据库；只要目录与数据库卷保留，升级镜像后仍在。

8. 目录结构

zabbix-deploy/
├── docker-compose.yaml            # 带插件：挂载 ./web-modules + wecom-module-init 自动启用
├── web-modules/
│   ├── install.sh                 # 一步搬运脚本（docker 自动探测 / 指定目录）
│   ├── README.md                  # 开发者向说明
│   └── WecomCenter/               # 插件本体
│       ├── manifest.json          # v2.0.1（manifest_version 2.0），注册 2 个 action
│       ├── Module.php             # 入口：注册视图、i18n、注入左侧菜单
│       ├── actions/               # View(GET) / Save(POST) 控制器
│       ├── views/                 # 页面模板
│       ├── lib/                   # I18n.php / Helper.php（业务逻辑）
│       ├── locale/                # 35 个语言文件
│       ├── templates/             # 内置真实华为模板
│       └── assets/                # wecom.center.css
└── docs/使用说明.md               # 本文档

9. 回滚建议

动手批量改前，建议先导出相关对象做备份（媒介类型、动作、全局宏、触发器 priority 快照）。示例（API 导出）：

# 用 API token 导出媒介/动作/宏，保存为 JSON，需要时用对应 API 还原

页面「预览」永远是 dry-run，先看影响面再应用，是最稳的做法。

10. L2 物理拓扑（ROMAN 定制中心模块内置）

10.1 访问入口

  • 展示页：Monitoring → L2 Topology，或直接 http://192.168.87.20:8080/zabbix.php?action=l2.topology.view
  • 配置页：Administration → ROMAN 定制中心 → 「L2 拓扑」标签（模块改名为“ROMAN 定制中心”， 配置项全部集中在配置页，展示页只读）。物理网络在「物理网络定义」中按每行 KEY | 显示名称 | 名称/IP关键字 | #RRGGBB 配置，例如 SURVE | SURVE 监控网 | SURVE,10.169. | #2E75B6；新增/减少网络只改这里。
  • 「核心交换机」与分组规则一样可逐行添加：每行选择网络（或全部网络）、匹配方式（contains/regex）、 名称/IP 规则。命中的交换机全部画在最左侧核心列；同一网络可定义多个核心，顺序不限。

10.2 展示页功能

  • 链路速率配色（可在配置页改）：
    • 100M = 橙色 #F39C12，1G = 绿色 #2ECC71，10G = 蓝色 #3498DB， 20G+ = 紫色 #9B59B6，未知 = 红色 #E74C3C，中断 = 红色虚线 #C0392B。
  • 延迟着色：默认 ping 交换机管理 IP（Zabbix 主机 → 交换机）， >3ms 橙色、>5ms 红色（阈值可配）。注：本网实测 0.8ms 左右，绝大多数为正常（无色）。
  • 一张全局大拓扑图（不再有卡片全景/车间详情两级）：
    • 从左到右固定为 核心（可多个）→ 各网络主交换 → 各车间汇聚/分布 → 接入，一级交换机一列；列只按层级区分， 不按车间拆成多列。
    • 每个车间一个框（包住该车间的汇聚+接入），框内按 GRD → 1F → 3F → 4F → 7F 从下到上画楼层小框， 每层接入交换机在该楼层框内排列；接入下还有接入时按层级向右加一列（不改协议连接关系）。同一车间跨网络时拆成两个独立框，只连接各自网络的上游。
    • 所有链路均为单段直线，从上级标签左缘中点画到下级标签左缘中点；上级标签可以遮住线路出口， 但任何目标标签和其他线路不被遮挡；同一车间内部线路互不交叉，跨区直连核心的链路除外。点任意交换机高亮完整上联链路，点空白恢复。
    • 数据流动效果：正常在线链路叠加从核心向下游流动的细虚线（下行/离线链路不流动）， 100M/1G/10G/20G+ 的流动速度依次加快，仅作视觉提示，不改变任何连接关系。
    • PoE 交换机：采集器优先通过 RFC3621 pethPsePortAdminEnable 和华为 hwPoePortJudgeIsSupport 判断；部分华为固件不开放 HUAWEI-POE-MIB 时，再用 ENTITY-MIB entPhysicalDescr 的型号描述（如 S5735-L24P4XE-A-V2 ... PoE+）兜底。支持 PoE 的交换机名称最前面显示 ⚡️；当前离线或 SNMP 无响应的设备不显示。
  • 节点标签：车间 · 楼层机柜U · 角色 · IP；双击节点跳转该主机的问题页。
  • 告警/离线/延迟着色：告警交换机整个节点填充红色，离线交换机同样整节点红色；延迟 3–5ms 为橙色边框，大于 5ms 才为红色边框。告警不会再只画一个红框。告警面板只显示拓扑内交换机，不混入服务器/测试机等“拓扑外”主机。
  • 显示终端（端口矩阵）：勾选「显示终端」后，接入/汇聚交换机下方按实际端口清单绘制圆点；外圈颜色表示该端口支持的最大速率（100M 橙、1G 绿、2.5G 青、10G 紫、20G+ 深紫、未知灰），圆心实心颜色表示该端口当前实际链路速率。例如：10G 口插 1G 线 = 紫色外圈 + 绿色实心；10G 口未插线 = 空心紫色圈；2.5G 口 = 青色圈。端口较多时按实际面板自动分两行/多行，上联端口单独成行；历史快照没有端口清单时退回通用 24 口两行矩阵（12+12），不丢已有终端位置。端口颜色与上方链路速率颜色是两套语义，不要混用。
  • 右侧「离线交换机」面板可查看离线交换机并点击定位；终端面板点击任意终端可定位到其接入交换机及具体端口。
  • 时间轴：右上「快照时间」是一个下拉面板（不是两个并排选择框）：左侧只列实际保存过快照的日期（含「实时（最新）」），点日期后右侧只列该日期实际保存过的时间点，点时间即切换；默认 5 分钟一个点，保存 7 天；采集/快照间隔和历史保留天数都在配置页可调；采集成功即保存，不再单独设置快照间隔。
  • 明暗主题：自动跟随 Zabbix 当前主题（Zabbix 深色即深色、亮色即亮色），无手动开关。
  • 搜索：输入 IP / MAC / 名称，下拉结果点击即居中定位。
  • 导出图片：右上角「导出图片」把当前完整拓扑导出为 PNG；无论当前 Zabbix 是明色还是深色，导出图固定使用日间模式（白底）， 且导出时隐藏流动虚线，保证静态图上的实线/红虚线含义清晰。
  • 实时模式按配置的刷新秒数自动刷新，可暂停；支持缩放/适应窗口。

10.3 数据与存储

  • 采集结果 → assets/l2topology/snapshot.json（展示页实时读取）。
  • 每次全量采集成功后，按配置的 full_interval_min（默认 5 分钟）把快照 gzip 后写入 MySQL 表 l2_topology_history （字段 ts、captured_at、stats、snapshot），并自动清理超过 history_days（默认 7 天）的旧数据； 每分钟告警刷新只更新实时 JSON，不重复写历史。 按当前约 822 KB 原始 JSON / 约 33 KB gzip 压缩后估算：5 分钟 × 7 天 = 2,016 条，约 65–75 MB； 10 分钟约 33 MB，1 分钟约 330 MB。默认 5 分钟/7 天不夸张。
  • 配置存 l2_topology_config（单行 id=1），并镜像到 assets/l2topology/config.json 供采集脚本读取。
  • 两张表由 L2Store::ensureSchema() 在页面加载时自动 CREATE TABLE IF NOT EXISTS； docker-compose.yaml 的 wecom-module-init 一次性容器也会在 up 时建表，全新环境零手工。
  • 手动安装/升级后可在 L2 拓扑配置页顶部点 「初始化 / 自检 L2 存储」：幂等建表、配置行缺失时写默认配置，不覆盖已有配置。它与告警「初始化 / 自检」是同一套幂等逻辑，但不会创建/修改任何 Zabbix 用户或告警对象。

10.4 采集器（宿主机运行）

采集器代码位于仓库 collector/，安装到 /opt/zabbix/l2collector/：

stp_collect.py        # STP 指定桥 + MAC 学习 -> 交换机级联关系
fdb_collect.py        # ARP + BRIDGE-MIB FDB + ifName -> 终端/链路
fdb_analyze3.py       # 归并出链路与终端清单
port_status.py        # IF-MIB 端口 up/down/速率/每口 MAC 数
latency_collect.py    # 并发 ping 交换机管理 IP -> /tmp/latency.tsv
l2_snapshot.py        # 合成 snapshot.json + 按配置间隔写历史库
l2cfg.py              # 读取 config.json，按模板过滤要采集的主机
run_full.sh           # 全量：stp->fdb->analyze->port->latency->snapshot(写历史)
refresh_alarms.sh     # 仅刷新实时告警 JSON(每分钟；不写历史)
  • 只采集配置页所选模板（默认 Huawei VRP by SNMP (walk)，id 10962）的主机，避免误采其它设备。

  • 安装（一次性，幂等）：

    cd /opt/zabbix/l2collector && chmod +x run_full.sh refresh_alarms.sh
{ crontab -l 2>/dev/null | grep -v l2collector || true
echo '*/5 * * * * /bin/bash /opt/zabbix/l2collector/run_full.sh >/dev/null 2>&1'
echo '* * * * * /bin/bash /opt/zabbix/l2collector/refresh_alarms.sh >/dev/null 2>&1'
} | crontab -

  • 手动跑一次全量：bash /opt/zabbix/l2collector/run_full.sh，日志 /var/log/l2collector.log。

10.5 docker-compose 一键启用

  • docker-compose.yaml 已把 web-modules/ 挂进 zabbix-web 容器， 并由 wecom-module-init 一次性容器等待 Zabbix 的 module 表就绪后自动登记（启用）模块、创建 L2 两张表。 全新机器 docker compose up -d 后插件即已启用，无需手工去「Administration → Modules」点启用。 全新库首次创建 module 表需要一点时间，侧车最多等 300 秒，避免首次 up 时序失败。
  • 若 web-modules 目录不在 compose 同级，用 .env 的 WEB_MODULES_DIR 指向绝对路径。
  • 采集器为宿主机进程（需 SNMP 工具、且要读交换机网络），不在容器内运行，按 10.4 安装。

10.6 故障排查

  • 按钮出现 鈼?、鉂氣潥、锛? 等乱码：不是浏览器字体问题，而是 views/topology.view.php 被按 GBK/ANSI 重新编码。2.0.1 起已全部改为 HTML 数字实体；请重跑 install.sh 覆盖旧文件，安装脚本会检测并拒绝带 mojibake 的包。
  • 展示页空白：确认 assets/l2topology/snapshot.json 存在（跑一次 run_full.sh）。
  • 时间轴没有历史：确认 cron 在跑、l2_topology_history 行数在增长；历史写入间隔最少 5 分钟，改配置页后需等下一个周期。
  • 交换机没被采集：检查配置页模板是否勾选正确、该主机是否挂了该模板、SNMP 可达。
  • 颜色/阈值不生效：改完配置页保存后，config.json 会同步；采集侧下个周期生效。