Coolify 4.4.6 Docker Compose 部署指南

在 Ubuntu 24.04 部署 Coolify 4.4.6：官方脚本与手动编排双路线从零部署、部署验证、数据持久化、环境变量逐项、升级与运维命令及 8 条排障实录，全部实测通过（Docker 29.8.1 + Compose v5.5.1）。

CoolifyCoolify服务器管理2026/10/21

Coolify 4.4.6 Docker Compose 部署指南

目标：在一台 Ubuntu 24.04 服务器上完成 Coolify 4.4.6 的从零部署，覆盖「官方安装脚本」与「手动编排部署」两条路线、部署结果验证、数据持久化、环境变量逐项说明、升级与常用运维命令及排障实录。全部命令与回显已在 Ubuntu 24.04（Docker 29.8.1 + Docker Compose v5.5.1）实测通过，平台就绪后 GET /api/health 返回 OK。

一、环境信息

项目值
操作系统Ubuntu 24.04（x86_64）
Docker29.8.1（安装脚本自动检测，要求 24+，实测回显见 4.4 节）
Docker Composev5.5.1（docker compose version 实测）
Coolify 版本4.4.6（官方脚本 2026-10-21 默认通道解析的最新版；官方仓库当日另发布 v4.4.7，升级流程相同）
coolify-helper 版本1.0.17（官方脚本升级流程引用）
元数据库postgres:15-alpine
队列缓存redis:7-alpine（启用 --requirepass）
监听端口8000（Web 控制台/REST API）、6001/6002（实时通信 Reverb）
部署目录/data/coolify（编排文件与配置位于 /data/coolify/source）
编排项目名source（官方编排文件未显式指定项目名，由目录名推导；勿改名目录，否则升级时项目识别会分裂）
演示管理员root / q1w2e3r4（通过安装脚本环境变量预置）

二、版本与组件选型说明

Coolify 官方交付物是一组编排文件（安装脚本从官方 CDN cdn.coollabs.io/coolify 下载），生产编排 docker-compose.prod.yml 定义三个服务：

服务编排引用版本角色端口
coolifycoollabsio/coolify:4.4.6（经 .env 的 LATEST_IMAGE 注入）Web 控制台 + REST API + 部署编排器 + 内置实时通信（Reverb）内部 8080/6001/6002，对外 8000/6001/6002
postgrespostgres:15-alpine平台元数据库（项目、应用、部署记录、用户、API Token）仅编排内网 5432
redisredis:7-alpine后台任务队列（Horizon）、缓存与会话通道仅编排内网 6379

选型解读：平台主服务版本由官方安装脚本运行时解析（LATEST_IMAGE=4.4.6 写入 .env），元数据库与缓存由官方编排锁定为 postgres:15-alpine 与 redis:7-alpine，不建议自行更换大版本（数据库结构迁移按官方版本矩阵执行）；生产编排另含一个 soketi 占位服务（挂 legacy-soketi profile，永不启动），用于兼容 4.4 之前版本遗留的覆盖文件，属官方兼容设计，保留原样即可。

三、前置条件

  1. 操作系统：Ubuntu 24.04（官方脚本内置 Ubuntu/Debian/Fedora/Arch 系发行版检测分支，本文以 Ubuntu 24.04 实测）。
  2. Docker 引擎 24+ 与 docker compose 插件：脚本检测到缺失时会调用官方安装通道自动安装；已安装的须满足 24+（实测回显「Docker version 29.8.1 meets minimum requirement (24+)」）。
  3. 基础软件包：curl、wget、git、jq、openssl（脚本启动时逐项检查，缺失则自动安装）。
  4. OpenSSH server：Coolify 通过 SSH 管理目标服务器，脚本检测未安装时会自动安装并确认 PermitRootLogin 已启用（实测日志见 4.4 节 Step 2/9）。
  5. 端口规划：8000（Web/API）、6001/6002（实时通信）未被占用；如 8000 冲突见「十一、常见问题」问题 2。
  6. 网络地址池：脚本会检查 Docker 网络地址池配置，默认 10.0.0.0/8（池大小 24）；与现有环境冲突时的处理见「十一、常见问题」问题 3。

四、部署方案 A：官方安装脚本（推荐）

4.1 方案说明

