Dokploy v0.30.8 配置参数详解

目标：系统梳理 Dokploy v0.30.8 的全部可配置参数——面板环境变量、数据持久化位置、自动生成的 Traefik 配置、API Key 安全参数与被编排应用的资源参数，给出每项的含义、默认值、修改方式与生效验证方法，并提供一份生产配置模板。全部参数已在 Ubuntu 24.04（Docker 29.8.0 + Compose v5.5.1）实测核对。

一、环境信息

部署过程（如何得到上述环境）见本专栏《Dokploy Docker Compose 部署指南》（https://www.quzuo.net/document/sQz2z32P5Jec），本文所有参数查看与修改命令均可独立执行。

二、前置条件

• 已按 Compose 方案完成 Dokploy 部署且面板健康（docker ps 中 dokploy 为 Up ... (healthy)）。
• 具备服务器 root 或 sudo 权限（/etc/dokploy 与 Docker 接口操作需要）。
• 能在部署目录执行 docker compose 命令（默认 /opt/dokploy/compose）。

快速自检：

docker inspect dokploy --format '{{.State.Health.Status}}'

实测回显：

healthy

三、参数查看与修改方式

Dokploy 的参数分布在四个层面，查看与修改方式各不相同：

查看面板容器实际生效的环境变量（排除镜像内置项）：

docker inspect dokploy --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E '^(ADVERTISE_ADDR|DATABASE_URL|REDIS_HOST|TZ|PORT)='

实测回显：

REDIS_HOST=dokploy-redis
TZ=Asia/Shanghai
ADVERTISE_ADDR=10.0.0.3
DATABASE_URL=postgresql://dokploy:q1w2e3r4@dokploy-postgres:5432/dokploy

修改示例（把时区改为 UTC 后重建）：

cd /opt/dokploy/compose
sed -i 's|TZ=Asia/Shanghai|TZ=UTC|' docker-compose.yml
docker compose up -d dokploy
docker inspect dokploy --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^TZ='

实测回显：

TZ=UTC

改回示例值（sed -i 's|TZ=UTC|TZ=Asia/Shanghai|' docker-compose.yml && docker compose up -d dokploy）后继续。

💡 说明：官方 Swarm 形态（docker service create 部署）的等价修改方式为 docker service update --env-add TZ=America/New_York dokploy（官方 Manual Installation 文档，查询日期 2026-10-21）；Compose 形态直接改文件重建即可，两种形态参数名完全一致。

四、参数总览

面板（dokploy 服务）支持的常用环境变量一览（官方 Manual Installation 文档列出，查询日期 2026-10-21；默认值为官方口径或实测推断）：

关键差异：PORT/TRAEFIK_PORT/TRAEFIK_SSL_PORT 只改服务监听端口，还需同步修改端口映射才对外生效；ADVERTISE_ADDR 是唯一「改错会导致集群异常」的参数，多网卡环境务必显式指定。

五、核心参数分类详解

5.1 网络与端口类参数

PORT（面板端口，默认 3000）

面板 Web 控制台与 REST API 的监听端口。修改时必须同步修改 Compose 的端口映射（ports: ["3000:3000"] → 两处一致）。适用场景：3000 已被 Grafana 等服务占用时换端口。

ADVERTISE_ADDR（Swarm 公告地址，默认自动探测）

docker swarm init --advertise-addr 使用的地址，也是面板内传给编排层的集群公告地址。官方脚本默认取服务器公网 IP（经 ifconfig.io/icanhazip.com 探测）；内网/多网卡/NAT 环境应显式指定为所有节点可达的地址。本例实测：

docker exec dokploy printenv ADVERTISE_ADDR

实测回显：

10.0.0.3

验证 Swarm 状态与该地址一致：

docker info 2>/dev/null | grep -A3 'Swarm:'

实测回显（输出节选）：

 Swarm: active
  Node ID: tgobjz79ph734nhqp1v2j2wof
  Is Manager: true

⚠️ 注意：ADVERTISE_ADDR 指向不可达 IP 会导致 overlay 网络不通、应用部署失败；改它需要 docker swarm leave --force 后重新 swarm init，属于重操作。

TRAEFIK_PORT / TRAEFIK_SSL_PORT（默认 80/443）

Traefik 边缘入口的监听端口，用于 80/443 被占用或前置了其他网关的场景。改后同样需同步 Traefik 的 ports: 映射；已绑定域名应用的回源端口随之变化。

5.2 数据与存储类参数

DATABASE_URL（元数据库连接串）

格式 postgresql://<用户>:<密码>@<主机>:<端口>/<库名>，本例实测值为 postgresql://dokploy:q1w2e3r4@dokploy-postgres:5432/dokploy。参数分解与 Compose 中 Postgres 侧的对应关系：

