メインコンテンツまでスキップ

バックアップと復元

PlantPulse Studio は、バックアップスクリプト1つと復元スクリプト1つで全体の状態を管理します。 すべてのコマンドはインストールディレクトリ(/opt/kopens/plantpulse-studio-docker)で実行します。

何がバックアップされるか​

バックアップファイル1つ(dist/backup-<date>.tar.gz)に以下がすべて含まれます。

対象内容
PostgreSQL 全体ダンプユーザーアカウント · 会話履歴 · ウォッチャー · 通知の既読状態 · スキル · デプロイ履歴 · 監査ログ
ワークスペース(workspaces/)プロジェクトごとの実際のソースコード · チャット添付ファイル
ビルド成果物(builds/)デプロイされたアプリの各バージョン(ロールバックに必要)
状態ディレクトリ(state/)settings.json(環境設定) · 監査/使用量ログ · カスタムテンプレート · ブランディングロゴ

PostgreSQL のデータディレクトリ自体はアーカイブから除外されます — SQL ダンプで置き換えられるためです。

バックアップファイルは機密資料です

アーカイブ内には 全ユーザーのワークスペースが丸ごと 含まれ、以前のインストールから引き継いだ 場合、settings.json に API キーが残っている可能性があります。

  • スクリプトはバックアップファイルを 600(所有者のみ読み取り)、dist/ ディレクトリを 700 にします。
  • 外部メディア・他のサーバーへ移動する際もこの権限を維持してください。 (scp -p, rsync -a, tar -p など権限保持オプションを使用)
  • 社外へ持ち出す場合は別途暗号化を推奨します。

バックアップ実行​

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh
▶ PostgreSQL 덤프
▶ 파일 상태 아카이브(postgres 데이터 제외 — 덤프로 대체)
-rw------- 1 root root 78M ... dist/backup-20260728-031501.tar.gz
✅ 백업 완료 (보존 14개)
  • 成果物: dist/backup-<YYYYMMDD-HHMMSS>.tar.gz
  • 保存ポリシー: 最新14個のみ残し、古いファイルは自動削除されます(BACKUP_KEEP で調整可能)。
  • 外部 PostgreSQL に 到達できる必要があります。ダンプを取得するためです。
BACKUP_KEEP=30 bash bin/backup.sh     # 이번 실행부터 30개 보존
アップデートの直前は必ず手動バックアップ

イメージのアップグレードや設定の大幅変更の前に、bash bin/backup.sh を一度実行しておいてください。

自動バックアップのインストール(推奨)​

毎日午前3時30分にバックアップが実行されるよう cron をインストールします。root 権限が必要です。

sudo bash bin/install-backup-cron.sh
[backup-cron] 설치 완료 — 스케줄: '30 3 * * *', 보존 14개, 로그: dist/backup.log

時間・保存数を変更するには、

sudo BACKUP_CRON="0 4 * * *" BACKUP_KEEP=30 bash bin/install-backup-cron.sh

削除するには、

sudo bash bin/install-backup-cron.sh remove

動作確認はログで行います。

tail -50 /opt/kopens/plantpulse-studio-docker/dist/backup.log
ls -lh /opt/kopens/plantpulse-studio-docker/dist/backup-*.tar.gz

推奨運用サイクル​

周期作業
毎日自動バックアップ(cron) — 14日分保存
毎週最新バックアップ1つを 別のサーバー・メディアへコピー(権限維持)
毎月dist/ の容量とディスク空き容量を確認
四半期DRYRUN=1 復元リハーサル — 下記参照
アップグレード前手動バックアップ1回
バックアップは『復元できるか』を確認して初めてバックアップです

バックアップファイルが毎日蓄積されていても、実際に復元できるかは試してみるまでわかりません。 四半期ごとにリハーサルを実行してください。非破壊的なので、運用中に実行しても安全です。

復元リハーサル (非破壊)​

アーカイブ構造とデータベースへの到達性のみを検査し、何も変更しません。

DRYRUN=1 bash bin/restore.sh                 # 최신 백업 대상
DRYRUN=1 bash bin/restore.sh dist/backup-20260712-191858.tar.gz
▶ 아카이브 검증
  ppstudio.sql 12M · files.tar.gz 66M
▶ DRYRUN — DB 도달성만 확인
  ✅ DB 도달 OK
✅ DRYRUN 통과 — 실제 복구는 DRYRUN 없이 실행

復元の実行​

復元は破壊的です

現在のデータベース内容とデータディレクトリ全体を バックアップ時点の状態で上書きします。 復元後に作成されたプロジェクト・会話・デプロイは失われます。

cd /opt/kopens/plantpulse-studio-docker

bash bin/restore.sh                                    # 최신 백업으로 복구
bash bin/restore.sh dist/backup-20260712-191858.tar.gz # 특정 시점으로 복구

確認プロンプトに restore を入力すると進行します。

⚠ 현재 DB 와 /var/lib/pp-studio 파일 상태를 이 백업으로 덮어씁니다: dist/backup-...
계속하려면 'restore' 를 입력하세요:

スクリプトが実行する順序です。

  1. アーカイブ構造の検証(ダンプ・ファイルアーカイブの存在確認)
  2. 現在のファイル状態を dist/pre-restore-<date>.tar.gz へ自動退避
  3. スタック停止
  4. データディレクトリの復元 → データベースの復元
  5. スタック起動 → ヘルスチェック

自動化スクリプト内でプロンプトなしに実行するには、

FORCE=1 bash bin/restore.sh dist/backup-20260712-191858.tar.gz

復元直後にヘルスが上がらない場合​

bash bin/logs.sh          # 서버 로그 확인
bash bin/status.sh

元に戻すには、手順2で作成された退避データで再度復元します。ただし、退避データはファイル状態のみ を含みます(データベースは含まれません)。

bash bin/restore.sh dist/pre-restore-20260728-104233.tar.gz

他のサーバーへの移行​

  1. 新しいサーバーに 同じバージョン でスタックをインストールします(インストール または 閉域網インストール)。
  2. 既存サーバーの .env を新しいサーバーへコピーします(権限 600 を維持)。
  3. バックアップアーカイブを新しいサーバーの dist/ へコピーします(権限 600 を維持)。
  4. 復元を実行します。
cd /opt/kopens/plantpulse-studio-docker
DRYRUN=1 bash bin/restore.sh dist/backup-20260728-031501.tar.gz   # 먼저 리허설
bash bin/restore.sh dist/backup-20260728-031501.tar.gz
ドメインが変わる場合

移行後に接続アドレスが変わると、全ユーザーが ログアウト後に再ログイン を一度行う必要があります — ログインクッキーは発行時点のホスト専用のため、そのままにするとデータリクエストが 401 になります。 詳細は ドメインとリバースプロキシ を参照してください。

ディスク管理​

バックアップはワークスペースとビルド成果物を丸ごと含むため、プロジェクトが増えるほど大きくなります。

du -sh /opt/kopens/plantpulse-studio-docker/dist
du -sh /var/lib/pp-studio/*
df -h /var/lib/pp-studio
  • 保存数を減らすには、cron を BACKUP_KEEP の値と共に再インストールしてください。
  • デプロイ済みアプリの過去バージョンは、プロジェクトごとにデフォルトで最大10個まで保管され、超過分は自動整理されます (現在サービス中のバージョンは常に保持)。

関連ドキュメント​