Dokploy Docker Compose 部署指南

目标：在一台 Ubuntu 24.04 服务器上，用 Docker Compose 编排官方四组件（dokploy 管理面板、dokploy-postgres 元数据库、dokploy-redis 队列缓存、dokploy-traefik 边缘代理）完成 Dokploy v0.30.8 的从零部署，覆盖 Swarm 初始化、Compose 编排、首启验证、数据持久化、环境变量、等价 docker run、日常运维与排障实录。全部命令与回显已在 Ubuntu 24.04（Docker 29.8.0 + Compose v5.5.1）实测通过。

一、环境信息

项目	值
操作系统	Ubuntu 24.04（x86_64）
Docker	29.8.0（`docker version` 实测）
Docker Compose	v5.5.1（`docker compose version` 实测）
Dokploy 版本	v0.30.8（镜像 `dokploy/dokploy:v0.30.8`）
数据库	postgres:16（官方脚本指定版本）
缓存队列	redis:7
边缘代理	traefik:v3.6.7（官方脚本锁定版本）
编排底座	Docker Swarm（单管理节点）
部署目录	/opt/dokploy/compose（项目名 `dokploy-v0.30.8-stack`）
配置目录	/etc/dokploy
端口	3000（面板）、80/443（Traefik HTTP/HTTPS）
示例服务器内网 IP	10.0.0.3（读者按实际服务器 IP 替换）

💡 说明：Dokploy 官方安装脚本以 Docker Swarm 服务形式部署组件（docker service create）；本文将官方脚本参数逐项等价转写为 Compose 文件，两者效果一致。Compose 部署前仍需初始化 Swarm，因为 Dokploy 编排用户应用时调用的是 Swarm 服务接口。

二、镜像选型说明

镜像	说明	选择建议
dokploy/dokploy:v0.30.8	官方面板镜像，多架构（amd64/arm64）	首选，固定版本保证可复现
dokploy/dokploy:latest	官方最新稳定版标签	跟随官方升级，升级行为不可控
dokploy/dokploy:canary	开发通道，每日构建	仅测试评估，勿用于生产
postgres:16 / redis:7 / traefik:v3.6.7	官方安装脚本锁定的配套版本	与官方一致，避免兼容性问题

建议：生产环境固定 dokploy/dokploy:v0.30.8 这类精确版本标签；latest 会在官方发版后静默变化，导致「重启即升级」的不可控行为。查询可用标签：docker pull dokploy/dokploy:v0.30.8（拉取即验证标签存在）。

三、前置条件

一台 Ubuntu 24.04 服务器（其他主流发行版亦可），root 或 sudo 权限。
已安装 Docker 29.x 与 Docker Compose v2+，验证：

docker version --format 'Docker {{.Server.Version}}'

实测回显：

Docker 29.8.0

docker compose version

实测回显：

Docker Compose version v5.5.1

端口 3000、80、443 空闲（官方安装脚本会检查这三项）：

ss -ltn | grep -E ':(80|443|3000) ' || echo "ports 80/443/3000 are free"

实测回显：

ports 80/443/3000 are free

服务器已知自身内网 IP（作为 Swarm advertise 地址与 ADVERTISE_ADDR），本例为 10.0.0.3。
服务器可访问外网（拉取镜像）。

四、部署步骤

4.1 初始化 Docker Swarm

Dokploy 面板本身可以跑在普通容器里，但它编排用户应用时调用 Swarm 服务接口，因此必须先把服务器初始化为 Swarm 管理节点。--advertise-addr 指向本机内网 IP：

docker swarm init --advertise-addr 10.0.0.3

实测回显：

Swarm initialized: current node (tgobjz79ph734nhqp1v2j2wof) is now a manager.

To add a worker to this swarm, run the following command:
r6vz6kzxm8cxhxa02w247u76g

💡 说明：回显中的 worker 加入令牌用于多节点扩容，单机部署可忽略；ADVERTISE_ADDR 必须是所有节点可达的 IP，否则 overlay 网络无法互通。

