项目	说明
执行环境	在 Linux 主机上执行，并使用具备 Docker 管理权限的管理员账户。
基础依赖	需要 Docker 及其编排工具；本地媒体 FUSE 维护额外需要第二代编排命令。
安装目录	脚本会创建应用配置、数据库目录、密钥文件和容器。请选择你拥有管理权限的目录。
已有小雅	已有 Alist 或 Xiaoya 时，先确认数据目录和当前用途；安装器可复用已有服务，也可单独创建一套受管理的小雅。
敏感信息	不要公开 `.env`、`secrets/`、控制器密钥、数据库密码、阿里云授权信息或完整安装日志。

操作提醒

清理、重建、挂载变更和数据库维护都可能影响正在使用的服务。执行前请确认影响范围，并为重要数据准备备份。

开始安装

进入希望作为安装目录的位置后执行。默认安装目录就是当前工作目录，脚本会显示交互菜单。

curl -fsSL --proto '=https' --proto-redir '=https' \
  https://git.keeper.work/admin/xymediavault-releases/raw/branch/main/install.sh \
  | sudo bash

指定安装目录

curl -fsSL --proto '=https' --proto-redir '=https' \
  https://git.keeper.work/admin/xymediavault-releases/raw/branch/main/install.sh \
  | sudo bash -s -- --install-dir /opt/xymedia

安装器会从当前公开 catalog-v1.json 下载与主机架构匹配的应用、媒体文件解析服务、媒体管理服务和控制器制品。不要手工编辑目录文件，也不要填写未发布的组件地址。

选择安装方式

菜单	用途	适合场景
`1`	推荐安装：管理平台和本机小雅	新用户、单机部署、默认推荐
`2`	仅安装管理平台	只需要平台，暂不接入小雅
`3`	安装管理平台并连接远程小雅控制器	小雅部署在另一台主机
`4`	仅安装小雅控制器	在小雅主机上部署控制器，供另一台管理平台连接
`5`	状态、诊断与维护	查看状态、管理本地 FUSE 挂载、执行清理
`6`	查看小雅控制器地址和密钥	仅限可信管理员查看
`7`	查看数据库连接信息	仅限可信管理员查看
`0`	退出	不执行安装或维护操作

已有小雅：复用或独立安装

选择模式 1 后，若检测到本机已有 Alist 或 Xiaoya 容器，安装器会让你选择：

选择	行为
复用已有容器	不会接管、重命名或删除该容器。请确认你有管理权限，并按提示提供与容器数据挂载一致的宿主机目录。同机已有 Alist/Xiaoya 且希望由平台管理时，请选择模式 `1`。
独立安装小雅	创建由 XyMediaVault 管理的 `xymedia-xiaoya` 容器和独立数据目录。默认端口被占用时，按提示选择其他宿主机端口。
取消	不修改已有容器或安装配置。

复用已有服务前，请先确认它不是其他业务正在依赖的生产实例。独立安装不会主动修改已有 Alist/Xiaoya，但端口和目录不能冲突。名称或镜像中不含 alist 或 xiaoya 的服务不会被安装器自动识别，请勿假定它会被复用。

远程小雅控制器

远程部署分两步：

在小雅所在主机选择模式 4，配置真实的小雅数据目录和容器名。
在管理平台主机选择模式 3，填写控制器地址、Token 和显示名称。

两台主机之间必须具备网络连通性，并应使用防火墙限制控制器端口的访问来源。

服务端口

默认端口如下。应用、WebDAV、TVBox 和控制器端口不会在交互菜单中逐项询问；首次安装需要改端口时，请在运行安装器前通过环境变量传入。端口冲突时不要直接修改正在运行的部署文件。

服务	宿主机默认端口	访问方式
管理后台/API	`18080`	`http://服务器IP:18080`
WebDAV	`18081`	`http://服务器IP:18081/dav`
TVBox	`18082`	`http://服务器IP:18082`
小雅 Web	`5678`	`http://服务器IP:5678`
小雅管理	`2345`	由小雅使用
小雅代理	`2346`	由小雅使用
小雅控制器	`19090`	远程管理平台连接时使用

例如，将应用、WebDAV、TVBox 和控制器端口改为其他可用端口后再安装：

