Peach: Local-first video metadata scraper and media manager.
docs(docker): Docker 首次设置的 ADR 改号为 0149
longmeidaof484d01644b8
diff --git a/SECURITY.md b/SECURITY.mdindex 8250a3d7f..41252c043 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-0149](docs/adr/0149-docker-first-access-setup.md)。其他没有 `access.json` 的已有部署,登录页使用下面的访问口令。## 访问口令diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex a17401be5..79ee1143b 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -707,7 +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。首次设置服务的 `/healthz?ready=1` 回 200 与 `setup: true`。+- Docker 全新数据卷不跑 `peach init`:`peach.server` 以 `serve --setup` 监听容器端口,设置文件出现后换成正常服务(ADR-0149)。守卫改按 `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。首次设置服务的 `/healthz?ready=1` 回 200 与 `setup: true`。- 两条接口共用守卫(`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.mdindex 6f58cd85f..33d270765 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-0149](adr/0149-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/0149-docker-first-access-setup.mdsimilarity index 99%rename from docs/adr/0148-docker-first-access-setup.mdrename to docs/adr/0149-docker-first-access-setup.mdindex e652733ee..2fd07e4db 100644--- a/docs/adr/0148-docker-first-access-setup.md+++ b/docs/adr/0149-docker-first-access-setup.md@@ -1,4 +1,4 @@-# ADR-0148:Docker 首次设置按请求来源开放+# ADR-0149:Docker 首次设置按请求来源开放- 状态:已采纳- 日期:2026-11-05diff --git a/frontend/src/react/pages/first-access.ts b/frontend/src/react/pages/first-access.tsindex 4a46ce697..88abc5dbb 100644--- a/frontend/src/react/pages/first-access.ts+++ b/frontend/src/react/pages/first-access.ts@@ -1,3 +1,3 @@-/* Docker 首次设置与访问设置共用的那句拒绝说明:来源不是本机或局域网,或带了代理转发头(ADR-0148)。+/* Docker 首次设置与访问设置共用的那句拒绝说明:来源不是本机或局域网,或带了代理转发头(ADR-0149)。* 服务端 403 正文里是同一句(`routes_auth.FIRST_ACCESS_DENIED`)。 */export const FIRST_ACCESS_DENIED = '请从部署 Peach 的机器或同一局域网打开 Peach 完成设置,或在启动容器时设置 PEACH_ACCESS_PASSWORD。';diff --git a/frontend/src/react/pages/login/access-setup.tsx b/frontend/src/react/pages/login/access-setup.tsxindex bca9a83b4..02e80bbd0 100644--- a/frontend/src/react/pages/login/access-setup.tsx+++ b/frontend/src/react/pages/login/access-setup.tsx@@ -1,4 +1,4 @@-/* Docker 访问设置:已经配置过、还没有访问策略的部署,登录页换成这一张卡(ADR-0148)。全新部署走首次设置页。+/* Docker 访问设置:已经配置过、还没有访问策略的部署,登录页换成这一张卡(ADR-0149)。全新部署走首次设置页。** 和桌面首次设置的访问部分同一套控件:「访问密码」开关、两框密码与一句说明。开着时设访问密码,* 关掉就是明确选了免登录,按钮跟着写清楚是哪一种。提交走 `POST /api/configuration/access/first`,diff --git a/frontend/src/react/pages/login/login-page.tsx b/frontend/src/react/pages/login/login-page.tsxindex 6204242dd..180351c10 100644--- a/frontend/src/react/pages/login/login-page.tsx+++ b/frontend/src/react/pages/login/login-page.tsx@@ -3,7 +3,7 @@* 画哪一种由服务端判定后经 `data-mode` 交进来,页面不自己猜:没有这个键是有访问策略的部署,框里填* 访问密码;`legacy` 是还没有访问策略的非 Docker 部署,框里填自动生成的访问口令,下面一句说用* `peach token` 查看;`setup` 是 Docker 还没有访问策略、来源是本机或局域网,换成访问设置;`denied`- * 是同样情况但来源不满足,先说去哪里打开,再给访问口令登录(ADR-0148)。+ * 是同样情况但来源不满足,先说去哪里打开,再给访问口令登录(ADR-0149)。** 表单是原生提交:`POST /login` 收 `token`、`next`,勾选「保持登录」时多带 `days=30`,会话 cookie 由它的* 303 设下,页面不经脚本发请求。口令不对(401)、尝试太多(429)、保持登录时间不合法(400)时服务端diff --git a/scripts/smoke_docker.py b/scripts/smoke_docker.pyindex 90ddfdc84..121c36a09 100644--- a/scripts/smoke_docker.py+++ b/scripts/smoke_docker.py@@ -37,7 +37,7 @@ def request(name: str, path: str, *, authenticated: bool = True, body: dict | Nodef ready(name: str, *, setup: bool = False) -> None:- """等到服务就绪;`setup` 为真时等的是全新数据卷上的首次设置服务(ADR-0148)。"""+ """等到服务就绪;`setup` 为真时等的是全新数据卷上的首次设置服务(ADR-0149)。"""deadline = time.monotonic() + 90while time.monotonic() < deadline:try:diff --git a/src/peach/api.py b/src/peach/api.pyindex 9010ffb2d..8b66ea5ed 100644--- a/src/peach/api.py+++ b/src/peach/api.py@@ -144,7 +144,7 @@ class ResponseHeadersMiddleware:class FirstSetupSourceMiddleware:- """Docker 首次设置完成前,服务没有口令也没有访问策略,谁连得上谁就能调接口(ADR-0148)。+ """Docker 首次设置完成前,服务没有口令也没有访问策略,谁连得上谁就能调接口(ADR-0149)。这段时间 `/api/` 与写请求只收 `local_client` 认的来源:本机或私有网络、不带代理转发头。页面壳与静态资源照常给,来源不满足的浏览器也能看到首次设置页上那句说明。配置完成后diff --git a/src/peach/health.py b/src/peach/health.pyindex ebf0e4af5..26e7f6cf6 100644--- a/src/peach/health.py+++ b/src/peach/health.py@@ -64,7 +64,7 @@ def readiness(settings: PeachSettings, *, background_ready: bool | None = None)Docker 全新数据卷先起首次设置服务,等用户在页面上答题,这就是它此刻该在的状态:报就绪,另带 `setup: true`。否则镜像的 HEALTHCHECK 会在首启窗口里把容器标成 unhealthy,等它健康- 才启动的 Watchtower 也跟着卡住(ADR-0148)。+ 才启动的 Watchtower 也跟着卡住(ADR-0149)。"""if not settings.configured and distribution.docker():return {"ready": True, "setup": True, "checks": {"web": settings.page_path.is_file()}}diff --git a/src/peach/routes_auth.py b/src/peach/routes_auth.pyindex 7fc72a1b5..c1646a946 100644--- a/src/peach/routes_auth.py+++ b/src/peach/routes_auth.py@@ -332,7 +332,7 @@ def login_mode(request: Request) -> str:有访问策略时是 `password`,框里填访问密码。没有策略(`legacy`)时,非 Docker 部署填自动生成的访问口令;Docker 已经配置过(全新部署走首次设置页)时改在这里设访问密码或选免登录(`setup`),来源须过 `local_client`:本机或私有网络、不带代理转发头。来源不满足的是- `denied`,只能用口令登录(ADR-0148)。+ `denied`,只能用口令登录(ADR-0149)。"""if access.load(request.app.state.settings.access_path)["mode"] != "legacy":return "password"diff --git a/src/peach/routes_configuration.py b/src/peach/routes_configuration.pyindex 74e9fd78c..ed5d62eb1 100644--- a/src/peach/routes_configuration.py+++ b/src/peach/routes_configuration.py@@ -1075,7 +1075,7 @@ def save_access(request: Request, body: dict[str, Any] = Body(default_factory=di@router.post("/api/configuration/access/first")def first_access(request: Request, body: dict[str, Any] = Body(default_factory=dict)):- """Docker 访问设置:已经配置过、还没有访问策略的部署设访问密码或明确选择免登录(ADR-0148)。+ """Docker 访问设置:已经配置过、还没有访问策略的部署设访问密码或明确选择免登录(ADR-0149)。这时没有登录可言,边界只剩来源:`login_mode` 判 `setup` 才收,即本机或私有网络、不带代理转发头;提交再按 `origin_allowed` 看是不是 Peach 自己的页面发的,首次设置时隧道diff --git a/src/peach/routes_pages.py b/src/peach/routes_pages.pyindex 89cd54aff..d48e0a93c 100644--- a/src/peach/routes_pages.py+++ b/src/peach/routes_pages.py@@ -426,7 +426,7 @@ def _setup_guard(request: Request, *, submit: bool) -> None:「禁止」——把它做成一条可探测的 403 等于对外宣告这里有个初始化入口);非回环调用方是403(引导服务只绑 127.0.0.1,能走到这里说明有人转发了它);独立包认地址栏里的主机名,不是回环写法也是 403。Docker 的请求都从网桥进来,不能只认回环,改按 `local_client`- 收本机与私有网络、不带代理转发头的来源(ADR-0148),403 正文带 `docker` 让页面说清楚去哪里打开。+ 收本机与私有网络、不带代理转发头的来源(ADR-0149),403 正文带 `docker` 让页面说清楚去哪里打开。提交再按 `origin_allowed` 看来源:从别的页面发来的表单不收,隧道地址在首启时不算本机。"""settings = request.app.state.settingsdiff --git a/src/peach/server.py b/src/peach/server.pyindex 2a5d74f72..b415f4374 100644--- a/src/peach/server.py+++ b/src/peach/server.py@@ -10,7 +10,7 @@ import threadingfrom . import access, distribution, onboarding, settings_file-#: 容器首次启动时直接设好的访问密码(ADR-0148);读过就从环境里删掉,不传给子进程。+#: 容器首次启动时直接设好的访问密码(ADR-0149);读过就从环境里删掉,不传给子进程。ACCESS_PASSWORD_ENV = "PEACH_ACCESS_PASSWORD"@@ -55,7 +55,7 @@ def initialize() -> None:if config.directory("database").joinpath("ledger.db").exists():raise RuntimeError("已有数据库但缺少配置文件,请恢复 config.toml 后启动")if distribution.docker():- # 全新数据卷不替用户答题:服务以未配置状态起来,浏览器打开就是首次设置页(ADR-0148)。+ # 全新数据卷不替用户答题:服务以未配置状态起来,浏览器打开就是首次设置页(ADR-0149)。returnprocess = launch("init", "--no-input")try:diff --git a/tests/test_access.py b/tests/test_access.pyindex 887186119..bb27eb5b1 100644--- a/tests/test_access.py+++ b/tests/test_access.py@@ -544,7 +544,7 @@ class CertificateTrustTests(ConfigurationPageCase):class DockerFirstAccessTests(ConfigurationPageCase):- """Docker 还没有访问策略时,登录页换成访问设置;只收本机与私有网络、不带转发头的来源(ADR-0148)。"""+ """Docker 还没有访问策略时,登录页换成访问设置;只收本机与私有网络、不带转发头的来源(ADR-0149)。"""DOCKER = {"PEACH_DISTRIBUTION": "docker", "PEACH_HEADLESS_MANAGED": "1"}diff --git a/tests/test_fastapi_api.py b/tests/test_fastapi_api.pyindex 52b8ca283..ff416b1d4 100644--- a/tests/test_fastapi_api.py+++ b/tests/test_fastapi_api.py@@ -4178,7 +4178,7 @@ PUBLIC_ROUTES = {("GET", "/api/setup/questions"),("POST", "/api/setup"),("POST", "/api/setup/restore"),- # Docker 首次访问设置的提交(ADR-0148)。这时还没有访问策略,没有密码可验;只在 Docker 且+ # Docker 首次访问设置的提交(ADR-0149)。这时还没有访问策略,没有密码可验;只在 Docker 且# 没有策略时收,来源须是本机或私有网络、不带代理转发头(403),再看 Origin(403);已有策略# 就 409,非 Docker 是 404。("POST", "/api/configuration/access/first"),diff --git a/tests/test_onboarding.py b/tests/test_onboarding.pyindex c161b2b4c..5f2e2d9bb 100644--- a/tests/test_onboarding.py+++ b/tests/test_onboarding.py@@ -1004,7 +1004,7 @@ class SetupJsonContractTests(_SetupHttpCase):@unittest.skipUnless(HAS_HTTP_DEPS, "需要 fastapi 与 httpx")class DockerFirstSetupTests(_SetupHttpCase):- """全新 Docker 走同一张首次设置页:来源按本机或私有网络判,数据目录固定为卷(ADR-0148)。"""+ """全新 Docker 走同一张首次设置页:来源按本机或私有网络判,数据目录固定为卷(ADR-0149)。"""QUESTIONS = "/api/setup/questions"SUBMIT = "/api/setup"