dokploy-skill

name

dokploy-skill

description

Dokploy（自建 PaaS 平台）的管理技能：通过 SSH/API 管理服务器、部署应用， 管理 Docker Compose/Swarm，管理数据库（PostgreSQL/MySQL/MongoDB/Redis）， 管理 Traefik 反向代理、SSL 证书（Let's Encrypt/Cloudflare Origin CA）与域名， 支持卷备份/恢复、容器监控、服务器排障与调试。 触发使用本技能的场景： (1) 提到 "Dokploy" / "dokploy" (2) 要求部署/重部署应用 (3) Docker Compose 或 Swarm 相关操作 (4) 域名、SSL 证书、HTTPS 配置 (5) Traefik 配置检查/修改、502 错误、域名访问问题 (6) 创建数据库、备份、恢复 (7) 卷备份/恢复、S3 对接 (8) 查看容器日志、检查服务器状态 (9) 服务器维护、Dokploy 更新 (10) 选择构建类型（Nixpacks/Dockerfile/Buildpack）

Dokploy 服务器管理技能

Dokploy 是一个自建 PaaS（Platform as a Service）工具，可以基于 Docker 更方便地管理应用部署。

来源说明

本仓库基于上游仓库进行整理与中文化：

https://github.com/thruthesky/dokploy-skill

示例项目：Dokploy 配置（模板）

模板：这一节需要按你的环境填写。下面的值只是示例，不要保存/硬编码。

项目	值
Dokploy 服务器 URL	http://<server_ip>:3000 或 https://<dokploy_domain>
SSH 登录	root@<server_ip> 或 root@<dokploy_domain>
应用 ID	<app_id>
PostgreSQL 主机	<server_ip>:<port>
数据库名	<db_name>

部署监控脚本

# 实时监控部署状态
./.claude/skills/center-skill/scripts/deploy-watch.sh

# 查看部署状态与历史
./.claude/skills/center-skill/scripts/deploy-monitor.sh

# 部署失败时查看错误日志
./.claude/skills/center-skill/scripts/deploy-error-check.sh auto

---

通用 Dokploy 服务器连接信息

在接入一台新的 Dokploy 服务器之前，必须先向用户确认以下信息：

变量	说明	示例
DOKPLOY_SERVER_IP	Dokploy 服务器 IP	1.2.3.4
ROOT_SSH_CONNECTION	Root SSH 登录地址	root@1.2.3.4
DOKPLOY_API_KEY	Dokploy API Key	Settings → Profile → API/CLI 里生成

安全原则：连接信息只保存在会话/内存中，不写入文件。

需要向用户确认的问题

在进行 Dokploy 服务器操作前，需要以下信息：

1. Dokploy 服务器 IP（例如：1.2.3.4）
2. Root SSH 登录地址（例如：root@1.2.3.4）
3. Dokploy API Key（在 Settings → Profile → API/CLI 生成）

※ 必须已配置 SSH Key 登录（例如已完成 ssh-copy-id）

---

参考文档

按不同任务类型参考对应文档：

任务	文档	主要内容
通过 API 远程管理	api.md	Dokploy REST API、认证、部署自动化
应用管理/配置	applications.md	环境变量、监控、资源管理、Swarm 配置
构建类型选择	build-types.md	Nixpacks、Dockerfile、Buildpack 对比
Cloudflare 域名/SSL	cloudflare.md	Cloudflare DNS、Origin CA、代理设置
traefik.me 免费域名	traefik-me-domain.md	测试用免费域名（仅 HTTP）
卷备份/恢复	volume-backups.md	S3 对接、Named Volume 备份/恢复
数据库管理	database.md	PostgreSQL/MySQL/MongoDB/Redis 管理
Docker Compose 管理	docker-compose.md	多容器配置、卷挂载规则
问题排查/调试	debugging.md	502 错误、域名访问问题、Traefik 日志
服务器维护/更新	maintenance.md	Dokploy 更新、磁盘管理、备份

---

快速参考

常用端口

框架	默认端口
Next.js / Node.js	3000
Laravel / PHP	8000
Django / Python	8000
NGINX（静态站点）	80

容器监听地址

# 正确写法（监听所有网卡）
0.0.0.0:3000

# 错误写法（外部无法访问）
127.0.0.1:3000

Docker Compose 卷挂载

# 正确写法（相对路径）
volumes:
  - "../files/my-data:/var/lib/data"

# 错误写法（不建议使用绝对路径）
volumes:
  - "/folder:/path/in/container"

---

基于 SSH 的操作示例

查看服务器状态

# 查看 Docker 容器状态
ssh root@$SERVER_IP "docker ps"

# 查看 Dokploy 必要容器（4 个：dokploy/postgres/redis/traefik）
ssh root@$SERVER_IP "docker ps | grep -E 'dokploy|postgres|redis|traefik'"

