Foldergram 配置完全指南:环境变量、DERIVATIVE_MODE 与 IMAGE_DETAIL_SOURCE 详解

原创2026-11-16 11:47:141,993 阅读

Foldergram 配置完全指南:环境变量、DERIVATIVE_MODE 与 IMAGE_DETAIL_SOURCE 详解

Foldergram 是一款自托管的、文件夹驱动的照片视频相册应用(Self-hosted folder-based photo and video gallery app),它把本地文件夹变成类似 Instagram 的浏览界面,同时保持原片不动。对新手来说,最核心的上手环节就是配置:Foldergram 通过仓库根目录的 .env 文件读取环境变量,其中 DERIVATIVE_MODE 决定缩略图和预览图是"扫描时生成"还是"首次请求时生成",IMAGE_DETAIL_SOURCE 则决定图片详情页展示预览图还是原图。本文带你逐项看懂 Foldergram 的环境变量,帮你一次配好、少踩坑。

Foldergram 自托管照片视频相册应用界面与功能特性概览

配置从哪里来:.env 文件如何生效

  • 源码安装时,Foldergram 从仓库根目录读取 .env,并在 server/src/config/env.ts 中用 Zod 模式做严格校验:非法取值会直接让启动失败,而不是悄悄使用默认值。
  • 仓库提供了 .env.example 模板,包含全部运行时配置项。最常见的做法是:
cp .env.example .env
  • 默认的 Docker Compose 部署使用镜像内置的生产默认值加挂载的 ./data/... 卷,并不会直接读取源码里的 .env,需要自行在 Compose 文件中设置。

更完整的配置说明见 docs/configuration.md,媒体处理细节见 docs/media-processing.md。

环境变量全览:一张表看懂默认值

变量 默认值 说明
NODE_ENV development 只能是 development、test、production
SERVER_PORT 4141 生产模式 Express 端口,Docker 默认映射到该端口
DEV_SERVER_PORT 4140 pnpm dev 时的后端端口
DEV_CLIENT_PORT 4141 Vite 前端端口,可自动向上顺延到 4144
DATA_ROOT ./data 应用存储的根目录,其他存储路径默认挂在它下面
GALLERY_ROOT ./data/gallery 相册源媒体根目录,Foldergram 只扫描它下面的文件夹
DB_DIR ./data/db SQLite 数据库目录,文件名为 gallery.sqlite
THUMBNAILS_DIR ./data/thumbnails 缩略图输出目录
PREVIEWS_DIR ./data/previews 预览图/预览视频输出目录
GALLERY_EXCLUDED_FOLDERS 未设置 逗号分隔的排除文件夹规则
IMAGE_DETAIL_SOURCE preview 图片详情页用预览图还是原图
DERIVATIVE_MODE eager 派生图生成时机:扫描时 vs 首次请求时
LOG_VERBOSE 0 详细日志开关(1/true/yes/on 生效)
SCAN_MEDIA_ERROR_MODE skip 扫描遇到坏文件时跳过还是立即失败
SCAN_DISCOVERY_CONCURRENCY 4 文件发现并发数,范围 1–32
SCAN_DERIVATIVE_CONCURRENCY 4 派生图生成并发数,范围 1–32
PUBLIC_DEMO_MODE 0 开启后写操作接口返回 403,适合只读演示部署
CSRF_TRUSTED_ORIGINS 未设置 反向代理场景下的额外可信来源

最小可用配置

大多数用户只需要改两个变量就能跑起来:

DATA_ROOT=./data
GALLERY_ROOT=/your/photo/library

其余路径会自动落在 DATA_ROOT 之下:数据库、缩略图、预览图互不干扰。

存储路径配置:DATA_ROOT 与 GALLERY_ROOT 的解析规则

路径解析是新手最容易困惑的地方,Foldergram 的规则其实很清晰:

  • 只设 DATA_ROOT:例如 DATA_ROOT=/mnt/foldergram,则默认路径自动变为 /mnt/foldergram/gallery、/mnt/foldergram/db、/mnt/foldergram/thumbnails、/mnt/foldergram/previews。
  • 单独覆盖:GALLERY_ROOT、DB_DIR、THUMBNAILS_DIR、PREVIEWS_DIR 任意一个都只覆盖自身,不影响其他路径。
  • 相对路径以仓库根目录为基准解析;绝对路径原样使用。
  • THUMBNAILS_DIR 和 PREVIEWS_DIR 必须是两个互不重叠的独立目录,且都不能嵌套在 GALLERY_ROOT 内部,否则启动时会抛出 Invalid storage configuration 错误。
  • GALLERY_ROOT 只需要读权限;数据库和派生图目录必须可写。

提示:如果数据库、缩略图或预览目录恰好位于相册目录树内部,Foldergram 会自动把它们排除出扫描范围,防止生成的文件被当成源媒体再次索引。

DERIVATIVE_MODE 详解:eager 与 lazy 两种生成时机

