Coolify：自托管 PaaS（Heroku 平替）一键部署应用与数据库｜部署与使用全指南

本文基于 Coolify 官方 GitHub 仓库（main 分支）、官方文档 https://coolify.io/docs 以及安装脚本/编排文件（scripts/install.sh、docker-compose.yml、docker-compose.prod.yml、.env.production）的当前真实状态撰写。文中所有命令、端口、路径、环境变量均来自官方源码，可直接照搬。
状态说明（截至 2026-10）：Coolify 的稳定可安装版本为 v4 系列（当前稳定版约 v4.3.x，v4.4 处于 RC 阶段）；v5 是一次完全重写的长期计划（2025-04 宣布），截至本文撰写仍处开发阶段，尚未发布稳定版。因此本教程以 v4 为准，v4→v5 的自动迁移将在 v5 稳定后随升级流程提供（见第十章）。

一、项目简介与适用场景

Coolify 是一个开源、可自托管的 PaaS（平台即服务），定位是 Vercel / Heroku / Netlify 的平替。它让你在自己的服务器上通过可视化的 Web 面板，轻松地部署：

静态站点、全栈应用、后台服务；
PostgreSQL / MySQL / Redis / MongoDB / ClickHouse 等数据库；
300+ 个一键服务模板（Appwrite、Grafana、WordPress、Jellyfin……）。

你只需要一台能 SSH 登录的 Linux 服务器，Coolify 会替你完成构建、反向代理（Traefik）、自动 HTTPS（Let’s Encrypt）、环境变量管理、日志查看、备份等脏活累活。你的应用以 Docker 容器方式运行，配置留在你自己的服务器上——即便你停用 Coolify，已经跑起来的业务依然在运行、依然可管理。

适用场景

场景	是否适合	说明
个人 / 小团队想把多个网站、API、数据库集中托管到自己的 VPS	✅ 非常适合	一条命令装好，Web 面板统一管理
想摆脱 Vercel/Heroku 的按量计费、带宽费、构建费	✅ 适合	自带服务器，无平台抽成
需要自动 HTTPS、反向代理、分支预览	✅ 适合	Traefik + Let’s Encrypt 默认开箱即用
大规模、强 SLA、多区域高可用生产	⚠️ 谨慎	v4 为单控制面 + 远程 Docker 模型，规模化与高可用仍在 v5 路线图中
完全不会 Linux / 不想维护服务器	⚠️ 考虑 Coolify Cloud	官方托管版帮你运维控制面

不适合的场景提示

你连 SSH、防火墙、域名解析都不想碰 → 直接用 Coolify Cloud。
你执着于 Kubernetes 编排、多集群调度 → Coolify 的默认心智模型是「远程管理的普通 Docker」，不是 K8s（v5 才把扩展性作为核心目标）。

二、核心功能逐条拆解

以下能力均来自官方 README「What can Coolify do?」与文档，逐条说明：

部署任意应用（Deploy any application） 支持从 GitHub / GitLab / Bitbucket / Gitea 拉取源码，构建方式涵盖 Nixpacks、Railpack、Dockerfile、Docker Compose、预构建 Docker 镜像。也就是说「只要能被 Docker 打包，Coolify 就能跑」。
运行数据库与服务（Run databases and services） 内置 300+ 一键服务模板，自动创建持久化存储并生成凭据；数据库支持 PostgreSQL、MySQL、Redis、MongoDB、ClickHouse 等。
自动化部署（Automate deployments） 每次 Git push 自动触发构建部署；可创建 PR 预览环境；支持 Webhook 触发部署；并可回滚到保留的历史应用镜像。
网络管理（Manage networking） 配置自定义域名、自动 HTTPS 证书、反向代理、健康检查、容器网络。默认入口是 Traefik v3，证书由 Let’s Encrypt 自动签发续期。
基础设施运维（Operate your infrastructure） 管理多台服务器；查看部署日志与运行时日志；打开容器终端；监控资源状态。
工作负载保护（Protect your workloads） 配置数据库与存储备份（可备份到 S3 兼容对象存储，如 Backblaze、Cloudflare R2、Hetzner Object Storage、自建 MinIO）、定时任务、环境变量、密钥、通知。
工作流集成（Integrate with your workflow） 通过 Dashboard、API、CLI、MCP 管理资源，并支持基于团队的访问控制。

