Startseite Erkunden Hilfe
Anmelden
FlyingRome
/
zabbix-deploy
2
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Struktur: 639c41a6ee
Branches Tags
zabbix-deploy
/
docs
/
使用说明.md

使用说明.md 18 KB
Verlauf Originalformat

WeCom Center — 使用与部署说明

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

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

标签页 关键能力
告警 Alert 企业微信群机器人 key 设置与测试；5 套告警策略预设（先预览 → 再应用）；手动勾选会通知的严重度；一键刷新（写入模板触发器 / 触发器原型 / 已发现触发器，全部节点生效）。
优化 Optimization 服务端调优参数生成（只生成 .env/compose 片段与重建命令，不落地，运维自行重建）；真实华为模板 →「导入」→「切换」迁移设备；Geomap 单点标记。
日常维护 Maintenance 按类别批量改告警等级；按单个触发器精确调整：勾选开关告警 + 行尾下拉改严重度；保存后页面自动刷新。

所有改动都走 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 就绪后，把 module 表里的 wecom_center 登记为 已启用（status=1）。脚本是幂等的：已存在就不动，重复 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）。

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

  4. 启用模块（写 module 表，status=1 为启用；moduleid 不是自增列，需显式给值）：

    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');

    也可以进 Administration → General → Modules → Scan directory → 启用 WecomCenter。

2.3 换环境 / 升级镜像

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

2.4 部署验证

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

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

安装后第一次打开 WeCom Center → 告警 页，会显示 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} 直达详情链接

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

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，注册 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 物理拓扑（WecomCenter 模块内置）

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 从下到上画楼层小框， 每层接入交换机在该楼层框内单列排列。同一车间跨网络时拆成两个独立框，只连接各自网络的上游。
    • 所有链路均为单段直线，从上级标签左缘中点画到下级标签左缘中点；上级标签可以遮住线路出口， 但任何目标标签和其他线路不被遮挡；同一车间内部线路互不交叉，跨区直连核心的链路除外。点任意交换机高亮完整上联链路，点空白恢复。
  • 节点标签：车间 · 楼层机柜U · 角色 · IP；双击节点跳转该主机的问题页。
  • 告警面板只显示拓扑内交换机，不再混入服务器/测试机等“拓扑外”主机；告警交换机边框统一红色。
  • 显示终端 / 只看离线：勾选「显示终端」在交换机下方展开终端点（绿=在线、灰=离线）； 「只看离线」仅显示离线终端。右侧「离线终端」面板点击可联动定位。
  • 时间轴：右上「快照时间」下拉可选 实时 或历史某分钟快照（保存 7 天，5 分钟一个点）。
  • 明暗主题：自动跟随 Zabbix 当前主题（Zabbix 深色即深色、亮色即亮色），无手动开关。
  • 搜索：输入 IP / MAC / 名称，下拉结果点击即居中定位。
  • 实时模式按配置的刷新秒数自动刷新，可暂停；支持缩放/适应窗口。

10.3 数据与存储

  • 采集结果 → assets/l2topology/snapshot.json（展示页实时读取）。
  • 每次全量采集同时把快照 gzip 后写入 MySQL 表 l2_topology_history （字段 ts、captured_at、stats、snapshot），并自动清理超过 history_days(默认7) 天的旧数据。
  • 配置存 l2_topology_config（单行 id=1），并镜像到 assets/l2topology/config.json 供采集脚本读取。
  • 两张表由 L2Store::ensureSchema() 在页面加载时自动 CREATE TABLE IF NOT EXISTS； docker-compose.yaml 的 wecom-module-init 一次性容器也会在 up 时建表，全新环境零手工。

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     # 仅刷新告警(每分钟，不写历史)
  • 只采集配置页所选模板（默认 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 一次性容器自动登记（启用）模块、创建 L2 两张表。 全新机器 docker compose up -d 后插件即已启用，无需手工去「Administration → Modules」点启用。
  • 若 web-modules 目录不在 compose 同级，用 .env 的 WEB_MODULES_DIR 指向绝对路径。
  • 采集器为宿主机进程（需 SNMP 工具、且要读交换机网络），不在容器内运行，按 10.4 安装。

10.6 故障排查

  • 展示页空白：确认 assets/l2topology/snapshot.json 存在（跑一次 run_full.sh）。
  • 时间轴没有历史：只有全量采集写历史；确认 cron 在跑，l2_topology_history 行数在增长。
  • 交换机没被采集：检查配置页模板是否勾选正确、该主机是否挂了该模板、SNMP 可达。
  • 颜色/阈值不生效：改完配置页保存后，config.json 会同步；采集侧下个周期生效。