# monitor-agent

**Repository Path**: SoulBGM/monitor-agent

## Basic Information

- **Project Name**: monitor-agent
- **Description**: 通过http接口的方式来收集服务器的运行状态（CPU、内存、磁盘、jvm、Bps）以及查询程序是否活着的功能
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 4
- **Created**: 2020-10-28
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent

## README

# monitor-agent

一个轻量级的服务器监控代理，通过 HTTP 接口暴露服务器运行状态，支持进程存活检测和远程命令执行。

## 功能概述

| 接口 | 路径 | 说明 |
|------|------|------|
| 心跳检测 | `GET /heartbeat` | 返回 `up`，用于快速探测 agent 是否存活 |
| 硬件信息 | `GET /info` | CPU、内存、磁盘、JVM、网络流量 |
| 时间同步 | `GET /ntpdate` | NTP 时间同步状态与偏移量 |
| 远程执行 | `POST /exec` | 执行 shell 命令并返回输出 |
| 进程检测 | `GET /isAlive` | 批量检测指定进程是否存活 |
| 目录列表 | `GET /listDir` | 列出指定目录下的文件和子目录 |
| 文件下载 | `GET /getFile` | 下载文件或目录（目录自动打包为 ZIP） |
| 日志下载 | `GET /getLog` | 下载日志文件并打包为 ZIP |
| 文件上传 | `POST /uploadFile` | 上传单个文件到远程目录 |
| 目录上传 | `POST /uploadDir` | 上传 ZIP 文件到远程目录并自动解压 |

## 技术栈

- Spring Boot 2.7.18
- Java 8
- oshi-core（系统信息采集）
- commons-net（NTP 时间同步）

## 快速开始

### 1. 构建

```bash
mvn clean package -DskipTests
```

构建产物位于 `target/monitor-agent/`，包含：
- `monitor-agent.jar` — 主程序
- `lib/` — 依赖 jar 包
- `bin/` — 启动脚本
- `config/application.yml` — 配置文件

### 2. 启动

```bash
cd target/monitor-agent/

# 前台运行
bin/start.sh console

# 后台运行
bin/start.sh

# Systemd 方式（含开机自启）
bin/start.sh systemd
```

默认监听端口 **9300**。

### 3. 验证

```bash
curl http://localhost:9300/heartbeat
# 返回: up
```

## 配置说明

`config/application.yml`：

```yaml
server:
  port: 9300

spring:
  servlet:
    multipart:
      max-file-size: 1GB
      max-request-size: 1GB

config:
  # NTP 服务器地址，留空则跳过时间同步
  ntpIp: ntp.ntsc.ac.cn

  # 监听网卡名称，留空则自动获取
  networkName:

  # 监控中心地址（可选）
  # centre: 10.1.60.204:9991,10.1.60.71:9992

  # 需要监控的服务（可选）
  # service:
  #   soul-template:
  #     - checkPort: 8088

  # 需要监控的软件进程（可选）
  # software:
  #   ZooKeeper:
  #     - processName: QuorumPeerMain
  #       checkPort: 2181
  #   Kafka:
  #     - processName: kafka.Kafka
  #       checkPort: 9092
  #   MySQL:
  #     - processName: mysqld.exe
  #       checkPort: 3306
```

## API 接口详解

### 心跳检测

```bash
curl http://10.1.7.200:9300/heartbeat
```

返回：`up`

### 获取硬件状态信息

```bash
curl http://10.1.7.200:9300/info
```

返回字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `cpu.logicalCpuCount` | int | 逻辑 CPU 数 |
| `cpu.physicalCpuCount` | int | 物理 CPU 数 |
| `cpu.totalUsed` | double | CPU 总使用率 |
| `cpu.idle` | double | CPU 空闲率 |
| `mem.total` | double | 内存总量（字节） |
| `mem.used` | double | 已用内存（字节） |
| `mem.free` | double | 剩余内存（字节） |
| `jvm.jdkVersion` | String | JDK 版本 |
| `jvm.runTime` | long | JVM 运行时长（毫秒） |
| `sys.computerName` | String | 服务器名称 |
| `sys.computerIp` | String | 服务器 IP |
| `sys.osName` | String | 操作系统 |
| `sys.osArch` | String | 系统架构 |
| `sysFiles[].dirName` | String | 盘符路径 |
| `sysFiles[].total` | long | 总磁盘大小（字节） |
| `sysFiles[].used` | long | 已用磁盘（字节） |
| `sysFiles[].usage` | double | 磁盘使用率 |
| `network.name` | String | 网卡名称 |
| `network.ip` | String | IP 地址 |
| `network.recvBytes` | long | 每秒接收字节数 |
| `network.sendBytes` | long | 每秒发送字节数 |

