CleanMCA · 故障排查

找不到 Python 或入口文件

先确认当前目录和文件名，再确认实际解释器：

pwd
ls -la
python3 --version

Windows 可以执行 Get-Location、Get-ChildItem 和 python --version。不要只输入 python CleanMCA.py 就假定调用的是服务器或面板使用的 Python；必要时使用 Python 绝对路径。

白名单文件不存在

脚本会在解析后检查 --mca 指向的是一个文件。常见原因包括：

• 当前工作目录不是保存白名单的目录；
• 相对路径拼写错误；
• Windows 路径中有空格但没有加引号；
• 使用了目录路径而不是文件路径；
• 计划任务使用了与交互式终端不同的用户。

先改用白名单绝对路径，并在执行前用 ls -l 或 Get-Item 验证。

Region、POI 或 Entities 目录不存在

CleanMCA 要求 --region 所在目录的上一级同时存在 poi 和 entities。检查目录树：

目标上级目录/
├── region/
├── poi/
└── entities/

如果你传入了世界根目录，工具会寻找错误的 world/../poi；如果你传入了 poi，它会寻找 poi/../poi。修正为实际的 region 目录，而不是手动创建空目录掩盖路径错误。不同服务端、版本和维度的目录布局可能不同，应以目标存档真实内容为准。

权限或删除失败

读取权限不等于删除权限。确认运行用户对三个目录有进入、读取和删除文件的权限，并检查是否有服务器进程、备份程序或文件同步服务占用文件。

Python 版本会输出具体删除失败信息；先停止所有可能写入世界的进程，再用测试副本复现。不要为了绕过权限问题直接用不熟悉的 root/管理员账户对生产目录运行。

没有删除文件

可能原因：

1. 目标目录的每个文件名都在白名单中；
2. 你把清理后的测试目录当成了原目录；
3. 白名单中加入了错误的完整路径、通配符或大小写不一致的名称；
4. 实际运行的 --region 不是你检查的维度；
5. 目标目录只有子目录，而 Python 版本不会递归处理。

先抽查目标目录中一个确实存在的文件名，确认它与白名单逐字符一致，再核对命令行中展开后的绝对路径。

删除数量或范围超出预期

立即停止后续操作，并从备份恢复，不要用新的白名单在已修改目录上“补救”。重点检查：

• 是否把“想删除的文件”误写进白名单；
• 是否遗漏了公共区域、交通线或管理区域；
• 是否把另一个维度的列表用于当前目录；
• 是否存在不以 .mca 结尾但需要保留的普通文件；
• 是否把 Dominion 自动生成的领地范围当成完整存档保留策略。

CleanMCA 没有 undo。恢复依赖清理前备份或快照。

清理后服务器异常

如果服务器启动失败、区块加载报错、村民/POI 行为异常或重要实体消失：

1. 停止服务器，避免异常状态继续写入世界；
2. 保存启动日志、CleanMCA 输出、执行命令和白名单；
3. 将问题描述与清理前备份进行对照；
4. 优先完整恢复清理前世界，再在副本中缩小白名单范围重新验证；
5. 确认是脚本范围、白名单来源还是服务端本身问题后，再安排下一次生产操作。

Bash 输入 n 仍然继续

这是当前 Bash 脚本的已知实现问题：确认读取后没有根据字符退出。不要继续测试“是否真的删了”，直接停止流程并切换到 Python 版本。若已经发生删除，只能从备份或快照恢复。

提交问题时带上什么

向 CleanMCA Issues 或支持渠道反馈时，避免上传世界文件和敏感路径；至少提供：

• CleanMCA commit 或下载时间；
• 操作系统、Python/Bash 版本；
• 使用的入口和完整命令格式（隐藏敏感路径）；
• 目标目录树的匿名化示例；
• 白名单中几行无敏感信息的样例；
• 终端错误、删除失败信息和是否已从备份恢复。