SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-22

Docker Compose stack 備份與升級完整指南

了解 Docker Compose stack 備份不可遺漏的 4 項內容:compose 檔案、`.env`、volumes 與 database dump,並驗證還原及安全升級。

Docker Compose stack 備份必須包含的內容

Docker Compose stack 備份必須包含 4 項獨立內容。任何一項遺失,都會導致應用程式無法還原:compose 檔案、同一目錄中的 .env、每個 volume 的內容,以及使用資料庫自身 client 匯出的 database dump。在 container 執行期間直接複製資料庫檔案,不算備份。升級時使用相同的清單,另須遵守一項規則:在 pull 前先完成備份,因為 schema migration 的設計是向前套用,而且大多數專案沒有提供回復方式。

以下內容均假設 stack 已經部署完成,且 docker compose ps 顯示服務正在執行。範例使用位於 /srv/myapp 的 project directory,服務名稱為 app 和 db。請替換成自己的名稱。命令刻意保持通用,因為真正重要的部分,也就是 volume 和 database,不論應用程式為何,運作方式都相同。

確認堆疊實際儲存的內容

cd /srv/myapp
docker compose ps
docker compose config --volumes
docker volume ls --filter label=com.docker.compose.project=myapp

docker compose config --volumes 會列出 compose 檔案宣告之具名 volume 的簡稱。docker volume ls 會列出這些 volume 在磁碟上實際使用的名稱。兩份清單會有所不同,因為 Compose 會在名稱前加上 project name:檔案中的 db_data,實際存在時會是 myapp_db_data。project name 預設為目錄名稱,因此重新命名目錄會讓堆疊改用一組全新的空 volume,而舊 volume 仍會保留其中的資料。以下每個指令都需要使用 docker volume ls 中的實際名稱。

Bind mount 不會出現在上述任一清單中。在 compose 檔案中,冒號左側是主機路徑的項目就是 bind mount,例如 ./config:/app/config。這些是主機上的一般目錄,因此可使用一般工具存取。具名 volume 位於 /var/lib/docker/volumes/ 下方,docker volume inspect --format '{{.Mountpoint}}' myapp_db_data 會列出其中一個 volume 的確切路徑。堆疊使用哪一種類型,會影響備份方式;bind mount 與具名 volume 的比較會完整說明兩者的取捨。

接著將找到的項目分成兩組。有些 volume 儲存的是無法重新建立的狀態資料,例如上傳檔案、產生的金鑰、資料庫本身,以及使用者在應用程式中輸入的任何內容。其他 volume 儲存的是縮圖與搜尋索引等衍生資料,應用程式可自行重新建立。備份第二組資料只會增加磁碟空間需求與還原時間,沒有實際收益。Redis cache volume 是最明顯的例子:遺失它只會讓第一次請求變慢。

備份 compose 檔案與 .env 檔案

兩個檔案都位於主機上彼此相鄰的位置,且都不在任何 volume 內。.env 包含資料庫密碼、應用程式 secret 與各種 API token,因此它是將一組 volume 還原成可運作應用程式的關鍵檔案。它通常也會列在 .gitignore 中,因此「我的設定已放在 git」這項備份方式,反而排除了最重要的單一檔案。將 secret 存放在 env 檔案中是正確的做法,備份也必須配合保存這個檔案。

sudo install -d -m 700 -o "$USER" -g "$(id -gn)" /srv/backups/myapp
cp -a compose.yaml .env /srv/backups/myapp/
chmod 600 /srv/backups/myapp/.env

備份 stack 使用的每個 compose 檔案,不要只備份第一個檔案。使用 -f compose.yaml -f compose.prod.yaml 啟動的 stack 必須還原所有檔案,才能以相同方式恢復,而多個 compose 檔案如何合併會決定哪些值實際傳入 container。

