部署两个应用就吃光服务器？Dokploy 部署避坑指南 · 从"在服务器上 build"到"外部 build + 拉镜像"

❌ 真正原因：你在服务器上 build！

Dokploy 默认的部署方式是：拉取你的源码 → 在服务器上执行 docker build → 生成镜像 → 运行容器。

问题是，构建过程极其吃资源。一个 Next.js 项目 build 一次，轻松吃掉 2GB+ 内存和大量 CPU。如果同时跑两三个项目的构建，小规格 VPS（2核4G/2核8G）直接被按在地上摩擦。

"You're building on this machine, of course the resource consumption is high."

「你在这台机器上 build，当然消耗大。」

✅ 正确姿势：把构建（build）这个"体力活"甩给外部——用 GitHub Actions 在 GitHub 的服务器上构建镜像，构建完推送到 ghcr.io，Dokploy 只需要拉取现成镜像运行即可。

"A better approach is to use external Docker to build."

「更好的方法是用外部 Docker 来 build。」

📋 一句话解释

GitHub Actions 是 GitHub 提供的免费 CI/CD 自动化平台。你写好一个配置文件（YAML 格式），每次代码 push 到仓库，GitHub 就自动帮你执行你定义的一系列任务。

"GitHub Actions automates your build, test, and deployment pipeline."

「GitHub Actions 帮你自动化 构建 → 测试 → 部署 的整个流水线。」

📋 一句话解释

ghcr.io 是 GitHub 提供的容器镜像仓库（Container Registry）。你可以把构建好的 Docker 镜像存在这里，就像把代码存在 GitHub 一样。

⚠️ 为什么选 ghcr.io 而不是 Docker Hub？

因为你的代码就在 GitHub 上，用 GitHub Actions 构建后直接推到 ghcr.io，全程一体化无缝衔接，认证用的就是 GitHub 自带的 GITHUB_TOKEN，不用额外注册账号、不用额外配密钥。

📋 一句话解释

Dokploy 是一个开源自托管 PaaS 平台（Platform as a Service），可以装在你自己的 VPS 上，替代 Vercel / Netlify / Heroku 来部署项目。它基于 Docker + Traefik 构建，提供可视化界面管理你的应用。

❌ 模式 A：Git 源码构建（默认，不推荐）

Dokploy 拉取你的源码 → 在服务器上执行 docker build → 生成镜像 → 运行

问题：构建过程吃 CPU 和内存，小服务器扛不住

✅ 模式 B：Docker 镜像部署（推荐！）

GitHub Actions 在外部构建好镜像 → 推送到 ghcr.io → Dokploy 只拉取现成镜像 → 直接运行

优势：服务器只干"跑服务"的活，资源消耗大幅降低

"This approach uses GitHub Actions to build Docker images. After the build completes, Dokploy directly pulls the image and starts it, significantly reducing server load."

「这种方式使用 GitHub Actions 构建 Docker 镜像。构建完成后，Dokploy 直接拉取镜像并启动，大幅降低服务器负载。」

Step 1 ✍️ 推代码
你把代码 push 到 GitHub 仓库的 main 分支

Step 2 🤖 触发 Actions
GitHub 检测到 push 事件，自动触发你定义的 workflow

Step 3 🔨 外部构建
在 GitHub 的 runner（2核7G免费服务器）上执行 docker build，你的 VPS 完全不参与

Step 4 📦 推送镜像
构建完成的镜像被推送到 ghcr.io（GitHub 容器注册表）

Step 5 🔔 触发部署
通过 Webhook 或手动触发，通知 Dokploy：有新镜像了！

Step 6 🚀 拉取运行
Dokploy 从 ghcr.io 拉取镜像（只下载，不需要 build），直接启动容器

"Build on GitHub's servers (free), store in ghcr.io, pull and run on your VPS."

「在 GitHub 的服务器上构建（免费），存到 ghcr.io，在你的 VPS 上拉取运行。」

💡 类比理解

想象你开了一家餐厅（VPS）。模式 A 是"在餐厅后厨自己杀鱼、磨面粉、烤面包"——后厨忙到炸。模式 B 是"让中央厨房（GitHub Actions）把半成品做好，送到你的餐厅（ghcr.io → Dokploy）"——你只需要装盘上菜。

repo — 访问仓库

workflow — 访问 GitHub Actions

write:packages — 上传镜像包

delete:packages — 删除旧镜像包（可选）

⚠️ 重要：生成后的 Token 只会显示一次，立即复制保存到密码管理器，丢了只能重新生成。

name: Build and Push Docker Image
on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
    - Checkout 代码
    - Login to ghcr.io
    - Build Docker image
    - Push to ghcr.io
    - Trigger Dokploy webhook

✅ 搞定！以后每次 push 代码到 main 分支，GitHub Actions 自动构建 → 推送 ghcr.io → Webhook 通知 Dokploy → 自动拉新镜像部署。全程自动化，服务器零构建负担。

📋 两种环境变量的处理方式