4.2 创建 Dokploy overlay 网络

按官方脚本创建 dokploy-network，--attachable 允许普通容器（含 Traefik）加入：

docker network create --driver overlay --attachable dokploy-network

实测回显（网络 ID）：

r6vz6kzxm8cx

验证网络已创建：

docker network ls --filter name=dokploy-network

实测回显：

NETWORK ID     NAME              DRIVER    SCOPE
r6vz6kzxm8cx   dokploy-network   overlay   swarm

4.3 编写 Compose 文件

创建部署目录并写入 docker-compose.yml：

mkdir -p /opt/dokploy/compose
cd /opt/dokploy/compose
vim docker-compose.yml

docker-compose.yml 全文（参数与官方安装脚本逐项对应）：

name: dokploy-v0.30.8-stack

services:
  dokploy-postgres:
    image: postgres:16
    container_name: dokploy-postgres
    restart: unless-stopped
    networks:
      - dokploy-network
    environment:
      - POSTGRES_USER=dokploy
      - POSTGRES_PASSWORD=q1w2e3r4
      - POSTGRES_DB=dokploy
    volumes:
      - dokploy-postgres-data:/var/lib/postgresql/data

  dokploy-redis:
    image: redis:7
    container_name: dokploy-redis
    restart: unless-stopped
    networks:
      - dokploy-network
    volumes:
      - dokploy-redis-data:/data

  dokploy:
    image: dokploy/dokploy:v0.30.8
    container_name: dokploy
    restart: unless-stopped
    networks:
      - dokploy-network
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/dokploy:/etc/dokploy
      - dokploy-docker-config:/root/.docker
    environment:
      - ADVERTISE_ADDR=10.0.0.3
      - DATABASE_URL=postgresql://dokploy:q1w2e3r4@dokploy-postgres:5432/dokploy
      - REDIS_HOST=dokploy-redis
      - TZ=Asia/Shanghai

  dokploy-traefik:
    image: traefik:v3.6.7
    container_name: dokploy-traefik
    restart: unless-stopped
    networks:
      - dokploy-network
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml
      - /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  dokploy-postgres-data: {}
  dokploy-redis-data: {}
  dokploy-docker-config: {}

networks:
  dokploy-network:
    external: true

逐项说明：

配置项	含义与依据
`name: dokploy-v0.30.8-stack`	显式 Compose 项目名，避免多项目同名互相干扰
`networks: dokploy-network (external)`	复用 4.2 创建的官方 overlay 网络，与官方脚本一致
`POSTGRES_USER/PASSWORD/DB`	官方脚本同样使用 `dokploy` 用户与 `dokploy` 库；密码官方走 Docker Secret，此处演示直接落值，生产建议保留 Secret 方式
`DATABASE_URL`	面板连接元数据库的串，主机名用服务名 `dokploy-postgres`（Compose 内部 DNS 解析）
`REDIS_HOST`	队列/缓存地址，指向服务名 `dokploy-redis`
`ADVERTISE_ADDR`	Swarm advertise 地址，与 4.1 一致
`/var/run/docker.sock` 挂载	Dokploy 通过本机 Docker 接口编排服务（官方脚本同款挂载）
`/etc/dokploy` 挂载	平台配置与 Traefik 动态配置目录（首启自动生成，见 4.6）
`dokploy:/root/.docker` 卷	面板自身的 Docker 客户端配置（官方脚本同款）
Traefik 80/443	HTTP/HTTPS 边缘入口，`443/udp` 为 HTTP/3（官方脚本同款）
Traefik 挂载 `traefik.yml` 与 `dynamic/`	主配置与动态路由目录，均由 Dokploy 首启生成（见 4.6）

💡 说明：postgres:16、redis:7、traefik:v3.6.7 为官方安装脚本当前锁定版本；升级 Dokploy 主程序时无需同步升级这三个组件（Traefik 升级需按官方说明手动操作，见「十、常用运维命令」）。

