ドキュメント

このドキュメントは、NAS、家庭用サーバー、個人の PC で Wanmory をセルフホストする管理者向けです。インストール、設定、AI サービスの導入、日常の使い方、システム設定、運用までを扱います。システム構成とアルゴリズムの詳細はアーキテクチャをご覧ください。

Wanmory はオープンソースでセルフホスト型のプライベート AI フォトライブラリです。システムは 4 つのコンテナで構成されます：Go バックエンド（server）、Python の AI 推論サービス（ml）、PostgreSQL + pgvector データベース（postgres）、そして LAN ドメインを告知する mdns。写真、メタデータ、ベクトル、ジョブキューはすべてローカルに保存され、クラウドサービスには一切依存しません。

• 写真管理：月ごとにまとめたタイムライン、アルバムとスマートアルバム、連写・類似写真の整理、旅の地図、スライドショー。
• AI 機能：顔の検出とクラスタリング、自然言語検索（Chinese-CLIP）、文字認識（PP-OCR）、美的スコア（AI ピックアップ）。
• 複数メンバー：個別のアカウント、所有者に基づく削除権限、ログイン履歴。

方法 1：インストールスクリプト（推奨）

Docker をインストール済みの 64 ビットマシンで実行します：

curl -fsSL https://wanmory.com/install.sh | bash

スクリプトは次の作業を順に行います：

• 環境チェック：CPU アーキテクチャ（amd64 / arm64）と 64 ビットのユーザー空間、Docker と Docker Compose v2 が使えるか、メモリとディスクの空き容量。
• 対話式の設定：インストール先（初期値 ~/wanmory）、アクセス用ポート（初期値 8080、使用中かを自動確認）、LAN ドメイン（初期値 wanmory.local）、データベースのパスワード（初期値はランダム生成）と保存場所（初期値は Docker ボリューム pgdata、ローカルディスク上のディレクトリも指定可）、タイムゾーン（都市名や地域名を入力して検索。shanghai、tokyo、北京 など。複数一致したら番号で選択）。
• 保存場所：データディレクトリ（サムネイル、プレビュー、アップロードした写真。初期値 ./data）、AI モデルディレクトリ（初期値 ./models）。
• スクリプトの案内と出力は英語です。さまざまな NAS の端末で正しく表示できるようにするためです。
• 既存の写真フォルダー：複数のフォルダーを 1 つずつ追加でき、フォルダーごとに読み取り専用（推奨）か読み書き可能なマウントかを選べます。
• .env（パーミッション 600）を作成します。写真フォルダーを指定した場合は docker-compose.override.yml も作成し、Docker Compose がこれを自動でマージします。
• 公式の docker-compose.yml をダウンロードし（GitHub に接続できない場合は自動で Gitee を使用）、設定を検証してからイメージを取得・起動し、サービスの準備が整うとアクセス先を表示します。

# 例：/opt/wanmory に非対話でインストールし、ポート 9000 を使い、NAS の写真フォルダーをマウント
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

方法 2：手動インストール

1. 1
   導入用ディレクトリを作成し、Compose ファイルを取得

   Compose ファイル、データ、モデルを置くディレクトリを作成し、公式の docker-compose.yml をダウンロードします：

   bashコピー

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   （任意）.env を作成

   同じディレクトリに .env を作成して初期値を上書きします。本番環境では必ずデータベースのパスワードを変更してください：

   .envコピー

   WANMORY_DB_PASSWORD=ランダムな文字列に置き換えてください
   WANMORY_PORT=8080
   WANMORY_TZ=Asia/Tokyo
   WANMORY_VERSION=latest

3. 3
   サービスを起動

   初回起動時はイメージを取得し、データベースのマイグレーションを自動で実行します：

   bashコピー

   docker compose up -d
   docker compose ps        # 4 つのサービスがすべて running / healthy であることを確認

4. 4
   アクセスして初期設定

   ブラウザで http://wanmory.local:8080（または http://<ホストの IP>:8080）を開き、案内に従って管理者アカウントを作成し、「システム設定 → AI 設定」でモデルをダウンロードします。モデルのダウンロードが終わると、既存の写真は自動で AI 処理キューに入ります。

公式の Compose ファイルには 4 つのサービスが定義されています：データベース postgres、アプリのバックエンド server、LAN ドメインを告知する mdns、内蔵 AI サービス ml。各設定項目の役割はファイル内に直接記載しています：

