Seu Dev Notes

AFFiNE セルフホストのディレクトリ構成と運用の注意点(WSL2)

一言まとめ

docker compose のデータ(postgres / storage / config)は相対パスで運用ディレクトリにまとめ、自作ツールのコードは別ディレクトリ、認証情報は ~/.config/ に出す。UID/GID の不一致、vhdx の肥大、バックアップ先を WSL の外にすることが運用の要点。

作成 · 更新 · #affine#selfhost#docker#wsl2
目次 8 sections
  1. 01 配置の 3 原則
  2. 02 推奨構成(分離型)
  3. 03 .env の典型例
  4. 04 運用の注意点
  5. 05 バックアップの頻度と退避先
  6. 06 撤退を見据えた前提
  7. 07 関連
  8. 08 更新履歴

調査時点: 2026-05。AFFiNE の公式 docker compose を WSL2 上でセルフホストする前提。

AFFiNE は、文書・ホワイトボード・データベース形式の情報をまとめて扱えるオープンソースのワークスペースアプリ。セルフホストでは、そのサーバーを自分の環境で運用する。

配置の 3 原則#

  1. すべて WSL2 の Linux ファイルシステム(~/ 配下)に置く。/mnt/c/ は性能と inotify の問題で避ける。Windows から見るときは \\wsl$\<distro>\home\<user>\...
  2. 「データ」と「コード」を分ける。Postgres のデータや Blob はバックアップ対象で git 対象外、自作ラッパーは逆に git 管理。最初から物理的にディレクトリを分ける
  3. ホーム直下に押し込めず、~/services/(動かし続けるもの)と ~/dev/(書いて壊すもの)のように用途で 1 階層切る

推奨構成(分離型)#

~/services/affine/            # 運用領域
├── docker-compose.yml        # 公式リリースから取得
├── .env                      # ポート、DB 認証情報
├── postgres/                 # PG 永続データ(バックアップ対象、gitignore)
├── storage/                  # Blob(バックアップ対象、gitignore)
├── config/                   # config.json(秘密値は .env で注入)
├── backups/
│   ├── postgres/
│   └── storage/
└── scripts/
    ├── backup.sh
    ├── restore.sh
    └── upgrade.sh


~/dev/<affine-tools>/         # 自作ツール(git リポジトリ)
~/.config/<affine-tools>/     # 認証情報(chmod 600)
└── credentials.json
  • .env の DB_DATA_LOCATION / UPLOAD_LOCATION / CONFIG_LOCATION を ./postgres / ./storage / ./config の相対パスにしておくと、ディレクトリごと別マシンに移しても同じ構成で動く
  • scripts/ は最初に空ファイルでも作っておく。backup / restore / upgrade は遅かれ早かれ要る
  • 認証情報を ~/.config/ に出すのは XDG Base Directory に従うためで、コードを公開リポジトリに上げたときの事故を防ぐ

統合型(~/affine/{server,tools})でも動くが、tools/ を git 管理すると server/ を丸ごと .gitignore することになり見通しが悪い。

.env の典型例#

Terminal window
PORT=3010                       # WSL2 内なので Windows から localhost で届く


DB_DATA_LOCATION=./postgres
UPLOAD_LOCATION=./storage
CONFIG_LOCATION=./config


DB_USERNAME=affine
DB_PASSWORD=<pwgen などで生成した強パスワード>
DB_DATABASE=affine


AFFINE_SERVER_HOST=localhost
AFFINE_SERVER_HTTPS=false

運用の注意点#

論点対処
所有権(UID/GID)コンテナが root で書き出すとホスト側のファイルが root 所有になり、シェルから削除できなくなる。ホストの uid/gid をコンテナに渡すか、sudo chown -R $USER:$USER ~/services/affine/postgres で戻す
ディスクext4.vhdx が SSD 上にあるか確認。vhdx は自動で縮まないので Blob の肥大前に削除方針を決める
/srv/ /opt/複数ユーザー・システムワイド向けの場所。WSL2 の単一ユーザー環境では ~/ 配下でよく、sudo が要る場面が増えるだけ
バックアップ先backups/ は一時置き場。cron で Windows 側のクラウド同期フォルダへコピーするか rclone で外部へ。WSL2 のディスクが死ぬと一緒に消える
git 管理運用側も管理したいなら docker-compose.yml と scripts/ だけを別リポジトリにし、データディレクトリは厳格に gitignore

バックアップの頻度と退避先#

対象頻度退避先
Postgres(DB ダンプ)日次backups/postgres/ + 外部
storage(Blob)週次backups/storage/ + 外部
自作ツール都度 git pushprivate リモート
~/.config/*/ の認証情報月次、暗号化アーカイブ別マシンや安全な外部媒体

定期実行の方式(WSL 内 cron か Windows タスクスケジューラか)とメモリ割当は WSL2 で常駐サービスを動かす設定 を参照。

撤退を見据えた前提#

AFFiNE 内に閉じた情報を作らない運用にしておくと、やめるときの被害が小さい。DB ダンプと storage を保持しておけば後日の復元も可能。Edgeless の空間配置(座標・矢印)や Database のビュー定義(カンバン列・フィルタ)、双方向リンクの参照側はエクスポートで失われる点は織り込んでおく。考え方は Obsidian と AFFiNE の併用設計 にまとめた。

関連#

更新履歴#

  • 2026-05-10: 初版(ローカル調査ノート)
  • 2026-10-17: Wiki へ移植、概念ページとして再構成。冒頭に定義を追加

同じトピック — ツール