基准服务端

Benchmark Serverside

一个轻量级、AI 可读的 NeoForge 1.21.1 服务端性能基准测试模组。 轻量级 · 基于采样的 CPU 分析器 · JSON/文本报告 · 无需 JavaScript 渲染

---

📖 英文版

注意：本模组与我开发的另一个 Benchmark 模组没有任何关联！

总览

Benchmark Serverside 是一个面向 Minecraft 服务器的性能基准测试模组。它对服务器主线程进行采样，并将性能报告导出为结构化 JSON（或人类可读的文本摘要），同时附带完整的服务器上下文——模组列表、插件列表（混合端）、server.properties 配置、系统环境与实时运行状态。

报告设计为可直接供大语言模型（如 DeepSeek / GPT） 或服务器管理员使用，以便快速定位和优化卡顿根源——无需 JavaScript 渲染的分析器视图（例如 Spark）。

功能特性

• 轻量级采样型分析器 —— 采用基于 ThreadMXBean 的采样方式（而非插桩），采样间隔（默认 50 ms）与时长（默认 60 s）均可配置。采样开销可忽略不计，且仅在基准测试激活期间（/bcs start）运行，绝不影响服务器正常运行。
• 全面的环境采集 —— 收集模组列表、插件列表（混合端/Bukkit 服务器尽力而为）、服务器配置（view-distance、simulation-distance、entity-broadcast-range-percentage、network-compression-threshold、max-players）、Java/JVM 信息、操作系统、CPU 核心数、内存、磁盘空间、世界列表、在线玩家与当前 TPS。
• 热点分析 —— 将采样调用栈聚合成 Top N 热点列表（自耗与总耗采样数及占比），并附带代表性调用栈；同时区分空闲/等待与活跃样本，便于 AI 判断“服务器大部分时间在休眠”与“服务器正忙”。
• AI 友好的 JSON 报告 —— 字段名自解释（snake_case），保存至 benchmark-reports/benchmark_<yyyyMMdd_HHmmss>.json。
• 简洁的指令接口 —— /bcs 指令树，需要 OP 4 级权限。

环境要求

项目	值
Minecraft	1.21.1
NeoForge	21.1.241
Java	21

安装方法

1. 下载构建好的 jar（benchmarkserverside-1.0.0.jar）并将其放入服务器的 mods/ 文件夹。
2. 启动服务器。本模组为服务端模组；专用服务器无需客户端 jar。
3. 执行 /bcs start 并等待，然后检查 benchmark-reports/ 中生成的报告。

指令说明

所有子指令均需 OP 4 级权限。

指令	说明
/bcs start [seconds]	开始对服务器主线程采样（可覆盖默认时长）。
/bcs stop	停止当前采样；自动生成报告。
/bcs status	显示当前采样状态 / 最近一次结果。
/bcs report [format]	重新导出最近一次报告。format 为 json、txt 或 both。

配置说明

配置文件：config/benchmarkserverside-common.toml（首次运行时自动生成）。

配置项	默认值	说明
sampling.sampleIntervalMs	50	采样间隔（毫秒）。请保持 ≥ 50 ms。
sampling.sampleDurationSeconds	60	默认采样时长（秒）。
sampling.maxStackDepth	60	每次采样捕获的最大栈帧数。
sampling.maxSamples	100000	最大存储采样数（内存保护）。
sampling.excludedPackages	(JDK/系统前缀)	计算热点时过滤的包前缀。
report.directory	benchmark-reports	报告输出目录（相对于服务器根目录）。
report.topHotspots	50	报告中保留的热点数量。
report.writeTxt	false	自动生成时是否同时写入纯文本报告。

报告输出

报告保存在服务器根目录下的 benchmark-reports/ 中：

• benchmark_<yyyyMMdd_HHmmss>.json —— 结构化报告（首选，AI 可读）
• benchmark_<yyyyMMdd_HHmmss>.txt —— 人类可读摘要

JSON 报告包含：timestamp、sampling_duration_seconds、server_info、environment、config、plugins、mods、runtime 以及 profiling_results（总/空闲/活跃样本、带百分比的 top_hotspots、call_stacks）。

示例（节选）：

{
  "timestamp": "2026-08-16T12:00:00Z",
  "sampling_duration_seconds": 60,
  "server_info": { "type": "NeoForge", "version": "21.1.241", "minecraft_version": "1.21.1", "worlds": ["minecraft:overworld"] },
  "environment": { "java_version": "21.0.2", "os": "Windows 10 10.0 (amd64)", "cpu_cores": 8, "total_memory_mb": 16260, "free_memory_mb": 4838, "disk_free_gb": 33.0 },
  "config": { "view_distance": 10, "simulation_distance": 10, "entity_broadcast_range_percentage": 100, "network_compression_threshold": 256, "max_players": 20 },
  "mods": [ { "id": "neoforge", "name": "NeoForge", "version": "21.1.241" } ],
  "runtime": { "online_players": 0, "tps": 20.0, "process_cpu_usage_percent": 0.5, "system_cpu_usage_percent": 15.6 },
  "profiling_results": {
    "total_samples": 1200, "idle_samples": 800, "active_samples": 400,
    "top_hotspots": [
      { "method": "net.minecraft.server.level.ServerLevel.tick()", "samples": 150, "percentage": 12.5 }
    ]
  }
}

工作原理

• 守护线程通过 ThreadMXBean#getThreadInfo(threadId, maxDepth) 周期性捕获服务器主线程的调用栈（安全点采样——开销低，统计意义明确）。
• 最内层帧为 JDK 等待/睡眠的样本被归类为空闲；其余为活跃，用于热点统计。
• 采样完成时（自动或通过 /bcs stop），编译结果并在服务器主线程上写入报告。