官方推荐路线：一条命令下载并执行安装脚本，自动完成「装依赖 → 查 SSH → 查 Docker → 配置守护进程 → 下载编排文件 → 生成 .env → 生成本机 SSH 密钥 → 拉取组件 → 启动」九步。脚本源码公开（参考链接 2），可先下载审阅再执行。

4.2 预置管理员与环境变量（可选）

脚本支持通过环境变量预置管理员与覆盖默认行为（脚本头部注释原文列出的变量）：

环境变量作用本文取值
ROOT_USERNAME预置管理员用户名root
ROOT_USER_EMAIL预置管理员邮箱root@example.com
ROOT_USER_PASSWORD预置管理员密码q1w2e3r4
DOCKER_ADDRESS_POOL_BASEDocker 网络地址池基址10.0.0.0/8（默认）
DOCKER_ADDRESS_POOL_SIZE地址池规模24（默认）
AUTOUPDATE设为 false 关闭自动更新默认开启
REGISTRY_URL组件仓库地址docker.io（默认）

不预置则安装完成后在控制台页面注册管理员。本文预置演示账号，执行前先导出：

export ROOT_USERNAME=root
export ROOT_USER_EMAIL=root@example.com
export ROOT_USER_PASSWORD=q1w2e3r4

4.3 执行安装

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

4.4 安装过程回显（实测日志节选）

脚本首先打印环境清单：

==========================================
   Coolify Installation - 20261021-074529
==========================================
Source code: https://github.com/coollabsio/coolify/blob/v4.x/scripts/install.sh
Using default registry URL: docker.io
Found existing Docker network pool: 10.0.0.0/8/24
---------------------------------------------
| Operating System  | ubuntu 24.04
| Docker            | latest
| Coolify           | 4.4.6
| Helper            | 1.0.17
| Docker Pool       | 10.0.0.0/8 (size 24)
| Registry URL      | docker.io
---------------------------------------------

随后九步逐项推进，完整日志同步写入 /data/coolify/source/installation-<时间戳>.log。以下为首装全程实测节选（输出节选，步骤间隔省略）：

============================================================
[2026-10-21 07:45:29] Step 1/9: Installing required packages
============================================================
[2026-10-21 07:45:53] Required packages installed successfully

============================================================
[2026-10-21 07:45:53] Step 2/9: Checking OpenSSH server configuration
============================================================
 - OpenSSH server not detected. Installing OpenSSH server.
 - OpenSSH server installed successfully.
 - SSH PermitRootLogin is enabled.

============================================================
[2026-10-21 07:46:14] Step 3/9: Checking Docker Engine
============================================================
 - Docker is installed.
 - Docker version 29.8.1 meets minimum requirement (24+).

============================================================
[2026-10-21 07:46:14] Step 4/9: Configuring Docker daemon
============================================================
 - Creating new Docker configuration with network pool: 10.0.0.0/8/24
 - Configuration updated - restarting Docker daemon...
 - Docker daemon restarted successfully

============================================================
[2026-10-21 07:46:15] Step 5/9: Downloading required files from CDN
============================================================
[2026-10-21 07:46:15] All configuration files downloaded successfully

============================================================
[2026-10-21 07:46:15] Step 6/9: Setting up environment variables
============================================================
 - No .env file found, copying .env.production to .env
 - Updated value of APP_ID as the current value was empty
 - Updated value of APP_KEY as the current value was empty
 - Updated value of DB_PASSWORD as the current value was empty
 - Updated value of REDIS_PASSWORD as the current value was empty
 - Updated value of PUSHER_APP_ID as the current value was empty
 - Updated value of PUSHER_APP_KEY as the current value was empty
 - Updated value of PUSHER_APP_SECRET as the current value was empty
 - Added PUSHER_BACKEND_PORT and its value as the variable was missing
 - Setting predefined root user credentials from environment
 - Updated value of ROOT_USERNAME as the current value was empty
 - Updated value of ROOT_USER_EMAIL as the current value was empty
 - Updated value of ROOT_USER_PASSWORD as the current value was empty

============================================================
[2026-10-21 07:46:15] Step 7/9: Checking SSH key for localhost access
============================================================
 - Generating SSH key.
[2026-10-21 07:46:15] SSH key check completed

首装实测在 Step 8 处因组件拉取失败而中止（网络抖动），真实日志：

============================================================
[2026-10-21 07:46:15] Step 8/9: Pulling images
============================================================

