PhotoPrism 与 MariaDB 数据库集成
技术 docker 21

PhotoPrism 与 MariaDB 数据库集成：优化性能，解决卡顿问题

摘要： PhotoPrism 是一款优秀的自托管照片管理应用，默认使用 SQLite 数据库。然而，当图片数量庞大或并发访问增多时，SQLite 的性能限制可能导致应用响应迟缓，尤其是在添加、分享照片等操作时。本文将详细指导如何将 PhotoPrism 的后端数据库切换到高性能的 MariaDB，并通过 Docker 容器化部署，确保流畅的用户体验。

关键词： PhotoPrism, MariaDB, Docker, 性能优化, 数据库集成, HTTPS, 反向代理

1. 引言

PhotoPrism 提供了一站式的照片管理解决方案，包括智能识别、分类、索引等功能。默认情况下，PhotoPrism 使用内嵌的 SQLite 数据库，这对于小型个人图库而言是足够的。但随着照片库的不断增长，以及多用户访问场景，SQLite 的文件锁机制和单文件 I/O 特性将逐渐成为性能瓶颈。切换到功能更强大、并发性能更好的关系型数据库（如 MariaDB 或 MySQL）是解决此类问题的最佳实践。本文将以 MariaDB 为例，详细阐述其集成过程。

2. 环境准备

确保您的系统已安装以下组件：

  • Docker & Docker Compose (可选): 用于容器化部署 MariaDB 和 PhotoPrism。
  • Nginx/Caddy (可选): 用于配置反向代理和 HTTPS。
  • mysql-client: 用于在宿主机上测试 MariaDB 连接。

3. MariaDB 容器部署与配置

首先，我们需要启动并配置一个 MariaDB 数据库容器。

3.1 启动 MariaDB 容器

推荐使用 docker run 命令启动 MariaDB 容器，并配置持久化存储、设置root密码，并将其连接到一个自定义的 Docker 网络（例如 baota_net，如果已存在，否则默认会连接到 bridge 网络，后续需要统一）。

docker run -d \
  --name mariadb_container_name \
  --network your_docker_network \
  -p 23036:3306 \
  -e MARIADB_ROOT_PASSWORD=your_mariadb_root_password \
  -e MARIADB_DATABASE=photoprism \
  mariadb:11.4.2
  • --name mariadb_container_name: 为容器指定一个易于识别的名称，例如 photoprism-mariadb。
  • --network your_docker_network: 将 MariaDB 容器连接到指定的 Docker 网络，例如 photoprism-net 或您已有的网络（如 baota_net）。确保 PhotoPrism 容器后续也会连接到此网络。
  • -p 23036:3306: 将容器内部的 3306 端口映射到宿主机的 23036 端口，方便从宿主机进行管理（PhotoPrism 容器内部连接时仍使用 3306 端口）。
  • -e MARIADB_ROOT_PASSWORD=your_mariadb_root_password: 重要！ 设置 MariaDB 的 root 用户密码。请替换为您自己的强密码。
  • -e MARIADB_DATABASE=photoprism: 自动创建一个名为 photoprism 的数据库。

3.2 验证 MariaDB 状态与用户权限

进入 MariaDB 容器的 Shell，验证数据库是否正确创建，以及 root 用户是否允许从外部连接。

docker exec -it mariadb_container_name sh

在 MariaDB Shell 中执行：

# 登录数据库
mariadb -u root -pyour_mariadb_root_password

# 验证 'photoprism' 数据库是否存在
SHOW DATABASES;

# 验证 root 用户的主机权限
SELECT User, Host FROM mysql.user WHERE User='root';

确保 SHOW DATABASES; 的输出包含 photoprism。 SELECT User, Host FROM mysql.user WHERE User='root'; 的输出应包含 root | %，表示 root 用户允许从任何主机连接。如果只有 root | localhost，则需要更新权限：

UPDATE mysql.user SET Host='%' WHERE User='root' WHERE Host='localhost';
FLUSH PRIVILEGES;

提示： 生产环境中，更推荐创建专用的 photoprism 用户并仅授予 photoprism 数据库的权限。

4. PhotoPrism 容器部署与配置

接下来，我们将启动 PhotoPrism 容器，并将其配置为连接到 MariaDB。

4.1 确定 MariaDB 容器的 Docker 网络名称

这是解决容器间通信问题的关键。查询 MariaDB 容器所属的网络名称：

docker inspect mariadb_container_name | grep -A 10 "Networks"

在输出中找到类似 "your_docker_network": { ... } 的网络名称。例如，如果显示 photoprism-net，则 PhotoPrism 容器也应连接到此网络。

4.2 启动 PhotoPrism 容器

停止并移除任何旧的 PhotoPrism 容器（如果有），然后使用新的配置启动。

# 停止并移除旧 PhotoPrism 容器（如果存在）
docker stop your_old_photoprism_container_name || true
docker rm your_old_photoprism_container_name || true