有一項注意事項會同時涉及 .env 與 volume。官方 Postgres image 只會在初始化空的資料目錄時讀取 POSTGRES_PASSWORD。之後修改該值,不會變更資料庫內的密碼。若將上個月的 volume 與今天的 .env 一起還原,應用程式會因 FATAL: password authentication failed for user "appuser" 而無法連線,儘管檢查時兩個檔案看起來都正確。請將同一時間點的 .env 與 volume 一起保存在同一份備份中。

使用資料庫原生客戶端建立傾印

資料庫伺服器會持續寫入檔案。伺服器執行期間取得的 tar /var/lib/postgresql/data,可能會複製到寫入前的部分頁面,以及寫入後的部分頁面,因此封存檔包含不同時間點的混合狀態,還原時可能無法重播。傾印工具會在單一交易內讀取資料,因此檔案代表同一個一致的時間點。這項差異正是備份與複製的區別。

docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > /srv/backups/myapp/db-$(date +%F).dump

請保留 -T。它會停用 TTY 配置;若連接 TTY,Docker 會在輸出回傳至 shell 的過程中轉換資料流,導致二進位傾印損毀。直到還原失敗時,才會發現這個問題。單引號同樣重要:它會阻止主機 shell 展開 $POSTGRES_USER,改由容器內的 shell 使用 compose file 已設定的值進行展開。-Fc 會寫入自訂格式;此格式會在處理時壓縮,之後可用 pg_restore 從中挑出特定物件。

角色及其密碼位於個別資料庫之外,因此也要一併備份:

docker compose exec -T db sh -c 'pg_dumpall -U "$POSTGRES_USER" --globals-only' \
  > /srv/backups/myapp/globals.sql

接著確認檔案確實是傾印,而不是錯誤訊息:

ls -lh /srv/backups/myapp/
head -c 5 /srv/backups/myapp/db-$(date +%F).dump

自訂格式傾印會以 5 個位元組 PGDMP 開頭。大小為 0 位元組的檔案,或以 pg_dump: 開頭的檔案,都表示命令執行失敗。shell 會在命令執行前建立輸出檔案,因此傾印失敗後仍會留下名稱與時間戳看似合理的檔案。這是最常見的靜默備份失敗原因。

MariaDB 或 MySQL 使用不同的客戶端,但做法相同:

docker compose exec -T db sh -c \
  'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction --databases "$MARIADB_DATABASE"' \
  > /srv/backups/myapp/db-$(date +%F).sql

--single-transaction 會在不阻塞寫入的情況下,建立一致的 InnoDB 資料表傾印。在 MySQL image 中,命令是 mysqldump,變數則是 MYSQL_ROOT_PASSWORD 與 MYSQL_DATABASE。在 MariaDB image 中,自 11.0 起已移除 mysqldump 相容名稱,因此呼叫該名稱的舊有 script 會失敗,必須改用 mariadb-dump。請注意,只要傾印仍在執行,透過命令列提供的密碼就會顯示在容器的 process list 中。

SQLite 需要另外處理。資料庫雖然只有一個檔案,但最近的交易可能仍位於旁邊獨立的 -wal 檔案中,因此只複製 .db 會遺失最新寫入內容。如果 image 內含該客戶端,sqlite3 /data/app.db ".backup '/data/app-backup.db'" 可在應用程式執行期間寫出一致的複本。如果沒有,請停止容器,並將 .db 檔案與其 -wal 及 -shm 附屬檔案一併複製。

如果資料庫執行在主機上,而不是 stack 內,則可不使用 docker compose exec 前綴,直接套用相同命令;在下次重建前,建議閱讀在 Docker 或主機上執行資料庫。

擷取 volume

Named volume 沒有應手動編輯的主機路徑,因此請將它掛載到暫時容器,再從容器內建立封存檔。

docker run --rm \
  -v myapp_uploads:/data:ro \
  -v /srv/backups/myapp:/backup \
  alpine:3 tar czf /backup/uploads.tar.gz -C /data .

