本页目录
Itemory Private Cloud

Itemory 私有云安装教程

在自己的 NAS 上装一个小服务,让 Itemory 翻看 NAS 里的照片更快。全流程五步,照着做大约 15 分钟,中间不需要懂 Docker 命令。

最后更新:2026-10-19
按顺序做,遇到问题可以随时停下,已经装好的部分不会坏掉
  1. 1 · 安装服务建文件夹,粘贴配置
  2. 2 · 设管理员账号浏览器打开管理网页
  3. 3 · iPhone 配对扫一次二维码
  4. 4 · 选照片文件夹告诉服务要索引哪里
  5. 5 · 确认装好了四项检查

先确认要不要装

Itemory 读取 NAS 上的照片有两种方式,只能同时用一个。两者的部署成本差别很大,先看一眼再决定要不要往下做。

不用安装

共享文件夹直连(SMB / WebDAV)

NAS 上什么都不装,App 直接读共享文件夹。

  • 在 App 里填一次地址和账号就能用,五分钟搞定
  • App 自己逐个文件读取,照片多或视频多时每一次浏览都要现场解析
  • 适合照片不多、想先试试效果
本页要装的

Itemory 私有云服务

在 NAS 上跑一个 Docker 容器,把这些活提前做完。

  • NAS 预先建好索引和缩略图,App 只取结果,翻看和滚动明显更快
  • 拍摄时间、位置、实况照片、RAW 预览在 NAS 上读一次就缓存下来
  • 适合照片多、视频多,或者 NAS 和手机之间的 Wi-Fi 较慢

看完还是拿不准,就先试共享文件夹:它不需要在 NAS 上装任何东西。真觉得慢了,再回来做这一页,两种方式可以随时切换,装完不满意也可以删掉容器。

装之前准备好这些

1在 NAS 上安装

先选 NAS 系统,照着四步做。默认用图形界面;走不通时,再看末尾的备用方式。

选择 NAS 系统

群晖 DSM 7.2 及以上

01创建数据文件夹

打开 File Station,在 docker 里新建 itemory-agent 文件夹。

02打开 Compose

打开 Container Manager,进入「项目 → 新增」,选择刚建的文件夹,用「创建 docker-compose.yml」。

03粘贴配置

需要确认的几项
照片路径/volume1按需修改照片在另一个存储空间时改成 /volume2;只让服务读取某个相册时,改成 /volume1/photo。
数据路径/volume1/docker/itemory-agent一般不用改与第 1 步一致。
运行用户"1000:1000"按需修改照片显示不可读时,改成你的 NAS 账号用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 群晖 DSM 7.2+
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
整卷挂载

第 4 步只选照片文件夹,或把 docker 填进「不扫描的文件夹」。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

飞牛 fnOS

01创建数据文件夹

打开「文件管理」,新建 itemory-agent 文件夹,再在里面新建 data。

02打开 Compose

打开 Docker,进入「Compose → 新建项目」,选择 itemory-agent 文件夹。

03粘贴配置

需要确认的几项
照片路径/vol1/1000/Photos必须改改成你的照片文件夹,通常在 /vol1/1000/ 下。
数据路径/vol1/1000/itemory-agent/data一般不用改与第 1 步一致。
运行用户"1000:1000"按需修改照片不可读时,改成 NAS 账号的用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 飞牛 fnOS
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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/1000/Photos:/volumes/Photos:ro     # ← 改成你的照片文件夹,只读
      - /vol1/1000/itemory-agent/data:/data      # 服务自己的数据
    ports:
      - "8787:8787"
    environment:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
不要放进 Docker 数据目录

数据文件夹不要放在 /vol1/docker,重装 Docker 时可能被清掉。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

绿联 UGOS Pro

01创建数据文件夹

打开「文件管理」,在 docker 里新建 itemory-agent 文件夹。

02打开 Compose

打开 Docker,进入「项目 → 创建项目」,选择刚建的文件夹。

03粘贴配置

需要确认的几项
照片路径/volume1按需修改照片在别处时改成实际路径;也可以收窄到 /volume1/photo。
数据路径/volume1/docker/itemory-agent一般不用改与第 1 步一致。
运行用户"1000:1000"按需修改照片不可读时,改成 NAS 账号的用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 绿联 UGOS Pro
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
整卷挂载

第 4 步只选照片文件夹,或把 docker 填进「不扫描的文件夹」。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

极空间 ZOS

01创建数据文件夹

打开 Docker 管理器,进入「Compose 项目 → 添加 Compose」,新建 itemory 项目并选择数据文件夹。

02打开 Compose

进入刚创建的项目,打开 Compose 配置编辑区。

03粘贴配置

