Gadget 16：永続化設計

どこに何を置くべきか、コンテナ再作成や再起動でもデータを守る永続化設計

永続化設計

「コンテナを作り直しても、NAS を再起動しても、データが残る」ための設計です。

目的

  • 消えて困るデータを、消えない場所へ確実に置く
  • どこに何を置くかを共有可能な「配置表」にする

前提条件

  • データの所在の理解: .wrangler/ が最重要（05-logs-cheatsheet）
  • QNAP のボリューム / volume の概念

配置表（どこに何を置くか）

データ 置き場所 コンテナで消える？ 対応
永続データ（ワークスペース・Gadget） .wrangler/ Yes 名前付きボリュームへ
リポジトリ本体 cloudflare-os/ Yes clone で復元 or ボリューム
秘密情報 .dev.vars Yes 安全な場所（暗号化）に退避
バックアップ tarball /share, 外部 No 自前で保存（07）
ログ 任意 任意 外部保存推奨

手順

1. 名前付きボリュームを作る

docker volume create cfos_data
docker volume create cfos_repo

2. コンテナにマウントする

docker run -d --name cfos \
  -v cfos_data:/app/cfos/.wrangler \
  -v cfos_repo:/app/cfos \
  -p 8787:8787 \
  node:22 \
  bash -c "cd /app/cfos && pnpm run-local"
TipQNAP の Share フォルダを使う場合

docker run で -v /share/Container/cfos-data:/app/cfos/.wrangler のように 共有フォルダを直接マウントすると、NAS のスナップショットとも連携しやすくなります。

3. 再作成後に検証する

  • コンテナを停止 → 削除 → 再作成（同じボリューム指定）→ 起動
  • ワークスペース・Gadget が残っていることを確認（07 の検証）

よくある失敗

症状 原因 対処
再作成で全消え ボリューム未使用 .wrangler を必ずボリュームへ
マウント後の起動失敗 パス不一致 ボリューム → /app/cfos/.wrangler の対応を確認
東 $ に変な空フォルダ バインド先が誤り 絶対パスで明示
スナップショットが効かない 非共有フォルダに置いた 共有フォルダ or 外部へ

確認

次に読む