外观
安装 Docker 与 Compose 插件
完成后，服务 → Compose 菜单出现，Docker 引擎在运行，compose 文件、应用数据、备份和 Docker 自己的数据各有一个共享文件夹。
开始之前
- 已经装好 omv-extras，见安装 omv-extras。Compose 插件来自 omv-extras，没有它，插件列表里找不到。
- OMV 能访问 Docker 官方软件源
download.docker.com，也能访问 GitHub（插件要下载两个小工具，示例清单也从 GitHub 读取）。 - 至少有一块数据盘已经创建并挂载了文件系统。omv-extras wiki 建议 Docker 所在的盘放在 SSD 或 NVMe 上，容量至少 60–100 GB。
- 系统是 amd64 或 arm64。OMV 8 只支持这两种架构，Compose 插件在两者上都有。
安装插件
- 打开
系统 → 插件（System → Plugins）。刚装完 omv-extras 的话，先点工具栏的 检查是否有新插件（Check for new plugins），列表才会出现 omv-extras 的插件。 - 搜索
compose，选中openmediavault-compose，点 安装（Install），确认。 - 安装结束后页面会自动重载。如果
服务菜单下还没有 Compose，用 Ctrl+Shift+R 硬刷新浏览器，仍然不行见插件装完界面不对。 - 如果页面顶部出现黄色的「待应用的配置更改」提示条，点 应用（Apply）。
装插件时会发生这些事：
| 动作 | 说明 |
|---|---|
| 自动装依赖 | openmediavault-sharerootfs、borgbackup、python3-docker、python3-pretty-yaml |
| 启用 Docker 源 | 安装前，插件会在 omv-extras 里打开 Docker 源（Docker repo）。老教程里「先去 系统 → omv-extras 手动勾选」现在不用了，勾上也无害 |
| 安装 Docker 引擎 | 不是随 apt 依赖装上的，而是在 Compose 模块「应用」时部署：docker-ce、docker-ce-cli、containerd.io、docker-compose-plugin、docker-buildx-plugin，以及容器终端插件 openmediavault-cterm（默认不启用） |
| 下载小工具 | 首次安装会下载 yq 和 regctl 到 /usr/local/bin，备份和镜像检查要用 |
不要卸载 sharerootfs
Compose 依赖官方插件 openmediavault-sharerootfs（它让 OMV 允许在系统盘上建共享文件夹）。在 系统 → 插件 里卸载它，会把依赖它的 Compose 插件一起卸掉，KVM、scripts 等插件也一样。
- 影响范围：卸载 Compose 插件（
purge方式）会清掉数据库里的 Compose 设置、compose 文件定义和计划任务。磁盘上的 compose 目录、应用数据，以及已经装好的 Docker 引擎不会被删除。 - 前置条件：卸载前先记下设置页的各项值，并确认 compose 目录里的文件都还在。
- 怎么回退：重新安装 Compose 插件，重新填设置，再用
服务 → Compose → 文件（Services → Compose → Files）里的 导入（Import）把磁盘上的 compose 目录找回来。目录必须是<名称>/<名称>.yml的结构。
卸载插件会连带影响谁，详见安装、更新与卸载插件和 sharerootfs。
建四个共享文件夹
omv-extras wiki 推荐把东西分开放。名字可以自己取，本站统一用下面这四个：
| 共享文件夹 | 用途 | 放在哪块盘 |
|---|---|---|
appdata | compose 文件，以及各应用的配置目录 | SSD 优先 |
data | 设置页里的「数据」，示例文件里的 CHANGE_TO_COMPOSE_DATA_PATH 指向它 | 容量大的盘 |
backup_compose | 插件计划备份的落地位置 | 和 Docker 不在同一块盘，最好是另一块盘 |
docker | Docker 的存储目录：镜像、容器层、命名卷、日志 | 独立的盘，EXT4，不放系统盘、U 盘、mergerfs 池 |
操作：存储器 → 共享文件夹（Storage → Shared Folders）→ 创建（Create），填 名称（Name）、文件系统（File system）、相对路径（Relative path）和 权限（Permissions），保存后点应用。共享文件夹的概念见共享文件夹：OMV 共享的基本单位。
这几个文件夹不要共享给别人
docker 和 backup_compose 不要加进 SMB 或 NFS。appdata 里的 compose 目录默认权限是 700，也不适合共享。需要在电脑上看容器文件时，用 SSH 或 服务 → Compose 里的编辑器。
填设置并让 Docker 装好
- 打开
服务 → Compose → 设置（Services → Compose → Settings）。 - 至少填这四项：Compose 文件 下的共享文件夹选
appdata；数据 选data；备份 选backup_compose；Docker 配置 勾选 使用共享文件夹，再选docker。每一项的含义和其他选项见Compose 插件设置详解。 - 点 保存（Save），再点黄色提示条上的 应用（Apply）。应用时会下载并安装 Docker，需要几分钟，期间不要关页面。
检查结果
- 回到
服务 → Compose → 设置，拉到页面底部的 Docker 信息（Docker info）：状态（Status）应该显示已安装并在运行，Docker 版本和 Compose 版本都有值。 - 在 OMV 的 shell 里（SSH 或本机控制台，以 root 身份）确认：
sh
docker --version
docker compose version
systemctl is-active docker
docker info | grep -E "Docker Root Dir|Storage Driver"Docker Root Dir 应该是 docker 共享文件夹的路径，形如 /srv/dev-disk-by-uuid-<UUID>/docker。如果还是 /var/lib/docker，说明设置页的 Docker 存储没有生效。
常见问题
设置页的 Docker 状态是「未安装」。 先确认设置保存后点过黄色提示条上的应用。仍然不行，在 OMV 的 shell 里以 root 身份运行 omv-salt deploy run compose，输出会告诉你卡在哪一步，常见原因是连不上 Docker 软件源。也可以在设置页底部点 重新安装 Docker（Reinstall Docker），它会先卸载 Docker 软件包再重装，期间容器会停止，镜像、卷等数据目录不会被删除。
保存设置时提示共享文件夹「不支持 Linux 文件权限」「不支持符号链接」之类。 插件会在你选的共享文件夹里真实测试写入、权限、符号链接、硬链接、命名管道和文件锁，不通过就拒绝保存。典型会被拒绝的是 exFAT 和通过 SMB/CIFS 挂载的远程共享，NTFS 也不适合放 Docker 数据。换到 EXT4、XFS、Btrfs 上的共享文件夹。
保存时提示「Compose 文件存储的共享文件夹必须与 data 存储共享文件夹不同」。 插件要求：Compose 文件、数据、Docker 三者两两不同，备份和 Docker 也要不同。按上面的四个共享文件夹分开建就不会遇到。
Docker 软件源下载很慢或失败。 Docker 源是 https://download.docker.com/linux/debian。网络不通时，可以用环境变量 OMV_DOCKER_APT_REPOSITORY_URL 和 OMV_DOCKER_KEY_URL 指向可用的镜像，设置方法见环境变量：调整界面里没有的选项，改完在 系统 → omv-extras 点 清理源（apt clean repos）。
别再手动维护 Docker 源
omv-extras 的 apt clean repos 会重写它自己管理的 Docker 源，并且按源码，会删除 /etc/apt/sources.list.d 里内容含 docker 的其他文件，包括你手动加的 Docker 官方源。Docker 源交给插件管就好。这一行为来自源码阅读，尚未在真机上验证。