LagDoctor
服务器卡顿诊断与处方 —— 无需性能分析器术语。
LagDoctor 从内部测量您的服务器(刻时间、每个区块的生物/方块实体密度、服务器配置值),并将结果转化为 按优先级排序的可操作建议,而非原始的性能分析数据。当性能分析器向您展示火焰图时,LagDoctor 会告诉您类似这样的话:
区域 r.0.-1 中坐标为 5,-3 的区块包含 412 个漏斗 —— 在 spigot.yml 中将 ticks-per.hopper-check 提高到 8。
所有功能均在服务器内部运行:无需外部服务、无需 Web API、无需依赖 spark。输出语言可选(英文 / 土耳其语)。
✨ 特性
- ? 刻采样器 —— 通过 Paper 的刻事件测量每一个刻,存入固定大小的环形缓冲区(默认:最近 6000 刻 ≈ 5 分钟)。报告 MSPT 平均值、p95、最差刻和尖峰数量。无额外线程,开销可忽略不计。
- ? 区块扫描器 —— 由命令触发,时间切片式 扫描(每刻限制扫描一定数量的区块),因此绝不会导致服务器冻结。统计每种类型的生物数量、掉落物品以及已加载区块中的方块实体(漏斗、刷怪笼、熔炉等)。
- ? 配置审计员 —— 从
server.properties、bukkit.yml、spigot.yml 和 config/paper-world-defaults.yml 读取约 15 个已知的关键值(严格只读,绝不修改),并标记超出推荐范围的任何设置。
- ? 基于规则的诊断引擎 —— 一套固定的规则集(漏斗密度、怪物堆积、物品堆积、红石密集型区块信号、过大的视距、模拟距离与可用 RAM 的比例,等等)将所有测量结果转换为发现项,这些发现项 按严重程度排序,每项都附带一行原因说明和一个具体的操作建议。
- ? 报告 —— 分页的游戏内聊天报告,带有可点击的
[TP] 按钮,可直接传送至问题区块;此外,在 plugins/LagDoctor/reports/ 下还会生成带时间戳的 markdown 文件(旧文件会自动轮换删除)。
- ? 本地化 —— 每条诊断字符串都位于
messages_en.yml / messages_tr.yml 中;缺失的键将回退到内置默认值。
明确不在范围内的功能:持续后台性能分析、方法级性能分析(这是 spark 的工作)、Web 面板、自动编辑配置文件、以及移除/清理实体。
? 安装
- 下载 LagDoctor jar 文件并将其放入服务器的
plugins/ 文件夹中。
- 重启服务器(或首次启动)。
- 可选:编辑
plugins/LagDoctor/config.yml 并运行 /lagdoctor reload。
要求: Paper(或其分支如 Purpur)1.20.4 – 1.21.x,Java 21。不支持 Spigot —— LagDoctor 所依赖的 tick-duration 事件仅适用于 Paper。
? 命令
| 命令 |
描述 |
权限 |
/lagdoctor scan [world] |
全面诊断:刻统计 + 区块扫描 + 配置审计,生成排名报告 |
lagdoctor.scan |
/lagdoctor report [page] |
重新显示上次扫描的报告 / 打印报告文件路径 |
lagdoctor.scan |
/lagdoctor top [entities|hoppers] |
列出最繁忙的 10 个区块(点击即可传送) |
lagdoctor.scan |
/lagdoctor tps |
即时 MSPT/TPS 摘要和尖峰计数(轻量级,随时安全使用) |
lagdoctor.tps |
/lagdoctor tp <world> <chunkX> <chunkZ> |
从报告中传送到某个区块(点击文本的目标) |
lagdoctor.teleport |
/lagdoctor reload |
重新加载配置文件和消息文件 |
lagdoctor.admin |
所有命令也支持从控制台执行(tp 除外)。默认仅限 OP 使用。/ld 可作为别名使用。
⚙️ 配置
language: en # en | tr — 所有输出的语言
sampler:
history-ticks: 6000 # 环形缓冲区大小(~5 分钟,假设 20 TPS)
spike-threshold-ms: 100 # 超过此值的刻被视为“尖峰”
scan:
chunks-per-tick: 20 # 扫描速度;越低对服务器影响越小,但扫描越慢
top-chunk-count: 10 # /lagdoctor top 列出的最繁忙区块数量
report:
save-to-file: true # 将 markdown 报告写入 plugins/LagDoctor/reports/
max-saved-reports: 20 # 超出此数量的旧报告文件会被自动删除
findings-per-page: 8 # 每页聊天显示的建议数量
thresholds: # 规则阈值(高级调整)
hoppers-per-chunk: 60
entities-per-chunk: 150
dropped-items-per-chunk: 200
tile-entities-per-chunk: 100
messages_tr.yml 和 messages_en.yml 会在首次启动时复制到插件文件夹中,您可以自由编辑它们。
? 数据与隐私
- 无数据库。 测量数据存储在内存中;仅保留最后一次扫描的结果。
- 报告以
plugins/LagDoctor/reports/scan-YYYYMMDD-HHmmss.md 格式写入;超出 max-saved-reports 数量的文件会被删除,优先删除最旧的。
- 服务器配置文件以 只读 方式打开 —— LagDoctor 永远不会修改它们。
❓ 常见问题
扫描会让服务器卡顿吗? 不会。扫描每刻最多处理 chunks-per-tick 个区块(默认为 20),因此即使是一个拥有数千个已加载区块的世界,也能在不引起可见 MSPT 增加的情况下完成扫描——只是耗时稍长几秒而已。
这与 spark 有何不同? spark 向您展示时间消耗在哪些 方法级别 上;而 LagDoctor 告诉您在 游戏机制/配置层面 该如何应对。两者互补。
? 源码
源代码和问题追踪器:CyberSoldier112/lagdoctor
LagDoctor
Diagnosis + prescription for server lag — no profiler jargon.
LagDoctor measures your server from the inside (tick times, entity/tile-entity density per chunk, server config values) and turns the results into ranked, actionable recommendations instead of raw profiler data. Where a profiler shows you flame graphs, LagDoctor tells you things like:
The chunk at 5,-3 in region r.0.-1 contains 412 hoppers — raise ticks-per.hopper-check in spigot.yml to 8.
Everything runs inside the server: no external services, no web API, no spark dependency. Output language is selectable (English / Turkish).
✨ Features
- ? Tick sampler — measures every tick via Paper's tick events into a fixed-size ring buffer (default: last 6000 ticks ≈ 5 minutes). Reports MSPT average, p95, worst tick and spike count. No extra threads, negligible cost.
- ? Chunk scanner — command-triggered, time-sliced scan (a limited number of chunks per tick) so it never freezes the server. Counts entities per type, dropped items, and tile entities (hoppers, spawners, furnaces) per loaded chunk.
- ? Config auditor — reads ~15 known-critical values from
server.properties, bukkit.yml, spigot.yml and config/paper-world-defaults.yml (strictly read-only, never modified) and flags anything outside recommended ranges.
- ? Rule-based diagnosis engine — a fixed rule set (hopper density, mob accumulation, item pile-ups, redstone-heavy chunk signals, oversized view distance, simulation distance vs. available RAM, and more) converts all measurements into findings sorted by severity, each with a one-line cause and a concrete action.
- ? Reports — paginated in-game chat report with clickable
[TP] buttons to teleport straight to a problem chunk, plus a timestamped markdown file under plugins/LagDoctor/reports/ (old files rotate automatically).
- ? Localization — every diagnosis string lives in
messages_en.yml / messages_tr.yml; missing keys fall back to bundled defaults.
Intentionally out of scope: continuous background profiling, method-level profiling (that's spark's job), web panels, automatic config editing, and entity removal/cleanup.
? Installation
- Download the LagDoctor jar and drop it into your server's
plugins/ folder.
- Restart the server (or start it for the first time).
- Optionally edit
plugins/LagDoctor/config.yml and run /lagdoctor reload.
Requirements: Paper (or a Paper fork such as Purpur) 1.20.4 – 1.21.x, Java 21. Spigot is not supported — the tick-duration events LagDoctor relies on are Paper-only.
? Commands
| Command |
Description |
Permission |
/lagdoctor scan [world] |
Full diagnosis: tick stats + chunk scan + config audit, ranked report |
lagdoctor.scan |
/lagdoctor report [page] |
Re-show the last scan report / print the report file path |
lagdoctor.scan |
/lagdoctor top [entities|hoppers] |
List the 10 busiest chunks (click to teleport) |
lagdoctor.scan |
/lagdoctor tps |
Instant MSPT/TPS summary and spike count (lightweight, safe anytime) |
lagdoctor.tps |
/lagdoctor tp <world> <chunkX> <chunkZ> |
Teleport to a chunk from a report (target of the clickable text) |
lagdoctor.teleport |
/lagdoctor reload |
Reload config and message files |
lagdoctor.admin |
All commands also work from the console (except tp). Everything defaults to OP-only. /ld is available as an alias.
⚙️ Configuration
language: en # en | tr — language of all output
sampler:
history-ticks: 6000 # ring buffer size (~5 min at 20 TPS)
spike-threshold-ms: 100 # a tick longer than this counts as a "spike"
scan:
chunks-per-tick: 20 # scan speed; lower = less impact, slower scan
top-chunk-count: 10 # busiest chunks listed by /lagdoctor top
report:
save-to-file: true # write markdown reports to plugins/LagDoctor/reports/
max-saved-reports: 20 # older report files are deleted automatically
findings-per-page: 8 # findings per chat page
thresholds: # rule thresholds (advanced tuning)
hoppers-per-chunk: 60
entities-per-chunk: 150
dropped-items-per-chunk: 200
tile-entities-per-chunk: 100
messages_tr.yml and messages_en.yml are copied into the plugin folder on first start and can be edited freely.
? Data & privacy
- No database. Measurements live in memory; only the last scan is kept.
- Reports are written as
plugins/LagDoctor/reports/scan-YYYYMMDD-HHmmss.md; files beyond max-saved-reports are deleted, oldest first.
- Server config files are opened read-only — LagDoctor never modifies them.
❓ FAQ
Does scanning lag the server? No. The scan processes at most chunks-per-tick chunks per tick (20 by default), so even a world with thousands of loaded chunks is swept without a visible MSPT increase — it just takes a few seconds longer.
How is this different from spark? spark shows you where the time goes at the method level; LagDoctor tells you what to do about it at the gameplay/config level. They complement each other.
? Source
Source code and issue tracker: CyberSoldier112/lagdoctor
评论 0
登录后参与评分
还没有评论,来抢沙发吧