4.4 先启动面板三件套（postgres / redis / dokploy）

Traefik 挂载的 traefik.yml 由 Dokploy 首次启动时生成，因此必须先起面板三件套，再起 Traefik，否则 Traefik 因挂载文件不存在而启动失败：

cd /opt/dokploy/compose
docker compose up -d dokploy-postgres dokploy-redis dokploy

实测回显：

 Container dokploy-postgres Starting
 Container dokploy-redis Starting
 Container dokploy Started
 Container dokploy-postgres Started
 Container dokploy-redis Started

首次启动 Dokploy 会自动执行数据库迁移、初始化定时任务与部署队列，观察日志确认就绪：

docker logs dokploy 2>&1 | tail -8

实测回显（输出节选，实测首尾）：

Please migrate to Docker Secrets:
  curl -sSL https://dokploy.com/security/0.29.3.sh | bash

Network is already initialized
Setting up cron jobs....
Initializing 0 schedules
Setting up cancel deployments....
Cancelled 0 deployments
Setting up volume backups cron jobs....
Initializing 0 volume backups
Starting Deployment Worker

💡 说明：「Please migrate to Docker Secrets」是 v0.29.3 起的安全加固提示——官方推荐数据库口令改用 Docker Secret 注入（compose 明文密码场景触发）。功能不受影响，可按官方脚本方式迁移；「Starting Deployment Worker」出现即部署队列就绪。

4.5 启动 Traefik 边缘代理

确认 /etc/dokploy/traefik/traefik.yml 已生成后，再启动 Traefik：

ls -la /etc/dokploy/traefik/

实测回显：

total 16
drwxr-xr-x    3 root     root          4096 Oct 21 07:08 .
drwxr-xr-x    9 root     root          4096 Oct 21 07:08 ..
drwxr-xr-x    3 root     root          4096 Oct 21 07:08 dynamic
-rw-r--r--    1 root     root           612 Oct 21 07:08 traefik.yml

cd /opt/dokploy/compose
docker compose up -d dokploy-traefik

实测回显：

 Container dokploy-traefik Starting
 Container dokploy-traefik Started

4.6 验证部署结果

查看四组件运行状态：

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

实测回显：

NAMES              STATUS                    PORTS
dokploy-traefik    Up 10 seconds             0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp, [::]:443->443/udp
dokploy-postgres   Up 54 seconds             5432/tcp
dokploy            Up 54 seconds (healthy)   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
dokploy-redis      Up 53 seconds             6379/tcp

dokploy 状态为 healthy 即面板就绪。验证面板 HTTP 响应（首次安装会 307 跳转到注册页）：

curl -sI http://127.0.0.1:3000/ | head -8

实测回显：

HTTP/1.1 307 Temporary Redirect
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
Location: /register
Date: Wed, 21 Oct 2026 07:09:11 GMT

浏览器打开 http://<服务器IP>:3000，在注册页创建管理员账号（首个注册用户自动成为管理员，示例账号 admin@dokploy.local / q1w2e3r4），即可进入控制台开始使用。验证元数据库就绪：

docker exec dokploy-postgres pg_isready -U dokploy

实测回显：

/var/run/postgresql:5432 - accepting connections

五、数据持久化说明

Dokploy 的持久化分两层：平台自身数据与被编排应用的数据。

平台自身数据（本部署方案的落盘点）：

数据	落盘位置	说明
Traefik 与平台配置	/etc/dokploy（宿主机目录）	含 `traefik.yml`、`dynamic/` 动态路由、SSH 密钥、日志等，首启自动生成
Postgres 元数据	命名卷 `dokploy-v0308-stack_dokploy-postgres-data`	项目/应用/部署记录/用户，平台最核心数据
Redis 数据	命名卷 `dokploy-v0308-stack_dokploy-redis-data`	队列与缓存，可丢失重建
面板 Docker 配置	命名卷 `dokploy-v0308-stack_dokploy-docker-config`	面板自身的 Docker 客户端配置

