如果你和我一样平时主要靠docker-compose管理服务器上的各种服务那你大概率经历过这种时刻SSH 登录服务器、cd进某个项目的目录、敲docker compose up -d、再打开另一个终端看日志……服务少的时候还挺有仪式感服务一多光是记“哪个服务放在哪个目录”就够头疼了更别提多台服务器轮流操作。Dockge 就是冲这个痛点来的。它是 Uptime Kuma 作者 louislam 开源的 docker-compose 可视化管理工具把服务器上所有 compose 项目集中展示成卡片网页里直接编辑 compose 文件、一键启停、看日志、更新镜像甚至通过 Agent 模式用一块面板管多台机器。项目完全开源部署只需要一个 compose 文件跑起来之后你大概率会和我一样把常用的 SSH 管理目录流程直接丢进历史。这篇文章我会从“为什么需要它”讲到“怎么部署、怎么用、踩过哪些坑”全程按实际操过的流程来写适合已经熟悉 docker 和 compose 基本命令、但不想天天 SSH 敲键盘的人。1. Dockge 到底解决了什么问题1.1 纯命令行管理 Compose 的日常痛点我自己前两年管理服务器的状态是这样的服务器上一共跑了十几个 compose 项目有博客、有监控系统、有内网工具每个项目一个文件夹文件夹里一个compose.yaml。平时最常用的操作无非这么几个——更新某个服务、看某个容器日志、重启某个挂掉的容器。听起来不难但实际做的时候每一步都在消耗注意力。先说“更新服务”这件事标准流程是cd /opt/stacks/blog docker compose pull docker compose up -d如果好几个服务都要更新就得不停切换目录、重复命令中间的上下文切换其实很烦人。再说“看日志”你以为就是docker compose logs -f这么简单前提是你得先记得这个服务到底部署在哪个路径下再加上端口、容器名、网络配置这些信息全靠脑内索引时间一长必然出乱子。更难受的是“修改配置”。某个服务想加一个环境变量、换个端口映射命令行里的操作路径是SSH 连上服务器 →vim compose.yaml→ 改完还要自己心算 YAML 缩进对不对 →docker compose config验证 →docker compose up -d重新建容器。这套流程每隔几周就要来一遍一旦 YAML 写错缩进启动失败先不说排查起来还得一条条看报错信息。如果服务器不止一台每个节点都来这么一遍那基本就是纯体力劳动。所以真正让我下定决心找图形化工具的转折点是有一天我想不起来某个项目的实际部署目录在服务器上find / -name docker-compose.yml找了半天。那一刻我就意识到命令行不是不好而是它把所有信息都摊在你的记忆里服务规模一上来记忆就是最不可靠的组件。1.2 Dockge 的解题思路把 Stack 变成一等公民Dockge 的核心设计思路是把“docker-compose 项目”重新组织成一种叫Stack的概念。一个 Stack 就对应一个 compose 项目它有独立的目录、独立的compose.yaml、独立的运行状态。你在 Dockge 的网页里看到的是一张张卡片每张卡片代表一个 Stack卡片上有名字、状态、最近更新时间点进去就是这个项目完整的操作空间。这种组织方式和 Docker 生态里的“Service/Container”层级不太一样它是直接站在 compose 项目的角度思考问题的。我平时脑子里的问题本来就是“博客这个项目现在怎么样了”而不是“某个容器怎么样了”。Dockge 恰好把问题的粒度对齐到项目层这个对齐很关键——它让“管一个服务”变成“管一个目录加一个文件”而你看到的界面就是这个目录和文件的直接映射。它的另一个核心思路是“文件即状态”。Dockge 没有搞自己的数据库来存服务配置它直接读写服务器上的compose.yaml文件自身状态只用一个最小的元数据文件dockge.yaml来记录。这意味着你完全可以随时回到命令行继续操作同一个 compose 项目两边不会产生状态冲突。我试过在命令行docker compose up -d刷新一下网页Dockge 马上就把状态同步过来了完全没有“界面和命令行不一致”这种尴尬。1.3 和 Portainer、Watchtower 这些工具有什么区别提到 Docker 图形化管理很多人第一反应是 Portainer。Portainer 确实是很成熟的项目容器管理、镜像、网络、存储卷都能管但它更偏向“容器级”操作对 compose 文件本身的管理其实停留在“导入/导出”层面并没有把“编辑 compose 文件并实时管理生命周期”当核心体验来做。Dockge 正好相反——它不管镜像怎么拉、网络怎么建这些底层事专注把 compose 文件的管理和编排操作做到顺滑。Watchtower 也经常被混在一起提但它俩完全不是一类东西。Watchtower 是自动检测镜像更新并自动重建容器的工具解决的是“镜像版本落后”的问题Dockge 的更新按钮是手动触发相当于帮你把pull和up -d合成一键。两者可以共存甚至可以互补Dockge 负责日常管理和查看Watchtower 选择性地对某些服务开自动更新。选择工具的边界其实很简单如果你每天都要频繁改 compose 配置、经常新建服务Dockge 是最高效的如果只是偶尔看看容器状态、偶尔重启个容器Portainer 也够用如果连“管”都不想管全自动更新那直接 Watchtower 就好。我现在的实际组合是Dockge 作为唯一入口管理所有 compose 项目Portainer 只用来偶尔看网络和卷的情况两者不冲突。2. 部署安装从零到可用的完整步骤2.1 准备环境需要什么样的服务器配置Dockge 本身是个轻量 Web 服务官方镜像是基于 Node 的资源占用非常低。我实测过的环境一台 2G 内存的小鸡跑 Dockge 十几个 compose 项目内存长期稳定在 200MB 上下完全不构成负担。所以硬件上没有门槛常见的 x86 小主机、ARM 开发板、NAS 都能跑。系统层面只有一个硬性要求宿主机必须装好 Docker Engine并且带docker compose插件V2 版本。注意这里的docker compose中间有空格和老的docker-compose中间带横杠基于 Python不是一回事Dockge 在后台调用的就是 V2 的docker compose子命令如果你机器上只有老版docker-compose那得先升级插件。排查方法很简单docker compose version如果能输出类似Docker Compose version v2.x.x就没问题如果提示docker: compose is not a docker command说明插件没装或者装的是老版本。端口方面默认面板端口是5001如果你服务器上有防火墙记得放行。这个 5001 端口和 Uptime Kuma 的 3001 其实都是 louislam 的风格——不占常规 80/443给反代留了位置。2.2 安装步骤一个 compose 文件搞定官方推荐的目录布局是两套并行的路径一是 Dockge 自身的安装目录放在/opt/dockge二是你所有业务 compose 项目的根目录统一放在/opt/stacks。这种“工具目录和业务目录分离”的设计我很喜欢后面面板管理的就是/opt/stacks这个根路径。先创建目录并写好安装用的 compose 文件sudo mkdir -p /opt/stacks /opt/dockge sudo tee /opt/dockge/compose.yaml EOF services: dockge: image: louislam/dockge:latest container_name: dockge restart: unless-stopped ports: - 5001:5001 environment: - DOCKGE_STACKS_DIR/opt/stacks volumes: - /var/run/docker.sock:/var/run/docker.sock - /opt/stacks:/opt/stacks - /opt/dockge/data:/app/data EOF然后启动cd /opt/dockge docker compose up -d浏览器打开http://你的服务器IP:5001第一次访问会让你创建一个管理员账号之后就进入主界面了。这里几个配置解释一下因为我遇到过有人照着抄但不知道每行是干嘛的出问题也不知道从哪查DOCKGE_STACKS_DIR/opt/stacks告诉 Dockge 去哪找 compose 项目目录。这个必须和挂载卷里的路径保持一致。/var/run/docker.sock把宿主机的 Docker 套接字挂进容器。Dockge 本身不执行 Docker 命令它靠这个套接字访问宿主机 Docker Engine这是它所有操作的根基。/opt/stacks:/opt/stacks让容器能看到宿主机的配置目录。Dockge 读写 compose 文件本质上就是读写这个目录。/opt/dockge/data:/app/data保存 Dockge 自身的用户账号、Agent key 等元数据相当于它的“家目录”。2.3 目录设计为什么官方坚持用这种布局如果你是第一次接触 Dockge可能觉得/opt/stacks这种集中式目录很强制。实际上这正是它管理逻辑的基石。Dockge 的做法是根目录底下每个子目录代表一个 Stack子目录里的compose.yaml或者compose.yml、docker-compose.yml就是那个 Stack 的编排文件。这个约定让目录结构天然等于面板上的项目列表你新增一个子目录放一个 compose 文件刷新面板它就出现了。例如/opt/stacks ├── blog │ └── compose.yaml ├── monitor │ └── compose.yaml └── nginx └── compose.yaml对应到 Dockge 面板上就是三张卡片。这种设计带来一个额外收益备份和迁移极其简单。整个/opt/stacks目录就是一个压缩包的事换机器时把这目录原样拷过去Dockge 一扫就全部识别。我自己经历过一次服务器迁移整个过程就是把两个目录打包、解包、装好 Dockge半小时搞定所有项目原样回来状态、配置一个没丢。3. 核心功能逐个拆解3.1 从零创建你的第一个 StackDockge 里创建一个新项目的入口很直接。点右上角的新建 Stack输入一个名称比如blogDockge 会自动在你的根目录下创建/opt/stacks/blog这个子目录然后打开一个网页编辑器默认给了最小可用的 compose 模板。这个编辑器本质是一个带语法高亮的 YAML 编辑框光标提示、缩进检查都有。我第一次用的时候写了一个非常简单的 Nginx 示例services: web: image: nginx:alpine ports: - 8080:80 restart: unless-stopped保存后Stack 卡片里多了一个“部署”按钮点一下就相当于在命令行执行了docker compose up -d。这里有个细节体验特别好页面上会直接输出 compose 命令的执行日志你看得到它在拉镜像、创建网络、启动容器和命令行里看到的一模一样。如果命令时报错错误信息也会直接呈现在界面里不用再到服务器上翻日志。创建项目的过程中有一些路径管理的细节值得注意Stack 的名称会被直接用作目录名所以别用空格、斜杠等特殊字符另外 Docker Compose 项目名默认取目录名所以目录名最好直接是“项目名”而不是“blog_v2”这种带后缀的命名否则容器命名、网络命名都会跟着变长变乱。3.2 编辑与校验网页版的 YAML 工作台Dockge 的编辑器是我留在它身边的最重要原因。我此前用 vim 改 YAML 最怕的就是缩进因为vim对 YAML 的缩进提示非常有限一个 tab 和空格混用就能让整个文件语义错乱。Dockge 的编辑器提供了基础的 YAML 语法高亮虽然没有做到 IDE 级别但对于 compose 文件这种长度通常不超过两三百行的场景完全够用。它更实用的是内置了“配置检查”功能。保存文件后Dockge 会在后台执行docker compose config这类校验命令如果 YAML 有语法问题、或者有不合法的 compose 字段它会直接给出具体的报错行和错误信息。我实际体验到的一个场景是我在某个服务的环境变量里写错了引号它立刻标出来“第 43 行第 15 列有问题”这个定位精度比命令行报错友好太多了。编辑和多机同步也顺带解决了。以前在 A 服务器上改了配置B 服务器想同步只能靠复制粘贴文件现在多台机器装了 Dockge Agent 后每台机器的配置文件都在各自面板里直接维护改完保存、部署一气呵成不用再开终端。而且因为 Dockge 直接写的是宿主机上的物理文件你随时可以 SSH 上去cat同一个文件两边内容绝对一致。3.3 整套服务的生命周期管理每个 Stack 卡片上的操作按钮是整套流程的快捷键启动、停止、重启、更新镜像、查看日志、打开终端。前三个就是docker compose start/stop/restart的别名但界面上点了就能生效不用手敲。“更新镜像”这个按钮我要单独说因为它的行为逻辑值得理解。点下去之后Dockge 实际上是依次执行了docker compose pull docker compose up -d相当于先拉取所有服务镜像的最新版本再优雅地重建容器。这里的几个特点它不会自动删除旧容器而是通过up -d的机制做滚动替换如果某个服务在 compose 文件里配置了镜像 tag 为latest那这个操作就会把服务更新到最新版如果你用的是固定 tag比如nginx:1.25那pull只会拉取该 tag 对应的版本不会有惊喜。我习惯的更新节奏是先在面板上点“更新镜像”让新版本拉下来并启动然后进“日志”页面观察服务有没有异常。Dockge 没有做自动回滚这其实是好事——更新的主动权始终在你自己手里不会像某些带“自动更新”的工具那样一个上游 bug 直接被拉进生产环境。3.4 日志查看与排错入口日志功能是日常排错最有价值的一环。Dockge 的日志页面按服务分 tab 展示左边容器列表点哪个看哪个日志内容支持自动跟随类似-f的效果也支持关键词搜索。以前要docker compose logs --tail 50 web然后盯着终端看现在直接在面板里切换服务、拖动时间范围体验完全不是一个层级。还有一点我很欣赏面板里可以直接点击进入某个容器的“终端”这相当于自动执行了docker exec -it 容器名 /bin/sh。不用再先查容器名再手动 exec省掉了一步很烦的查询过程。如果你管理的是数据库容器、定时任务脚本容器这类需要隔三差五进去看一眼的服务这个功能价值很大。日志搜索这块可以提个建议如果服务日志量很大Dockge 的页面内搜索会比较吃力遇到海量日志还是建议结合 Loki 或 Dozzle 这类专门工具。但大多数场景下家庭服务器、小团队开发环境的日志量Dockge 的日志页面完全兜得住。3.5 Agent 模式一块面板管多台机器Dockge 的 Agent 模式是我后期最看重的功能也是它区别于一堆“单机面板”的差异化能力。原理很简单每台安装了 Dockge 的机器都是一个独立的节点你可以通过 Agent 机制把主面板和各节点的管理端打通。实际操作通常是这样先在目标机器上部署一个 Dockge Agent 服务它会生成一个 Agent API Key回到主面板的 Agent 设置页填入目标机器的地址和 Key点连接这台机器上的所有 Stack 就会出现在主面板的项目列表里并且可以直接在主面板上进行启停、编辑、日志查看等全量操作。整个过程不会要求你打开双向公网端口主面板主动连过去就行部署起来非常顺。我现在的使用状态是家里 NAS 一台、云服务器两台三台机器分别装了 Dockge然后以 NAS 为主面板管理另外两台。以前升级云服务器上的某个服务要 SSH 过去现在打开面板选对应机器点更新日志直接在主页面里看整个流程三百秒缩到三分钟。对于管着好几台机器的朋友来说这个功能值得重点体验。4. 常见问题与排错速查4.1 为什么已部署的服务没出现在面板里这是我被问得最多的问题“我的机器上明明有 compose 项目部署好 Dockge 后怎么一个都看不到”原因几乎都出在目录约定上。Dockge 只扫描你指定的DOCKGE_STACKS_DIR根目录下的一级子目录并且只在子目录里识别compose.yaml、compose.yml、docker-compose.yml这三个标准文件名。如果你的 compose 文件不在这个根目录下、或者文件名不合规比如叫my-app.yaml它自然不会出现在面板里。解决办法也很直接把项目目录移动到/opt/stacks底下并规范文件名然后刷新页面即可。另外注意首次被 Dockge 管理的 Stack 目录里会自动生成一个dockge.yaml元数据文件如果目录不可写添加会失败此时检查目录权限即可chmod 755 /opt/stacks chown -R 你的用户:你的用户组 /opt/stacks4.2 点按钮报错、容器起不来是怎么回事面板上点“部署”或者“启动”报错错误信息本身通常会直接告诉你原因但我见过几种常见情况值得单独列出来。一是旧版 Compose V1 兼容问题。Dockge 需要的是 Docker Compose V2 插件如果宿主机只有老版docker-composePython 包后台调docker compose空格版时就会失败报错类似于docker: compose is not a docker command。这时候需要对 Docker Engine 升级或重装插件老包卸载干净。二是文件权限问题。Dockge 通过挂载的 docker.sock 操作容器的确不需要特殊权限但读写/opt/stacks下的文件用的是服务器本地用户权限。如果compose.yaml的所有者是 root 且权限是 600Dockge 容器里的进程可能改不了文件。改权限chmod -R arw /opt/stacks三是端口冲突。compose 文件里写的宿主机端口如果早已被别的容器占用部署时会报port is already allocated。这个在面板的错误信息里直接能看到定位非常快。4.3 Dockge 和宿主机 docker compose 命令的关系是什么Dockge 只是一个前端它本身不实现任何容器编排功能。面板上的所有操作实质都是通过挂载的 docker socket调用宿主机的 Docker Engine 去执行docker compose相关命令。这意味着两件事第一你不会被锁死在 Dockge 里。无论何时你都可以回到命令行手动操作同一个 compose 项目Dockge 会在刷新后同步状态不会出现数据冲突。第二Dockge 的能力边界就是docker compose的能力边界。它不支持你在界面上做集群调度、跨主机网络这类高阶编排那些请交给 Docker Swarm 或 K8s不是一个维度的东西。想验证这一点也很简单在 Dockge 里部署一个项目后到服务器上执行docker compose -f /opt/stacks/项目名/compose.yaml ps结果和面板显示完全一致。我经常用这个方式来确认“面板没骗我”。4.4 升级 Dockge 本身和迁移数据Dockge 的升级继承了 Docker 社区的标准路径进到/opt/dockge目录拉取最新镜像然后重建容器cd /opt/dockge docker compose pull docker compose up -d升级后你的 Stack 配置、账号、Agent 连接全部保留因为数据都在挂载卷里。我升级过好几个版本没遇到过配置丢失的情况但稳妥起见升级前还是建议备份一下两个目录tar -czf dockge-backup.tar.gz -C /opt dockge/stacks迁移到新机器也是同样的思路新机器装好 Docker 和 Dockge把备份的/opt/stacks整个解压到新机器对应路径面板上刷新即可看到所有项目。甚至你可以直接在新机器上启动容器后再拷贝/opt/dockge/data里的账号数据账号信息也能一起搬走。最后分享一个我个人的使用习惯Dockge 每隔一个月会小版本更新一次我不会追新只在面板首页提示有新版本时才顺手升级。它本身很稳定跑在个人服务器上大半年没出过问题。反过来有一次上游 compose 规范变化导致某个 Stack 起不来Dockge 给出的错误信息让我五秒定位到了问题这个工具真正值钱的地方不在于它多炫酷而在于它把原来散落在命令行各处的信息统一聚到了一块屏幕上。