PhotoPrism 文档：使用 Docker Compose 进行设置

使用 Docker Compose，你可以使用一个 YAML 文件来配置所有应用程序服务，这样只需一条命令就能轻松启动它们。在继续之前，请确保您的系统已安装 Docker。它适用于 Mac、Linux 和 Windows。

此外，Podman Compose 还支持在兼容 Red Hat 的 Linux 发行版（如 RHEL、CentOS、Fedora、AlmaLinux 和 Rocky Linux）上替代 Docker Compose。

步骤 1：配置

下载我们的 compose.yaml 示例（右击并将链接另存为……或使用 wget）到您选择的文件夹，然后根据需要更改配置：

基于 AMD64 的 Linux 设备：
wget https://dl.photoprism.app/docker/compose.yaml
基于 ARM64 的 Linux 设备：
wget https://dl.photoprism.app/docker/arm64/compose.yaml
基于 ARMv7 的 Linux 设备：
wget https://dl.photoprism.app/docker/armv7/compose.yaml

如果不以 root 身份运行，Linux 上的命令可能需要以 sudo 作为前缀。请注意，这将在配置文件的 volumes: 部分把主目录快捷方式 ~ 指向 /root。有报告称 AppArmor 和 SELinux 等内核安全模块会导致问题。

我们建议服务器配置至少 4 GB 的交换空间，并避免设置硬性内存限制，因为当索引器暂时需要更多内存来处理大文件时，这会导致意外重启。索引 RAW 图像和高分辨率全景图可能需要超出建议最小值的额外交换空间和/或物理内存。

编辑 YAML 文件时，请确保相关值保持在同一缩进级别，列表以破折号开头。如果环境变量的值包含字面意义上的 $ 号，例如密码中的 $ 号，则必须用 $$（双美元符号）转义，这样 “compo$e ”就变成了 “compo$$e”。

始终更改 PHOTOPRISM_ADMIN_PASSWORD，以便应用程序以安全的初始密码启动。切勿在可公开访问的服务器上使用易于猜测的密码或默认值（如不安全）。如果没有提供密码，则没有默认值。密码长度至少为 8 个字符。

数据库

我们的示例包括一个预配置的 MariaDB 数据库服务器。如果删除它，并且不提供其他数据库服务器凭据，就会在存储文件夹中创建 SQLite 数据库文件。对于任何类型的数据库，本地固态硬盘存储都是最佳选择。

切勿将数据库文件存储在 USB 闪存盘、SD 卡或共享网络文件夹等不可靠的设备上。这些设备也可能会有意想不到的文件大小限制，对于不将数据分割成较小文件的数据库来说，问题尤其严重。

首次启动 MariaDB 后，就不能使用 MARIADB_PASSWORD 更改数据库密码了。不过，如果不与其他应用程序共享数据库或在网络上公开数据库，选择一个安全的密码并不是必要的。要在升级到新的主版本时启用模式自动更新，请确保 MARIADB_AUTO_UPGRADE 设置为非空值。

Volumes

您必须明确指定要从主机挂载的目录，因为 PhotoPrism 无法查看未共享文件夹中的文件。这是一项重要的安全功能，可实现灵活配置，无需更改任何其他变量。

重要的是，所有文件夹都要加载到持久卷。我们建议将示例中使用的相对路径更改为绝对路径，并避免使用已命名或匿名卷，以防止在重新创建容器（如更新 Docker 映像后）时可能丢失数据。

/photoprism/originals

originals 文件夹包含你的原始照片和视频文件。~/Pictures 将被默认挂载，其中 ~ 是你的主目录的快捷方式：

services:
  photoprism:
    volumes:
      - "~/Pictures:/photoprism/originals"

我们建议您将 ~/Pictures 改为现有媒体文件所在的目录，例如：

      - "/mnt/photos:/photoprism/originals"

其他目录可以挂载为 /photoprism/originals 的子文件夹（取决于叠加文件系统的支持情况）：

    volumes:
      - "/mnt/photos:/photoprism/originals"
      - "/mnt/videos:/photoprism/originals/videos"

