main

ASPbackup 使用說明書

Minecraft Spigot 伺服器進階備份插件 | Java 21 | Spigot 1.20.6+

1. 安裝與需求

系統需求

項目	需求
Java	21 或更高版本 (Temurin/OpenJDK)
伺服器	Spigot / Paper / Leaf 1.20.6+
儲存空間	備份目標至少需要與來源目錄相同的可用空間

安裝步驟

從 Releases 下載 ASPbackup-1.0.0.jar
將 jar 檔案放入伺服器的 plugins/ 目錄
啟動（或重啟）伺服器
插件會自動生成 plugins/ASPbackup/config.yml 配置檔案
編輯配置檔案以符合您的需求
執行 /aspbackup reload 重新載入配置

目錄結構

plugins/ASPbackup/
├── config.yml          # 主配置檔案
├── temp/               # 暫存目錄（壓縮中的備份檔）
├── checkpoints/        # 中斷備份的檢查點檔案
├── logs/               # 備份日誌檔案
│   ├── backup-2026-08-08.log
│   └── backup-2026-08-09.log
└── backups/            # 本地備份目標（預設，若使用 REMOTE 目標則不會有）
    ├── ASPbackup-20260808-143022.tar.gz
    └── ASPbackup-20260809-080015.tar.gz

2. 快速開始

基本操作

# 手動觸發備份
/aspbackup start

# 查看備份狀態
/aspbackup status

# 查看備份歷史
/aspbackup list

# 重新載入配置
/aspbackup reload

# 查看插件資訊
/aspbackup info

# 查看所有命令
/aspbackup help

自動備份

插件預設啟用啟動備份和關閉備份，無需任何額外設定：

伺服器啟動時：延遲數秒後在背景執行備份，不阻塞伺服器
伺服器關閉時：收到 /stop 命令後攔截關閉，先執行備份，完成後再關閉

定時備份

在 config.yml 中啟用定時備份：

schedule:
  enabled: true
  interval-minutes: 360    # 每 6 小時備份一次
  backup-type: "full"
  target-id: "remote-cluster"
  quiet-hours:
    - "06:00-22:00"        # 此時間段內不執行備份

3. 配置檔案詳解

3.1 備份設定 (`backup`)

backup:
  # 伺服器啟動時是否自動備份
  auto-on-start: true

  # 伺服器關閉時是否自動備份
  auto-on-shutdown: true

  # 啟動備份的延遲秒數（讓伺服器穩定後再備份）
  start-delay-seconds: 10

  # 備份主檔案名稱（用於暫存檔命名）
  backup-name: "ASPbackup"

  # 阻塞式備份超時秒數（防止遠端傳輸失敗時阻塞伺服器）
  blocking-timeout-seconds: 120

  # 暫存目錄
  temp-directory: "plugins/ASPbackup/temp"

  # 單次備份最大大小（MB），0 = 無限制
  max-backup-size-mb: 0

  # 備份完成後是否驗證完整性
  verify-after-backup: true

  # 壓縮設定
  compression:
    format: "targz"       # "zip" 或 "targz"
    level: 9              # 1 (最快) 到 9 (最小)

3.2 備份來源 (`sources`)

每個來源可設定 category 分類標籤，備份完成後會按分類顯示統計資訊。

backup:
  sources:
    # 玩家背包資料
    - path: "world/playerdata"
      name: "玩家背包数据"
      category: "player-data"
      exclude:
        - "**/*.dat"
        - "**/*.dat_old"
      max-depth: 10

    # 玩家統計資料
    - path: "world/stats"
      name: "玩家统计数据"
      category: "player-data"
      exclude:
        - "**/*.lock"
      max-depth: 10

    # 玩家進度資料
    - path: "world/advancements"
      name: "玩家进度数据"
      category: "player-data"
      exclude:
        - "**/*.lock"
      max-depth: 10

    # 所有插件檔案
    - path: "plugins"
      name: "所有插件文件"
      category: "plugins"
      exclude:
        - "**/ASPbackup/**"    # 排除備份插件自身
        - "**/dynmap/web/**"
        - "**/*.log"
      max-depth: 50

    # 插件配置檔案（僅備份設定檔）
    - path: "plugins"
      name: "插件配置文件"
      category: "plugin-configs"
      include:
        - "**/config.yml"
        - "**/config.yaml"
        - "**/settings.yml"
        - "**/*.properties"
        - "**/*.json"
        - "**/*.toml"
        - "**/*.conf"
      exclude:
        - "**/ASPbackup/**"
        - "**/dynmap/web/**"
        - "**/*.db"
      max-depth: 30

來源欄位說明：