# Wanmory 公式 Compose ファイル：このファイルのあるディレクトリで docker compose up -d を実行
# ${VAR:-初期値} 形式の変数は同じディレクトリの .env から読み込み、未設定なら初期値を使う
services:
  # ── データベース：PostgreSQL 17 + pgvector ───────────────────────
  # 写真のメタデータ、人物、アルバム、設定、ジョブキュー、ベクトル（HNSW 索引）を保存
  # ポートは公開せず、Compose の内部ネットワークからのみ到達可能
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # 本番環境では必ず .env で変更すること
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # 初期値は名前付きボリューム pgdata、WANMORY_DB_DIR を設定するとそのディレクトリに保存。バックアップ対象
    healthcheck:                             # server はこのヘルスチェックを待ち、DB の準備ができてから起動する
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── アプリのバックエンド：Web アプリを内蔵した Go バイナリ ───────
  # API、アップロード（tus）、ジョブスケジューリング、サムネイル、権限を担当。起動時に DB マイグレーションを自動実行
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # 内蔵 AI サービスのアドレス。リモート AI サービスは Web の「AI 設定」で指定
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # EXIF にタイムゾーンがない場合に使うタイムゾーン
      WANMORY_MDNS: "off"                    # このコンテナはブリッジネットワークでマルチキャストを受信できないため、告知は下の mdns サービスに任せる
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # Web 上に表示するアクセス用ポート。ポートの割り当てと揃えること
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # LAN ドメインの初期値。Web の設定で変更した後はそちらが優先
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # ホストのポート:コンテナのポート
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ にアップロードした原本、thumbs/ にサムネイルと 1440px プレビュー
      # 既存の写真フォルダーは /photos 配下のサブディレクトリにマウント（複数可）。:ro は読み取り専用、15 分ごとにスキャン
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/camera:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── LAN ドメインの告知（mDNS）────────────────────────────────────
  # server と同じイメージで mdns サブコマンドだけを実行し、wanmory.local を告知（Web で変更可）
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # LAN のマルチキャストを送受信するにはホストネットワークが必須
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # 定期的に server へ現在のドメインを問い合わせる
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # 問い合わせできない間はこのドメインを告知
    depends_on:
      - server
    restart: unless-stopped
  # ── 内蔵 AI サービス：FastAPI + ONNX Runtime、CPU のみ ──────────
  # ステートレス。server から送られたプレビューを受け取り、顔・ベクトル・文字を返す。ポートは公開しない
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # モデルファイルを永続化し、コンテナを作り直しても再ダウンロード不要
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # 自動ダウンロードはせず、管理者が Web でライセンスとディスク使用量を確認してからダウンロード
    restart: unless-stopped
volumes:
  pgdata:

.env（Compose の変数）

次の変数は docker-compose.yml から参照されます。同じディレクトリの .env に書けば反映されます：

server コンテナ（任意）

DATABASE_URL、WANMORY_ML_URL、WANMORY_MDNS、WANMORY_HTTP_PUBLIC_PORT は Compose ファイルで設定済みで、用途も記載しています。次の変数は既定の Compose ファイルには含まれていないため、必要に応じて server の environment に追加します：

NAS や外付けドライブにすでにある写真は、アップロードし直す必要はありません。フォルダーをコンテナ内の /photos 配下のサブディレクトリにマウントすれば、15 分ごとにスキャンされ、新しいファイルはその場で取り込まれ（コピーも移動もしません）、その後はアップロードした写真と同じようにメタデータの読み込み、サムネイル生成、AI 処理が行われます。

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro は読み取り専用マウント
      - /media/usb/camera:/photos/usb:ro
      - /home/me/Pictures:/photos/pictures    # 読み書き可能なマウント

変更後に docker compose up -d を実行すると、コンテナの再起動から約 20 秒後に最初のスキャンが始まります。

• 読み取り専用マウント（:ro）を推奨：システムはこれらのフォルダーに書き込みません。アプリで写真を削除しても「最近削除」に移るだけで、完全に削除しても原本ファイルは消えず、その後のスキャンで再び取り込まれることもありません。読み書き可能なフォルダーでは、完全に削除すると原本ファイルも削除されます。
• 内容がまったく同じファイルは 1 つだけ取り込みます（SHA-1 チェックサムで判定）。すでにアップロード済みのファイルや、複数のフォルダー間の重複も含みます。
• 隠しフォルダーや NAS のシステムフォルダー（.xxx、@eaDir、#recycle など）は自動でスキップします。
• 写真フォルダーから取り込んだ写真はどのメンバーにも属さず、削除できるのは管理者だけです。