curl -fsSL --proto '=https' --proto-redir '=https' \
  https://git.keeper.work/admin/xymediavault-releases/raw/branch/main/install.sh \
  | sudo env \
      XYMEDIA_API_PORT=28080 \
      XYMEDIA_WEBDAV_PORT=28081 \
      XYMEDIA_TVBOX_PORT=28082 \
      XYMEDIA_CONTROLLER_PORT=29090 \
      bash

小雅 Web、管理和代理端口会在选择独立安装小雅时由安装器提示确认；也可通过 XYMEDIA_XIAOYA_PORT、XYMEDIA_XIAOYA_ADMIN_PORT、XYMEDIA_XIAOYA_PROXY_PORT 预先指定。已有实例需要变更端口时，请先备份安装目录中的 .env，确认依赖方已停止或已调整，再使用对应端口变量重新运行安装器。

安装后检查

安装完成后，建议先在安装器中选择菜单 5 的“查看状态”。也可在安装目录中检查应用健康状态：

curl -fsS http://127.0.0.1:18080/api/health

查看容器：

docker ps --filter name=xymedia

查看应用日志：

docker logs --tail=200 xymedia-app

如果安装目录不是当前目录，请先进入实际安装目录，或在维护命令中使用 --install-dir。

本地媒体 FUSE 挂载

菜单 5 提供以下维护项：

维护项	作用
查看状态	查看服务、数据库和当前挂载状态
一键挂载本地媒体库	首次配置宿主机媒体目录并启动 FUSE
启动/重启已配置挂载	使用已保存的挂载路径重新启动
停用本地媒体库挂载	停止受管理的 FUSE 挂载并恢复普通应用模式
清理 XyMediaVault 容器及数据	需多次确认的破坏性维护操作

启用 FUSE 前，请逐项确认：

宿主机存在字符设备 /dev/fuse；
使用 root 执行 FUSE 维护；
目标目录是已存在、绝对、非符号链接的目录；
首次挂载时目标目录必须为空；
目标目录不能是其他应用正在读写的普通数据目录；
部署配置能够向 xymedia-app 映射 /dev/fuse 和 SYS_ADMIN 能力。

挂载动作由管理员执行一次即可。挂载成功后，媒体服务应读取挂载后的目录；是否允许普通用户读取仍取决于媒体服务容器的目录映射、挂载传播和自身用户权限。

如果挂载失败，安装器会输出预检、容器设备、应用健康和挂载状态诊断。请保留脱敏后的诊断结果，不要粘贴 .env 或密钥文件内容。

清理与数据安全

维护菜单中的“清理 XyMediaVault 容器及数据”是破坏性操作：

它只处理安装器能够确认属于当前实例的受管理资源；
不会使用 Docker prune，也不会按名称猜测删除其他容器；
选择清理本机小雅时，只会处理明确标记为本安装实例管理的小雅；
仍应在执行前自行确认数据库、媒体目录和小雅数据的备份；
不要使用 docker compose down -v 代替安装器维护流程，除非你明确要永久删除对应数据卷。

仓库文件说明

文件	用途
`install.sh`	交互式安装、升级和维护入口
`catalog-v1.json`	当前公开应用、媒体文件解析服务、媒体管理服务和控制器制品目录
`compose.yaml`	平台、本地数据库和本机小雅模板
`compose.fuse.yaml`	FUSE 启用时合并的部署覆盖配置
`compose-controller.yaml`	仅部署控制器时使用的模板
`config.yaml`	应用默认配置模板
`remount-fuse.sh`	本地媒体 FUSE 维护脚本，由安装器自动刷新
`Dockerfile.bootstrap`	应用与控制器启动镜像定义

这些文件由发布流程同步。安装实例中的 .env、config.yaml、secrets/、data/、releases/ 和组件目录属于本机状态，不应直接提交回公开仓库。

获取帮助

排障时请提供以下脱敏信息：

使用的安装模式和安装目录；
操作系统、CPU 架构、Docker 和 Compose 版本；
菜单操作步骤；
docker ps --filter name=xymedia 输出；
docker logs --tail=200 xymedia-app 中去除凭据后的相关部分；
FUSE 维护输出中的 preflight diagnostics 和 timeout diagnostics。

请勿提交控制器 Token、数据库密码、阿里云授权信息、Cookie、完整 .env、完整 config.yaml 或包含内部地址和凭据的截图。

README.md Unescape Escape

XyMediaVault 公开发布与安装

安装前确认