# XyMediaVault 公开发布与安装

> 本仓库提供 XyMediaVault 的安装入口、部署模板与公开组件目录。
>
> 日常安装、升级、状态查看和本地媒体 FUSE 挂载维护，均从 `install.sh` 进入。本仓库不包含应用源码。

---

## 安装前确认

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

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

---

## 开始安装

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

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

### 指定安装目录

```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` 的服务不会被安装器自动识别，请勿假定它会被复用。

### 远程小雅控制器

远程部署分两步：

1. 在小雅所在主机选择模式 `4`，配置真实的小雅数据目录和容器名。
2. 在管理平台主机选择模式 `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 和控制器端口改为其他可用端口后再安装：

```bash
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` 的“查看状态”。也可在安装目录中检查应用健康状态：

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

查看容器：

```bash
docker ps --filter name=xymedia
```

查看应用日志：

```bash
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` 或包含内部地址和凭据的截图。