架构要点：Coolify 本身是一个 Laravel 应用，通过 SSH 在远程服务器上编排 Docker 容器。安装 Coolify 的节点成为「控制面」，你部署的每台服务器是「目标」。每个应用最终都会落成一个可查看、可复制的 docker-compose.yml——没有黑魔法，出问题时你能直接看懂运行状态。

三、全套官方链接

类型	地址	备注
GitHub 仓库	https://github.com/coollabsio/coolify	主仓库，源码与 Issue/Discussions
官方文档	https://coolify.io/docs	安装、部署、运维全量文档
官方主页	https://coolify.io	产品介绍、定价、哲学
License	Apache-2.0（仓库 `LICENSE` 文件）	商用友好，详见第十一章
在线 Demo	无	官方不提供公开 Demo，需自行安装；可用 Coolify Cloud 体验托管版
社区支持	Discord（coolify.io/docs/support）、GitHub Discussions	提问与报障
版本信息（CDN）	https://cdn.coollabs.io/coolify/versions.json	查询最新可安装版本号
安装脚本	https://cdn.coollabs.io/coolify/install.sh	一键安装脚本源码可审阅
Coolify Cloud	https://app.coolify.io	官方托管控制面（付费）

四、硬件与环境前置要求

以下来自官方文档「Start with Self-hosted → Before you begin」。

4.1 一台 Linux 服务器

你需要一台能通过 SSH 访问的服务器，可以是：

VPS（任意云厂商）；
独立物理服务器（bare-metal）；
自有 Linux 虚拟机；
Raspberry Pi（64 位）；
甚至一台旧的、带 SSH 的 Linux 笔记本。

官方建议使用全新（fresh）服务器安装 Coolify，避免与已有应用（如已占用 80/443 的 Nginx）冲突。

4.2 推荐硬件配置

项目	最低要求	官方说明
CPU	2 核	同一台机器上跑多个业务时建议加核
内存	2 GB RAM	随业务增长增加
磁盘	10 GB 可用空间	另需为 Docker 镜像、卷、备份留空间
架构	amd64 或 arm64	Raspberry Pi OS 安装必须用 arm64（64 位镜像）

预算极低场景（不推荐，仅能跑得动）：1 核 / 512 MB / 4 GB。官方提示：若成本敏感，可从 1 核 1 GB 起步，随业务增长再升级服务器规格。

生产参考：官方文档给出的一个真实样例——单台 Hetzner CAX11（2 vCPU / 4 GB / 40 GB）即稳定运行 16 个静态站点、9 个 Rust API、5 个全栈应用、4 个 Discord bot、7 个 worker、2 个 Valkey、1 个 PostgreSQL，外加 Coolify 自身与 Beszel 监控。

4.3 支持的操作系统

系列	发行版	备注
Debian 系	Debian、Ubuntu	Ubuntu 非 LTS 请走手动安装；推荐 20.04 / 22.04 / 24.04 LTS
Red Hat 系	CentOS、Fedora、RHEL、AlmaLinux、Rocky、TencentOS、Asahi	部分变体需手动预装 Docker
SUSE 系	SLES、SUSE、openSUSE	支持
Arch 系	Arch Linux	支持
Alpine 系	Alpine Linux	支持（使用 OpenRC，非 systemd）
树莓派	Raspberry Pi OS（64-bit）	必须用 64 位镜像

Coolify 仅运行在 Linux。非 Linux 系统可通过 Linux 虚拟机间接运行。安装脚本需要 root 或具备 sudo 权限的账户。

4.4 Docker 要求

必须安装 Docker Engine（不是 snap 版 Docker Desktop）。若检测到 snap 安装的 Docker，安装脚本会提示移除并按官方方式重装，或自动处理。
安装脚本会自动安装/配置 Docker；你也可先手动装好 Docker Engine（见 docs.docker.com/engine/install）。
Coolify 通过 Docker 的 default-address-pools 管理容器网络，安装脚本会按需写入 /etc/docker/daemon.json（默认 10.0.0.0/8，size 24）。若与既有网络规划冲突，可用环境变量 DOCKER_ADDRESS_POOL_BASE / DOCKER_ADDRESS_POOL_SIZE 自定义。

