Dokploy 容器部署完全指南¶

为什么要学 Dokploy¶

最简洁的自托管 PaaS：Dokploy 专注于一件事——让 Docker 部署变简单。界面干净直观，没有过多概念和配置项。对于只需要部署几个应用和数据库的开发者，Dokploy 的复杂度恰到好处。
轻量级，1GB 内存即可运行：相比 Coolify 需要 2GB+，Dokploy 在 1GB 内存的 VPS 上就能流畅运行。适合预算有限的个人开发者和小项目。
Traefik 集成，自动 SSL：内置 Traefik 反向代理，自动配置 Let's Encrypt SSL 证书和路由规则。添加域名后 HTTPS 自动生效。
数据库一键部署：PostgreSQL、MySQL、Redis、MongoDB、MariaDB 一键创建，自动配置持久化存储和连接信息。
Docker Compose 原生支持：可以直接使用 docker-compose.yml 定义多服务应用，Dokploy 会正确处理服务间网络、持久化和路由。

核心概念详解¶

Dokploy 是什么（白话解释）¶

你有一台服务器，想部署几个网站。手动方式是 SSH 进去装 Docker、拉镜像、配 Nginx、搞 SSL。Dokploy 把这些步骤做成了一个 Web 界面：点点鼠标就能部署应用、管理数据库、配置域名。

它比 Coolify 更轻量，比 CapRover 更现代化。如果你只需要简单的 Docker 部署而不需要复杂的 CI/CD 管道，Dokploy 是最佳选择。

核心概念¶

概念	说明
Project	项目（一组相关的应用和服务）
Application	应用（从 Git/Docker 部署）
Database	数据库服务
Compose	Docker Compose 多服务部署
Domain	域名绑定与路由
Deployment	一次部署记录
Registry	Docker Registry 配置

Dokploy vs Coolify vs CapRover 对比¶

特性	Dokploy	Coolify	CapRover
最低内存	1GB	2GB	1GB
UI 设计	现代简洁	现代全面	功能性
学习曲线	最低	低	中
功能丰富度	适中	最丰富	中等
数据库管理	一键部署	一键部署+备份	手动
Docker Compose	原生支持	支持	有限
多服务器	支持	支持	集群模式
一键应用	有限	100+	有限
监控	基础	内置	需配置
构建方式	Nixpacks/Docker	Nixpacks/Docker	Docker
技术栈	Next.js + tRPC	Laravel/Livewire	Node.js
适合场景	简单部署/小团队	全面的自托管	Docker部署
活跃度	活跃	非常活跃	稳定

安装与配置¶

系统要求¶

Linux 服务器（Ubuntu 22.04+/Debian 12+）
最少 1 CPU + 1GB RAM
Docker（安装脚本会自动安装）
域名（推荐但不必须）

一键安装¶

# SSH 到服务器
ssh root@your-server-ip

# 一键安装
curl -sSL https://dokploy.com/install.sh | sh

# 安装完成后显示：
# Dokploy is running on http://your-ip:3000
# 首次访问设置管理员账号

Docker 安装¶

docker run -d \
  --name dokploy \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dokploy-data:/data \
  dokploy/dokploy:latest

初始配置¶

打开 http://your-ip:3000
创建管理员账号
设置服务器信息
配置域名（可选）：Settings → Server → Domain
配置 SSL：自动启用 Let's Encrypt

添加 Git Provider¶

Settings → Git Providers → Add New

支持：
- GitHub（OAuth 或 Personal Access Token）
- GitLab
- Bitbucket
- Gitea
- 任意 Git URL

快速上手：5 分钟最小示例¶

部署一个 Node.js 应用¶

创建项目：Projects → Create Project → 输入名称
添加应用：项目内 → Create Service → Application
配置来源：
Source: GitHub
Repository: your-org/your-repo
Branch: main
构建设置：
Build Type: Nixpacks（自动检测）
Port: 3000
域名绑定：
Domains → Add Domain
输入 app.yourdomain.com
HTTPS: Auto
部署：点击 Deploy

部署一个数据库¶

Projects → Create Service → Database
选择 PostgreSQL 16
配置：
Database Name: mydb
Username: myuser（自动生成密码）
Create
记录连接信息（显示在 Database 面板中）

连接应用与数据库¶

在 Application → Environment Variables 中添加：

DATABASE_URL=postgresql://myuser:auto-generated-pass@db-service-name:5432/mydb

