|
|
@@ -0,0 +1,210 @@
|
|
|
+# 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` 已经把「插件随仓库走 + 自动启用」做好:
|
|
|
+
|
|
|
+```bash
|
|
|
+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 目录(否则重建容器文件会丢):
|
|
|
+ ```yaml
|
|
|
+ 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` 不是自增列,需显式给值):
|
|
|
+ ```sql
|
|
|
+ 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 导出):
|
|
|
+```bash
|
|
|
+# 用 API token 导出媒介/动作/宏,保存为 JSON,需要时用对应 API 还原
|
|
|
+```
|
|
|
+页面「预览」永远是 dry-run,先看影响面再应用,是最稳的做法。
|