3/6 Pulling Docker images...
     This may take a few minutes depending on your connection.
     - Pulling docker.io/coollabsio/coolify-helper:1.0.17...
     - Pulling docker.io/coollabsio/coolify:4.4.6...
     ERROR: Failed to pull docker.io/coollabsio/coolify:4.4.6. Aborting upgrade.

直接重跑同一命令即可续装：脚本幂等，前七步检测到已就绪即跳过（.env 自动备份合并），随后完成拉取与启动。重跑实测（节选）：

============================================================
[2026-10-21 08:03:56] Step 8/9: Pulling images
============================================================

3/6 Pulling Docker images...
     This may take a few minutes depending on your connection.
     - Pulling docker.io/coollabsio/coolify-helper:1.0.17...
     - Pulling docker.io/coollabsio/coolify:4.4.6...
     - Pulling postgres:15-alpine...
     - Pulling redis:7-alpine...
     All images pulled successfully.
[2026-10-21 08:04:08] Step 8/9 completed in 12.1s

============================================================
[2026-10-21 08:04:08] Step 9/9: Starting Coolify
============================================================
 - Waiting for Coolify to be ready...
 - Upgrade in progress: Starting new containers (0s)
 - Upgrade in progress: Starting new containers (10s)
 - Upgrade in progress: Starting new containers (20s)
 - Upgrade in progress: Starting new containers (30s)
 - Upgrade in progress: Starting new containers (40s)
 - Upgrade in progress: Starting new containers (50s)
 - Upgrade in progress: Starting new containers (60s)
 - Upgrade in progress: Starting new containers (70s)
 - Upgrade in progress: Starting new containers (80s)
[2026-10-21 08:05:36] Upgrade completed: Upgrade complete
 - Upgrade complete!
 - Verifying Coolify is healthy...

⚠️ 注意：重跑实测在末尾健康校验处出现 ERROR: Coolify container is not healthy after 60s. Status: starting——平台服务启动超过脚本内置的 60 秒校验窗，属启动慢而非故障，随后服务自然转为 healthy（用 4.5 节 docker compose ps 与 curl /api/health 复核即可），完整定位过程见问题 8；首装拉取失败的处置见问题 7。

💡 说明：Step 6 的 APP_ID/APP_KEY/DB_PASSWORD/REDIS_PASSWORD/PUSHER_* 均由脚本用 openssl 自动生成（APP_KEY 形如 base64:...），无需手工填写；预置的管理员三项取自 4.2 节导出的环境变量。

4.5 部署结果验证

安装完成后编排文件与配置就位，ls -la /data/coolify/source 实测清单：

/data/coolify/source/:
total 88
drwx------  2 9999 root  4096 Oct 21 08:05 .
drwx------ 11 9999 root  4096 Oct 21 07:45 ..
-rw-r--r--  1 root root   730 Oct 21 08:04 .env
-rwx------  1 9999 root   689 Oct 21 08:03 .env-20261021-080354
-rwx------  1 9999 root   212 Oct 21 08:03 .env.production
-rwx------  1 9999 root  2971 Oct 21 08:03 docker-compose.prod.yml
-rwx------  1 9999 root   726 Oct 21 08:03 docker-compose.yml
-rwx------  1 9999 root  4970 Oct 21 07:46 installation-20261021-074529.log
-rwx------  1 9999 root  5545 Oct 21 08:06 installation-20261021-080354.log
-rwx------  1 9999 root  3689 Oct 21 07:46 upgrade-2026-10-21-07-46-15.log
-rw-r--r--  1 root root  5890 Oct 21 08:05 upgrade-2026-10-21-08-03-56.log
-rwx--x--x  1 9999 root 13162 Oct 21 08:03 upgrade-postgres.sh
-rwx------  1 9999 root 13661 Oct 21 08:03 upgrade.sh

💡 说明：.env-20261021-080354 是重跑时脚本自动备份的旧 .env（时间戳命名），installation-*.log 与 upgrade-*.log 是安装/升级全程日志，排障时优先翻这里；upgrade-postgres.sh 是官方附带的数据库小版本升级脚本。

编排状态验证（三条命令均在 /data/coolify/source 下执行）：

cd /data/coolify/source
docker compose ls

NAME                STATUS              CONFIG FILES
source              running(3)          /data/coolify/source/docker-compose.yml,/data/coolify/source/docker-compose.prod.yml

