dockge 1.5.0 介绍与选型指南

目标：说清 dockge 是什么、能做什么、架构如何、与同类工具的差异在哪，帮助读者在"是否引入 dockge"的问题上做出有依据的决策。本篇为认知篇，所有版本、活跃度与功能论断均以官方源（GitHub 仓库、Release 页、镜像发布页）为依据，查询日期统一为 2026-10-18，本篇不做本地安装实测（部署实测见《dockge Docker Compose 部署指南》）。

一、环境信息

本篇是软件认知与选型类文档，不涉及本地安装与命令实测，因此本章记录的是撰写本篇时的"信息基准"：查询日期、版本依据与官方来源清单。读者日后阅读本篇时，应以这些来源的最新状态为准复核版本号与活跃度数据。

• 信息查询日期：2026-10-18（本篇所有版本号、活跃度数据、功能描述的统一取数时点）
• 介绍版本：dockge 1.5.0（官方 GitHub 最新稳定 Release，发布于 2025-03-30；发布页重定向实测 https://github.com/louislam/dockge/releases/latest → 1.5.0）
• 版本依据：
  • GitHub Releases：https://github.com/louislam/dockge/releases（releases/latest 302 重定向至 tag 1.5.0，2026-10-18 实查）
  • 官方发布页标签列表：https://hub.docker.com/v2/repositories/louislam/dockge/tags（标签 1 与 1.5.0 的 last_updated 均为 2025-03-30，即滚动标签 1 当前指向 1.5.0；另存在 nightly 滚动开发标签，2026-10-18 仍在更新）
• 官方来源清单：
  • 官方主页与配置生成器：https://dockge.kuma.pet
  • 源码仓库：https://github.com/louislam/dockge（MIT 许可）
  • README（安装与功能说明）：https://github.com/louislam/dockge#readme
  • Release Notes（1.5.0）：https://github.com/louislam/dockge/releases/tag/1.5.0
  • 发布物发布页：https://hub.docker.com/r/louislam/dockge（含标签 1、1.5.0、nightly 的更新时间与累计拉取量）
• 本文撰写环境说明：本篇不执行任何本地安装；文中引用的配置说明均以官方 README（标注出处）为准，功能描述以官方文档与源码（backend/ 目录）为对照。

二、软件概述

dockge 是一个自托管的 Compose 栈管理面板，开源协议 MIT，作者 louislam 也是知名监控工具 Uptime Kuma 的作者。官方 README 对它的定位是"花哨、易用且响应迅速的自托管栈管理器"（原词：fancy, easy-to-use and reactive, stack-oriented manager）——围绕 compose.yaml 文件、以"栈"为核心管理单元的图形化管理面板。

它解决的核心痛点很明确：用 Compose 部署的服务越积越多之后，compose.yaml 文件散落在服务器的各个目录里，部署、改参、查看运行状态、看日志、进终端都要来回切命令行。dockge 把这些动作集中到一个 Web 界面：栈的创建/编辑/启动/停止/重启/删除全部可视化，且文件仍然以普通 compose.yaml 的形态留在磁盘上——官方 README 特别强调"File based structure - Dockge won't kidnap your compose files"（基于文件结构，dockge 不会绑架你的 compose 文件），你在面板外用普通 Compose 命令行照样能操作同一批文件，这是它与"把配置收进自己数据库"类管理平台最本质的区别。

💡 技术拓展：这里的"栈（stack）"指由一份 compose.yaml 定义的一组相关服务实例的集合。编排体系里同类概念横向对比——

编排体系	"栈"的载体	管理粒度	典型适用规模
Compose	compose.yaml 文件	单机上的多服务实例组	1 台主机、几个到几十个栈
Swarm	stack 文件 + 集群服务	集群级多副本服务	3 台以上小集群
Kubernetes	Helm Chart / Kustomize 清单	命名空间内工作负载集合	中大规模集群
Nomad	Job 规范（HCL/HCL2）	数据中心级任务组	混合负载数据中心

dockge 只面向 Compose 体系的单机栈管理，不涉及 Swarm/Kubernetes 分发调度。本文介绍的就是这一形态。

与 Uptime Kuma 的关系值得单独一句：两者是同一作者的姊妹项目，技术栈同源（Node.js + Vue 3 + Socket.IO + SQLite），界面风格与交互习惯高度一致——README 原话是"If you love Uptime Kuma's UI/UX, you will love this one too"。职责上两者互补：Uptime Kuma 负责"监控可用性并告警"，dockge 负责"管理服务本身的生命周期"，很多自托管用户会把两者搭配部署（监控告警篇与部署管理各司其职），但两者代码独立、数据独立、可分开单独部署。

三、核心架构

理解 dockge 的架构，关键在于理解它"薄"在哪里：它自己不解析、不存储编排逻辑，而是把所有编排动作委托给 Compose 工具链，自身只做"文件编辑 + 命令转发 + 状态展示"。本章按分层拆解（依据：官方仓库 backend/ 目录源码与 README，查询日期 2026-10-18）。

关键设计动因有两条，都是从这套分层自然推导出来的：

