Peach: Local-first video metadata scraper and media manager.
fix(docker): 首次设置期间就绪检查报就绪,容器冒烟改走首次设置
longmeidao60a101aae6ae
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex e42b7396b..a17401be5 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。+- 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`。- 两条接口共用守卫(`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/adr/0148-docker-first-access-setup.md b/docs/adr/0148-docker-first-access-setup.mdindex 99ce824fa..e652733ee 100644--- a/docs/adr/0148-docker-first-access-setup.md+++ b/docs/adr/0148-docker-first-access-setup.md@@ -33,6 +33,6 @@ Docker 不能照搬回环边界:宿主机和局域网的请求都从网桥进## 代价- **局域网里第一个打开的人能完成设置。** 设置完成前,同一局域网里能连到 Peach 的任何设备都能抢先答题、设访问密码或选免登录。首次设置在设置文件已存在时回 409,访问设置卡在文件锁里再确认一次策略不存在,后到的都不会覆盖已有设置。介意这个窗口的部署用 `PEACH_ACCESS_PASSWORD` 预设,或先保持 Compose 默认的 `127.0.0.1` 绑定,在宿主机上完成设置后再改绑局域网地址。-- **首启前服务处于未配置状态。** 没有账本、口令和访问策略,后台调度不启动,健康检查照常应答;本机与私有网络来源可以调用全部接口,这和桌面引导服务对回环开放相同。设置提交后服务换成正常模式,会断开一两秒,完成页按配置页重启后的同一时长再跳转。设了访问密码的部署,进入后要用这个密码登录一次。+- **首启前服务处于未配置状态。** 没有账本、口令和访问策略,后台调度不启动。`/healthz?ready=1` 这时报就绪并带 `setup: true`,镜像的 HEALTHCHECK 和等它健康才启动的 Watchtower 不会卡在首启窗口;本机与私有网络来源可以调用全部接口,这和桌面引导服务对回环开放相同。设置提交后服务换成正常模式,会断开一两秒,完成页按配置页重启后的同一时长再跳转。设了访问密码的部署,进入后要用这个密码登录一次。- 已在用口令登录、但从没设过访问密码的 Docker 部署,升级后未登录的浏览器会看到访问设置卡,而不是口令登录框。已登录的浏览器不受影响。- 私有地址只说明请求来自私有网段。宿主机上的反向代理若不加转发头,会被当成本机来源放行;这和 ADR-0105 配置页的边界相同。diff --git a/scripts/smoke_docker.py b/scripts/smoke_docker.pyindex c62a26c94..90ddfdc84 100644--- a/scripts/smoke_docker.py+++ b/scripts/smoke_docker.py@@ -1,4 +1,4 @@-"""使用独立容器与临时卷验收镜像的初始化、鉴权、配置重载和持久化。"""+"""使用独立容器与临时卷验收镜像的首次设置、鉴权、配置重载和持久化。"""from __future__ import annotationsimport argparse@@ -18,9 +18,8 @@ def request(name: str, path: str, *, authenticated: bool = True, body: dict | Noheaders: dict | None = None):script = ("import json,urllib.request,urllib.error; from pathlib import Path; "- "token=Path('/data/secrets/auth-token').read_text().strip(); ""body=json.loads(__import__('sys').argv[1]); "- "headers={'X-Token':token} if body['auth'] else {}; "+ "headers={'X-Token':Path('/data/secrets/auth-token').read_text().strip()} if body['auth'] else {}; ""headers=headers | (body['headers'] or {}); ""headers['Content-Type']='application/json'; ""req=urllib.request.Request('http://127.0.0.1:8900'+body['path'],"@@ -37,13 +36,15 @@ def request(name: str, path: str, *, authenticated: bool = True, body: dict | Nojson.dumps({"auth": authenticated, "path": path, "body": body, "headers": headers}))-def ready(name: str) -> None:+def ready(name: str, *, setup: bool = False) -> None:+ """等到服务就绪;`setup` 为真时等的是全新数据卷上的首次设置服务(ADR-0148)。"""deadline = time.monotonic() + 90while time.monotonic() < deadline:try:response = json.loads(request(name, "/healthz?ready=1", authenticated=False))- if "status" not in response:+ if "status" not in response and response.get("setup", False) == setup:return+ time.sleep(1)except subprocess.CalledProcessError:if docker("inspect", "-f", "{{.State.Running}}", name) != "true":raise RuntimeError(docker("logs", name)) from None@@ -108,6 +109,15 @@ def main() -> None:docker("volume", "create", volume)docker("run", "-d", "--name", name, "--network", "none","--mount", f"type=volume,source={volume},target=/data", args.image)+ ready(name, setup=True)+ # 全新数据卷不再自动初始化:先答首次设置,设访问密码,后面的未登录请求才是 401。+ assert docker("exec", name, "python", "-c",+ "from pathlib import Path; print(Path('/data/config.toml').exists())") == "False"+ done = json.loads(request(name, "/api/setup", authenticated=False, body={+ "media_dir": [], "skip_media": True, "scan_now": False, "access_enabled": True,+ "access_password": "smoke-password", "access_confirm": "smoke-password"}))+ assert done.get("url") == "/?onboarding=1", done+ time.sleep(2)ready(name)assert docker("exec", name, "id", "-u") == "1000"assert json.loads(request(name, "/api/items")) is not None@@ -155,7 +165,7 @@ def main() -> None:docker("restart", "--time", "75", name)ready(name)assert docker("exec", name, "cat", config_path) == original- print(json.dumps({"image": args.image, "checks": ["non-root", "ready", "auth", "configuration",+ print(json.dumps({"image": args.image, "checks": ["first-setup", "non-root", "ready", "auth", "configuration","scan", "range", "vaapi-stack", "transcode-fallback","amane-prerequisites", "reload", "restart", "persistence"]}))finally:diff --git a/src/peach/health.py b/src/peach/health.pyindex 7e1e135e8..ebf0e4af5 100644--- a/src/peach/health.py+++ b/src/peach/health.py@@ -3,6 +3,7 @@ import sqlite3import refrom contextlib import closing+from . import distributionfrom .config import MIGRATIONS_DIR, PeachSettingsfrom .migrations import applied, discover@@ -59,6 +60,14 @@ def database_status(path) -> str:def readiness(settings: PeachSettings, *, background_ready: bool | None = None) -> dict:+ """服务能不能用:已配置、页面在、账本可读且结构是最新的,后台任务按需也算进去。++ Docker 全新数据卷先起首次设置服务,等用户在页面上答题,这就是它此刻该在的状态:报就绪,+ 另带 `setup: true`。否则镜像的 HEALTHCHECK 会在首启窗口里把容器标成 unhealthy,等它健康+ 才启动的 Watchtower 也跟着卡住(ADR-0148)。+ """+ if not settings.configured and distribution.docker():+ return {"ready": True, "setup": True, "checks": {"web": settings.page_path.is_file()}}checks = {"configured": bool(settings.configured),"web": settings.page_path.is_file(), "database": False, "schema": False}inspected = inspect_database(settings.db_path)diff --git a/tests/test_onboarding.py b/tests/test_onboarding.pyindex 117386817..c161b2b4c 100644--- a/tests/test_onboarding.py+++ b/tests/test_onboarding.py@@ -1086,6 +1086,13 @@ class DockerFirstSetupTests(_SetupHttpCase):self.assertEqual(response.status_code, 200, response.text)self.assertTrue(access.verify(access.load(path), "container-secret"))+ def test_the_setup_service_reports_ready_so_the_container_healthcheck_passes(self):+ ready = self._send("GET", "/healthz?ready=1")+ self.assertEqual(ready.status_code, 200)+ self.assertEqual((ready.json()["ready"], ready.json()["setup"]), (True, True))+ with mock.patch.dict(os.environ, {"PEACH_DISTRIBUTION": "source"}):+ self.assertEqual(self._send("GET", "/healthz?ready=1").status_code, 503, "桌面引导服务照旧不算就绪")+def test_restoring_another_data_root_is_not_offered(self):response = self._send("POST", "/api/setup/restore", json={"data_root": str(self.root)}, client=self.LAN)self.assertEqual(response.status_code, 404)