升級與備份

保持 ThirtyFile 更新，並把資料副本存放在安全位置。

升級

請先備份。檔案和設定會保留，新版本啟動時會更新資料庫。修改資料庫前，ThirtyFile 會將副本儲存到 data/backups/drive-before-<version>.db（保留最近三份）。

docker run

docker pull ghcr.io/thirtyfile/thirtyfile:latest
docker stop thirtyfile && docker rm thirtyfile
docker run -d --name thirtyfile --restart unless-stopped …   # the same options as when you installed it

Docker Compose

docker compose pull && docker compose up -d

版本頁面提供的 compose.yaml 跟隨對應版本系列，例如 ghcr.io/thirtyfile/thirtyfile:0.4，取得該系列的修復。升級到更新系列時，先閱讀版本說明，再修改 image: 的標籤（例如 :0.5），執行相同命令。

0.4.0 及以後的資料可以原地升級：在相同 data 和 storage 資料夾上啟動新版本即可。0.3 及以前不能升級，因為之後重新建立了資料庫結構；請用空的 data 和 storage 安裝新版本，再複製檔案。新版遇到 0.3 或更舊資料時，會在寫入任何 data 或 storage 內容前立即停止並記錄原因，保留舊資料原狀。資料庫被更新版本修改過時，也會停止並顯示明確訊息（參閱退回舊版本）。

會獲得哪個版本

ghcr.io/thirtyfile/thirtyfile 和 Docker Hub 的 thirtyfile/thirtyfile 提供相同的已驗證映像和版本標籤。切換倉庫時，只修改命令或 Compose 的映像名稱，保留版本標籤和磁碟區。GitHub 已簽名的來源證明仍附在 GHCR 映像；檢查 Docker Hub 副本時，用對應 digest 在 GHCR 驗證。

1.0.0 之前沒有主版本標籤；最接近的是 0.4，因為任何 0.x 版本都可能改變行為。每個版本的更改列在版本頁面，還提供 compose.yaml、Linux amd64 與 arm64 的獨立伺服器程式，以及 SHA256SUMS 中的 SHA-256 校驗碼。

每個發布映像附有內容清單（SBOM）和已簽名的建置紀錄。要驗證映像或程式確實由 ThirtyFile 官方發布流程建置，使用 GitHub CLI：

gh attestation verify oci://ghcr.io/thirtyfile/thirtyfile:1.2.3 --repo ThirtyFile/ThirtyFile
gh attestation verify thirtyfile-1.2.3-linux-amd64 --repo ThirtyFile/ThirtyFile

ThirtyFile 內部相依函式庫的授權條款位於映像的 /usr/share/licenses/thirtyfile/THIRD-PARTY-NOTICES，以及版本頁面的 THIRD-PARTY-NOTICES。

退回舊版本

舊版無法在新版已修改的資料庫上啟動。要退回舊版，先停止 ThirtyFile，用升級前的副本（data/backups/drive-before-<new version>.db）替換 data/drive.db，刪除存在的 drive.db-wal 和 drive.db-shm，再啟動舊映像。升級後的更改（新帳號、上傳的檔案及其名稱）會遺失；之後上傳的檔案仍在儲存資料夾，但不會出現在清單中。

備份

data 與 storage 合起來包含所有內容：檔案、帳號、設定和紀錄。storage/company、storage/teams 和 storage/users 內為一般檔案，任何備份工具都能複製並逐個還原；分享連結、權限、資源回收筒和歷史版本還需要資料庫。data 內的資料庫會持續寫入，所以執行時不要直接複製 drive.db，應使用備份命令取得副本，或停止 ThirtyFile 後複製。

不停止服務

1. 儲存一致的資料庫副本（不能覆蓋已有檔案，每次使用新名稱）：

   docker exec thirtyfile thirtyfile backup /data/backups/drive-$(date +%F).db

