Dockge 是一款时尚、易于使用的自托管 Docker Compose 项目管理工具，由广受欢迎的 Uptime Kuma 开发者 Louis Lam 创建。它专为家庭实验室（Homelab）和自托管爱好者设计，提供了简洁而强大的用户体验。

Louis Lam 是一位来自开源社区的独立开发者，其开发理念是"Simple is beautiful"（简洁即美）和"Write less, do more"（少写代码，多做事情）。他在 2021 年 7 月发布 Uptime Kuma 时，发现市面上缺乏免费、现代、稳定的自托管监控工具，于是亲手打造了这个如今在 GitHub 上获得超过 60k+ Star 的明星项目。2023 年底，Louis Lam 将相同的设计哲学带入 Docker 管理领域，推出了 Dockge——一个专注于 Docker Compose 堆栈管理的轻量级工具。

一、Dockge 的定位与设计哲学

在深入功能之前，理解 Dockge 的设计哲学非常重要，这将帮助你判断它是否适合你的使用场景。

🔹 核心设计理念

这与 Portainer 等"全能型"工具形成了鲜明对比：Portainer 将 Compose 配置存储在内部数据库中，一旦数据库损坏或 Portainer 崩溃，配置可能面临丢失风险。Dockge 的文件优先策略从根本上规避了这一问题。

二、主要功能详解

1. 📦 堆栈（Stacks）全生命周期管理

Dockge 允许用户通过统一界面对 Docker Compose 堆栈进行全生命周期管理：

• 创建：通过 Web 界面新建堆栈，支持模板或手动编写
• 编辑：内置 YAML 编辑器，支持语法高亮和实时校验
• 启动 / 停止 / 重启：一键操作，带实时状态反馈
• 删除：安全删除堆栈及其关联资源

所有这些操作都基于标准的 compose.yaml 文件，意味着你在 Dockge 中做的任何修改，都可以直接通过命令行 docker compose up -d 来复现，实现了 GUI 与 CLI 的完美统一。

2. ✏️ 交互式 YAML 编辑器

内置的 YAML 编辑器使配置变得简单直观：

• 语法高亮：清晰区分键、值、注释等元素
• 实时验证：编辑时自动检测语法错误，避免因格式问题导致服务启动失败
• 智能缩进：自动处理 YAML 格式敏感的缩进问题
• 环境变量支持：可通过 UI 创建独立的 .env 文件来管理敏感配置（虽然仍以明文存储，但与主配置分离管理更为清晰）

3. 🖥️ 实时交互式 Web 终端

通过内置的 Web 终端，你可以与容器和服务进行实时交互：

• 实时日志查看：Pull、Up、Down 等操作的进度和输出实时呈现
• 容器终端访问：直接进入容器内部执行命令，无需在宿主机 SSH 中输入 docker exec
• 组合日志流：查看堆栈内所有容器的聚合日志流

⚠️ 安全提示：自 v1.5.0+ 版本起，出于安全考虑，Console（控制台）功能已默认禁用。如需启用，需在环境变量中设置 DOCKGE_ENABLE_CONSOLE=true。请确保你理解开放终端访问的潜在风险——任何能访问 Dockge 界面的用户都将获得对宿主机 Docker 的控制权限。

4. 🌐 多代理支持（Multi-Agent）

从 v1.4.0 版本开始，Dockge 支持多代理模式，可以从单一界面管理多个 Docker 主机上的堆栈：

┌─────────────┐
│   浏览器     │
└──────┬──────┘
       │ 只需连接一个实例
       ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Dockge 1   │────▶│  Dockge 2   │     │  Dockge 3   │
│  (主节点)    │     │  (代理节点)  │     │  (代理节点)  │
└─────────────┘     └─────────────┘     └─────────────┘
       │                                       ▲
       └───────────────────────────────────────┘

工作原理：

