バックアップと復元

インスタンスを使用したら、サーバーをアップグレードまたは移動する前にバックアップを作成します。初めてのクライアントのセットアップについては、以下で説明します。最初のリクエスト.

SubLane は、実行中のインスタンスをエクスポートし、バックアップを検証し、新しいディレクトリに復元できます。コマンドラインと システム設定 → バックアップと復元 同じアーカイブ検証と復元の実装を使用します。リカバリによって実行中のインスタンスが上書きされることはありません。復元されたデータへの切り替えは、オペレーターの明示的な再起動です。

含まれるもの

新しいバックアップはパスワードで暗号化されたバイナリ age ファイルです。復号後の gzip/tar には次が含まれます。

sublane.db: コミットされた WAL データを含む、一貫した SQLite スナップショット。
credentials.key: サブスクリプション資格情報と回復可能なゲートウェイキーに一致する暗号化キー。
manifest.json: フォーマットバージョン、作成時間、SubLane ビルドバージョン、スキーマバージョン、ファイルサイズ、SHA-256 チェックサム。

ユーザー、パスワードハッシュ、API キー、サブスクリプションアカウント、プール、権限、カタログ、設定、リクエストレコード、使用状況の概要、クールダウン、およびアフィニティレコードが含まれます。ブラウザセッションはバックアップにキャプチャされますが、復元されたディレクトリではクリアされます。ブラウザローカルのテーマ/言語の選択、プロセス環境、展開ファイル、およびメモリ内での保留中の試行 OAuth は含まれません。

新しいエクスポートには 12〜128 文字のパスワードが必要です。 SubLane は保存しません。バックアップと分けて保管してください。紛失すると暗号化バックアップを復元できません。従来の暗号化されていない .tar.gz はパスワードなしで検証・復元できますが、読み取り可能な鍵を含むため非公開で保管してください。

コマンドライン

データベーススナップショットと圧縮アーカイブ用に十分な空き領域があるディレクトリからコマンドを実行します。

Command line · 1

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
./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

backup 読む SUBLANE_DATA_DIR または ./data、オプションで --data-dir オーバーライド。 restore 常に明示的な新しいディレクトリが必要です。既存の空のディレクトリであっても拒否されます。親ディレクトリが存在する必要があります。既存のアーカイブファイルと復元ディレクトリは置き換えられません。コマンドが成功すると、操作、パス、およびバックアップのメタデータを含む JSON 結果が出力されます。 sublane --help にコマンドをリストします。

メンテナンスコマンドは、HTTP サーバー、SDK エグゼキュータ、OAuth、または自動リリースチェックを起動せず、サーバーアドレス/パブリック URL 設定に依存しません。彼らには 15 分の期限があり、SIGINT/SIGTERM に応答します。データベーススナップショットは 4 GiB に制限されており、アーカイブ IO は制限付きバッファを使用します。アーカイブ自体に加えて、検証または復元するときに、抽出および移行用のディスク領域を許可します。

復元が成功した後:

現在の SubLane サービスを停止します。
元のデータディレクトリをそのまま保持します。
復元されたディレクトリで SubLane を開始します。

Command line · 2

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

チームのトラフィックを再開する前に、もう一度サインインし、予想されるユーザー、プール、キー、アカウントの状態を確認してください。

SubLane を停止して切り替えることで、元のディレクトリをロールバックできます。 SUBLANE_DATA_DIR 戻る。同じデータディレクトリに対して 2 つのゲートウェイインスタンスを実行しないでください。復元すると、保存されているすべての状態がスナップショットにロールバックされます。その後のキーの取り消し、パスワードの変更、および新しいレコードは含まれません。サブスクリプションプロバイダーは、バックアップ以降の古い更新トークンを無効にした可能性があります。必要に応じて、影響を受けるアカウントを再認証します。検証では、プロバイダーに連絡せずに復号化とローカルの整合性をチェックします。

ウェブインターフェース

有効な管理者のみがページまたはそのエンドポイントを使用できます。ミューテーションには正確なブラウザーの起点が必要であり、エクスポートではファイルの準備後に管理者セッションが再チェックされます。

バックアップをダウンロードする インスタンスが利用可能な状態のまま、完全なアーカイブを作成してダウンロードします。
バックアップの検証 選択したファイルをチェックし、その作成時間、SubLane バージョン、データベースサイズを表示します。
復元の準備 ファイルを再度アップロードして検証してから、 <current data directory>/restore-ready。このページにはフルパスと再起動手順が表示されます。現在のインスタンスは、オペレーターがディレクトリを切り替えるまで、元のデータで実行を続けます。

既存の restore-ready パスが別の準備をブロックします。サーバー上で検査するか、別の新しいターゲットで CLI を使用してください。 Web 経由でディレクトリを上書きすることはできません API。リカバリデータが準備されていても、ライブ監査の書き込みが失敗した場合、ディレクトリは保持され、ページで監査の失敗が報告されます。再試行する前に検査してください。

Web でのアップロードとダウンロードは、圧縮データが 256 MiB に制限されています。より大きなバックアップには CLI が必要です。サーバーごとに一度に 1 つのエクスポート/検証/復元操作が実行されます。アップロード、処理、ダウンロードには期限があります。一時ファイルは、完了、失敗、または通常のキャンセル後に削除されます。強制的なプロセスの強制終了または電源喪失により、プライベートな状態が残る可能性があります。 .sublane-backup-* ディレクトリ;バックアップ操作が実行されていない場合にのみ、残ったステージングディレクトリを削除します。

