Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

5.9 KB
Raw Blame

ADR-0149:Docker 首次设置按请求来源开放

  • 状态:已采纳
  • 日期:2026-11-05
  • 关系:扩展 ADR-0105 的首启与访问边界

背景

Docker 用户首次打开 Peach,会被要求填一个从没设过的「访问密码」(讨论 #379)。镜像入口 peach.server 原先对全新数据卷执行非交互的 peach init,替用户答完全部题目,却不写访问策略 secrets/access.json。没有策略时 access.load() 返回 legacy,登录页认的是自动生成的访问口令,要在容器里运行 peach token 才看得到。

Windows 与 macOS 不会遇到这个问题。托盘发现既没有 config.toml 也没有数据库时,起只绑本机回环的引导服务 peach serve --setup(build_setup_service_specs),首次设置页里选媒体目录、设访问密码或留空免登录、选代理与首次扫描,提交后由 onboarding.apply() 建库、生成口令、写设置文件与访问策略,托盘再换成正常服务。

Docker 不能照搬回环边界:宿主机和局域网的请求都从网桥进入容器,在容器里看来源都不是回环。

决策

一、全新 Docker 部署走同一张首次设置页。 PEACH_DISTRIBUTION=docker 且数据卷里既没有 config.toml 也没有 ledger.db 时,peach.server 不再执行 peach init,以 serve --setup 起首次设置服务,所有页面都是首次设置页。提交走同一个 POST /api/setup 与 onboarding.apply()。看守循环发现设置文件出现,就把首次设置服务换成正常服务,首次扫描请求由同一循环消费,和托盘首启后的切换对应。已有 config.toml 的部署照旧升级账本后启动;有账本、没配置照旧拒绝启动。

二、题目按容器裁剪。 数据目录固定为卷挂载点 /data,不出题,只在确认页列出,提交里带了也不认。监听地址、端口与局域网名由 Compose 决定,同样不出题,也不显示算不出来的访问地址。媒体目录第一行预填 /media,按容器内路径校验。不提供「使用已有数据」:换数据目录就是换卷。访问密码、代理和首次扫描与桌面版一致,访问密码默认开启,可以关掉免登录。完成后页面过一会儿自己回到当前地址:外部地址由宿主机端口映射决定,服务不知道。

三、边界由回环换成请求来源。 首次设置的读题与提交改用 web_local_access.local_client:本机或私有网络地址,且不带 X-Forwarded-*、Forwarded、CF-Connecting-IP 等代理转发头。判定与 ADR-0105 的配置页管理边界是同一个函数。提交另查 origin_allowed,隧道地址不算本机。首次设置服务没有口令,完成前 /api/ 与写请求一律按同一判定拦下;页面壳与静态资源照常给,来源不满足的浏览器看到一句说明:从部署机器或局域网打开,或在启动容器时设置 PEACH_ACCESS_PASSWORD。非 Docker 部署仍只认回环。

四、已配置、没有访问策略的 Docker 部署走访问设置卡。 这类部署来自本 ADR 之前的 peach init。登录页换成访问设置:设访问密码,或关掉开关明确选择免登录;提交 POST /api/configuration/access/first 写入 password 或 open 策略,设了密码就给提交的浏览器签发会话。来源判定同上;来源不满足时页面给同一句说明,并保留访问口令登录。

五、PEACH_ACCESS_PASSWORD 是预设路径。 容器启动且没有策略文件时,peach.server 用它写入 password 策略,日志只说已按该变量设置,不输出明文;已有策略时忽略并提示一次。全新部署也先写入,首次设置页里访问那一项标成已设置,不再出题。值不合规时只报原因、照常启动,浏览器打开后仍可在页面上设置。读过后从环境里删掉,不传给服务子进程。

六、口令不变。 访问口令照旧生成,全新部署在首次设置提交时生成;用户脚本、X-Token、?t= 和登录页的口令登录都不变。非 Docker 部署没有访问策略时仍是口令登录,登录页由服务端告知模式,标签写「访问口令」,下方说明用 peach token 查看。

与桌面版的区别

桌面首次设置服务只监听回环,能打开它的只有运行 Peach 的那台电脑。Docker 的首次设置服务监听容器的全部地址,能打开它的是一个网络范围:宿主机,以及在 PEACH_BIND 绑了局域网地址时同一局域网的设备。

代价

  • 局域网里第一个打开的人能完成设置。 设置完成前,同一局域网里能连到 Peach 的任何设备都能抢先答题、设访问密码或选免登录。首次设置在设置文件已存在时回 409,访问设置卡在文件锁里再确认一次策略不存在,后到的都不会覆盖已有设置。介意这个窗口的部署用 PEACH_ACCESS_PASSWORD 预设,或先保持 Compose 默认的 127.0.0.1 绑定,在宿主机上完成设置后再改绑局域网地址。
  • 首启前服务处于未配置状态。 没有账本、口令和访问策略,后台调度不启动。/healthz?ready=1 这时报就绪并带 setup: true,镜像的 HEALTHCHECK 和等它健康才启动的 Watchtower 不会卡在首启窗口;本机与私有网络来源可以调用全部接口,这和桌面引导服务对回环开放相同。设置提交后服务换成正常模式,会断开一两秒,完成页按配置页重启后的同一时长再跳转。设了访问密码的部署,进入后要用这个密码登录一次。
  • 已在用口令登录、但从没设过访问密码的 Docker 部署,升级后未登录的浏览器会看到访问设置卡,而不是口令登录框。已登录的浏览器不受影响。
  • 私有地址只说明请求来自私有网段。宿主机上的反向代理若不加转发头,会被当成本机来源放行;这和 ADR-0105 配置页的边界相同。