项目介绍
Dockhand 管理容器环境和项目,Hawser 等连接组件可用于接入远端引擎。多主机场景需要同时规划身份、网络和引擎权限。
容器管理与 Compose 项目放在同一界面,多环境连接再扩展到其他主机。远端连接组件负责通信,不应直接公开未鉴权引擎。
适合需要管理一到多台 Docker 主机的用户。先在本机验证操作,再添加远端并明确各环境名称。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 生命周期 | 启动停止与重建容器 |
| Compose 项目 | 维护成套配置 |
| 镜像卷管理 | 查看资源与数据 |
| 远端环境 | 连接其他受控主机 |
| Git 接入 | 按版本管理仓库部署 |
界面展示

图 1:官方仓库提供的项目示意图,用于说明功能与布局。

项目信息
| 项目 | 说明 |
|---|---|
| 类型 | Docker |
| 分类 | NAS 与运维 |
| 项目仓库 | Finsys/dockhand |
| 官方入口或文档 | 直接访问 |
| 整理日期 | 2026-11-14 |
安装或使用条件
准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。
安装与使用步骤
- 先按官方文档部署单实例并设置数据存储,初始化管理员。
- 接入本机测试引擎,确认容器列表、日志和 Compose 项目可用。
- 需要远端时再按 Hawser 文档配置连接与认证,避免直接开放未鉴权的 Docker TCP 接口。
初次接入检查
打开 http://NAS_IP:3016 完成管理员初始化。先查看容器和镜像列表,再操作一个测试项目。项目数据如果需要面板内的文件管理,按官方手册核对 DATA_DIR 与宿主机路径的一致性,不把面板数据目录误当作所有业务容器的数据目录。Docker Socket 权限报错时使用官方匹配 GID 的方法,不对 Socket 全局开放读写。
首次使用与操作检查
先接测试引擎查看日志并启动一个小项目。连接远端后在明显位置标记主机名称,防止操作错环境。
升级先备份面板配置与连接密钥。远端失败分开检查网络、认证和引擎权限,不绕过鉴权排错。
Docker Compose
依据 Dockhand 官方手册的基础 Compose 整理,宿主端口改为 3016。数据使用命名卷;初始化与权限配置完成前只在可信局域网访问。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/dockhand/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/dockhand
cd /volume1/docker/dockhand
HALO_PREPARE
cd /volume1/docker/dockhand
配置中的命名卷由 Docker 创建并管理,不需要手动填写 UID/GID。备份时同时保存这些数据卷,不能只备份项目目录。
services:
dockhand:
image: fnsys/dockhand:latest
restart: unless-stopped
ports:
- "3016:3000"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- dockhand_data:/app/data
volumes:
dockhand_data:
在项目目录保存为 compose.yaml 后,先检查配置,再启动:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
配置与常见问题
- 原文加速域名不是项目官方镜像地址,应恢复为当前文档注明的来源。
- 页面无法打开:先用
docker compose ps检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。 - 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。
更新与备份
保存面板数据库、连接配置和栈文件,远端业务数据分别备份。
更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。
参考资料
配图来自 Finsys/dockhand 官方仓库,按 MIT 许可 保留来源与许可;图片只做等比例缩小和压缩。