在 VPS 上搭一个 Piwigo 活动相册

活动照片分散在几个人的电脑里，后来写回顾文章时很难找到原图。Piwigo 适合按活动、项目和时间整理照片，并给固定成员提供浏览入口。

VPS 的磁盘和流量要按实际照片量估算。它是照片库，不能仅因网页中有“私有相册”就假定所有原图地址都受相同保护；上传真实资料前需要实际检查访问。

安装相册和数据库

以下命令在 Linux VPS 上执行，需要有 Docker 操作权限。先运行 docker version 和 docker compose version，确认引擎与 Compose v2 都能工作。没有安装 Docker 时，按 Docker 官方安装说明选择对应发行版；不要把其他发行版的仓库配置直接复制过来。

示例工作目录为 /opt/piwigo，所有相对路径都以这个目录为基准。VPS_IP、SSH 用户和示例域名需要换成自己的值。端口 8087 若已被占用，只改映射左侧的宿主机端口，并同步修改访问地址。

sudo install -d -m 0750 -o "$(id -u)" -g "$(id -g)" /opt/piwigo
cd /opt/piwigo
umask 077

创建 .env，用户编号来自 id -u 和 id -g，两个数据库密码分别随机生成：

PUID=REPLACE_WITH_YOUR_UID
PGID=REPLACE_WITH_YOUR_GID
DB_PASSWORD=REPLACE_WITH_RANDOM_DB_PASSWORD
DB_ROOT_PASSWORD=REPLACE_WITH_RANDOM_ROOT_PASSWORD

mkdir -p config gallery database
chmod 600 .env

初次打开安装页时，数据库服务器填 db，库名与用户名填 piwigo，密码采用上面的普通数据库密码；不要使用 root。另设自己的相册管理员账号。

将下面内容保存为 compose.yaml：

services:
  piwigo:
    image: lscr.io/linuxserver/piwigo:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8087:80"
    environment:
      PUID: ${PUID:?set uid}
      PGID: ${PGID:?set gid}
      TZ: Asia/Shanghai
    volumes:
      - ./config:/config
      - ./gallery:/gallery
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: piwigo
      MARIADB_USER: piwigo
      MARIADB_PASSWORD: ${DB_PASSWORD:?set db password}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:?set root password}
    volumes:
      - ./database:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

在工作目录启动并检查日志：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

启动后按下面的步骤试用。遇到目录不可写的报错，先核对 UID 和挂载路径，不要直接改成 chmod 777。

用 SSH 隧道打开界面

示例仅把应用端口发布到 VPS 的 127.0.0.1。在自己的电脑上运行以下命令，保留终端窗口，再打开 http://127.0.0.1:8087：

ssh -N -L 8087:127.0.0.1:8087 your_ssh_user@VPS_IP

浏览器里的回环地址是自己的电脑，SSH 把请求转到 VPS。若本地同号端口被占用，可换隧道左侧端口；涉及应用外部 URL 的项目也要一起调整。管理界面无需因此开放公网端口。

先拿十张测试照片建相册

建立一个活动相册，上传几张带有不同方向和尺寸的测试照片，检查缩略图、横竖图显示与原图下载。给照片加日期和可检索的关键词，别只靠文件名。

新建普通访问者，将测试相册设为仅指定用户可见。用这个账号、未登录窗口以及复制出的原图地址分别访问，记录实际访问结果。如果原图可直接公开访问，就不要上传要求严格保密的照片，先处理访问保护。

照片可能包含 GPS、拍摄时间和设备信息。发布前检查原图 EXIF，按需要在上传前移除；不能默认上传软件已经替你清理。

多人使用时优先让一个管理员整理分类与权限，避免大家随手新增几十个类似相册。独立主题和插件逐个测试，先完成稳定的上传与检索。

照片和数据库要对应同一时点

照片目录与 MariaDB 必须对应同一时点。恢复后检查相册顺序、原图、缩略图、用户权限和一个带附件的记录；少了数据库会丢分类，少了照片目录只剩记录。

在工作目录执行下面的停机备份，压缩包保存在应用目录之外。停止全部服务会带来短暂不可用；确认停止成功后再打包。

docker compose stop
sudo install -d -m 0700 /var/backups/docker-apps
backup_file="/var/backups/docker-apps/$(basename "$PWD")-$(date +%Y%m%d-%H%M%S).tar.gz"
sudo tar -czpf "$backup_file" compose.yaml config gallery database .env
sudo chmod 0600 "$backup_file"
sudo tar -tzf "$backup_file" | head
docker compose start

将压缩包复制到 VPS 之外。恢复时，在另一台测试机器的空目录解包，保留文件所有者和相对路径，用原镜像版本启动，检查前面提到的数据。不要直接覆盖正在使用的原数据目录。

升级前先记录镜像 ID 或摘要，并保存这份备份。阅读项目更新说明后再拉取镜像；涉及数据库迁移时，回滚需要恢复旧数据与旧镜像，不能只把标签改回去。

安装参数和数据路径可对照LinuxServer Piwigo 文档。