欄位	類型	說明
`path`	字串	相對於伺服器根目錄的路徑
`name`	字串	顯示名稱
`category`	字串	分類標籤，用於備份統計和 tar.gz 內部分類
`include`	列表	僅包含符合這些 glob 模式的檔案（空 = 全部）
`exclude`	列表	排除符合這些 glob 模式的檔案
`max-depth`	整數	最大目錄深度

3.3 檔案過濾規則 (`file-filter`)

backup:
  file-filter:
    # 包含的檔案（glob 模式）
    include:
      - "**/*"

    # 排除的檔案（全域，對所有來源生效）
    exclude:
      - "**/*.tmp"
      - "**/*.lock"
      - "**/*.pid"
      - "**/ASPbackup/**"   # 避免備份的備份

    # 最小檔案大小（位元組），0 = 不限制
    min-size-bytes: 0

    # 最大檔案大小（位元組），0 = 不限制
    max-size-bytes: 0

Glob 模式說明：

模式	說明	範例
`*`	匹配任意字元（不含 `/`）	`*.log` 匹配所有 .log 檔案
`**`	匹配任意目錄層級	`/ASPbackup/` 匹配所有 ASPbackup 目錄下的檔案
`?`	匹配單個字元	`region/r.?.?.mca`

3.4 備份目標 (`targets`)

backup:
  targets:
    # 遠端分散式目標（傳輸到接收端）
    - id: "remote-cluster"
      type: "REMOTE"
      retention-count: 3
      min-free-space-mb: 10240

    # 本地目標
    # - id: "local"
    #   type: "LOCAL"
    #   path: "backups/"
    #   retention-count: 10
    #   min-free-space-mb: 1024

    # NAS 目標（掛載的網路磁碟）
    # - id: "nas"
    #   type: "NAS"
    #   path: "/mnt/nas/minecraft-backups/"
    #   retention-count: 5
    #   min-free-space-mb: 5120

目標類型：

類型	說明
`LOCAL`	本地目錄，path 為相對於伺服器根目錄的路徑
`NAS`	網路磁碟，path 為絕對路徑（如 `/mnt/nas/...`）
`REMOTE`	遠端接收端，透過 TCP 傳輸

3.5 分散式傳輸設定 (`transfer`)

transfer:
  # 分塊大小（KB）— 用於進度顯示
  chunk-size-kb: 1024

  # 並行傳輸執行緒數
  parallel-threads: 4

  # 連線超時（毫秒）
  connect-timeout-ms: 10000

  # 讀取超時（毫秒）
  read-timeout-ms: 30000

  # 失敗重試次數
  retry-count: 3

  # 重試間隔（毫秒）
  retry-delay-ms: 5000

  # 負載均衡策略："round_robin" 或 "least_loaded"
  load-balance-strategy: "least_loaded"

  # 傳輸節點列表
  nodes:
    - id: "node-1"
      host: "127.0.0.1"
      port: 9876
      auth-token: "remote-cluster"
      enabled: true
      weight: 1

3.6 檢查點設定 (`checkpoint`)

checkpoint:
  # 啟用中斷續傳
  enabled: true

  # 檢查點儲存目錄
  directory: "plugins/ASPbackup/checkpoints"

  # 自動清理超過 N 天的檢查點
  max-age-days: 7

3.7 日誌設定 (`logging`)

logging:
  # 日誌級別："DEBUG"、"INFO"、"WARN"、"ERROR"
  level: "INFO"

  # 日誌目錄
  directory: "plugins/ASPbackup/logs"

  # 保留天數
  retention-days: 30

  # 詳細傳輸日誌
  verbose-transfer: false

  # 同時輸出到控制台
  console-output: true

3.8 磁碟空間監控 (`disk-space`)

disk-space:
  # 可用空間低於此百分比時警告
  warn-threshold-percent: 15

  # 檢查間隔（秒）
  check-interval-seconds: 300

4. 命令參考

命令總覽

命令	權限	說明
`/aspbackup start`	`aspbackup.start`	手動開始備份
`/aspbackup stop <id>`	`aspbackup.stop`	停止備份（儲存檢查點）
`/aspbackup status [id]`	`aspbackup.status`	查看備份狀態
`/aspbackup resume <id>`	`aspbackup.resume`	從檢查點續傳
`/aspbackup list`	`aspbackup.list`	列出備份歷史
`/aspbackup nodes`	`aspbackup.nodes`	管理傳輸節點
`/aspbackup verify <id>`	`aspbackup.verify`	驗證備份完整性
`/aspbackup reload`	`aspbackup.reload`	重新載入配置
`/aspbackup about`	`aspbackup.command`	顯示插件資訊
`/aspbackup info`	`aspbackup.command`	顯示運行狀態
`/aspbackup help`	`aspbackup.command`	顯示命令幫助

