Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(docker): ADR-0148 改为全新部署走首次设置、已有部署走访问设置卡

longmeidao37f98f5a93cf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 603894d83..6053f4fdb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,7 +28,7 @@ Removed / Fixed / Security。
### 新增
- **更新**:Docker 镜像同时发布到 `ghcr.io/peach-mitao/peach`,Docker Hub 拉取受限时可以改用。
-- **配置**:Docker 首次打开先进入访问设置,可设密码或免登录,不再要口令;也可用 `PEACH_ACCESS_PASSWORD` 预设。
+- **配置**:全新 Docker 首次打开走与桌面相同的首次设置,可设密码或免登录,不再要口令。
### 修复
diff --git a/SECURITY.md b/SECURITY.md
index 039551ecb..8250a3d7f 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -23,7 +23,7 @@ Linux 无桌面部署的配置管理接受经过鉴权的回环与私有网络
- 同一来源每分钟最多尝试登录 10 次,超出后要等一分钟。
- 密码以 scrypt 哈希保存在本机 `<Peach 数据目录>/secrets/access.json`,不进数据库,也不参与任何同步。
-Docker 部署首次打开时进入访问设置,只接受宿主机或局域网来源,也可以用 `PEACH_ACCESS_PASSWORD` 在首次启动时预设,见 [ADR-0148](docs/adr/0148-docker-first-access-setup.md)。其他没有 `access.json` 的已有部署,登录页使用下面的访问口令。
+Docker 部署的首次设置与访问设置只接受宿主机或局域网来源,也可以用 `PEACH_ACCESS_PASSWORD` 在启动时预设,见 [ADR-0148](docs/adr/0148-docker-first-access-setup.md)。其他没有 `access.json` 的已有部署,登录页使用下面的访问口令。
## 访问口令
diff --git a/compose.yaml b/compose.yaml
index c52453478..86d5384c8 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -8,7 +8,7 @@ services:
environment:
# Watchtower 只换同一标签的新镜像;标签不是 edge 时配置页不给「一键更新」。
PEACH_IMAGE_TAG: ${PEACH_VERSION:-edge}
- # 可选:首次启动时直接设访问密码(8–256 个字符),跳过网页里的访问设置;已有访问设置时忽略。
+ # 可选:还没有访问设置时,启动就用它设访问密码(8–256 个字符),首次设置页不再问;已有访问设置时忽略。
# 密码写在 .env 的 PEACH_ACCESS_PASSWORD,再取消下一行的注释。
# PEACH_ACCESS_PASSWORD: ${PEACH_ACCESS_PASSWORD}
labels:
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 771a6a27f..7b492e106 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -43,13 +43,17 @@ PEACH_MEDIA_ROOT=/srv/videos
`192.0.2.10` 是文档示例地址,不能直接用于部署。NAS 管理界面支持 Compose 环境变量时,也可在那里填写这三个值。应用配置并重新创建容器后,打开 `http://<NAS 局域网 IP>:<PEACH_PORT>`。不要在另一台电脑上用 `127.0.0.1` 访问 NAS。
-首次打开时,Peach 会进入访问设置:设访问密码,或关掉开关选择免登录,提交后直接进入。这一步只接受宿主机或同一局域网设备打开的页面;经反向代理或公网打开时,页面会提示改从这些地址打开。局域网里第一个打开的人就能完成设置,介意时用下面的 `PEACH_ACCESS_PASSWORD` 预设密码。
+全新数据卷首次打开时,Peach 进入和 Windows、macOS 相同的首次设置:确认媒体目录(默认 `/media`),设访问密码或关掉开关选择免登录,选代理与是否立即扫描。数据目录固定为 `/data`,端口与访问地址由 Compose 决定,不在页面上出题。完成后服务自动切换到正常模式,页面稍后回到首页;设了密码时用它登录。
+
+首次设置只接受宿主机或同一局域网设备打开的页面;经反向代理或公网打开时,页面会提示改从这些地址打开。局域网里第一个打开的人就能完成设置,介意时用下面的 `PEACH_ACCESS_PASSWORD` 预设密码。
### 初始化与管理
-使用 Compose 启动后,Peach 会为全新数据卷创建配置、数据库和随机访问口令。已有配置保持原值;如果已有数据库但缺少配置文件,服务拒绝启动,需要恢复配置文件。初始化日志只显示口令文件位置。
+全新数据卷在首次设置完成前没有配置和数据库,服务以未配置状态运行;提交首次设置后,Peach 创建配置、数据库和随机访问口令。已有配置保持原值;如果已有数据库但缺少配置文件,服务拒绝启动,需要恢复配置文件。
+
+已经配置过、但从没设过访问密码的部署,未登录的浏览器打开时会看到访问设置:设访问密码或选择免登录,来源要求与首次设置相同。
-也可以在 `.env` 里写 `PEACH_ACCESS_PASSWORD=<8–256 个字符的密码>`,并取消 `compose.yaml` 中对应行的注释。容器首次启动时直接用它设访问密码,跳过网页里的访问设置,日志不显示密码;已有访问设置时忽略它,改密码请到配置页。
+也可以在 `.env` 里写 `PEACH_ACCESS_PASSWORD=<8–256 个字符的密码>`,并取消 `compose.yaml` 中对应行的注释。还没有访问设置时,容器启动就用它设访问密码,首次设置页里访问那一项显示为已设置,日志不显示密码;已有访问设置时忽略它,改密码请到配置页。
访问口令仍会自动生成,供用户脚本和 API 使用,容器终端运行 `peach token`、宿主机运行 `docker compose exec peach peach token` 查看。配置页要求登录,并且连接必须来自容器本机或私有网络;携带代理转发头的管理请求会被拒绝。通过配置页保存后,服务自动读取配置;勾选扫描时会启动资料处理。
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index b2f5a8d29..e42b7396b 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -707,6 +707,7 @@ PikPak 官方核验通道使用「推送发现」中该媒体根对应的唯一
- 托盘启动时读一次设置文件,由 `tray.needs_setup()` 判断:**没有 `config.toml` 且没有数据库**才算需要首次设置。不用 `PeachConfig.configured` 判断:托盘的单实例锁一启动就会在 Peach 数据目录下建出 `state/`,一次失败的启动就可能让下一次误判成已配置;反过来,没有 `config.toml` 的老部署数据库还在,不能被拖进首次设置。
- 需要设置时,托盘不构建正常的服务规格(全新机器上 `build_service_specs()` 会因为缺 TLS 材料抛 `FileNotFoundError`),而是启动 `peach serve --setup --host 127.0.0.1 --port <设置里的端口,默认 8900> --no-mdns --no-ledger-sync`,再把浏览器打开到 `http://127.0.0.1:<端口>/`。这条引导服务没有 TLS,口令强制为空,安全边界就是回环绑定地址。
- 首页是首次设置表单:`GET /` 回一张薄壳(`routes_pages.setup_shell()`),表单由页面包 `/dist/peach-pages.js` 画出,题目与提交都走下面两条 JSON 接口。完成态的入口带 `/?onboarding=1`;选了导入浏览器历史则先去 `/taste?onboarding=1`。安装教程通过专用状态接口读取各项的实际状态。
+- Docker 全新数据卷不跑 `peach init`:`peach.server` 以 `serve --setup` 监听容器端口,设置文件出现后换成正常服务(ADR-0148)。守卫改按 `web_local_access.local_client` 收本机与私有网络、不带代理转发头的来源,403 正文带 `docker: true`;完成前 `/api/` 与写请求按同一判定拦下。读题不出 `data_root`、`host`、`port`、`mdns_name`,提交里带了也不认;`media_dir` 默认 `/media`,另给 `data_root`(固定的数据目录)与 `access_preset`(已按 `PEACH_ACCESS_PASSWORD` 写下访问密码)。完成后 `url` 与 `redirect` 都是当前地址下的 `/?onboarding=1`,`POST /api/setup/restore` 回 404。
- 两条接口共用守卫(`routes_pages._setup_guard`):已配置 404,非回环来源 403,独立包地址栏主机名不是回环写法 403;提交另查 Origin(403)与设置文件已存在(409)。两条都在 `/api/` 下,错误一律回 JSON。
- `GET /api/setup/questions` 给出画表单要的数据:`questions` 按 `onboarding.questions()` 的顺序列出每题的 `key`、`label`、`help`(说明行列表)、`default`、`required`、`advanced`(是否折进「高级设置」)、`input`(`text`、`number`、`choice`、`folders`)、`prefix`、`suffix`,`host` 另带按页面顺序排好的 `options`,`mdns_name` 另带 `visible_when: {"host": "2"}`;另有 `media_sources`、`media_source_default`、`media_root`(非 Windows 的对应路径格,Windows 为 `null`)、`cloud`(提示、帮助链接与缺失的挂载软件 `dependencies`)、`windows`、`standalone`,以及三个开关的初始值 `access_enabled`(host 默认是局域网就开)、`scan_now`、`history_guide`。
- `POST /api/setup` 收同名字段:`media_dir` 是 `{path, location, root}` 行列表(`location` 缺省为 `local`),`access_enabled`、`scan_now`、`history_guide` 是布尔,选了「只有这台电脑」可不传 `mdns_name`。400 回 `{"error", "errors"}`:`errors` 按题目 key,访问密码在 `access_password`,`media_dir` 与提交的行一一对应、没错的行是空串;整表不成立(超过 100 行)时只有一句,长度与行数不等。`apply` 失败回 400,错误在 `data_root`。200 回 `url`、`scan_requested`、`history_guide`、`standalone`、`redirect`(独立包为入口地址,其余为 `null`,跳转时长由前端定)与运行信息 `facts`(同 `/api/configuration` 的 `facts`)。
diff --git a/docs/ROUTES.md b/docs/ROUTES.md
index 9f3fcf7bd..6f58cd85f 100644
--- a/docs/ROUTES.md
+++ b/docs/ROUTES.md
@@ -126,7 +126,7 @@ Docker 镜像的一键更新([ADR-0140](adr/0140-docker-one-click-update-via-w
`POST /api/configuration/smb/test` 接受共享地址及连接字段,验证只读目录访问,返回 `readable` 和最多 500 个可进入子目录名。接口要求本机管理权限与同源请求;地址无效返回 400,无读取权限返回 403,共享不可达返回 502,不回显密码。配置读取只返回账号、加密要求与密码是否已保存。
-`POST /api/configuration/access/first` 是 Docker 首次访问设置的提交([ADR-0148](adr/0148-docker-first-access-setup.md)),不要求登录。正文 `{mode, password, confirmation, next}`,`mode` 为 `password` 或 `open`;成功写入访问策略,返回站内地址 `url`,设了密码时同时设下会话 cookie。只在 Docker 且还没有访问策略时可用:非 Docker 返回 404,已有策略返回 409,来源不是本机或私有网络、带代理转发头或不同源时返回 403,密码错误按 `errors.password`、`errors.confirmation` 返回 400。
+`POST /api/configuration/access/first` 是已配置、还没有访问策略的 Docker 部署的访问设置提交([ADR-0148](adr/0148-docker-first-access-setup.md)),不要求登录。正文 `{mode, password, confirmation, next}`,`mode` 为 `password` 或 `open`;成功写入访问策略,返回站内地址 `url`,设了密码时同时设下会话 cookie。只在 Docker 且还没有访问策略时可用:非 Docker 返回 404,已有策略返回 409,来源不是本机或私有网络、带代理转发头或不同源时返回 403,密码错误按 `errors.password`、`errors.confirmation` 返回 400。
`POST /api/configuration/access/token/rotate` 更换访问口令,运行中的服务立即改用新口令。接口要求本机管理权限与同源请求;口令由 `--token`、`PEACH_TOKEN` 指定或这次启动没有口令时返回 409,访问设置读不出时也返回 409。响应只在这一次带回新口令 `token`(`Cache-Control: no-store`),另有访问方式 `mode` 和被登出的其他设备数 `signed_out`。配置读取的 `api_token` 只给出 `rotatable`、`reason`、`paired`,不回显口令。
diff --git a/docs/adr/0148-docker-first-access-setup.md b/docs/adr/0148-docker-first-access-setup.md
index b802fac81..99ce824fa 100644
--- a/docs/adr/0148-docker-first-access-setup.md
+++ b/docs/adr/0148-docker-first-access-setup.md
@@ -1,33 +1,38 @@
-# ADR-0148:Docker 首次访问设置按来源限制
+# ADR-0148:Docker 首次设置按请求来源开放
- 状态:已采纳
- 日期:2026-11-05
-- 关系:扩展 [ADR-0105](0105-linux-headless-container.md) 的访问边界
+- 关系:扩展 [ADR-0105](0105-linux-headless-container.md) 的首启与访问边界
## 背景
-Docker 用户首次打开 Peach,会被要求填一个从没设过的「访问密码」(讨论 #379)。镜像入口 `peach.server` 用非交互的 `peach init` 初始化,不写访问策略 `secrets/access.json`;没有策略时 `access.load()` 返回 `legacy`,登录页认的是自动生成的访问口令,要在容器里运行 `peach token` 才看得到。
+Docker 用户首次打开 Peach,会被要求填一个从没设过的「访问密码」(讨论 #379)。镜像入口 `peach.server` 原先对全新数据卷执行非交互的 `peach init`,替用户答完全部题目,却不写访问策略 `secrets/access.json`。没有策略时 `access.load()` 返回 `legacy`,登录页认的是自动生成的访问口令,要在容器里运行 `peach token` 才看得到。
-Windows 与 macOS 不会遇到这个问题。托盘的首次设置页(`build_setup_service_specs`)只绑本机回环,不需要口令;用户在页面上设访问密码,或留空免登录,提交时写下 open 或 password 策略。口令照旧生成,只给用户脚本和 API 用。
+Windows 与 macOS 不会遇到这个问题。托盘发现既没有 `config.toml` 也没有数据库时,起只绑本机回环的引导服务 `peach serve --setup`(`build_setup_service_specs`),首次设置页里选媒体目录、设访问密码或留空免登录、选代理与首次扫描,提交后由 `onboarding.apply()` 建库、生成口令、写设置文件与访问策略,托盘再换成正常服务。
Docker 不能照搬回环边界:宿主机和局域网的请求都从网桥进入容器,在容器里看来源都不是回环。
## 决策
-**一、Docker 没有访问策略时,登录页换成访问设置。** 服务在 `PEACH_DISTRIBUTION=docker` 下运行、访问策略文件不存在时,浏览器打开任意页面都会转到 `/login`,页面画访问设置而不是口令框:设访问密码,或关掉开关明确选择免登录,内容和桌面首次设置的访问部分一致。提交 `POST /api/configuration/access/first` 写入 password 或 open 策略;设了密码就给提交的浏览器签发会话,直接进入。
+**一、全新 Docker 部署走同一张首次设置页。** `PEACH_DISTRIBUTION=docker` 且数据卷里既没有 `config.toml` 也没有 `ledger.db` 时,`peach.server` 不再执行 `peach init`,以 `serve --setup` 起首次设置服务,所有页面都是首次设置页。提交走同一个 `POST /api/setup` 与 `onboarding.apply()`。看守循环发现设置文件出现,就把首次设置服务换成正常服务,首次扫描请求由同一循环消费,和托盘首启后的切换对应。已有 `config.toml` 的部署照旧升级账本后启动;有账本、没配置照旧拒绝启动。
-**二、边界由回环换成请求来源。** 页面和提交都只接受 `web_local_access.local_client` 判定的来源:本机或私有网络地址,且不带 `X-Forwarded-*`、`Forwarded`、`CF-Connecting-IP` 等代理转发头。判定与 ADR-0105 的配置页管理边界是同一个函数,不另写一套。提交还要通过 `origin_allowed`,隧道地址这时不算本机。来源不满足时,页面说明请从部署机器或局域网打开,或在启动时设置 `PEACH_ACCESS_PASSWORD`,并保留访问口令登录。
+**二、题目按容器裁剪。** 数据目录固定为卷挂载点 `/data`,不出题,只在确认页列出,提交里带了也不认。监听地址、端口与局域网名由 Compose 决定,同样不出题,也不显示算不出来的访问地址。媒体目录第一行预填 `/media`,按容器内路径校验。不提供「使用已有数据」:换数据目录就是换卷。访问密码、代理和首次扫描与桌面版一致,访问密码默认开启,可以关掉免登录。完成后页面过一会儿自己回到当前地址:外部地址由宿主机端口映射决定,服务不知道。
-**三、`PEACH_ACCESS_PASSWORD` 是预设路径。** 容器首次启动且没有策略文件时,`peach.server` 用它写入 password 策略,日志只说已按该变量设置,不输出明文。已有策略时忽略它并提示一次,改密码仍走配置页。值不合规时只报原因、照常启动,浏览器打开后仍进入访问设置。读过后从环境里删掉,不传给服务子进程。
+**三、边界由回环换成请求来源。** 首次设置的读题与提交改用 `web_local_access.local_client`:本机或私有网络地址,且不带 `X-Forwarded-*`、`Forwarded`、`CF-Connecting-IP` 等代理转发头。判定与 ADR-0105 的配置页管理边界是同一个函数。提交另查 `origin_allowed`,隧道地址不算本机。首次设置服务没有口令,完成前 `/api/` 与写请求一律按同一判定拦下;页面壳与静态资源照常给,来源不满足的浏览器看到一句说明:从部署机器或局域网打开,或在启动容器时设置 `PEACH_ACCESS_PASSWORD`。非 Docker 部署仍只认回环。
-**四、口令不变。** 访问口令照旧生成,用户脚本、`X-Token`、`?t=` 和登录页的口令登录都不变。非 Docker 部署没有访问策略时仍是口令登录,登录页由服务端告知模式,标签写「访问口令」,下方说明用 `peach token` 查看。
+**四、已配置、没有访问策略的 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 的那台电脑。Docker 的首次设置服务监听容器的全部地址,能打开它的是一个网络范围:宿主机,以及在 `PEACH_BIND` 绑了局域网地址时同一局域网的设备。
## 代价
-- **局域网里第一个打开的人能设密码。** 设置完成前,同一局域网里能连到 Peach 的任何设备都能抢先设访问密码或选免登录。提交在文件锁里再确认一次策略不存在,后到的收 409,不会覆盖已有设置。介意这个窗口的部署用 `PEACH_ACCESS_PASSWORD` 预设,或先保持 Compose 默认的 `127.0.0.1` 绑定,在宿主机上完成设置后再改绑局域网地址。
-- 已在用口令登录、但从没设过访问密码的 Docker 部署,升级后未登录的浏览器会看到访问设置,而不是口令登录框。已登录的浏览器不受影响。
+- **局域网里第一个打开的人能完成设置。** 设置完成前,同一局域网里能连到 Peach 的任何设备都能抢先答题、设访问密码或选免登录。首次设置在设置文件已存在时回 409,访问设置卡在文件锁里再确认一次策略不存在,后到的都不会覆盖已有设置。介意这个窗口的部署用 `PEACH_ACCESS_PASSWORD` 预设,或先保持 Compose 默认的 `127.0.0.1` 绑定,在宿主机上完成设置后再改绑局域网地址。
+- **首启前服务处于未配置状态。** 没有账本、口令和访问策略,后台调度不启动,健康检查照常应答;本机与私有网络来源可以调用全部接口,这和桌面引导服务对回环开放相同。设置提交后服务换成正常模式,会断开一两秒,完成页按配置页重启后的同一时长再跳转。设了访问密码的部署,进入后要用这个密码登录一次。
+- 已在用口令登录、但从没设过访问密码的 Docker 部署,升级后未登录的浏览器会看到访问设置卡,而不是口令登录框。已登录的浏览器不受影响。
- 私有地址只说明请求来自私有网段。宿主机上的反向代理若不加转发头,会被当成本机来源放行;这和 ADR-0105 配置页的边界相同。