From 02697172bec9c3ae8d6605f41d3cb70e936556b5 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 9 Sep 2026 02:47:06 +0000 Subject: [PATCH] release: sync public installer asset README.md --- README.md | 206 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 189 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index badcf28..fa778d0 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,205 @@ -# XyMediaVault public installer +# XyMediaVault 公开发布与安装 -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. +> 本仓库提供 XyMediaVault 的安装入口、部署模板与公开组件目录。 +> +> 日常安装、升级、状态查看和本地媒体 FUSE 挂载维护，均从 `install.sh` 进入。本仓库不包含应用源码。 -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) 仅安装小雅控制器（这台机器只负责运行小雅控制器）`。首次本机部署请选择模式 1；已有本机 Alist/小雅可在模式 1 中选择复用或独立安装。模式 4 只下载 controller 制品并启动控制器，不拉取 App、不创建或使用 PostgreSQL、不迁移数据库，也不会启动主服务。 +| 项目 | 说明 | +| --- | --- | +| 执行环境 | 在 Linux 主机上执行，并使用具备 Docker 管理权限的管理员账户。 | +| 基础依赖 | 需要 Docker 及其编排工具；本地媒体 FUSE 维护额外需要第二代编排命令。 | +| 安装目录 | 脚本会创建应用配置、数据库目录、密钥文件和容器。请选择你拥有管理权限的目录。 | +| 已有小雅 | 已有 Alist 或 Xiaoya 时，先确认数据目录和当前用途；安装器可复用已有服务，也可单独创建一套受管理的小雅。 | +| 敏感信息 | 不要公开 `.env`、`secrets/`、控制器密钥、数据库密码、阿里云授权信息或完整安装日志。 | -选择菜单 `1) 推荐安装：管理平台和本机小雅（新用户、单机部署、默认推荐）` 时，安装器会在 Docker 检查通过后自动发现已有的 `alist`/`xiaoya` 容器；发现一个或多个符合条件的候选时，都会提示选择复用或安装独立小雅，多个候选会按运行中的容器优先列出并继续要求输入编号。复用时只启动管理平台、PostgreSQL 和控制器，不创建、启动、停止或删除已有小雅容器；已停止的容器会显示警告。没有候选时才创建 `xymedia-xiaoya`。模式 1 和模式 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) 查看小雅控制器地址和密钥` 可以查看本机控制器连接信息。选择 `1) 推荐安装：管理平台和本机小雅（新用户、单机部署、默认推荐）` 并完成安装后，安装器也会自动显示控制器地址和密钥；密钥不会写入安装日志。 +```bash +curl -fsSL --proto '=https' --proto-redir '=https' \ + https://git.keeper.work/admin/xymediavault-releases/raw/branch/main/install.sh \ + | sudo bash +``` -维护菜单中的 `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 容器由服务名管理，安装器不会按名称删除无关容器。 +```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 +``` -安装器不会在数据库准备阶段启动 app。选择小雅 profile 时只启动对应的小雅服务；本机 PostgreSQL 启动后每 2 秒通过 Compose 查询其容器 ID，再读取 Docker health 状态，持续等待到 `healthy`，没有固定超时。随后在同一 Compose 网络中启动临时 `postgres:17-bookworm` 客户端，通过应用实际使用的宿主机 IP、公开端口、用户名和密码执行 `SELECT 1`，外部连接验证成功后才运行数据库迁移，迁移成功后才启动 app。外部数据库跳过本机 PostgreSQL，但执行相同的外部连接验证。应用启动后同样持续等待 `/api/health`；数据库迁移的原始输出会实时显示并追加到安装日志。已用秒数和状态会显示在终端；在等待期间按 Ctrl-C 会记录对应容器日志、停止等待并执行既有临时目录清理，安装以未完成状态退出。 +安装器会从当前公开 `catalog-v1.json` 下载与主机架构匹配的应用、媒体文件解析服务、媒体管理服务和控制器制品。不要手工编辑目录文件，也不要填写未发布的组件地址。 -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 权限。 +| 菜单 | 用途 | 适合场景 | +| --- | --- | --- | +| `1` | 推荐安装：管理平台和本机小雅 | 新用户、单机部署、默认推荐 | +| `2` | 仅安装管理平台 | 只需要平台，暂不接入小雅 | +| `3` | 安装管理平台并连接远程小雅控制器 | 小雅部署在另一台主机 | +| `4` | 仅安装小雅控制器 | 在小雅主机上部署控制器，供另一台管理平台连接 | +| `5` | 状态、诊断与维护 | 查看状态、管理本地 FUSE 挂载、执行清理 | +| `6` | 查看小雅控制器地址和密钥 | 仅限可信管理员查看 | +| `7` | 查看数据库连接信息 | 仅限可信管理员查看 | +| `0` | 退出 | 不执行安装或维护操作 | -`catalog-v1.json` 是公开仓库的发布生成物，不手工填写未发布的制品地址。仓库中的初始目录只保证 v1 schema 和四个组件的 `artifacts` 对象合法，不能直接安装；正式发布前必须由组件发布流程填充 app、TMM、Title 和 controller 的真实制品条目。Generic Package URL 使用 `显示版本-12位提交短 SHA-构建 nonce`，catalog 的 `version` 仍是显示版本，且每个条目必须有 SHA-256。安装器暂时兼容没有 nonce 的旧 `显示版本-12位提交短 SHA` URL，以便旧 catalog 继续工作，但新发布一律使用 nonce。每次公开发布先由 `.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 制品”，发布完成后重试即可。 +### 已有小雅：复用或独立安装 + +选择模式 `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` 或包含内部地址和凭据的截图。