dokploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dokploy Infrastructure Management

Dokploy基础设施管理

Dokploy is a self-hosted PaaS. All management happens through its REST API using curl. No CLI tools or bash scripts — construct curl commands directly.

Dokploy是一款自托管PaaS，所有管理操作都通过curl调用其REST API完成，无需CLI工具或bash脚本，直接构造curl命令即可。

Authentication & Request Pattern

认证与请求规则

Environment variables (must be set):

```
DOKPLOY_API_URL
```
— base URL of the Dokploy instance (e.g.,
```
https://dokploy.example.com
```
)
```
DOKPLOY_API_KEY
```
— API token generated from Dokploy UI: Settings → Profile → API/CLI Section

All endpoints follow the pattern:

$DOKPLOY_API_URL/api/{router}.{procedure}

环境变量（必须提前配置）：

```
DOKPLOY_API_URL
```
— Dokploy实例的基础地址（例如：
```
https://dokploy.example.com
```
）
```
DOKPLOY_API_KEY
```
— 在Dokploy UI中生成的API令牌：设置 → 个人资料 → API/CLI板块

所有接口的地址规则为：

$DOKPLOY_API_URL/api/{router}.{procedure}

GET request (reads)

GET请求（查询操作）

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/{endpoint}?{param}={value}"

Parameters are flat query params. Do NOT use tRPC

?input=

encoding — it doesn't work on the OpenAPI surface.

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/{endpoint}?{param}={value}"

参数为扁平的查询参数，不要使用tRPC的

?input=

编码格式，OpenAPI层面不支持该格式。

POST request (all mutations)

POST请求（所有变更操作）

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/{endpoint}" \
  -d '{"param": "value"}'

Every mutation (create, update, remove, deploy, start, stop, reload) uses POST. Never use PUT, PATCH, or DELETE.

Always pipe output through

jq

for readability:

| jq .

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/{endpoint}" \
  -d '{"param": "value"}'

所有变更操作（创建、更新、删除、部署、启动、停止、重载）都使用POST请求，不要使用PUT、PATCH或DELETE方法。

建议始终将输出通过

jq

处理提升可读性：

| jq .

Response Formats

响应格式

Not all endpoints return JSON objects. Be aware of these patterns:

application.update
, application.saveEnvironment
, and other mutation endpoints may return a bare
```
true
```
instead of the updated object. Do not pipe these through
```
jq
```
with object filters — use
```
jq .
```
or skip
```
jq
```
entirely.
application.deploy
returns empty output on success.
GET endpoints (
```
*.one
```
,
```
*.all
```
) return full JSON objects.
When in doubt, don't assume the response shape — capture raw output first.

并非所有接口都返回JSON对象，请注意以下规则：

application.update
、**
```
application.saveEnvironment
```
**以及其他变更类接口可能直接返回布尔值
```
true
```
，而非更新后的对象。不要对这类响应使用带对象筛选规则的
```
jq
```
命令，可使用
```
jq .
```
或者直接跳过
```
jq
```
处理。
application.deploy
调用成功时返回空内容。
GET接口（
```
*.one
```
、
```
*.all
```
）返回完整的JSON对象。
存疑时不要假设响应结构，优先先获取原始输出。

Critical: The Resource Hierarchy

重点：资源层级结构

Project
  └── Environment (default: "production")
        ├── Applications
        ├── Databases (postgres, mysql, mariadb, mongo, redis)
        └── Compose services

Every project has at least one environment. The default is named "production" with
```
isDefault: true
```
.
Creating any resource requires
environmentId
, NOT
projectId
.
To get
```
environmentId
```
: fetch the project with
```
project.one
```
, then read
```
.environments[0].environmentId
```
(or find the environment by name).

This is the most common source of errors. Always fetch the environment first.

项目
  └── 环境（默认："production"）
        ├── 应用
        ├── 数据库（postgres, mysql, mariadb, mongo, redis）
        └── Compose服务