1. 文件即真身：dockge 保存栈时只写 /opt/stacks/<栈名>/compose.yaml 与 .env，不把编排配置收进自己的 SQLite。因此"面板里删除栈"与"磁盘上删目录"是同一件事；反过来，手工改文件后面板刷新即可识别。备份迁移也因此简化为"拷文件"（详见《dockge 日常运维手册》）。
2. 命令即面板：面板上的"部署/启动/停止"按钮，底层就是到对应栈目录执行 Compose 子命令（源码 backend/stack.ts 中 start/stop/restart/delete 分别映射 compose up -d --remove-orphans、compose stop、compose restart、compose down --remove-orphans）。部署过程的真实输出以实时终端流（terminalWrite 事件）推送到页面，所见即命令行所得。

💡 技术拓展：面板型工具对编排配置的"收编程度"分三种流派，选型时值得先想清楚——

流派	代表	配置存放	代价与收益
文件式（本文对象 dockge）	dockge	磁盘上的 compose.yaml	随时可脱离面板用命令行；面板功能因此偏轻
库式（收进平台数据库）	Portainer 栈	平台库 + 平台 API 导出	平台能力强；离开平台后配置还原是额外工作
声明式 GitOps	Komodo 等	Git 仓库为单一事实源	审计/回滚强；需要维护 Git 工作流

dockge 选择文件式，收益是零锁定、备份迁移极简，取舍是它不提供配置漂移的强纠偏（文件被改它就如实展示）。

多主机能力（1.4.0 引入）：dockge 支持"多 agent 模式"——在多台编排主机上各跑一个 dockge 实例，主实例通过 Socket.IO 连接其他实例（以 endpoint 标识），在一个界面里管理分布在多台主机上的栈。这是一种"面板级联邦"，每台主机仍需各自部署一个 dockge，并非把面板做成中心调度器。

安全与权限模型：面板访问用账号密码（首访强制初始化管理员），登录后签发 JWT，后续 Socket.IO 会话以令牌恢复；密码经加盐哈希入库；支持 2FA（TOTP）。对被管服务实例的控制权完全来自挂载进面板的引擎套接字——这意味着能打开 dockge 界面的人，等价于拿到了该主机编排引擎的完全控制权，官方在 1.5.0 把交互式终端（Console）改为默认关闭（环境变量 DOCKGE_ENABLE_CONSOLE=true 才开启）正是基于这个风险考量（Release Notes 1.5.0 Breaking change 原文：出于安全原因 Console 功能默认禁用，理解风险后可通过环境变量开启）。

四、功能特性

本章按官方 README 的功能清单逐项展开（依据 README 与 1.5.0 Release Notes，查询日期 2026-10-18），并在功能后标注引入版本，便于对照。

两点补充解读：

1. 1.5.0 的实质变更集中在三处（Release Notes 实查）：其一，Console 默认禁用（前述安全考量，部署时若需要必须显式加环境变量，这是从旧版本升级后"终端菜单消失"的最常见原因）；其二，内嵌依赖升级——编排客户端升级到 28.0.4、内嵌 Compose 升级到 2.34.0；其三，一批 UI 修正（如保留 YAML 注释的列表重排序修复）。
2. 响应式体验是它刻意打磨的点：README 用"Reactive - Everything is just responsive"自述，栈状态、部署进度、终端输出都由 Socket.IO 双向推送而非轮询，这也是作者从 Uptime Kuma 一脉相承的交互风格。

五、快速上手（引自官方文档）

本节为官方文档的最小上手路径（来源：官方 README "How to Install" 一节，原文链接 https://github.com/louislam/dockge#readme ，本篇不重复执行部署实测，逐条命令的实测过程与回显见《dockge Docker Compose 部署指南》）。官方要求前置具备：编排引擎 20 以上版本（或 Podman 经其兼容层提供等价接口）、可运行该引擎的主流 Linux 发行版（Ubuntu、Debian Bullseye+、Raspbian、CentOS、Fedora、ArchLinux 均在官方支持列表；架构支持 amd64/arm64/armv7）。

官方标准安装步骤（README 原文流程，注释为原文）：

# 1. 建两个目录：栈目录 + dockge 自身编排目录（README 原文：Create directories
#    that store your stacks and stores Dockge's stack）
#    mkdir -p /opt/stacks /opt/dockge

# 2. 进入 dockge 编排目录，下载官方 compose.yaml
#    cd /opt/dockge
#    curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml

官方部署文件的关键配置要点（完整 compose.yaml 逐项实测解说见《dockge Docker Compose 部署指南》）：

随后官方指引在该目录执行 Compose 启动命令完成部署，服务默认监听 http://localhost:5001。首次打开页面会强制进入管理员初始化页（无用户时服务端日志打印 No user, need setup），创建管理员后即可在界面新建第一个栈。

两个官方进阶配置（README "Advanced" 一节原文）：栈目录不在 /opt/stacks 时，可用官方生成器 https://dockge.kuma.pet/compose.yaml?port=5001&stacksPath=/opt/stacks 带自定义端口与栈路径参数生成 compose.yaml；需要栈文件归属非 root 用户时，在 environment: 中加 PUID/PGID（README 原文：Both PUID and PGID must be set for it to do anything，两者必须同时设置才生效）。