需要确认的几项
照片路径./media必须改改成照片的绝对路径,例如 /volume1/photos。
数据路径./data必须改改成数据的绝对路径,不要放在照片目录里。
运行用户"1000:1000"按需修改照片不可读时,改成 NAS 账号的用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 极空间 ZOS
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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:
      - ./media:/volumes/media:ro                # ← 改成你的照片文件夹,只读
      - ./data:/data                             # 服务自己的数据
    ports:
      - "8787:8787"
    environment:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
没有 Compose 菜单

没有 Compose 菜单时,使用章末的 SSH 或离线安装包。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

威联通 QTS / QuTS hero

01创建数据文件夹

打开 File Station,在 Container 里新建 itemory-agent 文件夹。

02打开 Compose

打开 Container Station,进入「应用程序 → 创建」,打开 YAML 编辑区。

03粘贴配置

需要确认的几项
照片路径/share/CACHEDEV1_DATA按需修改卷名不是 CACHEDEV1_DATA 时,两处一起改。
数据路径/share/CACHEDEV1_DATA/Container/itemory-agent一般不用改与第 1 步一致。
运行用户"1000:1000"按需修改照片不可读时,改成 NAS 账号的用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 威联通 QTS / QuTS hero
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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/cachedata:ro                  # 照片所在的存储卷,只读
      - /share/CACHEDEV1_DATA/Container/itemory-agent:/data          # 服务自己的数据
    ports:
      - "8787:8787"
    environment:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
整卷挂载

第 4 步只选照片文件夹,或把 Container 填进「不扫描的文件夹」。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

TrueNAS SCALE 24.10 及以上

01创建数据文件夹

新建数据集 itemory-agent,记下实际路径,例如 /mnt/apps/itemory-agent。

02打开 Compose

进入「Apps → Custom App」,选 YAML 安装。

03粘贴配置

需要确认的几项
照片路径/mnt按需修改照片在某个数据集时,把 /mnt 收窄到该路径。
数据路径/mnt/apps/itemory-agent必须改改成第 1 步记下的路径。
运行用户"1000:1000"按需修改照片不可读时,改成 NAS 账号的用户编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# TrueNAS SCALE 24.10+
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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:/volumes/mnt:ro                     # 全部存储池,只读
      - /mnt/apps/itemory-agent:/data            # 服务自己的数据
    ports:
      - "8787:8787"
    environment:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
机型与权限

仅支持 Intel/AMD。照片读不到时,调整数据集 ACL。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

Unraid

01创建数据文件夹

在 Community Applications 安装 Compose Manager。

02打开 Compose

进入「Docker → Compose → Add New Stack」,新建并编辑 Stack。

03粘贴配置

需要确认的几项
照片路径/mnt/user一般不用改/mnt/user 已包含所有共享目录,第 4 步再选具体文件夹。
数据路径/mnt/user/appdata/itemory-agent一般不用改appdata 用来存放应用数据。
运行用户"99:100"一般不用改Unraid 默认使用 99:100。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# Unraid
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/itemory-agent:1
    container_name: itemory-agent
    restart: unless-stopped
    user: "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:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g
整卷挂载

第 4 步只选照片文件夹,或把 appdata 填进「不扫描的文件夹」。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

装有 Docker 的 Linux 电脑或服务器

01准备配置文件

新建一个空文件夹,用来存放 compose.yaml。

02打开 Compose

打开终端,进入这个文件夹。

03粘贴配置

需要确认的几项
照片路径/CHANGE/ME/photos必须改改成照片目录的绝对路径,例如 /home/me/Pictures。
数据路径itemory-data一般不用改Docker 会自动创建这个命名卷。
运行用户"1000:1000"按需修改运行 id 用户名,填写输出里的用户编号和组编号。
时区Asia/Shanghai按需修改照片没有时区时,用它判断日期。
# 通用 Docker Compose
services:
  itemory-agent:
    image: ccr.ccs.tencentyun.com/itemory/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:
      - /CHANGE/ME/photos:/volumes/photos:ro     # ← 改成你的照片文件夹,只读
      - itemory-data:/data                       # 服务自己的数据
    ports:
      - "8787:8787"
    environment:
      ITEMORY_PRESET: "balanced"
      TZ: "Asia/Shanghai"
    # 库里有超过 1 GB 的视频时,把这个数字调大
    mem_limit: 2g

volumes:
  itemory-data:
OpenMediaVault

OMV 用 openmediavault-compose,路径按共享文件夹改成 /srv/…。其他模板见deploy/compose。

04确认启动

显示「运行中」后,等半分钟变成「健康」,就可以继续第 2 步。

需要时再看

路径怎么放

数据文件夹和照片文件夹不能互相包含。否则缩略图可能被当成照片再扫一遍。

配置怎么看

通常只改照片路径;照片不可读时再改 user。

缩进

