Itemory Companion · Enhanced Service

主流 NAS 安装增强服务指南

通过 Docker Compose 为你的私有 NAS 快速部署 Itemory 增强服务（NasAgent）。端侧优先、零第三方中转、秒级提取缩略图与快速检索。

更新于 2026-09-20 · 针对 DSM 7 / fnOS / UGOS Pro / ZOS / QTS / TrueNAS 等系统

用户支持 · 隐私政策 · 用户协议

前置检查：你的 NAS 能否安装？
核心原理与安全规范
群晖 Synology DSM 7 安装
飞牛 fnOS 安装
绿联 UGOS Pro 安装
极空间 ZOS 安装
威联通 QNAP QTS / QuTS 安装
TrueNAS SCALE 与 Unraid 安装
配对步骤：在 App 中扫码连接
常见排错与进阶建议

1前置检查：你的 NAS 能否安装？

Itemory 增强服务本质上是一个高度轻量化的开源容器（基于 Go 语言编写，内存占用仅约 50MB–200MB）。能否安装取决于你的 NAS 系统是否提供 自定义 Docker / 容器环境。

系统 / 品牌	支持级别	容器方案	推荐部署方式
飞牛 fnOS、TrueNAS SCALE、Unraid、OMV	第 4 档 · 原生 Docker	系统原生集成 Docker / Compose	WebUI Compose 或标准 SSH 命令行
群晖 Synology DSM 7.2+	第 3 档 · 图形化编排	Container Manager 套件	「项目 (Project)」页面粘贴 Compose
绿联 UGOS Pro (DXP 系列等)	第 3 档 · 图形化编排	Docker 应用	「项目 (Docker Compose)」向导粘贴
极空间 ZOS (2024-10 后固件)	第 3 档 · 图形化编排	Docker 管理器	Compose 项目支持，支持环境变量
威联通 QNAP QTS / QuTS hero	第 3 档 · 图形化编排	Container Station	「应用程序 → 创建」粘贴 Compose
铁威马 TOS 6、华硕 ADM	第 3 档 · 图形化编排	Docker Manager / Portainer	Compose 模板或 Stack 创建
联想个人云、海康存储	第 2 档 · 受限/非官方	未正式开放自定义 Compose	不建议折腾，优先走下方替代方案
华为家庭存储、WD My Cloud	第 1 档 · 无 Docker	系统不支持 Docker 且不开放 SSH	无法安装（请直接使用局域网共享）

💡 你的 NAS 属于第 1 档或不支持 Docker？
完全不用担心。Itemory App 内置了通用的 SMB / WebDAV 网络共享支持。在 iPhone / iPad 上的「数据源设置」中选择「添加数据源 → NAS 或电脑共享文件夹」，直接输入 NAS 开启的 SMB 或 WebDAV 共享路径与账号密码，即可直接读取浏览相片，无需部署任何增强服务。

2核心原理与安全规范

相比普通 SMB 协议逐张照片通过网络远程解码，增强服务部署在存储同侧，负责在 NAS 本地建立高效索引与生成高清缩略图。在设计上，增强服务遵循 最低权限与降低数据风险原则：

增强服务的安全设计

照片原始卷严格只读（Read-Only）：在所有 Docker Compose 模板中，媒体卷均以 :ro 挂载。增强服务在文件系统层面上无法修改、删除或重命名你的任何照片与视频。
非 Root 用户运行：容器进程默认以普通用户权限运行；各平台模板中的 user 值必须与媒体目录和数据目录的实际 UID:GID 权限匹配（Unraid 模板使用 99:100）。
只读根文件系统与 Drop All：容器开启 read_only: true 并丢弃所有 Linux 内核特权（cap_drop: [ALL]），仅开放独立的临时内存 tmpfs。
管理员令牌保护配对：只有持有你在 Compose 中配置的 ITEMORY_ADMIN_TOKEN 的管理员，才能开启/关闭配对窗口、读取二维码或管理已配对设备；一次性配对码仍仅 5 分钟有效且只能使用一次。

3群晖 Synology DSM 7 安装

适用机型：群晖 Plus 系列（x86 架构）及部分 ARM64 机型（如 DS223 等）。系统版本需为 DSM 7.2 或更新。