輔助容器會以唯讀方式將 volume 掛載到 /data,並將備份目錄掛載到 /backup,然後把封存檔寫回主機端。--rm 會在 tar 結束後立即移除輔助容器。:ro 很重要,因為即使 tar 指令打錯,也不會損壞來源資料。-C /data . 可確保還原時使用正確的路徑:它會將每個路徑儲存為相對於 volume 根目錄的路徑。若改用 tar czf /backup/uploads.tar.gz /data,每個路徑都會多出開頭的 data/,還原後便會在 volume 內建立 /data/data,應用程式看到的會是空目錄。封存檔的擁有者是 root,因為 tar 在容器內以 root 身分執行。若這造成問題,請執行 sudo chown "$USER" /srv/backups/myapp/uploads.tar.gz;如果還原後的檔案無法由應用程式讀取,請參閱PUID 與 PGID 如何決定檔案擁有權。

每個 named volume 執行一次即可。Bind mount 完全不需要容器:tar czf /srv/backups/myapp/config.tar.gz -C /srv/myapp/config . 在主機上即可完成相同工作。

請針對每個 volume 判斷應用程式是否必須停止。若應用程式會在原位置持續改寫 volume,對其執行中的資料使用 tar,可能會擷取到寫入一半的檔案。對於上傳目錄,檔案通常只寫入一次,之後只會讀取,因此風險很低。其他資料則應使用 docker compose stop app 停止服務,直到複製完成,再執行 docker compose start app。stop 會保留容器與 volume,這正是此處需要的行為;在輸入任一指令前,請先確認down 與 stop 的差異。

不要把資料庫 volume 的 tar 封存檔當成資料庫備份。dump 才是備份。已停止資料庫的 volume 封存檔,只適合作為快速重建途徑,除此之外沒有其他用途。

操作順序

  1. 將 compose 檔案與 .env 複製到備份目錄。
  2. 在資料庫仍在執行時匯出資料庫。
  3. 如果應用程式容器的 volume 會在原處變更,請停止該容器。
  4. 將每個具名 volume 與每個 bind mount 目錄封存。
  5. 啟動先前停止的服務,然後使用 docker compose ps 確認。
  6. 記錄 stack 目前使用的 image tags 與 digests。
  7. 將整個備份目錄複製到這台伺服器以外的位置。

第 7 步最容易被留到稍後才處理。

將副本移出這台伺服器

儲存在與服務堆疊相同磁碟上的備份,只能防止你自己操作錯誤,無法防範其他問題。只要有一個磁碟區故障、伺服器遭刪除或帳號遺失,兩份副本就會同時消失。請排程將目錄推送到不是這台 VPS 的儲存空間,並設定保留政策。VPS 的 restic 備份涵蓋 repository 設定、保留旗標與檢查命令,因此這裡不再重複說明。

restic 也能直接從 pipe 讀取 dump,完全不將純文字資料庫寫入磁碟:

docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  | restic backup --stdin --stdin-filename db.dump

無論使用哪個工具,都應將排程設定在 systemd timer 或 cron job 中,並讓工作將失敗狀態回報到你會查看的位置。輸出無人查看的備份腳本,可能停止運作半年而沒有人發現。

透過還原演練驗證備份可用

從未還原過的備份只是個假設。以下演練會將備份還原至與原環境並行的第二組服務,因此正式環境可持續提供服務,輸入的任何內容也不會觸及正式環境。

關鍵在於 project name。Compose 會從目錄名稱取得 project name,並將其套用至建立的每個容器與 volume。將備份複製到新目錄後,還原的服務組合便會自動取得各自的 volume。

sudo install -d -m 700 -o "$USER" -g "$(id -gn)" /srv/myapp-restore
cd /srv/myapp-restore
cp /srv/backups/myapp/compose.yaml /srv/backups/myapp/.env .

編輯複製的 compose 檔案,讓發布的主機埠不會與執行中的服務組合衝突:將 8080:8080 改成 18080:8080,或修改複製的 .env 中設定該埠的變數。接著建立容器與空的 volume,但先不要啟動任何服務:

