# Meerkat

**Repository Path**: fsscms/Meerkat

## Basic Information

- **Project Name**: Meerkat
- **Description**: Meerkat服务器集群实时监控平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://monitor.phpframe.org/#
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: influxdb, Gin, Postgresql, gorm, vue3

## README

# Meerkat 服务器集群实时监控平台

<div align="center">
  <img src="https://www.phpframe.org/logo.png" width="600" alt="Logo">
</div>

Meerkat（猫鼬/狐獴）是一种群居动物，在非洲南部生活，它们喜欢群居生活，跟小伙伴在一起的时候，总有一个专职"站岗放哨"的哨兵，发现危险后，通过不同频率组合的叫声传递超过20种信息，精准指示天敌类型和方位，让其它小伙伴及时警觉危险。

**Meerkat 服务器集群实时监控平台**正是寓意如此——像狐獴一样及早发现服务器的状态异常，及时预警。

## 简介

当您管理数十上百台裸金属服务器、虚拟机、Docker 容器、K8s 节点时，需要时刻紧盯上面的服务状态、负载性能等各项指标。Meerkat 正是为解决这个痛点而来的——帮您主动报警，及时介入。

Agent 端一旦部署在客户机上，主动采集指标，向中心机汇聚、存储与展示，几分钟后就可以在 Web Dashboard 看到各项指标。

**核心特性：**
- 指标不经 Telegraf 直写 InfluxDB，经 **monitor-agent** 用 **mTLS gRPC** 上报到 **Collector**
- 内置 SSH 控制台，支持用户名连接、密钥连接
- SFTP 模块：管理服务器文件上传、下载、删除、重命名
- 高危命令过滤，防止服务器崩盘
- SSH 命令会话审计，录像回放
- 计划任务与计划任务日志
- 完整的后台管理系统（用户、部门、角色、岗位、菜单、字典、系统设置、缓存、系统日志、附件等）

**演示地址：** https://monitor.phpframe.org/

**商务合作：** 联系作者微信：xdbyvibm6（注明来意）

---

## 架构概览

### 部署架构

```
                         中心机
┌────────────────────────────────────────────────────────────┐
│  浏览器 :3000 ──► Vue（/dev-api 代理到 webserver :8090）    │
│  webserver :8090 ──读──► PostgreSQL :5432、InfluxDB :8086  │
│  Collector :9500 (mTLS gRPC) ──写──► PG + InfluxDB         │
│  Collector 管理 HTTPS :8080（自签 CA）                       │
└────────────────────────────┬───────────────────────────────┘
                             │ gRPC + mTLS
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   被监控机 A            被监控机 B            被监控机 N
   Telegraf → :9510      同左                  同左
   monitor-agent         monitor-agent         monitor-agent
   health :9511           health :9511          health :9511
```

### 数据流

```
Telegraf → monitor-agent (本地 :9510) → Collector (mTLS gRPC) → PostgreSQL / InfluxDB ← webserver ← 浏览器
```

---

## 技术栈

| 组件 | 技术 |
|------|------|
| **monitor-agent** | Go 1.27+，gRPC 客户端、SQLite 积压、HTTP 收 Telegraf |
| **collector** | Go 1.27+，GORM、Influx 写入、Outbox |
| **webserver** | Go 1.27+，Gin、JWT |
| **控制台** | Vue 3、Vite、TypeScript、Element Plus、ECharts、pnpm |
| **RPC** | gRPC + Protobuf |
| **传输安全** | mTLS |

---

## 快速开始

### 环境要求

**被监控机（Agent 端）：**
- Telegraf 1.40+
- Go 1.27+（仅编译需要）

**中心机（Server 端）：**
- PostgreSQL 16+
- InfluxDB 2.x
- Go 1.27+
- Node.js LTS + pnpm

### 构建

```powershell
# Windows 构建
$env:CGO_ENABLED = "0"
cd client && go build -trimpath -ldflags "-s -w" -o ../monitor-agent.exe ./cmd/monitor-agent
cd ../server && go build -trimpath -ldflags "-s -w" -o ../collector.exe ./cmd/collector
cd ../webserver && go build -trimpath -ldflags "-s -w" -o ../webserver.exe ./cmd/webserver
```

