Piwigo 从 2002 年维护至今，是开源相册里的老牌项目。它不靠 AI 吸引人，而是靠扎实的相册管理、用户组权限和 200 多个插件主题。如果你们家是「一个相册，多个成员，各看各的」，Piwigo 的权限模型比大多数新项目都细。
一、镜像与端口
| 项目 | 值 |
|---|---|
| 应用镜像 | piwigo/piwigo:latest（Docker Hub） |
| 数据库 | docker.io/library/mariadb:lts |
| Web 端口 | 容器 80，宿主机默认 8080 |
| 数据目录 | ./piwigo-data/piwigo、./piwigo-data/mysql |
二、下载官方 Compose 与 .env
mkdir -p /opt/piwigo && cd /opt/piwigo
curl -O https://raw.githubusercontent.com/Piwigo/piwigo-docker/refs/heads/main/compose.yaml
mv compose.yaml docker-compose.yml
新建 .env（密码用随机字符串，别用示例值）：
piwigo_port=8080
db_user_password=请替换成随机强密码
timezone=Asia/Shanghai
PIWIGO_UID=1000
PIWIGO_GID=1000
Compose 内容很直接：
services:
piwigo-main:
image: piwigo/piwigo:latest
restart: always
environment:
- TZ=${timezone}
- PIWIGO_UID=${PIWIGO_UID}
- PIWIGO_GID=${PIWIGO_GID}
ports:
- ${piwigo_port}:80
depends_on:
- piwigo-db
volumes:
- ./piwigo-data/piwigo:/var/www/html/piwigo/
- ./piwigo-data/scripts:/usr/local/bin/scripts/
piwigo-db:
image: docker.io/library/mariadb:lts
restart: always
environment:
- MARIADB_RANDOM_ROOT_PASSWORD=true
- MARIADB_USER=piwigodb_user
- MARIADB_DATABASE=piwigodb
- MARIADB_PASSWORD=${db_user_password}
- TZ=${timezone}
volumes:
- ./piwigo-data/mysql:/var/lib/mysql
三、启动与安装向导
docker compose up -d
docker compose logs -f piwigo-main
打开 http://服务器IP:8080，Piwigo 会检测到尚未安装，跳转到安装页。数据库填写：
| 字段 | 值 |
|---|---|
| 主机 | piwigo-db:3306 |
| 用户 | piwigodb_user |
| 密码 | .env 里的 db_user_password |
| 数据库名 | piwigodb |
| 表前缀 | piwigo_ |
再填管理员账号、密码和邮箱，点「开始安装」。完成后用管理员登录，进入管理面板。
四、建立相册与权限
- 「相册 → 添加相册」，建立「2026 春节」「孩子成长」等目录。
- 上传照片：网页上传，或把文件放进服务器目录后用「工具 → 同步」批量导入。
- 「用户 → 添加用户」创建家庭成员，把用户加入组。
- 「相册 → 管理 → 权限」按组授权：谁能看、谁能上传。
- 安装主题（如 Bootstrap Darkroom）和水印、地图等插件，按需开启。
五、反向代理与 HTTPS
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 2000M;
location / {
proxy_pass http://127.0.0.1:8080/;
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;
}
}
如果放在子路径（如 /gallery），加 proxy_set_header X-Forwarded-Prefix /gallery;，官方文档有完整示例。
六、备份与升级
- 备份
piwigo-data/piwigo（程序与上传图片）和piwigo-data/mysql（数据库）。 - 升级：先备份，再
docker compose pull && docker compose up -d；跨大版本按官方 Docker Update 文档执行数据库升级。 - 照片多时建议把
./piwigo-data/piwigo/_data放到独立磁盘。
七、常见问题
上传大照片失败？ 检查 PHP 的 upload_max_filesize、post_max_size 和反代的 client_max_body_size。
中文界面？ 安装后在「管理 → 语言」里启用中文并设为默认。
有没有手机自动备份？ Piwigo 本身没有官方自动备份 App，可用 FTP 同步、Web 上传或第三方客户端；要自动备份优先选 Immich。
八、小结
Piwigo 的强项是「管理」：成员、相册、权限、插件都能细调。它更像一个家庭内部的照片门户，而不是手机相册的云端备份盘。
相关阅读：Lychee 部署教程 · 2026 开源家庭相册横评