# 查看磁盘使用
ssh root@$SERVER_IP "df -h"

排查域名访问问题

# DNS 检查
dig +short example.com

# 查看 HTTP 响应
curl -sI https://example.com | head -10

# 在 Traefik 配置里搜索域名
ssh root@$SERVER_IP "grep -r 'example.com' /etc/dokploy/traefik/dynamic/*.yml"

# 查看 SSL 证书信息
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates

查看容器日志

# Traefik 日志
ssh root@$SERVER_IP "docker logs dokploy-traefik --tail 100"

# 指定服务日志
ssh root@$SERVER_IP "docker service logs <service-name> --tail 100"

重启 Docker / 服务

# 只重启 Traefik
ssh root@$SERVER_IP "docker restart dokploy-traefik"

# 触发 Dokploy 服务滚动重启
ssh root@$SERVER_IP "docker service update --force dokploy"

---

基于 API 的操作示例

查询项目/应用

# 查询所有项目
curl -X GET "http://$SERVER_IP:3000/api/project.all" \
  -H "x-api-key: $API_KEY"

# 查询指定应用
curl -X GET "http://$SERVER_IP:3000/api/application.one?applicationId=$APP_ID" \
  -H "x-api-key: $API_KEY"

重新部署应用

curl -X POST "http://$SERVER_IP:3000/api/application.redeploy" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d "{\"applicationId\": \"$APP_ID\"}"

更完整的 API 用法见 api.md。

---

排障顺序

1. 端口：应用是否在正确端口运行
2. 监听地址：是否监听在 0.0.0.0
3. DNS：域名是否解析到服务器 IP
4. 日志：docker service logs <service-name>
5. Traefik 配置：/etc/dokploy/traefik/dynamic/*.yml
6. API 查看部署状态：deployment.all 端点

更完整的排障流程见 debugging.md。

---

常见工作流程

部署新应用

1. 创建项目（UI 或 API）
2. 创建应用并关联 Git 源码
3. 选择构建类型（见 build-types.md）
4. 配置环境变量
5. 配置域名并申请 SSL 证书
6. 执行部署

配置域名

1. 配置 DNS 记录（A 记录 → 服务器 IP）
2. 在 Dokploy 中添加域名
3. 开启 HTTPS 并选择证书类型
4. 访问测试

使用 Cloudflare 见 cloudflare.md，测试域名见 traefik-me-domain.md。

配置卷备份

1. 连接 S3 兼容存储
2. 确认使用 Named Volume
3. 设置备份计划（Cron）
4. 执行一次测试备份

详细说明见 volume-backups.md。

---

示例项目：Docker 配置

Dockerfile 结构（etc/docker/Dockerfile）

FROM php:8.4-fpm

# 安装的软件包:
# - nginx, libpq-dev (PostgreSQL)
# - libpng-dev, libjpeg-dev, libwebp-dev, libfreetype6-dev (GD 图像处理)
# - APCu (PHP 共享内存缓存)

# PHP 扩展:
# - pdo, pdo_pgsql (PostgreSQL PDO)
# - gd (生成图片缩略图)
# - apcu (缓存)

WORKDIR /www
COPY . /www
EXPOSE 80
CMD php-fpm -D && nginx -g "daemon off;"

主要特点：

• PHP 8.4 + FPM + Nginx 单容器
• PostgreSQL PDO 驱动
• GD 库（生成缩略图）
• APCu 缓存
• 上传目录：/uploads（权限 777）

docker-compose.yml（仅用于本地开发）

services:
  center:
    build:
      context: .
      dockerfile: etc/docker/Dockerfile
    ports:
      - "8080:80"
    volumes:
      - .:/www          # 源码实时映射
      - ./uploads:/uploads  # 上传文件持久化保存

**重要：**用 Dokploy 部署时不会使用 docker-compose.yml，而是只使用 Dockerfile 通过 COPY 把源码打进镜像。

Nginx 配置（etc/nginx/conf.d/center.conf）

配置项	值	说明
client_max_body_size	50M	最大上传大小
静态文件缓存	365 天	/uploads/* 路径
禁止执行 PHP	403	禁止 uploads 目录下的 PHP
路由	layout.php	所有请求走 Front Controller

部署工作流

# 1. 执行测试（Deploy + Browser 测试）
./deploy.sh

# 2. 更新构建日期
npm run patch:build-date

# 3. 提交并推送
git add .
git commit -m "提交信息"
git push

# 4. 监控部署
./.claude/skills/center-skill/scripts/deploy-watch.sh

deploy.sh 测试项：

• tests/Deploy/**/*Test.php - 部署环境测试
• tests/Browser/**/*Test.php - 浏览器测试