修改场景：外接数据库（RDS/自建高可用 Postgres）。官方文档明确 DATABASE_URL 用于「替换内置数据库」（Manual Installation，查询日期 2026-10-21）。外接时 Compose 中的 dokploy-postgres 服务可整体移除。

验证连接串可用（用平台自带 psql 实测，统计元数据库表数量）：

docker exec dokploy-postgres psql "postgresql://dokploy:q1w2e3r4@127.0.0.1:5432/dokploy" -c "select count(*) as tables from information_schema.tables where table_schema='public';"

实测回显：

 tables
--------
     67
(1 row)

⚠️ 注意：若连接串错误，面板会卡在 wait-for-postgres 阶段反复重启（启动流程见 5.6）。

REDIS_HOST（Redis 地址，默认 dokploy-redis）

部署队列与缓存通道地址，默认指向 Compose 服务名。外接 Redis 时改为实际地址（可含端口，如 redis.internal:6379）。

/etc/dokploy（配置数据根目录）

平台全部文件型数据落点，首启自动生成（目录清单与用途见《部署指南》7.2 节）。其中：

• /etc/dokploy/traefik/：Traefik 主配置 + 动态路由（详见 5.3）；
• /etc/dokploy/ssh/：多服务器模式的 SSH 私钥，权限 700；
• /etc/dokploy/schedules/、volume-backups/：定时任务与卷备份定义。

数据卷（命名卷）

查看命令与实测回显：

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

5.3 Traefik 配置参数（/etc/dokploy/traefik/traefik.yml）

该文件由 Dokploy 首次启动自动生成（全文见《部署指南》7.1 节），核心参数逐项拆解：

验证参数生效（Traefik 实际监听端口）：

ss -ltn | grep -E ':(80|443) '

实测回显：

tcp        0      0 0.0.0.0:443             0.0.0.0:*               LISTEN
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN
tcp        0      0 :::443                  :::*                    LISTEN
tcp        0      0 :::80                   :::*                    LISTEN

⚠️ 注意：修改此文件推荐走面板「Settings → Web Server」的 Traefik File Manager，面板会做合法性校验并自动触发 Traefik 热加载；直接手改文件后需 docker compose restart dokploy-traefik。升级 Dokploy 不会覆盖此文件。

5.4 版本与发布通道参数

DOKPLOY_VERSION（安装脚本版本选择，默认自动探测最新稳定版）：export DOKPLOY_VERSION=v0.30.8 && curl -sSL https://dokploy.com/install.sh | sh 指定版本安装/升级；canary 进入开发通道（每日构建）。查询可用版本：Docker Hub 标签列表（实测当前最新稳定 v0.30.8，2026-09-29）。

RELEASE_TAG（Swarm 形态镜像标签，默认 latest）：官方 Swarm 服务创建时的镜像标签；Compose 形态直接改 image: 字段，二者等价。

5.5 安装与 Swarm 参数

DOCKER_SWARM_INIT_ARGS（swarm init 追加参数，默认空）：安装前导出，追加到 docker swarm init 后面。官方示例（Manual Installation，查询日期 2026-10-21）：

export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24"
curl -sSL https://dokploy.com/install.sh | sh

用于自定义 Swarm 默认地址池，避免与现有内网网段（如 10.0.0.0/8）冲突——地址池重叠会造成 overlay 网络无法创建。

5.6 面板健康检查参数（镜像内置）

面板镜像自带健康检查，参数实测：

docker inspect dokploy --format '{{json .Config.Healthcheck}}'

实测回显：

{"Test":["CMD-SHELL","curl -fs http://localhost:3000/api/trpc/settings.health || exit 1"],"Interval":30000000000,"Timeout":0,"StartPeriod":0,"Retries":0}

💡 说明：settings.health 是面板内部健康端点，docker ps 显示的 (healthy) 即来自它；自建负载均衡探活可直接复用该路径。

5.7 API Key 安全参数（v0.30 多租户相关）

创建 API Key 的响应体字段（实测，敏感值已脱敏）：

{"name":"cli-token","start":"ifvWne","prefix":null,"enabled":true,
 "rateLimitEnabled":true,"rateLimitTimeWindow":86400000,"rateLimitMax":10,
 "requestCount":0,"remaining":null,"expiresAt":null,
 "permissions":...}

排障实录：程序化创建 Key（POST /api/auth/api-key/create，需会话与 Origin 头）时若不带 metadata:{"organizationId":"<组织ID>"}，该 Key 全部调用 401；组织 ID 经 GET /api/auth/organization/list 查询（本例实测 avblv0QFJO6M1qqNqBITg）。触发限速后日志记录 Error verifying API key Error: Rate limit exceeded.，处理方法见《部署指南》Q4。

