玩家在线时间统计与服务器监控 Mod

# 玩家在线时间统计与服务器监控 Mod


## 功能概述

本模组为 Minecraft 服务器提供以下核心功能：

### 1. 玩家时间追踪系统
– **精确计时**：记录白名单玩家的累计游戏时长
– **时间窗口统计**：
– 总时长（自模组安装起）
– 30天滚动窗口
– 7天滚动窗口
– **数据持久化**：自动保存至`player_time_data.json`
– **实时更新**：玩家在线时持续累积当前会话时间

### 2. 嵌入式 Web 服务
– **默认端口**：60048（可通过配置文件修改）
– **跨平台仪表盘**：响应式网页界面
– **数据可视化**：实时图表展示服务器性能指标

### 3. 游戏内指令
– `/onlineTime [页码]`：查看分页统计
– **交互式界面**：支持点击翻页功能

—

## 技术架构

### 数据追踪模块 (`PlayerTimeTracker.java`)
“`java
// 核心数据结构
public static class PlayerTimeData {
long totalTime = 0;
long lastLogin = 0;
RollingTimeWindow rolling30Days = new RollingTimeWindow(30);
RollingTimeWindow rolling7Days = new RollingTimeWindow(7);
}
“`
– **滚动窗口算法**：自动清理过期数据
– **线程安全设计**：使用`ConcurrentHashMap`存储数据
– **异步保存**：通过独立线程执行文件I/O

### Web 服务模块 (`WebServer.java`)

#### API 端点列表
| 端点 | 数据类型 | 描述 |
|———————–|———-|—————————|
| `/api/stats` | JSON | 全部玩家时间统计 |
| `/api/widget-data` | JSON | 实时在线玩家与排行榜数据 |
| `/api/server-status` | JSON | 服务器硬件性能指标 |
| `/api/online-players` | JSON | 分类在线玩家列表 |

### 前端监控界面

—

## 安装与配置

### 安装步骤
1. 将模组文件放入服务端`mods`目录
2. 启动服务器生成配置文件
3. 修改`playertime-config.json`：
“`json
{
“webPort”: 60048
}
“`

### 访问方式
1. 浏览器输入：`http://服务器IP:端口`
2. 默认凭证：无需认证

—

## 数据存储格式

### 玩家时间数据 (`player_time_data.json`)
“`json
{
“玩家UUID”: {
“totalTime”: 3600,
“lastLogin”: 1713571200,
“rolling30Days”: {
“entries”: [
{“timestamp”: 1713571200, “seconds”: 3600}
]
},
“rolling7Days”: { … }
}
}
“`

—

## 开发者文档

### 扩展API使用示例
“`javascript
// 获取服务器状态
fetch(‘/api/server-status’)
.then(res => res.json())
.then(data => {
console.log(‘当前TPS:’, 1000 / data.server.average_tick_time_ms);
});
“`

### 事件监听
“`java
// 玩家加入事件处理
ServerPlayConnectionEvents.JOIN.register((handler, sender, server) -> {
timeTracker.onPlayerJoin(handler.player);
});
“`

—

## 常见问题

### 数据异常处理
– 日志路径：`logs/PlayerTimeTracker.log`
– 自动恢复机制：损坏数据文件会自动重建

### 性能优化
– 内存管理：采用时间窗口算法限制数据增长
– 异步处理：使用`ExecutorService`线程池

—

## 开源协议
[MIT License](https://opensource.org/licenses/MIT) © 2025 BRanulf