Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(docker): 记录首次访问设置的取舍,部署说明改成新流程

longmeidao22ebf98a54da
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 938287be0..603894d83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,7 @@ Removed / Fixed / Security。
### 新增
- **更新**:Docker 镜像同时发布到 `ghcr.io/peach-mitao/peach`,Docker Hub 拉取受限时可以改用。
+- **配置**:Docker 首次打开先进入访问设置,可设密码或免登录,不再要口令;也可用 `PEACH_ACCESS_PASSWORD` 预设。
### 修复
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index a475e8ceb..771a6a27f 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -43,13 +43,15 @@ PEACH_MEDIA_ROOT=/srv/videos
`192.0.2.10` 是文档示例地址,不能直接用于部署。NAS 管理界面支持 Compose 环境变量时,也可在那里填写这三个值。应用配置并重新创建容器后,打开 `http://<NAS 局域网 IP>:<PEACH_PORT>`。不要在另一台电脑上用 `127.0.0.1` 访问 NAS。
-登录口令由 Peach 随机生成,没有通用初始密码。在 NAS 的容器管理界面打开 Peach 容器终端,运行 `peach token` 查看;通过宿主机 Compose 终端时运行 `docker compose exec peach peach token`。登录后设置访问密码。
+首次打开时,Peach 会进入访问设置:设访问密码,或关掉开关选择免登录,提交后直接进入。这一步只接受宿主机或同一局域网设备打开的页面;经反向代理或公网打开时,页面会提示改从这些地址打开。局域网里第一个打开的人就能完成设置,介意时用下面的 `PEACH_ACCESS_PASSWORD` 预设密码。
### 初始化与管理
-使用 Compose 启动后,Peach 会为全新数据卷创建配置、数据库和随机登录口令。已有配置保持原值;如果已有数据库但缺少配置文件,服务拒绝启动,需要恢复配置文件。初始化日志只显示口令文件位置。
+使用 Compose 启动后,Peach 会为全新数据卷创建配置、数据库和随机访问口令。已有配置保持原值;如果已有数据库但缺少配置文件,服务拒绝启动,需要恢复配置文件。初始化日志只显示口令文件位置。
-在容器终端运行 `peach token` 取得登录口令,在浏览器登录后设置访问密码。配置页要求登录,并且连接必须来自容器本机或私有网络;携带代理转发头的管理请求会被拒绝。通过配置页保存后,服务自动读取配置;勾选扫描时会启动资料处理。
+也可以在 `.env` 里写 `PEACH_ACCESS_PASSWORD=<8–256 个字符的密码>`,并取消 `compose.yaml` 中对应行的注释。容器首次启动时直接用它设访问密码,跳过网页里的访问设置,日志不显示密码;已有访问设置时忽略它,改密码请到配置页。
+
+访问口令仍会自动生成,供用户脚本和 API 使用,容器终端运行 `peach token`、宿主机运行 `docker compose exec peach peach token` 查看。配置页要求登录,并且连接必须来自容器本机或私有网络;携带代理转发头的管理请求会被拒绝。通过配置页保存后,服务自动读取配置;勾选扫描时会启动资料处理。
容器内 HTTP 端口固定为 8900,访问端口在 Compose 设置。默认只发布到宿主机 `127.0.0.1`,远程访问使用私有 VPN 或 SSH 隧道。需要局域网访问时,通过 `PEACH_BIND` 绑定宿主机的局域网地址,并设置访问密码。公网托管边界见 [安全说明](../SECURITY.md)。Docker 镜像不提供多人账号或租户隔离。
diff --git a/docs/adr/0148-docker-first-access-setup.md b/docs/adr/0148-docker-first-access-setup.md
new file mode 100644
index 000000000..b802fac81
--- /dev/null
+++ b/docs/adr/0148-docker-first-access-setup.md
@@ -0,0 +1,33 @@
+# ADR-0148:Docker 首次访问设置按来源限制
+
+- 状态:已采纳
+- 日期:2026-11-05
+- 关系:扩展 [ADR-0105](0105-linux-headless-container.md) 的访问边界
+
+## 背景
+
+Docker 用户首次打开 Peach,会被要求填一个从没设过的「访问密码」(讨论 #379)。镜像入口 `peach.server` 用非交互的 `peach init` 初始化,不写访问策略 `secrets/access.json`;没有策略时 `access.load()` 返回 `legacy`,登录页认的是自动生成的访问口令,要在容器里运行 `peach token` 才看得到。
+
+Windows 与 macOS 不会遇到这个问题。托盘的首次设置页(`build_setup_service_specs`)只绑本机回环,不需要口令;用户在页面上设访问密码,或留空免登录,提交时写下 open 或 password 策略。口令照旧生成,只给用户脚本和 API 用。
+
+Docker 不能照搬回环边界:宿主机和局域网的请求都从网桥进入容器,在容器里看来源都不是回环。
+
+## 决策
+
+**一、Docker 没有访问策略时,登录页换成访问设置。** 服务在 `PEACH_DISTRIBUTION=docker` 下运行、访问策略文件不存在时,浏览器打开任意页面都会转到 `/login`,页面画访问设置而不是口令框:设访问密码,或关掉开关明确选择免登录,内容和桌面首次设置的访问部分一致。提交 `POST /api/configuration/access/first` 写入 password 或 open 策略;设了密码就给提交的浏览器签发会话,直接进入。
+
+**二、边界由回环换成请求来源。** 页面和提交都只接受 `web_local_access.local_client` 判定的来源:本机或私有网络地址,且不带 `X-Forwarded-*`、`Forwarded`、`CF-Connecting-IP` 等代理转发头。判定与 ADR-0105 的配置页管理边界是同一个函数,不另写一套。提交还要通过 `origin_allowed`,隧道地址这时不算本机。来源不满足时,页面说明请从部署机器或局域网打开,或在启动时设置 `PEACH_ACCESS_PASSWORD`,并保留访问口令登录。
+
+**三、`PEACH_ACCESS_PASSWORD` 是预设路径。** 容器首次启动且没有策略文件时,`peach.server` 用它写入 password 策略,日志只说已按该变量设置,不输出明文。已有策略时忽略它并提示一次,改密码仍走配置页。值不合规时只报原因、照常启动,浏览器打开后仍进入访问设置。读过后从环境里删掉,不传给服务子进程。
+
+**四、口令不变。** 访问口令照旧生成,用户脚本、`X-Token`、`?t=` 和登录页的口令登录都不变。非 Docker 部署没有访问策略时仍是口令登录,登录页由服务端告知模式,标签写「访问口令」,下方说明用 `peach token` 查看。
+
+## 与桌面版的区别
+
+桌面首次设置页只监听回环,能打开它的只有运行 Peach 的那台电脑。Docker 的访问设置跑在正式服务上,监听容器的全部地址,能打开它的是一个网络范围:宿主机,以及在 `PEACH_BIND` 绑了局域网地址时同一局域网的设备。
+
+## 代价
+
+- **局域网里第一个打开的人能设密码。** 设置完成前,同一局域网里能连到 Peach 的任何设备都能抢先设访问密码或选免登录。提交在文件锁里再确认一次策略不存在,后到的收 409,不会覆盖已有设置。介意这个窗口的部署用 `PEACH_ACCESS_PASSWORD` 预设,或先保持 Compose 默认的 `127.0.0.1` 绑定,在宿主机上完成设置后再改绑局域网地址。
+- 已在用口令登录、但从没设过访问密码的 Docker 部署,升级后未登录的浏览器会看到访问设置,而不是口令登录框。已登录的浏览器不受影响。
+- 私有地址只说明请求来自私有网段。宿主机上的反向代理若不加转发头,会被当成本机来源放行;这和 ADR-0105 配置页的边界相同。