5.8 被编排应用的资源参数

经面板/API 创建的数据库与应用支持资源限额参数。实测创建 PostgreSQL 数据库（POST /api/postgres.create）的响应字段：

{"postgresId":"hcgREDx_xW3iURXKacig7","appName":"postgres-back-up-virtual-alarm-amtzgf",
 "databaseName":"labdb","databaseUser":"labuser","dockerImage":"postgres:16",
 "command":null,"args":null,"env":null,
 "memoryReservation":null,"memoryLimit":null,
 "cpuReservation":null,"cpuLimit":null,"externalPort":null,"applicationStatus":"idle"}

验证限额生效：面板部署后 docker service inspect <appName> 查看 Resources.Limits。

六、生产配置模板

适用场景：2C4G 云主机 / NVMe SSD / 中小团队（10 人以内、数十个应用）自托管部署平台。

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
    deploy:
      resources:
        limits:
          memory: 1024M

  dokploy-redis:
    image: redis:7
    container_name: dokploy-redis
    restart: unless-stopped
    networks:
      - dokploy-network
    volumes:
      - dokploy-redis-data:/data
    deploy:
      resources:
        limits:
          memory: 256M

  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        # 改为你的服务器内网 IP
      - DATABASE_URL=postgresql://dokploy:q1w2e3r4@dokploy-postgres:5432/dokploy
      - REDIS_HOST=dokploy-redis
      - TZ=Asia/Shanghai
    deploy:
      resources:
        limits:
          memory: 1024M

  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
    deploy:
      resources:
        limits:
          memory: 256M

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

networks:
  dokploy-network:
    external: true

模板要点：四个组件合计内存限额 2.5G（4G 机器预留系统与被编排应用余量）；ADVERTISE_ADDR/DATABASE_URL 两处按实际环境修改；生产建议将 Postgres 口令改为 Docker Secret 注入（官方 0.29.3 安全迁移脚本：curl -sSL https://dokploy.com/security/0.29.3.sh | bash），并把 /etc/dokploy 与 Postgres 数据卷纳入每日备份。应用模板验证：

cd /opt/dokploy/compose && docker compose config --quiet && echo "compose file valid"

实测回显：

compose file valid

七、常见问题（FAQ）

Q1：改了 environment 重启后面板没生效？

确认执行的是 docker compose up -d（重建服务）而非 docker compose restart（restart 不应用新的环境变量）。重建后用 docker inspect dokploy --format '{{range .Config.Env}}{{println .}}{{end}}' 复核生效值。

Q2：ADVERTISE_ADDR 能不能随便改？

不能。它必须是「本机真实网卡地址」且「所有 Swarm 节点可达」。单机环境改为错误值后，docker swarm leave --force + 重新 swarm init 才能纠正；已部署的应用需要重新部署。

Q3：Traefik 的 acme.email 还是 test@localhost.com，有什么风险？

Let's Encrypt 会向该邮箱发到期/撤销通知，占位邮箱收不到。改法：面板「Settings → Web Server → Traefik File Manager」中修改 certificatesResolvers.letsencrypt.acme.email 为真实邮箱保存，面板自动热加载；已签发证书不受影响，续期时生效。

Q4：外接了数据库，compose 里还留着 dokploy-postgres 服务会怎样？

不影响运行（多余服务空跑），但浪费资源且可能误连。外接 DATABASE_URL 后应从 Compose 中移除 dokploy-postgres 服务与其卷定义，再 docker compose up -d。

Q5：API Key 限速 10 次/天太少，怎么调？

面板创建 Key 时不可修改限速参数（rateLimitEnabled 等为服务端专用属性，程序化传入会报 SERVER_ONLY_PROPERTY，实测）。当前版本的可行做法：拆分多个 Key 轮换、合并 API 请求、或等待窗口重置后重试。

八、参考链接

• 官方环境变量说明（Manual Installation）：https://docs.dokploy.com/docs/core/manual-installation

• Traefik 配置参考：https://doc.traefik.io/traefik/reference/routing-configuration/providers/docker/

• Docker Secrets 迁移脚本：https://dokploy.com/security/0.29.3.sh

• 本专栏《Dokploy 介绍与选型指南》：https://www.quzuo.net/document/KzLqn3RZUakX

• 本专栏《Dokploy Docker Compose 部署指南》：https://www.quzuo.net/document/sQz2z32P5Jec

• 本专栏系列：《Dokploy v0.30.8 常用 CLI 命令与工具详解》。