# Dokploy部署在自托管 Dokploy 实例 (v0.28.4+) 上部署和管理应用程序。 Dokploy 是一个使用 Docker + Traefik v3 的开源 PaaS（Vercel/Heroku 的替代品）。 ## 快速参考项目 |价值 ---|--- 仪表板| `https:///` API库| `https:///api/` 招摇用户界面 | `https:///swagger`（需要浏览器登录）身份验证标头 | `x-api-key: <令牌>` CLI 安装 | `npm install -g @dokploy/cli` MCP服务器| `@sattva/dokploy-mcp`（449 个工具 — 完整的 API 覆盖） API版本 | OpenAPI 3.1.0，449 个端点文档 | ## 首次运行 — 设置 **首次使用**时，检查 Dokploy MCP 服务器是否已配置。如果没有，请运行交互式设置： 1. 检查：~/.claude/mcp.json 是否包含“dokploy”服务器条目？ 2. 如果否 → 运行：python3 Skills/dokploy-api-mcp/scripts/setup.py （或者用户技能安装目录中的完整路径） 3. 该脚本将： - 询问 Dokploy URL（例如，https://dokploy.example.com） - 请求 API 密钥（在仪表板 → 设置 → 配置文件 → API/CLI 中生成） - 验证连接 - 使用 MCP 服务器自动配置 ~/.claude/mcp.json 4. 告诉用户：“重新启动 Claude Code 以激活 Dokploy MCP 服务器。” **使用 CLI 参数**（非交互式）： python3技能/dokploy-api-mcp/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY **设置后**，MCP 服务器（`@sattva/dokploy-mcp`，449 个工具）将在下次 Claude Code 重新启动时可用。对于所有操作，优先使用 MCP 工具而不是curl。 ## 环境变量在使用此技能之前，请确保这些功能可用： DOKPLOY_URL=https://dokploy.example.com DOKPLOY_API_KEY=<生成的 api 令牌> 生成 API 令牌：仪表板 → 设置 → 配置文件 → API/CLI → 生成。 ## 部署工作流程 ### 第 1 步：检查当前状态 # 获取申请状态 curl -s -X GET "${DOKPLOY_URL}/api/trpc/application.one?input=$(python3 -c " 导入 urllib.parse, json print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}}))) ")" -H "x-api-key: ${DOKPLOY_API_KEY}" ### 第 2 步：触发部署 # 部署应用程序（POST — 突变）卷曲 -s -X POST "${DOKPLOY_URL}/api/application.deploy" \ -H "x-api-key: ${DOKPLOY_API_KEY}" \ -H“内容类型：application/json”\ -d '{"json":{"applicationId":"APP_ID"}}' ### 步骤 3：监控部署状态 # 轮询部署状态 curl -s -X GET "${DOKPLOY_URL}/api/trpc/deployment.all?input=$(python3 -c " 导入 urllib.parse, json print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}}))) ")" -H "x-api-key: ${DOKPLOY_API_KEY}" ### 第 4 步：验证健康状况卷曲-sk“https://<应用程序域>/api/health” ## API 参考 Dokploy 在内部使用 **tRPC**。两种请求格式： ### 查询（读取）- 带有编码输入的 GET GET /api/trpc/<路由器>.<过程>?input=URL_ENCODED({"json":{...}}) 标头：x-api-key：<令牌> ### 突变（写入）——带有 JSON 主体的 POST POST /api/<路由器>.<过程> 标头：x-api-key：<令牌> 标头：内容类型：application/json 正文：{“json”：{...}} ### 关键端点有关完整列表（449 个端点），请参阅 [references/API-REFERENCE.md]()。端点|方法|目的 ---|---|--- `项目.all` |获取 |列出所有项目 `项目.one` |获取 |通过ID获取项目 `application.one` |获取 |获取应用详细信息+状态 `application.deploy` |发布 |触发部署 `application.stop` |发布 |停止申请 `application.start` |发布 |开始申请 `应用程序.更新` |发布 |更新应用程序设置 `application.saveBuildType` |发布 |更改构建类型 `application.saveEnvironment` |发布 |设置环境变量 `compose.one` |获取 |获取撰写服务 `compose.deploy` |发布 |部署撰写服务 `部署.all` |获取 |列出应用程序的部署 `domain.byApplicationId` |获取 |获取应用程序的域 `domain.create` |发布 |添加自定义域 `postgres.one` |获取 |获取 PostgreSQL 服务 `redis.one` |获取 |获取Redis服务 `mariadb.one` |获取 |获取 MariaDB 服务 `mongo.one` |获取 |获取 MongoDB 服务 `environment.byProjectId` |获取 |列出环境 `回滚.回滚` |发布 |回滚部署 `计划.创建` |发布 |创建计划任务 `备份.创建` |发布 |创建备份配置 `notification.createTelegram` |发布 |设置电报通知 `docker.getContainersByAppNameMatch` |获取 |列出 Docker 容器 `application.readTraefikConfig` |获取 |读取 Traefik 配置 ## CLI 用法 # 安装 npm install -g @dokploy/cli # 身份验证（创建 ~/.config/dokploy/config.json）多克普洛伊认证 # 验证令牌多克普洛伊验证 # 应用管理 dokploy app create # 创建新应用程序 dokploy app deploy # 部署应用程序 dokploy app stop # 停止应用程序 dokploy app delete # 删除应用程序 # 数据库管理 dokploy db create # 创建数据库服务 dokploy db delete # 删除数据库服务 # 环境变量 dokploy env set # 设置环境变量 dokploy env list # 列出环境变量 # 项目管理 dokploy项目创建多克普洛伊项目清单 ## MCP 服务器（449 个工具 — 完整的 API 覆盖） **当 MCP 可用时，总是更喜欢 MCP 工具而不是curl。** MCP 自动处理 tRPC URL 编码和响应解析。有关完整的 449 工具参考，请参阅 [references/MCP-TOOLS.md]()。 ### 设置 **自动**（推荐）：从上面的“首次运行”部分运行安装脚本 — 它会自动配置 MCP。 **手册**（`~/.claude/mcp.json`）： { “mcp服务器”：{ “多克普洛伊”：{ “命令”：“cmd”， “args”：[“/c”，“npx”，“-y”，“@sattva/dokploy-mcp”]， “环境”：{ "DOKPLOY_URL": "https://dokploy.example.com/api", "DOKPLOY_API_KEY": "<您的 api 令牌>" } } } } **注意：** 在 macOS/Linux 上直接使用 `"command": "npx"` 而不是 `cmd /c`。 **本地开发：**使用 `"command": "node", "args": ["e:/My/MCP/dokploy-mcp/dist/index.js"]`。 ### MCP 工具按类别（共 449 个）类别 |工具|描述 ---|---|--- `应用程序_*` | 29 | 29应用程序生命周期、部署、配置、git 提供程序 `撰写_*` | 28 | 28 Docker Compose 服务 `设置_*` | 49 | 49服务器设置、Traefik、清理、监控 `通知_*` | 38 | 38 Slack/Telegram/Discord/电子邮件/Webhook/Gotify/Ntfy/Pushover/Lark/Teams `用户_*` | 18 | 18用户管理、API密钥、权限 `服务器_*` | 16 | 16远程服务器管理 `postgres_*` | 14 | 14 PostgreSQL 管理 `redis_*` | 14 | 14 Redis管理 `mysql_*` | 14 | 14 MySQL管理 `mariadb_*` | 14 | 14 MariaDB管理 `mongo_*` | 14 | 14 MongoDB管理 `补丁_*` | 12 | 12文件补丁 `备份_*` | 11 | 11数据库备份 `组织_*` | 10 | 10组织、邀请函 `sso_*` | 10 | 10 SSO/SAML 企业身份验证 `域_*` | 9 |域名/SSL 管理 `ai_*` | 9 | AI 驱动的作曲生成器 `部署_*` | 8 |部署历史记录、队列 `项目_*` | 8 |项目管理 `gitea_*` | 8 | Gitea 提供商 `docker_*` | 7 |集装箱作业 `bitbucket_*` | 7 |位桶提供商 `注册表_*` | 7 | Docker 注册表 `GitLab_*` | 7 |亚搏体育appGitLab提供商 `条纹_*` | 7 |计费（云） `环境_*` | 7 |每个项目的环境 `github_*` | 6 | GitHub 提供商 `licenseKey_*` | 6 |企业许可 `sshKey_*` | 6 | SSH 密钥管理 `坐骑_*` | 6 |卷安装 `目的地_*` | 6 | S3 备份目标 `时间表_*` | 6 |计划任务/cron `volumeBackups_*` | 6 |卷备份 `证书_*` | 4 | SSL 证书 `集群_*` | 4 | Docker Swarm 集群 `端口_*` | 4 |港口管理 `重定向_*` | 4 | URL 重定向 `安全_*` | 4 |安全设置 `previewDeployment_*` | 4 |预览部署 `swarm_*` | 3 | Swarm节点信息 `gitProvider_*` | 2 | Git 提供者通用 `回滚_*` | 2 |部署回滚 `admin_*` | 1 |管理员设置 ### MCP 部署工作流程 1. application_one → 检查当前状态 2. application_saveEnvironment → 如果需要设置/更新环境变量 3. application_saveBuildType → 确保配置了 Dockerfile 构建 4. application_deploy→触发部署 5. application_one → 轮询直到 applicationStatus = "done" 6.curl health 端点 → 验证应用程序是否正常工作 ### MCP 限制（仅使用仪表板） * **构建/容器日志** — 仅 WebSocket，无 MCP 或 REST 端点 * **Docker exec 进入容器** — 无 API 端点，使用 SSH 访问 VPS **其他一切都可以通过 MCP 工具获得**，包括：Redis、MariaDB、MongoDB、Compose、备份、通知、计划、回滚、SSO、补丁、组织等。 ## 常见陷阱有关详细解决方案，请参阅 [references/PITFALLS.md]()。问题 |原因 |修复 ---|---|--- `COPY /app/public` 失败 | Git 忽略空目录 | Dockerfile 中的“RUN mkdir -p public” 数据库连接错误 | Neon HTTP 驱动程序与标准 PG |使用 `postgres` (postgres.js) 包职员“publishableKey”失踪 | SSG 在构建时验证环境 | `export const dynamic = "force-dynamic"` \+ 在构建阶段跳过提供程序 migrate.mjs 导致容器崩溃 |独立输出缺少模块|通过应用内 API 端点运行迁移无法通过 API 获取构建日志 |仅 WebSocket，无 REST |检查仪表板 UI 或轮询“deployment.all”状态无法通过 API 获取容器日志 |仅限 WebSocket |使用仪表板用户界面外部数据库端口无法访问 | VPS 防火墙阻止端口 |使用内部 Docker 网络名称来自curl 的SSL 证书错误|自签名或 Let's Encrypt 延迟 |使用“curl -sk”或等待证书配置部署后 API 路由上出现 404 |路线不在独立输出中 |验证路由存在于“.next/standalone”中 Traefik 中间件升级后损坏 | Dokploy v0.25+ 使用 Traefik v3 |更新中间件配置语法 ## 构建类型 Dokploy 支持：类型 |何时使用 ---|--- **Dockerfile** |定制构建、多阶段、完全控制 **Nixpacks** |自动检测语言，零配置 **构建包** | Heroku/Paketo 兼容应用程序 **Docker 镜像** |来自注册表的预构建映像 ## 服务（数据库）通过仪表板→项目→添加服务创建： * **PostgreSQL** — 内部主机名：`:5432` * **MySQL/MariaDB** — 内部主机名：`:3306` * **MongoDB** — 内部主机名：`:27017` * **Redis** — 内部主机名：`:6379` 内部主机名使用 Docker 网络。外部端口可选（可能需要防火墙规则）。 ## 域名和 SSL 1.通过仪表板或API添加域（`domain.create`） 2. 将 DNS A 记录指向 VPS IP 3. Dokploy 自动配置 Let's Encrypt 通过 Traefik v3 证书 4. HTTPS 在 DNS 传播后自动工作 ## Next.js 具体指南有关将 Next.js 14/15 部署到 Dokploy 的完整详细信息，请参阅 [references/NEXTJS-GUIDE.md]()。

Dokploy Api MCP

包含技能