每个项目至少包含一个环境，默认环境名为"production"，对应
```
isDefault: true
```
。
创建任意资源都需要传入
environmentId
，而非
projectId
。
获取
```
environmentId
```
的方法：调用
```
project.one
```
查询项目信息，然后读取
```
.environments[0].environmentId
```
（或按环境名称查找对应ID）。

这是最常见的错误来源，务必优先查询获取环境ID。

Quick Reference

快速参考

Projects & Environments

项目与环境

Task	Endpoint	Method	Key Params
List all projects	`project.all`	GET	—
Get project details	`project.one`	GET	`projectId`
Create project	`project.create`	POST	`name` , `description`
Update project	`project.update`	POST	`projectId` , `name` , `description`
Delete project	`project.remove`	POST	`projectId`

任务	接口	请求方法	核心参数
查询所有项目	`project.all`	GET	—
获取项目详情	`project.one`	GET	`projectId`
创建项目	`project.create`	POST	`name` , `description`
更新项目	`project.update`	POST	`projectId` , `name` , `description`
删除项目	`project.remove`	POST	`projectId`

Applications

应用

Task	Endpoint	Method	Key Params
Get app details	`application.one`	GET	`applicationId`
Create app	`application.create`	POST	`name` , `environmentId`
Update app	`application.update`	POST	`applicationId` , ...
Delete app	`application.delete`	POST	`applicationId`
Deploy app	`application.deploy`	POST	`applicationId`
Start app	`application.start`	POST	`applicationId`
Stop app	`application.stop`	POST	`applicationId`
Redeploy app	`application.redeploy`	POST	`applicationId`
Save env vars	`application.saveEnvironment`	POST	`applicationId` , `env` , `buildArgs` , `buildSecrets` , `createEnvFile`
Set build type	`application.saveBuildType`	POST	`applicationId` , `buildType` , ...

任务	接口	请求方法	核心参数
获取应用详情	`application.one`	GET	`applicationId`
创建应用	`application.create`	POST	`name` , `environmentId`
更新应用	`application.update`	POST	`applicationId` , ...
删除应用	`application.delete`	POST	`applicationId`
部署应用	`application.deploy`	POST	`applicationId`
启动应用	`application.start`	POST	`applicationId`
停止应用	`application.stop`	POST	`applicationId`
重新部署应用	`application.redeploy`	POST	`applicationId`
保存环境变量	`application.saveEnvironment`	POST	`applicationId` , `env` , `buildArgs` , `buildSecrets` , `createEnvFile`
设置构建类型	`application.saveBuildType`	POST	`applicationId` , `buildType` , ...

Databases

数据库

All database types share the same operation pattern. Replace

{type}

with:

postgres

mysql

mariadb

mongo

redis

Task	Endpoint	Method	Key Params
Get DB details	`{type}.one`	GET	`{type}Id`
Create DB	`{type}.create`	POST	`name` , `environmentId` , `databasePassword` , ...
Delete DB	`{type}.remove`	POST	`{type}Id`
Deploy DB	`{type}.deploy`	POST	`{type}Id`
Start DB	`{type}.start`	POST	`{type}Id`
Stop DB	`{type}.stop`	POST	`{type}Id`

Note: Each type uses its own ID field name:

postgresId

mysqlId

mariadbId

mongoId

redisId

所有数据库类型的操作规则一致，将

{type}

替换为对应类型：

postgres

、

mysql

、

mariadb

、

mongo

、

redis

。

任务	接口	请求方法	核心参数
获取数据库详情	`{type}.one`	GET	`{type}Id`
创建数据库	`{type}.create`	POST	`name` , `environmentId` , `databasePassword` , ...
删除数据库	`{type}.remove`	POST	`{type}Id`
部署数据库	`{type}.deploy`	POST	`{type}Id`
启动数据库	`{type}.start`	POST	`{type}Id`
停止数据库	`{type}.stop`	POST	`{type}Id`

注意：每种数据库类型使用独立的ID字段名：

postgresId

、

mysqlId

、

mariadbId

、

mongoId

、

redisId

。

Domains

域名

