Skip to content

armgit / peach

Public Imported from GitHub
0

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

fix(docker): 首次设置期间就绪检查报就绪,容器冒烟改走首次设置

longmeidao60a101aae6ae
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 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.md
index 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.py
index c62a26c94..90ddfdc84 100644
--- a/scripts/smoke_docker.py
+++ b/scripts/smoke_docker.py
@@ -1,4 +1,4 @@
-"""使用独立容器与临时卷验收镜像的初始化、鉴权、配置重载和持久化。"""
+"""使用独立容器与临时卷验收镜像的首次设置、鉴权、配置重载和持久化。"""
from __future__ import annotations
import argparse
@@ -18,9 +18,8 @@ def request(name: str, path: str, *, authenticated: bool = True, body: dict | No
headers: 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 | No
json.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() + 90
while 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.py
index 7e1e135e8..ebf0e4af5 100644
--- a/src/peach/health.py
+++ b/src/peach/health.py
@@ -3,6 +3,7 @@ import sqlite3
import re
from contextlib import closing
+from . import distribution
from .config import MIGRATIONS_DIR, PeachSettings
from .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.py
index 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)