2. 複製 storage，以及排除 drive.db*、thumbs 和 tmp 的 data（縮圖會重新產生，tmp 僅包含進行中的上傳）：

   sudo tar czf thirtyfile-$(date +%F).tar.gz -C /srv/thirtyfile \
     --exclude='data/drive.db*' --exclude=data/secret.key --exclude=data/thumbs --exclude=data/tmp data storage

製作封存檔時上傳的檔案，可能只在封存檔中而不在已儲存資料庫中，或者相反；兩種情況下都可還原備份。要每晚執行，把兩個命令寫入腳本並加入 cron，例如 0 3 * * * /usr/local/bin/thirtyfile-backup.sh，同一腳本也刪除超過數週的封存檔。

停止 ThirtyFile 後備份

docker stop thirtyfile
sudo tar czf thirtyfile-backup.tar.gz -C /srv/thirtyfile data storage
docker start thirtyfile

使用 Docker Compose 時，在 compose.yaml 資料夾執行 docker compose stop 和 docker compose start，data storage 也以該處為相對路徑。

儲存位置檔案的副本

ThirtyFile 也能自行把儲存位置的檔案複製到另一位置：從控制台 › 儲存位置使用全部複製到…執行一次（參閱將全部內容複製到其他位置），或使用檔案備份反覆執行。鏡像在其他位置維護目前檔案，以便來源位置故障時繼續讀取；不保留歷史狀態，所以不能代替備份。這些都是檔案副本，不是整臺伺服器副本：不含帳號、設定、分享連結和紀錄，仍需按上文備份 data。

將檔案備份到其他位置

備份把某個儲存位置的空間快照儲存在另一位置：NAS、其他磁碟、S3 儲存桶、SFTP 或 FTP 伺服器。每個快照都是還原點，包含當時的空間、資料夾、檔案、資源回收筒和歷史版本。舊快照按指定期限保留，以便還原誤刪或誤改的檔案。只有管理員可檢視和管理備份。

建立備份

從控制台 › 備份選取新增備份…（或儲存位置選單中的備份…），然後：

• 備份和到：來源空間所在位置和備份目標。相同或互相包含的位置被拒絕。同一磁碟或服務的位置允許使用，但對話方塊會說明無法承受該磁碟或服務故障。一個位置可備份到多個目標，每個目標使用獨立備份。
• 空間：預設包含來來源位置全部空間及之後新增空間，也可只選擇勾選的空間。預設包含歷史版本和資源回收筒，除非取消勾選。
• 時間：
  • 更改後儘快備份：每次空間更改（上傳、編輯、重新命名、移動、刪除和權限修改）儲存後立即計入。連續數秒無新更改後建立快照。每次只執行一個快照，期間更改會在完成後觸發另一個。檔案在更改稍後才獲得保護，不是同步寫入；備份頁面顯示落後程度。
  • 依排程：每隔指定分鐘或小時、每天指定時間，或每週指定日期和時間，在所選時區執行（顯示接下來三次執行時間）。夏令時開始日不存在的時間不執行；結束日重複出現的時間只執行一次。伺服器停機後僅建立一次補償快照，不會為每個錯過時間分別建立。
  • 兩者都用（預設）：更改後儘快備份，同時按計劃執行。
• 保留與檢查：快照保留天數（預設 30）、始終保留的最新快照數（至少 1）、多久沒有新快照就通知管理員（48 小時）、讀回檢查頻率（每 7 天），以及複製速度上限（預設不限）。

第一個快照立即建立，複製全部內容；之後只複製備份尚未持有的內容（相同內容只儲存一次，不論被多少快照使用）。快照與複製、還原共用一次一項的背景工作，關閉頁面或伺服器重新啟動後仍會繼續。

快照包含什麼

