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、不迁移数据库，也不会启动主服务。
选择菜单 2) 安装管理平台和本机小雅 时，安装器会在 Docker 检查通过后自动发现已有的 alist/xiaoya 容器；唯一候选自动复用，多个候选按运行中的容器优先列出并要求输入编号。复用时只启动管理平台、PostgreSQL 和控制器，不创建、启动、停止或删除已有小雅容器；已停止的容器会显示警告。没有候选时才创建 xymedia-xiaoya。模式 2 和模式 4 都要求用户目录规范化后与所选容器 /data（优先）或 /www/data 的 bind Source 完全一致；目录及父目录不能包含符号链接，也不接受 Source 子目录。控制器使用已校验的规范化路径和真实容器名写入 .env，不要求小雅 token。重跑时保留 .env 中已有的小雅容器名和数据目录，并重新校验挂载。
双服务器流程：在小雅服务器运行模式 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。
全新本机 bundled PostgreSQL 安装会从宿主机可用 IP 地址中选择数据库连接地址，在 20000-40000 范围随机选择对外端口，并生成符合 PostgreSQL 标识符规则的随机用户名和至少 32 位十六进制密码。应用和迁移容器始终通过宿主机 IP 加公开端口访问 PostgreSQL，不使用 Compose 内部 postgres:5432；Docker/NAS 必须允许容器到宿主机发布端口的 LAN/回环访问，并在防火墙放行该端口。可用 XYMEDIA_POSTGRES_PUBLIC_PORT 指定端口；端口仍映射到容器内固定的 5432。主机、公开端口、数据库和用户名写入 .env，密码只写入 secrets/xymedia-postgres-password。已有本机安装若旧主机是 postgres 或数据库容器 IP，会自动改为检测到的首个宿主机 IP；旧端口属于本机 PostgreSQL 容器时保留，否则 5432 或被占用时改用随机空闲端口，不删除数据库数据。安装成功后本机数据库连接信息会直接显示一次；主菜单 7) 查看数据库连接信息 是再次显示密码的主动操作。外部数据库安装保留用户提供的主机和端口，只显示主机、端口、数据库和用户名，不显示用户提供的密码。
主菜单 6) 查看小雅控制器地址和密钥 可以查看本机控制器连接信息。选择 2) 安装管理平台和本机小雅 并完成安装后，安装器也会自动显示控制器地址和密钥；密钥不会写入安装日志。
维护菜单中的 5) 清理 XyMediaVault 容器及数据 提供 1) 只清理 XyMediaVault、2) 清理 XyMediaVault 和本机安装的小雅 和取消选项。全新安装会在 .env 保存随机 XYMEDIA_INSTANCE_ID，并给安装器创建的 Compose 服务写入 managed、实例 ID 和 canonical 安装目录标签。清理要求 .env 身份与当前目录完全一致，并逐容器复核名称和所有权标签；缺少标签的旧容器、其他实例容器和用户容器均保留，不会按名称猜测删除。迁移容器只查询当前实例的 managed 标签，确认前冻结名称和 ID，确认后再次 inspect，发生变化则跳过。选项 1 保留用户小雅容器和外部 XYMEDIA_XIAOYA_DATA_DIR；选项 2 还要求 .env 标记 XYMEDIA_XIAOYA_MANAGED=1 且小雅 /data 挂载位于安装目录内。清理不执行 Docker prune；中断会保留 root-only .cleanup.journal，下次必须输入数字 1 才能恢复。真实旧安装若缺少身份标签会明确拒绝删除相关容器。
普通全新安装创建的持久容器名称为 xymedia-postgres、xymedia-app、xymedia-xiaoya 和 xymedia-controller；数据库迁移是短生命周期任务，使用 Compose 自动生成的临时名称并在完成后删除。复用已有小雅时不会创建 xymedia-xiaoya，.env 中保存真实容器名，控制器只记录并连接该容器，不会重命名用户已有的小雅容器。已有 PostgreSQL、app 等旧 Compose 容器由服务名管理，安装器不会按名称删除无关容器。
PostgreSQL 启动后安装器每 2 秒通过 Compose 查询其容器 ID，再读取 Docker health 状态，持续等待到 healthy，没有固定超时。应用启动后同样持续等待 /api/health；数据库迁移的原始输出会实时显示并追加到安装日志。已用秒数和状态会显示在终端；在等待期间按 Ctrl-C 会记录对应容器日志、停止等待并执行既有临时目录清理，安装以未完成状态退出。
FUSE 维护要求安装目录、.env、config.yaml 和 state 由 root 拥有且不允许 group/world 写入；不满足时脚本会拒绝执行。快照、配置写入临时文件和日志均在 /tmp 下随机命名的 root 私有目录中通过 mktemp 创建，权限为 700/600，不会在可写安装目录中创建可预测临时文件或持久日志。
主安装器的安装日志也使用 root 私有随机临时目录和 mktemp，退出时自动清理；迁移或健康检查失败时会先复制到安装目录的 install.log 并显示路径。.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 制品”，发布完成后重试即可。