備份與復原

實例投入使用後，在升級或遷移伺服器前做好備份。首次連接客戶端請先看第一次使用。

備份內容與保存

新備份為以密碼加密的二進位 age 檔案。解密後的歸檔包含 sublane.db、配對的 credentials.key 和記錄版本、大小及 SHA-256 校驗和的 manifest.json。資料庫快照包含已提交的 WAL 資料，涵蓋使用者、金鑰、帳號、權限、設定、請求與用量。

新匯出必須使用 12–128 個字元的密碼。 SubLane 不保存密碼，請與備份分開保管；遺失後無法還原該加密備份。舊版未加密 .tar.gz 仍可不提供密碼進行校驗與還原，但包含可讀取的憑據金鑰，須存放於私人位置。

部署檔案、環境變數、瀏覽器本地偏好與尚未完成的 OAuth 嘗試不在歸檔中。恢復會清除瀏覽器會話，使用者必須重新登入。

命令列備份

在有足夠空間的目錄執行：

mkdir -p backups
./bin/sublane backup --password-stdin --output ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane backup verify --password-stdin --input ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password

預設讀取 SUBLANE_DATA_DIR 或 ./data，也可使用 --data-dir 指定。已有歸檔不會被覆蓋。 CLI 資料庫快照上限為 4 GiB，校驗和復原還需要解壓縮與遷移空間。維護指令不會啟動 HTTP 服務或供應商執行器。

復原流程

恢復目標必須是尚不存在的新目錄，即使已有空目錄也會被拒絕；父目錄必須存在。

./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

恢復成功不代表運行實例已切換。停止原服務、保留原目錄，再使用新目錄啟動：

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

重新登入並檢查成員、群組、金鑰與訂閱帳號，再恢復團隊流量。回滾時停止服務並切回原目錄，不要讓兩個程序同時使用相同資料庫。復原會回到快照時刻，之後的撤銷和密碼修改不再存在；上游可能已廢棄舊刷新令牌，必要時重新授權。

網頁操作

管理員進入「系統設定 → 備份與復原」。可在線上下載歸檔、上傳校驗，或「準備恢復」到目前資料目錄下的 restore-ready。準備完成後仍需維運人員停止服務並切換目錄。

網頁壓縮檔案上限 256 MiB，更大歸檔使用 CLI。同一實例一次只處理一個網頁維護作業。已有 restore-ready 會阻止再次準備，不會覆蓋。檢查目錄後再決定下一步，或用 CLI 指定其他新目錄。

網頁備份與復原作業介面範例：

Docker Compose

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec -T sublane sublane backup --password-stdin --output /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz.age ./team.sublane-backup.tar.gz.age

恢復歸檔放入容器可存取的私有目錄後執行：

docker compose -f docker.compose.yaml exec -T sublane sublane restore --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age --data-dir /data/restore-ready < /secure/backup-password

創建 docker.compose.restore.yaml：

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

後續部署保持使用覆蓋配置，勿刪除命名資料磁碟區。容器已停止時，可用 docker compose -f docker.compose.yaml run --rm --no-deps sublane ... 執行維護命令。

校驗邊界

校驗檢查歸檔條目、大小、摘要、gzip 完整性、受支援的合併結構版本、SQLite 完整性與外鍵，並驗證憑證解密。路徑穿越、符號連結、重複條目、缺少檔案及未知未來資料庫版本會被拒絕。目前預發布版本不接受舊開發結構；校驗不會修改運行中的資料庫，也不聯絡供應商驗證帳號。

credentials.key · 備份密碼

已有實例請先停止服務，將原金鑰複製到資料目錄外的私有位置並設定服務使用者權限；驗證啟動及加密備份成功後，再移除原位置的副本。

SUBLANE_CREDENTIALS_KEY_FILE: 資料目錄外的選用私有憑據金鑰檔案；未設定時保留原位置.

若使用獨立金鑰，請將還原的 credentials.key 移至資料目錄外的新私人位置，並在重新啟動前更新 SUBLANE_CREDENTIALS_KEY_FILE，不要覆蓋原實例的金鑰。

使用 12–128 個字元。請將密碼分開保存，遺失後無法重設。 加密備份必須輸入密碼；舊版未加密封存檔可留空。

--key-file FILE · --password-stdin · scrypt: 18 (~256 MiB)

請透過 --password-stdin 從權限 0600 的私人單行檔案讀取密碼，不要將密碼放入命令列參數或環境變數。

網頁使用 multipart/form-data，依序傳送 password 與 file；舊版原始歸檔上傳仍可不提供密碼。