Task	Endpoint	Method	Key Params
Get domain	`domain.one`	GET	`domainId`
Domains for app	`domain.byApplicationId`	GET	`applicationId`
Create domain	`domain.create`	POST	`host` , `applicationId` , `port`
Update domain	`domain.update`	POST	`domainId` , `host` , ...
Delete domain	`domain.delete`	POST	`domainId`

任务	接口	请求方法	核心参数
获取域名详情	`domain.one`	GET	`domainId`
查询应用绑定的域名	`domain.byApplicationId`	GET	`applicationId`
创建域名	`domain.create`	POST	`host` , `applicationId` , `port`
更新域名	`domain.update`	POST	`domainId` , `host` , ...
删除域名	`domain.delete`	POST	`domainId`

Compose

Task	Endpoint	Method	Key Params
Get compose	`compose.one`	GET	`composeId`
Create compose	`compose.create`	POST	`name` , `environmentId`
Update compose	`compose.update`	POST	`composeId` , ...
Delete compose	`compose.delete`	POST	`composeId` , `deleteVolumes`
Deploy compose	`compose.deploy`	POST	`composeId`
Start compose	`compose.start`	POST	`composeId`
Stop compose	`compose.stop`	POST	`composeId`
List services	`compose.loadServices`	GET	`composeId`

任务	接口	请求方法	核心参数
获取Compose详情	`compose.one`	GET	`composeId`
创建Compose	`compose.create`	POST	`name` , `environmentId`
更新Compose	`compose.update`	POST	`composeId` , ...
删除Compose	`compose.delete`	POST	`composeId` , `deleteVolumes`
部署Compose	`compose.deploy`	POST	`composeId`
启动Compose	`compose.start`	POST	`composeId`
停止Compose	`compose.stop`	POST	`composeId`
列出服务	`compose.loadServices`	GET	`composeId`

Deployments

部署记录

Task	Endpoint	Method	Key Params
List deployments	`deployment.all`	GET	`applicationId`
By type	`deployment.allByType`	GET	`id` , `type`

type

values:

application

compose

server

schedule

previewDeployment

backup

volumeBackup

任务	接口	请求方法	核心参数
列出部署记录	`deployment.all`	GET	`applicationId`
按类型查询部署记录	`deployment.allByType`	GET	`id` , `type`

type

可选值：

application

、

compose

、

server

、

schedule

、

previewDeployment

、

backup

、

volumeBackup

Servers

服务器

Task	Endpoint	Method	Key Params
List servers	`server.all`	GET	—
Get server	`server.one`	GET	`serverId`
Create server	`server.create`	POST	`name` , `ipAddress` , `port` , `username` , `sshKeyId`
Delete server	`server.remove`	POST	`serverId`

任务	接口	请求方法	核心参数
列出服务器	`server.all`	GET	—
获取服务器详情	`server.one`	GET	`serverId`
创建服务器	`server.create`	POST	`name` , `ipAddress` , `port` , `username` , `sshKeyId`
删除服务器	`server.remove`	POST	`serverId`

Common Workflows

常见工作流

List all projects with their resources

列出所有项目及其关联资源

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" | jq .

The response includes nested environments with all applications, databases, and compose services summarized.

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" | jq .

响应包含嵌套的环境信息，以及所有应用、数据库、Compose服务的汇总信息。

Deploy an existing application

部署已有的应用

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.deploy" \
  -d '{"applicationId": "THE_APP_ID"}' | jq .

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.deploy" \
  -d '{"applicationId": "THE_APP_ID"}' | jq .

Create a new app in an existing project

在现有项目中创建新应用

Step 1 — Get the project's environmentId:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.one?projectId=PROJECT_ID" \
  | jq '.environments[] | select(.isDefault) | .environmentId'

Step 2 — Create the application:

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.create" \
  -d '{"name": "my-app", "environmentId": "ENV_ID"}' | jq .

步骤1 — 获取项目的environmentId：

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.one?projectId=PROJECT_ID" \
  | jq '.environments[] | select(.isDefault) | .environmentId'

步骤2 — 创建应用：

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.create" \
  -d '{"name": "my-app", "environmentId": "ENV_ID"}' | jq .

Create a full project from scratch

从零创建完整项目

