OMV 7 使用 omv-compose 管理 Docker 应用完整教程
本文基于 知乎专栏文章 整理，适用于 OpenMediaVault 7.x 用户，帮助你使用官方推荐的 omv-compose 插件 替代 Portainer，高效管理 Docker 容器。
声明：本文由 AI 整理，但所有操作均 由本人在真实树莓派 5 + OMV 7.7.10 环境下亲自验证成功，可放心参考。
一、为什么使用 omv-compose？
✅ 优势
- 深度集成 OMV，与共享文件夹、权限系统无缝协作
- 原生支持 docker-compose，适合多容器应用（如 Aria2 + AriaNG）
- 通过 环境变量 简化超长 UUID 路径（如 /srv/dev-disk-by-uuid-xxx）
- 自动备份支持（配合 docker_backup_dir）
- 支持 autocompose 功能，可从现有容器生成 compose 文件
⚠️ 劣势（当前版本）
- 界面简陋，交互体验不如 Portainer
- 无法直接进入容器（需 SSH 后使用 docker exec）
- 学习成本略高
二、准备工作
1. 安装 omv-extras
- 进入 系统 → omv-extras
- 勾选 docker repo → 点击 保存
2. 安装 omv-compose 插件
- 进入 系统 → 插件
- 搜索 compose
- 安装 openmediavault-compose
三、创建所需共享文件夹
在 存储器 → 共享文件夹 中创建以下三个文件夹：
| Compose 配置 | docker_app_data | 存放 docker-compose.yml 和环境变量 |
| 容器数据 | docker_data | 存放数据库、媒体库等持久化数据 |
| 备份目录 | docker_backup_dir | 用于自动备份容器卷 |
💡 Docker 存储路径（可选）： 若需将 /var/lib/docker 移至独立磁盘（如 NVMe），可额外创建 docker 共享文件夹，并在 Compose 设置 中指定，然后点击 重新安装 Docker。
四、配置 omv-compose
进入 服务 → Compose → 设置，绑定共享文件夹：
| Compose | docker_app_data |
| Data | docker_data |
| Backup | docker_backup_dir |
| Docker 存储 | （可选）docker |
五、创建专用用户 appuser
为安全起见，不要用 root 运行容器。
1. 创建用户
- 用户 → 用户 → 新建
- 用户名：appuser
- 用户组：勾选 users 和 docker
2. 授予权限
- 选中 appuser → 共享文件夹权限
- 为 docker_app_data、docker_data、docker_backup_dir 赋予 读/写 权限
- 后续若容器需访问其他共享文件夹（如电影库），也需在此授权
3. 获取 UID/GID
SSH 登录后执行：
id appuser
记下输出中的 uid=1001(appuser) 和 gid=100(users)，用于后续环境变量。
六、编写 Compose 应用（以 Home Assistant 为例）
1. 创建环境变量
进入 服务 → Compose → 文件 → 环境变量，添加：
PUID=1001
PGID=100
TZ=Asia/Shanghai
🔁 替换为你的 appuser 实际 UID/GID
2. 创建 Compose 文件
点击 创建，填写名称（如 homeassistant），内容如下：
version: '3'
services:
homeassistant:
image: ghcr.io/home–assistant/home–assistant:stable
container_name: homeassistant
environment:
– PUID=${PUID}
– PGID=${PGID}
– TZ=${TZ}
volumes:
# 配置文件：存放在 compose/homeassistant/config
– ./config:/config
# 媒体数据：存放在 data/homeassistant/media
– CHANGE_TO_COMPOSE_DATA_PATH/homeassistant/media:/media
# 或挂载其他共享文件夹（通过环境变量）
# – ${MIRROR_0}/photos:/photos
network_mode: host
restart: unless–stopped
3. 路径说明
| ./config | /srv/docker_app_data/homeassistant/config |
| CHANGE_TO_COMPOSE_DATA_PATH/homeassistant/media | /srv/docker_data/homeassistant/media |
| ${MIRROR_0}/photos | 需先定义 MIRROR_0=/srv/dev-disk-by-uuid-xxx |
七、部署与管理
- ↑ Up：部署或更新容器
- ↓ Down：停止并删除容器
- ⏹ Stop：仅停止容器
- ⟳ Push：拉取最新镜像
- Autocompose：从运行中的容器自动生成 compose 文件（迁移 Portainer 项目利器）
八、最佳实践建议
九、常见问题
Q：容器无法写入文件？
A：检查 docker_data 目录是否属于 appuser（UID/GID 正确）
Q：如何访问容器 Shell？
A：SSH 登录后执行：
docker exec -it homeassistant /bin/bash
Q：能否继续使用 Portainer？
A：可以，但 omv-extras 已移除其入口，建议逐步迁移至 omv-compose。
📌 提示：omv-compose 是 OMV 官方未来方向，虽当前体验有待优化，但架构更清晰、备份更可靠，值得投入学习。