mdns サービスはホストネットワークモードで動作し、LAN 内にアクセス用ドメイン（初期値 wanmory.local）を告知します。macOS、iOS、iPadOS、Windows 10 以降なら、ルーターの設定なしで http://wanmory.local:8080 にアクセスできます。ドメインは「システム設定 → アクセス用ドメイン」で変更でき、.local で終わる必要があります。

Web アップロードは再開可能な tus プロトコル（/api/uploads/）を使い、チャンクサイズは 16 MB です。リバースプロキシの背後に置く場合は、1 リクエストあたりのボディサイズ制限を緩め、リクエストのバッファリングを無効にする必要があります。Nginx の例：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # リクエストボディのサイズを制限しない（最低でも 20m）
    proxy_request_buffering off;     # ストリーミングで転送し、プロキシ側のディスクに書き出さない
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

AI サービスはステートレスな HTTP サービスです。バックエンドから送られる 1440 ピクセルのプレビューを受け取り、顔、ベクトル、文字認識の結果を返します。データベースにはアクセスせず、ファイルも保存しません。バックエンドは 2 つの実行方式に対応しており、「システム設定 → AI 設定 → AI の実行方式」で切り替えます：

AI サービスが使えないときは、AI ジョブはキューに残ったまま取得が止まり、再試行回数は消費されません。サービスが復旧すると自動で再開します。写真の閲覧やアップロードなどの機能には影響しません。

方法 1：Mac または GPU マシンで直接実行（推奨）

直接実行するとハードウェアアクセラレーションが使えます。Apple シリコンでは顔認識モデルが CoreML、Chinese-CLIP が MPS を使い、NVIDIA GPU では Chinese-CLIP が CUDA を使って半精度で動作します（VRAM / メモリ約 1.9 GB）。事前に uv をインストールしてください。

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # PyTorch 版の依存関係をインストール（GPU でセマンティック検索を高速化）
# アクセストークンを生成。バックエンドと AI サービスで同じ値を使う
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# 既定では 0.0.0.0:3003 で待ち受け。WANMORY_ML_HOST / WANMORY_ML_PORT で変更可

方法 2：別のマシンで Docker イメージを実行

性能は高いものの使える GPU がない x86 マシン向けです。イメージは CPU のみを使います：

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<アクセストークン> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

バックエンドでリモートサービスを有効にする

1. 1
   AI 設定を開く

   管理者として「システム設定 → AI 設定 → AI の実行方式」を開き、「リモートサービス」を選びます。

2. 2
   アドレスとトークンを入力

   アドレスは http://192.168.1.20:3003 のような形式で、トークンには前の手順で生成した値を入力します。保存前に接続テストが行われ、遅延とサービスのバージョンが表示されます。

3. 3
   ティアとモデルを確認

   接続に成功すると、ティアが「自動」の場合はリモートマシンのハードウェアに基づいて推奨し直されます。「モデルティア」で必要なモデルをダウンロードします。

ティアによって、顔認識とセマンティック検索に使うモデルの組み合わせが決まります。「自動」を選ぶと、AI サービスが動くマシンのハードウェアから推奨します。使える GPU があれば「高精度」、CPU のみでメモリが 6 GB 未満なら「軽量」、それ以外は「バランス」です。

• 文字認識には PP-OCRv6（RapidOCR）を使います。モデルは依存関係と一緒にインストールされるため、個別のダウンロードは不要です。
• ティアを切り替えると、すべての写真について新しいモデルで顔を検出し直し、セマンティックベクトルを再計算します。その間も検索は古いベクトルで動き、名前を付けた人物は保持されます。
• モデルはマウントした ./models ディレクトリにダウンロードされ、使わなくなったモデルを削除して容量を空けられます（使用中のモデルは削除できません）。
• InsightFace の顔認識モデルは非商用利用に限られます。商用で使う前に、別のモデルに置き換えるかライセンスを取得してください。

1. 1
   管理者を作成

   初回アクセス時にアカウントがまだないことを検出し、管理者の作成を案内します。管理者はメンバーの追加やシステム設定の変更ができます。

2. 2
   モデルをダウンロード

   「システム設定 → AI 設定」でモデルティアを確認し、モデルをダウンロードします。モデルの準備ができるまで、AI ジョブはキューで待機します。

3. 3
   写真を取り込む

   Web からアップロードするか、既存の写真フォルダーのマウントの手順で NAS の写真を接続します。