从源码构建

git clone https://github.com/youyiMC/Benchmark-Serverside.git
cd Benchmark-Serverside
# Windows
gradlew.bat build
# macOS / Linux
./gradlew build

构建出的 jar 位于 build/libs/benchmarkserverside-1.0.0.jar。

许可证

本项目基于 GNU General Public License v3.0 开源。详见 LICENSE 文件。

原始 NeoForged MDK 模板文件仍按 MIT 许可证授权，详见 TEMPLATE_LICENSE.txt。

---

📖 中文版

注意：这个模组和我开发的另一个 Benchmark 模组没有任何关联！

简介

Benchmark Serverside 是一个面向 Minecraft 服务器的轻量级性能基准测试（Benchmark）模组。它对服务器主线程（Server Thread）进行采样，并将性能报告以结构化 JSON（或人类可读的纯文本摘要）的形式导出，同时附带完整的服务器上下文——模组列表、插件列表（混合端）、server.properties 配置、系统环境与实时运行状态。

报告专门设计为可供大语言模型（如 DeepSeek、GPT）直接阅读分析，也可供服主快速定位卡顿根源——无需像 Spark 那样依赖 JavaScript 渲染的报告。

功能特性

• 轻量级采样型 Profiler —— 基于 ThreadMXBean 的采样（Sampling）方式而非仪器（Instrumentation），采样间隔（默认 50 ms）与时长（默认 60 s）均可配置。仅在 /bcs start 后才开始采样，平时零开销，绝不干扰服务器正常运行。
• 全面的环境采集 —— 模组列表、插件列表（混合端/Bukkit 尽力而为）、服务器配置（视距、模拟距离、实体广播范围、网络压缩阈值、最大玩家数）、Java/JVM 信息、操作系统、CPU 核心、内存、磁盘、世界列表、在线玩家与当前 TPS。
• 热点分析 —— 将采样调用栈聚合成 Top N 热点列表（自耗/总耗采样数及占比）并附带代表性调用栈；同时区分空闲/等待与活跃样本，便于 AI 判断“服务器主要在睡眠”还是“服务器正忙”。
• AI 友好的 JSON 报告 —— 字段名自解释（snake_case），保存于 benchmark-reports/benchmark_<yyyyMMdd_HHmmss>.json。
• 简洁的指令接口 —— /bcs 指令树，需要 OP 4 级权限。

环境要求

项目	值
Minecraft	1.21.1
NeoForge	21.1.241
Java	21

安装方法

1. 将构建好的 jar（benchmarkserverside-1.0.0.jar）放入服务器的 mods/ 文件夹。
2. 启动服务器。本模组为服务端模组，专用服务器无需客户端文件。
3. 执行 /bcs start 开始采样，等待结束后在 benchmark-reports/ 目录查看生成的报告。

指令说明

所有子指令均需 OP 4 级权限。

指令	说明
/bcs start [seconds]	开始对服务器主线程采样（可指定时长）。
/bcs stop	停止当前采样，并自动生成性能报告文件。
/bcs status	查看当前采样状态 / 最近一次采样结果。
/bcs report [format]	手动导出最近一次采样的报告，format 为 json、txt 或 both。

配置说明

配置文件：config/benchmarkserverside-common.toml（首次运行自动生成）。

配置项	默认值	说明
sampling.sampleIntervalMs	50	采样间隔（毫秒），建议不低于 50ms。
sampling.sampleDurationSeconds	60	默认采样时长（秒）。
sampling.maxStackDepth	60	每次采样获取的最大栈帧深度。
sampling.maxSamples	100000	最大采样条数（防止内存溢出）。
sampling.excludedPackages	(JDK/系统前缀)	热点统计时过滤的包前缀。
report.directory	benchmark-reports	报告保存目录（相对服务器根目录）。
report.topHotspots	50	报告保留的热点方法数量。
report.writeTxt	false	自动生成报告时是否同时输出纯文本版本。

报告输出

报告默认保存在服务器根目录下的 benchmark-reports/ 文件夹中：

• benchmark_<yyyyMMdd_HHmmss>.json —— 结构化报告（首选，AI 可读）
• benchmark_<yyyyMMdd_HHmmss>.txt —— 人类可读的纯文本摘要

JSON 报告包含：timestamp、sampling_duration_seconds、server_info、environment、config、plugins、mods、runtime 与 profiling_results（总/空闲/活跃样本、带占比的 top_hotspots、call_stacks）。

工作原理

• 守护线程通过 ThreadMXBean#getThreadInfo(threadId, maxDepth) 周期性抓取服务器主线程调用栈（安全点采样，开销极小，统计意义上足以定位热点）。
• 栈顶帧命中 JDK 等待/睡眠方法的样本被归类为空闲，其余为活跃样本，用于热点统计。
• 采样结束（自动或 /bcs stop）后，结果被编译并在服务器主线程上写入报告文件。

从源码构建

git clone https://github.com/youyiMC/Benchmark-Serverside.git
cd Benchmark-Serverside
# Windows
gradlew.bat build
# macOS / Linux
./gradlew build

构建产物位于 build/libs/benchmarkserverside-1.0.0.jar。

许可证

本项目基于 GNU General Public License v3.0 开源，详见 LICENSE 文件。

原始 NeoForged MDK 模板文件仍按 MIT 许可证授权，详见 TEMPLATE_LICENSE.txt。