docker compose create
docker volume ls --filter label=com.docker.compose.project=myapp-restore

第二個指令應列出與正式環境相同的 volume 名稱,前面加上 myapp-restore_。將資料填入 volume,單獨啟動資料庫,然後載入 dump:

docker run --rm -v myapp-restore_uploads:/data -v /srv/backups/myapp:/backup \
  alpine:3 tar xzf /backup/uploads.tar.gz -C /data
docker compose up -d db
docker compose exec -T db sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' \
  < /srv/backups/myapp/db-2026-08-16.dump

--clean --if-exists 會在重新建立每個物件前先刪除該物件,因此還原可以重複執行。若未使用此選項,第二次對已經包含這些資料表的資料庫執行時,會因 pg_restore: error: could not execute query: ERROR: relation "users" already exists 而停止。

接著啟動其餘服務,並以使用者實際操作的方式進行確認:

docker compose up -d --wait
docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\\dt"'
docker compose logs --tail=50

docker compose up -d --wait 會持續等待,直到每個服務都回報正在執行或狀態健康;若其中一個服務始終未達成條件,指令會以非 0 狀態碼結束,因此可以納入指令碼。服務始終未變成健康狀態時,docker compose ps -a 會顯示其狀態,包括已經結束的服務;一般的 docker compose ps 不會列出這些服務。Compose 健康檢查說明該欄位顯示的內容。接著使用替代埠開啟應用程式,並以實際帳號登入。建立一筆記錄,再開啟一個位於 volume 中的檔案。這兩項操作就是驗證依據:dump 已還原、volume 已還原,而且兩者內容一致。只確認登入頁面能顯示,無法證明任何資料已成功還原。

演練通過後,將其清除:

docker compose down -v

這是唯一應使用 -v 旗標的情況。在正式環境目錄中執行相同指令,會刪除你要保護的 volume。

如何升級 Compose stack

閱讀目前版本與目標版本之間每個版本的 release notes,並搜尋 breaking 與 migration。不支援跨越多個 major version 直接升級的專案,通常會在其中說明;而 migration 若無法執行,往往要到已經變更部分 schema 後才會回報。

變更前先記錄目前的執行狀態:

docker compose images
docker image inspect --format '{{index .RepoDigests 0}}' postgres:16.4

docker compose images 會列出目前各服務使用的 image 與 tag。digest 是唯一能精確指定 image 的值,因為 tag 隨時可能被重新指向其他位置。

使用上述章節建立的 backup,並將其複製到這台伺服器以外的位置。即使是 patch release,也應該這樣做。人們最容易停止準備的,正是那些看似成本低廉的升級。

接著在 compose file 中固定版本,因為 latest 不是版本:

services:
  db:
    image: postgres:16.4

使用 image: postgres:latest 時,docker compose pull 會取得該 tag 今天所指向的內容,而你無法指定昨天實際執行的內容。固定 tag 後,升級只需修改一行;你可以在 git diff 中清楚看出變更,也能再修改一行復原。application image 也應以相同方式固定,並從專案的 release page 取得確切版本。

Pull 並重新建立服務:

docker compose pull
docker compose up -d --wait

docker compose up -d 會比較檔案與目前執行中的 containers,只重新建立 image 或設定已變更的服務。它不會碰 named volumes,因此新的 container 會使用現有資料啟動。這正是此操作的目的,也是它的風險所在,因為新版本通常會在第一次啟動時執行 schema migration。

監看執行結果:

docker compose ps -a
docker compose logs -f --tail=100 app

單獨執行 docker compose ps 只會列出正在執行的 containers,因此失敗的 container 會直接從清單中消失。使用 -a 後,它會繼續留在清單中,並在 STATUS 欄顯示 exited (1) 或其他非零代碼;失敗原因則會出現在 log 的最後幾行。Migration 錯誤會在那裡明確顯示,其他地方則看不到。log 穩定後,登入並操作應用程式幾分鐘。

