Dockge · 面向 compose.yaml 的自托管 Docker 栈管理器 · 中文部署与使用全指南

项目仓库： https://github.com/louislam/dockge

开源协议：MIT（以仓库 LICENSE 为准） · 运行时：Node.js + TypeScript（ES Module） · 容器化：Docker Compose（镜像 louislam/dockge:1） · 依赖：Docker 20+ / Podman · 架构：amd64 / arm64 / armv7 · 默认端口：5001 · 默认栈目录：/opt/stacks

1 项目简介

Dockge（仓库名 louislam/dockge，作者也是 Uptime Kuma 的作者）是一个面向 compose.yaml 的自托管 Docker 栈管理器。它的理念很直白：把所有容器都用 docker compose 的 compose.yaml 文件来管理，然后在一个漂亮、实时响应的 Web 界面里完成 创建 / 编辑 / 启动 / 停止 / 重启 / 删除 / 更新镜像 等操作。

它不是要做成大而全的 Portainer 替代品——官方 FAQ 明确说：Portainer 提供大量 Docker 功能，而 Dockge 只专注 docker compose 的栈管理，把这一件事的 UI 和体验做到更好。

1.1 核心信息一览

1.2 适用场景

• 已经习惯用 compose.yaml 管理服务，但想要一个比纯命令行更直观、实时看进度和日志的 Web 面板。
• 觉得 Portainer 部署栈时转圈、报错信息不清晰，想要更轻快的 compose 体验。
• 想要一个文件式结构——Dockge 不绑架你的 compose 文件，它们就是存在磁盘上的普通文件，你随时可以用 docker compose 命令行直接操作。
• 需要把 docker run ... 命令一键转写成 compose.yaml。

1.3 能力边界（官方口径）

• 官方 FAQ：不管理没有 compose.yaml 的单容器；想管单容器请用 Portainer 或 Docker CLI。
• 目前专注 docker compose 栈管理；Docker 网络、单容器等 Portainer 类功能不在其目标范围。
• 栈文件就是普通文件，Dockge 不锁定、不私有存储，可与 docker compose 命令混用。

2 功能特性

• compose.yaml 全生命周期：创建 / 编辑 / 启动 / 停止 / 重启 / 删除栈，更新 Docker 镜像。
• 交互式编辑器：在 Web 里直接编辑 compose.yaml。
• 交互式 Web 终端：内置终端面板。
• 多 agent 支持（1.4.0 起）：一个界面管理来自不同 Docker 主机的多个栈。
• docker run 转 compose：把 docker run ... 命令转换成 compose.yaml。
• 文件式结构：栈以目录形式存在 /opt/stacks/<stackName>/compose.yaml，不被私有格式绑架。
• 实时响应：Pull / Up / Down 进度与终端输出实时推送。
• 沿用 Uptime Kuma 的 UI/UX 风格。

3 官方界面预览

封面为 Dockge 官方 README 主界面截图。面板以卡片列表展示各栈，点击进入可编辑 compose、看实时进度与终端输出。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Docker 20+（或 Podman，Podman 需 apt install podman-docker）。
• 支持的发行版：Ubuntu、Debian Bullseye+、Raspbian Bullseye+、CentOS、Fedora、ArchLinux；不支持 Debian/Raspbian Buster 及更低。
• 架构：armv7、arm64、amd64。

5.2 端口与目录

6 方式一：Compose 一键部署（官方推荐）

# 1. 创建栈目录与 Dockge 数据目录
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. 启动
docker compose up -d
# 若使用 docker-compose V1 或 Podman：
# docker-compose up -d

启动后访问 http://localhost:5001 即进入 Dockge 面板。

6.1 自定义栈目录 / 端口

用官方在线生成器生成带参数的 compose：

curl "https://dockge.kuma.pet/compose.yaml?port=5001&stacksPath=/opt/stacks" --output compose.yaml

参数：port（默认 5001）、stacksPath（默认 /opt/stacks）。

7 方式二：手写 compose.yaml（等价官方模板）

services:
  dockge:
    image: louislam/dockge:1
    restart: unless-stopped
    ports:
      - 5001:5001          # 宿主机端口:容器端口
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      # 私有镜像仓库：共享 Docker 认证文件
      # - /root/.docker/:/root/.docker
      # 栈目录：宿主机与容器内路径必须一致
      - /opt/stacks:/opt/stacks
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks
      - PUID=1000          # 栈文件归属用户（须与 PGID 同时设置才生效）
      - PGID=1000          # 栈文件归属用户组

官方警告：栈目录挂载必须两边路径一致（- /my-stacks:/my-stacks），写成 - /docker:/my-stacks 这种路径不匹配会导致数据写到错误位置。

8 配置项说明

9 常用运维命令

# 启动 / 停止 / 查看
cd /opt/dockge
docker compose up -d
docker compose down
docker compose logs -f

# 更新
cd /opt/dockge
docker compose pull && docker compose up -d

在 Web 面板里：右上角下拉菜单可"Scan Stacks Folder"扫描已有栈目录；把已有 compose 移到 /opt/stacks/<stackName>/compose.yaml 后即可纳入管理。

10 常见故障排查

• 面板打不开 / 端口不通：确认 5001:5001 映射已发布，宿主机防火墙放行 5001。
• Dockge 无法操控 Docker：确认挂载了 /var/run/docker.sock，且当前用户有权限。
• 栈数据写到错误位置：检查栈目录挂载两边路径是否完全一致（官方警告项）。
• 栈文件归属不对：在 compose environment 里同时设置 PUID 和 PGID（单独设一个不生效）。
• 管理不了已有栈：停栈 → 把 compose 文件移进 /opt/stacks/<stackName>/compose.yaml → 面板右上角"Scan Stacks Folder"。
• Podman 环境：需先 apt install podman-docker。

11 风险与合规说明

• Dockge 是 MIT 许可的开源个人项目，由 Uptime Kuma 作者主导社区维护。
• Dockge 容器挂载了 Docker socket，意味着它拥有宿主机 Docker 的完整控制权，务必只在可信内网 / 受控反向代理后暴露面板，设置强口令，不要把 5001 直接裸露公网。
• 栈文件以明文 compose.yaml 存在 /opt/stacks，注意其中可能含数据库密码等敏感信息，做好目录权限。
• 本文命令、端口、环境变量来自官方 README，随版本演进可能调整，以官方仓库最新说明为准。