整段复制。需要修改时,用两个空格缩进,不要用 Tab。

路径和端口

NAS路径:容器内路径:ro:左边换成你的 NAS 路径,右边不要改。8787:8787:左边可以换端口,右边不要改。

不要重复挂载

同一个目录只挂一次。挂了照片文件夹,就不要再挂它的上级目录。

上面的配置已经写好,多数人只需改照片路径。

怎么确认服务正常

Docker 里显示「运行中」或「健康」就正常。也可以打开 http://NAS的IP:8787/api/v1/health,看到 "status":"ok" 即可。

备用安装方式

上面的方法走不通时再用。

离线安装包

Intel/AMD 或 x86_64 选 amd64;ARM 或 aarch64 选 arm64。

下载 amd64 安装包 · 下载 arm64 安装包

  1. 解压后把镜像导入 Docker:docker load -i 镜像文件。
  2. 使用包内对应系统的 Compose 配置,核对路径、用户和端口。
  3. 启动后打开 http://NAS的IP:8787,继续第 2 步。已有安装先备份数据,不要直接套新配置。
SSH 一键安装

在 NAS 上执行。脚本会提示填写照片目录和安装位置,升级也用这条命令。

默认使用腾讯云镜像。需要 GHCR 或 OSS 时,在命令末尾加 -s -- --source ghcr 或 -s -- --source oss。

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

需要 Bash、Python 3.9+、curl 和 Docker Compose V2;权限不足时用 sudo bash。

照片默认只读。升级会先备份 /data,保留配置和配对。

已有的 Compose 安装会直接升级;配置不一致时,会在停服前退出。

旧版 docker run 容器会先询问是否迁移。迁移会备份数据,并保留旧容器用于回滚。

日志默认在 ~/.cache/itemory-agent/logs/;可以用 --log-file 指定位置,--debug 显示详细过程。失败时脚本会自动打印日志路径和复制命令。

让 AI Agent 安装

NAS 上有能执行命令的 AI Agent 时,把这份提示词发给它。

2设置管理员账号

在同一个 Wi-Fi 下的电脑上,用浏览器打开 http://NAS的IP地址:8787,例如 http://192.168.1.20:8787。第一次打开会让你设置管理员账号:用户名 3–64 个字符,密码至少 12 位。

密码只以哈希形式保存,无法找回。忘记了只能重置管理员账号,请现在就记好。

不要用 localhost 或 127.0.0.1 打开。你在这个地址栏里填的地址会被写进配对二维码。用 localhost 打开时,手机扫到的也是一个只在本机有效的地址,配对一定失败。必须用 NAS 在局域网里的 IP。

3iPhone 扫码配对

  1. 在管理网页左侧打开「配对与设备」,点「开始配对」。页面会显示一个二维码,5 分钟内有效,而且只能用一次。
  2. 在 iPhone 上打开 Itemory,进入「我的 → 设置 → 数据源 → 数据源设置 → 添加数据源 → Itemory 私有云服务」,点「扫描二维码」。
  3. 对准屏幕上的二维码扫描,App 提示配对完成后就可以关掉这个页面。要给另一台 iPhone 配对,再点一次「开始配对」生成新的二维码。

App 只支持扫码配对,没有手动输入地址的入口。如果你的手机浏览器也能打开管理网页,二维码请显示在另一块屏幕上再扫,不要在同一台手机上来回切。

4添加媒体库

配对只是建立了信任关系,服务还不知道要索引哪里。这一步告诉它去哪找照片。

  1. 在 App 的「我的 → 设置 → 数据源 → 数据源设置」里找到刚配对的这台服务,点右侧的调节图标,进入「Itemory 私有云设置」。
  2. 打开「媒体库 → 添加文件夹」,选好存放照片的文件夹。列表里显示的是容器内的 /volumes/… 路径,不是 NAS 上的路径。选「选择该卷根目录」会索引整个挂载点。
  3. 需要多个文件夹就依次添加,然后保存。服务立即开始第一次扫描,照片越多用时越长,可能是几分钟到几小时。

扫描期间已经可以浏览:扫到哪一天,哪一天就会出现在 App 里。之后服务每天夜里 03:00 自动检查一次变化,只读取新增或修改过的文件。每次扫描结束后,服务会在后台从最新的照片开始提前生成缩略图,默认每晚最多 5000 张。

整卷挂载的话,这里多一步。上一节的配置把整个存储空间都挂给了服务,你的数据文件夹也在里面。请在「不扫描的文件夹」里填上数据文件夹的名字(群晖、绿联是 docker,威联通是 Container,Unraid 是 appdata),否则服务会把缩略图当成照片再扫一遍。

5确认装好了

按顺序核对这四项。全部通过就可以正常用了;有一条没过,去下面的「遇到问题」里找对应的一条。前两项在配对之前就能看。