如果 docker compose pull 因 no space left on device 停止,通常是舊 image layers 導致;使用 清理未使用的 Docker images 即可釋放空間。請在升級確認運作正常後再進行清理,不要提前清理,因為快速 rollback 需要依賴那些舊 layers。

升級失敗時如何回復

這分成兩種情況,所需處理成本差異很大。如果新版本沒有變更 schema,回復只需一行:將舊的 tag 放回 compose 檔案,然後執行 docker compose up -d。容器會重新建立,volume 會保留在原處,舊版程式也能讀取它寫入的資料。

如果新版本已遷移 schema,舊版程式就無法再讀取。遷移通常只支援向前執行,而且多數專案根本沒有提供降級指令碼。因此,舊版啟動後,第一次查詢已重新命名或刪除的欄位時就會失敗,並出現類似 ERROR: column "avatar_url" does not exist 的錯誤。回復方式是使用拉取新版本前建立的 dump:放回舊的 tag,移除資料庫 volume,重新建立空的 volume,將 dump 還原其中,然後啟動服務。如果沒有該 dump,就完全無法回復,這正是備份必須在拉取新版本前完成的原因。

Postgres major version 是最典型的情況,且常讓人意外,因為錯誤通常發生在升級時,而不是回復時。Major release 經常會變更 system table 的配置,而且每個 data directory 都會標記建立它的 major version。因此,即使使用者資料檔案本身很少變更格式,不同 major version 的伺服器仍會拒絕開啟該目錄。將 postgres:16.4 改為 postgres:17.2,執行 docker compose up -d,新伺服器就會拒絕啟動:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.2.

該 image 不會替你執行 pg_upgrade。在 Compose stack 中,最簡單的方式是 dump、替換、restore:在舊版本仍在執行時建立 dump,執行 docker compose down,移除資料庫 volume,設定新的 tag,執行 docker compose create 建立全新的空 data directory,啟動資料庫,還原 dump,最後啟動其餘服務。如果新的 tag 是 18 或更新版本,還要一併調整 volume mount:從 PostgreSQL 18 起,官方 image 會將資料放在版本專用的目錄,例如 /var/lib/postgresql/18/docker,其 volume 應為 /var/lib/postgresql,而不是 /var/lib/postgresql/data。在新的 major version 實際處理流量滿一天前,請保留舊的 dump。同一個 major version 內的 minor upgrade,例如 16.4 升至 16.9,則不需要這些步驟,因為 minor release 不需要 dump 和 restore,容器會直接啟動。

VPS snapshot 是備份嗎?

VPS snapshot 是備份的補充,兩者的失效方式不同。snapshot 會在 hypervisor 層複製整個磁碟,因此能在幾分鐘內還原整台機器,包括你忘記備份的部分。這使它適合一項特定工作:升級導致伺服器故障,而你想將伺服器還原到 20 分鐘前的狀態。

對其他用途而言,snapshot 並不理想。其粒度是整台機器,因此要復原單一遭刪除的資料表,就必須先在某處還原整台伺服器,再從中取出該資料表。保留期限通常很短。副本通常與伺服器位於同一個 provider 帳戶,因此帳戶遺失時,伺服器與 snapshot 也會同時遺失。此外,執行中機器的 snapshot 可能擷取到資料庫正在寫入的狀態,因此資料庫首次啟動時會執行 crash recovery,任何當時尚未完成的交易都會遺失。

兩者都使用。snapshot 是升級期間的復原按鈕。dump 則是即使帳戶遭刪除仍能保留的副本。snapshot 與備份的差異會說明兩者實際能涵蓋哪些故障。相同的備份目錄也能讓將 stack 搬移到新的 VPS成為例行工作,而不必憑記憶重新建置。

發生的問題與你會看到的現象

