部署與文件

本文件面向在 NAS、家用伺服器或個人電腦上自架萬象 Wanmory 的管理員，覆蓋安裝、設定、AI 服務部署、日常使用、系統設定和維運。系統架構與演算法細節見功能架構。

萬象 Wanmory 是一個開源、自架的私有 AI 相簿。系統由四個容器組成：Go 後端（server）、Python AI 推論服務（ml）、PostgreSQL + pgvector 資料庫（postgres），以及負責區域網路網域廣播的 mdns。所有照片、後設資料、向量和任務佇列均儲存在本地，不依賴任何雲端服務。

• 照片管理：按月份分組的時間線、相簿與智慧相簿、連拍和相似照片整理、足跡地圖、幻燈片。
• AI 能力：人臉檢測與分群、中文自然語言搜尋（Chinese-CLIP）、文字辨識（PP-OCR）、美學評分（AI 精選）。
• 多成員：獨立帳號、基於所有權的刪除權限、登入日誌。

方式一：安裝腳本（推薦）

在已安裝 Docker 的 64 位元主機上執行：

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

腳本依次完成以下工作：

• 環境檢查：CPU 架構（amd64 / arm64）與 64 位元使用者空間、Docker 與 Docker Compose v2 是否可用、記憶體與磁碟餘量。
• 互動式設定：安裝目錄（預設 ~/wanmory）、存取連接埠（預設 8080，自動檢測佔用）、區域網路連線網域（預設 wanmory.local）、資料庫密碼（預設隨機生成）及資料庫位置（預設 Docker 磁碟區 pgdata，也可指定本機磁碟上的目錄）、時區（輸入城市或地區名即可檢索，如 shanghai、tokyo、北京，多個匹配時按編號選擇）。
• 儲存位置：資料目錄（縮圖、預覽圖與上傳照片，預設 ./data）、AI 模型目錄（預設 ./models）。
• 腳本的提示與輸出為英文，便於在各類 NAS 終端中正常顯示。
• 已有照片目錄：可逐個新增多個目錄，每個目錄單獨選擇只讀（推薦）或可讀寫掛載。
• 生成 .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

方式二：手動安裝

1. 1
   建立部署目錄並獲取編排檔案

   新增一個目錄用於存放編排檔案、資料和模型，下載官方的 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/Shanghai
   WANMORY_VERSION=latest

3. 3
   啟動服務

   首次啟動會拉取映像並自動執行資料庫遷移：

   bash複製

   docker compose up -d
   docker compose ps        # 確認四個服務均為 running / healthy

4. 4
   存取並初始化

   瀏覽器開啟 http://wanmory.local:8080（或 http://<主機 IP>:8080），按提示建立管理員帳號，然後在「系統設定 → AI 設定」下載模型。模型下載完成後，已有照片會自動進入 AI 處理佇列。

官方編排檔案定義了四個服務：資料庫 postgres、相簿後端 server、區域網路網域廣播 mdns 和內建 AI 服務 ml。各設定項的作用直接標註在檔案中：

# 萬象 Wanmory 官方編排檔案：在本檔案所在目錄執行 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 依賴此健康檢查，資料庫就緒後才啟動
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── 相簿後端：Go 程式，內嵌網頁 ─────────────────────────────────
  # 負責 API、上傳（tus）、任務排程、縮圖、權限；啟動時自動執行資料庫遷移
  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 服務在網頁「AI 設定」中設定
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # EXIF 缺少時區時使用的時區
      WANMORY_MDNS: "off"                    # 本容器在橋接網路收不到組播，網域廣播交給下方 mdns 服務
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # 網頁上展示的存取連接埠，與連接埠對映保持一致
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # 區域網路連線網域的初始值，網頁設定中修改後以設定為準
    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/相機照片:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── 區域網路網域廣播（mDNS）──────────────────────────────────────
  # 與 server 同一映像，只執行 mdns 子指令，廣播 wanmory.local（網頁中可修改）
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # 必須使用主機網路才能收發區域網路組播
    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"             # 不自動下載，由管理員在網頁中確認授權與磁碟佔用後下載
    restart: unless-stopped
volumes:
  pgdata:

.env（Compose 變數）

以下變數在 docker-compose.yml 中被引用，寫入同目錄的 .env 即可生效：

server 容器（可選）

