跳到內容

備份與狀態檔管理

安全查閱模式 — 完全不會修改您的世界存檔

此模式下的指令僅讀取資料並輸出結果,不會對 Minecraft 世界資料夾進行任何寫入或更動。

NBTExplorerCLI 會將所有的掃描快取、翻譯進度、備份檔案與寫入復原日誌統一存放在世界資料夾外部。這確保無論您執行多少次掃描或翻譯,都不會在您的 Minecraft 存檔資料夾內留下多餘的暫存檔。

1. 認識外部狀態目錄(--state-root)

Section titled “1. 認識外部狀態目錄(--state-root)”

預設情況下,工具會依世界資料夾的識別碼,將狀態檔存放在 Windows 本機應用程式資料目錄下:

%LOCALAPPDATA%\nbtcli\worlds\<world-id>\

您也可以透過 --state-root 'D:\NbtState\MyWorld' 指定自訂的外部資料夾。請注意:同一組工作流程中的 plan、apply、status、recover、backup、restore、translate 與 agent 指令,都必須使用同一個 --state-root。

獨立的 scan、extract 與一般 validate 預設使用 %LOCALAPPDATA%\nbtcli\scan\<world-id>,也可透過 --cache-root 指定外部目錄。翻譯與寫入流程使用 state root 下的獨立快取。

狀態目錄內的資料夾與檔案說明

Section titled “狀態目錄內的資料夾與檔案說明”
子資料夾/檔案 用途說明 是否可清理或重建?
cache/ 儲存翻譯與寫入流程使用的快取。 可重建:將它與獨立掃描命令的快取分開管理。
sessions/ 儲存翻譯工作階段(translate start、譯文回覆、備註、術語表與封存紀錄)。 翻譯期間請保留:內含您的翻譯進度與歷史版本紀錄。
agent/ 儲存外部翻譯助手的問卷偏好設定(agent setup / submit)。 使用者設定:保留此目錄即可維持該世界的預設翻譯語言與每頁筆數設定。
objects/ 以 SHA-256 雜湊命名的內容定址儲存庫,保存寫前原始檔案映像與備份實體內容。 還原與回滾必備:restore 與 recover 必須依賴此資料夾才能還原世界檔案。
journals/ 儲存 apply、status 與 recover 的寫入日誌與完成回執。 復原必備:當寫入進行中或出現退出碼 7(待復原)時,切勿刪除此資料夾。
backup_<後綴>_*.json 執行 backup --suffix <名稱> 時產生的具名備份清單檔。 需與 objects/ 一起保留:記錄該次備份的所有檔案路徑與 SHA-256 雜湊索引。

狀態目錄與世界路徑的綁定關係

Section titled “狀態目錄與世界路徑的綁定關係”

<world-id> 是工具使用的世界識別碼,目錄名稱省略連字號。請為每份世界副本指定獨立的 state root。重建或複製世界資料夾後,請掃描所選資料夾並建立新計畫。接續現有日誌時,請使用原世界路徑及 state root。

2. 建立並驗證世界備份(backup)

Section titled “2. 建立並驗證世界備份(backup)”

在進行重要修改前,可執行 backup 為整個世界(或搭配 --path <相對路徑> 為單一檔案)建立經 SHA-256 驗證的完整備份:

終端機視窗
New-Item -ItemType Directory -Path 'D:\Backups' -Force | Out-Null
.\nbtcli.exe backup 'D:\WorldCopy' `
--suffix before-translation `
--output 'D:\Backups\before-translation-manifest.json'

回傳 JSON 範例:

{
"schemaFamily": "nbtcli.cli",
"schemaVersion": 1,
"success": true,
"command": "backup",
"outcome": "Success",
"data": {
"manifestHash": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
"stateRoot": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c...",
"backupPath": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c...\\backup_before-translation_20261118T070000Z_a1b2c3.json",
"namedManifestPublished": true
},
"error": null
}

[!IMPORTANT] 備份清單檔(before-translation-manifest.json)記錄的是檔案清單與雜湊索引,實際的檔案內容儲存在 stateRoot 下的 objects/ 目錄中。請同時保留 manifestHash 與該 stateRoot 目錄,以便日後隨時還原。

3. 從備份還原世界或修復損壞檔案(restore)

Section titled “3. 從備份還原世界或修復損壞檔案(restore)”
寫入存檔模式 — 執行前請務必關閉 Minecraft 並使用世界副本

此操作會實際修改指定的世界資料夾。請先建立備份或在世界副本上操作,確認遊戲與其他編輯器皆已關閉後,再加上 --world-offline 執行。

restore 會核對備份清單(manifestHash)與 objects/ 內的檔案雜湊,將世界(或指定的單一 --path)安全還原。即使世界內目前的目標檔案已經損壞或被誤刪,restore 依然能正常修復。

不加 --apply 執行 restore,即可預覽預計還原的檔案清單:

終端機視窗
.\nbtcli.exe restore 'D:\WorldCopy' `
--manifest-hash 4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a `
--output 'D:\Backups\restore-plan.json'

步驟 2:離線套用已審閱的還原計畫

Section titled “步驟 2:離線套用已審閱的還原計畫”

關閉 Minecraft,使用與預覽相同的世界和 state root 套用保存的計畫。套用時會核對計畫記錄的前像,拒絕覆寫預覽後出現的改動。

終端機視窗
.\nbtcli.exe apply 'D:\WorldCopy' `
--plan 'D:\Backups\restore-plan.json' `
--world-offline

若預覽時自訂 --state-root,套用時也要帶入相同路徑。只還原單一檔案時,先在預覽命令加上 --path level.dat,審閱輸出的計畫後再套用該檔。