docker compose --env-file /data/coolify/source/.env -f docker-compose.yml -f docker-compose.prod.yml ps

NAME            IMAGE                                COMMAND                  SERVICE    CREATED          STATUS                   PORTS
coolify         docker.io/coollabsio/coolify:4.4.6   "docker-php-serversi…"   coolify    9 minutes ago    Up 9 minutes (healthy)   8000/tcp, 8443/tcp, 0.0.0.0:6001-6002->6001-6002/tcp, [::]:6001-6002/tcp, 9000/tcp, 0.0.0.0:8000->8080/tcp, [::]:8000->8080/tcp
coolify-db      postgres:15-alpine                   "docker-entrypoint.s…"   postgres   10 minutes ago   Up 9 minutes (healthy)   5432/tcp
coolify-redis   redis:7-alpine                       "docker-entrypoint.s…"   redis      10 minutes ago   Up 9 minutes (healthy)   6379/tcp

三个服务均 Up (healthy)。再用健康检查端点做应用层验证：

curl -s http://localhost:8000/api/health

OK

浏览器访问 http://<服务器IP>:8000，使用预置账号 root / q1w2e3r4 登录即可进入控制台。

五、部署方案 B：手动编排部署

5.1 方案说明与适用场景

不跑安装脚本，手工完成「目录 → 官方文件 → 网络 → .env → 编排启动」五步。适用：内网无法直连 CDN 需离线导入文件、需要把编排文件纳入自管配置库、或想精确控制每一步的环境。文件与参数与方案 A 完全同源（均取自官方 CDN），效果一致。

5.2 准备目录与官方文件

mkdir -p /data/coolify/source
cd /data/coolify/source
curl -fsSL -L https://cdn.coollabs.io/coolify/docker-compose.yml -o docker-compose.yml
curl -fsSL -L https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o docker-compose.prod.yml
curl -fsSL -L https://cdn.coollabs.io/coolify/.env.production -o .env.production
curl -fsSL -L https://cdn.coollabs.io/coolify/upgrade.sh -o upgrade.sh
chmod +x upgrade.sh

四个地址即安装脚本源码中的官方 CDN 常量（CDN="https://cdn.coollabs.io/coolify"，脚本第 18 行），与方案 A 下载的文件逐字节一致。

5.3 创建编排网络与生成 .env

官方编排使用外部网络 coolify，先创建（命令取自官方 upgrade.sh 的网络保障逻辑）：

docker network create --attachable coolify

复制官方模板并补齐密钥（生成命令逐条取自安装脚本源码第 1024–1031 行，与方案 A 自动生成的算法一致）：

cd /data/coolify/source
cp .env.production .env
sed -i "s|^APP_ID=.*|APP_ID=$(openssl rand -hex 16)|" .env
sed -i "s|^APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|" .env
sed -i "s|^DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|" .env
sed -i "s|^REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|" .env
sed -i "s|^PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|" .env
sed -i "s|^PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|" .env
sed -i "s|^PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|" .env

再补齐管理员与版本锁定项（方案 A 由脚本写入，这里手工追加）：

cat >> .env <<'EOF'
ROOT_USERNAME=root
ROOT_USER_EMAIL=root@example.com
ROOT_USER_PASSWORD=q1w2e3r4
PUSHER_BACKEND_PORT=6001
LATEST_IMAGE=4.4.6
COOLIFY_VERSION=4.4.6
EOF

💡 说明：LATEST_IMAGE 与 COOLIFY_VERSION 锁定平台主服务版本为 4.4.6（官方编排以 ${LATEST_IMAGE:-latest} 引用）；不锁定则随官方 latest 标签漂移，生产建议锁定。

5.4 启动编排

启动命令与官方升级流程使用的完全一致（取自官方 upgrade.sh）：

cd /data/coolify/source
docker compose --env-file /data/coolify/source/.env -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans --wait --wait-timeout 60

--wait 会等待三个服务全部通过健康检查（主服务健康检查需同时通过 /api/health 与实时通信 /up 两个探针）。

5.5 验证

与方案 A 相同：docker compose ps 应看到三服务 Up (healthy)，curl -s http://localhost:8000/api/health 返回 OK（回显见 4.5 节）。

六、方案对比与选择建议

