Dockge 10 分钟上手：让 Docker Compose 管理像搭积木一样简单

结论先行：如果你日常通过 Docker Compose 管理多个微服务或自托管工具，Dockge 是比 Portainer 更纯粹轻量的管理面板（由知名监控开源项目 Uptime Kuma 作者打造）。它彻底抛弃了中间层数据库抽象，直面宿主机磁盘上的 /opt/stacks 目录与原生 compose.yaml 文件。即便面板容器停机，本地目录结构与原生命令也完全不受影响。左右分屏（可视化积木与 YAML 双向同步编辑）、环境变量直观注入、实时日志与交互式终端一应俱全。

0、写在前面

在单台 VPS 上维护三五个 Docker Compose 项目时，典型的运维流程往往相当枯燥：

打开终端输入 SSH 密码或密钥登录服务器；
逐层 cd 进入对应项目的配置文件目录；
使用 vim 或 nano 修改端口或镜像版本，一旦手抖打错缩进，启动即报错；
执行 docker compose up -d 后，再执行 docker compose logs -f 确认状态；
如果出现变量配置遗漏，又得退出日志重新进入编辑。

很多人尝试过 Portainer，但 Portainer 将 Stacks 储存在自己的内部数据库中，与宿主机文件系统的真实目录割裂，缺乏对原始配置文件的亲和度。

Dockge 改变了这种局面。它专为 Docker Compose 量身打造：你看到的所有服务卡片，背后直接对应宿主机磁盘里的一个真实目录和一份纯文本 compose.yaml。在浏览器里修改保存，宿主机文件立即同步更新；在宿主机终端里手动改文件，浏览器界面一刷新立刻生效。

1、期望目标

阅读并实操本文后，你将达成以下目标：

[ ] 按照最佳目录规范，在 VPS 上完成 Dockge 容器化部署；
[ ] 掌握左右分屏交互模式：可视化表单与原始 YAML 的双向实时同步；
[ ] 熟练在 Web 端对 Compose 堆栈执行部署、热重启、镜像拉取更新与日志追踪；
[ ] 掌握 .env 环境变量在线隔离管理，确保敏感密钥不直接硬编码在 YAML 中；
[ ] 掌握将服务器已有历史 Compose 项目一键无损导入 Dockge 的标准化路径；
[ ] 配置反向代理与网络访问控制，避免 5001 管理端口在公网裸奔。

2、技术架构与工具对比

Dockge vs Portainer vs 原生终端

对比主流容器编排管理手段的优劣势：

评估维度	原生终端 (SSH + CLI)	Portainer CE	Dockge
配置存储机制	本地文件系统目录	内部数据库（元数据与宿主文件割裂）	宿主 `/opt/stacks` 原生纯文本文件
Compose 交互体验	纯手写代码，缩进错误无实时提示	文本框单向编辑，表单较为笨重	左右双向分屏（积木表单 ↔ YAML 实时同步）
内存与系统开销	0 MB	约 50MB - 120MB	约 30MB - 45MB
面板损坏影响	无面板风险	恢复依赖面板备份卷与数据库导入	毫无影响，直接进入宿主目录敲 CLI 即可接管
终端与日志集成	依赖外部 SSH 客户端	内置终端与日志流	内置交互式终端与实时颜色渲染日志
定位场景	自动化运维、CI/CD 管道	多节点集群、镜像仓库、复杂团队权限	独立开发者、自托管玩家、纯 Compose 场景

架构拓扑：直面宿主机文件系统

Dockge 的底层极其克制：它没有复杂的外部依赖数据库，仅通过挂载数据目录与 Docker Socket 实现即时管控。

3、实操步骤

3.1 规划物理目录与安装部署

步骤 1：创建标准运行目录

我们遵循 Linux 标准，在 /opt 建立两大目录：

/opt/dockge：存放 Dockge 自身的配置文件与系统缓存；
/opt/stacks：存放所有被管理的 Docker Compose 业务项目。

# 创建系统目录
sudo mkdir -p /opt/dockge /opt/stacks

# 进入 Dockge 运行目录
cd /opt/dockge

步骤 2：编写 Dockge 自身的 `compose.yaml`

创建 /opt/dockge/compose.yaml 文件：

cat > compose.yaml <<'EOF'
services:
  dockge:
    image: louislam/dockge:1
    container_name: dockge
    restart: unless-stopped
    ports:
      - "5001:5001"
    volumes:
      # 挂载 Docker Socket 以调用引擎 API
      - /var/run/docker.sock:/var/run/docker.sock
      # 挂载 Dockge 本身的数据目录
      - /opt/dockge/data:/app/data
      # 核心：挂载全部业务 stacks 目录
      - /opt/stacks:/opt/stacks
    environment:
      - NODE_ENV=production
      # 指定 Stacks 在容器内的挂载路径
      - DOCKGE_STACKS_DIR=/opt/stacks
EOF

步骤 3：启动服务

1	docker compose up -d

确认日志运行状态：

1	docker compose logs -f dockge

若出现 Listening on :5001，说明面板已在后台成功运转。

3.2 首次初始化与主控制台导览

在本地浏览器打开：

1	http://<你的服务器IP>:5001