詳細命令說明

`/aspbackup start`

/aspbackup start [--full|--incremental] [--target <目標ID>]

啟動一個新的備份任務。

參數：

--full：完整備份（預設）
--incremental：增量備份（僅備份變更的檔案）
--target <id>：指定目標（預設使用第一個配置的目標）

範例：

/aspbackup start
/aspbackup start --target remote-cluster
/aspbackup start --full --target local

輸出：

[ASPbackup] 备份任务已启动：a1b2c3d4

`/aspbackup stop`

/aspbackup stop <任務ID>

安全停止正在執行的備份任務，並儲存檢查點以便後續續傳。

範例：

/aspbackup stop a1b2c3d4

`/aspbackup status`

/aspbackup status [任務ID]

查看備份任務的狀態。

不帶參數：顯示所有任務摘要 帶任務ID：顯示該任務的詳細進度

範例輸出（摘要）：

===== 备份任务 =====
[COMPLETED] a1b2c3d4 - 100.0% - FULL
[PAUSED]    e5f6g7h8 - 47.3% - FULL
[RUNNING]   i9j0k1l2 - 12.8% - FULL

`/aspbackup resume`

/aspbackup resume <任務ID>

從中斷的檢查點恢復備份任務。

注意：僅能恢復狀態為 PAUSED 的任務。

`/aspbackup list`

/aspbackup list [--active|--completed|--failed|--all] [--page <頁碼>]

列出備份任務歷史。

範例：

/aspbackup list --completed
/aspbackup list --all --page 2

`/aspbackup nodes`

/aspbackup nodes list
/aspbackup nodes status [節點ID]

管理分散式傳輸節點。

`/aspbackup verify`

/aspbackup verify <任務ID>

驗證已完成備份的 SHA-256 完整性。

`/aspbackup reload`

/aspbackup reload

重新載入 config.yml，無需重啟伺服器。

注意：正在執行的備份任務不受影響，新配置將在下一次備份時生效。

`/aspbackup about`

/aspbackup about

顯示插件名稱、版本、作者和網站資訊。

`/aspbackup info`

/aspbackup info

顯示當前運行狀態，包括：

啟動/關閉備份是否啟用
定時備份狀態
備份來源數量
備份目標數量
傳輸節點數量
活動備份任務數

5. 備份流程說明

5.1 完整備份流程

1. 觸發備份（手動/自動/定時）
       │
2. 儲存世界資料（主執行緒）
   ├── /save-off   → 關閉自動存檔
   ├── /save-all   → 強制儲存所有世界
   └── /save-on    → 重新開啟自動存檔
       │
3. 檢查磁碟空間
   ├── 不足 → 終止備份，記錄錯誤
   └── 充足 → 繼續
       │
4. 收集檔案（依 category 分類，套用過濾規則）
       │
5. 顯示分類統計
   ──────────────────────────────────
    备份内容汇总：
      player-data：45 个文件，12.3 MB
      plugins：120 个文件，48.7 MB
      plugin-configs：15 个文件，0.3 MB
    总计：180 个文件，61.3 MB
   ──────────────────────────────────
       │
6. 壓縮檔案（Tar.gz，SHA-256 校驗）
       │
7. 傳輸到目標
   ├── LOCAL  → 複製到本地目錄
   ├── NAS    → 複製到網路磁碟
   └── REMOTE → TCP 整檔傳輸到接收端（含 ACK 確認）
       │
8. 驗證完整性
       │
9. 清理舊備份（保留策略）
       │
10. 完成 → 記錄日誌

5.2 備份分類系統

備份檔案在 tar.gz 內按 category 分類組織，結構如下：

player-data/
  world/playerdata/xxx.dat
  world/stats/xxx.json
  world/advancements/xxx.json
plugins/
  plugins/LuckPerms/...
  plugins/Essentials/...
plugin-configs/
  plugins/Essentials/config.yml
  plugins/LuckPerms/config.yml

player-data：玩家背包、統計、進度資料
plugins：所有插件檔案（排除 ASPbackup 自身、大型網頁資源、日誌）
plugin-configs：僅插件設定檔（.yml, .json, .properties, .toml, .conf）

5.3 啟動/關閉備份機制

啟動備份：save-off/save-all/save-on 在主執行緒，備份在背景執行緒非同步執行，不阻塞主執行緒
關閉備份：攔截 /stop 命令，先執行備份（阻塞），備份完成後再關閉伺服器
手動備份：非阻塞，玩家可繼續遊戲