维度方案 A：官方脚本方案 B：手动编排
联网要求需访问 get/CDN 与组件仓库同左（可离线导入文件后执行）
步骤数1 条命令（内部 9 步自动）5 步手工
密钥生成脚本自动手工执行 openssl 命令
系统适配自动检测发行版/Docker/SSH需自行保证前置条件
版本控制随官方通道，支持 AUTOUPDATE完全自持，LATEST_IMAGE 锁版本
幂等升级支持（重跑即升级，见问题 1）经官方 upgrade.sh 或重跑 up

选择建议：能联网的生产服务器直接选方案 A（脚本封装了发行版差异与守护进程调优）；离线/强管控环境选方案 B，把四个官方文件纳入内部制品库后按 5.2–5.4 执行。

七、数据持久化说明

Coolify 的持久化分两层，升级/重建后数据均保留：

位置内容形态
/data/coolify/source编排文件、.env、安装与升级日志、upgrade.sh宿主机目录
/data/coolify/ssh平台 SSH 密钥（本机 + 目标服务器）宿主机目录挂载
/data/coolify/applications应用构建产物宿主机目录挂载
/data/coolify/databases数据库备份产物宿主机目录挂载
/data/coolify/services一键服务数据宿主机目录挂载
/data/coolify/backups备份文件宿主机目录挂载
/data/coolify/images上传图片宿主机目录挂载
/data/coolify/proxy、/data/coolify/sentinel反向代理配置、哨兵数据宿主机目录挂载
数据卷 coolify-dbPostgreSQL 数据命名数据卷（compose 声明）
数据卷 coolify-redisRedis 数据命名数据卷（compose 声明）

⚠️ 注意：卸载/重装时 down 若加 --volumes 会同时删除 coolify-db/coolify-redis 两个数据卷，元数据不可恢复；仅重建平台请勿加该参数。宿主机目录 /data/coolify 建议纳入备份计划（至少备份 source/.env 与 ssh 目录）。

八、环境变量表

.env（由 .env.production 模板 + 脚本生成/手工补齐）是 Coolify 唯一配置入口，主服务以只读方式挂载为自身配置文件。逐项说明：

变量示例值说明
APP_ID安装时自动生成（openssl rand -hex 16）应用实例标识
APP_NAMECoolify应用名，控制台标题与通知署名
APP_KEY安装时自动生成（base64:$(openssl rand -base64 32)）Laravel 加密根密钥，更换后既有加密数据不可解
APP_ENVproduction运行环境（生产编排默认注入 production）
APP_PORT8000Web/API 对外端口（编排 ${APP_PORT:-8000}:8080 映射，改端口见问题 2）
DB_USERNAMEcoolify元数据库用户（官方固定值，勿改，改名会导致初始化失败）
DB_PASSWORD安装时自动生成（openssl rand -base64 32）元数据库密码
DB_DATABASEcoolify元数据库库名（缺省 coolify）
REDIS_PASSWORD安装时自动生成（openssl rand -base64 32）Redis 访问密码（编排以 --requirepass 注入）
PUSHER_APP_ID / PUSHER_APP_KEY / PUSHER_APP_SECRET安装时自动生成（openssl rand -hex 32）实时通信（Reverb）三件套凭据
PUSHER_BACKEND_PORT6001实时通信后端监听端口
ROOT_USERNAME / ROOT_USER_EMAIL / ROOT_USER_PASSWORDroot / root@example.com / q1w2e3r4预置管理员（仅首次初始化生效，改密用命令篇的 root:reset-password）
REGISTRY_URLdocker.io组件仓库地址（内网仓库可指向自建地址）
DOCKER_ADDRESS_POOL_BASE10.0.0.0/8Docker 网络地址池基址（写入守护进程配置）
DOCKER_ADDRESS_POOL_SIZE24地址池规模
LATEST_IMAGE4.4.6平台主服务版本锁定
COOLIFY_VERSION4.4.6版本标识

💡 说明：密钥类变量均由 openssl 生成命令自动填充（见 4.4 节 Step 6 回显与 5.3 节命令），人工只需关心 ROOT_*、APP_PORT、DOCKER_ADDRESS_POOL_* 与版本锁定项。各变量在平台内部更深层的行为（队列、会话、日志通道等派生配置）见 《Coolify 4.4.6 配置参数详解》。

九、编排文件与挂载说明