• 內容儲存區空間（S3、SFTP、FTP）：精確反映產生檔案清單時的空間狀態。之後刪除的內容會暫緩刪除，直到快照複製完成。
• 資料夾空間（儲存資料夾、本機資料夾位置）：先檢查其他程式造成的更改（例如 SMB），逐個讀取檔案，並驗證讀取期間未發生變化，變化時重新讀取。其他程式持續寫入的檔案（紀錄、電子郵件信箱）不會阻止整個快照：嘗試數次後，保留最後一次完整讀取的內容，工作詳細資訊列為複製期間發生變化（從未完整讀取的檔案不進入該快照，也以相同方式列出；個人空間不顯示檔案名稱）。每個檔案都完整，但不代表其他程式在不同時間修改的全部檔案在同一瞬間的整體狀態。外部更改在下一次變更檢查發現，並非發生時立即發現。
• 只有完整快照才計入：所有內容複製並驗證後，最後寫入清單和完成標記。無法複製全部內容的快照會停止，列出失敗項目（個人空間不顯示檔案名稱），不刪除任何內容。
• 只含檔案，不含使用者為檔案留下的設定。快照包含空間的資料夾、檔案和先前版本。標籤、智慧型資料夾、收藏、分享連結、存取權限和活動則存在 ThirtyFile 的資料庫中：還原的項目不會帶回這些（存取權限沿用還原位置的設定）。要一併保留，請同時備份 data 資料夾（見備份）。

追蹤備份狀態

每個備份顯示狀態：已保護（最新快照包含全部更改）、更改等待中（及等待多久）、備份中、等待儲存位置（不可達；每隔幾分鐘重試，ThirtyFile 發現恢復時也立即重試）、失敗（最近快照因錯誤停止；每小時重試，或立即備份）、逾期（超過規則允許時間無新快照）、已暫停，以及空間保護截止時間。開始失敗、等待位置或逾期時，管理員收到一次通知（已設定時也發郵件）；恢復後再通知一次。詳細資訊顯示還原點、工作與錯誤。已完成工作保留 90 天，每個備份最多最新 1,000 項，最新 20 項不受時間限制；失敗工作保留至繼續或取消。

暫停備份停止建立快照，保留已有快照。刪除備份確認後停止備份，並刪除資料夾及全部快照；可暫停但不能取消。存有備份的位置，必須先刪除備份才能刪除位置。

占用多少空間

多個快照共用的內容只存一份，因此備份約佔空間原大小，加上保留期間修改或刪除的內容。每次新快照完成後，刪除超過規則期限的快照（始終保留指定最新數量），再刪除其他快照均未使用的內容。控制台 › 儲存用量顯示各位置備份占用量。

從備份還原

還原會先驗證已有內容再重複使用。內容儲存區中缺失或損壞的內容從已檢查的備份還原，並保護共用該內容的檔案。名稱衝突選項在每個檔案實際寫入時套用，包括讀取備份期間新出現的同名項目。

選擇備份並還原…，再選擇還原點和空間。公司與團隊空間可選資料夾或部分項目；個人空間僅能完整還原到原擁有者的個人空間，因為管理員看不到內容。

• 還原到新資料夾（預設）：放入獨立資料夾，名稱為目前語言的已還原 <空間> <日期>（對話方塊顯示，可修改），目標可選原空間或其他空間，不替換已有內容。
• 還原到原位置：直接放入空間。重複使用已有資料夾，重新建立缺失資料夾。開始前顯示目標已有內容的檔案數量，可選擇跳過、保留兩者（還原檔案加編號），或取代內容（目前內容保留為歷史版本）。
• 每個檔案還原時驗證 SHA-256。還原項目繼承目標權限，不重新授予備份記錄的存取權限。歷史版本保留在備份中。無法還原的檔案會列出原因。

伺服器本身遺失時

檔案備份不依賴建立它的伺服器：備份位置中各快照的清單記錄空間、資料夾、檔案和對應內容（.thirtyfile-backups/<id>/，參閱目錄結構）。舊伺服器與資料庫遺失後，在新伺服器還原：

1. 安裝 ThirtyFile，使用相同使用者名稱建立需要還原個人空間的帳號。
2. 使用相同設定將備份位置新增為儲存位置。原 .thirtyfile-location 檔案屬於舊伺服器，因此新伺服器會拒絕；確認原伺服器已不存在後，先刪除該檔案（在資料夾、儲存桶頂層或伺服器資料夾頂層）。
3. 在控制台 › 備份選取在位置上尋找備份…和該位置。找到的備份會列出並在背景檢查，之後可從完整快照還原。