5.4 中斷與續傳流程

備份進行中
       │
管理員執行 /aspbackup stop
       │
       ├── 設定中斷標記
       ├── 在安全的邊界點暫停
       ├── 儲存檢查點 → plugins/ASPbackup/checkpoints/<id>.properties
       └── 任務狀態變為 PAUSED

管理員稍後執行 /aspbackup resume
       │
       ├── 載入檢查點
       ├── 從中斷位置繼續收集檔案
       └── 完成後刪除檢查點

5.5 備份任務狀態

狀態	說明
`INITIALIZING`	任務已建立，正在初始化
`COLLECTING`	正在收集要備份的檔案
`COMPRESSING`	正在壓縮檔案
`TRANSFERRING`	正在傳輸到目標
`VERIFYING`	正在驗證完整性
`PAUSED`	已暫停，檢查點已儲存
`COMPLETED`	備份成功完成
`CANCELLED`	備份已被取消
`FAILED`	備份失敗

6. 分散式傳輸設定

6.1 架構說明

┌─────────────────┐
│  Minecraft 伺服器 │  (ASPbackup 插件)
│  192.168.1.100   │
└────────┬────────┘
         │ TCP 9876
         ├──────────────┬──────────────┐
         ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  接收端 #1   │ │  接收端 #2   │ │  接收端 #3   │
│ 10.0.0.101  │ │ 10.0.0.102  │ │ 10.0.0.103  │
└─────────────┘ └─────────────┘ └─────────────┘

6.2 負載均衡策略

輪詢（Round Robin）：

依序將備份分配給每個線上節點

最少負載（Least Loaded）：

將備份分配給目前傳輸量最少的節點
考慮節點權重（weight）
節點失敗時增加虛擬負載作為懲罰

6.3 傳輸協議

目前使用整檔傳輸模式，一次傳送完整備份檔案。

握手階段：
  插件 → 接收端：4位元組長度 + 協定版本(2B) + token長度(1B) + token + node_id長度(1B) + node_id + capabilities(1B)
  接收端 → 插件：4位元組長度 + ACK(4B, 0=成功)

檔案傳輸：
  插件 → 接收端：4位元組(任務ID長度) + 任務ID(UTF-8) + 8位元組(檔案大小) + 檔案資料(含進度顯示)
  接收端 → 插件：4位元組長度 + 2位元組(任務ID長度) + 任務ID + 1位元組(成功標誌) + 2位元組(訊息長度) + 訊息

接收端輸出：
  received-backups/{任務ID}/backup.tar.gz

7. 接收端應用程式

7.1 快速啟動

Windows：

java -jar ASPbackup-receiver-1.0.0.jar --port 9876 --dir D:\receiver\received-backups

Linux/macOS：

java -jar ASPbackup-receiver-1.0.0.jar \
  --port 9876 \
  --dir /mnt/backups/minecraft \
  --token your-secure-token

7.2 接收端目錄結構

receiver/
├── ASPbackup-receiver-1.0.0.jar     # 接收端主程式
└── received-backups/                # 接收的備份輸出目錄
    └── <任務ID>/
        └── backup.tar.gz

7.3 參數說明

參數	預設值	說明
`--port`	`9876`	監聽埠號
`--dir`	`received-backups`	備份輸出目錄
`--token`	`change-me`	認證令牌（必須與插件 `auth-token` 一致）
`--help`	-	顯示幫助

7.4 安全建議

使用防火牆：限制只有 Minecraft 伺服器 IP 可以連接收端埠
使用強密碼令牌：避免使用預設的 change-me
使用 VPN：如果接收端在遠端網路，建議透過 VPN 連接
定期更換令牌：定期更新 auth-token 並重啟兩端服務

8. 常見問題

Q: 備份失敗，提示 "Insufficient disk space"

原因：目標磁碟空間不足。

解決方案：

清理目標目錄的舊備份
調整 retention-count 減少保留數量
降低 min-free-space-mb 閾值
擴充目標磁碟容量

Q: 備份過程中伺服器 lag

原因：壓縮大型檔案消耗 CPU 和 I/O。

解決方案：

降低 compression.level（如從 9 降到 3）
排除不必要的目錄（如 dynmap/web/）
使用 quiet-hours 在玩家較少的時段執行定時備份
增加 start-delay-seconds 避免啟動時伺服器尚未穩定

Q: 備份越來越大？

原因：ASPbackup 上一次備份的檔案被包含在本次備份中。

