# user-behavior-tracker

**Repository Path**: zhanghongbin0608/user-behavior-tracker

## Basic Information

- **Project Name**: user-behavior-tracker
- **Description**: 用于监测和分析用户在Web系统中的行为，主要用于识别机器人和自动化脚本操作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户行为追踪系统

## 项目概述

这是一个完整的用户行为追踪系统，用于监测和分析用户在Web系统中的行为，主要用于识别机器人和自动化脚本操作。

## 技术架构

### 后端技术栈
- **框架**: Spring Boot 2.6.13
- **ORM**: MyBatis Plus 3.5.3.1（支持多数据源）
- **数据库**: MySQL（主库） + Oracle（可选） + ClickHouse（大数据分析，可选）
- **缓存**: Redis + Redisson
- **工具**: Lombok, Hutool, FastJson2

### 前端技术栈
- **采集SDK**: 原生JavaScript（兼容性强）
- **分析展示**: Vue 3 + Element Plus + ECharts
- **特性**: 批量上报、压缩传输、重试机制、本地缓存

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    前端采集层                              │
│  ┌──────────────────────────────────────────────────┐   │
│  │  user-behavior-tracker-sdk.js                     │   │
│  │  - 事件监听（点击、焦点、变更等）                     │   │
│  │  - 设备指纹采集（Canvas、WebGL、Audio）              │   │
│  │  - 批量队列管理                                     │   │
│  │  - 本地存储缓存                                     │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ↓ HTTP/HTTPS
┌─────────────────────────────────────────────────────────┐
│                   数据传输层                               │
│  - 批量上报（减少请求次数）                                │
│  - 重试机制（网络异常处理）                                │
│  - 压缩传输（可选，减少传输量）                             │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                   后端接收层                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  BehaviorTrackingController                       │   │
│  │  - /api/behavior/report (单条上报)                │   │
│  │  - /api/behavior/batch-report (批量上报)          │   │
│  │  - /api/behavior/session/{id} (查询会话)         │   │
│  │  - /api/behavior/detect/{id} (机器人检测)        │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                  业务处理层                                │
│  ┌────────────────────┐  ┌─────────────────────────┐   │
│  │ BehaviorTracking   │  │  RobotDetection        │   │
│  │ Service            │  │  Service               │   │
│  │ - 数据转换         │  │  - 高频操作检测         │   │
│  │ - 会话管理         │  │  - 规律间隔检测         │   │
│  │ - 异步处理         │  │  - 鼠标轨迹异常         │   │
│  └────────────────────┘  │  - 设备指纹异常         │   │
│                          │  - 操作序列分析         │   │
│                          │  - 深夜活跃检测         │   │
│                          └─────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                   数据存储层                               │
│  ┌──────────────────┬──────────────────┬─────────────┐  │
│  │  MySQL (主库)     │  Oracle (可选)    │ ClickHouse  │  │
│  │  - user_behavior  │  - 业务数据库     │  (大数据)   │  │
│  │    _log          │                  │  - 行为分析  │  │
│  │  - user_session   │                  │  - 趋势统计  │  │
│  │  - behavior_alert │                  │             │  │
│  │  - robot_rule     │                  │             │  │
│  └──────────────────┴──────────────────┴─────────────┘  │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                  AI分析层（MCP）                            │
│  ┌──────────────────────────────────────────────────┐   │
│  │  MCPAnalysisService                               │   │
│  │  - 对接大模型API                                   │   │
│  │  - 智能行为分析                                    │   │
│  │  - 模式识别                                        │   │
│  │  - 异常检测                                        │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                 分析展示层 (Vue3)                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  - 实时监控面板                                    │   │
│  │  - 机器人检测报告                                  │   │
│  │  - 行为分析图表                                    │   │
│  │  - 异常告警管理                                    │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## 快速开始

### 1. 数据库初始化

```bash
# 执行SQL脚本
mysql -u root -p < src/main/resources/db/init.sql
```