# 启动 PhotoPrism 容器
docker run -d \
  --name photoprism_container_name \
  --network your_docker_network \
  -p 2343:2342 \
  -v /path/to/photoprism/storage:/photoprism/storage \
  -v /path/to/your/pictures:/photoprism/originals \
  -e PHOTOPRISM_DATABASE_DRIVER=mysql \
  -e PHOTOPRISM_DATABASE_SERVER=mariadb_container_name:3306 \
  -e PHOTOPRISM_DATABASE_NAME=photoprism \
  -e PHOTOPRISM_DATABASE_USER=root \
  -e PHOTOPRISM_DATABASE_PASSWORD=your_mariadb_root_password \
  -e PHOTOPRISM_HTTP_PORT=2342 \
  -e PHOTOPRISM_ADMIN_PASSWORD=your_photoprism_admin_password \
  -e PHOTOPRISM_SITE_URL=https://yourdomain.com/ \
  photoprism/photoprism:preview
  • --name photoprism_container_name: 为容器指定一个易于识别的名称，例如 photoprism-app。
  • --network your_docker_network: 关键参数，确保 PhotoPrism 与 MariaDB 在同一网络中，才能通过容器名互相通信。
  • -p 2343:2342: 将容器内部的 2342 端口映射到宿主机的 2343 端口。
  • -v /path/to/photoprism/storage:/photoprism/storage: 重要！ 挂载 PhotoPrism 存储目录，请替换为您的实际路径。
  • -v /path/to/your/pictures:/photoprism/originals: 重要！ 挂载您的原始图片目录，请替换为您的实际路径。
  • -e PHOTOPRISM_DATABASE_SERVER=mariadb_container_name:3306: 配置 PhotoPrism 连接到 MariaDB 容器，使用 MariaDB 容器名（例如 photoprism-mariadb）而非 IP 地址，端口为 MariaDB 内部监听的 3306。
  • -e PHOTOPRISM_DATABASE_USER=root: 使用 MariaDB 的 root 用户连接。
  • -e PHOTOPRISM_DATABASE_PASSWORD=your_mariadb_root_password: MariaDB 的 root 用户密码。
  • -e PHOTOPRISM_ADMIN_PASSWORD=your_photoprism_admin_password: 重要！ 设置 PhotoPrism 管理员密码，请替换为您自己的强密码。
  • -e PHOTOPRISM_SITE_URL=https://yourdomain.com/: 重要！ 设置 PhotoPrism 的外部访问 URL，请替换为您实际的域名。这对于某些内部链接和 HTTPS 重定向非常重要。

4.3 验证 PhotoPrism 数据库连接

查看 PhotoPrism 容器的日志，确认它已成功连接到 MariaDB，并且没有 waiting for the database 等错误信息。

docker logs photoprism_container_name

5. 配置反向代理与 HTTPS (Nginx 示例)

为了通过域名 (https://yourdomain.com/) 访问 PhotoPrism 并启用 HTTPS，我们需要配置一个反向代理。这里以 Nginx 为例。

5.1 Nginx 配置文件示例

创建一个 Nginx 配置文件（例如 /etc/nginx/conf.d/yourdomain.com.conf），替换其中的域名和证书路径：

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri; # HTTP 自动跳转到 HTTPS
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    # SSL 证书路径，请替换为您的实际路径
    ssl_certificate /path/to/your/ssl/fullchain.pem; 
    ssl_certificate_key /path/to/your/ssl/privkey.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20';
    ssl_prefer_server_ciphers on;
    ssl_stapling on;
    ssl_stapling_verify on;

    # PhotoPrism 反向代理设置
    location / {
        # 如果 Nginx 运行在宿主机上，且 PhotoPrism 容器端口映射到宿主机 2343，使用此行
        # proxy_pass http://localhost:2343; 

        # 如果 Nginx 也是 Docker 容器并与 PhotoPrism 在同一 Docker 网络中，使用此行
        proxy_pass http://photoprism_container_name:2342; 

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

注意： proxy_pass 的地址取决于您的 Nginx 部署方式。请根据您的实际情况选择 localhost:2343 或 photoprism_container_name:2342。

5.2 重启 Nginx 服务

配置更新后，重新加载 Nginx 配置使其生效：

sudo systemctl restart nginx

6. 访问 PhotoPrism

现在，您可以通过配置的域名 https://yourdomain.com/ 访问 PhotoPrism。

  • 默认用户名: admin (如果您未修改)
  • 默认密码: your_photoprism_admin_password (根据您的 PHOTOPRISM_ADMIN_PASSWORD 设置)

登录后，上传大量图片或进行分享操作，您会明显感受到性能的提升，卡顿现象将得到显著缓解。

7. 常见问题排查

  • 数据库连接失败： 检查 Docker 网络配置，确保 PhotoPrism 和 MariaDB 在同一网络，且 PHOTOPRISM_DATABASE_SERVER 地址正确。检查 MariaDB 用户权限和监听端口。
  • 域名无法访问： 检查 Nginx 配置、SSL 证书路径、DNS 解析是否正确。确保宿主机防火墙允许 80/443 端口流量。
  • PhotoPrism 报错 HTTPS 错误： 确保 PHOTOPRISM_SITE_URL 使用 https 协议，并且反向代理配置正确处理了 SSL。

8. 结论

通过将 PhotoPrism 的数据库从 SQLite 迁移到 MariaDB，我们成功解决了在大规模图片库下 PhotoPrism 的性能瓶颈。容器化部署简化了环境管理，而反向代理则提供了安全的 HTTPS 访问和友好的域名支持。这一优化步骤对于希望搭建高性能、稳定照片管理平台的 PhotoPrism 用户至关重要。

PhotoPrism 与 MariaDB 数据库集成
https://www.quietphoenix.top/archives/photoprism-yu-mariadb-shu-ju-ku-ji-cheng
作者
QuietPhoenix
发布于
更新于
许可
技术 docker