派生图(derivatives)指 Foldergram 为加速浏览而生成的缩略图(宽 640 的 WebP)和预览图(宽 1500 的 WebP)。DERIVATIVE_MODE 控制它们什么时候生成,取值只有两个:

模式 行为 适合场景
eager(默认) 扫描时就把缩略图和预览图全部生成好,之后浏览全部走本地缓存,响应最快 库规模不大、希望"一次处理、长期流畅"
lazy 扫描只索引元数据;缺失的缩略图/预览在第一次请求 /thumbnails/... 或 /previews/... 时才生成,并缓存到磁盘 大库、老机器,希望快速完成首次扫描

几个关键细节:

  • lazy 模式不会"永远慢":首次请求某个文件时会生成并落盘,后续请求直接读缓存文件。
  • lazy 模式下,设置页的扫描动作和 Rebuild Library Index 都不会预生成派生图;Regenerate Thumbnails 只会重建缩略图和海报图,不会重建预览。
  • 符合"直连播放"条件的视频(.mp4 + H.264 + yuv420p + AAC/无声 + 不超过 24 MiB + 显示宽度不超过 1500px,策略定义在 server/src/utils/video-playback-policy.ts)始终只生成海报图,跳过可播放预览。
  • 派生图按 asset_key 分片存储(如 thumbnails/ab/<asset_key>.webp),移动文件夹不会导致缓存失效。

IMAGE_DETAIL_SOURCE 详解:详情页看预览图还是原图

IMAGE_DETAIL_SOURCE 只影响图片详情页,取值两个:

取值 行为
preview(默认) /image/:id 使用生成的预览资产,加载快、流量小
original /image/:id 改为走 /api/originals/:id 流式输出原图,细节完整

需要注意的边界:

  • 它不会影响信息流卡片、文件夹网格、头像等列表界面;
  • 它不会改变任何视频的播放行为,视频始终遵循直连播放策略。

官方推荐组合

目标 建议配置
保持当前默认体验 IMAGE_DETAIL_SOURCE=preview + DERIVATIVE_MODE=eager
大库最低前置处理开销 IMAGE_DETAIL_SOURCE=original + DERIVATIVE_MODE=lazy

也就是说:机器配置一般、照片库很大时,把这两项组合起来,首次扫描会非常快,浏览时按需生成即可。

扫描与日志:SCAN_MEDIA_ERROR_MODE 和并发调优

SCAN_MEDIA_ERROR_MODE(默认 skip)控制扫描中遇到损坏的受支持媒体时怎么办:

  • skip:记录错误、跳过该文件、继续扫描,最终状态为 completed_with_errors。完整报告写入 <DATA_ROOT>/scan-errors/,设置页会给出报告路径。
  • fail:遇到第一个错误立即中止扫描。

并发参数(范围均为 1–32,默认 4):

  • SCAN_DISCOVERY_CONCURRENCY:影响文件系统 stat 和元数据发现;
  • SCAN_DERIVATIVE_CONCURRENCY:影响 Sharp 和 FFmpeg 的派生图任务。

实践建议:小机器保持默认;只有当存储足够快、CPU/内存/磁盘带宽都跟得上时,才值得上调。

访问控制相关环境变量

  • PUBLIC_DEMO_MODE=1:所有写操作接口返回 403,适合公开只读展示相册;
  • CSRF_TRUSTED_ORIGINS:逗号分隔的额外可信浏览器来源。部署在反向代理或 HTTPS 终结器后面、浏览器可见域名与上游主机不一致时必须设置,否则变更类请求会被拦截;
  • 共享密码保护不放在 .env 里:它在设置页开启,密码哈希存在 SQLite 的 app_settings 表中;删除数据库文件会重置该保护状态。

配置校验清单:改完 .env 前自查一遍

  1. NODE_ENV 是否为三选一合法值,生产部署记得设为 production(此时才使用 SERVER_PORT);
  2. GALLERY_ROOT 指向的目录里,媒体要放在子文件夹内——直接放在根目录下的文件会被忽略;
  3. THUMBNAILS_DIR、PREVIEWS_DIR 与 GALLERY_ROOT 无嵌套关系,且两者互不重叠;
  4. DB_DIR 建议放在本地文件系统,不要放在 NFS/SMB 等网络存储上;
  5. 反向代理部署时设置了 CSRF_TRUSTED_ORIGINS;
  6. 大库选择了 lazy + original 组合来降低首扫开销。

改完 .env 后重启服务(Docker 部署执行 docker compose up -d),启动时若路径配置非法,server/src/config/env.ts 会抛出明确的 Invalid storage configuration 错误,按提示修正即可。

总结

Foldergram 的配置体系以 .env 为中心、启动时强校验:路径类变量决定数据落在哪里,DERIVATIVE_MODE 决定派生图是"扫描时"还是"请求时"生成,IMAGE_DETAIL_SOURCE 决定详情页看预览还是原图,SCAN_MEDIA_ERROR_MODE 与并发参数决定扫描的健壮性和速度。抓住这几个开关,你就能按机器性能和内容库规模,把 Foldergram 调成最顺手的状态。

登录后查看全文
foldergram