Dokploy 中同一项目的服务共享 Docker 网络，可以用服务名互相访问。

进阶用法¶

场景一：Docker Compose 多服务部署¶

在 Dokploy 中创建 "Compose" 类型的服务：

# docker-compose.yml
version: '3.8'
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:pass@db:5432/app
      - REDIS_URL=redis://cache:6379
    depends_on:
      - db
      - cache

  worker:
    build:
      context: .
      dockerfile: Dockerfile.worker
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
      - REDIS_URL=redis://cache:6379
    depends_on:
      - db
      - cache

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

  cache:
    image: redis:7-alpine

volumes:
  pgdata:

Dokploy 自动处理网络、持久化和路由。

场景二：自定义 Dockerfile 部署¶

# Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json .
EXPOSE 3000
CMD ["node", "dist/index.js"]

在 Dokploy 中：Build Type 选择 "Dockerfile"，指定 Dockerfile 路径。

场景三：环境变量管理¶

Application → Environment Variables

# 构建变量（Build Time）
NODE_ENV=production
NEXT_PUBLIC_API_URL=https://api.example.com

# 运行时变量（Runtime）
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret-key
SMTP_HOST=smtp.gmail.com

场景四：自动部署 Webhook¶

# Dokploy 自动在 GitHub 上设置 Webhook
# 每次 push 到配置的分支自动触发部署

# 也可以手动触发 API 部署
curl -X POST "https://dokploy.yourdomain.com/api/application.redeploy" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app-id"}'

场景五：Docker Registry（私有镜像）¶

Settings → Registry → Add Registry

- Docker Hub
- GitHub Container Registry (ghcr.io)
- AWS ECR
- Google GCR
- 自建 Registry

配置后可以从私有 Registry 拉取镜像部署

场景六：持久化存储¶

Application → Advanced → Volumes

# 添加挂载卷
Source: /data/uploads     # 宿主机路径
Target: /app/uploads      # 容器内路径

# 或使用 Docker Named Volume
Volume Name: app-uploads
Target: /app/uploads

场景七：多服务器部署¶

Settings → Servers → Add Server

1. 输入远程服务器 SSH 信息
2. Dokploy 自动在远程服务器安装 Docker
3. 创建应用时选择目标服务器
4. 从一个面板管理所有服务器的应用

场景八：健康检查与重启策略¶

Application → Advanced

# 健康检查
Health Check Path: /api/health
Health Check Interval: 30s
Health Check Timeout: 10s
Health Check Retries: 3

# 重启策略
Restart Policy: unless-stopped

# 资源限制
Memory Limit: 512MB
CPU Limit: 0.5

常见问题与排错¶

问题一：构建失败¶

查看部署日志：Application → Deployments → 点击失败的部署。

常见原因： 1. Nixpacks 检测错误：手动指定 Build Type 为 Dockerfile 2. 依赖安装失败：检查 package.json / requirements.txt 3. 内存不足：增加服务器 RAM 或 swap

# 在服务器上添加 swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

问题二：域名无法访问¶

排查步骤：
1. DNS 是否正确指向服务器 IP（A 记录）
2. 防火墙是否开放 80 和 443 端口
3. Traefik 是否运行：docker ps | grep traefik
4. 应用容器是否运行：docker ps | grep your-app
5. 查看 Traefik 日志：docker logs traefik

问题三：数据库连接失败¶

# 同一 Dokploy 项目内的服务使用内部网络
# 使用服务名（不是 localhost）作为主机名

# 查看 Docker 网络
docker network ls
docker network inspect dokploy-network

问题四：如何查看容器日志¶

# 在 UI 中
Application → Logs → 查看实时日志

# 在服务器上
docker logs -f container-name
docker logs --tail 100 container-name

问题五：如何备份¶

# Dokploy 数据目录
/etc/dokploy/

# 备份数据库
docker exec db-container pg_dump -U user dbname > backup.sql

# 全量备份
tar -czf dokploy-backup.tar.gz /etc/dokploy/

问题六：如何更新 Dokploy¶

# Dokploy 支持一键更新
# UI → Settings → 检查更新

# 或命令行
docker pull dokploy/dokploy:latest
docker restart dokploy

参考资源¶

官方网站：https://dokploy.com
官方文档：https://docs.dokploy.com
GitHub：https://github.com/Dokploy/dokploy
Discord 社区：https://discord.gg/dokploy
YouTube 教程：搜索 "Dokploy tutorial"
API 文档：部署后在 /swagger 路径查看