### 2. 配置文件

修改 `application.yml` 中的数据库连接信息：

```yaml
spring:
  datasource:
    dynamic:
      datasource:
        mysql:
          url: jdbc:mysql://localhost:3306/behavior_tracker
          username: root
          password: your_password
```

### 3. 启动后端服务

```bash
mvn clean package
java -jar target/user-behavior-tracker-0.0.1-SNAPSHOT.jar
```

或直接运行：
```bash
mvn spring-boot:run
```

### 4. 前端集成

在需要追踪的HTML页面中引入SDK：

```html
<!DOCTYPE html>
<html>
<head>
    <title>示例页面</title>
</head>
<body>
    <!-- 警号输入框（可选） -->
    <input type="text" id="slmjjh" value="110001" />
    
    <!-- 业务内容 -->
    <button id="btn1">点击我</button>
    <input type="text" id="input1" />
    
    <!-- 引入SDK -->
    <script src="http://localhost:8080/js/user-behavior-tracker-sdk.js"></script>
    <script>
        // 初始化SDK
        BehaviorTracker.init({
            apiUrl: 'http://localhost:8080/api/behavior',
            policeNumberFields: ['slmjjh', 'policeNo'],
            enableBatch: true,
            batchSize: 50,
            batchInterval: 5000,
            debug: true
        });
        
        // 页面卸载时确保数据发送
        window.addEventListener('beforeunload', function() {
            BehaviorTracker.flush();
        });
    </script>
</body>
</html>
```

## API接口说明

### 1. 单条行为上报

**接口**: `POST /api/behavior/report`

**请求体**:
```json
{
  "sessionId": "SESS_ABC123",
  "policeNumber": "110001",
  "deviceId": "DEV_XYZ789",
  "eventType": "click",
  "pageUrl": "http://example.com/page",
  "pageTitle": "示例页面",
  "element": {
    "tagName": "BUTTON",
    "id": "btn1",
    "className": "primary-btn",
    "text": "提交",
    "xpath": "//*[@id='btn1']"
  },
  "coordinates": {
    "x": 100,
    "y": 200,
    "screenX": 500,
    "screenY": 600
  },
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "device": {
    "userAgent": "Mozilla/5.0...",
    "language": "zh-CN",
    "platform": "Win32",
    "screenResolution": "1920x1080",
    "timezone": "Asia/Shanghai"
  },
  "fingerprint": {
    "canvas": "ABC123",
    "webgl": "XYZ789"
  },
  "eventTimestamp": 1704441600000
}
```

### 2. 批量行为上报

**接口**: `POST /api/behavior/batch-report`

**请求体**: 数组形式的行为数据

### 3. 获取会话行为

**接口**: `GET /api/behavior/session/{sessionId}`

### 4. 机器人检测

**接口**: `GET /api/behavior/detect/{sessionId}`

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": true,
  "timestamp": 1704441600000
}
```

## 机器人检测算法

系统采用多维度检测策略，每个维度有不同权重：

| 检测维度 | 权重 | 说明 |
|---------|------|------|
| 高频操作检测 | 20 | 检测单位时间内异常高频的操作 |
| 相同操作间隔检测 | 15 | 检测相同操作之间的时间间隔是否过于规律 |
| 鼠标轨迹检测 | 15 | 检测是否存在没有鼠标移动的点击操作 |
| 设备指纹异常 | 10 | 检测设备指纹是否异常或缺失 |
| 操作序列异常 | 15 | 检测操作序列是否过于相似 |
| 深夜活跃检测 | 10 | 检测深夜时段异常活跃的行为 |
| 快速表单填写 | 15 | 检测表单填写速度是否异常快 |

**可疑分数计算**:
- 总分: 0-100
- 阈值: 70 (可配置)
- 分数 >= 阈值则判定为机器人

## 配置说明

### 后端配置 (application.yml)

```yaml
behavior:
  tracker:
    batch-size: 100                          # 批量上报阈值
    retention-days: 90                       # 数据保留天数
    robot:
      action-rate-threshold: 10              # 每秒操作次数阈值
      same-action-interval-threshold: 50     # 相同操作间隔阈值(ms)
      mouse-move-threshold: 5                # 鼠标移动距离阈值(px)
      suspicious-score-threshold: 70         # 可疑分数阈值
    mcp:
      enabled: true                          # 是否启用MCP分析
      api-url: http://localhost:8081/mcp/analyze
      timeout: 30000