方案 A/B 落地的两份官方编排文件如下（官方 CDN 原文，4.4.6 版）。基础编排 docker-compose.yml：

services:
    coolify:
        container_name: coolify
        restart: always
        working_dir: /var/www/html
        extra_hosts:
            - host.docker.internal:host-gateway
        expose:
            - "6001"
            - "6002"
        networks:
            - coolify
        depends_on:
            - postgres
            - redis
    postgres:
        image: postgres:15-alpine
        container_name: coolify-db
        restart: always
        networks:
            - coolify
    redis:
        image: redis:7-alpine
        container_name: coolify-redis
        restart: always
        networks:
            - coolify
networks:
    coolify:
        name: coolify
        driver: bridge
        external: false

生产覆盖编排 docker-compose.prod.yml（关键字段节选，完整文件 2.9KB）：

services:
  soketi:
    image: busybox:1.37
    profiles:
      - legacy-soketi
  coolify:
    image: "${REGISTRY_URL:-docker.io}/coollabsio/coolify:${LATEST_IMAGE:-latest}"
    volumes:
      - type: bind
        source: /data/coolify/source/.env
        target: /var/www/html/.env
        read_only: true
      - /data/coolify/ssh:/var/www/html/storage/app/ssh
      - /data/coolify/applications:/var/www/html/storage/app/applications
      - /data/coolify/databases:/var/www/html/storage/app/databases
      - /data/coolify/services:/var/www/html/storage/app/services
      - /data/coolify/backups:/var/www/html/storage/app/backups
      - /data/coolify/images:/var/www/html/storage/app/images
    ports:
      - "${APP_PORT:-8000}:8080"
      - "${REVERB_PORT:-${SOKETI_PORT:-6001}}:6001"
      - "6002:6002"
    env_file:
      - /data/coolify/source/.env
    healthcheck:
      test: curl --fail http://127.0.0.1:8080/api/health && curl --fail http://127.0.0.1:${PUSHER_BACKEND_PORT:-6001}/up || exit 1
      interval: 5s
      retries: 24
      start_period: 1m
      timeout: 2s
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
  postgres:
    volumes:
      - coolify-db:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U ${DB_USERNAME}", "-d", "${DB_DATABASE:-coolify}" ]
  redis:
    command: redis-server --save 20 1 --loglevel warning --requirepass ${REDIS_PASSWORD}
    volumes:
      - coolify-redis:/data
volumes:
  coolify-db:
    name: coolify-db
  coolify-redis:
    name: coolify-redis
networks:
  coolify:
    external: true

逐项解读：

  • 两文件叠加：-f docker-compose.yml -f docker-compose.prod.yml 前者定骨架、后者做生产覆盖（端口映射、健康检查、挂载、凭据注入均来自后者）；网络在生产形态下转为 external: true，由 5.3 节命令预建。
  • .env 只读挂载：主服务配置以只读方式挂到 /var/www/html/.env，同时经 env_file 注入进程环境，改配置必须改宿主机 /data/coolify/source/.env 后重建服务。
  • 健康检查：主服务 5 秒一次、需连续通过 Web 探针（/api/health）与实时通信探针（/up），启动宽限期 1 分钟、最多重试 24 次；--wait 参数即依赖该检查判定就绪。
  • soketi 占位：挂 legacy-soketi profile 永不启动，仅为兼容旧版覆盖文件存在，删除它反而会让旧覆盖文件升级失败（文件内官方注释原意）。
  • 端口：${APP_PORT:-8000}:8080 是唯一需要按环境调整的映射；6001/6002 为实时通信，6002 固定。

十、升级与常用运维命令

10.1 升级

升级有两条等价路径。路径一（推荐）：重跑官方安装脚本，检测到已有部署时自动转入升级流程（实测于 2026-10-21，从 4.4.6 前一版本升级到 4.4.6）：

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

实测升级输出（六步，节选）：

==========================================

1/6 Downloading latest configuration files...
     Done.

2/6 Updating environment configuration...
     Done.

3/6 Pulling Docker images...
     This may take a few minutes depending on your connection.
     - Pulling docker.io/coollabsio/coolify-helper:1.0.17...
     - Pulling docker.io/coollabsio/coolify:4.4.6...
     - Pulling postgres:15-alpine...
     - Pulling redis:7-alpine...
     All images pulled successfully.