4. 4
   メンバーを追加

   「システム設定 → メンバー」でほかの利用者のアカウントを作成し、「メンバー」か「管理者」のロールを選びます。

• Web アップロードは写真、動画、HEIC、RAW（DNG など）などの形式に対応し、複数選択も可能です。tus プロトコルで分割アップロードするため、回線が切れたりページを再読み込みしたりしても続きから再開できます。
• アップロードしたファイルはアップロード先ディレクトリ（初期値 data/upload）に年月ごとに保存されます。ディレクトリは「システム設定 → アップロード先」で変更でき、新しくアップロードするファイルにのみ適用されます。
• 取り込み後は次の順に処理されます：メタデータの読み込み（ExifTool）→ サムネイルと 1440 ピクセルのプレビューの生成（libvips / FFmpeg）→ セマンティックベクトル、顔、文字の認識（AI サービス）→ 逆ジオコーディング。
• サイドバー上部のバックグラウンドタスク表示で、「写真の取り込み」と「AI による写真の認識」の進捗と残り時間の目安を写真の枚数単位で確認できます。

人物の情報（名前、統合関係）は全メンバーで共有されます。写真の枚数、人物のカバー写真、人物ページは各メンバーが見られる写真だけで計算され、非表示の写真は本人にしか見えません。

• メンバー：追加時に名前、初期パスワード（4 文字以上）、ロールを設定します。メンバーのパスワードのリセットやメンバーの削除もできます。
• ログイン履歴：ログインごとの日時、デバイス、IP を記録し、位置は IP からオフラインで推定します（ip2region）。直近半年分を保存し、閲覧できるのは管理者だけです。
• 「マイアカウント」では、各メンバーが自分のパスワードとアバターを変更し、現在ログインしているデバイスを確認できます。

カードの上部には AI の現在の状態（実行可能か、一時停止の理由）がリアルタイムに表示されます。変更はすぐに反映され、再起動は不要です。

「システム設定 → システム更新」には、バックエンドと AI サービスの現在のバージョンが表示され、新しいバージョンがあれば通知されます。更新するには docker-compose.yml のあるディレクトリで次を実行します：

docker compose pull && docker compose up -d

データベースのマイグレーションは server の起動時に自動で実行されます。WANMORY_VERSION でバージョンを固定している場合は、先に .env のタグを変更してください。

バックアップが必要なデータは 3 種類です：

# データベースをエクスポート
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# 新しい環境に復元（先に docker compose up -d postgres を実行）
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

メンバーがパスワードを忘れた場合は、管理者が「システム設定 → メンバー」でリセットします。管理者自身がパスワードを忘れた場合は、アプリを動かしているホスト上で、docker-compose.yml のあるディレクトリで次を実行します：

docker compose exec server wanmory reset-password            # アカウントを一覧表示して選択
docker compose exec server wanmory reset-password <名前>     # アカウントを直接指定

• コマンドはすべてのアカウント（名前、ロール、作成日時、最終ログイン）を一覧表示します。番号で選び、新しいパスワードを 2 回入力します。
• リセット後、そのアカウントはすべてのデバイスでログアウトされます。写真とアルバムには影響しません。
• この操作はホスト上でのみ実行でき、Web には入口がありません。Docker を使っていない場合は、実行時と同じ DATABASE_URL などの環境変数を付けて wanmory reset-password を実行します。

各サービスのログは docker compose logs -f server、docker compose logs -f ml で確認できます。それでも解決しない場合は、バージョン番号と関連するログを添えて問題を報告ページからお知らせください。

Wanmory を動かしているホストでアンインストールスクリプトを実行します：

curl -fsSL https://wanmory.com/uninstall.sh | bash

スクリプトはまずインストール先の .env を読み込み、コンテナ、データベース、データディレクトリ、AI モデルとその使用容量、マウントしている写真フォルダーを一覧表示します。続いてコンテナとネットワークを停止・削除し、各項目について削除するかを 1 つずつ確認します（すべて初期値は残す）：

• マウントしている既存の写真フォルダー（NAS、外付けドライブ）は決して削除しません。
• データベースまたはデータディレクトリの削除を選ぶと、確認のため DELETE の入力を求められます。
• コンテナだけを削除してデータを残した場合は、同じディレクトリで install.sh を再実行すればすべて元どおりになります。.env を削除してデータベースを残す場合は、先に中の WANMORY_DB_PASSWORD を控えておいてください。