在 Windows 系统中，主机路径以驱动器代号为前缀，并使用 / 代替分隔符：

    volumes:
      - "D:/Example/Pictures:/photoprism/originals"

启用只读模式后，所有需要写入origals 文件夹权限的功能都会被禁用，例如 WebDAV、上传和删除文件。为此，请在 compose.yaml 文件的环境部分将 PHOTOPRISM_READONLY 设置为 “true”。2 此外，你还可以使用 :ro 标志挂载卷，这样 Docker 也会阻止写入。

/photoprism/storage

storage 文件夹用于保存配置、缓存、备份、缩略图和副卡文件。必须始终指定该文件夹，以免重启或升级后丢失这些文件。如果有条件，建议将 storage 文件夹放在本地 SSD 驱动器上，以获得最佳性能。也可以保留默认值，将文件存储在与当前目录相对应的文件夹中：

services:
  photoprism:
    volumes:
      - "./storage:/photoprism/storage"

切勿将 storage 文件夹配置在 originals 文件夹内，除非文件名以 . 开头，表示隐藏。如果以后想将实例转移到另一台主机上，最简单省时的方法就是将整个 storage 文件夹连同 originals 文件夹和数据库一起复制。

/photoprism/import

您可以选择挂载一个 import 文件夹，从该文件夹将文件有序地传输到 originals 文件夹，以避免重复等，例如：

services:
  photoprism:
    volumes:
      - "/mnt/media/usb:/photoprism/import"

导入的文件会收到一个规范文件名，并按年月进行整理。千万不要将导入文件夹配置在 originals 文件夹内，因为这样会导入已编入索引的文件，造成循环。

即使不指定导入文件夹，也可以通过网络上传和 WebDAV 添加文件，除非启用了只读模式或禁用了这些功能。

步骤 2：启动服务器

打开终端，切换到保存配置文件的文件夹。运行此命令在后台启动应用程序和数据库服务：

docker compose up -d

请注意，我们的示例默认使用新的 docker compose 命令。如果你的服务器还不支持它，你仍然可以使用 docker-compose，或者在兼容红帽的发行版上使用 podman-compose。

现在通过导航到 http://localhost:2342/ 打开 Web UI。你会看到一个登录界面。使用用户 admin 和通过 PHOTOPRISM_ADMIN_PASSWORD 配置的初始密码登录。您可以在账户设置页面进行更改。启用公共模式将禁用身份验证。

调试时保持 Docker 在前台运行可能会有帮助，这样就能直接显示日志信息。为此，请在重启时省略 -d 参数。
如果服务器已经在运行，或者没有发现任何错误，则可能是在不同的主机和/或端口上启动了服务器。也可能是浏览器、广告拦截器或防火墙设置出了问题。

首次启动应用程序后，就不能使用 PHOTOPRISM_ADMIN_PASSWORD 更改密码了。要修改管理员密码，请在终端运行 docker compose exec photoprism photoprism passwd [username] 命令。你也可以运行 docker compose exec photoprism photoprism reset 删除现有的索引数据库，然后从头开始。

服务器端口和其他配置选项可随时在 compose.yaml 文件中更改。切记要重启服务才能使更改生效：

docker compose stop
docker compose up -d

第 3 步：为资料库编制索引

我们的 “第一步 ”教程将指导您完成用户界面和设置，以确保根据您的个人偏好为您的资料库编制索引。

很简单，不是吗？

PhotoPrism 附加功能

我们的会员可以使用设置时创建的管理员用户登录，然后按照激活指南中描述的步骤激活其他功能。感谢您一直以来的支持，这对项目的成功至关重要！

我们建议新用户在注册会员之前先安装免费的社区版。

故障排除

如果您的服务器内存不足，索引经常被锁定，或其他系统资源不足：

根据 CPU 性能和内核数量，尝试在 compose.yaml 文件中将 PHOTOPRISM_WORKERS 设置为合理的较小值，以减少 Worker 的数量。
确保服务器配置了至少 4 GB 的交换空间，避免设置硬性内存限制，因为当索引器临时需要更多内存来处理大文件时，这会导致意外重启
如果您使用的是 SQLite，请改用 MariaDB，它针对高并发进行了更好的优化
作为最后一项措施，可以禁用 TensorFlow 进行图像分类和面部识别