遇到问题

按卡住的那一步找。都不是你的操作错了,这些是常见情况。

卡在第 1 步:装不上或起不来

镜像拉不下来,或一直卡在下载

默认用的是腾讯云国内镜像仓库,多数情况不需要代理。还是拉不动时,改用上面的离线安装包;或者把配置里的 image: 换成 ghcr.io/sherlockgougou/itemory-agent:1 再试。

容器启动后马上停止,或提示 permission denied

服务使用的用户没有权限写数据文件夹,或者读不了照片文件夹。先确认数据文件夹已经建好;仍然不行时,把配置里 user 一行改成你自己 NAS 账号的编号。在管理网页的「媒体库」页,服务会直接给出建议的编号。不要改成 root 运行。

8787 端口被占用了

把配置里 "8787:8787" 冒号前面的数字改成别的,例如 "18787:8787"。冒号后面的不要动。改完重新启动容器,访问地址也相应改成新端口。

缩略图一直不出现,或者视频显示成灰色

多半是内存不够。提取一个 2 GB 视频的封面需要的内存远大于照片,mem_limit: 2g 在有大视频时可能不够。把这个数字调大,例如 4g,然后重新创建容器。

卡在第 2 步:管理网页打不开

浏览器打不开管理网页
  • 确认容器状态是「运行中」。
  • 确认地址里用的是 NAS 在家里网络中的 IP(通常是 192.168.x.x),而且电脑和 NAS 在同一个网络。不要用 localhost。
  • NAS 开了防火墙时,放行 8787 端口。
  • 端口改过的话,访问地址要用改过之后的端口。
忘记了管理员密码

密码无法找回,只能重置管理员账号,其他内容都不受影响。步骤见常见问题文档的「忘记管理员密码」。

卡在第 3 步:扫不了码

App 扫不了二维码

确认 iPhone 和 NAS 在同一个 Wi-Fi;把二维码放大、屏幕调亮后再扫。二维码超过 5 分钟会失效,再点一次「开始配对」生成新的。如果刚才用 localhost 打开过管理网页,关掉重新用 NAS 的 IP 打开再生成二维码。

App 提示无法使用相机

在 iOS 的「设置 → Itemory」里打开相机权限,再回到 App 重新扫描。

卡在第 4 步:配对成功但看不到照片

文件夹显示为不可读

照片可能还在磁盘上,只是这个用户读不到。管理网页的「媒体库」页会出现「建议运行用户」,把它填进配置里的 user,确认数据文件夹也属于这个用户,然后重新创建容器。

添加文件夹时列表是空的

说明容器里没有可读的挂载点。回到第 1 步检查 volumes: 里的照片路径是否真的存在,冒号后面的 /volumes/… 有没有写。也确认这个用户读得了该目录。列表里没有想要的文件夹时,用「手动输入路径」填容器内的完整路径,例如 /volumes/volume1/photo/2024。

照片出现在错误的日期

照片本身没有记录时区时,由配置里的 TZ 决定它属于哪一天。确认 TZ 是你所在时区,例如 Asia/Shanghai,改完重新创建容器并重新扫描。

第一次加载很慢

第一次扫描和提前生成缩略图要花时间。照片越多越久,这期间照片照样能打开,只是第一次显示慢一点。可以先让它在夜里跑完;想让首次扫描快一点,把配置里的 ITEMORY_PRESET 临时改成 performance,扫完再改回 balanced。视频很大的话同时调大 mem_limit。

想在外面也能看家里的照片

请通过 Tailscale、WireGuard 这类 VPN 连回家里的网络。不要把 8787 端口直接在路由器上转发到公网。

装好之后

完全开源,代码公开可查

Itemory 私有云服务(技术名称 itemory-agent)的全部源码以 MIT 许可证公开在 GitHub,任何人都可以查看它做了什么,也可以自己从源码构建。你安装的镜像由 GitHub 的自动构建流程直接从这份公开源码生成。希望先审查脚本时,可以把 install.sh 下载下来读过再执行。

  • 照片默认只读。配置里照片文件夹以只读方式交给服务,它不会修改、删除或重命名你的照片。要删除照片,需要在服务设置里开启删除模式并把该文件夹改成可写,两件事都做完才会生效。
  • 照片不离开你的 NAS。服务只在家里的网络中把照片提供给你配对过的 iPhone,不需要注册任何云端账号。
  • 权限最小。服务不以管理员(root)身份运行,只能写入它自己的数据文件夹,容器本身还是只读的。
  • 凭据分开。手机配对拿到的令牌只能读媒体,管理员账号只用来改设置,两套凭据互不相通。App 里不会保存管理员账号或密码。

更多内容(完整的配置参数、升级与备份细节、全部问题列表)见开源仓库的说明文档。