4.5 域名与端口

端口	用途	是否必须开放
22/TCP	SSH（Coolify 通过 SSH 管理服务器）	✅ 必须
80/TCP	HTTP 与 Let’s Encrypt 证书签发（ACME http-01 挑战）	✅ 必须（公网部署域名时）
443/TCP	HTTPS（反向代理 Traefik 入口）	✅ 必须（生产）
8000/TCP	Coolify 控制面 Web 面板	✅ 必须（访问后台）
6001/TCP	实时通信（Reverb/Soketi）	视需要（站内实时更新）
6002/TCP	实时通信辅助端口	视需要

绑域名并启用 HTTPS 时，80 与 443 必须能被公网访问，否则 Let’s Encrypt 无法完成证书签发。云厂商侧的安全组与系统防火墙（ufw/firewalld）都要放行。

4.6 SSH 要求

服务器需开启 OpenSSH，且 Coolify 所在节点能通过 root 或 sudo 账户 SSH 连上目标服务器（包括它自己 localhost）。
安装脚本会自动生成一条 ed25519 密钥并写入 authorized_keys，供 Coolify 以 host.docker.internal 身份连接本机。

五、多平台部署实战

5.1 官方一键脚本安装（推荐）

SSH 进入服务器，以 root（或 sudo）执行：

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

安装脚本会自动完成：安装 Docker、创建数据目录 /data/coolify、生成 SSH 密钥、拉取 coolify / postgres / redis / helper 镜像、启动容器并等待健康检查通过。

预创建管理员账户（避免公开注册被抢注）：

# root 用户直接执行
env ROOT_USERNAME=RootUser \
    ROOT_USER_EMAIL=example@example.com \
    ROOT_USER_PASSWORD='StrongPassword123!' \
    bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'

# 非 root 用户
sudo -E env ROOT_USERNAME=RootUser \
    ROOT_USER_EMAIL=example@example.com \
    ROOT_USER_PASSWORD='StrongPassword123!' \
    bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'

密码规则：至少 8 位，含大写、小写、数字、特殊符号。

安装完成后终端会打印类似：

Public IPv4   http://203.0.113.10:8000

打开该地址即可创建管理员账户（若未预创建，则谁先注册谁就是管理员，请尽快完成）。随后务必备份 /data/coolify/source/.env。

5.2 Docker / Docker Compose 安装（手动）

适合已有 Docker、非 root、或想完全掌控网络/卷/密钥的场景。核心是把编排文件放到 /data/coolify/source 再 docker compose up：

# 1. 准备目录与 .env
mkdir -p /data/coolify/source
cd /data/coolify/source

# 2. 下载编排文件（base + prod）
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/coollabsio/coolify/main/docker-compose.yml
curl -fsSL -o docker-compose.prod.yml https://raw.githubusercontent.com/coollabsio/coolify/main/docker-compose.prod.yml

# 3. 生成 .env（可基于仓库 .env.production 模板补全 APP_KEY 等）
cp /path/to/.env.production .env
# 至少填写 APP_KEY（用 `php -r "echo base64_encode(random_bytes(32));"` 之类生成）、DB/Redis 密码

# 4. 启动
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

手动安装同样需要 root 或 docker 组权限，且需自行保证 /data/coolify 下各子目录（applications/databases/backups/services/proxy/sentinel/ssh）的权限正确。生产环境推荐直接用 5.1 的一键脚本，它会处理好这些细节。

5.3 源码安装（开发 / 二次开发）

适合想改代码、跑测试、提 PR 的开发者。需要 PHP、Composer、Node/Bun、Docker 等完整工具链：

git clone https://github.com/coollabsio/coolify.git
cd coolify
git checkout v4.x          # 跟踪稳定分支

composer install --no-dev --optimize-autoloader
npm install && npm run build   # 或 bun install / bun run build

cp .env.production .env
# 编辑 .env，配置 APP_KEY、数据库连接、Redis 等
php artisan key:generate
php artisan migrate --force

# 本地开发用 dev compose
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

