# HawkEye

**Repository Path**: liuhao3169/hawk-eye

## Basic Information

- **Project Name**: HawkEye
- **Description**: 你是否为无法及时的察觉线上服务的异常而感到头疼？当线上系统出现问题时，却无法及时的得到通知，当发现时为时已晚。于是，客户的投诉、凌晨的加班、女朋友的埋怨接踵而至😭.....
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 66
- **Forks**: 5
- **Created**: 2023-09-20
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 运维, Java, 监控

## README


<p align="center">
	<a href=""><img src="image/logo.png" width="45%"></a>
</p>
<p align="center">
  您的Star是我继续前进的动力，如果喜欢HawkEye请右上角帮忙点亮星星⭐!
</p>

<p align="center">
	   <a target="_blank" href="https://gitee.com/liuhao3169/hawk-eye/releases">
            <img src="https://img.shields.io/badge/release-1.0.0-blue" />
       </a>
	<a target="_blank" href="https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html">
		<img src="https://img.shields.io/badge/JDK-8+-brown.svg" />
	</a>
	   <a target="_blank" href="https://www.mysql.com/">
            <img src="https://img.shields.io/badge/MySQL-5.7%2B-green" />
       </a>
	<a target="_blank" href='https://gitee.com/liuhao3169/hawk-eye/stargazers'>
		<img src='https://gitee.com/liuhao3169/hawk-eye/badge/star.svg?theme=gvp' alt='star'/>
	</a>
	<a target="_blank" href='https://gitee.com/liuhao3169/hawk-eye/members'>
		<img src='https://gitee.com/liuhao3169/hawk-eye/badge/fork.svg?theme=gvp' alt='members'/>
	</a>
</p>



# 🤔什么是HawkEye?
你是否为无法及时的察觉线上服务的异常而感到头疼？当线上系统出现问题时，却无法及时的得到通知，当发现时为时已晚。于是，客户的投诉、凌晨的加班、女朋友的埋怨接踵而至😭.....

🦅HawkEye（鹰眼），顾名思义，立足打造像鹰眼一般敏锐的监控系统，它是通过监控error级别的异常实现告警推送与日志记录。

# 文档地址
https://www.wolai.com/xda6B8kDAt5G98Q7XA8tQm

# 😄安装部署

## 目录