打开 File Station，进入你的存储空间（例如 /volume1/docker/），新建名为 itemory-agent 的文件夹。确认当前登录账户对该文件夹具有读写权限。
打开 Container Manager 套件（若未安装可在套件中心搜索安装）。
在左侧导航栏点击 项目 (Project) → 点击创建。
填写项目名称（例如 itemory），路径选择刚才创建的 /volume1/docker/itemory-agent。
来源选择 创建 docker-compose.yml，将以下 YAML 内容完整粘贴到文本框中：

# Synology DSM 7 · Container Manager → 项目 → 新建
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      # 媒体根目录：以只读挂载 (:ro)
      - /volume1:/volumes/volume1:ro
      # 数据持久化目录：存放索引与缓存
      - /volume1/docker/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

点击「下一步」，勾选「立即启动项目」，完成创建。等待镜像拉取完毕后，项目状态显示为绿色的「运行中」。

4飞牛 fnOS 安装

飞牛 fnOS 基于标准 Debian 底层，原生集成完整 Docker 环境与独立管理面板，对自定义容器非常友好。

在应用中心安装并打开 Docker 管理。
在左侧点击 Compose（或「项目」），点击 新建项目。
项目名称填写 itemory，在存储路径中指定持久化目录（如 /vol1/docker/itemory-agent）。
在配置编辑区粘贴下方 Compose YAML，并将 /vol1 替换为你实际存放相册的卷路径：

# 飞牛 fnOS · Docker 管理 → Compose 新建
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      - /vol1:/volumes/vol1:ro
      - /vol1/docker/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

点击确定启动，系统将自动拉取镜像并部署运行。

5绿联 UGOS Pro 安装

适用设备：绿联 DXP 系列等运行 UGOS Pro 系统的机型。底层路径沿用 /volume1 体系，支持图形化 Compose 项目。

在系统桌面打开 Docker 应用。
在左侧选择 项目（Docker Compose），点击 创建项目。
项目名称输入 itemory，路径选择指定的应用数据共享目录（如 /volume1/docker/itemory-agent）。
选择「输入 Docker Compose 内容」，粘贴以下配置：

# 绿联 UGOS Pro · Docker 应用 → 项目（Docker Compose）
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      # 照片所在的实际存储卷
      - /volume1:/volumes/volume1:ro
      - /volume1/docker/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

完成创建并立即运行。如果绿联提示特权模式或环境安全，无需勾选特权模式，标准非特权模式即可正常运行。

6极空间 ZOS 安装

极空间 ZOS 在较新固件中已全面开放标准 Docker Compose 与相对路径支持。

在极空间桌面打开 Docker 管理器。
切换至 Compose 项目 页面，点击 添加 Compose。
项目名填写 itemory，通过浏览指定持久化数据目录。
在 Compose 配置编辑器中粘贴以下内容（按极空间存储池路径确认 /data 与媒体目录）：

# 极空间 ZOS · Docker 管理器 → Compose 项目
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      # 请在极空间界面选取你的媒体文件夹挂载到 /volumes/media (只读)
      - ./media:/volumes/media:ro
      - ./data:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

保存并启动容器。

7威联通 QNAP QTS / QuTS hero 安装

打开 Container Station (容器工作站)。
点击左侧导航 应用程序 (Applications) → 点击右上角 创建 (Create)。
应用名称输入 itemory-agent。
在 YAML 编辑框中粘贴以下内容（将 CACHEDEV1_DATA 更改为你实际的数据卷名称）：

# QNAP QTS / QuTS hero · Container Station → Applications → Create
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      - /share/CACHEDEV1_DATA:/volumes/share:ro
      - /share/CACHEDEV1_DATA/Container/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

点击「创建」，Container Station 会自动完成校验并拉起服务。

8TrueNAS SCALE 与 Unraid 安装

开源与自建 NAS 系统（TrueNAS SCALE 24.10+ Electric Eel、Unraid、OpenMediaVault）原生支持标准 Docker Compose：

TrueNAS SCALE (24.10+)

在 Apps 页面点击 Custom App，选择 Compose 部署，输入：