• 浏览器只需连接到主 Dockge 实例（Dockge 1）
• 主实例作为代理，负责转发请求和响应到其他代理节点
• 所有节点的堆栈统一展示在堆栈列表中
• 2025.10.13 版本更新：改进了使用多代理时的堆栈列表 UI 展示效果

使用场景：

• 管理分布在不同物理服务器上的 Docker 服务
• 开发/测试/生产环境的统一管理视图
• 跨地理位置的 Homelab 集群管理

⚠️ 注意：多代理功能目前仍处于 Beta 阶段，相比 Portainer 的成熟多主机支持，可能存在一些稳定性问题。

5. 🔄 docker run 命令转换

轻松将复杂的 docker run 命令转换为 Compose 配置：

使用场景：当你从网上找到一个一长串的 docker run 命令时，无需手动逐行转换，只需粘贴原命令，Dockge 即可自动生成对应的 compose.yaml 结构。

转换示例：

# 原始 docker run 命令
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -p 443:443 \
  -v /var/run/docker.sock:/tmp/docker.sock:ro \
  --restart always \
  jwilder/nginx-proxy

⬇️ 自动转换为 ⬇️

# 生成的 compose.yaml
services:
  nginx-proxy:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
    restart: always

这一功能极大降低了 Compose 的学习门槛，特别适合从单容器管理过渡到 Compose 编排的用户。

6. 🔄 镜像一键更新

Dockge 提供便捷的镜像更新机制：

• 一键检查并拉取最新镜像版本
• 自动重建并重启使用旧镜像的容器
• 拉取过程实时显示进度和输出

这解决了 Homelab 用户的一个常见痛点：手动追踪和更新数十个服务的镜像版本既繁琐又容易遗漏。

7. 📝 智能配置文件管理

Dockge 在处理配置文件时具有智能特性：

• 自动清理空字段：不再向你的 compose 文件中添加空的 networks、volumes 等字段，保持配置文件简洁
• 标准格式输出：生成的 YAML 符合 Docker Compose V2 规范
• 保留注释：编辑时不会丢失你添加的注释内容

三、Dockge vs Portainer：如何选择？

作为目前最流行的两款 Docker 管理工具，Dockge 和 Portainer 各有定位。以下对比帮助你做出明智选择：

🎯 选择建议

选择 Dockge 如果你：

• 主要使用 Docker Compose 管理服务
• 追求简洁轻量的管理体验
• 希望配置文件完全可控、可版本化
• 是 Homelab 入门用户或个人自托管爱好者

选择 Portainer 如果你：

• 需要管理 Kubernetes 或 Docker Swarm 集群
• 需要精细的多用户权限控制
• 需要管理独立容器、网络、卷等资源
• 在团队或企业环境中使用

最佳实践：许多 Homelab 用户同时部署两者——用 Dockge 日常管理 Compose 堆栈，用 Portainer 处理需要细粒度控制的复杂场景。

四、安装部署

📋 前置要求

• Docker Engine 20.10+（推荐 24.0+）
• Docker Compose V2（Dockge 基于 Compose V2 构建）
• Linux 服务器（也支持 macOS/Windows，但 Linux 体验最佳）

🚀 快速安装

# 1. 创建必要的目录结构
mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge

# 2. 下载官方 compose.yaml
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml

# 3. 启动 Dockge
docker compose up -d

安装完成后，访问 http://你的服务器IP:5001 即可进入 Dockge 界面。

⚙️ 关键路径说明

⚠️ 重要提示：配置堆栈时请务必使用绝对路径，不支持相对路径。且容器内外的 Stacks 路径必须保持一致。

五、升级与维护

📈 一键升级到最新版本

# 1. 进入 Dockge 目录
cd /opt/dockge

# 2. 拉取最新镜像
docker compose pull

# 3. 重新启动服务
docker compose up -d

🔍 升级后找回"消失"的堆栈

升级后原有堆栈可能暂时不显示，这是正常现象。Dockge 需要重新扫描堆栈目录：