- [介绍](#介绍)
- [环境要求](#环境要求)
- [HawkEye的部署](#HawkEye的部署)
  - [下载程序包](#下载程序包)
  - [解压](#解压)
  - [配置hawk-eye-server](#配置hawk-eye-server)
    - [1.配置加密](#1配置加密)
    - [2.配置数据库](#2配置数据库)
  - [运行](#运行)
  - [访问](#访问)

## 介绍

HawkEye项目结构目前有 **前后端不分离** 和 **前后端分离** 两种形式

## 环境要求

**后端（HawkEyeServer）的环境要求**

- JDK1.8及以上
- MySQL5.7及以上

**前端（HawkEyeUI）的环境要求**

- 无要求

**客户端（HawkEyeClient）的环境要求**

- JDK1.8及以上
- 项目为spring项目
- 日志框架为logback
- 使用Maven作为项目管理工具

## HawkEye的部署

> 📌本章将演示如何部署HawkEye**前后端不分离版本**

### 下载程序包

[https://gitee.com/liuhao3169/hawk-eye/releases](https://gitee.com/liuhao3169/hawk-eye/releases/ "https://gitee.com/liuhao3169/hawk-eye/releases")

### 解压

```markdown
hawk-eye
  |--bin  #脚本程序
    |--start.sh #启动脚本
    |--start.bat #启动脚本
    |--hawk-eye.sql #数据库初始化脚本
  |--conf #配置文件
    |--application.yml #主配置文件,服务端的系统级别的配置
    |--application-prod.yml #副配置文件,服务端的数据库连接地址
  |--logs #日志
  |--plugins #扩展插件
      |--webhook #webhook扩展插件
      |--storage #日志存储扩展插件
  |--target
    |--hawk-eye-server.jar #jar包文件 项目结构介绍
```


### 配置hawk-eye-server

打开hawk-eye/conf/applicaion-prod.yml配置文件，配置如下信息

#### 1.配置加密

**什么是授权加密？**

```yaml
hawk-eye:
    #授权加密相关配置
    encipher:
      #开启授权加密
        enabled: true
        secure-key: 32位，采用的是AES算法，配置的秘钥要保证hawk-eye-client和hawk-eye-server端是一致的 applicantion-prod.yml
```


生成AES密钥的代码

```java
    public static void main(String[] args) throws NoSuchAlgorithmException {
        String str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
        Random random = new Random();
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < 32; i++) {
            int number = random.nextInt(62);
            sb.append(str.charAt(number));
        }
        System.out.println(sb.toString());
    }
```


#### 2.配置数据库

```yaml
# 数据源配置
spring:
    datasource:
        type: com.alibaba.druid.pool.DruidDataSource
        driverClassName: com.mysql.cj.jdbc.Driver
        druid:
            # 主库数据源
            master:
                url: jdbc:mysql://localhost:3306/hawk-eye?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
                username: 数据库用户名
                password: 数据库密码
```


> 📌数据库脚本位于hawk-eye/bin/hawk-eye.sql目录下，一般无需手动初始化数据库，HawkEye服务端在启动时会检测数据库表，如果不存在或者缺失，会初始化全部数据库表。

初始化完毕后，可将如下配置改为false，此后启动服务将不再检测数据库表

```yaml
hawk-eye:  
  server:  
    init-tables: false
```


### 运行

> Linux环境中运行hawk-eye/bin/server.sh命令启动

> Windows环境中运行hawk-eye/bin/server.bat命令启动

这里以Windows环境为例，运行start.bat

![](image/image_SlY_iuFuqY.png)

### 访问

HawkEye服务启动完成后，就可以直接使用浏览器访问啦！

> 📌默认端口：8899

使用管理员账号登录，默认管理员账号：

> 📌账号：hawkeye
> 密码：hawkeye

![](image/image_DR6YU_0UWT.png)

# 😊快速开始

## 目录

- [HawkEye服务端配置](#HawkEye服务端配置)
  - [登录服务端](#登录服务端)
  - [创建用户](#创建用户)
  - [创建webhook](#创建webhook)
    - [1.创建钉钉群聊](#1创建钉钉群聊)
    - [2.创建钉钉webhook机器人](#2创建钉钉webhook机器人)
    - [3.维护webhook](#3维护webhook)
  - [创建模板](#创建模板)
  - [创建告警配置](#创建告警配置)
- [HawkEye客户端](#HawkEye客户端)
  - [引入HawkEye客户端依赖](#引入HawkEye客户端依赖)
  - [配置yml](#配置yml)
  - [配置logback.xml](#配置logbackxml)
- [启动服务](#启动服务)
- [测试告警推送](#测试告警推送)
- [查看告警日志](#查看告警日志)

## HawkEye服务端

### 登录服务端

HawkEye服务部署完成后，就可以使用浏览器访问啦！

> 📌默认端口：8899

使用默认管理员账号登录，默认管理员账号：

> 📌账号：hawkeye
> 密码：hawkeye

![](image/image_T2-6M0lddS.png)

### 创建用户

用户的创建有两种形式：从首页进行新用户注册、在用户管理模块创建

本章示例中将演示如何在用户管理模块创建新用户

点击“新建”按钮，创建新用户

![](image/image_3bxqt3HqsI.png)

> 📌角色默认有一个普通角色，该角色具有除系统管理菜单外的所有权限

> 📌手机号必须为真实手机号，才可接收到告警推送

### 创建webhook

> 📌HawkEye默认支持HTTP和钉钉webhook机器人的通知方式，如果需要接入其它第三方平台，可以参考 **扩展webhook**

本次将演示使用内置的**钉钉webhook机器人**的方式实现告警推送  [**什么是钉钉webhook机器人？**](https://open.dingtalk.com/document/orgapp/webhook-robot "什么是钉钉webhook机器人？")

#### 1.创建钉钉群聊

点击钉钉应用的右上角“+”号，选择发起群聊，之后勾选需要接收告警推送的相关人员，点击确定即可。

![](image/image_UyCjlDiTp5.png)

#### 2.创建钉钉webhook机器人

[**什么是钉钉webhook机器人？**](https://open.dingtalk.com/document/orgapp/webhook-robot "什么是钉钉webhook机器人？")

![](image/image_0-3oILFAKP.png)

点击“添加机器人”

![](image/image_h9S6tylR-S.png)

在上方搜索栏中搜索“自定义”

![](image/image_NHgbAg1nvC.png)

输入机器人的名字，配置安全设置，本示例中使用的是加签的方式  [**什么是安全设置？**](https://open.dingtalk.com/document/robots/customize-robot-security-settings "什么是安全设置？")

![](image/image_9SspAN9z0y.png)

![](image/image_p7wXYQ5-lW.png)

#### 3.维护webhook

![](image/image_v460G7q-j2.png)

- **名称**：一般为群聊名称
- **请求实现**：默认支持钉钉和原生HTTP（POST）两种形式，可以自行扩展。在本示例中选钉钉
- **请求地址**：对应钉钉webhook机器人的webhook地址
- **密钥**：对应钉钉webhook机器人的加签
- **扩展参数**：扩展请求实现时如果需要额外参数可以使用该字段维护

### 创建模板

模板是用来定义推送到第三方平台的消息格式以及告警日志形式的 **模板配置**

![](image/image_qSWUCIwKXj.png)

点击“新增字段”按钮，配置模板字段

![](image/image_zjrdsTHqP7.png)

- **字段名**：字段名为推送的告警信息的名称
- **字段值**：字段值为推送的告警信息的数值，分为内置和自定义两种类型
  - 内置：HawkEye内置了一些常用的日志属性，可以直接使用，无需额外处理
  - 自定义：请参考 **模板配置**
- **告警输出**：表示该字段是否输出到第三方平台中，因为有时我们可能只需要推送部分字段到第三方平台，详细信息会在告警日志中查看

### 创建告警配置

HawkEye以服务为维度对业务异常进行监控，告警配置就是通过配置服务的监控规则、推送方式等信息达到监控的目的。具体配置项请参考 **告警配置**

点击“新增”按钮，新增告警配置

![](image/1737214188512_rXXMm4-pVs.png)

示例

![](image/image_saPumCFOL4.png)

**选项说明**

- **服务英文名**：必须和需要监控的应用中spring.application.name属性一致，否则配置将无法生效
- **负责人**：用来维护该服务的负责人，在钉钉群中会@的人员。该示例中使用刚才创建的“沉香”用户
- **降噪规则**：在周期时间内如果一个异常连续报错的次数超过了阈值，则在静默时间内不再继续告警，周期和静默时间的单位都分钟。**HawkEye如何判断异常是同一个异常？**
- **频度升级阈值**：对于重复发生的异常但是没有及时察觉或者解决的异常应该重点关注，为此HawkEye内置了频度等级这一属性，共有三个等级（一级、二级、三级），默认是三级。当某异常发生的次数超过了频度升级阈值时，会对等级进行升级，直到至最高等级一级后将不再升级。
- **认证密码**：这里的认证密码必须和HawkEyeClient中配置的hawk-eye.client.token属性相同才能成功颁发，告警才能成功推送。
- **状态**：停用的服务任何error级别的日志将不再进行告警和记录。
- **告警模板**：告警信息推送到第三方平台的模板格式，本示例中选择上文创建的“通用模板”。**可以参考 进行扩展**
- **外部推送**：推送的第三方平台的webhook，本示例中选择上文创建的“钉钉二群”。**如何创建webhook？**

## HawkEye客户端

### 引入HawkEye客户端依赖

```xml
<dependency>  
 <groupId>com.hawk.eye</groupId>  
  <artifactId>hawk-eye-client</artifactId>  
 <version>1.0.0</version>  
</dependency>
```


### 配置yml

```yaml
hawk-eye:
    client:
        #开启hawk-eye客户端
        enabled: true
        #hawk-eye服务端的后台地址
        hawk-eye-server-address: http://127.0.0.1:8080
        #服务的授权密码，必须和HawkEye服务端告警配置中设置的认证密码一致
        token: 123456
    #授权加密相关配置
    encipher:
        #开启授权加密
        enabled: true
        secure-key: 32位秘钥，采用的是AES算法，配置的秘钥要保证hawk-eye-client和hawk-eye-server端是一致的 yml
```


生成AES密钥的代码

```java
    public static void main(String[] args) throws NoSuchAlgorithmException {
        String str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
        Random random = new Random();
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < 32; i++) {
            int number = random.nextInt(62);
            sb.append(str.charAt(number));
        }
        System.out.println(sb.toString());
    }
```


### 配置logback.xml

```xml
    <!-- HAWK_EYE_ERROR -->
    <appender name="HAWK_EYE_ERROR" class="com.hawk.eye.client.logback.appender.http.HawkEyeHttpErrorAppender">
        <encoder charset="UTF-8" class="com.hawk.eye.client.logback.encoder.HawkEyeLoggingEventCompositeJsonEncoder"/>
    </appender>
    <!-- HAWK_EYE_ERROR_ASYNC-->
    <appender name="HAWK_EYE_ERROR_ASYNC" class="com.hawk.eye.client.logback.appender.HawkEyeAsyncAppender">
        <discardingThreshold>0</discardingThreshold>
        <queueSize>512</queueSize>
        <appender-ref ref="HAWK_EYE_ERROR"/>
    </appender>
```

### 使用appender
```xml
    <root level="INFO" additivity="false">
        <appender-ref ref="HAWK_EYE_ERROR_ASYNC"/>
    </root>
```


## 启动服务

看到如下图日志输出，说明HawkEye客户端正在尝试连接HawkEye服务端

![](image/image_z_tGTLB7s3.png)

看到如下图的日志输出，说明连接建立成功

![](image/1737214489597_Rcc-srk8y7.png)

## 测试告警推送

接入成功后，我们可以手动触发一次error级别的日志输出，测试告警推送等功能。下面示例是在服务中编写了一个接口，手动触发了一次error级别的日志输出

```java
    /**
     * 测试
     */
    @GetMapping(value = "/testApi")
    public ApiResult testApi() {
        log.error("测试一下", new RuntimeException());
        return ApiResult.ok("testApi");
    }
```


**访问接口**

```http
GET http://localhost:8080/hawk-eye/service/testApi 
```


告警推送至钉钉的效果如下图所示：

![](image/image_eY3gkoivEd.png.mark.png)

## 查看告警日志

告警推送完毕后，详细的日志信息可以在告警日志模块中查看

![](image/image_GSN8DI_ODV.png)