LagXpert Free v2.7 — 自主优化器与卡顿诊断
LagXpert 是一款支持多平台(Folia/Paper/Spigot/Bukkit)并兼容基岩版的 Minecraft 服务器性能插件。它主要做两件事:随着负载变化自动进行优化,并告诉你服务器卡顿的原因和位置。
v2.7 更新内容
卡顿诊断
大多数性能插件只会告诉你 TPS。更难的问题是哪个区块正在拖我后腿。/lagxpert diagnose 命令可以回答这个问题。
- 根据相对限制对区块进行排名,而非原始计数。 一个拥有 40 只生物但上限为 200 的区块是正常的。一个拥有 12 个漏斗但上限为 8 的区块才是问题所在。按原始计数排名会选出错误的区块。
- 使用当前实际生效的限制,因此报告内容与玩家此刻的体验相符。
- 统计干预历史。 如果一个区块在过去一小时内被插件清理过二十次,它的排名会高于那些仅仅只是“满”了的区块。
- 用通俗语言解释原因。 无论是负载集中在少数区块还是遍布各处、哪种违规类型占主导、内存压力是否是真正的罪魁祸首、哪个世界承载了负载——以及当原因超出 LagXpert 的处理范围时,让你停止在错误的地方寻找。
- 诊断卡顿不会造成卡顿。 区块快照在所属线程上获取;所有评分过程都在异步进行。结果会短暂缓存,以便同时执行的命令和 GUI 共享一次扫描。
交互式 GUI 提供五个屏幕:概览、分页的热点列表、带有传送按钮的单区块详细分析、纠正操作审计追踪以及历史趋势图。
优先适配基岩版的 GUI 渲染
此处的基岩版支持是结构性的,而非装饰性的。屏幕尺寸来自配置的安全尺寸,每个槽位的位置都基于该实际尺寸计算,因此不会放置任何基岩版客户端无法渲染的内容。Geyser 翻译效果不佳的材质会自动替换,lore(描述文本)会被截断,如果某个物品栏完全无法打开,完整报告将以聊天文本形式发送。
紧急控制器
一个具有迟滞效应以防止状态抖动的四级状态机(NORMAL → WARNING → CRITICAL → EMERGENCY)。每个状态应用分级且可配置的响应措施:生物上限降低、自然生成阻止、强制物品清理、激进区块卸载、AI 距离缩减、红石时钟关闭、全服 AI 冻结,以及可选的自定义命令。
在 v2.7 中,EMERGENCY 层级变得可达,且最后四项响应措施变为功能可用——此前它们虽然可配置和显示,但从未执行。
自适应阈值
每个区块的限制都会根据服务器健康状况进行缩放。结合了两个输入指标:来自 TPS 和内存的连续健康数据,以及离散的紧急状态。两者中更严格的那个胜出;它们永远不会相乘,否则会导致数值叠加到无法游玩的程度。限制只会向下缩放——你配置的值始终是上限——并设有一个可配置的下限。通过 lagxpert.limits.* 权限授予的玩家专属限制会原样保留。
优化配置文件
四种预设配置文件(relaxed, balanced, aggressive, performance),通过 /lagxpert profile <name> 应用。应用配置文件时会快照它所替代的值,因此 revert(恢复)命令能还原你的配置,而不是假设的默认值。auto-revert-minutes 用于防止在处理故障时应用了激进配置文件却忘记撤销的情况。
功能特性
自主优化
- 具有分级状态响应的紧急控制器
- 针对生物、存储、实体和红石的自适应限制
- 智能调度器,根据状态和优先级调整任务间隔:低优先级任务在 WARNING 状态下暂停,紧急优先级任务运行速度最高提升 4 倍
- 闭环机制:检测 → 行动 → 记录
- 所有纠正操作的完整审计追踪,可在游戏内查询
诊断与监控
- 带有通俗语言结论的排名区块热点分析
- 带有传送至热点功能的交互式诊断 GUI
- 1/5/15 分钟窗口内的 TPS、刻时间、卡顿尖峰检测
- 性能历史记录,支持可配置的时间间隔和保留策略,持久化至磁盘
- 每日最差时段检测、峰值玩家追踪、实体增长趋势
限制与清理
- 针对生物、漏斗、箱子、熔炉、 barrels(木桶)、发射器、投掷器、潜影盒、TNT、活塞和观察者的单区块限制
- 带有泛洪填充断路器的红石电路追踪
- 带有警告和深渊回收系统的物品清理器
- 实体清理:无效、重复、废弃、越界以及超过实体上限的区块中的实体
- 智能移除生物,保护命名、驯服、拴绳、骑乘和装备了物品的实体
- 生物 AI 优化器(基于距离和按类型)
- 爆炸半径控制与连锁反应预防
- 载具限制与废弃载具清理
- 鞘翅速度限制与引雷冷却
- 线程安全的控制台日志过滤器
管理
- 交互式 GUI 配置(
/lagxpertgui) - 按世界覆盖的配置
- 覆盖所有子系统的热重载
- bStats 指标集成
模块与配置文件
| 模块 | 配置文件 | 说明 |
|---|---|---|
| General | config.yml |
模块开关、自适应阈值、操作日志、性能历史 |
| Mobs | mobs.yml |
生物上限、AI 优化器、智能移除 |
| Storage | storage.yml |
每个区块的方块上限 |
| Redstone | redstone.yml |
电路追踪、泛洪填充破坏器 |
| Alerts | alerts.yml |
通知开关、冷却时间、速率限制 |
| Task Scanner | task.yml |
自动区块扫描间隔 |
| Item Cleaner | itemcleaner.yml |
地面物品清理 + Abyss 恢复 |
| Entity Cleanup | entitycleanup.yml |
实体移除目标、每区块实体上限 |
| Monitoring | monitoring.yml |
TPS、内存、区块、卡顿峰值阈值 |
| Chunks | chunks.yml |
区块加载/卸载、预加载 |
| Emergency Controller | emergency-controller.yml |
状态阈值、分级响应 |
| Vehicles | vehicles.yml |
载具上限、废弃清理 |
| Abilities | abilities.yml |
鞘翅速度、激流冷却 |
| Explosions | explosions.yml |
爆炸半径、连锁反应预防 |
| Console Filter | console-filter.yml |
控制台日志正则过滤器 |
| Profiles | profiles.yml |
优化预设 |
| Messages | messages.yml |
所有插件消息(i18n) |
命令
| 命令 | 说明 | 权限 |
|---|---|---|
/lagxpert |
主命令和帮助 | lagxpert.use |
/lagxpert diagnose [chat|refresh] |
查找导致卡顿的原因及其位置 | lagxpert.admin.diagnostics |
/lagxpert status |
性能仪表板 | lagxpert.admin.status |
/lagxpert optimize |
完整优化流程,包含优化前后对比 | lagxpert.admin.optimize |
/lagxpert emergency [status|force-normal] |
紧急状态控制 | lagxpert.admin.emergency |
/lagxpert profile [list|<name>|revert] |
应用优化配置 | lagxpert.admin.profile |
/lagxpert reload |
热重载所有配置和子系统 | lagxpert.admin |
/lagxpert inspect <x> <z> [world] |
检查特定区块 | lagxpert.admin |
/lagxpertgui [open|diagnostics] |
交互式图形界面 | lagxpert.gui |
/chunkstatus |
当前区块使用信息 | lagxpert.chunkstatus |
/tps |
服务器性能指标 | lagxpert.tps |
/abyss |
恢复最近被清除的物品 | lagxpert.abyss |
/clearitems [all|world] |
手动清理物品 | lagxpert.clearitems |
权限
lagxpert.admin 包含所有 lagxpert.admin.* 节点。更细粒度的节点允许为受限管理员授予单一能力,而不赋予其他权限——例如,仅拥有只读诊断功能,而无法重写配置文件或移除实体。
| 权限 | 默认值 | 说明 |
|---|---|---|
lagxpert.use |
true | 基本命令访问权限 |
lagxpert.admin |
op | 所有管理命令 |
lagxpert.admin.status |
op | 只读性能仪表板 |
lagxpert.admin.diagnostics |
op | 只读卡顿分析和诊断 GUI |
lagxpert.admin.diagnostics.teleport |
op | 从 GUI 传送至问题区块 |
lagxpert.admin.optimize |
op | 运行优化(移除实体、卸载区块) |
lagxpert.admin.emergency |
op | 紧急控制,包括强制恢复正常 |
lagxpert.admin.profile |
op | 应用配置(重写配置文件) |
lagxpert.gui |
op | GUI 访问权限 |
lagxpert.chunkstatus |
true | 区块状态命令 |
lagxpert.tps |
true | TPS 命令 |
lagxpert.abyss |
true | 物品恢复 |
lagxpert.clearitems |
op | 手动清理 |
lagxpert.emergency.notify |
op | 接收紧急状态广播 |
lagxpert.monitoring.alerts |
op | 接收性能警报 |
lagxpert.alerts.receive |
op | 接收所有限制警报 |
lagxpert.bypass.mobs |
false | 绕过生物上限和紧急生成阻止 |
lagxpert.bypass.redstone |
false | 绕过红石控制 |
lagxpert.bypass.abilities |
false | 绕过能力限制 |
lagxpert.bypass.* |
false | 绕过所有限制 |
lagxpert.limits.mobs.<N> |
false | 玩家或等级的自定义生物上限 |
lagxpert.limits.hoppers.<N> |
false | 玩家或等级的自定义漏斗上限 |
lagxpert.notifications.mob-removal |
false | 接收附近生物移除通知 |
lagxpert.console.view-filtered |
false | 在聊天中接收被屏蔽的控制台消息 |
安装
- 将
LagXpert-2.7.jar放入plugins/目录 - 启动服务器以生成配置文件
- 运行
/lagxpert diagnose查看服务器当前状态 - 根据需要调整
.yml文件 - 执行
/lagxpert reload无需重启即可应用更改
从 v2.6.x 升级
- 停止服务器并替换 jar 文件
- 重启服务器以生成
emergency-controller.yml和profiles.yml - 现有配置保持兼容;新键使用安全默认值
lagshield.yml已不再使用,可以删除
要求
- Java 11+
- Minecraft 1.16+ (Spigot / Paper / Purpur / Folia)
- 无必需依赖项。Geyser 和 Floodgate 是用于基岩版玩家检测的可选软依赖项。
开发者 API
// 响应区块过载
@EventHandler
public void onChunkOverload(ChunkOverloadEvent event) {
event.getChunk();
event.getCause();
}
// 统计区块内容
LagXpertAPI.countLivingEntitiesInChunk(chunk);
LagXpertAPI.countTileEntitiesInChunk(chunk, Material.HOPPER);
LagXpertAPI.countAllShulkerBoxesInChunk(chunk);
// 读取配置的限值
LagXpertAPI.getMobLimit();
LagXpertAPI.getHopperLimit();
LagXpertAPI.getLimitForMaterial(Material.HOPPER); // 如果未管理则返回 -1
由于 v2.7 中的限值是动态的,LagXpertAPI 返回的是配置值。如需获取当前正在执行的限值,请通过自适应引擎:
AdaptiveThresholdEngine adaptive = AdaptiveThresholdEngine.getInstance();
```java
// 当前生效的限制,在生命值和紧急缩放之后
adaptive.getEffectiveMobLimit(world);
adaptive.getEffectiveLimit(LimitCategory.STORAGE, ConfigManager.getMaxHoppersPerChunk(world));
adaptive.isCurrentlyThrottling();
// 服务器状态、审计跟踪和历史记录
EmergencyController.getInstance().getCurrentState();
ActionLogger.getInstance().getRecent(50);
PerformanceHistory.getInstance().getEntityTrend(6);
// 诊断报告(回调在主线程上运行)
LagDiagnosticsEngine.getInstance().requestReport(false, report -> {
if (report == null) return; // 扫描已在运行中
report.getTopChunks(10);
report.getObservations();
});
按世界覆盖配置
将以其世界名称命名的文件放入 plugins/LagXpert/config/worlds/ 目录,以仅针对该世界覆盖全局设置。需要在 config.yml 中启用 per-world-settings.enabled: true。
支持的路径:
limits:
mobs-per-chunk, hoppers-per-chunk, chests-per-chunk, furnaces-per-chunk,
blast_furnaces-per-chunk, smokers-per-chunk, barrels-per-chunk,
droppers-per-chunk, dispensers-per-chunk, shulker_boxes-per-chunk,
tnt-per-chunk, pistons-per-chunk, observers-per-chunk
entity-cleanup:
advanced:
max-entities-per-chunk # 该世界的实体总数上限
chunk-management:
auto-unload:
inactivity-threshold-minutes
preload:
enabled
monitoring:
tps:
alert-thresholds:
warning, critical
任何未指定的值将回退到全局值。按世界设置的值在负载下仍会由自适应引擎进行缩放调整。
限制值为 0 表示“无限制”,而非“禁止”。 使用 1 可实现最严格的限制。
Folia 支持
Folia 将服务器划分为独立刻更新的区域,实体只能被拥有其所在区块的线程访问。LagXpert 尊重这一机制:所有读取或移除实体的操作都通过区域调度器按区块分发执行。这涵盖了物品清理器、实体清理、载具清理、按区块实体修剪、紧急 AI 冻结、诊断扫描以及快照和优化报告中的实体计数等功能。
在 Spigot 和 Paper 上,相同的分发机制会在多个刻中将区块分批处理,从而将一次长时间卡顿的刻拆分为多次短暂的刻。这一点至关重要,因为这些清理操作恰好是在服务器已经承受压力时运行的。
一个后果是,清理总数仅在清理扫描完成时才会返回,因此 /clearitems 和 /lagxpert optimize 会在命令完成时报告结果。
已知限制
- 没有自动化测试套件;验证是针对构建产物手动执行的。
/lagxpert optimize报告的 TPS 为滚动平均值,而非命令前后的差值,因为在该命令的执行期间平均值无法发生显著变化。
支持
Discord:
bStats 插件 ID: 25746
LagXpert Free v2.7 — Autonomous Optimizer & Lag Diagnostics
LagXpert is a Minecraft server performance plugin with multi-platform support (Folia/Paper/Spigot/Bukkit) and Bedrock compatibility. It does two things: it optimizes automatically as load changes, and it tells you why your server is lagging and where.
What's New in v2.7
Lag Diagnostics
Most performance plugins tell you your TPS. The harder question is which build is
doing this to me. /lagxpert diagnose answers that.
- Ranks chunks relative to their limits, not by raw counts. A chunk with 40 mobs against a limit of 200 is fine. A chunk with 12 hoppers against a limit of 8 is the problem. Ranking by raw count surfaces the wrong chunks.
- Uses the limits actually in force, so the report matches what players are experiencing right now.
- Counts intervention history. A chunk the plugin has cleaned up twenty times in the last hour ranks above one that is merely full.
- Explains itself in plain language. Whether load is concentrated in a few chunks or spread everywhere, which violation type dominates, whether memory pressure is the real culprit, which world carries the load — and when the cause is outside LagXpert's scope, so you stop looking in the wrong place.
- Diagnosing lag does not cause lag. Chunk snapshots are taken on the owning thread; all scoring happens asynchronously. Results are cached briefly so a command and a GUI opened together share one scan.
An interactive GUI provides five screens: overview, paginated hotspot list, per-chunk drill-down with a teleport button, the corrective-action audit trail, and historical trends.
Bedrock-first GUI rendering
Bedrock support here is structural, not cosmetic. Screen sizes come from the configured safe size and every slot position is computed from that actual size, so nothing is placed where a Bedrock client cannot render it. Materials Geyser translates badly are substituted automatically, lore is capped, and if an inventory cannot be opened at all the full report is delivered as chat text.
Emergency Controller
A four-level state machine (NORMAL → WARNING → CRITICAL → EMERGENCY) with hysteresis to prevent flapping. Each state applies graduated, configurable responses: mob cap reduction, natural spawn blocking, forced item cleanup, aggressive chunk unloading, AI distance reduction, redstone clock shutdown, server-wide AI freeze, and optional custom commands.
In v2.7 the EMERGENCY tier became reachable and the last four responses became functional — previously they were configurable and displayed but never executed.
Adaptive Thresholds
Every per-chunk limit scales with server health. Two inputs are combined:
continuous health from TPS and memory, and the discrete emergency state. The
more restrictive of the two wins; they are never multiplied, which would
compound into unplayable values. Limits are only ever scaled down — your
configured value is always the ceiling — with a configurable floor. Per-player
limits granted via lagxpert.limits.* permissions are honored verbatim.
Optimization Profiles
Four presets (relaxed, balanced, aggressive, performance) applied with
/lagxpert profile <name>. Applying a profile snapshots the values it replaces,
so revert restores your configuration rather than an assumed default.
auto-revert-minutes guards against applying an aggressive profile during an
incident and forgetting about it.
Features
Autonomous optimization
- Emergency Controller with graduated per-state responses
- Adaptive limits for mobs, storage, entities and redstone
- Smart scheduler that adjusts task intervals by state and priority: low-priority tasks pause during WARNING, emergency-priority tasks run up to 4x faster
- Closed loop: detect → act → log
- Full audit trail of every corrective action, queryable in-game
Diagnostics & monitoring
- Ranked chunk hotspot analysis with plain-language conclusions
- Interactive diagnostics GUI with teleport-to-hotspot
- TPS across 1/5/15-minute windows, tick times, lag spike detection
- Performance history with configurable interval and retention, persisted to disk
- Worst-hour-of-day detection, peak player tracking, entity growth trends
Limits & cleanup
- Per-chunk limits for mobs, hoppers, chests, furnaces, barrels, droppers, dispensers, shulker boxes, TNT, pistons and observers
- Redstone circuit tracking with flood-fill circuit breaker
- Item cleaner with warnings and the Abyss recovery system
- Entity cleanup: invalid, duplicate, abandoned, out-of-bounds, and chunks over the entity ceiling
- Smart mob removal protecting named, tamed, leashed, ridden and equipped entities
- Mob AI optimizer (distance-based and per-type)
- Explosion radius control and chain-reaction prevention
- Vehicle limits and abandoned vehicle cleanup
- Elytra speed limit and Riptide cooldown
- Thread-safe console log filter
Administration
- Interactive GUI configuration (
/lagxpertgui) - Per-world configuration overrides
- Hot reload covering every subsystem
- bStats metrics integration
Modules & Config Files
| Module | Config File | Description |
|---|---|---|
| General | config.yml |
Module toggles, adaptive thresholds, action logger, performance history |
| Mobs | mobs.yml |
Mob limits, AI optimizer, smart removal |
| Storage | storage.yml |
Block limits per chunk |
| Redstone | redstone.yml |
Circuit tracking, flood-fill breaker |
| Alerts | alerts.yml |
Notification toggles, cooldowns, rate limits |
| Task Scanner | task.yml |
Auto-chunk scan interval |
| Item Cleaner | itemcleaner.yml |
Ground item cleanup + Abyss recovery |
| Entity Cleanup | entitycleanup.yml |
Entity removal targets, per-chunk entity ceiling |
| Monitoring | monitoring.yml |
TPS, memory, chunk, lag spike thresholds |
| Chunks | chunks.yml |
Chunk loading/unloading, preloading |
| Emergency Controller | emergency-controller.yml |
State thresholds, graduated responses |
| Vehicles | vehicles.yml |
Vehicle limits, abandoned cleanup |
| Abilities | abilities.yml |
Elytra speed, Riptide cooldown |
| Explosions | explosions.yml |
Explosion radius, chain reaction prevention |
| Console Filter | console-filter.yml |
Console log regex filters |
| Profiles | profiles.yml |
Optimization presets |
| Messages | messages.yml |
All plugin messages (i18n) |
Commands
| Command | Description | Permission |
|---|---|---|
/lagxpert |
Main command and help | lagxpert.use |
/lagxpert diagnose [chat|refresh] |
Find what is causing lag and where | lagxpert.admin.diagnostics |
/lagxpert status |
Performance dashboard | lagxpert.admin.status |
/lagxpert optimize |
Full optimization pass with before/after | lagxpert.admin.optimize |
/lagxpert emergency [status|force-normal] |
Emergency state control | lagxpert.admin.emergency |
/lagxpert profile [list|<name>|revert] |
Apply optimization profiles | lagxpert.admin.profile |
/lagxpert reload |
Hot-reload all configurations and subsystems | lagxpert.admin |
/lagxpert inspect <x> <z> [world] |
Inspect a specific chunk | lagxpert.admin |
/lagxpertgui [open|diagnostics] |
Interactive GUIs | lagxpert.gui |
/chunkstatus |
Current chunk usage info | lagxpert.chunkstatus |
/tps |
Server performance metrics | lagxpert.tps |
/abyss |
Recover recently cleared items | lagxpert.abyss |
/clearitems [all|world] |
Manual item cleanup | lagxpert.clearitems |
Permissions
lagxpert.admin implies every lagxpert.admin.* node. The finer nodes exist so a
limited admin can be granted one capability without the rest — for example
read-only diagnostics without the ability to rewrite configs or remove entities.
| Permission | Default | Description |
|---|---|---|
lagxpert.use |
true | Basic command access |
lagxpert.admin |
op | All administrative commands |
lagxpert.admin.status |
op | Read-only performance dashboard |
lagxpert.admin.diagnostics |
op | Read-only lag analysis and diagnostics GUI |
lagxpert.admin.diagnostics.teleport |
op | Teleport to a problem chunk from the GUI |
lagxpert.admin.optimize |
op | Run optimization (removes entities, unloads chunks) |
lagxpert.admin.emergency |
op | Emergency controls, including force-normal |
lagxpert.admin.profile |
op | Apply profiles (rewrites config files) |
lagxpert.gui |
op | GUI access |
lagxpert.chunkstatus |
true | Chunk status command |
lagxpert.tps |
true | TPS command |
lagxpert.abyss |
true | Item recovery |
lagxpert.clearitems |
op | Manual cleanup |
lagxpert.emergency.notify |
op | Receive emergency state broadcasts |
lagxpert.monitoring.alerts |
op | Receive performance alerts |
lagxpert.alerts.receive |
op | Receive all limit alerts |
lagxpert.bypass.mobs |
false | Bypass mob limits and emergency spawn blocking |
lagxpert.bypass.redstone |
false | Bypass redstone control |
lagxpert.bypass.abilities |
false | Bypass ability limits |
lagxpert.bypass.* |
false | Bypass all limits |
lagxpert.limits.mobs.<N> |
false | Custom mob limit for a player or rank |
lagxpert.limits.hoppers.<N> |
false | Custom hopper limit for a player or rank |
lagxpert.notifications.mob-removal |
false | Receive nearby mob removal notifications |
lagxpert.console.view-filtered |
false | Receive suppressed console messages in chat |
Installation
- Drop
LagXpert-2.7.jarintoplugins/ - Start the server to generate configuration files
- Run
/lagxpert diagnoseto see your server's current state - Adjust the
.ymlfiles as needed /lagxpert reloadto apply changes without a restart
Upgrading from v2.6.x
- Stop the server and replace the jar
- Restart so
emergency-controller.ymlandprofiles.ymlare generated - Existing configs remain compatible; new keys use safe defaults
lagshield.ymlis no longer used and can be deleted
Requirements
- Java 11+
- Minecraft 1.16+ (Spigot / Paper / Purpur / Folia)
- No required dependencies. Geyser and Floodgate are optional soft dependencies used for Bedrock player detection.
Developer API
// React to chunk overloads
@EventHandler
public void onChunkOverload(ChunkOverloadEvent event) {
event.getChunk();
event.getCause();
}
// Count contents of a chunk
LagXpertAPI.countLivingEntitiesInChunk(chunk);
LagXpertAPI.countTileEntitiesInChunk(chunk, Material.HOPPER);
LagXpertAPI.countAllShulkerBoxesInChunk(chunk);
// Read configured limits
LagXpertAPI.getMobLimit();
LagXpertAPI.getHopperLimit();
LagXpertAPI.getLimitForMaterial(Material.HOPPER); // -1 if unmanaged
Because limits are dynamic in v2.7, LagXpertAPI returns the configured
value. For the limit currently being enforced, go through the adaptive engine:
AdaptiveThresholdEngine adaptive = AdaptiveThresholdEngine.getInstance();
// Limit in force right now, after health and emergency scaling
adaptive.getEffectiveMobLimit(world);
adaptive.getEffectiveLimit(LimitCategory.STORAGE, ConfigManager.getMaxHoppersPerChunk(world));
adaptive.isCurrentlyThrottling();
// Server state, audit trail and history
EmergencyController.getInstance().getCurrentState();
ActionLogger.getInstance().getRecent(50);
PerformanceHistory.getInstance().getEntityTrend(6);
// Diagnostics report (callback runs on the main thread)
LagDiagnosticsEngine.getInstance().requestReport(false, report -> {
if (report == null) return; // a scan was already running
report.getTopChunks(10);
report.getObservations();
});
Per-world overrides
Drop a file named after your world into plugins/LagXpert/config/worlds/ to
override global settings for that world only. Requires
per-world-settings.enabled: true in config.yml.
Supported paths:
limits:
mobs-per-chunk, hoppers-per-chunk, chests-per-chunk, furnaces-per-chunk,
blast_furnaces-per-chunk, smokers-per-chunk, barrels-per-chunk,
droppers-per-chunk, dispensers-per-chunk, shulker_boxes-per-chunk,
tnt-per-chunk, pistons-per-chunk, observers-per-chunk
entity-cleanup:
advanced:
max-entities-per-chunk # total entity ceiling for this world
chunk-management:
auto-unload:
inactivity-threshold-minutes
preload:
enabled
monitoring:
tps:
alert-thresholds:
warning, critical
Anything omitted falls back to the global value. Per-world values are still scaled down by the adaptive engine under load.
A limit of 0 means "no limit", not "ban". Use 1 for the strictest
possible restriction.
Folia support
Folia splits the server into independently ticking regions, and an entity may only be touched by the thread that owns its chunk. LagXpert honors that: every operation that reads or removes entities is dispatched per chunk through the region scheduler. This covers the item cleaner, entity cleanup, vehicle cleanup, per-chunk entity trimming, the emergency AI freeze, the diagnostics scan, and even entity counting for snapshots and the optimize report.
On Spigot and Paper the same dispatch runs chunks in batches across ticks, which turns one long stalling tick into several short ones. That matters because these sweeps run precisely when the server is already under pressure.
A consequence is that cleanup totals arrive when a sweep finishes rather than
instantly, so /clearitems and /lagxpert optimize report their results on
completion.
Known limitations
- There is no automated test suite; verification is performed against the built artifact.
/lagxpert optimizereports TPS as a rolling average rather than a before/after delta, because the average cannot move within the span of the command.
Support
Discord:
bStats Plugin ID: 25746
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 LagXpert Free
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
LagXpert v2.7 — 自主优化器与卡顿诊断
本次更新做了两件事:让自动优化真正运行起来,并增加了一个诊断系统,告诉你服务器为什么卡顿以及在哪里卡顿。
诚实地表述很重要。v2.6 版本发布了一些配置,这些配置会被读取、在命令中显示,但随后从未被采取任何行动。本次更新填补了这些漏洞,并增加了验证机制,防止它们再次无声地失效。
? 卡顿诊断(新增)
管理员最常见的问题不是“我的 TPS 是多少”,而是“哪个建筑在搞我”。v2.7 直接回答了这个问题。
/lagxpert diagnose 扫描每个已加载的区块,并生成一份排名报告:
- 评分是相对于上限而言,而非原始计数。 一个拥有 40 只生物但上限为 200 的区块是正常的。一个拥有 12 个漏斗但上限为 8 的区块则是有问题的。按原始计数排名会暴露错误的区块,因此每个指标都贡献其在当前世界中实际适用的上限百分比。
- 干预历史会计入评分。 如果一个区块在过去一小时内被 LagXpert 清理过二十次,它的排名会比仅仅当前已满的区块更高。
- 上限来自实时自适应引擎,因此报告反映了当时正在执行的内容,与玩家体验相匹配。
- 通俗易懂的结论,而不仅仅是数字。报告会告诉你负载是集中在少数几个区块还是分散在各处,哪种违规类型占主导地位,内存压力是否是真正的原因,哪个世界承担了负载,以及——重要的是——当原因超出 LagXpert 的范围时,这样你就不会在错误的地方继续寻找了。
扫描分为两个阶段:区块快照在所属线程上收集,然后所有评分都在异步进行。诊断卡顿绝不能导致卡顿。报告缓存时间为 30 秒,以便同时发出的命令和打开的 GUI 共享一次扫描,并发扫描将被拒绝而不是排队。
诊断 GUI
在游戏内使用 /lagxpert diagnose 会打开一个包含五个屏幕的交互式界面:
- 概览 — 服务器状态、三个时间窗口内的 TPS、内存、每个世界的实体总数、通俗语言诊断以及当前生效的上限。
- 热点 — 分页排名的区块列表,按严重程度着色,每个区块显示哪些指标超出了上限。
- 区块详情 — 单个区块的所有测量贡献者,以及一个传送按钮,让你前往查看。
- 纠正措施 — 审计跟踪,带有时间戳、触发器和计数。
- 趋势 — 每天最糟糕的小时、峰值玩家数、实体增长方向和 24 小时预测。
Bedrock 兼容性
这是优先针对 Bedrock 构建的,而不是事后修补的:
- 屏幕尺寸来自
BedrockPlayerUtils.getSafeInventorySize,并且每个槽位位置都是根据实际大小计算的。没有任何内容被放置在 Bedrock 客户端永远不会渲染的槽位中。 - Geyser 翻译效果不佳的材质(刷怪蛋、命令方块、结构方块、知识之书)会自动替换。
- Lore 限制为 10 行,超过此行数后 Bedrock 会不可预测地截断工具提示。
- 仅支持传统的
&颜色代码。 - 如果根本无法打开库存,完整报告将以聊天文本形式发送。 Bedrock 管理员永远不会没有诊断结果。
Bedrock 规则现在存在于一个共享辅助类 (BedrockUI) 中,配置 GUI 和诊断 GUI 都通过它路由,因此它们不会脱节。之前的 BedrockCompatibleGUI 类——574 行代码,未注册任何监听器且没有调用者——已被移除,以免留下维护陷阱。
? 紧急控制器
一个四级状态机(NORMAL → WARNING → CRITICAL → EMERGENCY),带有迟滞效应:连续 3 次不良读数升级,5 次良好读数降级,每种状态最少持续 10 秒。
EMERGENCY 级别现在可以达到了。 在预发布代码中,computeTargetState() 只能返回 NORMAL、WARNING 或 CRITICAL,这使得整个 responses.emergency 块——25% 的生物上限、16 块的 AI 距离、1 分钟的卸载阈值以及自定义命令列表——永久处于无效状态。现在它通过专用的 thresholds.tps.emergency / thresholds.ram.emergency 值进行升级,并且在持续处于 CRITICAL 状态下也会升级:一台在两分钟内一直卡在 12 TPS 的服务器在实践中属于紧急情况,即使它从未跨越原始阈值。
启动时会验证阈值顺序。如果错误配置层级导致某个层级无法到达,现在会记录警告而不是静默失败。
现在实际执行的响应
| 响应 | 状态 |
|---|---|
| 生物上限乘数 (75% / 50% / 25%) | 正常工作 |
| 区块预加载器暂停 | 正常工作 |
| 激进区块卸载 | 正常工作 |
| AI 距离减少 | 正常工作 |
| 红石时钟关闭 | 正常工作 |
| 阻止自然生成 | 现已实现 |
| 强制物品清理 | 现已实现 |
| 全服 AI 冻结 | 现已实现 |
| 紧急命令 | 现已可达 |
最后四项是可配置的,并由 /lagxpert emergency 报告,但没有代码对其采取行动。一个新的响应协调器消耗它们:
- 自然生成阻止 按
SpawnReason过滤。仅抑制环境压力——刷怪蛋、繁殖、插件生成和命令仍然有效,因为阻止这些会让服务器看起来像是坏了而不是繁忙。该列表由操作员配置,拥有lagxpert.bypass.mobs权限的玩家豁免。 - 强制清理 以非周期方式运行,带有 CAS 闩锁和冷却时间,以防止状态抖动导致清理扫描堆叠。
- AI 冻结 按区块分发(在 Folia 下正确),跳过玩家和 NPC 元数据实体,并在恢复时尊重你的
mobs.ymlAI 规则,而不是盲目重新启用所有内容。紧急期间的关闭会解除冻结,因此生物永远不会被永久冻结。
? 自适应阈值
此前,该模块能正确计算乘数,但从未实际使用它们——开启或关闭此功能仅会改变 /lagxpert status 中显示的数字。现在,它成为“当前限制是多少”的唯一权威来源,并已接入以下系统:
StorageListener(存储监听器)——漏斗、箱子、熔炉、 barrels(桶)、发射器、投掷器、潜影盒、TNT、活塞和侦测器的放置数量上限EntityListener(实体监听器)与SmartMobManager(智能生物管理器)——生物生成上限RedstoneCircuitTracker(红石电路追踪器)——脉冲容限与最大电路持续时间AutoChunkScanTask(自动区块扫描任务)——确保被标记为过载的区块与实际玩家受到的限制相匹配EntityCleanupTask(实体清理任务)——每区块的实体上限
两个独立输入源会被结合:连续服务器健康状况(来自 TPS 和内存数据)以及离散的紧急状态。两者中更严格的一方生效;它们绝不会相乘,否则会导致数值叠加至无法游玩的程度。限制值仅会向下缩放——你配置的值始终是上限——而可配置的 minimum-multiplier(最小乘数)下限可防止数值崩溃。通过 lagxpert.limits.* 权限授予的玩家专属限制将按原样保留,绝不进行缩放。
健康因子现在取 TPS 和内存组件中较差的一个,而非对二者求平均,因此健康的内存数据不再能掩盖糟糕的 TPS 读数。
? 优化配置文件
profiles.yml 之前没有任何 Java 代码支持:没有读取逻辑,也没有 profile 子命令。执行 /lagxpert profile balanced 时会返回“未知子命令”。
现已实现:
/lagxpert profile list 显示配置文件及当前激活的配置文件
/lagxpert profile <name> 应用指定配置文件
/lagxpert profile revert 恢复配置文件之前的状态
应用配置文件会将更改写入真实配置文件,保存后重新加载所有子系统。在首次写入之前,被替换的值会被快照记录,因此 revert 恢复的是你的配置,而非假定的默认值——且在第一个配置文件之上应用第二个配置文件时,仍会一直回退到初始状态。safety.auto-revert-minutes(安全自动回退分钟数)用于防止在发生事故时应用了过于激进的配置文件却忘记撤销。
对于无法映射到实际设置的配置文件键,控制台会报告错误,而不是静默丢弃。原本无法映射的 redstone.disable-clocks(红石禁用时钟)键已被存在的键所替换。
? 其他修复
/lagxpert reload现在会重载所有内容。 此前它仅刷新ConfigManager和AbyssManager;十几个子系统在构造时读取各自的 YAML 文件,并保留启动时的值直到完全重启。现在所有这些子系统都已覆盖,且具备每个子系统的故障隔离机制,确保一个部分的错误不会导致整个重载失败。entity-cleanup.advanced.max-entities-per-chunk(实体清理.高级.每区块最大实体数)现已生效。 此前该值虽被读取到字段中但从未使用。新增的处理流程会修剪超过上限的区块,同时尊重所有现有的保护规则(命名实体、驯服实体、拴绳实体、骑乘实体、持久化实体、插件创建的实体、拥有交易的村民)。MobAIOptimizer(生物 AI 优化器)重新遵守其自身配置。 此前它读取的是紧急控制器的 getter 方法,当控制器禁用时该方法会返回硬编码的 64——这导致完全忽略了你在mobs.yml中设置的距离参数。现在控制器只能收紧配置的半径,而不能扩大它。- 修正了
plugin.yml。 添加了folia-supported: true(若无此项,无论代码如何,Folia 都会拒绝加载该插件)。Geyser 和 Floodgate 被声明为软依赖,以便在玩家首次加入时即可检测 Bedrock 端,而非仅在重连后生效。lagxpert.admin.*权限节点现已声明——此前它们虽被检查但未声明,导致持有lagxpert.admin权限的管理员会在帮助中看到命令提示,随后却收到“无权限”的错误。 - 统一了权限检查。 帮助输出、Tab 补全和命令执行现在都调用同一个方法,终结了“ advertised(广告/提示)内容”与“实际可运行内容”之间的不匹配问题。
/lagxpert optimize如实报告。 区块卸载现在以同步方式运行并返回真实计数,而非异步分发并始终报告零。前后数值会根据是否真正得到改善来着色,而非始终显示为绿色。硬编码的缓存清除计数 1 已移除,TPS 被标记为滚动平均值,而非显示无意义的同 tick 差值。/lagxpert status完全支持翻译。 此前其输出为硬编码的英文;现在像插件其余部分一样使用messages.yml,此外还会显示哪些紧急响应正在生效以及哪个配置文件处于激活状态。- 性能历史记录现在遵守其配置。
snapshot-interval-seconds(快照间隔秒数)和max-history-days(最大历史天数)此前虽有文档说明但被忽略,转而使用硬编码常量。保存的历史记录现在也会在启动时加载,而非仅在经过第一个时间间隔后才出现。 - Bedrock 玩家缓存不再泄漏。 断开连接时条目会被驱逐。检测逻辑现在通过结构识别 Floodgate UUID,而非通过字符串前缀,并在 Geyser 或 Floodgate 在 LagXpert 之后完成加载时重新初始化。
- 移除了
LagShield。 它是一个已过时的透传组件,无任何调用者;lagshield.yml虽随 JAR 包提供,但从未被写入或读取。两者均已移除,连同遗留的消息键一起消失。
⚙️ 配置
emergency-controller.yml 中的新增项:
thresholds:
tps:
emergency: 10.0 # 新增层级
critical: 15.0
warning: 18.0
recovery: 19.0
stability:
# 即使原始指标从未跨越紧急阈值,在此持续时间内保持在 CRITICAL 状态则升级为 EMERGENCY。设为 0 则禁用。
sustained-critical-escalate-seconds: 120
actions:
forced-item-cleanup:
enabled: true
cooldown-seconds: 60 # 防止状态震荡导致清理操作叠加
block-natural-spawns:
spawn-reasons: [NATURAL, SPAWNER, CHUNK_GEN, ...]
ai-freeze:
enabled: true
config.yml 中的新增项:
adaptive-thresholds:
enabled: true
sensitivity:
mobs: 1.0
storage: 0.7 # 不要干扰玩家建筑
entities: 1.0
redstone: 1.0
# 限制值永远不会低于配置值的此比例
minimum-multiplier: 0.25
health:
healthy-tps: 20.0
degraded-tps: 10.0
healthy-memory-percent: 50.0
degraded-memory-percent: 95.0
? 命令与权限
| 命令 | 权限 | 用途 |
|---|---|---|
/lagxpert diagnose [chat|refresh] |
lagxpert.admin.diagnostics |
查找导致延迟的原因及位置 |
/lagxpert status |
lagxpert.admin.status |
实时仪表盘 |
/lagxpert optimize |
lagxpert.admin.optimize |
执行完整优化流程 |
/lagxpert emergency [status|force-normal] |
lagxpert.admin.emergency |
紧急状态控制 |
/lagxpert profile [list|<name>|revert] |
lagxpert.admin.profile |
应用优化配置档 |
/lagxpertgui diagnostics |
lagxpert.admin.diagnostics |
直接进入诊断 GUI |
lagxpert.admin 包含上述所有权限。更细粒度的节点可以单独授予——这适用于仅赋予 moderator(版主/管理员)读取诊断信息的权限,而不允许其修改配置文件或删除实体。传送到热点区域需要 lagxpert.admin.diagnostics.teleport 权限。
安装
全新安装
- 将
LagXpert-2.7.jar放入plugins/目录。 - 启动服务器以生成配置文件。
- 运行
/lagxpert diagnose查看服务器当前状态。
从 v2.6.x 升级
- 停止服务器。
- 用
LagXpert-2.7.jar替换旧版 jar 文件。 - 重启服务器以生成
emergency-controller.yml和profiles.yml。 - 现有配置文件保持兼容。新键使用安全默认值。
lagshield.yml已不再使用,可以删除。
升级后,运行 /lagxpert reload 即可在不重启的情况下应用配置更改——包括以前必须重启才能生效的 emergency-controller.yml。
兼容性
- Minecraft: 1.16.x – 26.2
- 平台: Spigot, Paper, Purpur, Folia
- Java: 11 或更高版本
- 基岩版: Geyser & Floodgate
关于验证的说明
由于 v2.6 中反复出现的问题是“看起来处于活动状态但实际上未生效”的配置,本次发布针对该特定故障模式进行了检查:
- 确认每个之前失效的方法在真实生产环境中都有调用点。
- 解析了所有 21 个随附的 YAML 文件,以确认它们能正常加载。
- 确认所有 21 个配置档键映射都能解析为真实的配置路径。
- 对紧急状态机进行了测试,确认通过 TPS 和内存两种路径,所有四种状态均可从合理的指标值到达。
- 确认代码中引用的所有 84 个消息键均存在于
messages.yml中。
此前被静默忽略的世界级覆盖设置
max-entities-per-chunk没有世界感知的解析逻辑,因此模板中的150被全局设置的200所取代。tnt-per-chunk,pistons-per-chunk,observers-per-chunk虽然在WorldConfigManager中有解析器,但从未被调用过:ConfigManager未向它们暴露带有World参数的委托方法,且放置监听器和区块扫描器均使用了全局值。
现在这四个参数在放置监听器、区块扫描器、实体清理流程和诊断引擎中均按世界进行解析。已确认所有 18 条世界感知路径都具有有效的全局回退值,且随附的下界(Nether)和末地(End)模板各自应用了 6 个活动覆盖设置。
下界模板还随附了注释为“默认情况下下界无 TNT”的 tnt-per-chunk: 0,但在整个插件中 0 表示无限制。一旦世界级的 TNT 解析开始正常工作,这将导致下界拥有无限 TNT,而表面上却声称相反的情况。已在模板生成的所有三个位置将其更正为 1,并记录了 0 的语义含义。
Folia 环境下清理 sweeps 的正确性
Folia 为每个区域提供独立的 ticking 线程,实体只能由其所属区块的线程访问。不允许任何线程扫描整个世界的实体。之前的清理任务正是这样做的,它们通过 world.getEntities() 和 world.getEntitiesByClass() 实现。
新的 RegionizedSweeper 工具枚举已加载的区块,并在所属线程上执行工作。以下功能已转换为此机制:
- 物品清理器(计划内、手动、按世界以及紧急强制触发的)
- 实体清理,包括按区块限制的实体上限清理流程
- 载具清理
- 用于性能快照和优化报告的实体计数
在 Spigot 和 Paper 上,相同的分发机制按批次跨 tick 处理区块,将一个阻塞性的 tick 分解为多个短小的 tick——这是一个真正的改进,因为这些清理操作正是在服务器已经感到吃力的时候运行的。每个周期的移除预算通过原子计数器在整个清理过程中共享。
由于清理操作现在异步完成,/clearitems 和 /lagxpert optimize 会在完成后报告总数。优化阶段被链接起来,以便每个阶段仅在上一阶段完成后才开始,这确保了计数归属于正确的阶段,并防止三个并发清理竞争相同的预算。
验证结果:除注释外,不再有对整个世界的实体访问;所有四个实体移除点都位于按区块作用域、由 sweeper 分派的方法内部。
已知限制
- 没有自动化测试套件。上述验证是针对构建产物进行的,而非作为回归测试。
/lagxpert optimize将 TPS 报告为滚动平均值,而不是前后差值,因为在该命令的执行期间,平均值无法发生变化。
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
使床在所有维度中爆炸的模组
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
评论 0
登录后参与评分
还没有评论,来抢沙发吧