# zabbix_sentinel_aiops **Repository Path**: SRIM/zabbix_sentinel_aiops ## Basic Information - **Project Name**: zabbix_sentinel_aiops - **Description**: 项目概述 Sentinel AIOps 是一个 Zabbix 7.0 前端扩展模块，将 AI 能力深度集成到监控运维平台中。核心功能包括：功能说明 🤖 AI 对话助手基于 Hermes API 的流式对话，支持文件上传、消息引用、多会话管理 📊 实时监控仪表盘 CPU/内存 TOP5、网络流量、磁盘使用率、告警统计、主机状态 ⏰ Cron 定时任务管理通过 Hermes CLI - **Primary Language**: JavaScript - **License**: AGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-14 - **Last Updated**: 2026-04-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Sentinel AIOps — 部署说明手册 ![version](https://img.shields.io/badge/version-2.1.0-blue) ![zabbix](https://img.shields.io/badge/Zabbix-7.0.x-green) ![arch](https://img.shields.io/badge/arch-IIFE-orange) ![status](https://img.shields.io/badge/status-passing-brightgreen) > **作者**: Skyrim | **兼容**: Zabbix Server 7.0.11 已测试 | **架构**: 纯前端扩展模块（无构建工具） --- ## 目录 - [1. 项目概述](#1-项目概述) - [2. 架构设计](#2-架构设计) - [3. 前置依赖](#3-前置依赖) - [4. 安装部署](#4-安装部署) - [5. 配置说明](#5-配置说明) - [6. 功能详解](#6-功能详解) - [7. 安全机制](#7-安全机制) - [8. 故障排查](#8-故障排查) --- ## 1. 项目概述 Sentinel AIOps 是一个 **Zabbix 7.0 前端扩展模块**，将 AI 能力深度集成到监控运维平台中。核心功能包括： | 功能 | 说明 | |------|------| | **🤖 AI 对话助手** | 基于 Hermes API 的流式对话 ![SSE](https://img.shields.io/badge/SSE-流式输出-yellow) 支持文件上传 ![upload](https://img.shields.io/badge/upload-10MB_max-blue) 消息引用、多会话管理 | | **📊 实时监控仪表盘** | CPU/内存 TOP5、网络流量、磁盘使用率、告警统计、主机状态 | | **⏰ Cron 定时任务管理** | 通过 Hermes CLI 管理 AI 自动巡检等周期任务 | | **🔧 巡检报告生成** | 4 维度 16 点综合分析，自动生成结构化报告 | ### 技术特点 - **零构建工具**：纯 IIFE 模式单文件架构，无需 npm/webpack/vite - **本地化部署**：所有资源内联，无外部 CDN 依赖 - **暗色主题适配**：与 Zabbix 原生暗色 UI 无缝融合 - **流式渲染**：SSE 实时输出，思考过程可折叠展示 |

| | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | | | | | | | | | | | | --- ## 2. 架构设计 ``` ┌─────────────────────────────────────────────────────────────┐ │ 浏览器端 (Zabbix Frontend) │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ sentinel_widget.js (主逻辑 ~2700 行) │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ │ │ 聊天引擎 │ │仪表盘组件│ │ Cron 管理面板 │ │ │ │ │ │ SSE 流式 │ │ ECharts │ │ REST CRUD │ │ │ │ │ └────┬─────┘ └────┬─────┘ └───────┬──────────┘ │ │ │ └────────┼────────────┼────────────────┼────────────┘ │ │ │ │ │ │ │ ┌────────▼────────────▼────────────────▼────────────┐ │ │ │ sentinel_styles.css (~600 行样式) │ │ │ └───────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↕ HTTP / HTTPS ┌─────────────────────────────────────────────────────────────┐ │ Zabbix Server (后端) │ │ │ │ ┌────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Module.php │ │ cron_api.php │ │ configuration │ │ │ │ (配置注入) │ │ (Cron桥接) │ │ .edit.php (设置) │ │ │ └─────┬──────┘ └──────┬───────┘ └──────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Nginx 反向代理 │ │ │ │ /hermes-api/ → 127.0.0.1:8642 │ │ │ └─────────────────────┬───────────────────────────────┘ │ └─────────────────────────┼─────────────────────────────────┘ │ ┌─────────────────────────▼─────────────────────────────────┐ │ Hermes API Server (:8642) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ /v1/models │ │ /chat/completions │ │ Cron CLI │ │ │ │ (模型列表) │ │ (AI对话SSE) │ │ 定时任务管理 │ │ │ └──────────────┘ └──────────────┘ └────────────────┘ │ │ │ │ │ ┌─────────▼─────────┐ │ │ │ LLM Provider │ │ │ │ (DeepSeek/GPT…) │ │ │ └───────────────────┘ │ └───────────────────────────────────────────────────────────┘ ``` ### 文件结构 ``` sentinel_aiops/ ├── manifest.json # 模块清单 (Zabbix 识别入口) ├── Module.php # PHP 后端 (Cookie 注入 + 配置加载) ├── proxy_api.php # 代理 API (Cron 管理 + 分类管理) ├── categories.json # 分类定义 (名称/图标/颜色) ⚠️ 需 Web 用户可写 ├── job_categories.json # 任务-分类映射 (job_id → category_key) ⚠️ 需 Web 用户可写 ├── views/ │ └── module.configuration.edit.php # 设置面板表单 (Hermes URL + Key) ├── assets/ │ ├── css/ │ │ └── sentinel_styles.css # 全部样式 (暗色主题, ~600行) │ ├── js/ │ │ └── sentinel_widget.js # 全部业务逻辑 (IIFE, ~6700行) │ └── hosts_template.csv # 主机巡检模板数据 └── README.md # 本文档 ``` --- ## 3. 前置依赖 ### 必需项 | 组件 | 版本要求 | 用途 | |------|---------|------| | **Zabbix Server** | ![7.0.x](https://img.shields.io/badge/7.0.x-推荐_7.0.11-green) | 宿主平台 | | **Hermes Agent** | ![latest](https://img.shields.io/badge/latest-最新版-blue) | AI 引擎 (对话/Cron/Tool Calling) | | **PHP** | ![8.1+](https://img.shields.io/badge/php-8.1+-purple) (Zabbix 自带) | 后端桥接 | | **Nginx** | ![nginx](https://img.shields.io/badge/nginx-任意版本-orange) | 反向代理 Hermes API | ### Hermes Agent 安装 ```bash # 1. 安装 Hermes CLI curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash # 2. 验证安装 hermes --version # 3. 配置 API Key 和模型 # 编辑 ~/.hermes/config.toml # 设置 provider、model、api_key 等 # 4. 启动 Gateway (Cron 调度器需要) hermes gateway install # systemd 服务模式 # 或前台运行: # hermes gateway start ``` ### Nginx 反向代理配置在 Zabbix Nginx 配置中添加： ```nginx location /hermes-api/ { proxy_pass http://127.0.0.1:8642/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # SSE 流式响应需要关闭缓冲 proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; # 长对话超时 5 分钟 } ``` ```bash # 测试并重载 Nginx nginx -t && systemctl reload nginx ``` --- ## 4. 安装部署 ### 方法一：直接复制（推荐） ```bash # 在 Zabbix 服务器上执行 MODULE_DIR="/usr/share/zabbix/modules" # 创建目录 mkdir -p "$MODULE_DIR/sentinel_aiops/assets/css" mkdir -p "$MODULE_DIR/sentinel_aiops/assets/js" mkdir -p "$MODULE_DIR/sentinel_aiops/views" # 复制文件 cp manifest.json "$MODULE_DIR/sentinel_aiops/" cp Module.php "$MODULE_DIR/sentinel_aiops/" cp cron_api.php "$MODULE_DIR/sentinel_aiops/" cp views/module.configuration.edit.php "$MODULE_DIR/sentinel_aiops/views/" cp assets/css/sentinel_styles.css "$MODULE_DIR/sentinel_aiops/assets/css/" cp assets/js/sentinel_widget.js "$MODULE_DIR/sentinel_aiops/assets/js/" cp assets/hosts_template.csv "$MODULE_DIR/sentinel_aiops/assets/" # 设置权限 (非常重要!) chown -R zabbix:zabbix "$MODULE_DIR/sentinel_aiops" chmod -R 755 "$MODULE_DIR/sentinel_aiops" # ⚠️ 关键步骤：新分类数据文件必须设置为 Web 用户可写 # categories.json — 存储分类定义（名称/图标/颜色） # job_categories.json — 存储任务与分类的映射关系 # 如果这两个文件不可写，将导致"新增分类"等功能静默失败 cat > "$MODULE_DIR/sentinel_aiops/categories.json" << 'EOF' { "categories": [ { "key": "inspect", "name": "巡检任务", "icon": "search", "color": "#3b82f6" }, { "key": "security", "name": "安全审计", "icon": "shield", "color": "#ef4444" }, { "key": "daily", "name": "日常管理", "icon": "settings", "color": "#f59e0b" }, { "key": "report", "name": "报告生成", "icon": "file-text", "color": "#10b981" }, { "key": "alert", "name": "告警响应", "icon": "bell", "color": "#8b5cf6" } ], "default": "daily", "uncategorized": { "key": "_uncategorized", "name": "未分类", "icon": "folder", "color": "#94a3b8" } } EOF echo '{}' > "$MODULE_DIR/sentinel_aiops/job_categories.json" # 设置文件所有者为 Web 服务器用户 (根据实际 Nginx 用户调整) # CentOS/RHEL: nginx — Ubuntu: www-data — 如果 Nginx 在 Zabbix 下运行可能是 zabbix WEB_USER="zabbix" id nginx >/dev/null 2>&1 && WEB_USER="nginx" id www-data >/dev/null 2>&1 && WEB_USER="www-data" # 必须确保这两个文件可被 Web 用户读写 (664)，目录可执行 chown "$WEB_USER:$WEB_USER" "$MODULE_DIR/sentinel_aiops/categories.json" chown "$WEB_USER:$WEB_USER" "$MODULE_DIR/sentinel_aiops/job_categories.json" chmod 664 "$MODULE_DIR/sentinel_aiops/categories.json" chmod 664 "$MODULE_DIR/sentinel_aiops/job_categories.json" # 验证权限 (应显示 -rw-rw-r-- 且所有者为 nginx 或 zabbix) ls -la "$MODULE_DIR/sentinel_aiops/categories.json" "$MODULE_DIR/sentinel_aiops/job_categories.json" ``` ### 方法二：从本地上传 ```bash scp -r sentinel_aiops/* root@:/usr/share/zabbix/modules/sentinel_aiops/ ssh root@ " chown -R zabbix:zabbix /usr/share/zabbix/modules/sentinel_aiops # ⚠️ 关键：修复分类数据文件权限 WEB_USER=zabbix; id nginx >/dev/null 2>&1 && WEB_USER=nginx chown \$WEB_USER:\$WEB_USER /usr/share/zabbix/modules/sentinel_aiops/categories.json chown \$WEB_USER:\$WEB_USER /usr/share/zabbix/modules/sentinel_aiops/job_categories.json chmod 664 /usr/share/zabbix/modules/sentinel_aiops/categories.json chmod 664 /usr/share/zabbix/modules/sentinel_aiops/job_categories.json " ``` ### 启用模块 1. 打开 Zabbix Web → ** Administration → Modules** 2. 找到 **"Sentinel AIOps Engine"** → 点击 **Scan directory** 或手动启用 3. 进入模块设置页面，填写： - **Hermes API URL**: `/hermes-api/v1` - **Hermes API Key**: 你的 Hermes Bearer Token 4. 点击 **Update** 保存 ### 验证安装打开浏览器开发者工具 (F12) → Console，输入： ```javascript document.getElementById('sentinel-panel') ? '✅ 模块已加载' : '❌ 未找到' ``` 或在 Zabbix 页面右侧应看到 **Sentinel AIOps** 面板入口。 --- ## 5. 配置说明 ### 5.1 模块配置（Zabbix 设置页） | 字段 | 默认值 | 说明 | |------|--------|------| | `hermes_api_url` | `/hermes-api/v1` | Hermes API 地址前缀 | | `hermes_api_key` | *(空)* | **必填** — Hermes Bearer Token | ### 5.2 前端内置配置（代码中的常量）在 `sentinel_widget.js` 顶部可调整以下参数： ```javascript const HERMES_URL_DEFAULT = "/hermes-api"; // Hermes API 基础路径 const AI_MODEL = "deepseek-chat"; // 使用的模型名称 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 上传文件大小限制 (10MB) const MAX_CONTENT_CHARS = 500000; // 文件内容最大字符数 (500K) const CHAT_TIMEOUT_MS = 300000; // 对话请求超时 (5分钟) ``` ### 5.3 数据存储位置 | 数据类型 | 存储方式 | 位置 | |---------|---------|------| | 会话历史 | localStorage | 浏览器本地 (`s_sess`) | | 用户偏好设置 | localStorage | 浏览器本地 (`s_cfg`) | | Hermes API Key | Cookie | `sentinel_config` (httponly=false) | | Cron 任务数据 | Hermes 内部 | `~/.hermes/cron/jobs.json` | --- ## 6. 功能详解 ### 6.1 AI 对话系统 #### 核心能力 | 特性 | 实现 | |------|------| | **流式输出** | SSE `text/event-stream`，逐 token 渲染 | | **执行过程展示** | 从 content 中智能分离"过程文字"和"正文"，折叠容器展示 | | **文件上传** | 支持文本/代码文件读取内容；二进制文件(ZIP/PDF等)显示元信息 | | **消息引用** | 点击 AI 回复的引用按钮，可在新消息中引用该段内容 | | **多会话管理** | 左侧会话列表，支持切换/新建/删除/重命名 | | **Markdown 渲染** | 表格/代码块/列表/链接/图片完整支持 | | **Mermaid 图表** | 异步渲染流程图/序列图/甘特图等 | #### 消息渲染顺序 ``` 🤖 Sentinel AIOps ← 名称行 ┌─ ⚙ 执行过程 N 步操作 ▸ ─────┐ ← 可折叠 (默认收起) │ 🧠 Thinking ... │ ← 思考过程 (如有) │ ▸ tool_name ✓/✗ │ ← 工具调用卡片 (如有) └────────────────────────────────┘ [Markdown 正文内容...] ← 最终回答 [📋 复制] [✏️ 编辑] ← 操作按钮 2026-04-14 16:37 ← 时间戳 ``` ### 6.2 监控仪表盘 | 面板 | 数据源 | 展示形式 | |------|--------|---------| | **CPU TOP5** | Zabbix API | 主机名 + 使用率条形图 | | **内存 TOP5** | Zabbix API | 主机名 + 使用量/总量 | | **网络流量** | Zabbix API | 网卡名 + 入/出速率 | | **磁盘使用** | Zabbix API | 分区名 + 使用率 + 可用空间 | | **告警统计** | Zabbix API | 按严重级别分组计数 | | **主机状态** | Zabbix API | 在线/离线/维护数量概览 | | **触发器趋势** | Zabbix API | 近 24 小时折线图 | > ⚠️ **用户偏好**：CPU/内存显示**主机名**（非监控项名），流量接口用**网卡名** ### 6.3 Cron 定时任务管理通过 Hermes CLI 管理定时任务，支持完整的 CRUD 操作： | 操作 | API 方法 | 说明 | |------|---------|------| | 列出任务 | GET | 含调度器状态 + 所有任务详情 | | 创建任务 | POST | name, schedule, prompt, deliver, repeat | | 暂停/恢复 | PUT | pause / resume | | 手动触发 | PUT | run | | 删除任务 | DELETE | 按 ID 移除 | 典型用例：**每日自动巡检** — 设定 Cron 让 AI 定时分析监控数据并输出报告。 --- ## 7. 安全机制 | 措施 | 实现 | |------|------| | **认证链路** | Zabbix Session → Cookie → Hermes Bearer Token | | **CSRF 防护** | `cron_api.php` 校验 X-CSRF-Token 与 Session Token 一致性 | | **CORS 限制** | 仅允许同源请求（Origin 白名单） | | **命令注入防护** | `escapeshellarg()` + 参数白名单 + 输入长度限制 | | **XSS 防护** | `esc()` 函数转义所有动态 HTML 内容 | | **文件安全** | 二进制文件不读取内容；文件大小上限 10MB | | **敏感数据处理** | API Key 不写入日志/URL；localStorage 存储加密标记 | --- ## 8. 故障排查 ### 常见问题 #### Q0: 新增分类、删除分类、修改分类图标/名称等功能无反应或静默失败 ``` ⚠️ 这是部署中最常见的问题！原因是 categories.json 和 job_categories.json 两个 JSON 文件的文件权限设置不正确。现象: - 点击 "+" 添加新分类，输入名称后回车，UI 无变化 - 控制台日志显示 "add-category success"，但刷新后分类列表不变 - 删除分类、修改分类图标/名称等操作也无响应原因: - PHP 的 proxy_api.php 在 Web 服务器进程 (Nginx/PHP-FPM/PHP) 中运行 - 该进程以非 root 身份运行 (通常是 nginx/zabbix/www-data 用户) - 如果 categories.json 由 root 用户创建，Web 用户无法写入 - 此时 saveJsonFile() 返回 false，但上层逻辑未检查，返回虚假成功诊断步骤: 1. 登录服务器确认文件所有者: ls -l /usr/share/zabbix/modules/sentinel_aiops/categories.json # 错误示例: -rw-r--r-- 1 root root ... (所有者是 root) # 正确示例: -rw-rw-r-- 1 nginx nginx ... (所有者是 Web 用户) 2. 确认 Web 服务器用户身份: id nginx # CentOS/RHEL id zabbix # 如果 Nginx 在 Zabbix 进程下运行 id www-data # Ubuntu/Debian 修复步骤: WEB_USER="nginx" # 根据实际情况改为 zabbix 或 www-data chown \$WEB_USER:\$WEB_USER /usr/share/zabbix/modules/sentinel_aiops/categories.json chown \$WEB_USER:\$WEB_USER /usr/share/zabbix/modules/sentinel_aiops/job_categories.json chmod 664 /usr/share/zabbix/modules/sentinel_aiops/categories.json chmod 664 /usr/share/zabbix/modules/sentinel_aiops/job_categories.json 预防方法: - 在部署脚本中始终先创建空文件，再修改所有者和权限 - 不要使用 scp root 覆盖后再忘记修改权限 - 确保 PHP 运行用户对这两个文件有写权限 ``` #### Q1: 模块未出现在 Zabbix 中 ``` 检查清单: 1. 文件是否放在正确路径? → /usr/share/zabbix/modules/sentinel_aiops/ 2. manifest.json 是否有效 JSON? 3. 文件权限是否正确? → chown zabbix:zabbix; chmod 755 4. Zabbix 缓存? → Administration → Modules → Scan directory ``` #### Q2: "请先配置 Hermes API Key" 提示 ``` 检查步骤: 1. 进入 Administration → Modules → Sentinel AIOps Engine 2. 确保 hermes_api_key 已填写并点 Update 保存 3. 清除浏览器 Cookie 后刷新 (sentinel_config cookie 可能过期) 4. F12 Console 输入: JSON.parse(document.cookie.match(/sentinel_config=([^;]+)/)?.[1]) 查看 has_config 是否为 true ``` #### Q3: 对话请求失败 / 超时 ``` 排查方向: 1. Nginx 代理是否工作? curl -H "Authorization: Bearer YOUR_KEY" http://localhost/hermes-api/v1/models 2. Hermes Gateway 是否启动? hermes cron status 3. CORS 问题? (跨域部署时) 检查 Nginx 的 Access-Control-Allow-Origin 头 4. SSE 超时? 确保 nginx.conf 有: proxy_buffering off; proxy_read_timeout 300s; ``` #### Q4: 控制台报 SVG `` 错误 ``` 原因: 会话列表删除按钮的垃圾桶图标 SVG 路径缺少 M 命令修复: 已在 v2.1.0+ 修复。确保使用最新版 sentinel_widget.js ``` #### Q5: `/v1/models` 返回 404 ``` 原因: Hermes API URL 配置了 /v1 后缀，导致路径变成 /hermes-api/v1/v1/models 修复: 代码已做去重处理 (replace(/\/v1$/, ""))。确认 hermes_api_url 不含 /v1 后缀 ``` #### Q6: 附件显示为"文本文件"而非正确类型 ``` 原因: ZIP/PDF 等二进制文件被 FileReader.readAsText() 当成文本处理修复: v2.1.0+ 新增 BINARY_EXTS 白名单 (30+ 扩展名)，二进制文件只保存元数据 ``` ### 调试日志开启浏览器控制台 (F12) 可看到 `[Sentinel]` 前缀的调试信息： ``` [Sentinel] 流式 meta: {"hasReasoning":true,"reasonLen":345,"toolCount":2,...} [Sentinel] 最终结果: {"hasReasoning":true,"reasonLen":345,"toolCount":2,...} ``` 这些日志帮助确认： - AI 模型是否返回了 reasoning_content - 是否有 tool_calls 数据 - 内容长度是否正常 --- ## 附录：更新记录 | 版本 | 日期 | 主要变更 | |------|------|---------| | ![v2.1.0](https://img.shields.io/badge/v-2.1.0-blue) | 2026-04-14 | 执行过程折叠框、二进制文件识别、附件/引用右对齐、SVG 修复、URL 去重 | | ![v2.0.0](https://img.shields.io/badge/v-2.0.0-green) | 2026-04-13 | 对话功能全面升级（基于 Hermes HUD UI 分析） | | ![v1.x](https://img.shields.io/badge/v-1.x-lightgrey) | 2026-04 初 | 基础框架：仪表盘 + 聊天 + Cron 管理 | --- *本文档随项目更新而维护。如有疑问，请查看浏览器控制台的 [Sentinel] 日志或提交 Issue。*