這只會還原檔案，不會還原整台伺服器：帳號、群組、權限、分享連結、設定和紀錄來自 data 備份（參閱備份）；儲存位置和單一登入儲存的密碼需要 secret.key（參閱下方），否則必須重新輸入。請在 ThirtyFile 以外安全儲存備份位置的設定（金鑰、密碼），以便重新新增。定期演練：將某個資料夾還原到新資料夾，並檢查幾個檔案。

還原

1. 停止 ThirtyFile，在目錄原位置解壓封存檔：sudo tar xzf thirtyfile-backup.tar.gz -C /srv/thirtyfile（Docker Compose 在 compose.yaml 資料夾）。
2. 如果備份時未停止服務，把儲存的資料庫放回：將 data/backups/drive-<date>.db 複製到 data/drive.db，刪除 drive.db-wal 和 drive.db-shm。
3. 啟動備份時相同或更高版本的 ThirtyFile，登入並開啟幾個檔案，包括近期上傳的檔案。

資料庫也包含簽名登入工作階段與已解鎖分享連結的金鑰：同時還原 secret.key（參閱下方）時，使用者保持登入；沒有該金鑰時，所有人需重新登入，儲存位置和單一登入需重新輸入密碼。分享連結本身兩種情況下均保持有效。遷移到新伺服器也採用相同流程：在新伺服器安裝、還原備份，位址改變時修改網站網址。

定期在另一台電腦測試還原：備份是否可靠，取決於最近一次還原驗證。

資料庫大小

資料庫（data/drive.db）及近期寫入紀錄（drive.db-wal）在啟動和每日維護時歸還不再使用的空間：清空寫入紀錄；長時間讀取（例如備份產生檔案清單）結束後，紀錄不會持續大於 64 MB。新資料庫也歸還刪除內容（如舊紀錄）的空間，僅保留數 MB 供之後寫入。較舊版本建立的資料庫則保留空閒空間供自身重複使用；如需縮小並在之後自動歸還，停止 ThirtyFile，執行 docker compose run --rm thirtyfile compact（或 docker run --rm -v …same volumes… ghcr.io/thirtyfile/thirtyfile compact）。此操作重寫整個資料庫，需約等於資料庫大小的剩餘磁碟空間。

已儲存密碼的加密金鑰

儲存位置密碼與金鑰、單一登入 client secrets、兩步驟驗證金鑰，以及簽名工作階段和分享連結的金鑰，均加密存入資料庫。加密金鑰位於 data/secret.key（首次啟動建立），或 THIRTYFILE_SECRET_KEY、THIRTYFILE_SECRET_KEY_FILE 指定處。因此僅有資料庫副本無法取得這些秘密。

• 單獨備份金鑰，例如儲存到密碼管理器，並排除一般備份（如上方命令）。沒有金鑰仍可還原，但儲存位置和單一登入需重新輸入密碼，所有人必須重新登入。
• 要讓金鑰完全不放在資料目錄，先建立金鑰（openssl rand -hex 32），透過 THIRTYFILE_SECRET_KEY_FILE（Docker secret）或 THIRTYFILE_SECRET_KEY 提供。現有金鑰檔案內容也可採用相同方式。
• 更換金鑰（例如含金鑰的備份外洩）：停止 ThirtyFile，執行 docker compose run --rm thirtyfile rotate-secret-key（或 docker run --rm -v …same volumes… ghcr.io/thirtyfile/thirtyfile rotate-secret-key）。操作重新加密全部內容，並替換 secret.key。使用 THIRTYFILE_SECRET_KEY 時，該次執行透過 THIRTYFILE_NEW_SECRET_KEY 提供新金鑰，再將設定切換為新值。

安全儲存備份

備份包含檔案、帳號，以及帶有訪客 IP 位址的紀錄；包含 secret.key 時，也包含解密已儲存密碼所需的全部資訊。請像保護密碼一樣保護備份，僅放在管理員能存取的位置。