部署与文档

本文档面向在 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。