六、适用场景与限制

选一个工具，一半看它能干什么，一半看它明确不干什么。本章把官方声明与社区实践中公认的场景边界整理在一起（依据官方 README、Release Notes 与仓库 Issue 区常见主题，查询日期 2026-10-18）。

适用场景：

1. 单机多栈的自托管服务管理：家庭实验室或中小团队服务器上跑着十几个 Compose 栈，需要统一的查看/启停/改配入口——这是 dockge 的主场景。
2. 命令行到图形界面的过渡：文件式设计保证随时可以回到纯命令行操作，适合"想要界面但不想被平台锁定"的团队。
3. 多台主机的轻量联邦：几台机器各自跑 dockge 并互相加为 endpoint，一个界面管理全部，无需中心化调度器。
4. 与 Uptime Kuma 组成监控+管理组合：同作者、同风格，监控告警（Uptime Kuma）与生命周期管理（dockge）各司其职。
5. 教学与演示：把 Compose 的命令行语义可视化，面板动作与命令一一对应，适合讲解编排概念。

已知限制（引用官方原文声明处已标注）：

1. 不做跨主机调度：多 agent 只是"多面板视图合并"，不是 Swarm/Kubernetes 那样的资源池调度；栈仍属于单台主机。
2. Windows 不支持：README 明确"❌ Windows (Will be supported later)"，仅支持主流 Linux 发行版（Debian/Raspbian Bullseye 以下亦不支持）。
3. Console 默认关闭（1.5.0 起）：主机级 Web 终端需显式开启环境变量，升级后若发现终端入口消失属预期行为。
4. 面板权限约等于编排引擎权限：官方 compose.yaml 必须挂载引擎套接字，面板口令一旦泄露，攻击者获得的是整台主机编排层的完全控制权，公网暴露必须叠加反代认证/防火墙等外围防护（相关实践见《dockge 日常运维手册》）。
5. 无内置告警：它管理栈，不监控业务可用性；可用性探测与告警需搭配 Uptime Kuma 等监控工具。
6. 配置纠偏弱：手工改动文件后面板如实展示，不会反向"修复"到某个期望状态——这是文件式设计的必然取舍。

七、同类选型对比

本节以 2026-10-18 实查的量化数据横向对比 dockge 与三类常见替代方案：全功能面板 Portainer CE、多主机编排平台 Komodo、以及不用面板的 Compose 命令行裸用。数据来源：GitHub 仓库页与 API（star/issue 数、最新 Release tag）、官方发布页（拉取量），逐项标注在表后。

数据出处（均为 2026-10-18 实查）：各仓库 https://api.github.com/repos/<owner>/<repo>（stars/issues/pushed_at/license）；最新版本取 https://github.com/<owner>/<repo>/releases/latest 重定向目标（dockge→1.5.0、portainer→2.45.2、komodo→v2.3.3、uptime-kuma→2.5.6）；dockge 拉取量取官方发布页 API https://hub.docker.com/v2/repositories/louislam/dockge/ 的 pull_count。

关键差异与如何选型：

• 单机为主、想保持文件自由：dockge 是最贴合的选择——文件式管理、零锁定、轻量，功能面正好覆盖 Compose 栈的生命周期。
• 要一个"全家桶"引擎控制台（管网络、存储、用户 ACL、团队 RBAC）：Portainer CE 覆盖面更广，但栈管理为库式、多环境高级能力与商业版挂钩，资源占用也更高；如果只用它的栈管理功能，dockge 更轻。
• 多主机规模化、想要声明式/GitOps 管理与构建流水线：Komodo 的多主机原生架构更合适；dockge 的多 agent 只适合"几台机器"的轻量联邦。
• 栈数量少、脚本化程度高、没有界面诉求：直接 Compose 命令行裸用即可，无需引入面板；当栈一多、交接的人一多，面板的收益才会显现。
• 监控告警诉求：以上工具都不解决"服务挂了要不要通知我"的问题，按社区惯常组合搭配 Uptime Kuma（92,591 stars，2026-10-18 实查）。

八、参考链接

1. dockge 官方主页（含 compose.yaml 在线生成器）：https://dockge.kuma.pet
2. dockge 源码仓库与 README：https://github.com/louislam/dockge
3. dockge 1.5.0 Release Notes（Console 默认禁用等变更）：https://github.com/louislam/dockge/releases/tag/1.5.0
4. dockge 全部 Release 列表：https://github.com/louislam/dockge/releases
5. dockge 官方发布页（louislam/dockge）：https://hub.docker.com/r/louislam/dockge
6. Portainer 仓库（对比数据来源）：https://github.com/portainer/portainer
7. Komodo 仓库（对比数据来源）：https://github.com/Moghtech/komodo
8. Uptime Kuma 仓库（同作者姊妹项目）：https://github.com/louislam/uptime-kuma
9. 平台部署实测篇：《dockge Docker Compose 部署指南》（逐条命令实测）
10. 平台运维篇：《dockge 日常运维手册》（巡检/备份/升级/排障）