首次访问时，页面会提示创建管理员账户。输入管理员用户名与高强度密码后，直接进入主界面。

┌────────────────────────────────────────────────────────────────────────┐
│  Dockge 仪表盘                                                         │
├─────────────────┬──────────────────────────────────────────────────────┤
│  STACKS 列表    │  Stack 详情: my-blog [ ACTIVE (运行中) ]             │
│                 ├──────────────────────────────────────────────────────┤
│  ▶ my-blog      │  [ 编辑 ] [ 重启 ] [ 更新镜像 ] [ 停止 ] [ 终端 ]    │
│  ▶ uptime-kuma  ├──────────────────────────┬───────────────────────────┤
│  ⏸ test-api     │  可视化组件模式 (左)     │  纯文本 YAML 模式 (右)    │
│                 │  容器名称: web-app       │  services:                │
│                 │  镜像: nginx:alpine      │    web-app:               │
│  [ + Compose ]  │  端口: 8080:80           │      image: nginx:alpine  │
│                 │  [ + 环境变量 ]          │      ports: ["8080:80"]   │
│                 ├──────────────────────────┴───────────────────────────┤
│                 │  实时日志流 (终端高亮输出)...                        │
└─────────────────┴──────────────────────────────────────────────────────┘

Dockge 最出彩的设计在于左右实时同步编辑：

左侧是结构化交互表单，点击按钮可以一键添加容器服务、端口映射、挂载卷与依赖网络；
右侧是标准的 compose.yaml 代码编辑器，自带语法高亮与缩进校验；
在左侧点选，右侧代码毫秒级自动生成；在右侧修改 YAML 文本，左侧卡片立刻重绘。

3.3 实战：在 Web 端发布一个真实业务应用

以部署一个轻量级 Uptime Kuma 监控服务为例：

点击左上角 + Compose（新建 Stack）；
填写 Stack Name 为 monitor；

在右侧代码框中直接贴入以下标准配置：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

点击右上角的 .env 标签页，填入环境变量（若有需要）；
点击顶部的 Deploy（部署）按钮。

Dockge 会立即在后台调用 Docker CLI 执行镜像拉取并挂载。你可以看到下方弹出的全屏终端实时打印拉取进度与容器启动日志。

同时，登录 VPS 终端查看物理路径：

1	ls -la /opt/stacks/monitor

你会发现磁盘上已经真实生成了 /opt/stacks/monitor/compose.yaml 文件与 ./data 目录。毫无私有格式封装，完全保持原生规范。

3.4 迁移导入现有旧项目

如果你的服务器此前已有零散存放在 ~/my-project 或 /home/ubuntu/app 的 Docker Compose 项目，无缝迁移至 Dockge 只需简单的文件移动：

# 假设原有项目目录为 /home/ubuntu/wordpress
# 1. 将整个目录直接移动至 /opt/stacks/
sudo mv /home/ubuntu/wordpress /opt/stacks/

# 2. 检查内部文件名是否符合规范（必须是 compose.yaml 或 docker-compose.yml）
ls -la /opt/stacks/wordpress/

刷新 Dockge 网页后台，点击右上角菜单中的 Scan Stacks Folder，Dockge 会自动扫描 /opt/stacks 目录下的所有子文件夹，识别其 YAML 文件，并直接将其挂载在左侧列表供日常管控。

3.5 生产级安全访问加固

管理面板拥有宿主机 Docker 的完整控制权，默认使用 HTTP 协议且未开启传输加密，绝不可直接暴露 5001 端口给公网。

方案 A：使用 Tailscale 开启私网直连（推荐）

在 Dockge 的 compose.yaml 中，不要监听 5001:5001 全接口，而是绑定你服务器的 Tailscale 虚拟 IP：

1 2	ports: - "100.88.99.10:5001:5001"

这样外部公网 IP 完全无法扫描到 5001 端口，只有接入了 Tailscale 内网的个人设备才能打开管理后台。

方案 B：反向代理 + 强制 HTTPS

使用 Nginx Proxy Manager 或 Caddy 反向代理 http://127.0.0.1:5001，绑定二级域名并启用 HTTPS 证书，同时配置 Basic Auth 或 Access List 访问名单。

4、生产避坑指南与排障速查

避坑 1：修改 Stack 时提示 Permission Denied 无法保存

根因：宿主机 /opt/stacks 目录被 root 拥有，而容器内进程默认执行文件写入时权限受限。

解法：在宿主机修正目录属主权限：

1 2	sudo chown -R $USER:$USER /opt/stacks /opt/dockge sudo chmod -R 755 /opt/stacks

避坑 2：导入历史项目后显示「Broken」状态

根因：历史项目目录中未放置 compose.yaml，或者 YAML 缩进中混入了制表符（Tab 键）。
解法：进入该目录，使用 YAML 格式校验工具检查，或将制表符转换为空格。

5、FAQ

Q1：如果把 Dockge 容器停止或删除了，跑在上面的微服务会跟着挂掉吗？

不会。
业务容器是由 Docker 守护进程独立托管的。Dockge 仅仅是一层管理控制器。停止 Dockge 不会对任何业务容器产生干扰。你甚至可以直接通过 SSH 登录服务器，在 /opt/stacks/<项目名> 目录下运行 docker compose restart 手动接管。