PBS Client 備份主機與 VM、CT 內的檔案

Jason Cheng 發布 2026.10.28 瀏覽 1 次

Linux Proxmox BS Proxmox VE 系統管理虛擬化資料備份開源軟體

本文目錄

適用情境與版本
PBS 端準備
連線設定
PVE 主機：備份系統設定
VM 內：系統設定與資料
CT 內：系統設定與資料
排程
保留與清除
查詢與還原
常見錯誤
Windows 與 macOS
結論
參考資料

PVE 搭配 Proxmox Backup Server（PBS）備份整台 VM、CT 是最常見的用法，但有些資料用整機備份不方便：PVE 主機本身的設定、VM 裡需要比整機更頻繁備份的資料目錄、想單獨保留較久的檔案；還有不在 PVE 上的主機，例如其他虛擬化平台的 VM、雲端主機或實體機，根本沒有 PVE 的整機備份可用。這時候我會在主機或系統裡裝 proxmox-backup-client，直接把指定目錄備份到 PBS，一樣有去除重複、壓縮、加密與驗證。

這篇整理我自己的用法，並對照 PBS 4.2 的官方文件更新：先在 PBS 建立專用權杖，再分別寫 PVE 主機、VM、CT 三種情境，最後是排程、還原與常見錯誤。

適用情境與版本

情境	安裝方式	建議備份內容
PVE 主機	PVE 已內建，不用另外安裝	`/etc`、`/etc/pve`、pmxcfs 資料庫、`/root`
VM（Debian、Ubuntu）	PBS 的 client 套件庫	`/etc`、資料目錄、資料庫匯出檔
CT	同 VM	`/etc`、資料目錄
非 PVE 的 Linux 主機（實體機、其他平台的 VM）	同 VM，或靜態連結版	`/etc`、資料目錄、資料庫匯出檔
Windows、macOS	沒有官方 client	另文介紹第三方工具

本文依 PBS 與 proxmox-backup-client 4.2.8、PVE 9.2 撰寫（2026/10）。指令功能的版本需求主要看 client 的版本，部分功能有版本門檻，會在用到的地方註明；網頁介面瀏覽備份內容則另外受 PBS 伺服器版本限制。

proxmox-backup-client 做的是檔案層級的備份，在備份對象自己的系統裡執行。PVE 上 VM、CT 的整機備份仍然交給 PVE 的備份工作，兩者互補，不是取代。

注意：proxmox-backup-client 也能用 .img 備份區塊裝置，但不要拿來直接讀執行中 VM 的 zvol 或 LV，讀到的是不一致的磁碟內容。VM 的整機備份請用 PVE 的備份工作，它透過 QEMU 取得磁碟層級一致的快照，搭配 QEMU Guest Agent 還能先凍結檔案系統；資料庫仍建議另外匯出。

PBS 端準備

建立專用帳號與權杖

不要用 root@pam 備份。我會建一個專用帳號，每台備份對象各發一個 API 權杖：

proxmox-backup-manager user create backup@pbs --comment "proxmox-backup-client"
proxmox-backup-manager user generate-token backup@pbs pve01

輸出的 value 就是權杖密碼，只會顯示這一次，要立刻保存。接著給權限，帳號與權杖兩個都要給：

proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id backup@pbs
proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'backup@pbs!pve01'
proxmox-backup-manager user permissions 'backup@pbs!pve01' --path /datastore/store1

最後一行用來確認實際權限，要看到 Datastore.Backup。幾個重點：

權杖的權限是「權杖自己的 ACL」與「所屬帳號權限」的交集，只給其中一個，等於沒有權限
DatastoreBackup 只能備份、還原自己擁有的備份，一台主機一個權杖，某台被入侵也讀不到別台的備份
DatastoreBackup 不能刪除備份，保留與清除交給 PBS 的 prune 工作，被入侵的主機無法刪掉歷史備份
權杖名稱裡有 !，在 shell 裡要加單引號

取得憑證指紋

PBS 預設是自簽憑證，client 無法用系統的 CA 驗證，要改用指紋確認連到的是正確的伺服器。在 PBS 上查：

proxmox-backup-manager cert info | grep Fingerprint

網頁介面的「Dashboard → Show Fingerprint」也看得到。PBS_FINGERPRINT 只在系統 CA 無法驗證憑證時才會用到，PBS 換成受信任 CA 簽發的憑證（例如 Let's Encrypt）後就不需要指紋。

連線設定

儲存庫格式

client 用「儲存庫」字串指定連線目標：

[[帳號@realm[!權杖]@]伺服器[:連接埠]:]datastore

