Peach: Local-first video metadata scraper and media manager.
docs(config): 讲清跨平台路径与 Docker 配置行为
longmeidao9c46a8f57f92
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex de6b2375f..d205122cb 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -14,7 +14,7 @@ Peach 是一个 FastAPI 模块化单体:逻辑上前后端分离,部署时1. **Ledger**:资产、行为、来源和知识的唯一真相源,用 SQLite,单用户规模够用。硬盘上那份是权威副本,两台机器各持本地工作副本,由 `peach.sync` 做单写者复制:拉取、回写,冲突时转只读,**不做多主合并**。2. **API / 应用层**:FastAPI 承载页面、JSON、媒体响应和写入边界。`api.py` 只负责组装,路由分 `routes_auth`、`routes_pages`、`routes_media`、`routes_configuration`、`routes_api` 五个 APIRouter;`/api/{route}` 由 `web_router` 的 handler 表分派到 `web_catalog`、`web_entity`、`web_stats`、`web_batch`、`web_follow` 等域模块。-3. **平台层**:`peach.platform` 是账本路径与本机挂载点之间唯一的翻译层。账本只用 Windows 盘符记路径,读取时按「来源的声明根 → 本机挂载点」翻译:来源即 `asset.location`,两侧由设置文件的 `[media.locations]` 与 `[media.mounts]` 给出,`PEACH_MEDIA_MOUNTS` 可临时覆盖。没有挂载点的来源落到不可达根,整体按脱盘处理。CloudDrive 在 Windows 是盘符、在 macOS 是 macFUSE 挂载点,差异全部收在这一层。+3. **平台层**:`peach.platform` 把数据库中的媒体路径转换为当前系统实际读取的文件路径。影片记录的 `asset.path` 在所有系统上都使用 Windows 格式;`asset.location` 表示媒体来源,例如 `local`、`115`。`[media.locations]` 保存数据库中的目录前缀,`[media.mounts]` 保存本机实际目录。例如数据库中的 `R:\media\a.mp4` 可对应容器中的 `/media/a.mp4`,Linux 无需存在 `R:` 盘。Docker、Linux、macOS 都使用这两项配置;Windows 直接使用数据库路径。缺少对应实际目录时,平台层拒绝读取,该来源显示离线,数据库中的媒体记录保留。`PEACH_MEDIA_MOUNTS` 可临时覆盖实际目录。CloudDrive 在 Windows 使用盘符,在 macOS 使用 macFUSE 挂载目录,系统差异由这一层处理。4. **Media Engine**:FastAPI 只持有一个 `MediaEngine`,本地文件与挂载网盘都是原生后端。远端 MP4 默认走标准 Range;`stream-plan` 只在显式开启时给出按时间生成的 HLS 片段。HLS 是例外而不是默认,因为 HEVC-in-TS 会静默黑屏(ADR-0016)。5. **Web**:单页、移动端优先。主界面由 React 路由树渲染,应用域控制器、共享状态和控件位于 `frontend/src/`;使用 Tailwind v4 与 BoardUI 源码,构建产物提交进 `web/dist/`。适配器清退遵循 ADR-0031,模块职责见 [前端层](FRONTEND.md)。6. **AI Provider**:`InferenceProvider` 与 `AgentProvider` 分开。AI 只产出带来源和置信度的候选。diff --git a/docs/CLOUDDRIVE.md b/docs/CLOUDDRIVE.mdindex 029c39ff7..b3004823a 100644--- a/docs/CLOUDDRIVE.md+++ b/docs/CLOUDDRIVE.md@@ -11,13 +11,14 @@ Peach 支持已挂载的 115、PikPak、光鸭、OneDrive,以及「其他已## 配置步骤1. 在 CloudDrive2 里登录网盘、建立挂载点,并打开「启动时自动挂载」。具体操作见 [CloudDrive 官方帮助](https://www.clouddrive2.com/help.html)。-2. 在 Peach 首次设置页,或 Peach 配置的「媒体库与入库」分组里添加文件夹,选择实际网盘来源。未单列的网盘选「其他已挂载网盘」。同一个来源可以添加多个文件夹,但文件夹之间不能互相包含。+2. 在 Peach 首次设置页,或配置页的媒体分组里添加文件夹,选择实际网盘来源。未单列的网盘选「其他已挂载网盘」。同一个来源可以添加多个文件夹,但文件夹之间不能互相包含。3. 填写路径:- Windows:直接填挂载出来的盘符路径,例如 `B:\`。- - macOS:「本机文件夹」填本机挂载点,「Windows 中的对应路径」填这个来源在 Windows 上的盘符根,例如 `/Volumes/CloudDrive/115` 对应 `B:\`、`/Volumes/CloudDrive/PikPak` 对应 `A:\`。已经有馆藏的,必须沿用馆藏里登记的盘符路径。+ - macOS、Linux:「本机文件夹」填 Peach 实际读取的目录。「Windows 中的对应路径」填数据库中影片路径的目录前缀,Peach 要求这个值使用 Windows 格式;它不表示必须有一台 Windows 电脑。例如 `/Volumes/CloudDrive/115` 可对应 `B:\`,已有影片时必须匹配数据库中已保存的路径。+ - Docker:「本机文件夹」填容器内目录,例如 `/media/115`,不能填容器无法访问的宿主机路径。还需要在 Compose 中把实际目录挂进容器;两项路径配置的含义和完整示例见 [Docker 部署](DOCKER.md#配置文件与路径)。4. 为新增网盘目录选择「媒体读取策略」:正常读取,或代理流量保护。PikPak 也由用户选择;实际走哪条代理需在挂载工具中配置。-5. 点「保存配置」,托盘会重新载入设置。每个文件夹行右侧标着它在线还是离线,刷新页面重新读取。-6. 勾选扫描再保存,托盘会依次扫描所有在线的文件夹,离线的跳过。网盘重新挂上以后,再勾选一次扫描并保存即可。+5. 点「保存配置」,Peach 会重新读取设置。每个文件夹行右侧标着它在线还是离线,刷新页面重新读取。+6. 勾选扫描再保存,Peach 会依次扫描所有在线的文件夹,离线的跳过。网盘重新挂上以后,再勾选一次扫描并保存即可。Windows 上,Peach 和 CloudDrive2 要在同一个普通用户下运行。用「以管理员身份运行」启动的程序,可能看不到普通用户挂载的盘。diff --git a/docs/DIRECTORY_BROWSING.md b/docs/DIRECTORY_BROWSING.mdindex 642ea0ef9..3b3e3fc99 100644--- a/docs/DIRECTORY_BROWSING.md+++ b/docs/DIRECTORY_BROWSING.md@@ -1,6 +1,6 @@# 目录浏览-馆藏筛选条右侧的「文件夹模式」开关打开目录树和面包屑。目录树按媒体库声明根展示已登记的目录,保留原目录名与层级。关闭开关返回全部作品。+馆藏筛选条右侧的「文件夹模式」开关打开目录树和面包屑。目录树按媒体库配置中的顶层目录分组,展示数据库中已登记的目录,保留原目录名与层级。关闭开关返回全部作品。右侧「卡片 / 列表」切换馆藏显示方式,首页与资料页的作品区共用,当前浏览器会记住选择。列表展示封面、名称、归属、时长、体积和观看次数,行间以直线分隔;窄屏将时长和体积收在名称下方。diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 26c2cb92d..36d097cc3 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -1,14 +1,14 @@# Docker 部署-Peach 的 Linux 无桌面镜像用于单人 VPS 与 NAS,镜像仓库为 [longmeidao/peach](https://hub.docker.com/r/longmeidao/peach)。`edge` 是主线候选,版本号标签对应发布提交。当前镜像目标为 `linux/amd64`;ARM NAS 尚未验收。2026-10-15 在 WSL 的独立 Docker Engine 中,用正式锁定依赖通过空数据卷初始化、非 root、鉴权、配置保存、合成视频扫描、HTTP Range、配置重载与重启持久化验收。+Peach 的 Docker 镜像用于单人 VPS 与 NAS,通过浏览器管理,镜像仓库为 [longmeidao/peach](https://hub.docker.com/r/longmeidao/peach)。`edge` 随 `master` 分支构建更新,版本号标签对应发布提交。当前镜像目标为 `linux/amd64`;ARM NAS 尚未验收。2026-10-15 在 WSL 的独立 Docker Engine 中,用正式锁定依赖通过空数据卷初始化、非 root、鉴权、配置保存、合成视频扫描、HTTP Range、配置重载与重启持久化验收。-Docker 使用浏览器管理,无需桌面托盘。配置文件中的盘符是账本路径标识,实际媒体目录由容器挂载提供。Windows 安装包、macOS 源码运行和 Docker 的入口分别见 [README](../README.md#下载与使用)。+Docker 不使用桌面托盘。Peach 数据库在所有系统上都保存 Windows 格式的媒体路径;Linux 实际读取文件时,由配置把这些路径转换成容器中的目录。这里的盘符是 Peach 数据库的存储格式,Linux 无需创建对应盘符。Windows 安装包、macOS 源码运行和 Docker 的入口分别见 [README](../README.md#下载与使用)。## 数据与媒体-`/data` 保存配置、SQLite 账本、凭据和图片缓存,必须持久化。媒体通过 `/media` 单独挂入;默认只读,扫描和播放不需要媒体写权限。整理、移动与删除需要使用者明确提供可写挂载。+`/data` 保存配置、SQLite 数据库、凭据和图片缓存,必须使用数据卷保存,重建容器时保留该卷。媒体目录单独挂到 `/media`;默认只读,扫描和播放不需要媒体写权限。整理、移动与删除需要使用者明确提供可写挂载。-CloudDrive2 与 Peach 分别运行。NAS 已有 CloudDrive2 时直接复用;全新机器按 [CloudDrive2 官方 Docker 指南](https://www.clouddrive2.com/docker.html) 安装并绑定网盘。宿主机必须支持 FUSE,CloudDrive2 的挂载目录需要共享传播;Peach 用 `rslave` 接收挂载,不需要 FUSE 或特权容器。挂载目录的权限必须允许 UID 1000 读取。+CloudDrive2 与 Peach 分别运行。NAS 已有 CloudDrive2 时直接复用;全新机器按 [CloudDrive2 官方 Docker 指南](https://www.clouddrive2.com/docker.html) 安装并绑定网盘。宿主机必须支持 FUSE,并允许把 CloudDrive2 后续挂上的子目录传入 Peach 容器;Compose 中的 `rslave` 用于接收这些挂载。Peach 容器不需要 FUSE 或特权模式。目录权限必须允许容器用户 UID 1000 读取。需要云下载或推送发现时,Peach 配置中的 CloudDrive2 API 地址使用同一容器网络的服务名或可达的宿主机地址;容器里的 `127.0.0.1` 只指向 Peach 自己。@@ -16,15 +16,19 @@ CloudDrive2 与 Peach 分别运行。NAS 已有 CloudDrive2 时直接复用;## 首次运行与访问-使用 Compose 启动后,无桌面入口会为全新数据卷初始化配置、账本和随机内部口令。它不覆盖已有配置;发现只有账本而没有配置时拒绝启动。初始化日志只显示口令文件位置。+使用 Compose 启动后,Peach 会为全新数据卷创建配置、数据库和随机登录口令。已有配置保持原值;如果已有数据库但缺少配置文件,服务拒绝启动,需要恢复配置文件。初始化日志只显示口令文件位置。-在容器终端运行 `peach token` 取得登录口令,在浏览器登录后设置访问密码。配置页接受经过鉴权的回环或私有网络连接,带转发头的管理请求会被拒绝。配置保存会自动重载服务;勾选扫描时使用既有资料处理入口。+在容器终端运行 `peach token` 取得登录口令,在浏览器登录后设置访问密码。配置页要求登录,并且连接必须来自容器本机或私有网络;携带代理转发头的管理请求会被拒绝。通过配置页保存后,服务自动读取配置;勾选扫描时会启动资料处理。容器内 HTTP 端口固定为 8900,访问端口在 Compose 设置。默认只发布到宿主机 `127.0.0.1`,远程访问使用私有 VPN 或 SSH 隧道。需要局域网访问时,通过 `PEACH_BIND` 绑定宿主机的局域网地址,并设置访问密码。公网托管边界见 [安全说明](../SECURITY.md)。Docker 镜像不提供多人账号或租户隔离。## 配置文件与路径-配置文件位于持久卷内的 `/data/config.toml`。通常在浏览器配置页添加媒体文件夹即可;手动编辑前先备份文件,编辑后重启容器。已有配置不会因更新镜像而自动覆盖,注释示例可对照本节阅读,无需重新初始化数据卷。+配置文件位于数据卷内的 `/data/config.toml`。通常在浏览器配置页添加媒体文件夹即可;手动编辑前先备份文件,编辑后重启容器。更新镜像保留这个文件,因此已有文件的注释也保持原样。查看配置说明不需要重新初始化数据卷。++默认模板只包含初始值,不包含已有部署的媒体目录和自定义设置。用默认模板整份替换会同时替换这些值,可能使已有影片无法读取。只更新说明时可以替换注释,保留配置值;需要替换整个文件时,先备份并逐项核对差异。++`[media.locations]` 和 `[media.mounts]` 在 Docker、Linux、macOS 上都需要正确配置。前者写数据库中保存的路径前缀,后者写实际读取文件的目录。数据库保存 Windows 格式是 Peach 当前的数据存储设计,不表示 Linux 上存在相同路径。以下三个路径各有用途。假设宿主机媒体目录为 `/srv/videos`,Compose 将它挂到容器 `/media`:@@ -32,7 +36,7 @@ CloudDrive2 与 Peach 分别运行。NAS 已有 CloudDrive2 时直接复用;| --- | --- | --- || 宿主机目录 | `/srv/videos` | 填在 Compose 的 `PEACH_MEDIA_ROOT`,目录必须已存在 || 容器内目录 | `/media` | 填在配置页的媒体目录或 `[media.mounts]`,Peach 实际读取这里 |-| 账本声明根 | `R:\media` | 填在 `[media.locations]`,作为路径标识,无需在容器创建盘符 |+| 数据库中的目录前缀 | `R:\media` | 填在 `[media.locations]`,对应数据库影片路径的开头;无需在 Linux 创建这个目录 |全新本地馆藏可使用以下映射。将两个表中的条目合入已有配置,不要重复添加同名表:@@ -44,11 +48,13 @@ local = 'R:\media'local = '/media'```-此时容器中的 `/media/a.mp4` 对应账本路径 `R:\media\a.mp4`。已有馆藏保留既有声明根,只调整对应挂载点;不能把 `[media.locations]` 改成 `/media`。一个来源有多个目录时,两张表均使用数组,数量和顺序一一对应。+扫描 `/media/a.mp4` 后,Peach 在数据库的影片 `path` 字段中保存 `R:\media\a.mp4`;播放时再把 `R:\media` 替换为 `/media`,读取容器中的 `/media/a.mp4`。数据库中的这段 Windows 路径是字符串,不是 Linux 上实际存在的文件名。++已有影片时,`[media.locations]` 必须继续匹配数据库中的路径前缀。把它改成 `/media` 不会同步修改已有影片记录,反而会使路径无法对应。只搬动实际媒体目录时,保留 `[media.locations]`,调整 `[media.mounts]` 和 Compose 的目录挂载。一个来源有多个目录时,两张表均使用数组,数量和顺序一一对应。-配置页中的「Windows 中的对应路径」填写账本声明根;该字段用于跨平台路径映射。115 的既有声明根通常为 `B:\`,PikPak 为 `A:\`,实际目录分别填写 `/media/115`、`/media/pikpak` 等容器内路径,并确认 Compose 已挂入这些目录。CloudDrive2 是媒体来源之一,本地目录也可直接挂入 Peach。+配置页中的「Windows 中的对应路径」填写数据库中的目录前缀,即使只有一台 Linux 服务器也需要这个值。它不表示必须有一台 Windows 电脑。115 的默认前缀为 `B:\`,PikPak 为 `A:\`;已有部署以数据库中的路径为准。实际目录分别填写 `/media/115`、`/media/pikpak` 等容器内路径,并确认 Compose 已挂入这些目录。CloudDrive2 是媒体来源之一,本地目录也可直接挂入 Peach。-容器的网络监听由无桌面入口控制,宿主机绑定地址和端口使用 Compose 的 `PEACH_BIND`、`PEACH_PORT`;`[server]` 的 `host`、`port` 用于直接运行 `peach serve`。独立 Docker 部署保持 `[replication] enabled = false`,无需配置桌面托盘或 SMB 复制。+容器中的服务固定监听 `0.0.0.0:8900`,宿主机访问地址和端口使用 Compose 的 `PEACH_BIND`、`PEACH_PORT`;`[server]` 的 `host`、`port` 用于直接运行 `peach serve`。独立 Docker 部署保持 `[replication] enabled = false`,无需配置桌面托盘或 SMB 复制。## 更新与范围diff --git a/docs/FRONTEND.md b/docs/FRONTEND.mdindex 36efd1625..df56057c6 100644--- a/docs/FRONTEND.md+++ b/docs/FRONTEND.md@@ -76,7 +76,7 @@ Peach 按 [ADR-0031](adr/0031-frontend-react-boardui-tailwind.md) 接入 React +- 跳到某一组:别处(统计页「添加媒体文件夹」、空库提示、媒体库选单「管理媒体库」、诊断页)把组名记进壳单例 `configurationRequestedSection`(路由树里的页面经 `actions.requestConfigurationSection`),壳打开这一页时作为 `open.section` 交进去、页面画上之后清空;页面只拿它定第一帧选中哪一格。- 设置弹层「这台电脑」一格只挂 `configuration-summary`(`configuration-summary.tsx`):媒体库数、端口、更新状态和「打开配置页」,不放可编辑的控件(ADR-0050)。媒体库数取 `/api/configuration` 的 `library_count`,由服务端按 `media_libraries.libraries` 分组数好,页面不自己归并。- 相邻的两处不在这页:媒体修复是数据管理页 React 子树里的一张卡(`frontend/src/react/media-repair/`),订阅源是关注管理页的「订阅源」页签(`follow-manage/feed-sources.tsx`,读 `/api/feeds`)。-- 服务端按两道门放行:托盘管理的服务、发起连接的是本机。`/healthz` 按调用方回 `configurable`,遗留层据此决定管理菜单列不列「配置」,摘要卡挂 island 还是换成一句「该配置需在服务端设备修改」。+- 服务端检查部署方式和请求来源:桌面服务由托盘管理且请求来自本机;Docker 服务由容器入口管理,允许经过登录验证的本机或私有网络请求,拒绝携带代理转发头的管理请求。`/healthz` 按调用方返回 `configurable`,页面据此显示配置入口;入口隐藏不能替代服务端访问检查。- 表单校验的原因由服务端按字段给(400 的 `errors`),页面写回原位,不在前端复制判定。- 浏览器直接导航撞上 `HTTPException` 时,`api.py` 的处理器按 `Accept` 回一张 HTML 错误页(`routes_pages.error_page`,薄壳由页面包画),`/api/` 下和非导航请求仍回 JSON。diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex 17ea7d28c..8ea14c1ff 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -122,13 +122,14 @@ Windows 测试包默认使用 `%LOCALAPPDATA%\Peach\peach-data`。首次设置### 在 macOS 上对应 Windows 路径:`[media.mounts]`-数据库里的路径统一按 Windows 的形式记录(例如 `R:\media\x`)。macOS 用 `[media.mounts]` 告诉 Peach 这些路径在本机的实际位置:+Peach 数据库中每部影片的 `path` 字段都使用 Windows 格式,例如 `R:\media\x`,即使服务运行在 macOS 或 Linux 上。这个值是数据库里的字符串;本机没有对应盘符时,Peach 需要用以下两项配置找到实际文件。Docker 配置见 [Docker 部署](DOCKER.md#配置文件与路径)。-- 键是来源 ID(`[media.locations]` 里声明过的,例如 `local`、`115`)。-- 值是这个来源的声明目录在本机的落点。例如声明 `local = 'R:\media'`、挂载 `local = '/Volumes/<卷名>/media'` 时,数据库里的 `R:\media\x` 在本机读作 `/Volumes/<卷名>/media/x`。-- 声明了几个目录,就按同样的顺序给几个落点,两边都写成数组,数量对不上会被拒绝。+- 两项使用相同的媒体来源键,例如 `local`、`115`。+- `[media.locations] local = 'R:\media'` 表示数据库中的文件路径以 `R:\media` 开头,不要求 macOS 或 Linux 存在这个目录。+- `[media.mounts] local = '/Volumes/<卷名>/media'` 表示本机实际读取的目录。数据库中的 `R:\media\x` 会转换成 `/Volumes/<卷名>/media/x`。+- 一个来源有多个目录时,两项都写数组,目录数量和顺序必须相同。-Windows 上这一段留空是正常的,盘符本身就是挂载点。没挂上的来源整体按离线处理,不报错。来源 ID 写错或写成盘符,会被直接拒绝。+Windows 直接使用 `[media.locations]` 中的路径,`[media.mounts]` 可以留空。macOS 和 Linux 仍然使用两项配置;缺少对应实际目录时,该来源显示离线,媒体记录保留,但无法读取文件。把 `[media.locations]` 的值改成 POSIX 路径不会同步修改已有影片记录,也无法替代这一步转换。媒体来源键写错或写成盘符时,配置会被拒绝。临时诊断时可以用环境变量覆盖,例如 `PEACH_MEDIA_MOUNTS=local=/mnt/res,115=/mnt/115`。diff --git a/src/peach/platform.py b/src/peach/platform.pyindex 2d268b8a5..df0370c64 100644--- a/src/peach/platform.py+++ b/src/peach/platform.py@@ -1,16 +1,16 @@-"""账本来源与本机挂载点之间的受控映射。+"""把数据库中的媒体路径转换为当前系统可以读取的文件路径。账本里的 `asset.path` 一律是 Windows 形态的绝对路径:`R:\\media\\...`(本地硬盘)、`A:\\...`(PikPak)、`B:\\...`(115)。这是不变量,不随平台改写。-真正会变的是「同一个来源在这台机器上落在哪」。`asset.location` 本来就是挂载点 ID-(来源 ID 见 `media_sources.SOURCE_REGISTRY`),设置文件用 `[media.locations]` 声明每个 ID 的账本口径根-(一个来源可以有几个根:两块硬盘都算 `local`),用 `[media.mounts]` 按同样的顺序声明每个-根在本机的落点,翻译按「声明根前缀 → 本机挂载点」进行(ADR-0023 第 2 阶段勘误)。-Windows 上盘符本身就是挂载点,路径原样返回。+`asset.location` 保存媒体来源的键,例如 local、115、pikpak(见 `media_sources.SOURCE_REGISTRY`)。+`[media.locations]` 保存每个来源在数据库中的目录前缀;`[media.mounts]` 保存本机实际目录。+Linux 即使没有相同盘符,也需要用这两项配置将数据库路径转换成实际文件路径。+一个来源有多个目录时,两项均使用数组,数量和顺序相同(ADR-0023 第 2 阶段勘误)。+Windows 直接使用数据库中的路径,无需这一步转换。-没有挂载点的来源会被映射到 `UNMAPPED_ROOT` 下,一定通不过 `allowed_media_roots`-授权,于是该来源整体按「脱盘」处理,而不是意外落到当前工作目录下的同名相对路径。+其他系统缺少对应实际目录时,将路径指向 `UNMAPPED_ROOT` 下不存在的目录,禁止读取。+这不表示媒体已删除,也不表示 Docker / Linux / macOS 可以省略 `[media.locations]`。"""from __future__ import annotations@@ -24,7 +24,7 @@ from . import settings_fileLOGGER = logging.getLogger(__name__)-# 未映射来源的落点。刻意选一个不可能存在的绝对路径,让授权和存在性检查都必然失败。+# 缺少路径配置时使用的不存在目录;文件授权和存在性检查均拒绝该路径。UNMAPPED_ROOT = Path("/nonexistent/peach-unmapped-drive")#: 运行期覆盖挂载表的环境变量。键是 location ID,不是盘符。@@ -44,17 +44,16 @@ def _parse_override(raw: str) -> tuple[tuple[str, str], ...]:return tuple(pairs)-#: 一个来源的声明根或落点:按顺序一一对应的字符串元组。+#: 按媒体来源分组的目录;数据库目录前缀与本机实际目录按顺序对应。Roots = Mapping[str, Sequence[str]]def location_mounts() -> dict[str, tuple[Path, ...]]:- """当前生效的「来源 ID → 本机挂载点」,与该来源的声明根按顺序一一对应;- 没有条目表示「本机没有这个来源」。+ """读取各媒体来源的本机实际目录,与 [media.locations] 中的目录前缀按顺序对应。- 基础映射来自设置文件的 `[media.mounts]`(内建默认为空:一台新机器什么都没挂,- 对应资产按脱盘处理)。`MOUNTS_ENV` 每次现读而不是缓存进设置层——测试和临时诊断- 会在运行期改它,缓存住就看不到变化;覆盖值只给一个目录,对应该来源的第一个根。+ 基础映射来自设置文件的 [media.mounts],默认没有条目。Linux 和 macOS 缺少条目时无法+ 读取该来源的媒体文件;Windows 直接使用数据库路径,不需要本表。MOUNTS_ENV 每次现读——测试和临时诊断+ 会在运行期改它,缓存住就看不到变化;覆盖值只给一个目录,对应该来源的第一个数据库目录前缀。"""merged: dict[str, tuple[str, ...]] = dict(settings_file.active().mounts)for location, mount in _parse_override(os.environ.get(MOUNTS_ENV, "")):@@ -64,7 +63,7 @@ def location_mounts() -> dict[str, tuple[Path, ...]]:def location_roots() -> dict[str, tuple[str, ...]]:- """来源 ID → 账本口径的声明根(至少一个),来自 `[media.locations]`。"""+ """媒体来源键对应的数据库目录前缀(至少一个),来自 `[media.locations]`。"""return dict(settings_file.active().locations)diff --git a/src/peach/routes_configuration.py b/src/peach/routes_configuration.pyindex 152d1d203..5cf4ffefc 100644--- a/src/peach/routes_configuration.py+++ b/src/peach/routes_configuration.py@@ -2,8 +2,8 @@页面整个是 `frontend/src/react/settings/` 下的 React 子树(入口 `configuration-page.tsx`),挂在主站的 `/configuration` 路由里(ADR-0031);这里只回数据。桌面由托盘管理,无桌面服务由专用入口管理;调用方范围与配置写入都在服务端校验。-手机上的管理菜单不列这一页,靠的是 `/healthz` 的 `configurable`,但那只是入口的显隐,-拒绝写入的判定在这里。+桌面部署只允许本机管理;Docker 部署还允许已登录的私有网络客户端管理。+`/healthz` 的 `configurable` 只控制入口显隐;这里负责实际访问检查。"""from __future__ import annotations@@ -65,7 +65,7 @@ def tunnel_forwarded(request: Request) -> bool:def local_client(request: Request) -> bool:- """按连接两端的 IP 识别本机;Host 只用于校验允许的入口名称。"""+ """按 IP 检查管理请求;桌面限本机,Docker 允许本机与私有网络,拒绝代理转发。"""if not request.client or tunnel_forwarded(request):return Falseserver = request.scope.get("server")diff --git a/src/peach/settings_file.py b/src/peach/settings_file.pyindex 4cfef87c8..29ff4fd1a 100644--- a/src/peach/settings_file.py+++ b/src/peach/settings_file.py@@ -43,10 +43,10 @@ DIRECTORY_KEYS = ("database", "generated", "sources", "state", "secrets", "logs", "tools", "review",)-#: `asset.location` -> 账本口径的声明根。键是 ledger 里的 `asset.location` 值,它本来-#: 就是挂载点 ID;值仍是 Windows 盘符形态,因为账本路径的形状是不变量(AGENTS.md)。-#: 一个来源可以有多个声明根(两块硬盘都算 `local`),文件里写一个字符串或一个数组。-#: 本机落点由 `[media.mounts]` 按同一批 ID 给出,翻译在 `peach.platform`(ADR-0023 勘误)。+#: 媒体来源的键(如 local、115)对应数据库 asset.location 的值,不是盘符。+#: 值是数据库 asset.path 中保存的目录前缀;各系统均使用 Windows 格式。+#: 一个来源有多个目录时写数组;[media.mounts] 按同一顺序保存本机实际目录。+#: peach.platform 在读取文件前转换路径(ADR-0023 勘误)。DEFAULT_LOCATION_ROOTS: dict[str, tuple[str, ...]] = {"local": (r"R:\media",),"115": ("B:/",),@@ -586,58 +586,62 @@ def _render_pairs(pairs: dict[str, object]) -> list[str]:def render(config: PeachConfig) -> str:"""把设置渲染成带注释的 TOML。注释是给人读的,`load_config` 不依赖它们。"""lines = [- "# Peach 设置文件。优先级:环境变量 > 本文件 > 内建默认;改完重启服务生效。",- "# 本文件住在数据根内部,数据根本身由 PEACH_DATA_ROOT 或项目旁的 peach-data 决定。",- "# Docker:本文件位于 /data/config.toml,/data 必须持久化;媒体使用容器内路径 /media。",+ "# Peach 设置文件。优先级:环境变量 > 本文件 > 程序默认值;手动修改后重启服务生效。",+ "# 本文件保存在 Peach 数据目录中;该目录由 PEACH_DATA_ROOT 或项目旁的 peach-data 决定。",+ "# Docker:本文件位于 /data/config.toml;将 /data 放在数据卷中,重建容器时保留该卷。",+ "# Docker 中的 /media 是容器内的媒体目录,宿主机目录由 Compose 挂载到这里。","# Docker 部署说明:https://github.com/peach-mitao/peach/blob/master/docs/DOCKER.md",- f"# 生成入口:peach init(数据根:{config.data_root})",+ f"# 生成入口:peach init(Peach 数据目录:{config.data_root})","","[directories]",- "# 数据根下的子目录,省略即取同名目录;写绝对路径可以把某一类数据搬出数据根。",- "# Docker 中相对目录位于 /data 下;绝对路径必须在容器内可访问并持久化。",+ "# Peach 数据目录下的子目录,例如 database、logs;省略时使用同名目录。",+ "# 也可填写绝对路径。Docker 中相对目录位于 /data 下;其他目录需要单独挂载并保留数据。",]lines += _render_pairs({key: config.directories[key]for key in DIRECTORY_KEYS if key in config.directories})lines += ["","[media.locations]",- "# 来源 ID -> 账本中的声明根,统一使用带盘符的路径作为标识。已有声明根通常不要改。",- "# Docker / Linux / macOS 的实际目录填在 [media.mounts];无需创建 Windows 盘符。",- "# Docker 示例:local = 'R:\\media',在 [media.mounts] 中配 local = '/media'。",+ "# local、115、pikpak 等键表示媒体来源;值是数据库中影片路径的目录前缀。",+ "# Peach 数据库在所有系统上都保存 Windows 格式的路径,例如 R:\\media\\a.mp4。",+ "# 因此 Docker / Linux / macOS 也使用本表;R:\\media 无需在这些系统上实际存在。",+ "# 例:本表 local = 'R:\\media',[media.mounts] local = '/media'。",+ "# Peach 会把数据库中的 R:\\media\\a.mp4 转换为 /media/a.mp4,再读取文件。",+ "# 本表必须匹配数据库中的路径;Docker / Linux / macOS 搬动实际目录时保留本表,修改 [media.mounts]。","# Windows 示例:local = ['D:\\Videos', 'E:\\Movies'],直接使用本机媒体目录。",]lines += _render_roots(dict(config.locations))lines += ["","[media.libraries]",- "# 声明根 -> 馆藏在界面上的名字。不写就取目录名;同名的几个根合成一个馆藏。",+ "# [media.locations] 中的目录前缀 -> 界面显示的媒体库名称;不写时取目录名。",+ "# 多个目录使用相同名称时,在界面中显示为同一个媒体库。",]lines += [f"{_render_value(root)} = {_render_value(name)}" for root, name in config.library_names.items()]lines += ["","[media.library_icons]",- "# 声明根 -> 馆藏图标。取值是 peach.media_libraries.LIBRARY_ICONS 里的字形名,",+ "# [media.locations] 中的目录前缀 -> 媒体库图标。取值是 peach.media_libraries.LIBRARY_ICONS 里的图标名,","# 不认识的值忽略:只含一个来源的馆藏回落到该来源的图标,跨来源的用 database。",]lines += [f"{_render_value(root)} = {_render_value(icon)}" for root, icon in config.library_icons.items()]- lines += ["", "[media.costs]", "# 声明根 -> 代理流量保护。free 关闭,metered 开启。"]+ lines += ["", "[media.costs]", "# [media.locations] 中的目录前缀 -> 代理流量保护。free 关闭,metered 开启。"]lines += [f"{_render_value(root)} = {_render_value(cost)}" for root, cost in config.media_costs.items()]lines += ["","[media.mounts]",- "# 来源 ID -> 实际媒体目录,与 [media.locations] 的声明根一一对应。",- "# Docker 示例:local = '/media',R:\\media\\a.mp4 实际读取 /media/a.mp4。",- "# Docker 只填写容器内路径;宿主机目录在 Compose 的 volumes 中配置。",+ "# 与 [media.locations] 使用相同的媒体来源键;值是 Peach 实际读取文件的目录。",+ "# Docker 填容器内路径,例如 local = '/media';宿主机目录在 Compose 的 volumes 中配置。","# Linux / macOS 也使用本机绝对路径,例如 /mnt/media 或 /Volumes/Media。",- "# 声明了多个根就按同样的顺序给同样多个落点。",- "# 不写或留空表示本机没有这个来源,对应资产按「脱盘」处理,不报错。",- "# Windows 上整表为空:盘符本身就是挂载点,路径不需要翻译。",+ "# 一个来源有多个目录时,两表都写数组,目录数量和顺序必须相同。",+ "# Docker / Linux / macOS 必须提供实际目录,否则无法读取该来源的媒体文件;媒体记录仍保留。",+ "# Windows 直接读取 [media.locations] 中的目录,无需填写本表。",]lines += _render_roots(dict(config.mounts))lines += ["","[server]",- "# Docker 无桌面入口固定监听 0.0.0.0:8900;宿主机访问地址与端口由 Compose 配置。",+ "# Docker 服务固定监听 0.0.0.0:8900;宿主机访问地址与端口由 Compose 配置。","# 此处 host、port 用于直接运行 peach serve;Docker 入口参数优先。","# mdns_name 在局域网里必须唯一:两台机器同名会互相抢占。","# review_writer_origin 是 reader 复核镜像要读的 writer 源,留空表示本机不做镜像。",@@ -652,9 +656,11 @@ def render(config: PeachConfig) -> str:lines += ["","[replication]",- "# 多机单写者账本复制设置(ADR-0017)。单机与独立 Docker 部署保持 enabled = false。",+ "# 两台电脑之间的数据库复制设置(ADR-0017);只有一台允许修改数据库,另一台只读。",+ "# 单机与独立 Docker 部署保持 enabled = false。","# 关闭时不启动同步观察器、不探测 SMB;桌面托盘不显示 Ledger 菜单项。",- "# shared_root 留空表示 <数据根的上级>/peach-sync;smb_* 留空表示不挂载共享。",+ "# shared_root 是两台电脑交换数据库副本的目录;留空时使用 Peach 数据目录旁的 peach-sync。",+ "# smb_* 用于连接另一台电脑的共享目录;留空时不连接共享目录。",]lines += _render_pairs({"enabled": config.replication.enabled,diff --git a/tests/test_cli.py b/tests/test_cli.pyindex f5f0f69e4..026383622 100644--- a/tests/test_cli.py+++ b/tests/test_cli.py@@ -304,7 +304,7 @@ class InteractiveInitTests(unittest.TestCase):self.assertIn("✓ local: 1 文件", output)self.assertIn("下一步", output)self.assertEqual(output.count("扫描结果:"), 2, "每个目录各报一行")- self.assertNotIn("115", (self.data_root / "config.toml").read_text(encoding="utf-8"))+ self.assertNotIn("115", loaded.locations)def test_posix_flow_keeps_the_ledger_shape_and_mounts_the_directory(self):code, output, _ = self._run(["", str(self.media), "", "2", "9443", "peach-two", ""],