验证卷已创建：

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

被编排应用的数据：经面板创建的数据库等应用由 Swarm 托管，其数据卷由 Dokploy 自动创建（命名规则为 <appName>-data）。例如经面板创建一个 PostgreSQL 数据库并部署后：

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

实测回显：

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

docker volume ls --format '{{.Name}}' | grep back-up

实测回显：

postgres-back-up-virtual-alarm-amtzgf-data

⚠️ 注意：/etc/dokploy 目录与 Postgres 数据卷是备份的重点；建议将官方 Backups 功能的数据库定时备份与 /etc/dokploy 的文件级备份同时纳入运维规范。

六、环境变量表

Dokploy 面板支持的常用环境变量（官方 Manual Installation 文档列出，查询日期 2026-10-21），均在 docker-compose.yml 的 dokploy 服务 environment: 中设置：

变量	默认	说明
PORT	3000	面板监听端口，用于避免与其他服务冲突
ADVERTISE_ADDR	自动探测服务器 IP	Swarm advertise 地址，多网卡/内网环境建议显式指定
DATABASE_URL	（内置拼装）	Postgres 连接串，替换内置元数据库或外接数据库时设置
REDIS_HOST	dokploy-redis	Redis 地址，外接 Redis 时设置
TRAEFIK_PORT	80	Traefik HTTP 入口端口
TRAEFIK_SSL_PORT	443	Traefik HTTPS 入口端口
RELEASE_TAG	latest	面板镜像标签（swarm 部署场景使用）
TZ	UTC	时区，如 `Asia/Shanghai`
DOKPLOY_VERSION	latest（自动探测最新稳定版）	安装脚本专用：指定安装/升级版本（`latest`/`canary`/`v0.30.8`）
DOCKER_SWARM_INIT_ARGS	（空）	安装脚本专用：追加 `docker swarm init` 参数，如自定义地址池

修改方式：编辑 /opt/dokploy/compose/docker-compose.yml 后执行 docker compose up -d 重建对应服务生效（仅重建变更的服务）。

七、配置参数说明

7.1 平台自动生成的 Traefik 主配置

首启生成的 /etc/dokploy/traefik/traefik.yml 全文（实测）：

global:
  sendAnonymousUsage: false
providers:
  swarm:
    exposedByDefault: false
    watch: true
  docker:
    exposedByDefault: false
    watch: true
    network: dokploy-network
  file:
    directory: /etc/dokploy/traefik/dynamic
    watch: true
entryPoints:
  web:
    address: :80
  websecure:
    address: :443
    http3:
      advertisedPort: 443
    http:
      tls:
        certResolver: letsencrypt
api:
  insecure: true
certificatesResolvers:
  letsencrypt:
    acme:
      email: test@localhost.com
      storage: /etc/dokploy/traefik/dynamic/acme.json
      httpChallenge:
        entryPoint: web

逐项说明：

配置块	含义
`providers.swarm / docker`	Traefik 同时监听 Swarm 服务标签与容器标签，`exposedByDefault: false` 表示只有显式打标的才暴露
`providers.docker.network`	指定在 `dokploy-network` 上发现服务，避免误连其他网络
`providers.file`	动态路由来自 `/etc/dokploy/traefik/dynamic/`，Dokploy 为每个绑定域名的应用在该目录生成路由文件
`entryPoints.web / websecure`	80/443 两个入口；`websecure` 启用 HTTP/3（`advertisedPort: 443`）并默认挂 letsencrypt 证书解析器
`api.insecure`	Traefik 自带 API/dashboard 以非安全模式开放（仅容器网络内部可访问）
`certificatesResolvers.letsencrypt`	ACME 账户配置：证书存储在 `dynamic/acme.json`，HTTP-01 挑战走 80 端口

