• 后端
• 前端
• 云原生
• DevOps
• 容器编排
• 运维

Docker 是 Dokploy 这套自托管 PaaS（Platform as a Service）平台的底层运行基石：应用构建、数据库容器、Traefik 路由乃至多节点 Docker Swarm 集群都建立在其之上。本篇指南以仓库 GUIDES.md 为骨架，完整覆盖 macOS、Ubuntu、Windows 三大平台的 Docker 安装步骤，并结合仓库源码（Dockerfile、dockerode 封装、Compose 解析与多平台镜像构建脚本）讲解 Dokploy 在运行时究竟如何使用 Docker，帮助你在正式部署 Dokploy 之前先把容器环境准备到位。

为什么 Dokploy 离不开 Docker

Dokploy 定位为 Vercel、Netlify、Heroku 的开源自托管替代方案，核心能力是"一条命令部署应用与数据库"。从仓库的 README.md 可以确认，它支持任意类型应用（Node.js、PHP、Python、Go、Ruby 等）、MySQL/PostgreSQL/MongoDB/MariaDB/libsql/Redis 数据库、数据库自动备份、Docker Compose 编排、多节点 Swarm 集群、Traefik 路由与实时监控。这些能力的共同底层执行单元都是 Docker 容器。

Dokploy 官方镜像本身就构建在 Docker 生态之上。查看根目录 Dockerfile 可以发现，镜像构建阶段会依次执行：

• 调用get.docker.com安装 Docker（固定版本28.5.2）与 rclone；
• 安装 Nixpacks（1.41.0）与 Railpack（0.15.4）两类无 Dockerfile 自动构建引擎；
• 复制 buildpacks 官方的pack二进制（0.39.1），支持 Cloud Native Buildpacks 构建方式。

也就是说，Dokploy 自身运行在容器中，同时"容器内再跑容器"来调度用户的应用与数据库，因此宿主机上 Docker 环境是否就绪，直接决定 Dokploy 能否正常工作。这也是 GUIDES.md 把 Docker 安装列为第一份指南的原因。

安装前准备：明确你的部署场景

在动手之前，先确认两类典型场景：

1. 在 VPS 上自托管 Dokploy：这是 README 推荐的正式使用方式，运行curl -sSL https://dokploy.com/install.sh | bash即可自动完成安装。安装脚本要求服务器已经具备可用的 Docker 环境，因此本文的安装步骤是前置条件。
2. 在本地开发机调试：macOS 与 Windows 使用 Docker Desktop 最为方便；Linux 使用 Docker Engine + Compose 插件。

需要留意的是，Dokploy 支持通过 SSH 协议管理远程服务器上的 Docker（详见下文"多服务器与远程 Docker"小节），因此即便你的控制台跑在 macOS 上，也仍然需要保证远程 Linux 服务器装好 Docker。

macOS：使用 Docker Desktop

macOS 上没有原生的 Docker Engine，官方推荐的桌面方案是 Docker Desktop。参照 GUIDES.md 的步骤：

1. 访问 Docker 官网的 Docker Desktop for Mac 产品页；
2. 下载 Docker Desktop 安装程序（选择与芯片架构匹配的版本：Apple Silicon 选 arm64，Intel 选 amd64）；
3. 双击下载的.dmg文件将其挂载；
4. 将 Docker 图标拖入 Applications 文件夹完成安装；
5. 从应用程序（Applications）中启动 Docker Desktop；
6. 如需熟悉操作界面，可跟随首次启动时的 onboarding 引导教程。

启动后建议在"Settings → Resources"中确认内存与 CPU 配额，因为 Dokploy 在本地开发场景会同时拉起多个容器（应用 + 数据库 + Traefik），默认配额可能偏紧。

Ubuntu：使用 apt 安装 Docker Engine

Linux 服务器（尤其是 Ubuntu VPS）是 Dokploy 最常见的部署环境。GUIDES.md 提供了基于官方 apt 仓库的完整安装流程，逐段说明如下。

第一步：卸载可能存在的旧版本

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

这条命令一次性清理系统里可能预装的旧 Docker 组件（如 Ubuntu 自带源里的docker.io、docker-compose、podman-docker、containerd、runc）。它们往往版本落后或与官方源冲突，卸载后可避免后续安装时出现包冲突。

第二步：更新索引并安装前置依赖

sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings

ca-certificates用于校验 HTTPS 下载的证书，curl用于拉取 GPG 密钥，/etc/apt/keyrings目录用于存放密钥文件。

第三步：添加 Docker 官方 GPG 密钥

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc

密钥被保存为docker.asc（新版 apt 支持 ASCII-armored 密钥），chmod a+r确保所有用户可读，apt 校验软件包签名时会用到它。

第四步：将官方仓库写入 apt 源列表

echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

这条命令动态生成了仓库地址：$(dpkg --print-architecture)自动识别 amd64/arm64 架构，$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")自动识别系统代号（如noble、jammy），因此同一段命令可复用于不同 Ubuntu 版本，无需手工改版本号。stable表示使用稳定发布通道。

第五步：安装 Docker Engine 及插件

sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装清单含义：

其中docker-compose-plugin对 Dokploy 尤其重要——仓库在 README 中明确将"原生支持 Docker Compose"列为核心功能，UI 侧有 compose 文件编辑器，后端有完整的 Compose 解析与部署服务，且配套了 compose 测试套件 与 镜像拉取测试，说明 Compose 是 Dokploy 的一条一等公民能力。

提示：生产服务器上，安装完成后通常还需要将当前用户加入docker组（sudo usermod -aG docker $USER）并重新登录，以便免 sudo 执行 docker 命令。