解決方案：已在配置中預設排除 **/ASPbackup/**，確保備份插件自身的日誌、檢查點、暫存檔不會被重複備份。如果仍有問題，檢查 file-filter.exclude 和各來源的 exclude 是否正確設定。

Q: 如何恢復備份？

備份檔案為標準的 .tar.gz 格式，已按分類組織：

# 解壓縮
tar -xzf backup.tar.gz

# 解壓後結構：
# player-data/world/playerdata/...
# plugins/plugins/...
# plugin-configs/plugins/.../config.yml

將對應目錄內容複製回伺服器即可。

Q: 中斷的備份如何續傳？

# 1. 查看暫停的任務
/aspbackup status

# 2. 續傳
/aspbackup resume <任務ID>

# 3. 如果檢查點損壞，可以刪除檢查點檔案重新開始
rm plugins/ASPbackup/checkpoints/<任務ID>.properties

Q: 如何變更備份目標？

編輯 config.yml 中的 backup.targets 後：

/aspbackup reload
/aspbackup start --target <新目標ID>

Q: 接收端連線失敗？

原因：接收端未啟動、埠號錯誤、防火牆阻擋、或 JAR 版本過舊。

解決方案：

確認接收端已啟動並監聽正確埠號
檢查 config.yml 中 nodes.host 和 nodes.port 是否正確
確認插件和接收端都是最新版本
檢查防火牆是否允許該埠號

9. 權限節點

權限節點	說明	預設
`aspbackup.command`	使用 `/aspbackup` 命令	OP
`aspbackup.start`	手動開始備份	OP
`aspbackup.stop`	停止備份任務	OP
`aspbackup.status`	查看備份狀態	OP
`aspbackup.resume`	續傳中斷的備份	OP
`aspbackup.list`	列出備份歷史	OP
`aspbackup.nodes`	管理傳輸節點	OP
`aspbackup.verify`	驗證備份完整性	OP
`aspbackup.reload`	重新載入配置	OP
`aspbackup.*`	所有權限（萬用字元）	OP

權限設定範例（LuckPerms）

# 給予管理員所有權限
/lp user Admin permission set aspbackup.*

# 給予協管員基本權限
/lp group moderator permission set aspbackup.command
/lp group moderator permission set aspbackup.status
/lp group moderator permission set aspbackup.list

技術支援

GitHub Issues: https://github.com/HDB-Studio/ASPbackup/issues
授權: Apache License 2.0

ASPbackup v1.0.0 — 文件最後更新：2026-08-09

main

ASPbackup 使用說明書

目錄

1. 安裝與需求

系統需求

安裝步驟

目錄結構

2. 快速開始

基本操作

自動備份

定時備份

3. 配置檔案詳解

3.1 備份設定 (backup)

3.2 備份來源 (sources)

3.3 檔案過濾規則 (file-filter)

3.4 備份目標 (targets)

3.5 分散式傳輸設定 (transfer)

3.6 檢查點設定 (checkpoint)

3.7 日誌設定 (logging)

3.8 磁碟空間監控 (disk-space)

4. 命令參考

命令總覽

詳細命令說明

/aspbackup start

/aspbackup stop

/aspbackup status

/aspbackup resume

/aspbackup list

/aspbackup nodes

/aspbackup verify

/aspbackup reload

/aspbackup about

/aspbackup info

5. 備份流程說明

5.1 完整備份流程

5.2 備份分類系統

5.3 啟動/關閉備份機制

5.4 中斷與續傳流程

5.5 備份任務狀態

6. 分散式傳輸設定

6.1 架構說明

6.2 負載均衡策略

6.3 傳輸協議

7. 接收端應用程式

7.1 快速啟動

7.2 接收端目錄結構

7.3 參數說明

7.4 安全建議

8. 常見問題

Q: 備份失敗，提示 "Insufficient disk space"

Q: 備份過程中伺服器 lag

Q: 備份越來越大？

Q: 如何恢復備份？

Q: 中斷的備份如何續傳？

Q: 如何變更備份目標？

Q: 接收端連線失敗？

9. 權限節點

權限設定範例（LuckPerms）

技術支援

Uh oh!

Uh oh!

Clone this wiki locally

3.1 備份設定 (`backup`)

3.2 備份來源 (`sources`)

3.3 檔案過濾規則 (`file-filter`)

3.4 備份目標 (`targets`)

3.5 分散式傳輸設定 (`transfer`)

3.6 檢查點設定 (`checkpoint`)

3.7 日誌設定 (`logging`)

3.8 磁碟空間監控 (`disk-space`)

`/aspbackup start`

`/aspbackup stop`

`/aspbackup status`

`/aspbackup resume`

`/aspbackup list`

`/aspbackup nodes`

`/aspbackup verify`

`/aspbackup reload`

`/aspbackup about`

`/aspbackup info`