DATABASE_URL、WANMORY_ML_URL、WANMORY_MDNS、WANMORY_HTTP_PUBLIC_PORT 已在編排檔案中設定並註明用途。以下變數不在預設編排檔案中，按需新增到 server 的 environment：

NAS、行動硬碟上已有的照片無需上傳。將目錄掛載到容器內 /photos 下的子目錄，系統每 15 分鐘掃描一次，對新增檔案進行原地匯入（不復制、不移動），隨後與上傳的照片一樣執行後設資料讀取、縮圖生成和 AI 處理。

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro 只讀掛載
      - /media/usb/相機照片:/photos/usb:ro
      - /home/me/Pictures:/photos/pictures    # 可讀寫掛載

修改後執行 docker compose up -d，容器重啟約 20 秒後開始首次掃描。

• 推薦只讀掛載（:ro）：系統不會寫入這些目錄；在相簿中刪除照片僅移入「最近刪除」，永久刪除也不會刪除原檔案，且此後不會再被掃描匯入。可讀寫掛載的目錄，永久刪除會同時刪除原檔案。
• 內容完全相同的檔案只匯入一份（按 SHA-1 校驗和判重），包括已上傳過的檔案和多個目錄間的重複檔案。
• 自動跳過隱藏目錄及 NAS 系統目錄（.xxx、@eaDir、#recycle 等）。
• 從照片目錄匯入的照片不歸屬任何成員，僅管理員可以刪除。

mdns 服務以 host 網路模式執行，在區域網路內廣播連線網域（預設 wanmory.local）。macOS、iOS、iPadOS 和 Windows 10 及以上版本無需設定路由器即可透過 http://wanmory.local:8080 存取。網域可在「系統設定 → 連線網域」中修改，必須以 .local 結尾。

網頁上傳採用 tus 可續傳協議（/api/uploads/），分片大小 16 MB。部署在反向代理之後時，需放開單個請求體大小限制，並關閉請求緩衝。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 像素預覽圖，返回人臉、向量與文字辨識結果，不存取資料庫，也不儲存檔案。後端支援兩種執行方式，在「系統設定 → AI 設定 → AI 執行方式」中切換：

AI 服務不可用時，AI 任務會保留在佇列中並暫停領取，不消耗重試次數；服務恢復後自動繼續。照片瀏覽、上傳等功能不受影響。

方式一：在 Mac 或 GPU 主機上直接執行（推薦）

直接執行可使用硬體加速：Apple 晶片上人臉模型使用 CoreML、Chinese-CLIP 使用 MPS；NVIDIA 顯示卡上 Chinese-CLIP 使用 CUDA，並以半精度執行（約 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 修改

方式二：在另一台主機上執行 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
   匯入照片

   透過網頁上傳，或按掛載已有照片目錄接入 NAS 中的照片。

4. 4
   新增成員

   在「系統設定 → 成員」中為其他使用者建立帳號，選擇「成員」或「管理員」角色。

• 網頁上傳支援照片、影片、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 中的標籤。

需要備份的資料有三部分：

# 匯出資料庫
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 <名字>     # 直接指定帳號

• 指令會列出所有帳號（名字、角色、建立時間、最近登入），按序號選擇後輸入兩次新密碼。
• 重置後該帳號在所有裝置上的登入會失效，照片與相簿不受影響。
• 該操作只能在主機上執行，網頁上沒有入口。未使用 Docker 時執行 wanmory reset-password，並攜帶執行時的 DATABASE_URL 等環境變數。

檢視各服務日誌：docker compose logs -f server、docker compose logs -f ml。仍無法解決時，歡迎在提交問題頁面回報，並附上版本號與相關日誌。

在執行萬象的主機上執行解除安裝腳本：

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

腳本先讀取安裝目錄中的 .env，列出容器、資料庫、資料目錄、AI 模型及其佔用空間，以及掛載的照片目錄；隨後停止並刪除容器和網路，再逐項詢問是否刪除（預設均為保留）：

• 掛載的已有照片目錄（NAS、行動硬碟）始終不會被刪除。
• 選擇刪除資料庫或資料目錄時，需要輸入 DELETE 進行再次確認。
• 只刪除容器、保留資料時，在原目錄重新執行 install.sh 即可恢復全部內容；如果刪除了 .env 但保留資料庫，請先記下其中的 WANMORY_DB_PASSWORD。