4/6 Stopping containers and starting new ones...
     This step will restart all Coolify containers.
     Check the log file for details: /data/coolify/source/upgrade-2026-10-21-08-14-40.log

5/6 Containers are being restarted in the background...
6/6 Upgrade process initiated!

==========================================
   Coolify upgrade to 4.4.6 in progress
==========================================

   The upgrade will continue in the background.
   Coolify will be available again shortly.
   Log file: /data/coolify/source/upgrade-2026-10-21-08-14-40.log

路径二：直接调用官方升级脚本（参数：目标版本、helper 版本、仓库地址、是否启动）：

bash /data/coolify/source/upgrade.sh 4.4.6 1.0.17 docker.io true

⚠️ 注意：升级会重启平台三服务并短暂中断控制台，已部署的应用不受影响；升级日志落 /data/coolify/source/upgrade-<时间戳>.log。升级前确认 /data/coolify/source/.env 已备份（脚本会自动备份为 .env-<时间戳>，实测见问题 1）。

10.2 常用运维命令速查

以下命令均在 /data/coolify/source 下执行（COMPOSE 变量仅为行文缩写，逐条展开即可执行）：

cd /data/coolify/source
docker compose ls

NAME                STATUS              CONFIG FILES
source              running(3)          /data/coolify/source/docker-compose.yml,/data/coolify/source/docker-compose.prod.yml

查看服务清单与版本组合：

docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml config --services
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml config --images

postgres
redis
coolify

docker.io/coollabsio/coolify:4.4.6
postgres:15-alpine
redis:7-alpine

查看实时日志（平台主服务尾部 3 行，实测）：

docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml logs --tail 3 coolify

coolify  |   2026-10-21 15:11:01 App\Jobs\ServerManagerJob ................. 16.31ms DONE
coolify  |   2026-10-21 15:11:01 App\Jobs\ReconcileGithubRunnersJob ............. RUNNING
coolify  |   2026-10-21 15:11:01 App\Jobs\ReconcileGithubRunnersJob ........ 43.28ms DONE

健康状态复核：

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

healthy

重启/停止/启动编排（改动 .env 后使配置生效的标准动作）：

docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml restart
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml down --remove-orphans
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans --wait --wait-timeout 60

自动更新机制：平台内置每日更新检查（计划任务 App\Jobs\UpdateCoolifyJob，cron 0 0 * * *，实测于 php artisan schedule:list，完整任务表见命令篇），默认发现新版本即自动走升级流程；不希望自动升级时在 .env 设 AUTOUPDATE=false。

💡 更多平台内部命令（artisan 运维、REST API 调用实测）见 《Coolify 4.4.6 常用 CLI 命令与工具详解》。

十一、常见问题（排障实录）

问题 1：重复执行安装脚本会怎样？会不会覆盖配置？

实测（2026-10-21 同日两次执行）：脚本检测到已有部署自动转入升级流程，.env 先备份再合并，人工配置项全部保留。回显：

 - Creating backup of existing .env file to .env-20261021-080354
 - Merging .env.production values into .env
 - .env file merged successfully

合并算法为「已有键保留原值、新键追加」（脚本内 awk -F '=' '!seen[$1]++'），因此自加的 APP_PORT、版本锁定项不会被官方模板覆盖。

问题 2：8000 端口被占用如何改端口？

生产编排的端口映射是 ${APP_PORT:-8000}:8080，在 /data/coolify/source/.env 中增加一行（如 APP_PORT=8400），随后执行 10.2 节的 down + up 重建即可；.env 变更不会被升级覆盖（见问题 1）。

问题 3：Docker 网络地址池与现有环境冲突？

脚本检测到已有地址池配置时不强行覆盖，实测回显：

Found existing Docker network pool: 10.0.0.0/8/24
 - To override existing configuration: DOCKER_POOL_FORCE_OVERRIDE=true

需要强制覆盖时以 DOCKER_POOL_FORCE_OVERRIDE=true 环境变量重跑脚本，并可用 DOCKER_ADDRESS_POOL_BASE/DOCKER_ADDRESS_POOL_SIZE 指定新池。

问题 4：SSH 连不上目标服务器？

平台依赖目标服务器 SSH 可达。脚本检测到 PermitRootLogin 未开启时明确告警（脚本内置提示原文）：