自動遷移 Compose 金鑰

應用程式倉庫提供 scripts/separate-key.sh，適用於既有的 SubLane v0.12.0+ Compose 部署。請先將腳本儲存至 Docker 宿主機並審閱，執行前匯出並校驗一份以密碼加密的復原備份。

sudo bash scripts/separate-key.sh --dir /srv/sublane --key-dir /srv/sublane-secrets

--dir 指向包含 docker.compose.yaml 與選用 .env 的部署目錄。--key-dir 必須是父目錄已存在、目標尚不存在的絕對路徑，位於實際資料掛載與復原目錄之外，並使用持久化宿主機儲存；支援含空格的一般 ASCII 路徑。腳本需要本機 Linux rootful Docker（未啟用 userns 重新對應或 SELinux）、Compose、Bash、jq 與 GNU coreutils。現有健康服務必須命名為 sublane，資料目錄必須是可寫入的 bind 或具名磁碟區掛載根目錄；Compose 須使用兩空格服務縮排、environment 區塊映射與 volumes 區塊清單。不支援的配置會在停止服務前遭到拒絕。

腳本核對專案、映像檔、資料掛載、原金鑰的私有權限、32 位元組大小及摘要，保留 Compose 文字與變數插值，並比較 Compose 的標準化配置。新宿主目錄由 root 持有，權限為 0700；僅將其中權限 0600、歸服務 UID/GID 持有的金鑰檔案以唯讀方式掛載至容器。服務權限不會提高。

切換前、切換後及刪除舊金鑰後，都會以新的隨機密碼建立並校驗暫存加密備份。校驗暫存位於資料目錄之外，完成後移除；請預留足夠磁碟空間及備份 KDF 所需記憶體。這些檢查不會保留復原備份。只有新配置、健康檢查、金鑰摘要與憑據校驗都通過後，才刪除資料目錄中的舊副本，再次重建並校驗以確認不再依賴舊檔案。

開始切換後遇到可捕捉的錯誤或訊號，腳本會嘗試回復原狀。遷移成功後也可明確執行回復：

sudo bash scripts/separate-key.sh --dir /srv/sublane --rollback

私有復原記錄保留於 /srv/sublane/.key-migration。回復會還原原始配置及相符的金鑰，重建並校驗原服務；若配置、環境或金鑰有衝突，則拒絕覆寫，也不會降級映像檔或資料庫。回復後保留外部金鑰與復原記錄，後續遷移不會覆寫既有記錄或目標。重試前請妥善封存已校驗的復原記錄，並選用新的金鑰目錄。

腳本與安裝程式共用 .update-lock，請勿同時執行其他部署操作。強制終止或斷電後，先確認沒有遷移或更新程序，再僅移除遺留的空 .update-lock，然後執行 --rollback。若無法校驗回復結果，腳本會保留復原金鑰材料及私有 operation.log；完成復原前請保留復原目錄與外部金鑰目錄。自行保存的備份與密碼仍須分開保管。

自動加密備份

使用下列部署設定啟用排程備份。目標目錄須為私有目錄（0700），12–128 字元的獨立密碼須存於私有一般檔案（0600，不可為符號連結），並與資料和備份目錄分開保管。每次執行會重新讀取密碼。

export SUBLANE_BACKUP_DIR=/srv/sublane-backups
export SUBLANE_BACKUP_PASSWORD_FILE=/secure/sublane/backup-password
export SUBLANE_BACKUP_INTERVAL=24h
export SUBLANE_BACKUP_KEEP=7

啟動時執行一次，之後每次嘗試結束再等待設定間隔。完整驗證新封存後，才輪替預留的 scheduled- 檔案；手動封存和新驗證的封存會保留。結果記錄於服務日誌。首版不含遠端上傳或網頁排程表單；展示模式不執行備份。

SUBLANE_BACKUP_INTERVAL: 1h–720h (default 24h). SUBLANE_BACKUP_KEEP: 1–365 (default 7).

每個執行個體必須使用獨立的備份目錄。

可選設定 SUBLANE_BACKUP_WEBHOOK_URL 為公用 HTTPS 位址，每次備份失敗傳送一個有界的 backup_failure JSON 事件。這是獨立於工作空間通知的執行個體運維目的地；傳送失敗會記入日誌。

Docker 須使用容器內路徑，以本機 Compose 覆寫掛載私有密碼檔與可寫的獨立備份目錄，並授予服務使用者存取權。預設 /tmp tmpfs 為 64 MiB；較大封存的驗證須另掛載私有可寫暫存目錄，並設定 TMPDIR。