Peach: Local-first video metadata scraper and media manager.
Merge branch 'master' into agent/codex/issue-95-vaapi
longmeidao497ff0ee8f61
diff --cc docs/DOCKER.mdindex db120128b,36d097cc3..cab6613ac--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@@ -44,41 -48,14 +48,43 @@@ local = 'R:\medialocal = '/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 复制。+## 硬件转码(AMD / Intel VAAPI)++Linux 首次重编码时会探测实际可用的硬件编码器,整片 MP4 与 HLS 分片共享探测结果。AMD / Intel 使用 VAAPI;存在 NVIDIA 设备时探测 NVENC。探测失败的后端在当前服务进程内不再尝试,重启服务后重新探测。封装复制不需要硬件探测。++镜像包含 Debian FFmpeg、Mesa VAAPI 驱动与 `vainfo`。AMD 宿主机需加载 `amdgpu` 和对应固件,并提供 `/dev/dri/renderD*`。Intel 需在自定义镜像内安装适配设备的 VAAPI 驱动;Mesa 驱动不代表已覆盖全部 Intel GPU。将下面的条目合入 Compose 的 `services.peach`,设备路径按宿主机调整:++```yaml+ devices:+ - /dev/dri/renderD128:/dev/dri/renderD128+ group_add:+ - "${PEACH_RENDER_GID}"+ environment:+ PEACH_TRANSCODE_BACKEND: auto+ PEACH_VAAPI_DEVICE: /dev/dri/renderD128+```++`PEACH_RENDER_GID` 填宿主机渲染节点所属组的数字 GID。容器以 UID 1000 运行,需要该节点的读写权限;只透传设备但没有组权限仍会初始化失败。Unraid 在容器设置中添加同样的设备映射、环境变量和额外组,无需开启特权模式。默认 Compose 不挂设备,无 GPU 的机器可直接运行。++| 环境变量 | 值与用途 |+| --- | --- |+| `PEACH_TRANSCODE_BACKEND` | 默认 `auto`;可设为 `vaapi`、`nvenc` 或 `software`。指定硬件后端仍会验证能否编码,失败回退软件。 |+| `PEACH_VAAPI_DEVICE` | 指定容器内渲染节点;留空时按名称依次探测 `/dev/dri/renderD*`,使用第一个可用节点。 |++VAAPI 尝试顺序为硬件解码加 `scale_vaapi` / `h264_vaapi`、软件解码加 `hwupload` / `h264_vaapi`、`libx264`。解码能力还受 GPU 型号、片源编码与位深限制;硬件编码可用不能证明每个片源都能硬件解码。NVIDIA 透传还需宿主机驱动及 NVIDIA Container Toolkit,Mesa 不提供 CUDA / NVENC。++出现 CPU 高占用时,先查看日志中的「转码硬件后端」和「转码硬件探测失败」。完成日志「整片转码完成」或「HLS 分片完成」后的 `vaapi` 表示使用硬件解码和编码,`vaapi-encode` 表示软件解码加硬件编码,`libx264` 表示软件转码。再在同一容器、同一用户下检查设备权限与 `vainfo --display drm --device /dev/dri/renderD128` 的结果。`No VA display found` 需结合驱动和设备权限排查,不能仅凭节点存在排除权限问题。++`ffmpeg -hwaccels` 列出构建支持的硬件加速方式,`ffmpeg -h decoder=h264` 等列出对应解码器支持的硬件设备。VAAPI 解码通过普通解码器的硬件加速接口启用,`ffmpeg -decoders` 中没有名为 `vaapi` 的解码器不代表缺少 VAAPI 解码支持。参数含义见 [FFmpeg 官方文档](https://ffmpeg.org/ffmpeg.html#Advanced-Video-options)。目标 GPU 的实际解码、GPU 占用与播放效果需要在部署机器上验证。+## 更新与范围更新镜像并重建容器时保留 `/data`。数据库有待执行迁移时,先备份并按 [运行与配置](OPERATIONS.md) 的迁移流程处理;无桌面入口不会自动迁移已有账本。健康检查使用 `/healthz?ready=1`。