源码安装仅用于开发，生产请使用 5.1 / 5.2 的容器化方式。

5.4 Raspberry Pi OS 安装

必须用 64 位（arm64） 的 Raspberry Pi OS 镜像。其余步骤同一键脚本（5.1）；确保 Docker 为 arm64 构建且磁盘空间充足。

六、配置文件参数全解

Coolify 的实例配置位于 /data/coolify/source/.env（由安装脚本生成）。下方变量来自官方 .env.production 模板、docker-compose.prod.yml 与环境变量文档。

6.1 核心身份与实例变量

变量	默认值	说明
`APP_NAME`	`Coolify`	实例显示名称
`APP_ID`	空	实例唯一标识
`APP_KEY`	空（安装时生成）	加密密钥，用于加密数据库中的敏感值。丢失则无法还原备份，务必备份
`APP_URL`	空	实例对外访问地址（如 `https://coolify.yourdomain.com`），用于回调、Webhook、邮件链接等
`APP_ENV`	`production`	运行环境
`APP_PORT`	`8000`	控制面宿主端口：映射到容器内的 8080（`${APP_PORT:-8000}:8080`）。改端口就改这里
`REVERB_PORT` / `SOKETI_PORT`	`6001`	实时通信（WebSocket）对外端口；内部容器端口固定 6001
`PUSHER_BACKEND_PORT`	`6001`	实时后端端口（容器内）

6.2 数据库与缓存（Coolify 自身用）

变量	默认值	说明
`DB_USERNAME`	`coolify`	内置 Postgres 用户名
`DB_PASSWORD`	空（安装生成）	内置 Postgres 密码
`DB_DATABASE`	`coolify`	内置数据库名
`REDIS_PASSWORD`	空（安装生成）	内置 Redis 密码
`REGISTRY_URL`	`docker.io`	拉取 Coolify 镜像的镜像源；可改为 `ghcr.io` 等

6.3 实时通信（Pusher/Reverb）

变量	说明
`PUSHER_APP_ID`	实时通道应用 ID
`PUSHER_APP_KEY`	实时通道 Key
`PUSHER_APP_SECRET`	实时通道 Secret

v4.4 起实时通信已内置进 coolify 容器（早期版本用独立的 coolify-realtime / soketi 容器）。升级脚本会保留兼容别名 coolify-realtime。

6.4 预创建管理员（安装期环境变量，非持久项）

变量	说明
`ROOT_USERNAME`	3–255 字符，允许字母/数字/空格/下划线/连字符
`ROOT_USER_EMAIL`	合法邮箱（需有有效 DNS）
`ROOT_USER_PASSWORD`	≥8 位，含大小写+数字+特殊符号

6.5 PHP 与 Worker（影响 Coolify 自身性能）

变量	默认值	说明
`PHP_MEMORY_LIMIT`	`256M`	单个 PHP 脚本内存上限（区别于容器内存限制）
`PHP_FPM_PM_CONTROL`	`dynamic`	FPM 进程管理模式：`dynamic`/`ondemand`/`static`
`PHP_FPM_PM_START_SERVERS`	`1`	启动时 worker 数
`PHP_FPM_PM_MIN_SPARE_SERVERS`	`1`	最小空闲 worker
`PHP_FPM_PM_MAX_SPARE_SERVERS`	`10`	最大空闲 worker

6.6 调度与自动更新

变量	默认值	说明
`SCHEDULED_JOBS_DISPATCH_MODE`	`sequential`	每分钟调度检查备份/任务/卷备份/清理：`sequential`（最低资源，但慢任务会拖住其他）或 `concurrent`（每类一个进程，资源占用高）
`AUTOUPDATE`	未设	设为 `false` 关闭自动更新；设置后仪表盘的「自动更新」开关不可用

6.7 Docker 网络池（安装期/可持久）

变量	默认值	说明
`DOCKER_ADDRESS_POOL_BASE`	`10.0.0.0/8`	Docker 默认地址池基址，避免与既有内网网段冲突
`DOCKER_ADDRESS_POOL_SIZE`	`24`	地址池大小（16–28）
`DOCKER_POOL_FORCE_OVERRIDE`	`false`	是否强制覆盖已有地址池配置

