Foldergram 配置完全指南:环境变量、DERIVATIVE_MODE 与 IMAGE_DETAIL_SOURCE 详解
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 的环境变量,帮你一次配好、少踩坑。
配置从哪里来:.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 前自查一遍
NODE_ENV是否为三选一合法值,生产部署记得设为production(此时才使用SERVER_PORT);GALLERY_ROOT指向的目录里,媒体要放在子文件夹内——直接放在根目录下的文件会被忽略;THUMBNAILS_DIR、PREVIEWS_DIR与GALLERY_ROOT无嵌套关系,且两者互不重叠;DB_DIR建议放在本地文件系统,不要放在 NFS/SMB 等网络存储上;- 反向代理部署时设置了
CSRF_TRUSTED_ORIGINS; - 大库选择了
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 调成最顺手的状态。