down 時使用 volumes 旗標。 docker compose down -v 會移除 Compose 檔案宣告的 named volumes,Compose 會顯示一行 Volume myapp_db_data Removed 進行確認。此操作無法復原。單純執行 docker compose down 不會影響這些 volumes。請輸入完整形式 docker compose down --volumes,讓破壞性旗標必須明確輸入完整單字。

不含 magic string 的 dump。 pg_restore: error: did not find magic string in file header 表示該檔案不是 archive。最常見的原因是在 docker compose exec 上遺漏 -T,因為連接 TTY 時,資料流在傳送至 shell 的過程中會被轉換,導致 binary dump 損毀。請使用 -T 重新建立 dump,再以 head -c 5 檢查前 5 個位元組。

無法變更的密碼。 還原後執行 FATAL: password authentication failed for user "appuser",表示 .env 與資料目錄來自不同時間點。image 只會在建立空白資料目錄時設定該密碼,因此之後編輯 .env 不會變更資料庫內的內容。請還原相符的 .env,或使用 ALTER USER 在資料庫內變更密碼。

第二個空白 volume。 Docker 會在需要時建立 volume,因此在缺少 s 的情況下執行 docker run -v myapp_upload:/data,會將資料寫入全新且空白的 volume,並回報成功。接著執行 docker volume ls 會顯示兩個名稱,其中一個沒有任何內容。請從 docker volume ls 複製 volume 名稱,不要憑記憶輸入。

將還原操作指向 production。 在 /srv/myapp-restore 以外的 /srv/myapp 中執行還原命令,會使用 backup 覆寫執行中的資料,而兩處的命令看起來完全相同。每次執行還原命令前,請先確認 pwd,並將演練放在專用目錄中。

FAQ

docker compose down 會刪除我的資料嗎?

不會。docker compose down 會移除容器與預設網路,但不會動到具名 volume 和 bind mount。docker compose down -v 會移除檔案中宣告的具名 volume,而且這是永久性的。bind mount 是主機目錄,因此 Compose 永遠不會移除它們。如果您希望在備份期間停止服務,但保留其他所有內容,請改用 docker compose stop。

我可以直接複製 Postgres 資料目錄,而不執行 pg_dump 嗎?

只能在容器停止時這麼做。伺服器執行期間,檔案會持續變更,複製結果可能混合不同時間點的內容,無法正常重播。檔案層級的複製也綁定單一 Postgres major version,因此無法在不同版本下啟動。請停止容器、封存 volume,再重新啟動容器;並將這項複製視為快速重建途徑,不要把它當成唯一的備份。dump 才是可攜式副本,也是您要還原的來源。

如何在 Compose 中將 Postgres 升級至新的 major version?

只變更 tag 並不足夠。新的伺服器會拒絕使用舊的資料目錄啟動,並記錄 The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.2。在舊版本仍執行時,執行 pg_dump,接著執行 docker compose down;移除資料庫 volume、設定新的 tag,再執行 docker compose create 建立全新的空 volume。啟動資料庫,然後將 dump 還原至其中。在新版本實際處理過網路流量前,請保留舊的 dump。

備份應多久執行一次?應保留多久?

請依照您願意重新處理的工作量決定間隔。個人或小型團隊的 stack 適合每日備份,並在任何升級前立即再手動備份一次。保留期限應涵蓋您未能立即發現的損害,因為週五才發現損壞的資料表,無法由週四晚上的副本協助復原。restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune 是合理的起始政策。無論排程為何,每季都應從備份執行一次還原。在完成這項測試前,您擁有的不是備份,而只是檔案。

備份時必須停止整個 stack 嗎?

通常不必。資料庫 dump 在伺服器執行期間仍能保持一致,因此資料庫不需要停機。真正需要考量的是 volume。如果應用程式只會新增檔案,例如 uploads 目錄,線上封存通常已足夠安全。如果應用程式會原地改寫檔案,請使用 docker compose stop app 在複製期間停止該服務,完成後再重新啟動。讓應用程式停止、資料庫繼續執行,通常是能安排的最短安全時段。

這篇文章對您有幫助嗎?