⚠️ APP_KEY、各密码等密钥类变量丢失无法重置，务必在装好后把 /data/coolify/source/.env 备份到服务器之外（密码管理器/对象存储）。修改 .env 后需按第七章「重新加载配置」使其生效，单纯 docker restart coolify 不会重读环境变量。

七、启动 / 后台常驻 / 开机自启 / 改端口教程

7.1 安装后如何「后台常驻」

Coolify 以 Docker 容器运行。编排文件中 coolify / coolify-db / coolify-redis 三个服务均设置了：

restart: always

这意味着容器崩溃或 Docker 守护进程重启后会自动拉起。你无需手动 nohup/后台挂起——docker compose up -d 本身就是「后台常驻」。

7.2 开机自启（重启服务器后自动恢复）

Coolify 没有单独的 systemd unit 文件，而是依赖 Docker 守护进程的开机自启：安装脚本会执行 systemctl enable docker（并 systemctl start docker）。由于 Docker 开机自启，且容器内 restart: always，因此整机重启后 Coolify 会自动恢复。

确认 Docker 已开机自启：

systemctl is-enabled docker
# 期望输出：enabled

# 若未启用：
systemctl enable docker
systemctl start docker

常用运维命令：

docker ps -a | grep coolify          # 查看 Coolify 相关容器状态
docker logs --tail 100 coolify       # 查看控制面日志
docker logs --tail 100 coolify-db    # 查看数据库日志
systemctl status docker              # 查看 Docker 守护进程

7.3 修改控制面端口

默认面板在宿主 8000。如需改成例如 3000：

# 1. 备份
cp /data/coolify/source/.env /data/coolify/source/.env.backup

# 2. 在 .env 中追加/修改
nano /data/coolify/source/.env
# 加入：APP_PORT=3000

# 3. 重建 coolify 容器使其生效（保留当前镜像与自定义 override）
cd /data/coolify/source || exit 1
coolify_image=$(docker inspect --format '{{.Config.Image}}' coolify) || exit 1
compose_files=(-f docker-compose.yml -f docker-compose.prod.yml)
if [ -f docker-compose.custom.yml ]; then
  compose_files+=(-f docker-compose.custom.yml)
fi
docker compose "${compose_files[@]}" -f - up -d --no-deps --force-recreate coolify <<EOF
services:
  coolify:
    image: "$coolify_image"
EOF

之后访问 http://<服务器IP>:3000。注意：只改 APP_PORT 改的是控制面端口；业务应用的域名/端口在应用设置里单独配置（见第八章）。

切勿直接改 docker-compose.prod.yml 来改默认值——安装/升级脚本可能覆盖它。需要持久自定义端口映射、资源限制、挂载，请使用 /data/coolify/source/docker-compose.custom.yml（Compose override）。

7.4 自定义端口/资源的「永久 override」

把自定义放进 docker-compose.custom.yml，升级时会被自动并入：

services:
  coolify:
    mem_limit: 1g
    ports:
      - "3000:8080"

八、功能实操教程

以下流程对应官方「Deploy your first app / database」指南，以仪表盘（Dashboard）操作为准。

8.1 首次登录与连接服务器

浏览器打开 http://<服务器IP>:8000。
创建/登录管理员账户（若安装时已预创建则直接登录）。
左侧边栏打开 Servers，确认至少有一台服务器（自托管默认 localhost 已就绪）。
打开该服务器页面，确认 Proxy is running（Traefik）。若显示已停止，点击 Start Proxy。

反向代理是应用能被域名/HTTPS 访问的前提。

8.2 部署第一个应用（以 Nginx 镜像为例）

最快验证端到端可用的方式——用现成镜像，无需 Git 仓库：

仪表盘点击 New Project，输入项目名（如 my-first-project），点 Continue。
进入项目，点击 Create New Resource。
部署类型选择 Docker Image。
镜像字段填入 nginx:alpine，进入配置页。
网络设置 Ports Exposes 填 80（Nginx 容器内监听 80）。
域名：首次测试可直接用自动生成的 http://<uuid>.<服务器IP>.sslip.io 域名（无需 DNS）；生产则填入自己的域名并指向服务器 IP。
点击 Deploy。Coolify 会拉取镜像、启动容器、接入代理。
部署完成后打开应用 URL，看到 Nginx 默认欢迎页即成功。

