llamaq/photius

Photius

Photius 是一款朴实无华的开源多架构"主力工具"，用于维护个人家庭照片和视频档案的健康状态。

功能概述

Photius 持续监控输入目录 /opt/src 中的媒体文件（图片和视频），对其执行各种优化操作，然后将文件移动到输出目录 /opt/dest，并按 YYYY/MM/DD 子文件夹结构进行整理。

核心处理操作

目前 Photius 对媒体文件执行以下操作：

• 使用 jpegoptim 进行 JPEG 质量优化
• 使用 exiftran 根据 EXIF 方向标签进行自动无损旋转
• 使用 OptiPNG 优化 PNG 文件，在不丢失语义信息的前提下减小文件大小，同时执行错误恢复（对有效文件无影响）
• 使用 ffmpeg（libx265 hvc1）转换 MP4 视频
• 使用 exiftool 从文件名和文件属性设置 EXIF DateTimeOriginal（若该字段不存在）
• 使用 exiftool 清理 EXIF 信息
• 转换文件扩展名为小写
• 优化 Google 相机拍摄的 "photoboost" 照片文件名
• 将原始文件的 MD5 哈希值设置为 "Image Unique ID" EXIF 字段，供照片管理软件使用

Photius 会尽量减少系统资源占用，确保在处理文件时不影响正常电脑使用。

注意：该软件处于早期测试阶段，请定期备份数据。

使用方法

bash
docker run -it --restart unless-stopped \
    --name photius \
    -v /srv/webdav:/opt \
    llamaq/photius

参数与环境变量

卷挂载点

• /opt: 基础卷目录
  • /opt/src: 输入目录（如需独立于基础目录可单独挂载）
  • /opt/temp: 临时目录（如需独立于基础目录可单独挂载）
  • /opt/fail: 处理错误文件存放目录（如需独立于基础目录可单独挂载）
  • /opt/dest: 最终目标目录（如需独立于基础目录可单独挂载）

权限设置

使用卷挂载（-v 标志）时，主机 OS 与容器可能出现权限问题。可通过指定用户 PUID 和组 PGID 解决，例如 -e PUID=1000 -e PGID=1000。默认值均为 1000。

环境变量

实际使用场景

家庭/云服务器

• 将 /opt 指向 WebDAV/FTP/Samba 等服务器目录，上传媒体文件至 src 目录。可使用 https://hub.docker.com/r/llamaq/nginx-extras 作为 WebDAV 服务器基础。
• 如需在多地点（家庭服务器、云服务器、笔记本）同步媒体档案，推荐使用开源工具 Syncthing。在各服务器位置安装 photius、nginx-extras 和 syncthing 容器，实现跨设备媒体同步。

移动设备（Android/iOS）

• 如需在 iOS/Android 设备与电脑、云服务、NAS 间无线传输照片视频，推荐使用 PhotoSync。使用 WebDAV 上传时，建议将文件名格式设为"拍摄日期"（因 WebDAV 不保留文件日期），确保无 EXIF 元数据的媒体（如 / 下载图片）或不支持 EXIF 的格式（如 GIF）能保留创建日期。
• 如需保留父目录名称（通常对应应用名），可在 FolderSync 中设置"创建子目录"为"文件夹名称"，并启用容器的 PHOTIUS_RENAME_DATETIMEORIGINAL。也可在 FolderSync 中设置自定义格式为"拍摄日期+文件夹名称"（YR%mR%dR_%HR%MR%SR_%FP），此时无需启用 PHOTIUS_RENAME_DATETIMEORIGINAL。

高级使用示例

通过 PHOTIUS_SKIP_PICTURES 和 PHOTIUS_SKIP_VIDEOS 可同时运行两个 Photius 实例，分别处理图片和视频，避免处理队列阻塞（视频处理通常比图片耗时更长）：

bash
# 图片处理实例
docker run -it --restart unless-stopped \
    --name photius_pictures \
    -v /srv/webdav:/opt \
    -e PHOTIUS_FAILURE_THRESHOLD=300 \
    -e PHOTIUS_SKIP_VIDEOS=1 \
    llamaq/photius

# 视频处理实例
docker run -it --restart unless-stopped \
    --name photius_videos \
    -v /srv/webdav:/opt \
    -e PHOTIUS_FAILURE_THRESHOLD=3600 \
    -e PHOTIUS_SKIP_PICTURES=1 \
    llamaq/photius

贡献与资源

• 源码：https://github.com/llamaqcom/photius-docker
• Bug 报告：https://github.com/llamaqcom/photius-docker/issues
• Docker 镜像：https://hub.docker.com/r/llamaq/photius

许可证

本容器及其代码采用 MIT 许可证，按"原样"提供，不提供任何形式的担保。

与所有 Docker 镜像一样，其中可能包含其他软件，这些软件可能采用其他许可证（如基础发行版中的 Bash 等，以及主要软件的直接或间接依赖项）。

对于任何预构建镜像的使用，镜像用户有责任确保对该镜像的任何使用符合其中包含的所有软件的相关许可证。