[markdown]

ConfigDoctor —— 配置医生 · 配置检查 & 备份恢复 & 报错解读

版本 1.2.1 | 作者 LittleWo

简介

服主们大概都遇到过这种情况：

• 改了半天配置，插件的行为完全没变 —— 因为某个键拼错了，插件根本不读它；

• 升级插件后配置里留下一堆旧版残留键，没人知道它们还有没有用；

• 控制台刷了一屏报错，堆栈看得人头晕，不知道到底哪里出了问题。

ConfigDoctor 是一个只读的配置体检工具：它读取每个插件 jar 内打包的默认配置，与服务器上实际生效的配置逐键对比，找出配置文件报错、失效、残留的坑，它还能对插件配置随时进行备份和恢复，甚至能与备份配置进行对比。

它只读取文件，从不修改任何插件的配置。

功能特性

🔍 配置体检

• 逐键对比「jar 内默认配置」与「服务器实际配置」；

• 检测：类型不匹配（如该填数字的地方填了字符串，Bukkit 会静默使用默认值）、拼写错误/旧版残留的孤儿键、无法解析的配置文件；

• 支持全量扫描 plugins 目录，或指定单个插件。

• 保存报告文件，方便查看。也支持在游戏内输出报告。

💾 备份 / 恢复 / 对比

• 备份：把任意插件（或全服）的 .yml/.yaml 配置（含子目录）打包成 zip；

• 恢复：恢复配置文件成任意一个之前的备份。恢复前自动把当前配置快照为 pre-restore 备份，恢复错了还能反悔；

• 对比：逐键对比任意备份与当前配置，标出修改/新增/删除；

• 全部支持命令Tab补全插件名和备份名，免去找文件名的麻烦。

📜 日志报错解读

• 分析 logs/latest.log，统计报错事件并按出现频率排序；

• 对常见异常（ClassCastException、NoSuchMethod、NPE、异步违规、数据库锁定等）给出人话解释；

其他

• 忽略 通配符忽略列表，把已知无害的键提示静音；

• 扫描/报错/对比报告均带时间戳落盘，永不覆盖，方便回溯历史。

命令

主命令 /configdoctor，别名 /cfgdoc。需要权限 configdoctor.use（默认仅 OP）。

| 命令 | 说明 |

|---|---|

| /cfgdoc scan [插件名] | 体检配置：全量扫描或指定插件 |

| /cfgdoc errors | 分析 latest.log 里的报错并生成解释报告 |

| /cfgdoc backup <插件名\|all> | 备份插件配置（只打包 .yml/.yaml，含子目录） |

| /cfgdoc restore <插件名> [备份] | 恢复备份；列出可用备份；需 30 秒内重复执行确认 |

| /cfgdoc diff <插件名> [备份] | 对比备份与当前配置的差异 |

| /cfgdoc report | 重看最近一次扫描结果 |

| /cfgdoc ignore <通配> | 忽略某类键，例如 dynmap.* 或 *.markers.* |

| /cfgdoc reload | 重载自身配置与忽略列表 |

所有子命令均支持 Tab 补全。

配置

plugins/ConfigDoctor/config.yml：

# 扫描时跳过的插件名列表（区分大小写，与对方 plugin.yml 的 name 一致）

exclude-plugins: []

# 扫描完成后是否生成报告文件

report-file: true

# 是否报告「默认有而用户未设置」的键

# 大多数插件没被编辑过的部分会全是提示，默认关闭

show-missing: false

忽略列表保存在 plugins/ConfigDoctor/ignores.txt，由 /cfgdoc ignore 自动写入，也可手动编辑后 /cfgdoc reload。

报告和备份路径

所有报告和备份都保存在 plugins/ConfigDoctor/ 下，文件名自带时间戳，不会覆盖历史报告：

| 项目 | 路径 |

|---|---|

| 配置体检 | report-<时间戳>.txt |

| 日志报错解读 | errors-<时间戳>.txt |

| 配置差异对比 | diff-<时间戳>.txt |

| 配置备份 | backups/<插件名>/<时间戳>.zip |

| 恢复前自动快照 | backups/<插件名>/pre-restore-<时间戳>.zip |

安装方法

1. 下载 ConfigDoctor-x.x.x.jar；

2. 放入服务器的 plugins/ 目录；

3. 重启服务器（或使用 PlugManX 等热载）；

4. 完成。首次启动会自动生成默认配置，无需任何前置。

兼容性

• 核心：Paper / Purpur / Spigot（以及兼容 Bukkit API 的衍生核心）；

• 版本：理论上兼容1.18.2~26.3；

• Folia：理论上支持；

• Java：服务端需运行在 Java 17 或更高版本；

• 权限/前置：无任何硬依赖或软依赖，单 jar 即用。

反馈

有问题或建议可反馈到作者邮箱 block409@foxmail.com

[/markdown]