⚠️ 注意：acme.email 默认为占位值 test@localhost.com，生产环境应在面板「Web Server → Traefik」设置中改为真实邮箱并让 Dokploy 重新生成配置，避免 Let's Encrypt 通知失效。

7.2 /etc/dokploy 平台配置目录

ls -la /etc/dokploy/

实测回显：

total 40
drwxr-xr-x    9 root     root          4096 Oct 21 07:08 .
drwxr-xr-x    1 root     root          4096 Oct 21 07:08 ..
drwxr-xr-x    2 root     root          4096 Oct 21 07:08 applications
drwxr-xr-x    2 root     root          4096 Oct 21 07:08 logs
drwxr-xr-x    2 root     root          4096 Oct 21 07:08 monitoring
drwxr-xr-x    2 root     root          4096 Oct 21 07:08 schedules
drwx------    2 root     root          4096 Oct 21 07:08 ssh
drwxr-xr-x    3 root     root          4096 Oct 21 07:08 traefik
drwxr-xr-x    2 root     root          4096 Oct 21 07:08 volume-backups

目录	用途
applications/	应用相关运行数据（如 Compose 类应用的编排文件）
logs/	平台运行日志
monitoring/	资源监控数据
schedules/	计划任务定义
ssh/	多服务器模式的 SSH 私钥（权限 700，注意保护）
traefik/	Traefik 主配置与动态路由（见 7.1）
volume-backups/	卷备份任务数据

7.3 面板启动流程（进程视角）

面板容器的启动命令（docker compose top dokploy 实测）揭示了启动顺序，排障时可据此判断卡在哪一步：

cd /opt/dokploy/compose && docker compose top dokploy

实测回显：

SERVICE  #   PID  USER  TIME  COMMAND
dokploy  1   714  root  0:00  /usr/bin/tini -- sh -c node -r dotenv/config dist/wait-for-postgres.mjs && node -r dotenv/config dist/migration.mjs && exec node -r dotenv/config dist/server.mjs
dokploy  1   776  root  0:09  {MainThread} node -r dotenv/config dist/server.mjs

即：wait-for-postgres（等元数据库就绪）→ migration（执行数据库迁移）→ server（启动面板服务）。若面板反复重启，优先检查 DATABASE_URL 指向的 Postgres 是否可达。

八、配置文件挂载

宿主机路径	容器内路径	挂载方式	说明
/var/run/docker.sock	/var/run/docker.sock	bind（读写）	面板编排入口，Dokploy 编排应用的必需通道
/var/run/docker.sock	/var/run/docker.sock	bind（只读，traefik）	Traefik 发现服务标签
/etc/dokploy	/etc/dokploy	bind	平台配置与 Traefik 动态配置（持久化重点）
/etc/dokploy/traefik/traefik.yml	/etc/traefik/traefik.yml	bind（traefik）	Traefik 主配置（先起面板生成后再起 Traefik）
/etc/dokploy/traefik/dynamic	/etc/dokploy/traefik/dynamic	bind（traefik）	动态路由目录，Dokploy 按应用域名自动写入
命名卷 ×3	/var/lib/postgresql/data、/data、/root/.docker	volume	元数据/Redis/面板 Docker 配置

挂载验证：

docker inspect dokploy --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'

实测回显：

/var/run/docker.sock -> /var/run/docker.sock
/etc/dokploy -> /etc/dokploy
dokploy-v0308-stack_dokploy-docker-config -> /root/.docker

九、等价 docker run

官方安装脚本对四个组件的原始形态为 Swarm 服务（docker service create）+ 普通 docker run（Traefik）。Compose 编排的等价关系如下，供脱离 Compose 手工部署参考。

dokploy 面板（官方为 swarm service，等价 docker run 形态）：