```bash
# Linux 构建
export CGO_ENABLED=0
cd client && go build -trimpath -ldflags "-s -w" -o ../dist/linux-amd64/monitor-agent ./cmd/monitor-agent
cd ../server && go build -trimpath -ldflags "-s -w" -o ../dist/linux-amd64/collector ./cmd/collector
cd ../webserver && go build -trimpath -ldflags "-s -w" -o ../dist/linux-amd64/webserver ./cmd/webserver
```

### 启动顺序

**中心机：**
```
PostgreSQL → InfluxDB → Collector → webserver → (前端)
```

**被监控机：**
```
monitor-agent → Telegraf
```

---

## 配置文件

| 文件 | 用途 |
|------|------|
| `client/configs/agent.yaml` | Agent 配置 |
| `server/configs/server.local.yaml` | Collector 配置 |
| `webserver/configs/webserver.yaml` | Web API 配置 |
| `Telegraf/telegraf.conf` | Telegraf 采集配置 |
| `client/certs/` | mTLS 证书目录 |

### 关键配置项

**Agent 端 (`agent.yaml`)：**
- `agent_id`：全局唯一标识
- `server_address`：中心机地址，如 `192.168.1.100:9500`
- 证书路径：`ca_file`、`cert_file`、`key_file`

**中心机 (`server.local.yaml`)：**
- PostgreSQL 连接信息
- InfluxDB 连接信息（org: hkc, bucket: bucket）
- TLS 证书路径
- gRPC 监听地址 `:9500`

---

## 端口一览

| 端口 | 组件 | 所在机器 |
|------|------|----------|
| 5432 | PostgreSQL | 中心 |
| 8086 | InfluxDB | 中心 |
| 9500 | Collector gRPC | 中心 |
| 8080 | Collector 管理 HTTPS | 中心 |
| 8090 | webserver | 中心 |
| 3000 | Vite 开发前端 | 中心 |
| 9510 | Agent 收 Telegraf | 被监控 |
| 9511 | Agent healthz | 被监控 |

---

## 一键脚本

| 脚本 | 平台 | 作用 |
|------|------|------|
| `scripts/setup-windows.ps1` | Windows | 环境检查、安装依赖、编译 |
| `scripts/windows/server/start.ps1` | Windows | 启动中心服务 |
| `scripts/windows/agent/start.ps1` | Windows | 启动 Agent + Telegraf |
| `scripts/setup-linux.sh` | Linux | 安装依赖、编译 |
| `scripts/linux/server/start.sh` | Linux | 启动中心服务 |
| `scripts/linux/agent/start.sh` | Linux | 启动 Agent + Telegraf |

---

## 健康检查

```powershell
# Windows
Invoke-WebRequest http://127.0.0.1:8090/healthz -UseBasicParsing
Invoke-WebRequest http://127.0.0.1:9511/healthz -UseBasicParsing

# 验证 Telegraf → Agent 通路（期望 204）
Invoke-WebRequest -Method POST -Uri http://127.0.0.1:9510/v1/telegraf/metrics `
  -ContentType "text/plain" -Body "probe,source=manual value=1i" -UseBasicParsing
```

```bash
# Linux
curl -sS http://127.0.0.1:8090/healthz
curl -sS http://127.0.0.1:9511/healthz
```

---

## 证书生成

测试环境一键生成：

```powershell
powershell -File .\scripts\cert\Generate-mTLSCerts.ps1
```

或：

```powershell
cd client
go run .\cmd\certgen -out ..\client\certs
```

生成的文件：
- `ca.pem`：双方信任根
- `server.pem` / `server-key.pem`：仅 Collector 中心机
- `client.pem` / `client-key.pem`：所有 Agent（可复制分发）

---

## 更多信息

- [Windows 本机启动详解](./doc/windows-local-startup.md)
- [Telegraf 与 Agent 部署指南](./doc/telegraf-monitor-agent-deployment.md)
- [Collector 详细说明](./server/README_ZH.md)
- [webserver 配置说明](./webserver/README.md)
- [Agent 开发规范](./AGENT.md)

---

## 下一步计划

- [ ] 完成 RDP 远程连接、操作
- [ ] 告警参数设置
- [ ] 告警日志留存
- [ ] 告警通知（短信、飞书、邮件等）
- [ ] 接入大模型对告警进行分析处理，形成报告
- [ ] 命令编排

---

**许可证：** 查看 [LICENSE](./LICENSE) 文件