Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(docker): Docker 首次设置的 ADR 改号为 0149

longmeidaof484d01644b8
diff --git a/SECURITY.md b/SECURITY.md
index 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.md
index 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.md
index 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.md
similarity index 99%
rename from docs/adr/0148-docker-first-access-setup.md
rename to docs/adr/0149-docker-first-access-setup.md
index 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-05
diff --git a/frontend/src/react/pages/first-access.ts b/frontend/src/react/pages/first-access.ts
index 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.tsx
index 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.tsx
index 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.py
index 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 | No
def ready(name: str, *, setup: bool = False) -> None:
- """等到服务就绪;`setup` 为真时等的是全新数据卷上的首次设置服务(ADR-0148)。"""
+ """等到服务就绪;`setup` 为真时等的是全新数据卷上的首次设置服务(ADR-0149)。"""
deadline = time.monotonic() + 90
while time.monotonic() < deadline:
try:
diff --git a/src/peach/api.py b/src/peach/api.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.settings
diff --git a/src/peach/server.py b/src/peach/server.py
index 2a5d74f72..b415f4374 100644
--- a/src/peach/server.py
+++ b/src/peach/server.py
@@ -10,7 +10,7 @@ import threading
from . 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)。
return
process = launch("init", "--no-input")
try:
diff --git a/tests/test_access.py b/tests/test_access.py
index 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.py
index 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.py
index 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"