一、介绍
大家好，我是 XyMediaVault 的开发者。【冰齐的技术折腾】
所以我做了 XyMediaVault。它面向小雅 Alist、Emby、Jellyfin 和 TVBox，重点不是下载视频，而是建立本地媒体索引，并把整理后的目录以只读方式提供给播放端。
在用小雅 Alist 搭建家庭影音库时，我一直想把几件事集中起来：远程目录只扫描一次、媒体索引能长期复用、Emby 使用固定的媒体路径，同时小雅、WebDAV、TVBox 和相关容器都能在一个后台里管理。
二、功能
它能做什么？
- 扫描小雅目录并建立本地索引，减少媒体服务器反复递归访问远端目录。
- 用“媒体视图”把多个索引目录重新组合成适合家庭影音库的结构。
- 提供全局媒体库挂载，直接给 Emby、Jellyfin 等服务使用。
- 提供只读 WebDAV，可供 Infuse、Jellyfin 等客户端连接。
- 提供 TVBox JSON CMS、独立用户、设备令牌和目录权限。
- 集中管理小雅 Alist、Emby 和 TMM 容器，支持状态、启停、更新和实时日志。
- 支持定时更新媒体索引、小雅 STRM 和可选元数据。
XyMediaVault 不会下载视频文件。STRM 在需要时读取并保存相对播放路径；NFO、海报、字幕等辅助文件按配置从远端读取。
项目目前为闭源软件，请通过官方镜像和安装脚本部署。本文使用的镜像为：
iceqi/xymediavault:latest
三、安装
1、安装前准备
飞牛 NAS 需要满足以下条件：
- Docker 已安装并启动。
- 可以进入飞牛终端或通过 SSH 连接。
- 当前终端用户有权限访问 Docker。
- 准备一个长期保存数据的安装目录。
支持 **linux/amd64、linux/arm64 和 linux/arm/v7。**安装脚本需要可交互终端，因为镜像、服务器地址和端口会逐项询问。
2、一键安装
先进入希望保存 XyMediaVault 数据的目录。下面以 /vol1/1000/Docker/XyMediaVault 为例，实际路径请按自己的飞牛存储空间调整。
1.执行：
mkdir -p /vol1/1000/Docker/XyMediaVault cd /vol1/1000/Docker/XyMediaVault
2.然后运行官方一键安装命令：
curl -fsSL https://gh-proxy.org/https://raw.githubusercontent.com/iceqi/xymediavault/main/scripts/install.sh | sh
安装脚本会询问安装目录、Docker 镜像、服务器 IP 或域名、管理后台端口、WebDAV 端口、TVBox 端口、小雅端口，以及是否强制拉取最新镜像。
3、默认地址
- 管理后台：http://服务器IP:18080
- WebDAV：http://服务器IP:18081/dav
- TVBox：http://服务器IP:18082
- 小雅 Alist：http://服务器IP:5678
脚本还会自动检测宿主机是否能提供 FUSE 挂载能力。检测失败不会阻止安装，WebDAV 和 TVBox 仍然可以使用。
四、使用
1、首次登录并创建管理员
浏览器打开：
http://飞牛IP:18080
首次访问没有默认密码，需要自己创建管理员账号。建议使用独立强密码，不要与飞牛系统、阿里云盘或其他服务共用。
2、完成小雅初始化
第一次进入后台时会自动打开“小雅初始化”窗口，按顺序完成：
- 阿里云盘普通 Token 扫码授权。
- 阿里云盘 Open Token 扫码授权。
- 填写阿里云盘转存目录 ID。
转存目录默认可使用 root，也可以在阿里云盘网页版打开目标文件夹，从地址栏中取得文件夹 ID。保存后系统会重启小雅容器。
Token、Cookie、转存目录配置都保存在安装目录的 xiaoya/ 中。不要在论坛截图、日志或远程协助信息中公开这些文件。
3、选择目录并建立媒体索引
进入左侧“媒体资源”，保持顶部模式为**“小雅 5678”。找到需要加入媒体库的目录，点击右侧“扫描索引”，确认目录和失败重试次数，然后点击“创建并启动任务”。也可以在根目录使用“生成全部索引”**。
索引任务只保存目录和文件信息，不会把视频下载到飞牛。远程目录较大时建议先选择一个子目录测试，确认链路正常后再扩大范围。
4、在任务中心确认扫描完成
进入**“任务中心”**，查看任务状态、进度、成功与失败数量，以及实时事件。
正常完成时应满足：
• 状态为 success。
• 处理数量达到总数量。
• 失败数为 0，或失败项已经处理。
• 最后事件显示媒体索引扫描完成。
如果出现失败，先看任务事件和**“IO 日志”**，通常可以定位到远程目录不可访问、播放服务地址错误或权限不足。
5、启用媒体库挂载
进入**“媒体库挂载”。新手建议先使用“索引目录模式”。确认宿主机媒体根和安装目录一致，然后点击“挂载”。运行状态变成“已挂载”后，飞牛宿主机就能看到虚拟媒体目录**。
三个路径要区分：
- 飞牛宿主机：安装目录/mnt/xymediavault
- XyMediaVault 容器内：/mnt/xymediavault
- 托管 Emby 容器内：/media
FUSE 挂载依赖宿主机提供 /dev/fuse、容器 SYS_ADMIN 能力和共享挂载传播。安装脚本会自动探测，不支持时不会强行加入高权限配置。
6、安装或接入 Emby
进入**“Emby 管理”。如果尚未安装，可以设置宿主机访问端口，选择与全局挂载一致的展示模式，然后点击“安装 Emby”**。Emby 配置保存在：
Emby 显示**“运行中”后点击“打开 Emby”**。在 Emby 初始化向导中添加媒体库时，目录要选择：
/media
不要填写飞牛宿主机路径，也不要填写 /mnt/xymediavault。XyMediaVault 已经把宿主机媒体根以只读方式绑定到 Emby 的 /media。
后续可以在同一页面完成 Emby 的启动、停止、重启、更新和卸载。卸载 Emby 容器不会删除 emby/config。
7、更多用法
• 媒体视图：把多个索引目录合并、分类或重新组织。
• 只读 WebDAV：创建独立账号和目录权限，地址为 http://飞牛IP:18081/dav。
• TVBox 服务：为不同用户分配目录和播放服务，并生成独立订阅地址。
• TMM 管理：安装和管理 tinyMediaManager，补充 NFO、海报等元数据。
• 定时任务：定时扫描媒体索引、小雅 STRM 和元数据。
• 播放服务：为 WebDAV 或 TVBox 用户绑定不同的播放入口。
可接入各类影视端如：飞牛影视，emby、tvbox 等。
五、常见问题
1、安装时提示端口被占用
重新运行安装脚本，在交互提示中修改冲突端口。更新已有安装时，脚本会保留当前端口映射。
2、飞牛不支持 FUSE
仍可使用只读 WebDAV 和 TVBox。可以先通过 WebDAV 接入客户端，不要为了挂载功能盲目修改宿主机权限。
3、Emby 中找不到媒体目录
检查“媒体库挂载”是否为“已挂载”，检查宿主机的安装目录/mnt/xymediavault 是否可见，确认托管 Emby 中选择的是 /media，并确认索引任务已经完成。
4、WebDAV 能看到目录但文件无法读取
检查索引任务、远程源、当前用户绑定的播放服务和目录权限。详细错误可在任务中心和 IO 日志中查看。
六、更新与备份
更新和安装使用同一个脚本。在原安装目录执行：
cd /你的/XyMediaVault/安装目录 curl -fsSL https://gh-proxy.org/https://raw.githubusercontent.com/iceqi/xymediavault/main/scripts/install.sh | sh
重要数据包括：
- data/
- xiaoya/
- emby/config/
- config.yaml
- docker-compose.yml
备份前建议停止 XyMediaVault：
docker compose stop xymediavault
完整复制上述目录和文件后再启动：
docker compose start xymediavault
不要只复制正在写入的 SQLite 主文件而忽略同目录下的 -wal 和 -shm 文件。
最后
XyMediaVault 的目标，是把小雅资源的索引、整理、挂载和播放服务集中到一个后台中，让飞牛上的 Emby 媒体库更容易维护。
当前官方镜像：
iceqi/xymediavault:latest
一键安装：
curl -fsSL https://gh-proxy.org/https://raw.githubusercontent.com/iceqi/xymediavault/main/scripts/install.sh | sh
默认管理后台：
http://服务器IP:18080
如果使用中遇到问题，建议附上程序版本、任务事件或已脱敏的日志，并说明飞牛型号、CPU 架构和安装方式。
XyMediaVault 仅用于管理用户有权访问的媒体资源。请遵守所在地法律法规及相关服务条款，不要公开 Token、Cookie、密码、WebDAV 凭据或 TVBox 设备令牌。