寫法	帳號	伺服器	datastore
`store1`	`root@pam`	`localhost:8007`	`store1`
`pbs.example.com:store1`	`root@pam`	`pbs.example.com:8007`	`store1`
`backup@pbs!pve01@pbs.example.com:store1`	權杖 `backup@pbs!pve01`	`pbs.example.com:8007`	`store1`
`192.168.1.20:8443:store1`	`root@pam`	`192.168.1.20:8443`	`store1`

PBS 網頁介面的 datastore 摘要頁有「Show Connection Information」可以直接複製。client 4.1.8 起也可以改用 --server、--datastore、--auth-id 分開指定，對應的環境變數是 PBS_SERVER、PBS_DATASTORE、PBS_AUTH_ID。

權杖與指紋的存放位置

以前我把 PBS_REPOSITORY、PBS_PASSWORD、PBS_FINGERPRINT 寫進 /etc/environment、/etc/profile、~/.bashrc 三個地方，後來發現有幾個問題：

/etc/environment 所有使用者都讀得到（權限 644），權杖密碼等於公開給主機上的每個帳號，還會被帶進每個登入工作階段
/etc/environment 不是 shell 腳本，目前工作階段還沒有這些變數時，source /etc/environment 只會設成 shell 變數、不會 export，set | grep PBS 看得到，proxmox-backup-client 卻讀不到
三個地方重複，換權杖要改三處，漏改一處就是一台備份失敗

現在改成一個只有 root 能讀的設定檔：

install -d -m 700 /etc/pbs-client
cat > /etc/pbs-client/env <<'EOF'
PBS_REPOSITORY='backup@pbs!pve01@pbs.example.com:store1'
PBS_PASSWORD='your-token-secret'
PBS_FINGERPRINT='aa:bb:cc:...:ff'
EOF
chmod 600 /etc/pbs-client/env

手動操作時先載入，set -a 會讓載入的變數自動 export：

set -a; . /etc/pbs-client/env; set +a
proxmox-backup-client status

status 會顯示 datastore 的使用量，能看到就代表連線、憑證驗證與權杖都正常。

從舊做法改過來的話，記得刪掉三個地方的舊設定，並在 PBS 換發新權杖、刪除舊權杖：舊權杖已經放在所有人都讀得到的檔案裡一段時間，應該視為外洩。

也可以把權杖密碼另存一個檔案，改用 PBS_PASSWORD_FILE 指向它，注意 PBS_PASSWORD 的優先順序比較高，切換時要先 unset PBS_PASSWORD；client 3.3.5 起還支援 systemd 的 credentials（systemd-creds 加密保存），適合用 systemd 服務執行備份的環境。

加密金鑰

備份內容如果含有密碼、金鑰（PVE 的 /etc/pve/priv、應用程式設定檔，以及上面的 /etc/pbs-client/env），建議在 client 端加密，PBS 端的管理者就看不到內容。每台主機各自建立金鑰：

proxmox-backup-client key create /etc/pbs-client/encryption-key.json --kdf none
chmod 600 /etc/pbs-client/encryption-key.json
proxmox-backup-client key paperkey /etc/pbs-client/encryption-key.json --output-format text > /root/pbs-paperkey.txt

本文為了排程簡單，用 --kdf none 建立沒有密碼的金鑰，所以檔案權限一定要是 600。要保留金鑰密碼也可以，排程時改用 PBS_ENCRYPTION_PASSWORD_FILE 或 systemd credentials 提供密碼。

金鑰遺失，備份就還原不了。紙本金鑰（paperkey）印出來或存進密碼管理工具，不要只放在同一台主機上，印完記得刪掉 /root/pbs-paperkey.txt。之後的備份、還原、瀏覽、掛接指令都要帶 --keyfile。

PVE 主機：備份系統設定

PVE 已經內建 proxmox-backup-client（PVE 的儲存套件依賴它），不用另外安裝。

要備份哪些內容

內容	封存名稱	說明
`/etc`	`etc.pxar`	網路、hosts、APT、SSH、cron、本文的備份腳本與設定
`/etc/pve`	`pve.pxar`	VM/CT 設定、儲存設定、權限、`priv/` 裡的金鑰
pmxcfs 資料庫	`pmxcfs.pxar`	`/var/lib/pve-cluster/config.db` 的一致性複本
`/root`	`root.pxar`	自己的腳本、SSH 金鑰

/etc/pve 是 pmxcfs 叢集檔案系統的掛接點，備份 /etc 時會因為是另一個檔案系統而被略過（執行時會看到 skip mount point），所以要另外列一個封存。封存名稱只能用英數字、-、_，我習慣依內容命名，不要全部叫 root.pxar。