8.3 部署第一个数据库（以 Redis 为例）

进入项目，点击 Create New Resource。
在资源列表搜索 Redis 并点击，Coolify 会生成凭据、存储、网络与连接信息。
端口映射填 6380:6379（宿主机 6380 → 容器 6379），用于终端测试。
在防火墙/安全组放行 TCP 6380（测试完建议关闭或仅对自己 IP 开放）。
点击 Start 启动 Redis，从仪表盘复制生成的密码。
本地终端测试：

redis-cli --user default -h <服务器IP> -p 6380 -a "<redis密码>"
# 进入后执行
PING
# 返回 PONG 即成功

没有 redis-cli 时，用临时容器测试：

docker run --rm -it redis:alpine redis-cli --user default -h <服务器IP> -p 6380 -a "<redis密码>" PING

8.4 绑定域名与自动 SSL

在应用设置中将域名改为你的域名（如 app.example.com）。
确保该域名的 A 记录指向服务器公网 IP，且服务器 80/443 已对公网开放。
开启 Automatic HTTPS（默认开启，基于 Let’s Encrypt）。
重新 Deploy。Coolify 通过 Traefik + ACME 自动签发并续期证书，访问 https://app.example.com 即为 HTTPS。

证书签发失败最常见原因是：80 端口被占用/被防火墙挡住、域名未正确解析、或 Let’s Encrypt 触发速率限制（见第九章）。

8.5 设置环境变量

应用级环境变量：在应用设置页的 Environment Variables / Secrets 区域添加，部署时注入容器，用于区分配置、密钥、连接串等。
Coolify 实例级变量：改 /data/coolify/source/.env（见第六、七章），影响的是控制面本身。
数据库的连接信息（host/port/user/password）由 Coolify 在数据库资源页面生成，直接复制到应用环境变量即可。

8.6 进阶：Git 仓库自动部署

选择部署类型为 Git Repository / Public Repository，连接 GitHub/GitLab 等，选择分支，Coolify 用 Nixpacks/Railpack 自动识别语言栈并构建；开启「Deploy on Push」后每次 git push 自动重新部署，PR 还会生成预览环境。

九、全套报错故障排查

以下为社区与官方文档高频问题，按出现频率排列。

9.1 端口冲突（80/443 被占用）

现象：部署应用后无法访问，或代理启动失败；Traefik 报端口绑定错误。排查：sudo ss -tlnp | grep -E ':80|:443' 看是否被 Nginx/Apache 占用。解决：停止冲突服务，或将既有 Web 服务改为监听非 80/443；Coolify 的代理需要独占 80/443。全新服务器安装可避免此问题。

9.2 Docker 权限 / 非 root 问题

现象：安装脚本提示需 root；或 docker 命令报 permission denied。解决：以 root 或 sudo 运行安装；若用普通用户，确保其加入 docker 组（sudo usermod -aG docker $USER，重新登录）。注意 Coolify 容器内进程以 UID 9999 运行，需 /data/coolify 相关目录权限正确（安装脚本已处理）。

9.3 域名解析未生效

现象：绑域名后访问 404/无法连接，证书也签不出。排查：dig +short app.example.com 确认 A 记录指向服务器公网 IP；等待 DNS 传播（数分钟到数小时）。解决：修正 DNS 记录，确保解析到正确 IP 后再 Deploy。

9.4 SSL / Let’s Encrypt 失败

现象：域名可访问但非 HTTPS，或证书一直 pending。 常见原因与解决： - 80 端口未对公网开放（ACME http-01 挑战需要）→ 放行安全组与防火墙 80/TCP； - 域名未解析（见 9.3）； - 触发 Let’s Encrypt 速率限制（同一域名短期内申请过多）→ 等待限流窗口（通常 1 周针对失败校验），或先用 sslip.io 测试域名验证链路； - 反向代理未运行 → 在服务器页 Start Proxy。

9.5 磁盘空间不足

现象：构建失败、镜像拉取失败、No space left on device。解决：清理 Docker 资源——

