📷 简·相册

Simple Gallery — 轻量级多用户私有相册 · 部署使用维护指南

一、项目简介

简·相册（Simple Gallery）是一款基于 Flask + SQLite + ffmpeg 构建的轻量级多用户私有相册系统。支持图片/视频上传、在线预览、文件夹分类管理，Docker 一键部署于家庭 NAS，让家庭记忆私有化、安全化。

核心特性：多用户独立空间 · 图片视频上传预览 · 视频自动生成缩略图 · 文件夹分类 · 管理员面板 · ZIP 打包下载 · PWA 移动端支持 · 密码安全哈希存储

二、环境要求

项目要求
操作系统Linux（NAS / VPS / 树莓派），推荐绿联 NAS 等 Docker 兼容设备
Docker20.10+
Docker Composev2+
端口5003（可自定义）
存储空间根据实际使用量，建议预留充足空间存放图片和视频

三、快速部署

1准备项目目录 
mkdir -p /your-path/simple-gallery
cd /your-path/simple-gallery
2创建 docker-compose.yml

在项目目录下创建 docker-compose.yml 文件，内容如下：

services:
  gallery:
    image: your-registry/simple-gallery:latest
    container_name: simple-gallery
    ports:
      - "5003:5003"
    volumes:
      - ./uploads:/app/uploads
      - ./data:/app/data
      - ./icon.png:/app/icon.png
    environment:
      - DEFAULT_PASS=${DEFAULT_PASS:-admin123}
      - SECRET_KEY=${SECRET_KEY:-}
    restart: always
⚠️ 注意：请将 your-registry/simple-gallery:latest 替换为实际的镜像地址。
3准备图标文件

在项目目录下放置一个 icon.png（180×180px），用作 PWA 图标。如无特殊需求，可使用任意纯色 PNG。

4启动容器 
sudo docker compose up -d
5访问系统

浏览器打开 http://你的NAS-IP:5003，使用默认管理员账号登录：

用户名admin
密码admin123（建议首次登录后修改）

四、环境变量配置

变量名说明默认值
DEFAULT_PASS首次启动时创建 admin 用户的密码admin123
SECRET_KEYFlask 会话加密密钥随机生成
💡 建议：生产环境请务必修改 DEFAULT_PASS，并设置一个固定的 SECRET_KEY 以保证重启后用户会话不丢失。

修改环境变量后，重新启动容器：

sudo docker compose down
sudo docker compose up -d

五、使用指南

5.1 普通用户

  1. 登录：打开浏览器输入网址，使用管理员分配的账号密码登录
  2. 创建文件夹：点击右下角 + 按钮，输入文件夹名称
  3. 进入文件夹：点击文件夹卡片进入
  4. 上传文件：点击右下角 + 按钮，选择图片或视频（支持多选）
  5. 浏览文件：点击缩略图进入全屏预览模式
  6. 切换文件：全屏模式下，移动端左右滑动切换，桌面端点击左右箭头或键盘 ← → 键

支持的文件格式：

类型格式
图片PNG / JPG / JPEG / GIF / WebP / BMP / HEIC / HEIF
视频MP4 / MOV / AVI / MKV / 3GP / WMV / FLV / WebM
ℹ️ 视频文件上传后会自动生成首帧缩略图（需 ffmpeg 支持，已在镜像中预装）。

5.2 管理员

管理员除了具备普通用户的所有功能外，还可通过管理面板进行：

  1. 点击右上角 "管理" 进入管理面板
  2. 用户管理：添加新用户、删除用户（删除用户时其所有文件夹和文件将被清除）
  3. 文件夹下载：选择用户 → 查看其文件夹 → 点击下载 ZIP
⚠️ 警告：删除用户操作不可逆，其所有数据将被永久删除，请谨慎操作。

六、日常维护命令

6.1 查看运行状态

sudo docker compose ps

6.2 查看日志

# 实时查看
sudo docker compose logs -f

# 查看最近 100 条
sudo docker compose logs --tail=100

6.3 重启容器

sudo docker restart simple-gallery

6.4 停止/启动

# 停止
sudo docker compose down

# 启动
sudo docker compose up -d

6.5 更新镜像

sudo docker compose down
sudo docker compose pull    # 拉取最新镜像
sudo docker compose up -d

6.6 重置管理员密码

如忘记管理员密码，可删除数据库文件后重启容器（系统将自动重建并创建默认管理员）：

sudo docker compose down
sudo rm -rf ./data/users.db
sudo docker compose up -d
⚠️ 注意：此操作将删除所有用户数据，仅保留上传文件。请先备份 ./data 目录。

七、数据备份与恢复

7.1 备份

定期备份以下两个目录即可：

# 打包备份
tar -czf simple-gallery-backup-$(date +%Y%m%d).tar.gz ./data ./uploads

7.2 恢复

# 先停止容器
sudo docker compose down

# 解压恢复
tar -xzf simple-gallery-backup-20260701.tar.gz

# 重新启动
sudo docker compose up -d

八、常见问题（FAQ）

Q：视频上传后没有缩略图？
A：请确认镜像中包含 ffmpeg。进入容器执行 docker exec -it simple-gallery ffmpeg -version 验证。
Q：上传大文件失败？
A：系统默认限制 500MB。如果通过 Nginx 反代，请同步调整 client_max_body_size 参数。
Q：如何配置 Nginx 反向代理？

在 Nginx 配置中添加以下内容：

location /gallery {
    proxy_pass http://127.0.0.1:5003;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    client_max_body_size 500m;
}
Q：如何在手机上使用？
A：浏览器访问即可，系统已适配移动端。iOS Safari 可点击"分享"→"添加到主屏幕"获得类 App 体验。
Q：能否自定义端口？
A：可以。修改 docker-compose.yml 中左侧端口号（如 "8080:5003"），然后重启容器。
Q：支持 HTTPS 吗？
A：系统本身不处理 HTTPS，建议通过 Nginx/Caddy 反代后配置 SSL 证书。

九、项目目录结构

simple-gallery/
├── docker-compose.yml
├── icon.png              # PWA 图标
├── uploads/              # 用户上传文件（自动生成）
│   └── 用户名/
│       └── 文件夹名/
│           ├── uuid.mp4
│           └── uuid.mp4.thumb.jpg
├── data/
│   └── users.db          # 用户数据库（自动生成）
└── tmp/                  # ZIP 临时文件（自动生成）
DAFILI · 简·相册 — 让家庭记忆安全私有化