搬瓦工搭建 PhotoPrism 私人照片库完整教程

PhotoPrism 是一款功能强大的开源照片管理平台，内置 AI 驱动的自动分类、人脸识别、地理位置标注和 RAW 格式处理等特性。它可以作为 Google Photos 的自托管替代品，让你完全掌控自己的照片数据。本文将介绍如何在搬瓦工 VPS 上使用 Docker Compose 部署 PhotoPrism。

一、准备工作

1.1 系统要求

操作系统：Ubuntu 20.04+（推荐 Ubuntu 22.04）。
内存：至少 2GB，推荐 4GB 以上（AI 分类需要较多内存）。
磁盘空间：程序和数据库约 2GB，照片文件按需准备。
Docker：需提前安装，参考 Docker 安装教程。

1.2 创建目录

mkdir -p /opt/photoprism/originals
mkdir -p /opt/photoprism/storage
mkdir -p /opt/photoprism/import
mkdir -p /opt/photoprism/database

二、Docker Compose 部署

2.1 创建配置文件

cd /opt/photoprism
cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    depends_on:
      - mariadb
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "your_secure_password"
      PHOTOPRISM_AUTH_MODE: "password"
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "db_password"
      PHOTOPRISM_SITE_CAPTION: "我的照片库"
      PHOTOPRISM_SITE_DESCRIPTION: "私人照片管理平台"
      PHOTOPRISM_SITE_AUTHOR: ""
      PHOTOPRISM_DETECT_NSFW: "false"
      PHOTOPRISM_UPLOAD_NSFW: "true"
      TZ: "Asia/Shanghai"
    volumes:
      - ./originals:/photoprism/originals
      - ./storage:/photoprism/storage
      - ./import:/photoprism/import

  mariadb:
    image: mariadb:11
    container_name: photoprism-db
    restart: unless-stopped
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "db_password"
      MARIADB_ROOT_PASSWORD: "root_password"
    volumes:
      - ./database:/var/lib/mysql
EOF

请将 your_secure_password、db_password 和 root_password 替换为你自己的安全密码。

2.2 启动服务

docker compose up -d

首次启动需要初始化数据库和 AI 模型，可能需要几分钟。查看日志：

docker compose logs -f photoprism

2.3 访问界面

启动完成后，浏览器访问 http://你的服务器IP:2342，使用配置文件中设置的管理员用户名和密码登录。

三、上传照片

3.1 通过 Web 界面上传

登录后点击右上角的上传按钮，可以直接从浏览器上传照片。支持批量上传和拖拽上传。

3.2 通过命令行上传

# 上传到 import 目录
scp -r 照片文件夹/ root@你的服务器IP:/opt/photoprism/import/

# 触发导入
docker exec photoprism photoprism import

也可以直接上传到 originals 目录，然后执行索引：

scp -r 照片文件夹/ root@你的服务器IP:/opt/photoprism/originals/
docker exec photoprism photoprism index

3.3 支持的格式

PhotoPrism 支持广泛的图片和视频格式，包括 JPEG、PNG、GIF、HEIF/HEIC、WebP、TIFF 等。对于 RAW 格式（CR2、NEF、ARW、DNG 等），PhotoPrism 会自动生成 JPEG 预览。视频方面支持 MP4、MOV、AVI 等。

四、AI 功能

4.1 自动分类

PhotoPrism 使用 TensorFlow 模型自动识别照片中的内容（如动物、植物、建筑、食物等），并自动添加标签。这些标签可以用于搜索和筛选。

4.2 人脸识别

PhotoPrism 可以自动检测照片中的人脸，并将相似面孔归为同一人。在「人物」页面中，你可以为检测到的面孔命名，之后即可通过姓名搜索照片。

4.3 地图浏览

如果照片包含 GPS 位置信息（EXIF 数据），PhotoPrism 会在地图上标注拍摄位置，你可以通过地图界面浏览不同地点的照片。在「地点」页面中即可使用此功能。

五、性能优化

5.1 降低内存占用

在资源有限的 VPS 上，可以通过以下环境变量降低内存占用：

      PHOTOPRISM_WORKERS: 1
      PHOTOPRISM_THUMB_UNCACHED: "false"
      PHOTOPRISM_THUMB_SIZE: 1280
      PHOTOPRISM_THUMB_SIZE_UNCACHED: 1280
      PHOTOPRISM_JPEG_SIZE: 2048
      PHOTOPRISM_JPEG_QUALITY: 85

5.2 预生成缩略图

上传大量照片后，建议手动预生成缩略图以提升浏览体验：

docker exec photoprism photoprism thumbs -f

六、Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name photos.example.com;

    ssl_certificate /etc/letsencrypt/live/photos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/photos.example.com/privkey.pem;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1: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;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_buffering off;
    }
}

配置反向代理后，记得将 PHOTOPRISM_SITE_URL 更新为你的域名地址。

七、维护与备份

7.1 更新 PhotoPrism

cd /opt/photoprism
docker compose pull
docker compose down
docker compose up -d

7.2 备份数据

# 导出数据库
docker exec photoprism-db mariadb-dump -u photoprism -pdb_password photoprism > photoprism-db.sql

# 备份配置和索引
tar -czf photoprism-storage-backup.tar.gz -C /opt/photoprism storage/

7.3 查看日志

docker compose logs --tail=100 photoprism

总结

PhotoPrism 是 Google Photos 的优秀自托管替代品，其 AI 分类和人脸识别功能让照片管理变得智能高效。在搬瓦工 VPS 上部署后，你可以完全掌控自己的照片数据，不必担心隐私泄露。选购搬瓦工 VPS 请参考全部方案，建议选择至少 2GB 内存的方案以获得最佳体验。购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。如遇问题，可前往搬瓦工官网提交工单。