LibrePhotos 设置体系全解从个人资料、扫描元数据规则到站点级管理【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotosLibrePhotos 的设置分布在三个层级个人资料Profile、每个用户独立的扫描与保存设置Settings、以及管理员全局管理区Admin Area。这篇指南基于官方文档 settings/index.md 并结合后端源码 models/user.py、models/email_config.py、burst_detection_rules.py 逐项说明每类设置的作用、默认值与底层实现读完你可以完整掌握个人库行为的所有可调项以及管理员如何配置站点级功能、邮件与用户管理。一、三级设置的总体结构LibrePhotos 目前有三类设置Profile个人资料姓名、头像、邮箱、密码、语言与公开性Settings用户设置每个用户独立影响扫描与保存行为底部还有实验性功能开关Admin Area管理区作用于整个实例包括站点设置、邮件配置、管理工具、用户管理与 Worker 日志。从源码结构看第 2 类中的绝大多数设置都持久化在User模型上例如 User 模型 直接携带confidence、semantic_search_topk、save_metadata_to_disk、datetime_rules、burst_detection_rules、default_timezone等字段而第 3 类中的站点设置走 Django Constance 的 JSON schema见 schemas/site_settings.py邮件配置则单独存为一个数据库单例下文详述。这种用户级字段 站点级配置的双轨结构是理解 LibrePhotos 设置体系的关键。二、Profile个人资料设置点击右上角头像选择Profile进入。在这里可以修改姓名、照片、邮箱、密码、语言以及是否允许自己的档案被全局访问Avatar、First name、Last name当你与其他用户共享照片或你的档案公开可访问时展示E-mail密码重置链接的接收地址。登录页的Forgot your password?链接只有在管理员配置了出站邮件Admin Area → Site Settings → Email (SMTP)后才会出现重置自己的密码也要求账号已设置邮箱——若没有管理员仍可在 Admin Area → Users 中替你重置Change password修改密码Language切换界面语言Public Sharing决定你的档案是否能被全局发现。源码层面的印证User.public_sharing字段user.py默认False控制是否进入公开用户发现页公开接口由 PublicUserSerializer 严格白名单化只暴露头像、用户名、姓名、公开照片计数与样例绝不泄露邮箱、扫描目录、Nextcloud 凭据等私有字段。三、Settings用户级扫描与保存设置这些设置只影响当前用户且与扫描和保存如何工作直接相关。下面按文档原文小节逐一展开。3.1 Scan Confidence扫描置信度控制打标签时所需的确定程度默认Standard。对应User.confidence字段源码默认值为 0.1另有一个独立的confidence_person默认 0.9用于人物相册的置信度判定。3.2 Semantic Search语义搜索设置为Top 100、Top 50、Top 10时搜索将返回语义CLIP 嵌入结果而不仅仅依赖 EXIF 数据。默认Disabled——原因是首次搜索需要约一分钟要为整个库计算嵌入之后很快。详见 Search 文档。这一行为在源码中可以完整看到UserSerializer.queue_semantic_search_jobs 在semantic_search_topk从 0 变为正数时会串起一个任务链Chain——若模型未下载先执行download_models再执行batch_calculate_clip_embedding为全部照片计算 CLIP 嵌入。这就是第一次慢、之后快的实现来源。3.3 Metadata Options元数据选项Synchronize metadata to disk启用后将元数据保存到文件本体或 XMP 边车文件。默认Off。对应 User.SaveMetadata 的三个取值OFF、MEDIA_FILE、SIDECAR_FILEMinimum image rating to interpret as favorite改变收藏的读写方式。EXIF 只有 rating 字段而没有 favorite 字段所以用最低评分阈值解释收藏默认4User.favorite_min_rating默认取自settings.DEFAULT_FAVORITE_MIN_RATINGDefault timezone设定 EXIF 时间戳的读写方式默认UTC。该字段取值来自pytz.all_timezones源码并在日期规则解析中作为user_default时区来源被多条内置规则依赖。3.4 Set date time parsing rules日期时间解析规则日期规则允许按顺序定义从哪些来源提取照片时间的管线exifEXIF 标签、path文件名正则、filesystemmtime/ctime、user_defined用户手动设定。规则自上而下依次尝试第一条成功提取时间的规则胜出提取失败则视为不适用、继续下一条。完整机制含时区转换transform_tz/source_tz/report_tz、以及为什么 LibrePhotos 不会替你换算时区的设计理由见 日期规则文档默认规则集定义在 date_time_extractor.py 的DEFAULT_RULES_JSON中。关键实操提醒来自该文档修改规则后必须用Rescan全量重扫而非普通 Scan 才能生效因为普通扫描只处理新增或内容变化的文件若某张照片曾手动改过日期默认列表第一条规则Timestamp set by user会每次重扫回放该值导致其他规则对这张照片永远失效——清空手动时间即可交还给自动规则。3.5 Set burst detection rules连拍检测规则日期规则编辑器下方是Burst Detection Rules编辑器定义 stack 检测寻找连拍序列快速连拍时使用的有序规则列表。规则分两类界面以Hard或Soft徽章标识Hard 规则是确定性判定、默认启用EXIF Burst Mode Tag、EXIF Sequence Number、Filename Burst Pattern匹配IMG_001_BURST001、photo (1)这类文件名Soft 规则是估算型、默认存在但禁用Timestamp Proximity约两秒内、同一相机的照片与Visual Similarity视觉相似的相邻照片。每条规则可开关、删除、拖拽排序Add Rule打开可搜索的规则目录含Filename Burst Suffix Only、Custom Filename Pattern、更宽松的Timestamp Proximity (Loose)约五秒、不限相机Reset to Defaults恢复默认集合。各规则的参数固定、仅供查看没有参数编辑器。这与 burst_detection_rules.py 模块一致BurstRuleTypes定义了exif_burst_mode、exif_sequence_number、filename_patternHard与timestamp_proximity、visual_similaritySoft五类模块头注释明确默认仅启用 hard criteria 规则规则以 JSON 存于每个用户档案User.burst_detection_rules字段按序应用与日期规则器同一设计模式。预置文件名模式还覆盖 Samsung burst_\d{3}_COVER与 iPhone burstIMG_\d{4}_\d等厂商习惯。3.6 Experimental options实验选项Always transcode videos开启后所有视频在播放时按需转码为 h264 以提升兼容性此功能尚未经过充分优化其工作方式是第一次播放时边播边转。直播转码的时长未知因此首播无时长、不能拖动——进度条与快捷键都无效播放器会明确提示这一点观看结束后同样的转码会在后台写入文件事后而非同时因此不会拖慢你正在看的视频之后该视频的每次播放都直接来自这份缓存一个有正常时长、可拖动、可跳转的普通视频。转码副本保存在protected_media/transcoded/下每分钟的存储成本约在 10 到 20 MB 之间取决于画面运动量。该存储有容量上限并会按最久未观看淘汰旧视频管理员可用环境变量调整上限或直接整体关闭。源码印证transcode_cache.py 读取TRANSCODE_CACHE_MAX_GB、TRANSCODE_CACHE_MIN_FREE_GB等设置生产配置 中TRANSCODE_CACHE_ROOT默认为MEDIA_ROOT/transcodedTRANSCODE_CACHE_MAX_GB默认10GB、TRANSCODE_CACHE_MIN_FREE_GB默认2GB设置0可完全关闭缓存、只保留直播转码。完整环境变量说明见 environment-variables.md。用户侧的开关对应User.transcode_videos布尔字段默认False。3.7 Caption Context说明文字上下文这组开关告诉说明captioning模型 LibrePhotos 已经知道照片的哪些信息让说明能说出谁在里面、拍于何地。默认全部开启Tell the captioning model what LibrePhotos knows about a photo总开关默认OnUse the names of recognised people in captions把已识别人名写入 prompt仅当总开关开启时可用默认OnMention where the photo was taken in captions把地理编码位置写入 prompt仅当总开关开启时可用默认On。说明模型本身的配置见 Image Captioning 文档。源码层面默认值由 get_default_llm_settings 给出enabled、add_person、add_location为True而add_keywords/add_camera/add_lens/add_album为False此外还支持sentiment与custom_prompt等字段——字段保留了历史名称LLM 设置但现在直接驱动说明模型的 prompt。3.8 Slideshow OptionsSlideshow interval设置 lightbox 幻灯片模式下两张照片之间的间隔秒数。对应User.slideshow_interval源码默认 5 秒。3.9 Album OptionsInferred faces confidence设置推断出的面部达到什么置信度才会出现在人物相册中对应User.confidence_person默认0.9。3.10 Face Options人脸选项这些设置大多控制人脸聚类如何对你图库中的人脸分组——这正是标注人物时的操作对象Minimum Cluster Size影响聚类形成方式值越小聚类越多。可选项Auto、2、4、8、16。默认Auto由 LibrePhotos 自行决定。对应User.min_cluster_size默认0即 AutoMinimum Samples影响聚类的保守程度值越小越不保守。可选1、2、4、8、16。默认1。对应User.min_samplesCluster Selection Epsilon决定哪些聚类会被合并值越高分组越多。可选Off(0)、Small(0.025)、Normal(0.05)、High(0.1)、Very High(0.2)。默认Normal。对应User.cluster_selection_epsilon源码默认 0.05Confidence when Matching Unknown - Other Faces0 到 1 的置信度。Unknown - Other 组中的人脸只有当匹配置信度高于该值时才会归入具名人物0表示禁用该功能。默认0.50。对应User.confidence_unknown_faceWrite face tags to image files启用后每次标注人脸都会把标签以 XMP MWG-RS region tag 形式写入你的图像文件或根据Synchronize metadata to disk写入边车文件使人脸数据可以在 Lightroom、digiKam、XnView 等应用间保持可移植。默认Off。对应User.save_face_tags_to_disk。3.11 Public Sharing Defaults公开共享默认值为公开共享的相册配置默认可见性作用于所有新建的公开共享但可以按相册覆盖Show location是否展示照片位置数据Show camera info是否展示相机/镜头信息Show timestamps是否展示拍摄时间Show captions是否展示照片说明Show faces是否展示已识别人脸。源码印证默认值由 get_default_public_sharing_settings 给出五个字段share_location、share_camera_info、share_timestamps、share_captions、share_faces全部默认False采用隐私优先opt-in策略按相册的覆盖项优先于用户默认值。3.12 Duplicate Detection重复检测这是你在 Duplicates 页面Detection Options下拉框上的个人默认值——它们会在你点击Detect Duplicates之前预先填充该下拉框而不是自行触发检测。审查工作流见 Duplicate Detection 文档Visual sensitivity默认值控制视觉重复匹配的激进程度Strict匹配最少、置信最高、Normal平衡默认、Loose匹配最多、可能含误报。默认Normal。对应 User.DuplicateSensitivityClear pending duplicates默认值决定新一次检测开始前是否清除之前待处理的重复结果。默认Off。对应User.duplicate_clear_existing默认False。四、Admin Area实例级设置管理区设置作用于整个实例。除下文面板外Admin Area 还承载Services与Server Logs面板见 Library Management 文档。4.1 Site Settings站点设置Allow user registration在登录页启用注册按钮Allow uploads是否允许上传Skip patterns扫描时忽略的模式列表逗号分隔例如群晖设备上的eaDir,#recycleMap Provider选择哪个地理编码服务把 GPS 坐标转换为地名。可选 Nominatim免费、无需 key、Mapbox、MapTiler、OpenCage、TomTomAPI key for Map Provider仅在选择了商业供应商Mapbox、MapTiler、OpenCage、TomTom时显示且必填Nominatim 不需要 key故不显示Map Tiles地图底图从哪里加载。可选 PhotoPrism默认、OpenStreetMap、或None完全隐藏地图。打开地图会把你照片的大致位置暴露给所选供应商——注意它与上面的 mapprovider相互独立后者只影响反向地理编码Captioning ModelLFM2.5-VL默认或None关闭自动说明见 Image Captioning 文档Tagging Model选择自动打标签所用的 AI 模型。可选MobileCLIP-S2— 苹果的小型视觉-语言模型默认。基于 900 个真实照片标签的精选词表做零样本分类桌面 CPU 上约 125 ms/张、占用几百 MB 内存最多返回 10 个标签SigLIP 2— 谷歌的更大视觉-语言模型使用同一词表。更准确但慢约六倍、内存约两倍返回最相关的 10 个标签。切换模型不会删除已生成的标签——每个模型的标签独立存储因此可以来回切换而无需重扫Face Recognition Model选择用于检测与识别人脸的 InsightFace 模型。可选buffalo_sc— 轻量模型默认最快最小适合大多数部署buffalo_s / buffalo_m / buffalo_l— 逐级更大更准代价是更多内存与算力antelopev2— 高精度模型识别质量最佳。保存新模型会立即排队一个Download models任务若模型包尚不存在。只有切换之后编码的人脸才使用新模型——已有人脸保留其原有的嵌入Train faces也不会重编码它们只还为空的人脸生成嵌入然后重新聚类。因此应在第一次人脸扫描之前选定模型后期切换会使图库里混合两个模型产生的嵌入进行互比。详见 Face recognition 文档。以上站点设置项的类型约束见 site_settings_schemaallow_registration、allow_upload、skip_patterns、map_api_provider/map_api_key/map_tile_provider、captioning_model、tagging_model、face_recognition_model等键。4.2 Email (SMTP)站点设置卡片正下方是Email (SMTP)卡片配置出站邮件。若未在此配置Forgot your password?流程会静默失效服务器会记录失败日志但绝不透露某个地址是否存在。Provider选择发信方式Disabled、Custom SMTP server、SendGrid、Mailgun、Postmark、Brevo、SMTP2GO或Amazon SES。托管供应商使用内置服务器预设你只需提供From address、Username与 API keyCustom SMTP server以及 Amazon SES 的 host额外显示SMTP hostCustom SMTP server还显示Port、Use STARTTLS、Use implicit SSLFrom address发件地址Username供应商登录名。SendGrid 留空——它使用字面用户名apikeyPassword / API key只写字段存储前加密、API 永不返回。留空表示保留现有凭据不变用Remove the stored credential删除Send test email向你自己账号的邮箱发送测试邮件做端到端校验配置无效时保持禁用。源码层面这一卡片对应 EmailConfig 单例模型PROVIDER_PRESETS为每个托管供应商预置了 SMTP 端点与端口SendGridsmtp.sendgrid.net:587、Mailgunsmtp.mailgun.org:587、Postmarksmtp.postmarkapp.com:587、Brevosmtp-relay.brevo.com:587、SMTP2GOmail.smtp2go.com:587Amazon SES 因端点随区域变化由管理员自填 host预设的default_username机制正是 SendGrid 固定用户名apikey的来源密钥字段secret使用django_cryptography的encrypt字段静态加密基于部署的SECRET_KEY的 Fernet该模型通过save()强制pk1保证全实例只有一行配置UI 通过EmailConfig.load()读取is_configured属性判定能否真正发信provider 非 disabled 且有 host 与 from 地址。这些是 SMTP中继端点认证用的是供应商 API key 或 SMTP 凭据而非个人邮箱密码因此不受 Gmail / Microsoft 365 弃用基础认证的影响。4.3 Admin Tools管理工具Delete all auto created albums一步删除所有自动生成的事件相册不影响照片本身Download Server Stats保存serverstats.json报告报告内容见 Server Stats 章节。4.4 Users用户管理管理员在此修改用户的扫描目录和密码或向系统添加新用户。两个值得注意的约束来自 ManageUserSerializer扫描目录必须是真实存在的目录且必须位于数据根目录DATA_ROOT之内否则抛出验证错误用户名更新时检查唯一性冲突会报User name is already taken。4.5 Worker Logs展示各任务的执行进度。任务系统的完整说明见 Job System 文档。五、相关文档索引主题文档位置日期时间解析规则详解date-rules.md单点登录OIDCsingle-sign-on.md语义搜索search.md堆叠与文件变体stacks-and-file-variants.md人脸识别face-recognition.md图像说明image-captioning.md重复检测duplicate-detection.md环境参考含转码缓存变量environment-variables.md总结LibrePhotos 的设置遵循清晰的职责分层——Profile 管你是谁、是否公开用户 Settings 管我的库如何扫描、保存、聚类、去重Admin Area 管整个实例的行为与基础设施注册、上传、地图、模型、邮件、用户。每项设置都能在后端找到对应字段或配置项多数直接落在 User 模型 上站点项落在 Constance schema 与 EmailConfig 上这为排查设置为何不生效提供了直接的源码入口先确认字段值再看对应规则器日期规则、burst 规则、语义搜索任务链在扫描/重扫时如何消费它。【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考