Step 1 — Create the project:

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/project.create" \
  -d '{"name": "My Project", "description": "Project description"}' | jq .

Step 2 — Get the new project's environmentId from the response, or fetch it:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" \
  | jq '.[] | select(.name == "My Project") | .environments[0].environmentId'

Step 3 — Create resources using that environmentId (apps, databases, compose).

步骤1 — 创建项目：

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/project.create" \
  -d '{"name": "My Project", "description": "Project description"}' | jq .

步骤2 — 从响应中获取新项目的environmentId，或通过查询获取：

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" \
  | jq '.[] | select(.name == "My Project") | .environments[0].environmentId'

步骤3 — 使用该environmentId创建相关资源（应用、数据库、Compose）。

Check deployment status

查看部署状态

For applications:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.all?applicationId=APP_ID" | jq '.[0]'

For compose services:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.allByType?id=COMPOSE_ID&type=compose" | jq '.[0]'

应用部署状态：

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.all?applicationId=APP_ID" | jq '.[0]'

Compose服务部署状态：

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.allByType?id=COMPOSE_ID&type=compose" | jq '.[0]'

Set environment variables on an app

为应用设置环境变量

Env vars are set as a single newline-separated string block, not key-value pairs.

Required fields:

buildArgs

buildSecrets

, and

createEnvFile

are mandatory (use empty strings and

false

as defaults):

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.saveEnvironment" \
  -d '{
    "applicationId": "APP_ID",
    "env": "DATABASE_URL=postgres://...\nREDIS_URL=redis://...\nNODE_ENV=production",
    "buildArgs": "",
    "buildSecrets": "",
    "createEnvFile": false
  }'

环境变量以换行分隔的字符串块形式传入，而非键值对格式。

必填字段：

buildArgs

、

buildSecrets

和

createEnvFile

为必填项（默认可传入空字符串和

false

）：

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.saveEnvironment" \
  -d '{
    "applicationId": "APP_ID",
    "env": "DATABASE_URL=postgres://...\nREDIS_URL=redis://...\nNODE_ENV=production",
    "buildArgs": "",
    "buildSecrets": "",
    "createEnvFile": false
  }'

Important Notes

重要注意事项

```
project.all
```
returns a comprehensive overview — use it to discover IDs before drilling down.
Deployment is asynchronous. After triggering deploy, poll
```
deployment.all
```
or
```
deployment.allByType
```
to check status.
Destructive operations (
```
remove
```
,
```
delete
```
) cannot be undone. Always confirm with the user first.
The Swagger UI is available at
```
$DOKPLOY_API_URL/swagger
```
for interactive API exploration (admin only).

```
project.all
```
返回全面的概览信息，在查询具体资源前可先调用该接口获取对应ID。
部署为异步操作，触发部署后，可轮询
```
deployment.all
```
或
```
deployment.allByType
```
接口查看状态。
破坏性操作（
```
remove
```
、
```
delete
```
）无法撤销，执行前务必先和用户确认。
Swagger UI地址为
```
$DOKPLOY_API_URL/swagger
```
，可用于交互式接口调试（仅管理员可访问）。

Reference Files

参考文件

For full endpoint details with all parameters:

Need details about...	Read
Projects & environments	`references/api-projects.md`
Applications (CRUD, deploy, build types, git providers)	`references/api-applications.md`
Databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis)	`references/api-databases.md`
Domains (create, update, certificates)	`references/api-domains.md`
Docker Compose services	`references/api-compose.md`
Deployment history & logs	`references/api-deployments.md`
Server management	`references/api-servers.md`

如需查看所有参数的完整接口说明：

需要了解的内容	参考文档
项目与环境	`references/api-projects.md`
应用（CRUD、部署、构建类型、Git提供商）	`references/api-applications.md`
数据库（PostgreSQL、MySQL、MariaDB、MongoDB、Redis）	`references/api-databases.md`
域名（创建、更新、证书）	`references/api-domains.md`
Docker Compose服务	`references/api-compose.md`
部署历史与日志	`references/api-deployments.md`
服务器管理	`references/api-servers.md`