🔒 需要加密的（API Key、数据库密码等）：放到 GitHub Repo → Settings → Secrets and variables → Actions → Secrets

🔓 不需要加密的（NEXT_PUBLIC_ 开头的公开变量等）：放到 → Variables

🏃 运行时变量（不参与构建，只在容器跑起来后需要的）：在 Dokploy 的 Environment 里配置

🧹 技巧一：定期清理旧镜像

每次构建都会产生新镜像，旧镜像堆积会吃磁盘空间。建议在 Dokploy 的 Web Server 模块中打开每日自动清除废弃镜像功能。ghcr.io 免费账号也有存储限制，记得定期清理。

📏 技巧二：Docker 多阶段构建瘦身

在 Dockerfile 里用多阶段构建（Multi-stage build），把编译依赖和运行依赖分开。最终镜像只包含运行所需的文件，体积可以从 1GB+ 缩到 200MB 以下，拉取速度大幅提升。

🏷️ 技巧三：用版本标签代替 latest

别只打 latest 标签。用 v1.0.3 或 sha-abc1234 这样的版本标签，方便回滚和追踪。

🔄 技巧四：手动触发重新构建

如果代码没变但想重新部署，可以在 GitHub Actions 页面手动触发 workflow（在 YAML 里加上 workflow_dispatch 触发器即可）。

"Initial configuration only needs to be set up once and can be used permanently."

「初始配置只需要设置一次，就可以永久使用。」

☐ 项目有 Dockerfile → 意思是你的项目根目录要有一个 Dockerfile 文件，定义怎么打包成镜像。没有的话需要先写一个

☐ 代码已推到 GitHub → 你的项目源码在 GitHub 仓库里，不是 GitLab 或本地。（GitLab 有自己的 CI/CD，流程类似但工具不同）

☐ 有一台 VPS 且已装好 Dokploy → Dokploy 安装很简单，一行命令搞定（官方文档有）

☐ 域名已做好 DNS 解析 → A 记录指向你的 VPS IP（用 CloudFlare 的话 SSL 选"完全"）

☐ 创建 Personal Access Token (Classic) → 去 GitHub Settings → Developer Settings 创建，勾选 repo / workflow / write:packages 权限

☐ Token 已安全保存 → 复制到密码管理器或安全笔记，只显示一次！

☐ 创建 .github/workflows/docker-image.yml → 这是 GitHub Actions 的工作流配置文件，定义构建和推送的全部步骤

☐ 环境变量已配置到 Secrets/Variables → 加密的放 Secrets，公开的放 Variables，别把 .env 直接上传仓库

☐ Webhook 已配置 → 仓库 Settings → Webhooks → 添加 Dokploy 的 Webhook URL，事件选 Registry packages

☐ 添加 ghcr.io Registry → Dokploy 后台 → Registry → 填入 ghcr.io + GitHub 用户名 + Token 密码 → Test 通过 → Save

☐ 创建 Service，Provider 选 Docker → 意思是告诉 Dokploy "我不需要你帮我 build，我给你现成镜像"

☐ Docker Image 地址填写正确 → 格式：ghcr.io/用户名/仓库名:标签

☐ Cluster Settings 关联 Registry → Advanced → 选择刚添加的 ghcr.io registry

☐ 运行时环境变量已配置 → Dokploy 的 Environment 里填入运行时需要的变量

☐ 域名已配置 → Domains → 添加域名 → 打开 HTTPS → 选 Let's Encrypt

☐ 推一次代码，验证 Actions 自动触发 → 去 GitHub 仓库的 Actions 标签页，看 workflow 是否正常执行

☐ 确认镜像已推送到 ghcr.io → 去 GitHub → Packages 标签页，看是否有你的镜像

☐ Dokploy 自动拉取并部署成功 → Dokploy 后台 → Deployments 看日志是否成功

☐ 通过域名正常访问 → 浏览器打开你的域名，页面正常显示

☐ 检查 Monitoring 面板 → CPU 和内存消耗应该大幅下降，因为不再有 build 过程

☐ 开启 Dokploy 每日自动清除废弃镜像 → Web Server 模块里的设置，防止磁盘被旧镜像塞满

☐ 定期检查 GitHub Actions 分钟数 → 私有仓库免费 2000 分钟/月，超了会收费

☐ 定期轮换 Personal Access Token → 安全起见，建议设 90 天过期并提前更新

☐ 关注 ghcr.io 存储用量 → 免费账号有容量限制，定期清理旧版本镜像

问题：在 Dokploy 上直接 build，服务器资源拉满甚至构建失败。

方案：GitHub Actions 外部构建 → 推到 ghcr.io → Dokploy 只拉镜像运行。

效果：服务器资源消耗大幅下降，部署更稳定，支持更多项目。

成本：公开仓库完全免费，私有仓库每月 2000 分钟免费额度。

"After understanding the principles, you can let AI help you write the entire configuration."

「在明白原理以后，你可以让 AI 帮你写出完整的配置。」