LibrePhotos 后端开发指南从 Docker 开发环境搭建到代码质量与日志规范【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos导读本文是 LibrePhotos自托管的开源照片管理服务后端apps/backend模块的开发实战指南围绕官方 CONTRIBUTING.md 展开并深入到仓库源码docker-compose.dev.yml、pyproject.toml、logging_bootstrap.py等验证底层细节。读完本文你将掌握如何用 Docker Compose 一键拉起带热重载的后端开发环境、四个核心容器各自的职责与常用排障命令、ruff pre-commit 的代码质量流水线以及最重要的——LibrePhotos 那条“INFO 与 DEBUG 如何分级、日志行如何写”的硬性规范从而能顺利提交并让维护者愿意 review 你的 PR。一、开发环境搭建从 Clone 到docker compose up1.1 前置条件依赖版本要求用途Git任意现代版本版本控制、Clone 仓库Docker Docker Compose支持 Compose v2运行整个开发环境Node.js YarnNode 18可选若在 Docker 外开发前端Python3.11可选若在 Docker 外开发后端从 pyproject.toml 的target-version py311可以印证后端代码基线就是 Python 3.11。1.2 克隆 MonorepoLibrePhotos 采用单仓库monorepo结构apps/下同时容纳backendDjango、frontendReact、mobileReact Native、docsDocusaurusdeploy/下存放全部部署配置。Linux/macOSexport codedir~/dev mkdir -p $codedir cd $codedir git clone https://github.com/LibrePhotos/librephotos.git cd librephotosWindows (PowerShell)$Env:codedir $HOME\dev New-Item -ItemType Directory -Force -Path $Env:codedir Set-Location $Env:codedir git clone https://github.com/LibrePhotos/librephotos.git Set-Location librephotos1.3 配置环境变量进入deploy/compose目录从模板复制.envcd deploy/compose cp librephotos.env .env模板 librephotos.env 中三个必填变量开发调试时重点关注前两个# 指向你的测试照片库目录容器会把该目录挂载为 /data scanDirectory/path/to/your/test/photos # LibrePhotos 数据目录媒体、日志、缓存、数据库文件 data./librephotos/data # 重要monorepo 检出路径供开发 Compose 挂载源码使用 codedir~/dev/librephotos其余变量dbName、dbUser、dbPass、httpPort、workerConcurrency、gunicornTimeout、logLevel、feature*功能开关、transcodeCache*转码缓存参数等在模板中均有默认值或注释说明仅在做自定义部署时才需要修改详见 deploy/compose/librephotos.env。1.4 启动开发环境docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d这个命令会基于本地源码构建开发镜像热重载开启把本地代码挂载进容器后端源码挂到/code前端挂到/usr/src/app启动全部服务backend、frontend、db、proxy另加 pgAdmin。开发完成后访问http://localhost:3000即可使用。关于挂载细节可以在 docker-compose.dev.yml 中验证backend: volumes: - ../../apps/backend:/code # 后端源码热挂载 - ../vscode/settings.json:/code/.vscode/settings.json # IDE 配置注入 frontend: volumes: - ../../apps/frontend:/usr/src/app # 前端源码热挂载1.5 依赖变更后的重建修改了requirements.txt或package.json后需要重建镜像因为依赖是打进镜像层的# 重建后端 docker compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache backend # 重建前端 docker compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache frontend # 重启容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d二、Docker 架构与常用运维命令2.1 四个核心容器LibrePhotos 采用微服务式容器划分容器职责backendDjango API 服务器、ML 模型人脸识别、图像描述、场景分类、后台任务django-q2frontendReact Web 应用proxyNginx 反向代理负责静态文件服务与路由dbPostgreSQL 数据库开发版 Compose 额外加入第五个容器pgadmin端口 3001默认账号adminadmin.com/ 密码admin方便直接查看数据库这在生产版中是不存在的。2.2 高频 Docker 命令# 查看运行中的容器 docker compose ps # 查看全部容器日志跟随输出 docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f # 只看某个容器的日志 docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f backend # 重启单个容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml restart backend # 停止全部容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml down # 停止并删除数据卷彻底重置 docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v # 进入容器执行命令 docker exec -it backend bash docker exec -it frontend sh # 执行 Django 管理命令 docker exec -it backend python manage.py migrate docker exec -it backend python manage.py createsuperuser2.3 开发环境 vs 生产环境维度开发叠加docker-compose.dev.yml生产仅docker-compose.yml源码从本地文件系统挂载构建进镜像热重载✅ 开启❌ 关闭调试模式✅DEBUG1❌DEBUG0构建耗时长从源码构建快拉取预构建镜像附加工具pgAdmin端口 3001最小化注意开发 Compose 中backend容器还额外注入了 VS Code Server 扩展挂载与/entrypoint.sh覆盖见 deploy/compose/docker-compose.dev.yml这是为了配合“附加到容器”的 IDE 工作流见第三节。三、IDE 推荐与容器内开发3.1 VS Code官方推荐推荐扩展Python、Pylance、Docker、Remote - Containers、ESLint、Prettier。仓库自带 VS Code 设置 deploy/vscode/settings.json并且被开发 Compose 自动挂载为容器内的/code/.vscode/settings.json。该文件开启了python.pythonPath /usr/local/bin/python指向容器内解释器flake8 检查--max-line-length119排除migrations/与 pylint加载pylint_django插件通过files.exclude隐藏__pycache__、*.pyc、*.so等产物。附加到后端容器的最佳实践安装 “Remote - Containers” 扩展CtrlShiftP打开命令面板执行 “Remote-Containers: Attach to Running Container”选择backend容器打开/code文件夹。3.2 PyCharm ProfessionalPyCharm 支持 Docker Compose 解释器Settings → Project → Python InterpreterAdd Interpreter → On Docker Compose同时选中docker-compose.yml与docker-compose.dev.yml选择backend服务。3.3 其他 IDE只要满足以下条件即可Python 3.11 解释器支持、前端有 ESLint/Prettier 集成、Docker 集成可选但推荐。四、代码质量规范ruff 与 pre-commit4.1 后端ruff检查与格式化LibrePhotos 使用ruff做 lint 与格式化配置位于 pyproject.toml。关键点在于required-version固定版本pyproject.toml中写的是required-version 0.15.22而 requirements.dev.txt 里固定的是ruff0.16.3二者与.pre-commit-config.yaml、CI 的lint-backend.yml必须指向同一版本——任何不匹配都会导致ruff拒绝运行从而避免“本地能过、CI 报错”的分叉。在容器内执行cd /code pip install $(grep ^ruff requirements.dev.txt) ruff check . ruff format .从pyproject.toml可见当前启用的规则默认的 pycodestyle/pyflakesE、F之外额外开启了Gflake8-logging-format、LOGflake8-logging以及PLE1205/PLE1206日志格式串参数数量校验并忽略E501、E203、E231和G004日志中的 f-string存量约 257 处正在按区域逐步转换。这直接呼应了后面第五节“日志怎么写”的规范——日志格式串的错误会被 lint 直接拦下。4.2 pre-commit 钩子pip install pre-commit pre-commit install安装后每次git commit前都会自动执行格式化检查。pre-commit4.6.2同样固定在 requirements.dev.txt 中。4.3 后端代码风格速查行长限制88 字符pyproject.toml中line-length 88注意与 VS Code 设置里 flake8 的 119 是两套独立配置尽量使用类型注解type hints遵循 PEP 8 命名规范公共函数写 docstring。4.4 前端ESLint 与 Prettier# 在 frontend 容器内或本地 yarn lint:error # 仅检查错误 yarn lint:warning:fix # 修复 lint 问题前端规范行长 120 字符、Prettier 格式化配置见 prettier.config.cjs、优先使用 TypeScripttype而非interface、函数组件 hooks、Redux 状态管理遵循 slice 模式。4.5 PR 提交前自检清单代码符合项目风格规范lint 全部通过无错误新功能包含测试如有文档已更新如需提交信息清晰、描述性强一个 PR 只解决一个问题/特性五、日志规范ownphotos.log是共享资源这是本指南中最需要认真对待的一节。ownphotos.log是用户随 bug 报告附上的关键证据所有日志行都在竞争同一份空间——你多打的一行 INFO可能挤掉某个用户真正崩溃原因的那一行。因此日志纪律是 review 的实际门槛。5.1 获取 logger新代码以及你正在改动的旧代码统一使用模块级 loggerimport logging logger logging.getLogger(__name__)from api.util import logger仍然可用且未被弃用当前大多数模块仍在使用例如 api/api_util.py、api/autoalbum.py 都在导入它模块级新写法在 api/apps.py、api/ffmpeg_budget.py 等新代码中已出现。模块级 logger 的好处是日志行能指明来源模块并且可以让某个吵闹的模块被单独静音。5.2 级别语义reviewer 真正执行的规则核心铁律INFO 的日志量必须与任务/请求数量级O(任务数)相当绝不能与照片数量级O(照片数)相当。每张照片、每个文件、每个请求的细节属于 DEBUG。级别使用场景DEBUG逐条目的细节这个文件、这张照片、这个请求。默认关闭是唯一允许日志量与图库规模一起增长的级别INFO任务或请求的开始、结束、或管理员事后需要看到的关键决策。每个任务一行而非每个条目一行WARNING某件事被跳过、重试或回退但工作继续。单张无法读取的照片是WARNINGERROR任务或请求失败且用户会感知到CRITICAL进程完全无法运行——日志目录不可写、数据库不可达。极少见logger.exception()等价于 ERROR traceback只应出现在任务真正死亡的地方循环中单个失败项继续运行时是WARNING——否则一个满是损坏文件的文件夹会为每张照片打一条 traceback把真正的故障淹没掉。5.3 怎么写日志行1用惰性%参数永远不要用 f-string。参数只在日志行真正被写出时才格式化因此当LOG_LEVELINFO时一个 DEBUG 调用零成本logger.info(job %s: scan finished, %s photos added, job_id, count) # 正确 logger.info(fjob {job_id}: scan finished, {count} photos added) # 错误ruff 的G规则已开启会自动拒绝.format()、拼接和exc_infoTruef-string 规则G004是唯一例外在pyproject.toml中被 mute约 257 处存量调用按区域逐步转换——不要再新增 f-string 日志。2始终带上定位所需的标识符job id、image_hash、user id。可模仿 api/api_util.pylogger.info(Getting search terms for user %s, user.id)以及 api/autoalbum.pylogger.info(%s - %s, key.date, lastKey.date)的写法始终采用%占位。3DEBUG 之上不得出现个人数据。用户名、媒体文件绝对路径、说明文字caption、LLM 提示词、地址、搜索词都不属于 INFO 及以上级别——请记录 user id 和image_hash代替。存量代码中有不少不符合此规则的例子但不要新增。设置后端容器的LOG_LEVELDEBUG即可看到完整输出流。5.4 日志配置的源码实现日志的“单一事实来源”在 librephotos/logging_bootstrap.py文件名与格式LOG_FILENAME ownphotos.log格式串固定为%(asctime)s : %(filename)s : %(funcName)s : %(lineno)s : %(levelname)s : %(message)s——注释明确提醒用户和工具在 grep/解析这个文件不要改动格式滚动策略ConcurrentRotatingFileHandler默认单文件 200 MB、保留 10 个备份DEFAULT_LOG_MAX_BYTES/DEFAULT_LOG_BACKUP_COUNT。之所以不用标准库RotatingFileHandler是因为 gunicorn 与 django-q2 多进程并发写同一文件普通滚动会互相截断对应 bug #1765第三方 logger 下限django_q压到 INFO它按任务打日志一个任务对应一张照片、urllib3/matplotlib/asyncio/django.db.backends压到 WARNING防止噪音淹没主日志级别兜底resolve_level()对无法识别的LOG_LEVEL回退为 INFO 并延迟告警——因为dictConfig遇到非法级别会在 settings 导入期直接抛异常而此时连一个 handler 都不存在任何进程都会在没有任何说明的情况下挂掉独立服务进程复用image_similarity/main.py与service/*/main.py等纯 Python 进程不加载 Django通过configure_standalone()获得同样的格式、滚动与级别处理保证全仓库日志形态一致。.env中对应的开关即logLevel取值CRITICAL/ERROR/WARNING/INFO/DEBUG默认INFO与baseLogs容器内日志目录默认/logs同时存放secret.key。六、如何提交一个 PR6.1 Fork 与克隆在 GitHub 上 ForkLibrePhotos/librephotos克隆你的 fork 并添加上游 remotegit clone https://github.com/YOUR-USERNAME/librephotos.git cd librephotos git remote add upstream https://github.com/LibrePhotos/librephotos.git6.2 创建特性分支git checkout -b feature/my-awesome-feature # 或 git checkout -b fix/bug-description6.3 提交变更git add . git commit -m feat: add support for XYZ # 或 git commit -m fix: resolve issue with ABC提交信息规范使用现在时“add feature” 而非 “added feature”首行不超过 72 字符需要时引用 issue如fix: resolve login bug (#123)。6.4 推送并创建 PRgit push origin feature/my-awesome-feature随后在 GitHub 上点击 “Compare pull request”按 PR 模板填写变更的清晰描述、关联 issue、UI 变更附截图、测试说明。6.5 响应评审及时处理 reviewer 反馈在新的提交中完成修改对建议保持开放。七、调试技巧与获取帮助7.1 后端Django调试在代码中插入import pdb; pdb.set_trace()然后附加到容器docker attach $(docker ps --filter namebackend -q)用CtrlP后CtrlQ脱离而不停止容器。7.2 前端React调试使用 React DevTools 浏览器扩展使用 Redux DevTools 调试状态启用 WDYRWhy Did You Render在 deploy/compose/librephotos.env 中设置VITE_APP_WDYRtrue并重启 frontend 容器它会在浏览器控制台输出每个组件重新渲染的原因。注意该变量只对开发 Compose 生效且值必须是全小写的字符串true见 docker-compose.dev.yml 中VITE_APP_WDYR${VITE_APP_WDYR:-false}的透传逻辑。7.3 API 文档启动 LibrePhotos 后访问Swaggerhttp://localhost:3000/api/swaggerReDochttp://localhost:3000/api/redoc7.4 求助渠道Discord 服务器见 CONTRIBUTING.mdGitHub Issues 报告 bug 或请求特性官方文档站 docs.librephotos.comNiaz Faridani-Rad 的开发视频频道。八、许可证与贡献约定向 LibrePhotos 贡献代码即表示你同意贡献以 MIT License 授权。完整的仓库级规范还可以进一步参考根目录的 CONTRIBUTING.md 与 CLAUDE.md。一句话总结开发环境用docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d拉起代码交给ruff与 pre-commit 把关日志严格遵守“INFO 按任务计、DEBUG 按条目计、无个人数据、无 f-string”四条铁律这样你的 PR 才能顺利通过 review 进入 LibrePhotos 主分支。【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LibrePhotos 后端开发指南：从 Docker 开发环境搭建到代码质量与日志规范
LibrePhotos 后端开发指南从 Docker 开发环境搭建到代码质量与日志规范【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos导读本文是 LibrePhotos自托管的开源照片管理服务后端apps/backend模块的开发实战指南围绕官方 CONTRIBUTING.md 展开并深入到仓库源码docker-compose.dev.yml、pyproject.toml、logging_bootstrap.py等验证底层细节。读完本文你将掌握如何用 Docker Compose 一键拉起带热重载的后端开发环境、四个核心容器各自的职责与常用排障命令、ruff pre-commit 的代码质量流水线以及最重要的——LibrePhotos 那条“INFO 与 DEBUG 如何分级、日志行如何写”的硬性规范从而能顺利提交并让维护者愿意 review 你的 PR。一、开发环境搭建从 Clone 到docker compose up1.1 前置条件依赖版本要求用途Git任意现代版本版本控制、Clone 仓库Docker Docker Compose支持 Compose v2运行整个开发环境Node.js YarnNode 18可选若在 Docker 外开发前端Python3.11可选若在 Docker 外开发后端从 pyproject.toml 的target-version py311可以印证后端代码基线就是 Python 3.11。1.2 克隆 MonorepoLibrePhotos 采用单仓库monorepo结构apps/下同时容纳backendDjango、frontendReact、mobileReact Native、docsDocusaurusdeploy/下存放全部部署配置。Linux/macOSexport codedir~/dev mkdir -p $codedir cd $codedir git clone https://github.com/LibrePhotos/librephotos.git cd librephotosWindows (PowerShell)$Env:codedir $HOME\dev New-Item -ItemType Directory -Force -Path $Env:codedir Set-Location $Env:codedir git clone https://github.com/LibrePhotos/librephotos.git Set-Location librephotos1.3 配置环境变量进入deploy/compose目录从模板复制.envcd deploy/compose cp librephotos.env .env模板 librephotos.env 中三个必填变量开发调试时重点关注前两个# 指向你的测试照片库目录容器会把该目录挂载为 /data scanDirectory/path/to/your/test/photos # LibrePhotos 数据目录媒体、日志、缓存、数据库文件 data./librephotos/data # 重要monorepo 检出路径供开发 Compose 挂载源码使用 codedir~/dev/librephotos其余变量dbName、dbUser、dbPass、httpPort、workerConcurrency、gunicornTimeout、logLevel、feature*功能开关、transcodeCache*转码缓存参数等在模板中均有默认值或注释说明仅在做自定义部署时才需要修改详见 deploy/compose/librephotos.env。1.4 启动开发环境docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d这个命令会基于本地源码构建开发镜像热重载开启把本地代码挂载进容器后端源码挂到/code前端挂到/usr/src/app启动全部服务backend、frontend、db、proxy另加 pgAdmin。开发完成后访问http://localhost:3000即可使用。关于挂载细节可以在 docker-compose.dev.yml 中验证backend: volumes: - ../../apps/backend:/code # 后端源码热挂载 - ../vscode/settings.json:/code/.vscode/settings.json # IDE 配置注入 frontend: volumes: - ../../apps/frontend:/usr/src/app # 前端源码热挂载1.5 依赖变更后的重建修改了requirements.txt或package.json后需要重建镜像因为依赖是打进镜像层的# 重建后端 docker compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache backend # 重建前端 docker compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache frontend # 重启容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d二、Docker 架构与常用运维命令2.1 四个核心容器LibrePhotos 采用微服务式容器划分容器职责backendDjango API 服务器、ML 模型人脸识别、图像描述、场景分类、后台任务django-q2frontendReact Web 应用proxyNginx 反向代理负责静态文件服务与路由dbPostgreSQL 数据库开发版 Compose 额外加入第五个容器pgadmin端口 3001默认账号adminadmin.com/ 密码admin方便直接查看数据库这在生产版中是不存在的。2.2 高频 Docker 命令# 查看运行中的容器 docker compose ps # 查看全部容器日志跟随输出 docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f # 只看某个容器的日志 docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f backend # 重启单个容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml restart backend # 停止全部容器 docker compose -f docker-compose.yml -f docker-compose.dev.yml down # 停止并删除数据卷彻底重置 docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v # 进入容器执行命令 docker exec -it backend bash docker exec -it frontend sh # 执行 Django 管理命令 docker exec -it backend python manage.py migrate docker exec -it backend python manage.py createsuperuser2.3 开发环境 vs 生产环境维度开发叠加docker-compose.dev.yml生产仅docker-compose.yml源码从本地文件系统挂载构建进镜像热重载✅ 开启❌ 关闭调试模式✅DEBUG1❌DEBUG0构建耗时长从源码构建快拉取预构建镜像附加工具pgAdmin端口 3001最小化注意开发 Compose 中backend容器还额外注入了 VS Code Server 扩展挂载与/entrypoint.sh覆盖见 deploy/compose/docker-compose.dev.yml这是为了配合“附加到容器”的 IDE 工作流见第三节。三、IDE 推荐与容器内开发3.1 VS Code官方推荐推荐扩展Python、Pylance、Docker、Remote - Containers、ESLint、Prettier。仓库自带 VS Code 设置 deploy/vscode/settings.json并且被开发 Compose 自动挂载为容器内的/code/.vscode/settings.json。该文件开启了python.pythonPath /usr/local/bin/python指向容器内解释器flake8 检查--max-line-length119排除migrations/与 pylint加载pylint_django插件通过files.exclude隐藏__pycache__、*.pyc、*.so等产物。附加到后端容器的最佳实践安装 “Remote - Containers” 扩展CtrlShiftP打开命令面板执行 “Remote-Containers: Attach to Running Container”选择backend容器打开/code文件夹。3.2 PyCharm ProfessionalPyCharm 支持 Docker Compose 解释器Settings → Project → Python InterpreterAdd Interpreter → On Docker Compose同时选中docker-compose.yml与docker-compose.dev.yml选择backend服务。3.3 其他 IDE只要满足以下条件即可Python 3.11 解释器支持、前端有 ESLint/Prettier 集成、Docker 集成可选但推荐。四、代码质量规范ruff 与 pre-commit4.1 后端ruff检查与格式化LibrePhotos 使用ruff做 lint 与格式化配置位于 pyproject.toml。关键点在于required-version固定版本pyproject.toml中写的是required-version 0.15.22而 requirements.dev.txt 里固定的是ruff0.16.3二者与.pre-commit-config.yaml、CI 的lint-backend.yml必须指向同一版本——任何不匹配都会导致ruff拒绝运行从而避免“本地能过、CI 报错”的分叉。在容器内执行cd /code pip install $(grep ^ruff requirements.dev.txt) ruff check . ruff format .从pyproject.toml可见当前启用的规则默认的 pycodestyle/pyflakesE、F之外额外开启了Gflake8-logging-format、LOGflake8-logging以及PLE1205/PLE1206日志格式串参数数量校验并忽略E501、E203、E231和G004日志中的 f-string存量约 257 处正在按区域逐步转换。这直接呼应了后面第五节“日志怎么写”的规范——日志格式串的错误会被 lint 直接拦下。4.2 pre-commit 钩子pip install pre-commit pre-commit install安装后每次git commit前都会自动执行格式化检查。pre-commit4.6.2同样固定在 requirements.dev.txt 中。4.3 后端代码风格速查行长限制88 字符pyproject.toml中line-length 88注意与 VS Code 设置里 flake8 的 119 是两套独立配置尽量使用类型注解type hints遵循 PEP 8 命名规范公共函数写 docstring。4.4 前端ESLint 与 Prettier# 在 frontend 容器内或本地 yarn lint:error # 仅检查错误 yarn lint:warning:fix # 修复 lint 问题前端规范行长 120 字符、Prettier 格式化配置见 prettier.config.cjs、优先使用 TypeScripttype而非interface、函数组件 hooks、Redux 状态管理遵循 slice 模式。4.5 PR 提交前自检清单代码符合项目风格规范lint 全部通过无错误新功能包含测试如有文档已更新如需提交信息清晰、描述性强一个 PR 只解决一个问题/特性五、日志规范ownphotos.log是共享资源这是本指南中最需要认真对待的一节。ownphotos.log是用户随 bug 报告附上的关键证据所有日志行都在竞争同一份空间——你多打的一行 INFO可能挤掉某个用户真正崩溃原因的那一行。因此日志纪律是 review 的实际门槛。5.1 获取 logger新代码以及你正在改动的旧代码统一使用模块级 loggerimport logging logger logging.getLogger(__name__)from api.util import logger仍然可用且未被弃用当前大多数模块仍在使用例如 api/api_util.py、api/autoalbum.py 都在导入它模块级新写法在 api/apps.py、api/ffmpeg_budget.py 等新代码中已出现。模块级 logger 的好处是日志行能指明来源模块并且可以让某个吵闹的模块被单独静音。5.2 级别语义reviewer 真正执行的规则核心铁律INFO 的日志量必须与任务/请求数量级O(任务数)相当绝不能与照片数量级O(照片数)相当。每张照片、每个文件、每个请求的细节属于 DEBUG。级别使用场景DEBUG逐条目的细节这个文件、这张照片、这个请求。默认关闭是唯一允许日志量与图库规模一起增长的级别INFO任务或请求的开始、结束、或管理员事后需要看到的关键决策。每个任务一行而非每个条目一行WARNING某件事被跳过、重试或回退但工作继续。单张无法读取的照片是WARNINGERROR任务或请求失败且用户会感知到CRITICAL进程完全无法运行——日志目录不可写、数据库不可达。极少见logger.exception()等价于 ERROR traceback只应出现在任务真正死亡的地方循环中单个失败项继续运行时是WARNING——否则一个满是损坏文件的文件夹会为每张照片打一条 traceback把真正的故障淹没掉。5.3 怎么写日志行1用惰性%参数永远不要用 f-string。参数只在日志行真正被写出时才格式化因此当LOG_LEVELINFO时一个 DEBUG 调用零成本logger.info(job %s: scan finished, %s photos added, job_id, count) # 正确 logger.info(fjob {job_id}: scan finished, {count} photos added) # 错误ruff 的G规则已开启会自动拒绝.format()、拼接和exc_infoTruef-string 规则G004是唯一例外在pyproject.toml中被 mute约 257 处存量调用按区域逐步转换——不要再新增 f-string 日志。2始终带上定位所需的标识符job id、image_hash、user id。可模仿 api/api_util.pylogger.info(Getting search terms for user %s, user.id)以及 api/autoalbum.pylogger.info(%s - %s, key.date, lastKey.date)的写法始终采用%占位。3DEBUG 之上不得出现个人数据。用户名、媒体文件绝对路径、说明文字caption、LLM 提示词、地址、搜索词都不属于 INFO 及以上级别——请记录 user id 和image_hash代替。存量代码中有不少不符合此规则的例子但不要新增。设置后端容器的LOG_LEVELDEBUG即可看到完整输出流。5.4 日志配置的源码实现日志的“单一事实来源”在 librephotos/logging_bootstrap.py文件名与格式LOG_FILENAME ownphotos.log格式串固定为%(asctime)s : %(filename)s : %(funcName)s : %(lineno)s : %(levelname)s : %(message)s——注释明确提醒用户和工具在 grep/解析这个文件不要改动格式滚动策略ConcurrentRotatingFileHandler默认单文件 200 MB、保留 10 个备份DEFAULT_LOG_MAX_BYTES/DEFAULT_LOG_BACKUP_COUNT。之所以不用标准库RotatingFileHandler是因为 gunicorn 与 django-q2 多进程并发写同一文件普通滚动会互相截断对应 bug #1765第三方 logger 下限django_q压到 INFO它按任务打日志一个任务对应一张照片、urllib3/matplotlib/asyncio/django.db.backends压到 WARNING防止噪音淹没主日志级别兜底resolve_level()对无法识别的LOG_LEVEL回退为 INFO 并延迟告警——因为dictConfig遇到非法级别会在 settings 导入期直接抛异常而此时连一个 handler 都不存在任何进程都会在没有任何说明的情况下挂掉独立服务进程复用image_similarity/main.py与service/*/main.py等纯 Python 进程不加载 Django通过configure_standalone()获得同样的格式、滚动与级别处理保证全仓库日志形态一致。.env中对应的开关即logLevel取值CRITICAL/ERROR/WARNING/INFO/DEBUG默认INFO与baseLogs容器内日志目录默认/logs同时存放secret.key。六、如何提交一个 PR6.1 Fork 与克隆在 GitHub 上 ForkLibrePhotos/librephotos克隆你的 fork 并添加上游 remotegit clone https://github.com/YOUR-USERNAME/librephotos.git cd librephotos git remote add upstream https://github.com/LibrePhotos/librephotos.git6.2 创建特性分支git checkout -b feature/my-awesome-feature # 或 git checkout -b fix/bug-description6.3 提交变更git add . git commit -m feat: add support for XYZ # 或 git commit -m fix: resolve issue with ABC提交信息规范使用现在时“add feature” 而非 “added feature”首行不超过 72 字符需要时引用 issue如fix: resolve login bug (#123)。6.4 推送并创建 PRgit push origin feature/my-awesome-feature随后在 GitHub 上点击 “Compare pull request”按 PR 模板填写变更的清晰描述、关联 issue、UI 变更附截图、测试说明。6.5 响应评审及时处理 reviewer 反馈在新的提交中完成修改对建议保持开放。七、调试技巧与获取帮助7.1 后端Django调试在代码中插入import pdb; pdb.set_trace()然后附加到容器docker attach $(docker ps --filter namebackend -q)用CtrlP后CtrlQ脱离而不停止容器。7.2 前端React调试使用 React DevTools 浏览器扩展使用 Redux DevTools 调试状态启用 WDYRWhy Did You Render在 deploy/compose/librephotos.env 中设置VITE_APP_WDYRtrue并重启 frontend 容器它会在浏览器控制台输出每个组件重新渲染的原因。注意该变量只对开发 Compose 生效且值必须是全小写的字符串true见 docker-compose.dev.yml 中VITE_APP_WDYR${VITE_APP_WDYR:-false}的透传逻辑。7.3 API 文档启动 LibrePhotos 后访问Swaggerhttp://localhost:3000/api/swaggerReDochttp://localhost:3000/api/redoc7.4 求助渠道Discord 服务器见 CONTRIBUTING.mdGitHub Issues 报告 bug 或请求特性官方文档站 docs.librephotos.comNiaz Faridani-Rad 的开发视频频道。八、许可证与贡献约定向 LibrePhotos 贡献代码即表示你同意贡献以 MIT License 授权。完整的仓库级规范还可以进一步参考根目录的 CONTRIBUTING.md 与 CLAUDE.md。一句话总结开发环境用docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d拉起代码交给ruff与 pre-commit 把关日志严格遵守“INFO 按任务计、DEBUG 按条目计、无个人数据、无 f-string”四条铁律这样你的 PR 才能顺利通过 review 进入 LibrePhotos 主分支。【免费下载链接】librephotosA self-hosted open source photo management service.项目地址: https://gitcode.com/GitHub_Trending/li/librephotos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考