docker run -d \
  --name dokploy \
  --network dokploy-network \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/dokploy:/etc/dokploy \
  -v dokploy:/root/.docker \
  -e ADVERTISE_ADDR=10.0.0.3 \
  -e DATABASE_URL=postgresql://dokploy:q1w2e3r4@dokploy-postgres:5432/dokploy \
  -e REDIS_HOST=dokploy-redis \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  dokploy/dokploy:v0.30.8

dokploy-postgres（官方为 swarm service，等价 docker run 形态）：

docker run -d \
  --name dokploy-postgres \
  --network dokploy-network \
  -e POSTGRES_USER=dokploy \
  -e POSTGRES_PASSWORD=q1w2e3r4 \
  -e POSTGRES_DB=dokploy \
  -v dokploy-postgres:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:16

dokploy-redis（官方为 swarm service，等价 docker run 形态）：

docker run -d \
  --name dokploy-redis \
  --network dokploy-network \
  -v dokploy-redis:/data \
  --restart unless-stopped \
  redis:7

Traefik（官方脚本原文即为 docker run 形态）：

docker run -d \
  --name dokploy-traefik \
  --restart always \
  -v /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml \
  -v /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p 80:80/tcp \
  -p 443:443/tcp \
  -p 443:443/udp \
  traefik:v3.6.7
docker network connect dokploy-network dokploy-traefik

💡 说明：官方 Swarm 形态在 compose 之外还提供了滚动更新策略（--update-parallelism 1 --update-order stop-first）与 Docker Secret 管理口令；对单机部署而言 Compose 方案已覆盖等价能力，多节点接入时建议回归官方脚本形态。

十、常用运维命令

10.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            25 minutes ago   Up 25 minutes (healthy)   0.0.0.0:3000->3000/tcp
dokploy-postgres   postgres:16                                                               "docker-entrypoint.s…"   dokploy-postgres   25 minutes ago   Up 25 minutes             5432/tcp
dokploy-redis      redis:7                                                                   "docker-entrypoint.s…"   dokploy-redis      25 minutes ago   Up 25 minutes             6379/tcp
dokploy-traefik    traefik:v3.6.7                                                            "/entrypoint.sh trae…"   dokploy-traefik    24 minutes ago   Up 24 minutes             0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

docker logs dokploy --tail 20        # 面板日志
docker logs dokploy-traefik --tail 20  # 边缘代理日志

10.2 重启与恢复

cd /opt/dokploy/compose
docker compose restart dokploy

实测回显：

 Container dokploy Restarting
 Container dokploy Started

重启后验证面板恢复（等待约 15 秒）：

curl -s -o /dev/null -w 'panel HTTP %{http_code}\n' http://127.0.0.1:3000/

实测回显：

panel HTTP 200

10.3 检查 Swarm 与被编排应用

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

实测回显：

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

docker network ls --filter name=dokploy-network --format "{{.Name}} {{.Driver}}"

实测回显：

dokploy-network   overlay

10.4 升级 Dokploy

固定标签部署（本文方案）的升级路径——改 Compose 中的镜像标签后重建：

cd /opt/dokploy/compose
sed -i 's|dokploy/dokploy:v0.30.8|dokploy/dokploy:v0.31.0|' docker-compose.yml
docker compose up -d dokploy

latest 标签部署（官方脚本方案）的升级路径：

docker pull dokploy/dokploy:latest
docker service update --image dokploy/dokploy:latest dokploy

⚠️ 注意：升级前务必备份 /etc/dokploy 与 Postgres 数据卷；Dokploy 大版本间可能有数据库迁移，migration.mjs 会在启动时自动执行，回滚旧版本可能需要还原数据库。Traefik 不会被面板自动升级，如需升级按官方说明删除并重建 Traefik（保持挂载参数一致），版本不兼容可能导致已绑定域名 404。

10.5 卸载

cd /opt/dokploy/compose
docker compose down --volumes    # 移除容器与命名卷（/etc/dokploy 目录需手动删除）
rm -rf /etc/dokploy
docker network rm dokploy-network
docker swarm leave --force       # 如不再使用 Swarm，退出管理节点

