Peach: Local-first video metadata scraper and media manager.
docs(config): 完善 Docker 路径与配置说明
longmeidao030d0511ad1a
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 9e769d040..26c2cb92d 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -2,6 +2,8 @@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、配置重载与重启持久化验收。+Docker 使用浏览器管理,无需桌面托盘。配置文件中的盘符是账本路径标识,实际媒体目录由容器挂载提供。Windows 安装包、macOS 源码运行和 Docker 的入口分别见 [README](../README.md#下载与使用)。+## 数据与媒体`/data` 保存配置、SQLite 账本、凭据和图片缓存,必须持久化。媒体通过 `/media` 单独挂入;默认只读,扫描和播放不需要媒体写权限。整理、移动与删除需要使用者明确提供可写挂载。@@ -16,10 +18,38 @@ CloudDrive2 与 Peach 分别运行。NAS 已有 CloudDrive2 时直接复用;使用 Compose 启动后,无桌面入口会为全新数据卷初始化配置、账本和随机内部口令。它不覆盖已有配置;发现只有账本而没有配置时拒绝启动。初始化日志只显示口令文件位置。-在容器终端运行 `peach token` 取得登录口令,在浏览器登录后设置访问密码。配置页接受经过鉴权的回环或私有网络连接,带转发头的管理请求会被拒绝。配置页添加媒体文件夹时填容器内路径,例如 `/media/115`;对应声明根沿用 `B:\`,PikPak 沿用 `A:\`。配置保存会自动重载服务;勾选扫描时使用既有资料处理入口。+在容器终端运行 `peach token` 取得登录口令,在浏览器登录后设置访问密码。配置页接受经过鉴权的回环或私有网络连接,带转发头的管理请求会被拒绝。配置保存会自动重载服务;勾选扫描时使用既有资料处理入口。容器内 HTTP 端口固定为 8900,访问端口在 Compose 设置。默认只发布到宿主机 `127.0.0.1`,远程访问使用私有 VPN 或 SSH 隧道。需要局域网访问时,通过 `PEACH_BIND` 绑定宿主机的局域网地址,并设置访问密码。公网托管边界见 [安全说明](../SECURITY.md)。Docker 镜像不提供多人账号或租户隔离。+## 配置文件与路径++配置文件位于持久卷内的 `/data/config.toml`。通常在浏览器配置页添加媒体文件夹即可;手动编辑前先备份文件,编辑后重启容器。已有配置不会因更新镜像而自动覆盖,注释示例可对照本节阅读,无需重新初始化数据卷。++以下三个路径各有用途。假设宿主机媒体目录为 `/srv/videos`,Compose 将它挂到容器 `/media`:++| 位置 | 示例 | 用途 |+| --- | --- | --- |+| 宿主机目录 | `/srv/videos` | 填在 Compose 的 `PEACH_MEDIA_ROOT`,目录必须已存在 |+| 容器内目录 | `/media` | 填在配置页的媒体目录或 `[media.mounts]`,Peach 实际读取这里 |+| 账本声明根 | `R:\media` | 填在 `[media.locations]`,作为路径标识,无需在容器创建盘符 |++全新本地馆藏可使用以下映射。将两个表中的条目合入已有配置,不要重复添加同名表:++```toml+[media.locations]+local = 'R:\media'++[media.mounts]+local = '/media'+```++此时容器中的 `/media/a.mp4` 对应账本路径 `R:\media\a.mp4`。已有馆藏保留既有声明根,只调整对应挂载点;不能把 `[media.locations]` 改成 `/media`。一个来源有多个目录时,两张表均使用数组,数量和顺序一一对应。++配置页中的「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 复制。+## 更新与范围更新镜像并重建容器时保留 `/data`。数据库有待执行迁移时,先备份并按 [运行与配置](OPERATIONS.md) 的迁移流程处理;无桌面入口不会自动迁移已有账本。健康检查使用 `/healthz?ready=1`。diff --git a/src/peach/settings_file.py b/src/peach/settings_file.pyindex 7c0a67179..4cfef87c8 100644--- a/src/peach/settings_file.py+++ b/src/peach/settings_file.py@@ -588,18 +588,23 @@ def render(config: PeachConfig) -> str:lines = ["# Peach 设置文件。优先级:环境变量 > 本文件 > 内建默认;改完重启服务生效。","# 本文件住在数据根内部,数据根本身由 PEACH_DATA_ROOT 或项目旁的 peach-data 决定。",+ "# Docker:本文件位于 /data/config.toml,/data 必须持久化;媒体使用容器内路径 /media。",+ "# Docker 部署说明:https://github.com/peach-mitao/peach/blob/master/docs/DOCKER.md",f"# 生成入口:peach init(数据根:{config.data_root})","","[directories]","# 数据根下的子目录,省略即取同名目录;写绝对路径可以把某一类数据搬出数据根。",+ "# Docker 中相对目录位于 /data 下;绝对路径必须在容器内可访问并持久化。",]lines += _render_pairs({key: config.directories[key]for key in DIRECTORY_KEYS if key in config.directories})lines += ["","[media.locations]",- "# asset.location -> 账本口径的声明根。改这里等于改账本口径,通常不要动。",- "# 一个来源有几个目录就写几个:local = ['D:\\Videos', 'E:\\Movies']。",+ "# 来源 ID -> 账本中的声明根,统一使用带盘符的路径作为标识。已有声明根通常不要改。",+ "# Docker / Linux / macOS 的实际目录填在 [media.mounts];无需创建 Windows 盘符。",+ "# Docker 示例:local = 'R:\\media',在 [media.mounts] 中配 local = '/media'。",+ "# Windows 示例:local = ['D:\\Videos', 'E:\\Movies'],直接使用本机媒体目录。",]lines += _render_roots(dict(config.locations))lines += [@@ -620,8 +625,10 @@ def render(config: PeachConfig) -> str:lines += ["","[media.mounts]",- "# asset.location -> 本机挂载点:上面那个声明根落在本机的哪个目录。",- "# 例如 local = '/mnt/media' 时,R:\\media\\a.mp4 读作 /mnt/media/a.mp4。",+ "# 来源 ID -> 实际媒体目录,与 [media.locations] 的声明根一一对应。",+ "# Docker 示例:local = '/media',R:\\media\\a.mp4 实际读取 /media/a.mp4。",+ "# Docker 只填写容器内路径;宿主机目录在 Compose 的 volumes 中配置。",+ "# Linux / macOS 也使用本机绝对路径,例如 /mnt/media 或 /Volumes/Media。","# 声明了多个根就按同样的顺序给同样多个落点。","# 不写或留空表示本机没有这个来源,对应资产按「脱盘」处理,不报错。","# Windows 上整表为空:盘符本身就是挂载点,路径不需要翻译。",@@ -630,6 +637,8 @@ def render(config: PeachConfig) -> str:lines += ["","[server]",+ "# Docker 无桌面入口固定监听 0.0.0.0:8900;宿主机访问地址与端口由 Compose 配置。",+ "# 此处 host、port 用于直接运行 peach serve;Docker 入口参数优先。","# mdns_name 在局域网里必须唯一:两台机器同名会互相抢占。","# review_writer_origin 是 reader 复核镜像要读的 writer 源,留空表示本机不做镜像。",]@@ -643,8 +652,8 @@ def render(config: PeachConfig) -> str:lines += ["","[replication]",- "# 单写者 ledger 复制的坐标(ADR-0017)。enabled = false 时不启动同步观察器、",- "# 不探测 SMB、托盘不出 Ledger 菜单项,服务按独立写者跑。只有一台机器就别开。",+ "# 多机单写者账本复制设置(ADR-0017)。单机与独立 Docker 部署保持 enabled = false。",+ "# 关闭时不启动同步观察器、不探测 SMB;桌面托盘不显示 Ledger 菜单项。","# shared_root 留空表示 <数据根的上级>/peach-sync;smb_* 留空表示不挂载共享。",]lines += _render_pairs({