Dokploy v0.30.8 常用 CLI 命令与工具详解

目标：完整讲解 Dokploy v0.30.8 的两套命令行工具面——官方 CLI（npm 包 @dokploy/cli）与服务器侧 Docker Compose/Swarm 运维命令。涵盖 CLI 安装、认证、全量命令树、project/postgres/swarm/settings 四个高频命令组的逐参数讲解与真实回显，以及限速、版本差异等排障实录。全部命令均在 Ubuntu 24.04 实测执行，回显逐行照抄。

一、环境信息

项目	值
面板服务器操作系统	Ubuntu 24.04（x86_64）
面板服务器 Docker / Compose	29.8.0 / v5.5.1
Dokploy 服务端版本	v0.30.8
CLI 版本	@dokploy/cli 0.30.7（npm 仓库当前最新，查询日期 2026-10-21）
运维机 Node.js / npm	v22.23.3 / 10.9.9
面板地址	http://192.168.146.128:8129（示例环境；官方默认部署面板监听 3000，认证时填实际可访问地址即可）
部署形态	Docker Compose 编排（项目 `dokploy-v0308-stack`），Swarm 单管理节点
实测日期	2026-10-21

面板的 Compose 部署过程见本专栏《Dokploy Docker Compose 部署指南》（https://www.quzuo.net/document/sQz2z32P5Jec），配置参数细节见[《Dokploy v0.30.8 配置参数详解》](https://www.quzuo.net/document/p2gEgQo3sIBk)（https://www.quzuo.net/document/p2gEgQo3sIBk）。本文不依赖这两篇的正文内容，所有命令均可独立执行。

二、工具概览

Dokploy 的命令行运维面由两部分组成，分工如下：

工具面	载体	运行位置	适用场景
官方 CLI（`@dokploy/cli`）	npm 包，命令名 `dokploy`	任意可访问面板的 Linux 运维机	远程批量管理项目/数据库/域名/通知，脚本化与 CI 集成
Docker Compose / Swarm 命令	Docker 引擎自带	面板服务器本机	服务状态巡检、日志查看、组件健康自检、数据卷核对

关于官方 CLI 的几个关键事实（npm 仓库页面口径，查询日期 2026-10-21）：

CLI 自 Dokploy v0.29.0 起正式提供，与 MCP Server 同批发布；
命令由 Dokploy OpenAPI 规范自动生成，覆盖全部 API 端点（npm 页面标注 449 条子命令）；
CLI 版本号与服务端版本号独立演进，安装时建议尽量对齐服务端版本（对齐注意事项见第七节）。

CLI 与面板/API 的关系：CLI 是面板 REST API 的命令行封装，认证走 API Key，因此 CLI 能做的面板都能做；CLI 的价值在于免登录、可脚本、可纳入 CI。需要直接调 HTTP 接口的场景（如自建监控拉数据）可绕过 CLI 直接用 API Key 请求 /api/<procedure> 端点。

技术拓展说明：npm 包有三种常见使用方式，选型对比如下。本文实测采用「项目本地安装」。

方式	命令	优点	缺点	适用
全局安装	`npm install -g @dokploy/cli`	任意目录可直接敲 `dokploy`	升级影响全局；认证文件落在全局 node_modules 内	运维机专用机
项目本地安装	`npm install @dokploy/cli`	版本随项目锁定，可纳入 Git 管理	需经 `./node_modules/.bin/dokploy` 或 npx 调用	脚本仓库、CI
免安装直跑	`npx @dokploy/cli <cmd>`	不落盘、临时使用	每次解析包有等待；认证文件位置随 npx 缓存变化	偶尔排查

三、前置条件

面板已部署且可访问（部署方法见《Dokploy Docker Compose 部署指南》）。运维机连通性自检（Node.js 原生 fetch，实测）：

node -e "fetch('http://192.168.146.128:8129/').then(r => console.log('HTTP', r.status))"

实测回显：

HTTP 200

运维机已安装 Node.js（含 npm）。实测版本：

node --version && npm --version

实测回显：

v22.23.3
10.9.9

