日志与诊断

MineBackup 1.16.2 的 GUI、后台备份、还原、自动任务、平台集成和 KnotLink 共用一条结构化日志路径。排查问题时，要区分 Log 面板、会话日志、本地轮转文件 和 诊断导出；它们的保存范围和隐私处理不同。

三个日志层次

层次	用途	保存范围
Log 面板	运行中查看事件、按级别和分类过滤、打开详情。	只显示当前会话保留的记录；清除视图不会删除文件。
会话日志	供 UI、自动任务和诊断导出使用的内存记录。	保留最新 20,000 条记录，应用重启后不会作为历史数据库恢复。
本地文件	在应用外查看完整的结构化运行线索。	`minebackup.log` 当前文件 10 MiB，另有最多 4 个轮转文件。

命令面板的历史不是日志存储；复制命令或过滤结果是本地操作，会保留真实本机路径。不要把命令面板内容当成可脱敏的诊断包。

CLI 日志与 JSON 输出

Headless CLI 支持全局 --log-level off|info|debug；启用 --json 时，stdout 只输出一个 schema v1 envelope，日志和进度进入配置档 logs 或 stderr。自动化脚本应解析 JSON envelope 和退出码，不要解析人类可读的进度文本。服务器排障可先运行 minebackup-cli --json --no-network doctor，它不会启动 KnotLink；需要观察长期运行时则使用 serve status，再结合 profile 的日志文件定位问题。完整命令和退出码见 CLI 命令参考与 CLI 故障排查。

日志级别

配置项为 [General] LogFileLevel=off|info|debug，默认是 info：

级别	适合场景
`Off`	不写本地 `minebackup.log`；Log 面板仍可显示当前会话收集到的记录。适合平时不需要文件日志时使用。
`Info`	默认级别，记录备份、还原、任务、迁移、云端和网络操作的主要结果。
`Debug`	在 Info 基础上补充稳定事件 ID、线程、上下文和源码位置，适合复现问题后短时间采集。

设置页修改级别后会立即重建日志后端，不需要重启。Debug 会产生更多内容，问题复现完成后建议恢复 Info。旧版 AutoLog 只在新键不存在时兼容映射到 Off/Info；保存后以 LogFileLevel 为准。

日志位置

日志目录跟随配置档的位置：

平台	日志目录
Windows	`%LOCALAPPDATA%\MineBackup\logs`
Linux	`${XDG_STATE_HOME:-~/.local/state}/MineBackup/logs`
macOS	`~/Library/Logs/MineBackup`
显式或便携配置档	`<profile>/logs`

如果配置档目录不可写，Log 面板和特殊模式控制台仍应可用，状态区会报告文件后端错误。不要只凭“文件夹里没有日志”判断 MineBackup 没有运行；先查看 Log 面板中的后端状态和启动错误。

诊断导出与脱敏

在 Log 页签选择 Export Diagnostics。确认提示后，MineBackup 会在日志目录生成类似下面的文件：

minebackup-diagnostics-YYYYMMDD-HHMMSS.txt

导出包只包含版本、平台、配置档模式、会话/后端状态和当前保留的日志记录，不会读取或打包完整配置、历史、rclone 凭据文件或其他用户文件。已知的配置档根目录、用户目录、世界/备份/快照目录、压缩工具和 rclone 路径、任务工作目录、rclone 远端路径，以及 URL 用户信息和查询参数会被替换。

外部进程 stdout/stderr 中的任意秘密无法可靠识别，因此分享前必须用文本编辑器打开诊断导出人工检查。诊断导出经过脱敏；本地轮转日志仍可能保留真实路径，只应发给可信的排障人员。

旧日志文件不再是当前机制

1.16.2 不再写入以下旧文件：

auto_log.txt
special_mode_log.txt
console_log.txt

安装目录或旧配置档中已有的这些文件不会被自动迁移，也不会被程序删除。排查当前版本时，应优先查看 minebackup.log、Log 面板和诊断导出，而不是等待旧文件更新。

三个日志层次​

CLI 日志与 JSON 输出​

日志级别​

日志位置​

诊断导出与脱敏​

旧日志文件不再是当前机制​

推荐排查顺序​