🔥 BRAVE 質押池已上線 — 在錢包搜尋 BRAVE 即可委託
简体

Brave基地

Dockge: Homelab和自托管爱好者必备的Docker管理工具

    • 2024 年 8 月 8 日 上午 11:30 #23318
      Brave

      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 的设计哲学非常重要，这将帮助你判断它是否适合你的使用场景。

      🔹 核心设计理念

      理念说明
      文件优先（File-First）Dockge 不会”绑架”你的 Compose 文件——它们依然以 compose.yaml 的形式存储在磁盘上，你可以随时使用命令行工具 docker compose 直接操作
      透明可控所有配置文件可见、可编辑、可版本控制，即使删除 Dockge，你的容器和配置依然完好无损
      专注单一职责只做 Docker Compose 堆栈管理，不做 Kubernetes、Docker Swarm 等复杂编排
      响应式体验拉取镜像、启动/停止服务等操作均为实时反馈，无需刷新页面

      这与 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 各有定位。以下对比帮助你做出明智选择：

      对比维度DockgePortainer
      定位Docker Compose 专用管理器全功能容器管理平台
      配置存储文件系统（compose.yaml）内部数据库
      资源占用极轻量（~50MB RAM）较重（~150-300MB RAM）
      学习曲线平缓，上手即用较陡，功能众多需要时间熟悉
      单容器管理❌ 不支持✅ 支持
      网络/卷管理❌ 不支持✅ 完整支持
      Kubernetes 支持❌ 不支持✅ 支持
      多用户权限❌ 不支持✅ 支持
      日志过滤❌ 仅聚合日志，无法按容器筛选✅ 支持按容器筛选
      配置安全性⭐ 配置永不丢失⚠️ 数据库损坏可能导致配置丢失
      开源协议MIT（完全开源免费）社区版免费，商业版收费

      🎯 选择建议

      选择 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 界面。

      ⚙️ 关键路径说明

      路径用途
      /opt/dockgeDockge 自身的安装目录
      /opt/stacks你的堆栈存储目录（DOCKGE_STACKS_DIR）

      ⚠️ 重要提示：配置堆栈时请务必使用绝对路径，不支持相对路径。且容器内外的 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 管理工具。它的核心价值在于：

      亮点说明
      🎯 专注只做 Compose 管理，做到极致
      📁 透明文件优先，配置永不丢失
      ⚡ 高效实时响应，操作即反馈
      🪶 轻量资源占用极低，适合低功耗设备
      🛡️ 安全开源透明，社区审计

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

      🔗 参考资源

  • 抱歉，回覆主題必需先登入。