已在面板创建 API Key：登录面板 → 右上角头像 → 「API Keys」→ 新建。创建后立即复制保存（面板只展示一次）。注意默认每个 Key 限速 10 次请求 / 24 小时，CLI 每执行一条涉及 API 的命令即消耗一次，批量脚本前建议先调大限额（参数含义与修改方式见《Dokploy v0.30.8 配置参数详解》第 5.7 节）。

四、CLI 安装与认证

4.1 安装

在运维机选一个工作目录执行本地安装：

mkdir -p /opt/dokploy-cli && cd /opt/dokploy-cli && npm init -y && npm install @dokploy/cli

实测回显（安装完成段）：

7 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

确认版本：

./node_modules/.bin/dokploy -V

实测回显：

0.30.7

4.2 首次认证（auth）

查看 auth 用法：

./node_modules/.bin/dokploy auth --help

实测回显：

Usage: dokploy auth [options]

Authenticate with your Dokploy server

Options:
  -u, --url <url>      Server URL (e.g., https://panel.dokploy.com)
  -t, --token <token>  API key from your Dokploy dashboard
  -h, --help           display help for command

参数说明：

参数	含义	取值
`-u, --url`	面板访问地址	本文示例为 `http://192.168.146.128:8129`，以实际部署为准
`-t, --token`	面板生成的 API Key	第三步创建的 Key 值

token 属敏感值，建议经环境变量注入而不是落在 shell 历史：

read -s DOKPLOY_TOKEN    # 粘贴 API Key 后回车（输入不回显）
./node_modules/.bin/dokploy auth -u http://192.168.146.128:8129 -t "$DOKPLOY_TOKEN"

实测回显（Key 有效时）：

Validating credentials...
Authenticated successfully.

Key 无效时的实测回显（后面 FAQ 一节有完整排障）：

Validating credentials...
Authentication failed: Request failed with status code 401

4.3 认证存储位置与内容

认证成功后凭据落在 CLI 包目录下的 config.json。位置随安装方式不同：

项目本地安装：<项目目录>/node_modules/@dokploy/cli/config.json
全局安装：<npm 全局前缀>/node_modules/@dokploy/cli/config.json（可用 npm root -g 查前缀）

查看文件内容（token 为敏感值，回显隐去中间段）：

cat node_modules/@dokploy/cli/config.json

实测回显：

{
  "url": "http://192.168.146.128:8129",
  "token": "hRnoyXgJvymAtrvv…（64 位完整值此处隐去）"
}

文件为明文 JSON，建议收敛权限：

chmod 600 node_modules/@dokploy/cli/config.json

另注意：npm install 重装/升级 CLI 包会重建 node_modules，config.json 随之丢失，需重新执行 dokploy auth；脚本化场景推荐改用 4.4 的环境变量方式，凭据与包生命周期解耦。

4.4 环境变量认证（免 config.json）

CLI 支持两个环境变量：DOKPLOY_URL（面板地址）与 DOKPLOY_AUTH_TOKEN（API Key）。不落配置文件直接执行：

export DOKPLOY_URL="http://192.168.146.128:8129"
export DOKPLOY_AUTH_TOKEN="$DOKPLOY_TOKEN"
./node_modules/.bin/dokploy settings get-release-tag

实测回显：

latest

两处都没有凭据时的实测报错：

No configuration found. Please run 'dokploy auth' first or set DOKPLOY_URL and DOKPLOY_AUTH_TOKEN environment variables.

优先级：环境变量与 config.json 同时存在时以环境变量为准，可用这一点在不改动配置文件的前提下临时切换目标面板。

4.5 全量命令树

./node_modules/.bin/dokploy --help

实测回显（完整）：

Usage: dokploy [options] [command]

Dokploy CLI - Manage your Dokploy server

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  auth [options]      Authenticate with your Dokploy server
  admin               admin commands
  ai                  ai commands
  application         application commands
  audit-log           audit-log commands
  backup              backup commands
  bitbucket           bitbucket commands
  certificates        certificates commands
  cluster             cluster commands
  compose             compose commands
  custom-role         custom-role commands
  deployment          deployment commands
  destination         destination commands
  dns-provider        dns-provider commands
  docker              docker commands
  docker-disk-usage   docker-disk-usage commands
  docker-image        docker-image commands
  docker-volume       docker-volume commands
  domain              domain commands
  environment         environment commands
  forward-auth        forward-auth commands
  gitea               gitea commands
  github              github commands
  gitlab              gitlab commands
  git-provider        git-provider commands
  libsql              libsql commands
  license-key         license-key commands
  mariadb             mariadb commands
  mongo               mongo commands
  mounts              mounts commands
  mysql               mysql commands
  network             network commands
  notification        notification commands
  organization        organization commands
  overview            overview commands
  patch               patch commands
  port                port commands
  postgres            postgres commands
  preview-deployment  preview-deployment commands
  project             project commands
  redirects           redirects commands
  redis               redis commands
  registry            registry commands
  rollback            rollback commands
  schedule            schedule commands
  scim                scim commands
  security            security commands
  server              server commands
  settings            settings commands
  ssh-key             ssh-key commands
  sso                 sso commands
  stripe              stripe commands
  swarm               swarm commands
  tag                 tag commands
  user                user commands
  vault-provider      vault-provider commands
  volume-backups      volume-backups commands
  whitelabeling       whitelabeling commands

规律说明：除 auth 外全部是「命令组」，每组下再挂子命令；任意层级追加 --help 可查看该组用法；列表查询类子命令普遍支持 --json 输出原始 JSON，便于 jq 加工。

五、常用命令组详解

5.1 project 组（项目）

./node_modules/.bin/dokploy project --help

实测回显：

Usage: dokploy project [options] [command]

project commands

Options:
  -h, --help                     display help for command

Commands:
  all [options]                  project all
  all-for-permissions [options]  project allForPermissions
  complete-onboarding [options]  project completeOnboarding
  create [options]               project create
  duplicate [options]            project duplicate
  home-stats [options]           project homeStats
  onboarding-status [options]    project onboardingStatus
  one [options]                  project one
  remove [options]               project remove
  search [options]               project search
  update [options]               project update
  help [command]                 display help for command

最常用的是 project all（列出全部项目及其环境、资源清单），也是获取各类资源 ID 的入口：

./node_modules/.bin/dokploy project all

实测回显：

[
  {
    "projectId": "lK-c-eufIbhAuR_kWd4l0",
    "name": "demo",
    "description": "lab demo",
    "createdAt": "2026-10-21T07:24:26.713Z",
    "organizationId": "avblv0QFJO6M1qqNqBITg",
    "env": "",
    "environments": [
      {
        "name": "production",
        "environmentId": "ihjuHNzTNxuJHgtJ3a0D3",
        "isDefault": true,
        "applications": [],
        "mariadb": [],
        "mongo": [],
        "mysql": [],
        "postgres": [
          {
            "postgresId": "hcgREDx_xW3iURXKacig7"
          }
        ],
        "redis": [],
        "compose": [],
        "libsql": []
      }
    ],
    "projectTags": []
  }
]

project one 查询单个项目详情，参数 --projectId（从 project all 回显中取）：

./node_modules/.bin/dokploy project one --help

实测回显：

Usage: dokploy project one [options]

project one

Options:
  --projectId <value>  projectId
  --json               Output raw JSON
  -h, --help           display help for command

其余子命令按 create --name <名称> --description <描述>、remove --projectId <id> 等形式调用，参数名以各子命令 --help 输出为准。

5.2 postgres 组（PostgreSQL 数据库编排）

./node_modules/.bin/dokploy postgres --help

实测回显：

Usage: dokploy postgres [options] [command]

postgres commands

Options:
  -h, --help                    display help for command

Commands:
  change-password [options]     postgres changePassword
  change-status [options]       postgres changeStatus
  create [options]              postgres create
  deploy [options]              postgres deploy
  move [options]                postgres move
  one [options]                 postgres one
  read-logs [options]           postgres readLogs
  rebuild [options]             postgres rebuild
  reload [options]              postgres reload
  remove [options]              postgres remove
  save-environment [options]    postgres saveEnvironment
  save-external-port [options]  postgres saveExternalPort
  search [options]              postgres search
  start [options]               postgres start
  stop [options]                postgres stop
  update [options]              postgres update
  help [command]                display help for command

核心操作链：create 建库定义 → deploy 触发部署 → one/read-logs 查状态与日志 → stop/start/reload/remove 生命周期管理。deploy 与 one 的必填参数都是 --postgresId（驼峰命名）：

./node_modules/.bin/dokploy postgres deploy --help
./node_modules/.bin/dokploy postgres one --help

实测回显：

Usage: dokploy postgres deploy [options]

postgres deploy

Options:
  --postgresId <value>  postgresId
  --json                Output raw JSON
  -h, --help            display help for command

Usage: dokploy postgres one [options]

postgres one

Options:
  --postgresId <value>  postgresId
  --json                Output raw JSON
  -h, --help            display help for command

漏传必填参数时是客户端校验直接报错（不消耗 API 请求）：

./node_modules/.bin/dokploy postgres one

实测回显：

error: required option '--postgresId <value>' not specified

mysql/mariadb/mongo/redis/libsql 组与 postgres 组结构完全一致，仅资源 ID 参数名对应变化（--mysqlId、--mariadbId、--mongoId、--redisId、--libsqlId）。

5.3 swarm 组（Swarm 集群信息）

./node_modules/.bin/dokploy swarm --help

实测回显：

Usage: dokploy swarm [options] [command]

swarm commands

Options:
  -h, --help                     display help for command

Commands:
  get-container-stats [options]  swarm getContainerStats
  get-node-apps [options]        swarm getNodeApps
  get-node-info [options]        swarm getNodeInfo
  get-nodes [options]            swarm getNodes
  help [command]                 display help for command

各子命令参数：

./node_modules/.bin/dokploy swarm get-nodes --help
./node_modules/.bin/dokploy swarm get-node-info --help
./node_modules/.bin/dokploy swarm get-container-stats --help

实测回显：

Usage: dokploy swarm get-nodes [options]

swarm getNodes

Options:
  --serverId <value>  serverId
  --json              Output raw JSON
  -h, --help          display help for command

Usage: dokploy swarm get-node-info [options]

swarm getNodeInfo

Options:
  --nodeId <value>    nodeId
  --serverId <value>  serverId
  --json              Output raw JSON
  -h, --help          display help for command

Usage: dokploy swarm get-container-stats [options]

swarm getContainerStats

Options:
  --serverId <value>  serverId
  --json              Output raw JSON
  -h, --help          display help for command

实测排障记录：本环境（CLI 0.30.7 + 服务端 v0.30.8）下 swarm get-nodes 无论是否带 --serverId 0 均返回：

Request failed with status code 400

同组合下 project all、settings get-* 等命令正常，判断为该子命令在当前版本组合下的兼容问题（详见第七节版本对齐与第八节 FAQ）。遇到此类 400 时，面板「Swarm」页与服务器本机 docker node ls（见 6.1 节）可作为替代取数路径。

5.4 settings 组（平台设置）

settings 是子命令最多的一组（51 条），覆盖版本查询、Traefik 配置读写、磁盘清理、健康检查等平台级操作：

./node_modules/.bin/dokploy settings --help

实测回显（完整）：

Usage: dokploy settings [options] [command]

settings commands

Options:
  -h, --help                                     display help for command

Commands:
  assign-domain-server [options]                 settings assignDomainServer
  check-gpustatus [options]                      settings checkGPUStatus
  check-infrastructure-health [options]          settings checkInfrastructureHealth
  clean-all [options]                            settings cleanAll
  clean-all-deployment-queue [options]           settings cleanAllDeploymentQueue
  clean-docker-builder [options]                 settings cleanDockerBuilder
  clean-docker-prune [options]                   settings cleanDockerPrune
  clean-monitoring [options]                     settings cleanMonitoring
  clean-sshprivate-key [options]                 settings cleanSSHPrivateKey
  clean-stopped-containers [options]             settings cleanStoppedContainers
  clean-unused-images [options]                  settings cleanUnusedImages
  clean-unused-volumes [options]                 settings cleanUnusedVolumes
  get-docker-disk-usage [options]                settings getDockerDiskUsage
  get-dokploy-cloud-ips [options]                settings getDokployCloudIps
  get-dokploy-version [options]                  settings getDokployVersion
  get-ip [options]                               settings getIp
  get-log-cleanup-status [options]               settings getLogCleanupStatus
  get-open-api-document [options]                settings getOpenApiDocument
  get-release-tag [options]                      settings getReleaseTag
  get-traefik-ports [options]                    settings getTraefikPorts
  get-update-data [options]                      settings getUpdateData
  get-web-server-settings [options]              settings getWebServerSettings
  have-activate-requests [options]               settings haveActivateRequests
  have-traefik-dashboard-port-enabled [options]  settings haveTraefikDashboardPortEnabled
  health [options]                               settings health
  is-cloud [options]                             settings isCloud
  is-user-subscribed [options]                   settings isUserSubscribed
  read-directories [options]                     settings readDirectories
  read-middleware-traefik-config [options]       settings readMiddlewareTraefikConfig
  read-traefik-config [options]                  settings readTraefikConfig
  read-traefik-env [options]                     settings readTraefikEnv
  read-traefik-file [options]                    settings readTraefikFile
  read-web-server-traefik-config [options]       settings readWebServerTraefikConfig
  reload-server [options]                        settings reloadServer
  reload-traefik [options]                       settings reloadTraefik
  save-sshprivate-key [options]                  settings saveSSHPrivateKey
  setup-gpu [options]                            settings setupGPU
  toggle-dashboard [options]                     settings toggleDashboard
  toggle-requests [options]                      settings toggleRequests
  update-builds-concurrency [options]            settings updateBuildsConcurrency
  update-docker-cleanup [options]                settings updateDockerCleanup
  update-enforce-sso [options]                   settings updateEnforceSSO
  update-log-cleanup [options]                   settings updateLogCleanup
  update-middleware-traefik-config [options]     settings updateMiddlewareTraefikConfig
  update-remote-servers-only [options]           settings updateRemoteServersOnly
  update-server [options]                        settings updateServer
  update-server-ip [options]                     settings updateServerIp
  update-traefik-config [options]                settings updateTraefikConfig
  update-traefik-file [options]                  settings updateTraefikFile
  update-traefik-ports [options]                 settings updateTraefikPorts
  update-web-server-traefik-config [options]     settings updateWebServerTraefikConfig
  write-traefik-env [options]                    settings writeTraefikEnv
  help [command]                                 display help for command

高频子命令实测：

./node_modules/.bin/dokploy settings get-dokploy-version

实测回显：

v0.30.8

./node_modules/.bin/dokploy settings get-release-tag

实测回显：

latest

get-dokploy-version 返回服务端实际版本，与 dokploy -V（CLI 自身版本）配合即可核对两端版本差，这条检查建议纳入升级前后例行动作。clean-* 系列为破坏性清理操作（清构建缓存/未用镜像/未用卷等），生产环境执行前先评估。

5.5 其余命令组速查

按 --help 输出顺序，其余命令组的用途速查（每组下子命令均为「组名动词化」风格，细节用 <组> --help 查看）：

命令组	用途
admin / organization / user / custom-role / audit-log / scim / sso / forward-auth	管理员、组织与用户体系、自定义角色、审计、企业身份接入（SCIM/SSO/转发认证）
ai	AI 辅助分析（日志/构建错误诊断）
application / compose / deployment / preview-deployment / rollback	应用与编排部署的创建、部署记录、预览环境与版本回滚
mariadb / mongo / mysql / postgres / redis / libsql	六类数据库托管编排（结构与 5.2 postgres 组一致）
backup / volume-backups / destination	数据库备份、卷备份及备份存储目标
certificates / domain / redirects / port	证书、域名、重定向与端口管理
cluster / docker / docker-disk-usage / docker-image / docker-volume / network / overview	集群与 Docker 资源查询（磁盘/镜像/卷/网络/总览）
mounts / schedule / security / patch	挂载、计划任务、安全配置、补丁通道
gitea / github / gitlab / git-provider / bitbucket	代码仓库接入（含共享 Git Provider）
notification	通知渠道（邮件/Slack/Telegram 等）
registry	镜像仓库凭据管理
server / ssh-key / dns-provider / vault-provider	远程服务器纳管、SSH 密钥、DNS 与 Vault 凭据源
settings / environment / project / tag	平台设置、环境、项目与标签
license-key / stripe / whitelabeling / is-cloud 相关	商业化与品牌化能力（云版/许可）

六、服务器侧 Docker Compose / Swarm 运维命令

以下命令在面板服务器本机执行（部署目录 /opt/dokploy/compose，即 docker-compose.yml 所在目录），用于 CLI 覆盖不到的本机巡检。

6.1 服务状态巡检

cd /opt/dokploy/compose && docker compose ps

实测回显：

NAME               IMAGE                                                                     COMMAND                  SERVICE            CREATED          STATUS                    PORTS
dokploy            dokploy/dokploy:v0.30.8                                                   "/usr/bin/tini -- sh…"   dokploy            48 minutes ago   Up 22 minutes (healthy)   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
dokploy-postgres   sha256:8e011e58c789a89790269f53614a28a58cb02706ce74ba6d9d4171613d0b75e1   "docker-entrypoint.s…"   dokploy-postgres   48 minutes ago   Up 48 minutes             5432/tcp
dokploy-redis      redis:7                                                                   "docker-entrypoint.s…"   dokploy-redis      48 minutes ago   Up 48 minutes             6379/tcp
dokploy-traefik    traefik:v3.6.7                                                            "/entrypoint.sh trae…"   dokploy-traefik    47 minutes ago   Up 47 minutes             0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp, 0.0.0.0:443->443/udp, [::]:443->443/udp

重点看 dokploy 一行的 STATUS 是否为 Up ... (healthy)（面板内置健康检查为 curl -fs http://localhost:3000/api/trpc/settings.health，间隔 30 秒）。

列出 compose 项目内的服务清单：

docker compose config --services

实测回显：

dokploy-redis
dokploy-traefik
dokploy
dokploy-postgres

从 Swarm 视角核对被编排服务（通过面板部署的数据库会以 Swarm 服务形态出现）：

docker service ls --format "{{.Name}}\t{{.Replicas}}\t{{.Image}}"

实测回显（其中 postgres-back-up-virtual-alarm-amtzgf 为经面板「Project → PostgreSQL」部署生成的服务）：

postgres-back-up-virtual-alarm-amtzgf   1/1     postgres:16

6.2 日志查看

docker compose logs dokploy --tail 3

实测回显（截取自一次无效 API Key 调用后的日志，正好演示 401 在服务端的呈现）：

dokploy  | Error verifying API key Error: Invalid API key.
dokploy  |     at J (.next/server/chunks/3780.js:29:4683)
dokploy  |     at async Object.m [as createContext] (.next/server/chunks/6355.js:103:152052)

排查 CLI 报错时，先在本机日志里 grep 关键字（如 Error verifying API key、Rate limit），多数认证/限速问题在服务端日志的定位比 CLI 侧报错更直接。

6.3 组件健康自检与数据卷核对

docker exec dokploy-postgres pg_isready -U dokploy -d dokploy

实测回显：

/var/run/postgresql:5432 - accepting connections

docker exec dokploy-redis redis-cli ping

实测回显：

PONG

核对 compose 项目创建的命名卷（元数据与配置的持久化载体）：

docker volume ls --format "{{.Name}}" | grep dokploy

实测回显：

dokploy-v0308-stack_dokploy-docker-config
dokploy-v0308-stack_dokploy-postgres-data
dokploy-v0308-stack_dokploy-redis-data

三个卷分别承载 Docker 配置缓存、PostgreSQL 元数据、Redis 队列数据；备份策略（每日落盘位置）见《Dokploy v0.30.8 配置参数详解》生产配置模板一节。

七、注意事项

版本对齐：CLI 与服务端版本独立发布，实测时 npm 侧最新为 0.30.7、服务端为 v0.30.8。该组合下多数命令正常（认证、project all、settings get-*、数据库创建/部署均实测可用），但 project one、postgres one、swarm get-nodes 等详情查询类子命令实测返回 Request failed with status code 400。建议升级服务端后同步升级 CLI 到同版本号，并用 dokploy -V 与 dokploy settings get-dokploy-version 双向核对。
API Key 限速：默认每 Key 10 次请求 / 24 小时，超限后命令失败，服务端返回错误信息 Error: Rate limit exceeded.。CLI 每条涉及 API 的命令消耗一次限额，--help 类本地输出不消耗。批量脚本执行前先在面板调大限额；详情见《Dokploy v0.30.8 配置参数详解》第 5.7 节。
凭据明文落盘：config.json 以明文保存 API Key，且位于 node_modules 内，易被误提交或随目录泄露。务必 chmod 600，CI 场景改用 DOKPLOY_URL/DOKPLOY_AUTH_TOKEN 环境变量注入。
资源 ID 获取链路：CLI 各资源操作都需要资源 ID（如 --postgresId），ID 从 project all 的 JSON 回显中取（注意环境层级：资源挂在 project → environments 之下），配合 --json 参数与 jq 可脚本化提取。
400 排查路径：CLI 只回显状态码不回显错误体，先看面板服务器 docker compose logs dokploy 中对应时间的记录，再对照命令参数名（驼峰，如 --postgresId）与必填项。
客户端校验不消耗限额：required option ... not specified 类缺参报错发生在本地参数解析阶段，未发出请求，可放心重试。

八、常见问题

Q1：dokploy auth 提示 Authentication failed: Request failed with status code 401？

按顺序排查：① token 是否复制完整（面板只展示一次，漏字符最常见）；② url 是否为面板实际可访问地址（本例 http://192.168.146.128:8129）；③ 该 Key 是否已被删除或重建。服务端定位法：在面板服务器本机执行 docker compose logs dokploy --tail 50，若出现 Error verifying API key Error: Invalid API key. 即为 Key 无效，重新生成即可。另注意 0.30.x 版本存在「Key 未绑定组织上下文导致会话校验失败」的已知坑，创建 Key 时需在面板正常流程中生成，详见《Dokploy Docker Compose 部署指南》FAQ。

Q2：命令突然全部失败，提示限速？

服务端返回 Error: Rate limit exceeded.，即触发了默认 10 次/24 小时的 Key 限速。处理：等待限速窗口结束，或在面板 API Keys 设置中调大 rateLimitMax；已被限速的 Key 若需立即恢复，等待窗口自然重置即可（服务端侧的计数重置属运维操作，不在 CLI 能力范围内）。预防：脚本内串行调用并控制频率，高频场景单独创建大限额 Key。

Q3：报错 No configuration found. Please run 'dokploy auth' first or set DOKPLOY_URL and DOKPLOY_AUTH_TOKEN environment variables.？

运行目录下找不到凭据。三种可能：① 从未执行 dokploy auth；② npm install 重装/升级后 config.json 随 node_modules 被重建清掉；③ 在另一台机器/另一目录执行。按 4.2 或 4.4 重新提供凭据即可。

Q4：部分子命令返回 Request failed with status code 400，其他命令正常？

实测于 CLI 0.30.7 + 服务端 v0.30.8 组合，project one、postgres one、swarm get-nodes 复现，而 project all、settings get-*、数据库 create/deploy 正常——属于两端版本差异导致的个别接口不兼容。规避：详情类信息改从 project all 聚合回显取（其中已含各资源 ID 与项目结构），或升级 CLI 与服务端对齐后复测。

Q5：error: required option '--postgresId <value>' not specified 怎么解决？

漏传必填参数。参数名为驼峰（--postgresId 而非 --postgres-id），值从 dokploy project all 回显的对应资源条目中取。同类资源对应各自的 ID 参数（--mysqlId、--redisId 等），可用 dokploy <组> <子命令> --help 现查，避免凭记忆猜参数。

Q6：如何卸载/清理 CLI？

项目本地安装：删除项目目录即可（rm -rf /opt/dokploy-cli），凭据文件随 node_modules 一并清除。全局安装：npm uninstall -g @dokploy/cli，再手工确认全局 node_modules 下 @dokploy/cli 目录已不存在。CLI 的卸载不影响面板服务端任何数据；已发放的 API Key 建议在面板中一并吊销。

九、参考链接

CLI npm 包页（版本/命令规模口径来源）：https://www.npmjs.com/package/@dokploy/cli
官方 CLI 认证文档：https://docs.dokploy.com/docs/cli/authentication
官方文档总入口：https://docs.dokploy.com
CLI 能力发布公告（v0.29.0，CLI 与 MCP 同批引入）：https://dokploy.com/blog/v0-29-0-ai-powered-debugging-mcp-server-cli-shared-git-providers
代码仓库：https://github.com/Dokploy/dokploy
本专栏相关文章：