⚠️ 注意：down --volumes 会删除 Postgres 元数据，所有项目、应用与部署记录不可恢复，执行前确认已有备份。

十一、常见问题（FAQ）

Q1：docker compose up -d dokploy-traefik 后 Traefik 一直重启？

实测定位：Traefik 挂载的 /etc/dokploy/traefik/traefik.yml 由 Dokploy 面板首次启动时生成；若先起 Traefik，挂载点会被 Docker 创建为同名目录，Traefik 读取失败。解决：docker compose down dokploy-traefik，删除宿主机误生成的 /etc/dokploy/traefik/traefik.yml 目录，先 up -d dokploy（确认 /etc/dokploy/traefik/traefik.yml 为 612 字节左右的文件，见 4.5 实测）后再起 Traefik。

Q2：面板起来了，但通过面板部署应用一直失败？

Dokploy 编排应用依赖 Swarm 服务接口。若服务器未执行 docker swarm init（或曾 swarm leave），面板无法创建服务。验证：

docker info 2>/dev/null | grep -i swarm

实测回显（正常应输出）：

 Swarm: active
  Node ID: tgobjz79ph734nhqp1v2j2wof

若输出 Swarm: inactive，重新执行 4.1 的 docker swarm init --advertise-addr <内网IP> 并重启 dokploy 服务。

Q3：通过 API/CLI 使用 x-api-key 调用时始终 401？

实测排障：面板日志出现 Error verifying API key TypeError: Cannot read properties of null (reading 'organizationId')。原因：v0.30 引入组织（Organization/多环境）后，API Key 必须携带组织上下文——在面板「Settings → API Keys」生成的 Key 会自动写入组织信息；若是通过 API（POST /api/auth/api-key/create）程序化创建的 Key，必须在请求体 metadata 中显式带上 "organizationId":"<组织ID>"（组织 ID 可经 GET /api/auth/organization/list 查询）。补齐 metadata 后重新创建 Key 即恢复。

Q4：API/CLI 突然全部返回 401/400，日志有 Rate limit exceeded？

v0.30.x 每个 API Key 默认限速 10 次/24 小时（rateLimitTimeWindow: 86400000，rateLimitMax: 10，创建 Key 的响应体可实测看到）。自动化脚本高频调用时会触发限速，面板日志记录 Error verifying API key Error: Rate limit exceeded.。解决：等待 24 小时窗口重置，或在面板删除旧 Key 重新生成（新 Key 计数从零开始）；高频自动化场景应合并请求、缓存结果。

Q5：80 或 443 端口已被其他服务占用怎么办？

官方脚本遇到占用会直接终止安装（Error: something is already running on port 80）。Compose 方案可改端口映射避开，例如 Traefik 改为 "8080:80"、"8443:443"，并同步调整应用域名的对外端口；或在占用 80/443 的服务上做流量转发。面板端口同理改 PORT 环境变量与 ports 映射。

Q6：Proxmox LXC 里部署有什么注意事项？

官方文档明确：LXC 环境需为 Swarm 服务追加 --endpoint-mode dnsrr（脚本安装会自动检测；手动/Compose 场景需自行处理），否则 overlay 网络的服务发现在该环境下不可用。

十二、参考链接

官方安装文档（Manual Installation）：https://docs.dokploy.com/docs/core/manual-installation
官方一键安装说明：https://docs.dokploy.com/docs/core/installation
卸载说明：https://docs.dokploy.com/docs/core/uninstall
排障文档：https://docs.dokploy.com/docs/core/troubleshooting
Docker Secrets 迁移脚本：https://dokploy.com/security/0.29.3.sh
本专栏《Dokploy 介绍与选型指南》：https://www.quzuo.net/document/KzLqn3RZUakX
本专栏系列：《Dokploy v0.30.8 常用 CLI 命令与工具详解》、《Dokploy v0.30.8 配置参数详解》。