/etc/pve 是給人看的檔案，真正的資料在 config.db。PVE 官方的復原做法是把 config.db 放回新主機，所以我也一起備份。資料庫在執行中，不要直接複製檔案，先用 SQLite 的線上備份匯出：

apt install sqlite3
install -d -m 700 /var/backups/pmxcfs
sqlite3 /var/lib/pve-cluster/config.db ".backup /var/backups/pmxcfs/config.db"

執行備份

set -a; . /etc/pbs-client/env; set +a
proxmox-backup-client backup \
  etc.pxar:/etc pve.pxar:/etc/pve pmxcfs.pxar:/var/backups/pmxcfs root.pxar:/root \
  --keyfile /etc/pbs-client/encryption-key.json

備份 ID 預設是主機名稱，PBS 上會出現 host/pve01 這個群組。同一個 datastore 與 namespace 裡備份 ID 不能重複，從範本複製出來、主機名稱相同的 VM 或 CT，要用 --backup-id 指定不同的名稱；每台也都要用自己的權杖，不能共用 pve01 的設定。要看更詳細的處理過程，在指令前加 PBS_LOG=debug（目前的 backup 已沒有 --verbose 參數）。

VM 內：系統設定與資料

PVE 已經有整台 VM 的備份，VM 內再裝 client 的理由是：資料目錄要更頻繁備份或保留更久、只想還原幾個檔案、或是 VM 不在 PVE 上（例如其他虛擬化平台、雲端主機）。

安裝（Debian 13）

先加入 Proxmox 的套件庫金鑰，並核對 SHA256：

wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
  -O /usr/share/keyrings/proxmox-archive-keyring.gpg
sha256sum /usr/share/keyrings/proxmox-archive-keyring.gpg

官方文件列出的值是 136673be77aba35dcce385b28737689ad64fd785a797e57897589aed08db6e45。接著加入 client 專用的套件庫：

cat > /etc/apt/sources.list.d/pbs-client.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update
apt install proxmox-backup-client

Debian 12 只要把 Suites 改成 bookworm，同一個金鑰檔已包含 bookworm 的簽章金鑰，裝到的是 3.4 版。

其他發行版：靜態連結版

client 套件庫只有 APT 格式，Ubuntu 等衍生版本可能可以直接使用，但若系統的函式庫版本滿足不了一般版的相依需求，就改裝 client 3.4 起提供的靜態連結版，它不依賴系統函式庫：

apt install proxmox-backup-client-static

兩個套件會衝突，只能裝一個。靜態版的執行檔可以直接複製到 RHEL 這類非 Debian 的 x86-64 Linux 使用。官方仍建議能用一般版就用一般版：靜態版不走 libc 的名稱解析，/etc/nsswitch.conf 這類設定不會生效。我目前只在 Debian 系統用過，其他發行版請先實際測試備份與還原。

要備份哪些內容

mountpoint -q /data || { echo "/data 沒有掛接"; exit 1; }
proxmox-backup-client backup etc.pxar:/etc data.pxar:/data \
  --change-detection-mode=metadata \
  --keyfile /etc/pbs-client/encryption-key.json

資料目錄：範例的 /data 是另一顆磁碟的掛接點，列成自己的封存。只備份 / 的話，client 預設不會跨到其他檔案系統，要用 --include-dev /data 這類寫法才會納入
掛接檢查：/data 沒掛上時目錄還在，client 會備份到一個空目錄，而且照樣成功，所以先用 mountpoint 確認
資料庫：不要直接備份資料庫檔案，先用 mysqldump、pg_dump 匯出到某個目錄，再把那個目錄一起備份。匯出要寫進下面的排程腳本、放在備份之前，匯出失敗就不要繼續
一致性：client 是逐一讀取檔案，不是整個目錄同一時間點的快照。會同時修改多個檔案的應用程式，要用它自己的備份功能、先暫停寫入，或改備份檔案系統快照
排除：快取、暫存目錄可以在該目錄放 .pxarexclude（一行一個 glob 規則），或在指令加 --exclude
變更偵測：client 3.2.5 起有 --change-detection-mode。metadata 會比對上一次的中繼資料，沒變的檔案不重新讀取，檔案多、變動少的資料目錄快很多；預設的 legacy 模式每次都重讀全部檔案

注意：metadata 模式依檔案大小、mtime、擁有者、權限等中繼資料判斷，內容改了、但這些中繼資料都沒變的檔案會被當成沒變。對這點有疑慮的資料，定期改用 --change-detection-mode=data 完整重讀一次，它的封存格式與 metadata 相同。

CT 內：系統設定與資料