其他问题？我们的故障排除清单可帮助您快速诊断和解决这些问题。

欢迎在社区聊天中寻求帮助。赞助商可通过电子邮件直接获得技术支持。在提交支持请求之前，请尝试确定问题的原因。

命令行界面

简介

PhotoPrism help 列出了当前版本中的所有命令和配置选项：

docker compose exec photoprism photoprism help

例如，使用 –help 标志可查看详细的命令说明：

docker compose exec photoprism photoprism backup --help

PhotoPrism 的命令行界面也非常适合使用调度程序实现作业自动化。

使用 Docker Compose 时，可以在要运行的命令前加上 docker compose exec [service] 以在指定的服务容器中执行。如果执行失败，找不到容器，请确保服务已经启动，你指定了一个现有的服务（通常是 PhotoPrism），并且你在配置文件所在的文件夹中。

打开终端

以默认用户身份打开终端会话：

docker compose exec photoprism bash

由于上述操作默认以 root 身份打开终端，因此我们建议，如果 PhotoPrism 是在特定用户账户下运行，则通过 -u 标志显式打开非 root 会话，例如：

docker compose exec -u 1000 photoprism bash

这就避免了在命令创建新文件或文件夹（如存储缩略图）时可能出现的文件系统权限问题。

更改用户 ID

在使用 Docker 和 Docker Compose 运行的所有命令中，都可以使用 -u 标志指定用户。在下面的示例中，为了简洁起见，省略了用户 ID。不过请注意，在没有明确用户 ID 的情况下运行的命令可能会以 root 用户身份执行。目前支持的用户 ID 范围是 0、33、50-99、500-600、900-1250 和 2000-2100。

我们建议通过在配置文件中设置用户服务属性或 PHOTOPRISM_UID 环境变量，以非 root 用户身份运行 PhotoPrism 服务。在进行更改时，不要忘记使用 chown 命令更新文件权限和/或所有权。

示例

动作	指令
启动服务	docker compose up -d
停止服务	docker compose stop
下载更新	docker compose pull
卸载	docker compose rm -s -v
查看日志	docker compose logs -f –tail=100
显示配置值	docker compose exec photoprism photoprism show config
显示迁移状态	docker compose exec photoprism photoprism migrations ls
重复失败的迁移	docker compose exec photoprism photoprism migrations run -f
重置数据库	docker compose exec photoprism photoprism reset –yes
备份数据库	docker compose exec photoprism photoprism backup -i -f
还原数据库	docker compose exec photoprism photoprism restore -i -f
更改密码	docker compose exec photoprism photoprism passwd [username]
显示用户管理命令	docker compose exec photoprism photoprism users help
重置用户账户	docker compose exec photoprism photoprism users reset –yes
重置会话和访问令牌	docker compose exec photoprism photoprism auth reset –yes
显示人脸识别命令	docker compose exec photoprism photoprism faces help
索引面孔	docker compose exec photoprism photoprism faces index
重置人物和面孔	docker compose exec photoprism photoprism faces reset -f
将视频转码为 AVC	docker compose exec photoprism photoprism convert
重新生成缩略图	docker compose exec photoprism photoprism thumbs -f
更新索引	docker compose exec photoprism photoprism index –cleanup
移动到原始文件	docker compose exec photoprism photoprism import [path]
复制到原始文件	docker compose exec photoprism photoprism cp [path]

完全重新扫描
docker compose exec photoprism photoprism index -f 重新扫描所有原始文件，包括已经索引和未修改的文件。在重大升级和数据库模式迁移之后，尤其是在搜索结果丢失或不正确的情况下，这可能是必要的。请注意，您也可以从用户界面启动重新扫描，方法是导航至库 > 索引，选中 “完全重新扫描”，然后单击 “开始”。即使执行 “完全重新扫描”，手动输入的信息（如标签、人物、标题或描述）在编制索引时也不会被修改。