Windows：WSL2 + Docker Desktop

Windows 上运行 Docker 依赖 WSL2 虚拟化。参照 GUIDES.md 的步骤：

1. 启用 WSL2：如果尚未启用，先在 PowerShell（管理员）执行wsl --install完成内核与默认发行版的安装；
2. 访问 Docker 官网的 Docker Desktop for Windows 页面；
3. 下载安装程序并运行，按提示完成安装；
4. 安装向导会询问是否使用 WSL2 后端，确认勾选（这是 Docker Desktop 默认且推荐的模式）；
5. 从开始菜单启动 Docker Desktop。

启动后在终端执行wsl --version可确认 WSL 内核版本，docker version可确认客户端与引擎均已就绪。若 Dokploy 部署目标仍是 Linux VPS，Windows 上的 Docker Desktop 只承担管理端角色，核心能力同样依赖远程服务器的 Docker 环境。

安装验证：确认 Docker 环境可用

安装完成后，建议按以下顺序验证（无论哪个平台都适用）：

# 查看客户端与服务端版本（含 compose 插件信息） docker version # 确认 Compose 子命令可用 docker compose version # 拉取并运行 hello-world 验证完整链路 docker run hello-world

docker version会分别显示 Client 与 Server 两段信息，Server 段出现即代表引擎守护进程正常。docker compose version用于确认上文中docker-compose-plugin已生效，这是 Dokploy Compose 部署路径的宿主侧依赖。最后用hello-world走一遍"拉镜像 → 创建容器 → 运行 → 退出"的完整流程，确认网络与运行时均无问题。

日常维护层面，可以从仓库源码看到 Dokploy 会调用哪些 Docker 原生命令。在 packages/server/src/utils/docker/utils.ts 中，清理例程分别执行：

docker container prune --force # 清理停止状态的容器 docker builder prune --all --force # 清理所有构建缓存

需要说明的是，源码注释明确提示卷（volume）的清理必须由用户手工执行：自动清理时，一个处于停止状态的容器可能仍在占用卷，直接删除存在数据风险。这一设计体现了 Dokploy 对宿主 Docker 资源管理的谨慎态度，也提醒你在宿主侧同样按此原则操作。

从 Docker 到 Dokploy：容器环境如何被真正使用

理解了安装步骤，再看 Dokploy 在运行期如何使用 Docker，能让安装配置更有针对性。

Docker Engine 的编程式调用：dockerode

Dokploy 的后端并不直接 shell 调用 docker 命令，而是通过 Node.js 的dockerode库（apps/dokploy/package.json 中锁定版本4.0.2）以编程方式驱动 Docker API。应用、数据库、监控等几乎所有容器操作都走这条链路，例如 packages/server/src/utils/databases/postgres.ts 创建 PostgreSQL 容器、packages/server/src/utils/builders/index.ts 构建应用镜像时，均通过getRemoteDocker(serverId)拿到 Docker 客户端实例。

多服务器与远程 Docker：SSH 直连

Dokploy 的"Multi Server"特性允许把应用部署到远程服务器。此时客户端通过 SSH 协议直连远程 Docker 守护进程，见 packages/server/src/utils/servers/remote-docker.ts：读取服务器记录的 IP、端口、用户名与 SSH 私钥，构造Dockerode({ host, port, username, protocol: "ssh", sshOptions })。这意味着远程服务器的 Docker 只需开放 SSH 通道即可被 Dokploy 接管，无需额外开放 Docker 的 TCP 端口——这也是生产环境推荐的安全做法。

多平台镜像：buildx 与 docker build

仓库自身镜像的发布流程（apps/dokploy/docker/push.sh）会创建 buildx builder，并一次性构建linux/amd64,linux/arm64双架构镜像后推送到 registry。本地开发时也可用 apps/dokploy/docker/feat.sh 仅构建当前架构的 feature 镜像。这解释了为什么安装阶段要装docker-buildx-plugin：没有 buildx，多架构构建与缓存加速都无法工作。

常见问题与注意事项

• Docker 与 Dokploy 的版本关系：Dokploy 官方镜像内嵌 Docker28.5.2（Dockerfile），但这不要求你手工安装完全一致的版本；宿主 Docker 保持官方源中的最新稳定版即可。真正硬性的版本要求是 Compose 插件与 buildx 插件存在。
• 非 root 用户权限：安装后若docker命令报权限错误，说明当前用户不在docker组中，按上文提示执行usermod -aG docker并重新登录即可。
• VPS 场景的安全基线：不要让 Docker 守护进程直接暴露公网 TCP 端口；Dokploy 的远程管理走 SSH 通道（见上文remote-docker.ts），这是更安全的选择。
• 架构匹配：Apple Silicon Mac 与 ARM VPS 都要选择 arm64 版本软件；Ubuntu 源地址中的$(dpkg --print-architecture)会自动完成架构识别，无需手工干预。
• 资源规划：Dokploy 一个项目往往包含应用 + 数据库 + Traefik 多个容器，请为 Docker Desktop 或 VPS 预留充足的 CPU 与内存，并在运行监控面板出现资源告警时优先排查宿主侧配额。

完成以上安装与验证后，Docker 环境即满足 Dokploy 的部署前提。接下来只需在 VPS 上执行 README 提供的一键安装命令，或按官方文档完成初始化，即可把仓库中看到的应用部署、数据库管理、Compose 编排与多节点集群能力一一落地。

• 后端
• 前端
• 云原生
• DevOps
• 容器编排
• 运维