```

### 前端SDK配置

```javascript
BehaviorTracker.init({
    apiUrl: 'http://localhost:8080/api/behavior',
    policeNumberFields: ['slmjjh', 'policeNo'],
    
    // 批量配置
    enableBatch: true,
    batchSize: 50,
    batchInterval: 5000,
    maxQueueSize: 500,
    
    // 重试配置
    enableRetry: true,
    maxRetryTimes: 3,
    retryInterval: 2000,
    
    // 存储配置
    enableLocalStorage: true,
    storageType: 'localStorage',
    
    // 事件追踪
    trackEvents: {
        click: true,
        focus: true,
        change: true,
        scroll: false,
        mousemove: false
    },
    
    // 采样配置
    sampling: {
        enabled: false,
        rate: 1.0
    },
    
    // 调试
    debug: false
});
```

## 数据库表结构

### user_behavior_log (用户行为日志表)
- 记录每一次用户操作
- 包含元素信息、坐标信息、设备信息、指纹信息
- 支持JSON扩展字段

### user_session (会话信息表)
- 记录用户会话
- 统计会话时长、操作次数
- 记录机器人检测结果

### behavior_alert (异常行为告警表)
- 记录可疑行为告警
- 支持告警级别和处理状态
- 可人工审核和处理

### robot_detection_rule (机器人检测规则表)
- 配置化的检测规则
- 支持动态调整权重
- 可启用/禁用规则

### ai_analysis_result (AI分析结果表)
- 记录大模型分析结果
- 保存置信度和分析摘要
- 用于模型效果评估

### device_fingerprint (设备指纹库表)
- 记录设备指纹信息
- 统计访问次数
- 标记可疑设备

## 性能优化建议

### 1. 数据库优化
- 定期清理历史数据（根据retention-days配置）
- 对高频查询字段建立索引
- 考虑使用ClickHouse存储历史数据

### 2. 前端优化
- 启用批量上报减少请求次数
- 调整batchSize和batchInterval平衡实时性和性能
- 对高频事件（scroll, mousemove）谨慎启用

### 3. 后端优化
- 使用异步处理提高响应速度
- 启用Redis缓存会话信息
- 使用消息队列处理大量数据

## 部署建议

### 开发环境
```bash
mvn spring-boot:run
```

### 生产环境
```bash
# 打包
mvn clean package -DskipTests

# 运行
java -jar -Xms512m -Xmx2g \
  -Dspring.profiles.active=prod \
  target/user-behavior-tracker-0.0.1-SNAPSHOT.jar
```

### Docker部署
```dockerfile
FROM openjdk:8-jre-alpine
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app.jar"]
```

## 注意事项

1. **隐私合规**: 确保符合数据隐私法规，明确告知用户数据采集
2. **性能影响**: 合理配置采集频率，避免影响用户体验
3. **存储容量**: 规划好数据存储策略，定期清理历史数据
4. **网络带宽**: 批量上报可有效减少网络开销
5. **跨域配置**: 生产环境需要正确配置CORS

## 后续规划

- [ ] Vue3前端分析平台
- [ ] 实时WebSocket推送
- [ ] 大模型智能分析（MCP集成）
- [ ] 行为回放功能
- [ ] 告警规则引擎
- [ ] 报表导出功能

## 许可证

本项目仅供学习和研究使用。

## 联系方式

如有问题，请提交Issue。