内容
<div align="center">
<img src="docs/logo.svg" alt="Orveil" width="80" />
<h1>Orveil</h1>
<p>统一监控仪表盘，支持通过<a href="https://github.com/caronc/apprise/wiki">Apprise</a>发送通知。<br>监控您的自托管服务，在发生故障时接收警报，并将通知发送到任意渠道。</p>
[](https://hub.docker.com/r/zlimteck/orveil)
[](https://github.com/zlimteck/orveil/actions/workflows/docker.yml)
[](LICENSE)
[](https://hub.docker.com/r/zlimteck/orveil)
</div>
## 目录
- [功能](#features)
- [技术栈](#stack)
- [快速开始](#quick-start)
- [可用监控类型](#available-monitors)
- [每种监控类型发送的警报](#alerts-sent-per-monitor-type)
- [通知（Apprise）](#notifications-apprise)
- [MCP 服务器](#mcp-server)
- [Orveil AI](#orveil-ai)
- [环境变量](#environment-variables)
- [许可证](#license)
## 功能
- **统一仪表盘** — 所有服务的运行状态一目了然，支持网格或列表视图
- **23种监控类型** — HTTP/HTTPS、Ping/TCP、端口转发、SSH、DNS、MySQL、Redis、Proxmox、Cloudflare、AdGuard DNS、AdGuard Home、Home Assistant、Portainer、Docker、Syncthing、Immich、HostMyServers、Ultra.cc、Heartbeat、Unraid、Speedtest Tracker、Jellyfin、Ollama
- **公共状态页面** — 可分享的 `/status` 页面（无需登录）显示服务运行状态、故障历史和 90 天运行记录；可为每个服务切换可见性
- **搜索与排序** — 按名称筛选卡片，按状态 / 名称 / 手动排序
- **拖拽排序** — 在网格视图中手动调整卡片顺序
- **分类分组** — 为每个服务分配类别，以便在仪表盘上分组
- **故障跟踪** — 自动开启 / 关闭故障，并记录持续时间；支持 P1-P4 级别的严重程度（自动分配，可手动覆盖）；故障原因直接显示；故障按日期分组
- **战室** — 所有活跃故障的专用全屏视图，按严重程度排序，支持 30 秒自动刷新
- **事后总结报告** — 为已解决的故障附加结构化总结（概要、根本原因、影响、解决方案、经验教训）
- **SLA 跟踪** — 为每个监控设置目标运行时间百分比；在统计页面显示是否达到目标
- **统计数据** — 30 天全局视图：服务运行时间趋势、SLA 状态、故障次数、MTTR、MTTD、严重程度分布、通知日志、每天 / 每小时故障热图
- **维护窗口** — 服务级别的维护模式，支持立即或预定（日期 / 时间选择器）；支持 30 分钟至 8 小时或自定义时长；维护窗口期间不会发送警报或产生故障
- **自适应轮询** — 当服务宕机时，检查间隔自动降至 30 秒（可配置）以便快速检测恢复；服务恢复后恢复正常检查间隔；Speedtest 和 Heartbeat 监控除外
- **通知冷却** — 支持为相同服务配置重复故障通知的最小延迟（分钟）；防止在服务频繁故障时发送过多通知；恢复通知始终发送
- **监控依赖** — 支持将监控与父监控关联；当父监控也宕机时，子监控的故障通知会被抑制
- **备份与恢复** — 支持将所有监控和设置导出为 JSON；在其他实例上导入（设置页面）
- **状态徽章** — 为每个服务生成可嵌入的 SVG 徽章（`/api/badge/:id`），显示实时状态；支持 Markdown 和 HTML 代码片段
- **指标图表** — 仪表盘卡片和服务详情页显示火花线图表；支持平滑贝塞尔曲线、故障叠加和用户注释
- **Apprise 通知** — 支持 Pushover、Telegram、Discord、Slack、电子邮件等 [100+ 种通知方式](https://github.com/caronc/apprise/wiki)
- **每周报告** — 支持可选的每周 Apprise 总结（错误服务、平均运行时间）
- **手动通知** — 支持直接从界面发送消息到所有渠道
- **代理库** — 支持保存多个命名代理（HTTP、HTTPS、SOCKS5、SSH 隧道）；支持一键激活 / 停用全局默认代理；支持为每个监控分配特定代理；支持从界面测试每个代理；密码和私钥加密存储
- **克隆监控** — 支持一键复制任意监控（在启用前以禁用状态打开以便安全编辑）
- **实时通知** — 通过 SSE 实现的实时应用内通知，当服务状态变化时发送彩色通知
- **自动 / 浅色 / 深色主题** — 跟随系统偏好，支持每种浏览器持久化
- **FR / EN 界面** — 支持语言切换，同步到通知语言（一个设置同时控制 UI 和通知）
- **REST API** — 完整的 API，支持 Bearer token 认证，在应用内有文档
- **MCP 服务器** — Model Context Protocol 服务器，通过 Streamable HTTP 和 stdio 传输协议暴露监控、故障、统计、注释和运行时间历史给 AI 助手（Claude Desktop 等）
- **Orveil AI** — 内置 AI 助手（由 Anthropic Claude 驱动），可以直接从仪表盘回答关于监控、故障和 SLA 的问题；API 密钥加密存储在数据库中；模型可从 Anthropic 目录中选择
## 技术栈
| 层 | 技术 |
|-------|------|
| 前端 | React 18 + Vite + Tailwind CSS |
| 后端 | Node.js + Express |
| 数据库 | MongoDB |
| 通知 | Apprise（自托管 sidecar） |
| 部署 | 单个 Docker 镜像（前端 + 后端） |
| CI/CD | GitHub Actions → Docker Hub（amd64 + arm64） |
## 快速开始
**前提条件：** Docker + Docker Compose
```bash
git clone https://github.com/zlimteck/orveil.git
cd orveil
cp .env.example .env
# 编辑 .env — 在公开暴露之前修改 JWT_SECRET 和 ADMIN_PASSWORD
docker compose up -d
```
| 服务 | URL |
|---------|-----|
| 应用（前端 + API） | http://localhost:3050 |
| Apprise API | http://localhost:8008 |
默认凭证：`admin` / `orveil`
## 可用监控类型
| 类型 | 检查内容 |
|------|----------------|
| **HTTP** | HTTP/HTTPS 端点 — 状态码或自定义接受代码列表、关键词存在 / 不存在匹配、Bearer/Basic/自定义认证、多种方法（GET/POST/PUT…）、SSL 证书过期（显示颁发者和确切日期） |
| **Ping** | ICMP ping 或 TCP 端口可达性 — 延迟和数据包丢失 |
| **DNS** | DNS 记录解析（A、AAAA、CNAME、MX、TXT、NS）— 可选断言预期值 |
| **MySQL** | Ping MySQL/MariaDB 服务器并通过 `mysql2` 检索版本 |
| **Redis** | 通过 `ioredis` 对 Redis 实例进行 PING 并检索版本 |
| **SSH** | 通过 SSH（密码或私钥）获取 CPU / RAM |
| **Heartbeat** | Cron 作业 / 脚本监控 — 如果在预期间隔内未收到 ping，则发送警报 |
| **Docker** | 通过 Docker 套接字获取容器数量和状态 |
| **Proxmox** | 通过 API 令牌获取节点 CPU / RAM |
| **Cloudflare** | 通过 API 令牌获取隧道状态和主机名 |
| **AdGuard DNS** | 通过云 API 获取 DNS 保护状态和请求统计 |
| **AdGuard Home** | 自托管 DNS 保护 — 阻止查询百分比、总查询、安全浏览 |
| **Portainer** | 通过 API 密钥获取每个环境的容器列表 |
| **Syncthing** | 通过 API 密钥获取同步文件夹和连接设备 |
| **Immich** | 通过 API 密钥获取照片 / 视频数量和磁盘使用情况 |
| **HMS（HostMyServers）** | 通过 API 令牌获取 VPS 状态和规格 |
| **Ultra.cc** | 通过统计 API URL 获取 Seedbox 存储和流量 |
| **Unraid** | 通过 GraphQL API 获取阵列状态、磁盘使用情况、CPU / RAM、温度 |
| **Home Assistant** | 通过长期访问令牌获取实例状态、版本和选定的实体状态。数字实体（温度、湿度、功率…）可以绘制图表 — 非数字状态（开 / 关、家 / 离开）显示但不能绘制图表 |
| **Speedtest Tracker** | 最新速度测试结果 — 下载、上传、ping、抖动 |
| **Jellyfin** | 活动会话、库计数（电影 / 系列 / 歌曲）、服务器版本 |
| **Ollama** | 通过 Ollama API 获取正在运行的模型列表和服务器可用性 |
| **端口转发** | TCP 连接检查，以验证转发端口是否可从外部访问（路由器 / 防火墙 NAT 验证） |
## 每种监控类型发送的警报
所有监控类型在服务宕机时发送 **一个警报**，在恢复时发送 **一个警报** — 服务保持宕机状态时不会重复发送通知。故障在第一个警报时打开，在恢复时关闭。
额外类型特定警报：
| 类型 | 额外警报 |
|------|-------------|
| **HTTP** | SSL 过期警告 · SSL 过期 · 响应时间阈值超出 |
| **SSH** | CPU 高 · RAM 高 · 磁盘使用率高 |
| **Proxmox** | CPU 高 · RAM 高 |
| **Cloudflare** | 每个隧道的离线 / 恢复 |
| **AdGuard DNS** | 保护被禁用 / 重新启用 |
| **AdGuard Home** | 保护被禁用 / 重新启用 |
| **Syncthing** | 文件夹错误 · 设备断开连接 / 重新连接 |
| **Immich** | 关键磁盘使用率 |
| **HMS** | 每个 VPS 不可达 · CPU 高 · 内存高 |
| **Ultra.cc** | 存储空间不足 · 流量不足 |
| **Unraid** | 数组停止 · 磁盘错误 |
| **Home Assistant** | 实体变为不可用 · 实体恢复 |
## 通知（Apprise）
前往 **设置** 并添加您的 Apprise URL — 每行一个：
```
pover://UserKey@ApiToken/ # Pushover
tgram://BotToken/ChatID/ # Telegram
discord://WebhookID/WebhookToken/ # Discord
slack://TokenA/TokenB/TokenC/ # Slack
mailto://user:pass@gmail.com # 电子邮件
```
完整列表：https://github.com/caronc/apprise/wiki
## MCP 服务器
Orveil 暴露了一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，以便 AI 助手可以直接查询您的监控数据。
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `list_monitors` | 列出所有监控状态、SLA 目标、类别、维护状态（按状态 / 类别 / 启用筛选） |
| `get_monitor` | 获取特定监控的完整详细信息 + 指标 + 最近的快照历史 |
| `list_incidents` | 最近的故障，包含严重程度、持续时间、MTTR — 按开启 / 已解决或监控名称筛选 |
| `get_stats_detailed` | 完整统计数据：MTTR、MTTD、每监控运行时间（30 天）、SLA 合规性、每天故障次数、严重程度分布 |
| `list_annotations` | 附加到监控的手动事件标记（包含已解决的监控名称） |
| `get_uptime` | 每日监控运行时间历史（最多 90 天） |
| `trigger_check` | 为监控触发立即检查 |
资源 `orveil://monitors/{name}` 也可用于直接 URI 访问。
### 流式 HTTP（远程）
MCP 端点在 `/api/mcp` 提供。API 密钥在启动时自动生成，并在 **设置 → 集成 → MCP 服务器** 中可见。
```json
{
"mcpServers": {
"orveil": {
"url": "http://your-server:3050/api/mcp",
"type": "streamable-http",
"headers": {
"Authorization": "Bearer <your-mcp-api-key>"
}
}
}
}
```
### stdio（本地 / Claude Desktop）
```json
{
"mcpServers": {
"orveil": {
"command": "node",
"args": ["/path/to/orveil/backend/mcp-stdio.js"],
"env": {
"MONGO_URI": "mongodb://orveil:orveil_pass@localhost:27017/orveil"
}
}
}
}
```
与所有 `/api` REST 端点一样，该 API 密钥也作为 Bearer token 工作。
## Orveil AI
Orveil 内置了一个由 [Anthropic Claude](https://www.anthropic.com) 驱动的 AI 助手，可以直接从仪表盘回答关于您的基础设施的自然语言问题。
**工作原理：**
- 在 Anthropic API 密钥配置后，浮动按钮出现在右下角
- 助手通过 MCP 服务器与您的监控、故障、统计数据、注释和 SLA 数据交互
- 对话仅限于 Orveil — 助手不会回答无关问题
- 回答以用户语言（自动检测为法语/英语）给出
**设置：**
1. 前往 **设置 → 集成 → Orveil AI**
2. 输入您的 Anthropic API 密钥（`sk-ant-...`）
3. 选择使用的 Claude 模型（从 Anthropic 目录中加载）
4. 保存 — AI 按钮立即出现
API 密钥使用 AES-256-GCM（与监控凭证相同）加密存储。永不暴露给前端。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MONGO_USER` | `orveil` | MongoDB 用户名 |
| `MONGO_PASS` | `orveil_pass` | MongoDB 密码 |
| `JWT_SECRET` | `orveil-change-me-in-production` | JWT 签名密钥 — **请修改** |
| `ENCRYPTION_KEY` | *(无)* | 用于加密敏感的监控凭证的 AES-256-GCM 密钥 — **强烈推荐** |
| `ADMIN_USERNAME` | `admin` | 管理账户用户名 |
| `ADMIN_PASSWORD` | `orveil` | 管理账户密码 — **请修改** |
### 设置静止加密
生成密钥并添加到您的 `.env` 中：
```bash
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
```
设置后，之前保存的凭证将保持明文，直到您重新保存每个监控。新监控和您编辑的监控将在设置密钥后自动加密。
> **注意：** 如果您将 `ENCRYPTION_KEY` 添加到现有部署中，之前保存的凭证将保持明文，直到您重新保存每个监控。
## 许可证
[MIT](LICENSE)
