DEPLOYMENT GUIDE

備份與還原

原始檔 docs/deploy/backup.md · 在 GitHub 上檢視

你的所有資料都在 PostgreSQL。系統提供三道保障:每日自動備份、隨時手動備份、還原(含還原前自動保護)。備份檔為 PostgreSQL 原生 custom 格式(.dump),存於 Docker volume backups。

---

一、每日自動備份(預設已開)

• worker-ops 容器每天 02:00(以 .env 的 TZ 時區為準,預設 Asia/Taipei)自動 pg_dump 一份。
• 預設保留最新 30 份,超出者由舊到新自動輪替刪除。
• 可在 .env 調整:

ini # 這幾項為進階設定,一般維持預設即可;如需調整可加入 .env # BACKUP_HOUR=2 # 每日自動備份的時(0–23) # BACKUP_KEEP=30 # 保留份數 # BACKUP_DIR=/backups

改完 docker compose up -d 生效。

自動備份的檔名形如 backup_20260711_020000_daily.dump。

---

二、手動備份與還原(系統管理介面)

登入後到 系統管理 → 資料備份與還原(限系統管理員):

• 立即備份:當場產生一份手動備份(檔名 ..._manual.dump)。重大操作(升級、大量匯入、學期切換)前建議先按一次。
• 備份清單:列出所有備份(來源標為「自動 / 手動 / 還原前保護 / 上傳」),可下載、還原、刪除。
• 上傳還原:把先前下載的 .dump 檔上傳並還原(用於換主機、異地備援回復)。非備份格式的檔案會被直接拒絕,不影響現有資料。

還原會發生什麼

1. 系統先自動備份現狀(來源標「還原前保護」),萬一還原的內容不對可再退回。
2. 以該備份覆蓋整個資料庫。
3. 還原完成後強制所有人重新登入(因為使用者資料已被替換)。你會被導回登入頁,以還原時點的帳密登入。

還原是覆蓋性操作,請確認選對備份檔再執行。有「還原前保護」這道自動備份墊底,誤操作仍可救回。

---

三、異地備援(強烈建議)

Docker volume 存在同一台主機。若主機硬碟壞掉,volume 一起沒了。 真正安全的備份要放到另一個地方:

做法 1:定期下載備份檔(最簡單)

到「資料備份與還原」按「立即備份」→「下載」,把 .dump 檔存到另一台電腦、外接硬碟或雲端硬碟。要復原時在新主機上「上傳還原」。

超大資料庫的還原走這裡,不要用網頁上傳。 系統對網頁上傳有 200MB 的請求體上限(避免超大上傳打爆主機記憶體)。若貴校資料庫的 .dump 超過此上限,請改用下方「做法 2」的 volume 複製法把備份檔放回容器,再從系統介面「還原」。

做法 2:把 backups volume 同步到外部(可排程)

備份檔實際存在 volume backups。可用命令把整個備份目錄複製到主機檔案系統,再由你既有的異地備份機制(rsync、NAS 排程、雲端同步)接手:

# 把容器內 /backups 複製到主機當前目錄的 ./backups-export
      docker compose cp worker:/backups ./backups-export
      

反向(把外部備份檔放回系統以便還原):

docker compose cp ./某份.dump worker:/backups/
      

放回後即會出現在「備份清單」中,可直接還原。

---

四、手動用命令備份 / 還原(進階)

若你偏好在命令列操作(例如寫進自己的排程腳本):

# 備份(pg_dump 在 worker 容器內執行,worker 才裝了 postgresql-client)
      docker compose exec worker pg_dump -Fc -h postgres -U scheduler -d scheduler \
        -f /backups/manual_$(date +%Y%m%d_%H%M%S).dump
      
      # 還原(會覆蓋現有資料;跨版本可能出現可忽略的警告,資料仍正確)
      docker compose exec worker pg_restore --clean --if-exists --no-owner --no-privileges \
        -h postgres -U scheduler -d scheduler /backups/某份.dump
      

PGPASSWORD 於容器內已由 .env 提供,通常無需另外指定。透過系統介面操作會多做「還原前自動備份 + 強制重新登入」,命令列方式不會,請自行留意。

---

常見疑問

Q:備份含哪些資料? 全部業務資料(學期、教師、班級、課表、請假、代課、通知、稽核紀錄、系統設定與帳號)。不含 Redis(僅佇列與 session 時效,可重建)與上傳檔暫存。

Q:換一台新主機怎麼搬? 新主機照安裝指南裝好、起好空系統 → 系統管理上傳舊主機下載的 .dump 還原,即完成搬遷。

Q:備份會不會拖慢系統? pg_dump 對線上資料庫影響很小,且自動備份排在凌晨。手動備份亦為秒級(視資料量)。