# XyMediaVault public installer

Run `curl -fsSL https://git.keeper.work/admin/xymediavault-releases/raw/branch/main/install.sh | sudo bash` from the directory where you want XyMediaVault installed. The default install directory is the command's current directory; use `--install-dir /absolute/path` to override it. The installer downloads `catalog-v1.json` and the public Generic Package assets over HTTPS, selects `linux-amd64` or `linux-arm64`, safely extracts the app archive, and stores TMM and Title archives in the local component directory.

The app archive must contain `bin/xymediavault`, `bin/xymedia-supervisor`, `web/dist`, and `release.json`. The installer rejects legacy app packages missing the supervisor and waits for the current public catalog entry containing this complete layout.

Options include `--install-dir`, PostgreSQL connection options, `--postgres-password-file`, `--skip-components`, and `--existing-db`. An external database requires `--existing-db`; the migration command is explicit and never runs against an unconfirmed external database. No source repository, token, signature, or release hash is used by this v1 installer.

安装器提供四种中文模式：`1) 仅安装管理平台`、`2) 安装管理平台和本机小雅`、`3) 安装管理平台并连接远程小雅控制器`、`4) 仅安装小雅控制器`。模式 4 只下载 controller 制品并启动控制器，不拉取 App、不创建或使用 PostgreSQL、不迁移数据库，也不会启动主服务。

选择菜单 `4) 仅安装小雅控制器` 时必须填写小雅数据目录、监听地址和端口（默认 `0.0.0.0:19090`）。安装器只检查本机 Docker 容器，不会启动、停止或删除候选容器；它依据容器名称、镜像和标签发现 `alist`/`xiaoya` 候选。唯一候选会自动选择，多个候选按运行中的容器优先列出并要求输入编号；没有候选时可以手动输入容器名称，名称必须能被 `docker inspect` 确认。已存在但停止的候选也允许安装，控制器状态页会显示警告。安装前会再次读取所选容器的 Docker `Mounts`，要求用户目录规范化后与 `/data`（优先）或 `/www/data` 的 bind `Source` 完全一致；目录及父目录不能包含符号链接，也不接受 Source 子目录。控制器使用已校验的规范化路径和真实容器名写入 `.env`，不要求小雅 token。

双服务器流程：在小雅服务器运行模式 4，填写该机真实数据目录和小雅容器名，确认防火墙放行控制器端口；监听 `0.0.0.0` 时可被管理服务器访问，但建议使用防火墙限制来源。然后在管理服务器运行模式 3，输入控制器 URL、token 和显示名称，安装器会请求 `/health` 校验后保存连接。模式 3 不要求管理服务器存在本地小雅容器，也不会执行本地容器发现。

安装完成后，菜单 `5) 状态/诊断/维护` 提供本地媒体库维护子菜单：查看状态、一键挂载、按既有路径启动/重启，以及停用挂载。挂载目录必须是 root 可访问的已存在绝对目录，且首次配置时必须为空；路径及 `XYMEDIA_FUSE_ENABLED` 会持久化到 `.env`，应用配置固定使用容器内 `/mnt/xymediavault`。维护动作只停止和启动 `app`，不会停止 PostgreSQL；停用会卸载由 XyMediaVault 识别的 FUSE 挂载并恢复 base compose。脚本拒绝远程 Docker、符号链接路径和 foreign/unknown mount。

普通全新安装创建的持久容器名称为 `xymedia-postgres`、`xymedia-app`、`xymedia-xiaoya`、`xymedia-controller` 和 `xymedia-aliyuntvtoken`；数据库迁移是短生命周期任务，会使用带本次安装 nonce 的 `xymedia-app-migrate-*` 名称并在完成后删除。升级已有安装时，`.env` 中已有的 `XYMEDIA_XIAOYA_CONTAINER` 会原样保留，控制器只记录并连接该真实容器名，不会重命名用户已有的小雅容器。已有 PostgreSQL、app 等旧 Compose 容器由服务名管理，安装器不会按名称删除无关容器；旧名称可能在迁移期间暂时保留，需由管理员按实际项目状态处理孤立容器。

PostgreSQL 启动后安装器每 2 秒通过 Compose 查询其容器 ID，再读取 Docker health 状态，持续等待到 `healthy`，没有固定超时。已用秒数和状态会显示在终端并追加到安装日志；在等待期间按 Ctrl-C 会记录 PostgreSQL 日志、停止等待并执行既有临时目录清理，安装以未完成状态退出。

FUSE 维护要求安装目录、`.env`、`config.yaml` 和 `state` 由 root 拥有且不允许 group/world 写入；不满足时脚本会拒绝执行。快照、配置写入临时文件和日志均在 `/tmp` 下随机命名的 root 私有目录中通过 `mktemp` 创建，权限为 `700/600`，不会在可写安装目录中创建可预测临时文件或持久日志。

主安装器的安装日志也使用 root 私有随机临时目录和 `mktemp`，退出时自动清理；`.env` 更新临时文件使用安装目录同文件系统内的随机名称，并拒绝 `.env` symlink。root 执行时，已有安装目录路径组件必须由 root 拥有且不可 group/world writable。

公开安装器的普通安装默认关闭 FUSE，并将 `compose.fuse.yaml` 与 `remount-fuse.sh` 下载到安装目录。只有 FUSE 开启时 app、迁移和健康启动才合并 FUSE override；controller-only 模式不会下载或创建这些文件。维护闭环要求 Docker Compose v2、`/dev/fuse` 字符设备和 root 权限。

`catalog-v1.json` 是公开仓库的发布生成物，不手工填写未发布的制品地址。仓库中的初始目录只保证 v1 schema 和四个组件的 `artifacts` 对象合法，不能直接安装；正式发布前必须由组件发布流程填充 app、TMM、Title 和 controller 的真实制品条目。每次公开发布先由 `.gitea/workflows/build.yml` 调用 `scripts/publish-public-installer-assets.sh`，以单个 Gitea Git commit 同步本目录 allowlist 中的安装器模板和 FUSE 脚本，并逐个校验 raw 内容；随后调用 `scripts/publish-gitea-package.sh` 上传制品并校验现有 TMM/Title 条目。若当前架构的 controller 制品尚未发布，模式 4 会明确提示“公开目录没有当前架构的 controller 制品”，发布完成后重试即可。