エクスポートと準備されたリストアは、アーカイブの内容、ファイル名、ファイルシステムのパス、資格情報を記録せずに監査されます。ダウンロード使用 Cache-Control: no-store。ページは、選択したファイルからアップロードをストリーミングします。ブラウザーはダウンロードされたアーカイブを一時 BLOB として受け取り、ダウンロードの開始後にその URL を解放します。

ブラウザーのバックアップと復元のコントロールの例:

Backup page with download, archive verification and restore preparation

Docker Compose

実行中のコンテナ内でエクスポートして検証するには:

Docker Compose · 3

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 exec -T sublane sublane backup verify --password-stdin --input /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 · 4

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

Web 復元アクションでは同じターゲットが生成されます。これをアクティブにするには、ローカル Compose オーバーライドを作成します。たとえば、 docker.compose.restore.yaml:

Docker Compose · 5

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

次に、元のプロセスを停止し、オーバーライドを開始します。

Docker Compose · 6

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 ... の代わりに exec 指定されたデータボリュームに対してメンテナンスコマンドを実行します。選択したオーバーライドを後続のデプロイメントコマンドで保持します。この手順中に、名前付きボリュームを削除しないでください。

検証と失敗時の動作

検証では、正確なアーカイブエントリとサイズ、SHA-256 ダイジェスト、gzip の整合性、サポートされている統合スキーマバージョン、SQLite 整合性と外部キー、制限された資格情報レコード、アカウント資格情報と暗号化された API キーの復号化がチェックされます。検証接続では、個々の SQLite 値と SQL ステートメントも 1 MiB に制限されます。シンボリックリンク、パストラバーサル、重複/予期しないファイル、欠落ファイル、切り捨てられたアーカイブ、および不明な将来のスキーマは拒否されます。古い開発スキーマは、このプレリリースビルドでは受け入れられません。

復元は、アトミックな非置換操作で新しいディレクトリ全体を公開する前に、準備されたデータベース/キーを閉じて同期します。 Linux と macOS では、その操作のためのファイルシステムのサポートが必要です。サポートされていない操作は、上書きにフォールバックせずに失敗します。バックアップサポートにより、追加のデータベーステーブルやスキーマの移行は発生しません。 SQLite スナップショットの作成には、 SQLite オンラインバックアップ API ライブデータベースファイルをコピーするのではなく、固定された Go ドライバーを介して。

終点	目的
`GET /api/settings/backup`	Web サイズ制限と固定復元先の読み取り
`POST /api/settings/backup/export`	JSON `{password}` → `.age`
`POST /api/settings/backup/verify`	`multipart/form-data`: `password` + `file`
`POST /api/settings/backup/restore`	`multipart/form-data`: `password` + `file`

使用 application/gzip または application/octet-stream アップロード用。無効なアーカイブは 400 を返し、既存の宛先は 409 を返し、サイズ超過のアップロードは 413 を返し、占有された操作スロットは 429 を返します。 Retry-After。ストレージやその他の操作上の障害が発生すると、サニタイズされた 503 エラーが返されます。

credentials.key · バックアップのパスワード

既存のインスタンスは停止し、元の鍵をデータディレクトリ外の非公開の場所へコピーしてサービスユーザーの権限を設定してください。起動と暗号化バックアップの確認後に元のコピーを削除してください。

SUBLANE_CREDENTIALS_KEY_FILE: データディレクトリ外の任意の秘密鍵ファイル。未設定時は従来の保存先を使用.

鍵を別に保管する場合は、復元した credentials.key をデータディレクトリ外の新しい非公開の場所へ移し、再起動前に SUBLANE_CREDENTIALS_KEY_FILE を更新してください。元のインスタンスの鍵を上書きしないでください。

12〜128 文字を使用してください。パスワードは別に保管してください。紛失すると再設定できません。暗号化されたバックアップには必須です。従来の非暗号化アーカイブでは空欄にできます。

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

パスワードは権限 0600 の非公開の 1 行ファイルから --password-stdin で読み込みます。引数や環境変数には含めないでください。

画面は multipart/form-data で password、file の順に送信します。従来の生のアップロードもパスワードなしで使用できます。

Compose の鍵を自動移行する

アプリケーションのリポジトリには、既存の SubLane v0.12.0+ Compose 環境向けに scripts/separate-key.sh があります。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 はサービスを 2 スペースで字下げし、environment のブロックマッピングと volumes のブロックリストを使用してください。未対応の構成はサービス停止前に拒否されます。

プロジェクト、イメージ、データマウント、元の鍵の非公開権限、32 バイトのサイズとダイジェストを確認します。Compose のテキストと変数展開を維持し、正規化された設定を比較します。新しいホストディレクトリは root 所有の 0700 のままです。サービスの UID/GID が所有する 0600 の鍵ファイルだけをコンテナへ読み取り専用でマウントし、サービス権限は昇格しません。

切り替え前、切り替え後、古い鍵の削除後に、新しいランダムなパスワードで一時的な暗号化バックアップを作成・検証します。検証用の一時領域はデータディレクトリの外にあり、完了後に削除されます。十分なディスク容量とバックアップ 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、シンボリックリンク不可）に保存し、データとバックアップのディレクトリから分離してください。毎回読み直します。

Automatic backup deployment settings

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 を設定してください。