SSH PermitRootLogin is disabled. If you have problems with SSH, read https://coolify.io/docs/knowledge-base/server/openssh

按官方知识库（上述链接）开启 root 或专用部署用户的 SSH 登录后，在控制台「Servers」重新校验即可。

问题 5：控制台一直显示启动中/健康检查不过？

主服务健康检查需同时通过 /api/health 与实时通信 /up 两个探针（编排定义见第九章）。先看应用日志定位：

docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml logs --tail 50 coolify

常见根因：.env 中密钥项被手工清空（APP_KEY 为空会导致服务起不来）、PUSHER_BACKEND_PORT 与 6001 映射不一致、数据库未就绪（depends_on 已强制 postgres/redis 先过健康检查，一般无需处理）。

问题 6：首次登录用哪个账号？

预置了 ROOT_* 三变量时用预置账号（本文 root / q1w2e3r4）；未预置时首次访问 http://<服务器IP>:8000 会进入注册页，注册的第一个账号即管理员。密码遗忘用平台内置命令重置：docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml exec coolify php artisan root:reset-password（交互式，实测帮助回显见命令篇）。

问题 7：Step 8 报 ERROR: Failed to pull ... Aborting upgrade.？

组件拉取依赖外网，实测首装即遇网络抖动导致主服务制品拉取失败、脚本中止：

     - Pulling docker.io/coollabsio/coolify:4.4.6...
     ERROR: Failed to pull docker.io/coollabsio/coolify:4.4.6. Aborting upgrade.

处置：确认服务器可访问组件仓库后直接重跑同一命令。脚本幂等——已完成的依赖安装、SSH/Docker 检查、.env 生成等步骤自动跳过，且 .env 先备份后合并不丢配置；重跑后拉取与启动正常完成（回显见 4.4 节）。弱网环境可配置仓库加速地址后经 REGISTRY_URL 指向。

问题 8：安装末尾报 Coolify container is not healthy after 60s. Status: starting？

脚本 Step 9 内置 60 秒健康校验窗，低配服务器上平台服务完成初始化（数据库迁移、队列启动）可能超过该窗口。实测处置与结论：

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

healthy

等待约 1~2 分钟后复核，实测由 starting 转为 healthy，curl -s http://localhost:8000/api/health 返回 OK，无需任何干预。仅当持续 10 分钟以上仍 starting/unhealthy 才需按问题 5 查日志定位。

十二、卸载与清理

按需选择清理深度（命令在 /data/coolify/source 下执行）：

cd /data/coolify/source
# 1. 停止并移除编排（保留数据卷与 /data/coolify，可随时重新 up 恢复）
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml down --remove-orphans
# 2. 连同数据卷一并删除（元数据库与 Redis 数据清空，不可恢复）
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml down --remove-orphans --volumes
# 3. 彻底清理：删除编排网络与部署目录
docker network rm coolify
rm -rf /data/coolify

第 1 步实测回显（三服务逐一停止并移除，数据卷与部署目录保留）：

 Container coolify Stopping
 Container coolify Stopped
 Container coolify Removing
 Container coolify Removed
 Container coolify-db Stopping
 Container coolify-redis Stopping
 Container coolify-db Stopped
 Container coolify-db Removing
 Container coolify-redis Stopped
 Container coolify-redis Removing
 Container coolify-redis Removed
 Container coolify-db Removed

第 1 步仅停服，数据全保留；第 2 步追加删除 coolify-db/coolify-redis 两个命名数据卷；第 3 步从磁盘上彻底移除。彻底卸载后如需重装，直接重跑第 4.3 节安装命令即可（会重新走完整九步）。

十三、参考链接

  1. 官方安装文档：https://coolify.io/docs/installation （查询日期 2026-10-21）
  2. 安装脚本源码：https://github.com/coollabsio/coolify/blob/v4.x/scripts/install.sh （2026-10-21 运行留存于 /data/coolify/source）
  3. 官方 CDN（编排文件与升级脚本）：https://cdn.coollabs.io/coolify （查询日期 2026-10-21）
  4. OpenSSH 知识库：https://coolify.io/docs/knowledge-base/server/openssh （查询日期 2026-10-21）
  5. 本专栏同系列：《Coolify 介绍与选型指南》、《Coolify 4.4.6 配置参数详解》、《Coolify 4.4.6 常用 CLI 命令与工具详解》