CT 裡的安裝與用法跟 VM 相同，非特權 CT 一般的備份與還原不需要 FUSE。/proc、/sys、/dev 這些掛接點會自動略過。備份保存的是數字的 UID/GID，還原時照數字設定擁有者，不會依帳號名稱轉換；還原到重建的 CT 或另一台主機時，要確認帳號的 UID/GID 一致，第一次使用請實際還原一次確認。

差別在 mount 子指令用的是 FUSE：要掛接備份瀏覽檔案，CT 要開啟 FUSE 功能。而 PVE 官方不建議在 CT 裡使用 FUSE，FUSE 掛接中的 CT 用 snapshot、suspend 模式備份可能會卡住（細節見〈PVE 掛接外部 Ceph 與 CT 直接掛接 CephFS〉）。CT 裡要還原檔案時，我改用下一節的 catalog shell 或 restore。

排程

把載入設定與備份指令寫成一支腳本，放在 /etc/pbs-client/ 裡，備份 /etc 時就會一起備份到。PVE 主機的版本如下：

cat > /etc/pbs-client/backup.sh <<'EOF'
#!/bin/sh
set -eu
set -a
. /etc/pbs-client/env
set +a
mountpoint -q /etc/pve
sqlite3 /var/lib/pve-cluster/config.db ".backup /var/backups/pmxcfs/config.db"
exec proxmox-backup-client backup \
  etc.pxar:/etc pve.pxar:/etc/pve pmxcfs.pxar:/var/backups/pmxcfs root.pxar:/root \
  --keyfile /etc/pbs-client/encryption-key.json
EOF
chmod 700 /etc/pbs-client/backup.sh

set -e 讓任何一步失敗就停止，/etc/pve 沒掛上或資料庫匯出失敗都不會繼續備份。VM、CT 的版本把 mountpoint 換成自己的資料目錄，sqlite3 那行換成資料庫匯出（沒有資料庫就拿掉），備份清單改成自己的目錄即可。

接著加入排程 /etc/cron.d/pbs-client：

SHELL=/bin/sh
PATH=/usr/sbin:/usr/bin:/sbin:/bin

# 每天 03:20
20 3 * * * root flock -n /run/pbs-backup.lock /etc/pbs-client/backup.sh >> /var/log/pbs-backup.log 2>&1

flock 避免上一次還沒跑完又啟動下一次。腳本自己載入設定檔，不依賴 cron 的環境變數，也就不需要把權杖放進 /etc/environment。幾個容易漏掉的地方：

精簡的 VM、CT 可能沒裝 cron，先用 systemctl status cron 確認
輸出都導向記錄檔，cron 不會寄信，排程失敗要自己發現：我會定期到 PBS 看各群組最新快照的時間，記錄檔長期累積也要加 logrotate
第一次設定好後，手動執行一次 /etc/pbs-client/backup.sh，確認 PBS 上有新的快照

保留與清除

DatastoreBackup 權限不能刪除備份，所以 client 端不跑 prune。保留規則在 PBS 設定 prune 工作，例如 keep-daily=7、keep-weekly=4、keep-monthly=6，分別是最近 7 個有備份的日子、4 個週、6 個月各留最後一份，不是固定的總份數。

prune 移除的是快照本身（manifest 與索引等中繼資料），資料區塊要等 PBS 的垃圾回收（GC）確認沒有被引用、而且超過保護期間後才會釋放空間。

查詢與還原

列出備份群組與某個群組的快照：

proxmox-backup-client list
proxmox-backup-client snapshot list host/pve01

快照名稱的格式是 host/<備份 ID>/<UTC 時間>。還原整個封存到指定目錄，快照可以只寫群組，會自動用最新一份。用 metadata、data 模式備份的封存，在 PBS 上會分成 .mpxar、.ppxar 兩個檔案，還原、瀏覽、掛接時照樣寫 data.pxar，client 會自動對應：

proxmox-backup-client restore host/pve01 etc.pxar /root/restore-etc \
  --keyfile /etc/pbs-client/encryption-key.json

只要找幾個檔案時，用互動式的 catalog shell 比較快，瀏覽時只讀目錄與中繼資料，真正還原時才讀取需要的資料區塊：

proxmox-backup-client catalog shell host/pve01/2026-10-28T03:20:01Z etc.pxar \
  --keyfile /etc/pbs-client/encryption-key.json