### 获取时间同步信息

```bash
curl http://10.1.7.200:9300/ntpdate
```

返回：

| 字段 | 类型 | 说明 |
|------|------|------|
| `ntpIp` | String | NTP 服务器地址 |
| `offsetSeconds` | double | 时间偏移秒数 |
| `status` | int | 0=服务器不可用，1=未对准，2=成功对准 |

### 执行命令

```bash
curl -X POST http://10.1.7.200:9300/exec -d 'command=ifconfig'
```

参数：`command` — 要执行的 shell 命令

返回：命令的标准输出文本

### 进程存活检测

```bash
curl "http://10.1.7.200:9300/isAlive?processNames=QuorumPeerMain:2181,namenode.NameNode"
```

参数：`processNames` — 进程名列表，格式为 `name:port`，多个以逗号分隔

返回：

```json
[
  {"name": "QuorumPeerMain:2181", "status": true},
  {"name": "namenode.NameNode", "status": true}
]
```

## 配套工具

本项目通常与 **monitor-cli** 配合使用，实现批量运维操作：

```bash
# monitor-cli 通过 HTTP 调用各节点的 monitor-agent
monitor-cli exec -g web "systemctl status nginx"
monitor-cli info -g all
monitor-cli ps -g db "QuorumPeerMain:2181"
```

### 目录列表

```bash
curl "http://10.1.7.200:9300/listDir?path=/home/monitor-agent"
```

参数：`path` — 远程目录绝对路径

返回：JSON 数组，包含该目录下的文件和子目录名称

```json
["bin", "config", "lib", "monitor-agent.jar"]
```

### 文件下载

```bash
curl -O -J "http://10.1.7.200:9300/getFile?path=/home/monitor-agent/config/application.yml"
```

参数：`path` — 远程文件或目录的绝对路径

说明：
- 下载文件时直接返回文件流
- 下载目录时 Agent 自动打包为 ZIP 返回
- 响应头 `Content-Disposition` 中包含文件名信息

### 日志下载

```bash
curl -O -J "http://10.1.7.200:9300/getLog?logPath=/home/app/logs/info&zipName=app-logs.zip"
```

参数：
- `logPath` — 日志目录或文件路径
- `zipName` — 下载的 ZIP 文件名（可选，默认 `logs.zip`）

说明：将指定日志路径打包为 ZIP 后下载，便于批量收集日志。

### 文件上传

```bash
curl -X POST http://10.1.7.200:9300/uploadFile \
  -F "file=@/local/path/file.txt" \
  -F "targetDir=/remote/dir"
```

参数（multipart/form-data）：
- `file` — 要上传的文件
- `targetDir` — 远程目标目录

返回：Agent 返回的上传结果文本

### 目录上传

```bash
curl -X POST http://10.1.7.200:9300/uploadDir \
  -F "file=@/local/path/archive.zip" \
  -F "targetDir=/remote/dir" \
  -F "clean=false"
```

参数（multipart/form-data）：
- `file` — ZIP 压缩包
- `targetDir` — 远程目标目录
- `clean` — 是否先清空目标目录（`true`/`false`）

说明：
- Agent 端使用 `ZipInputStream` 纯 Java 解压，不依赖远程主机的 `unzip` 命令
- 典型场景：配合 `/getFile` 下载目录后，将 ZIP 上传到目标节点并解压还原为目录

## 注意事项

1. monitor-agent 当前无认证机制，建议部署在内网环境或通过防火墙限制访问
2. `/exec` 接口可执行任意命令，请确保访问可控
3. `/uploadFile` 和 `/uploadDir` 接口需要在 Agent 端实现对应处理逻辑
4. 默认端口 9300，可通过 `server.port` 修改