# TrueNAS SCALE (24.10+ Electric Eel)
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      - /mnt/pool/media:/volumes/media:ro
      - /mnt/pool/appdata/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

Unraid / 通用 Linux 服务器

在 Unraid Docker 界面添加 Compose 栈，或在任意 Linux 终端直接执行：

# 通用 Linux / Unraid 标准 Compose
services:
  itemory-agent:
    image: ghcr.io/sherlockgougou/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "1000:1000"                 # 通用 Linux；Unraid 请改为 99:100
    read_only: true
    tmpfs: ["/tmp:size=128m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    volumes:
      - /mnt/user:/volumes/user:ro
      - /mnt/user/appdata/itemory-agent:/data
    ports:
      - "8787:8787"
    environment:
      # 必填：管理配对窗口和已配对设备。请填入 openssl rand -hex 32 的结果。
      ITEMORY_ADMIN_TOKEN: ""
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    cpus: "1.5"
    mem_limit: 512m

9配对步骤：在 App 中扫码连接

容器启动成功后，无需在后台编写复杂的配置文件。首次部署前请在 Compose 的 ITEMORY_ADMIN_TOKEN 中填入随机值（例如运行 openssl rand -hex 32 生成），不要把它发布到网页、日志或截图中。配对、媒体库选取与扫描参数均在 iPhone / iPad App 内完成；当前 Apple TV 只支持本地系统相册路径，不提供增强服务配对入口。

打开服务网页

在局域网电脑或手机浏览器输入 http://<你的NAS-IP>:8787，打开增强服务初始页面。

输入令牌并开始配对

在页面输入 Compose 中配置的管理员令牌，再点击「开始配对」；页面随后展示一个 5 分钟有效的专属动态配对二维码。

App 扫码完成

打开 iPhone / iPad 上的 Itemory App，在「数据源」点按「添加增强服务」，扫描屏幕二维码即可。

💡 无相机环境？
在网页上点击二维码下方的「显示配对码」，即可获得一组 6 位配对代码与 IP 端口；在 iPhone / iPad App 的配对页面切换为「手动配对」，输入该配对码即可连接。Apple TV 当前没有增强服务配对入口。

💡 配对后的首次扫描
在 App 的「数据源」中打开「增强服务设置」，选择要扫描的媒体库并保存；随后点按「重新扫描全部」，等待状态显示扫描完成，再返回时间线或「我的」页面确认照片与视频数量。首次扫描未完成前，服务端索引可能为空或不完整。

10常见排错与进阶建议

1. 管理员令牌无效或无法开始配对？

确认 Compose 已设置 ITEMORY_ADMIN_TOKEN，且网页中输入的内容完全一致。令牌长度至少 32 个字符；修改后需要重新创建或重启容器。不要把令牌写进 URL，也不要把它直接发给其他设备。

2. 容器无法启动或报权限错误 (permission denied on /data)？

增强服务默认使用非 root 用户运行。请确保挂载到容器 /data 的目录（例如群晖的 /volume1/docker/itemory-agent）对模板中的 UID:GID 具有读写权限；媒体目录则至少需要读取权限。群晖等系统可在 SSH 中运行 id 查看当前用户的 UID:GID，再按实际权限调整 Compose 的 user 值。不要为了绕过错误改用 root 或直接取消非 root 配置。

3. 浏览器打不开 http://<NAS-IP>:8787？

请按以下步骤检查：

确认容器处于「运行中」状态，没有因端口冲突而退出。
检查 NAS 自身的防火墙设置，确保局域网入站 TCP 8787 端口已被放行。
确保访问的 IP 为 NAS 的局域网真实内网 IP（如 192.168.x.x），而非网关或虚拟交换机地址。

4. 配对成功后如何管理图库与远程访问？

选择并扫描文件夹：在 Itemory App 的「增强服务设置」中选择媒体库并保存，然后点按「重新扫描全部」；等待扫描完成后再确认时间线和统计数量。
随时清理服务端缓存：在 App 内部提供了一键清空服务端缩略图缓存的功能，原片只读不受任何影响。
外网穿透访问：推荐搭配 Tailscale、WireGuard 或私有反向代理等安全组网工具使用。为保护家庭私密照片，不建议直接把 8787 端口向公网裸露做端口映射。