6.2 KiB
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 制品”，发布完成后重试即可。