docker system df            # 查看占用
docker image prune -a       # 清理未使用镜像
docker container prune      # 清理停止的容器
docker volume prune         # 谨慎：会删未使用卷（勿误删业务卷）

同时确保 /data/coolify 所在分区有足够空间；为镜像、卷、备份预留余量。

9.6 升级中断 / 升级后异常

现象：更新过程中断，或更新后面板起不来。解决： - 查看更新日志：ls /data/coolify/source/upgrade-*.log，按日志处理； - 重新运行升级脚本：cd /data/coolify/source && bash upgrade.sh； - 确认容器健康：docker inspect --format='{{.State.Health.Status}}' coolify 应为 healthy； - 重要：升级前先备份（见第十章），出问题从备份还原。

9.7 容器一直 starting / 不健康

现象：docker ps 中 coolify 状态 starting 或 unhealthy。原因：多为 Postgres/Redis 未就绪、内存不足、或 APP_KEY 缺失导致迁移失败。解决： - docker logs coolify 看具体报错； - 确认 /data/coolify/source/.env 中 APP_KEY、DB_PASSWORD、REDIS_PASSWORD 齐全； - 资源不足时调高服务器规格或 PHP_MEMORY_LIMIT； - 重启依赖：docker compose -f docker-compose.yml -f docker-compose.prod.yml restart。

9.8 无法访问 8000 控制面

现象：浏览器打不开 http://IP:8000。排查： - 防火墙/安全组是否放行 8000/TCP； - 是否改过 APP_PORT（见 7.3），用新端口访问； - docker ps 确认 coolify 容器在运行且端口映射存在； - 云厂商安全组常被忽略，既要系统防火墙放行也要安全组放行。

9.9 SSH 连接 / 密钥问题

现象：添加远程服务器时连不上，或 localhost 资源操作失败。解决：确认 OpenSSH 运行（systemctl status ssh）；安装脚本生成的 host.docker.internal 密钥须在 authorized_keys 中；远程服务器需允许 Coolify 控制面通过 SSH 密钥登录。

9.10 实时通信（6001）异常

现象：部署状态不实时刷新、日志不自动滚动。解决：确认 6001/6002 端口映射正常；v4.4+ 实时已内置 coolify 容器，留意 REVERB_PORT 配置；检查容器日志 docker logs coolify | grep -i reverb。

十、升级 / 回滚 / 卸载教程

10.1 升级（v4 系列内）

方式一：仪表盘（推荐） 左侧 Settings → Updates：可开启 Automatic updates 并设置更新频率（cron 或 every_minute/hourly/daily/weekly/monthly/yearly，默认每日 0 0 * * *）。也可点 Check now 立即检查、Update 立即升级。

方式二：环境变量 在 /data/coolify/source/.env 设 AUTOUPDATE=false 可关闭；设置后仪表盘的自动更新开关失效。

方式三：终端手动

cd /data/coolify/source
bash upgrade.sh

升级前务必：① 创建实例备份；② 阅读目标版本 Release Notes；③ 确认无正在进行的部署。升级日志位于 /data/coolify/source/upgrade-YYYY-MM-DD-HH-MM-SS.log。

升级只更新 Coolify 控制面，不会动你已部署的应用/数据库/服务/服务器。升级期间面板会有短暂（通常 <1 分钟）不可用。

10.2 备份与还原（回滚的安全网）

实例备份：仪表盘内创建 Instance Backup（含 Coolify 数据库）。注意：实例备份不含你部署的应用、数据库、服务及其卷；那些需各自配置备份（可到 S3 兼容存储）。
密钥备份：单独保存 /data/coolify/source/.env——它是还原备份所需的加密密钥。
回滚策略：官方推荐「先备份，再升级」；若升级后异常，最稳妥是从升级前备份还原。硬降级（在 .env 指定旧版镜像标签 LATEST_IMAGE=v4.x.y 后重跑 upgrade.sh）风险较高，仅建议在测试环境验证后于生产使用，且务必先备份。

10.3 v4 → v5 升级路线

v5 是 2025-04 宣布的完全重写（全新 UI/UX、代码质量与可扩展性重构），截至本文撰写（2026-10）仍在开发、未发布稳定版。官方计划提供 v4 → v5 的完全自动迁移。当前阶段：请继续使用稳定的 v4；待 v5 稳定版发布后，升级流程会随发布说明提供，无需现在手动迁移。v4 线在此期间持续获得补丁与维护。