1. 登录 Dockge Web 后台
2. 点击右上角的 [下拉箭头]
3. 选择 "Scan Stacks Folder"
4. Dockge 会自动扫描 DOCKGE_STACKS_DIR 中定义的所有子文件夹

💡 为什么升级能解决问题？

• 版本适配：新版 Dockge（v1.5.0+）修复了对 Docker Engine 1.44+ API 的适配问题
• 重新握手：重新拉起容器会触发 Dockge 重新扫描宿主机的 Docker 进程，原本"消失"的容器会自动出现

六、常见问题与故障排除

❓ 问题 1：升级后面板进不去 / 报错 client version 1.43 is too old

原因分析：这说明你的 Docker 引擎版本升级后，API 版本高于 Dockge 容器内 Docker CLI 所支持的版本。

解决方案：

方案一（推荐）：升级 Dockge 到最新版本

cd /opt/dockge
docker compose pull
docker compose up -d

方案二：修改 Docker daemon 配置向下兼容

# 编辑 Docker 配置文件
sudo nano /etc/docker/daemon.json

# 添加以下内容（注意保留原有配置）
{
  "api-version": "1.43"
}

# 重启 Docker 服务
sudo systemctl restart docker

❓ 问题 2：100% CPU 占用或终端无响应

这是早期版本的已知问题，已在新版本中修复。请确保升级到 v1.5.0 或更高版本。

❓ 问题 3：堆栈状态显示不正确

同样是早期版本的 Bug，新版本已修复对 Dockge 自身堆栈状态的正确显示。

七、安全最佳实践

部署 Dockge 时，请注意以下安全考量：

1. Docker Socket 访问风险

Dockge 需要挂载 Docker Socket (/var/run/docker.sock) 来管理容器，这意味着：

• 任何能访问 Dockge 界面的用户，都具备对宿主机 Docker 的完全控制权
• 恶意用户可能通过容器逃逸获取宿主机权限

缓解措施：

• 使用反向代理（如 Nginx Proxy Manager、Traefik、Caddy）添加 HTTPS 和身份认证
• 将 Dockge 绑定到 localhost（127.0.0.1:5001），仅通过反向代理暴露
• 考虑使用 docker-socket-proxy 限制可用的 API 命令

2. 网络隔离

# 推荐配置：绑定到本地回环地址
services:
  dockge:
    ports:
      - "127.0.0.1:5001:5001"  # 仅本机可访问

3. 敏感信息管理

Dockge 目前不支持 Docker Secrets。环境变量虽然可以通过 .env 文件分离管理，但仍以明文存储在磁盘上。对于高度敏感的信息（如数据库密码、API 密钥），建议：

• 使用专门的密钥管理工具（如 HashiCorp Vault）
• 确保 .env 文件权限为 600（仅所有者可读写）
• 将敏感配置目录排除在版本控制之外

八、国际化与社区

Dockge 拥有活跃的国际化社区支持：

• 多语言界面：支持中文、英文、德语、西班牙语、印尼语（新增） 等多种语言
• 社区翻译：通过 Kuma Weblate 平台协作翻译
• 开源协作：基于 MIT 协议，欢迎社区贡献代码和功能建议

主要贡献者：@NexiaMoe、@leonsk29、@rumplin、@GunnarNorin、@stanol、@FreddieDK、@demonisius 等

九、小结

Dockge 是一款功能聚焦、用户友好的 Docker Compose 管理工具。它的核心价值在于：

对于 Homelab 爱好者和自托管新手而言，Dockge 是入门 Docker Compose 管理的绝佳选择。它降低了学习门槛，同时保持了足够的灵活性和控制力。随着你的需求增长，你可以选择与 Portainer 等工具配合使用，构建更完整的容器管理工作流。

🔗 参考资源

• 📦 Dockge GitHub 仓库
• 📖 Dockge 官方文档
• 🐳 Docker Hub 镜像
• 💬 GitHub Discussions 社区
• 💖 Open Collective 赞助页面