pxar:/ > find network/** --select
pxar:/ > restore-selected /root/restore-network

restore-selected 的目標用一個新的目錄。在可以使用 FUSE 的主機上，也可以唯讀掛接整個封存，掛接點要先建立，用完記得 umount：

mkdir -p /mnt/restore
proxmox-backup-client mount host/pve01/2026-10-28T03:20:01Z etc.pxar /mnt/restore \
  --keyfile /etc/pbs-client/encryption-key.json

注意：不要把 pve.pxar 直接還原到執行中的 /etc/pve。先還原到暫存目錄，再挑需要的設定檔複製回去。

整台主機重建時，依 PVE 官方的做法：

準備一台沒有任何 VM、CT 在執行的新 PVE 主機
停掉 pve-cluster 服務，放回 config.db（權限 0600）
把 /etc/hostname、/etc/hosts 改成原本主機的名稱，config.db 裡的設定是依節點名稱存放
重新開機後檢查設定，VM、CT 的磁碟資料要另外從備份還原

叢集節點則以重新加入叢集為主，不要直接覆蓋。

常見錯誤

Connection reset by peer (os error 104)

Starting backup protocol: ...
Error: connection error: Connection reset by peer (os error 104)

我遇到這個錯誤時，原因是權杖沒有該 datastore 的權限。用 proxmox-backup-manager user permissions 檢查，記得帳號與權杖都要有 ACL。這個錯誤碼本身只代表連線被對方重設，權限正常的話，再查網路、防火牆或中間設備是否切斷 8007 的連線。

certificate fingerprint does not match

WARNING: certificate fingerprint does not match expected fingerprint!
certificate validation failed - Certificate fingerprint was not confirmed.

PBS 的自簽憑證重新產生後，指紋就會改變。到 PBS 上用 proxmox-backup-manager cert info 確認新指紋，再更新 /etc/pbs-client/env。不要沒確認就照單全收，指紋不符也可能是連線被攔截。

權杖外洩或主機汰換

到 PBS 刪除那台的權杖即可，不影響其他主機：

proxmox-backup-manager user delete-token backup@pbs pve01

換發新權杖時要注意，備份群組的擁有者是原本的權杖，換了不同名稱的權杖就無法再寫入、還原原本的群組。要把群組擁有者改成新權杖。

變更擁有者要在新的終端機工作階段執行（不要先載入 /etc/pbs-client/env，否則會用到舊權杖），以具有 Datastore.Modify 權限的管理帳號連線，執行時會詢問該帳號的密碼：

proxmox-backup-client change-owner host/pve01 'backup@pbs!pve01-new' \
  --repository admin@pbs@pbs.example.com:store1

改完把那台主機 /etc/pbs-client/env 裡的權杖名稱與密碼換成新的，再手動備份、還原各測一次。

網頁介面的 datastore「Content」頁面也可以修改擁有者。

Windows 與 macOS

PBS 官方目前只有 Linux 版的 client，套件庫也只有 APT 格式，Windows 與 macOS 都沒有官方 client。這兩個平台要備份到 PBS 得靠第三方工具，我會另外寫一篇介紹。

結論

proxmox-backup-client 補足了整機備份不方便處理的部分：PVE 主機設定、VM 與 CT 裡的資料目錄，都能用同一套 PBS 去除重複、加密與保留規則管理。

幾個重點：每台主機用自己的權杖、只給 DatastoreBackup，權杖放在只有 root 能讀的檔案，含金鑰的備份要加密，加密金鑰另外保存，並定期實際還原測試。

參考資料

Proxmox Backup Server 文件：Backup Client Usage
https://pbs.proxmox.com/docs/backup-client.html
Proxmox Backup Server 文件：Client Installation
https://pbs.proxmox.com/docs/installation.html
Proxmox Backup Server 文件：User Management（API Tokens）
https://pbs.proxmox.com/docs/user-management.html
Proxmox Backup Server 文件：Change Detection Mode
https://pbs.proxmox.com/docs/technical-overview.html
Proxmox Backup Server 文件：Maintenance Tasks（Pruning、GC）
https://pbs.proxmox.com/docs/maintenance.html
Proxmox VE 文件：Proxmox Cluster File System（pmxcfs）
https://pve.proxmox.com/pve-docs/chapter-pmxcfs.html
PBS 災難復原：設定檔備份清單
https://blog.jason.tools/2026/03/pbs-etc-backup.html
PVE 掛接外部 Ceph 與 CT 直接掛接 CephFS
https://blog.jason.tools/2026/10/pve-external-ceph-cephfs.html

Jason Cheng

企業開源技術顧問，專注架構規劃與實務導入

關於作者 →

延伸閱讀

PBS 災難復原：設定檔備份清單 2026.03.13

Proxmox BS Beta 版小試 2020.07.12

Proxmox VE 備份整合方案應用：Proxmox BS 2021.10.10

PBS 掛接 iSCSI 作為備份儲存區 2025.12.26