10.4 卸载

⚠️ 卸载不可撤销，会删除 Coolify 的配置、SSH 密钥、部署文件、代理配置与本地实例备份。卸载前：备份实例与 .env、迁移需要的应用配置/卷/代理路由。

# 1. 连接运行 Coolify 的服务器（root）
ssh root@<服务器IP>

# 2. 删除 Coolify 控制面容器（应用/数据库/服务容器继续运行）
docker rm -f coolify coolify-db coolify-redis coolify-sentinel
# 老版本可能还有实时容器：
docker rm -f coolify-realtime

# 3. 删除 Coolify 代理（独立 Docker 模式）
docker rm -f coolify-proxy
# Docker Swarm 模式：
# docker stack rm coolify-proxy

# 4. 删除数据卷
docker volume rm coolify-db coolify-redis

# 5. （可选）如不再需要，移除 coolify 网络
docker network rm coolify

# 6. 删除数据目录（最终破坏性步骤）
rm -rf /data/coolify

# 7. （可选）释放镜像空间
docker rmi ghcr.io/coollabsio/coolify:latest
docker rmi ghcr.io/coollabsio/coolify-helper:latest
docker rmi ghcr.io/coollabsio/sentinel:1.0.1
docker rmi postgres:15-alpine
docker rmi redis:7-alpine
docker rmi traefik:v3.7        # 若用默认 Traefik
# docker rmi lucaslorentz/caddy-docker-proxy   # 若用 Caddy

验证卸载：

docker ps -a --format '{{.Names}}' | grep -E '^(coolify|coolify-db|coolify-redis|coolify-realtime|coolify-sentinel|coolify-proxy)(_|$)' || true
# 应无输出
test ! -d /data/coolify && echo "Coolify 数据目录已删除"

注意：删除 Coolify 代理（coolify-proxy）会停止它提供的域名路由与 TLS；若仍有业务依赖这些域名/证书，请在卸载前规划好替代反代。

十一、商用许可与合规风险提示

11.1 许可证：Apache-2.0

Coolify 以 Apache License 2.0 发布（仓库根目录 LICENSE）。该许可证允许商用、修改、再分发，并明确提供专利授权。要点：

✅ 可免费自托管、商用，无功能阉割、无付费墙（官方哲学：free forever）。
✅ 可修改源码适配自身需求。
✅ 可集成进商业产品/内部平台。
⚠️ 需保留版权与许可证声明；若修改并分发，应说明改动（NOTICE 文件要求）。
⚠️ Apache-2.0 不提供明示担保与责任限制，使用风险自负。

Coolify Cloud 是官方提供的付费托管控制面服务（高可用、省运维、含邮件通知与额外支持），与自托管版采用同一套开源代码，二者授权互不冲突。

11.2 自托管安全责任

自托管意味着安全边界由你掌控，也由你负责：

控制面即 root 风险：Coolify 通过 SSH 持有被管理服务器的 root 级访问能力。一旦控制面或其凭据泄露，攻击者可获得服务器 root。务必：强密码/预创建管理员、及时更新、限制 8000 端口暴露面（如仅内网/VPN 访问，前置鉴权反代）。
保持更新：项目维护团队较小，安全补丁以滚动发布形式随版本推送；建议开启自动更新并关注 GitHub Releases 与安全公告。
备份策略：定期实例备份 + 妥善保存 .env（含 APP_KEY）；为重要数据库配置异地（S3 兼容）备份。
暴露面收敛：数据库端口不要随意对公网开放（见 8.3）；业务域名走 HTTPS；防火墙只放行必要端口。
合规：在你所在司法辖区合规使用（数据驻留、个人隐私、行业监管等）；开源许可证不替代你的合规义务。生产关键负载建议自有运维/SLA 支撑，或评估 Coolify Cloud / 商业支持。

本文所有命令、端口、路径、环境变量均来自 Coolify 官方仓库与文档的当前真实状态，适用于 v4 稳定系列。部署前请以官方文档最新版为准：https://coolify.io/docs