Coolify 完全指南 2026：自托管 PaaS — 不用 Vercel/Heroku 也能部署应用

2026 年，自托管运动正在加速。开发者和团队正在从昂贵的云平台转向自主控制基础设施，以降低成本并消除供应商锁定。Coolify 走在这一转变的前沿——一个开源的自托管平台即服务（PaaS），让你在自己的服务器上获得类似 Vercel 的部署体验。本指南涵盖了安装、配置和在生产中运行 Coolify 所需的一切。

什么是 Coolify 以及为什么它很重要

Coolify 是一个免费的开源自托管 PaaS，旨在简化应用部署和服务器管理。你可以把它想象成在你控制的服务器上运行的私有 Heroku 或 Vercel。它将 Docker、反向代理、SSL 证书和部署流水线抽象为一个简洁的 Web UI。

为什么 Coolify 在 2026 年很重要

• 零供应商锁定：你的代码、你的服务器、你的数据
• 无按席位计费：无限团队成员无额外费用
• 完全的数据主权和 GDPR 合规控制
• 大幅降低成本：$5 的 VPS 替代 $50+ 的平台费用
• 不断壮大的生态：30,000+ GitHub stars，活跃社区，频繁发布
• 支持任何语言、框架或 Docker 镜像

Coolify vs Vercel vs Netlify vs Railway vs Heroku

以下是 Coolify 在 2026 年与主流云部署平台在关键维度上的对比。

系统要求和安装

Coolify 可以在任何 Linux 服务器上运行（推荐 Ubuntu 22.04+），需要 SSH 访问。最低要求不高，但生产工作负载需要更多资源。

一键安装

Coolify 通过一条 curl 命令安装，自动设置 Docker、Coolify 应用和所有依赖项。

# Install Coolify with one command
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# The installer will:
# 1. Install Docker Engine if not present
# 2. Pull Coolify Docker images
# 3. Set up PostgreSQL for internal state
# 4. Configure Traefik reverse proxy
# 5. Start the Coolify dashboard

# After installation, access the dashboard:
# http://your-server-ip:8000

# First-time setup:
# 1. Create an admin account
# 2. Set your instance domain (e.g., coolify.yourdomain.com)
# 3. Configure the wildcard domain for app subdomains

# VPS setup example (Hetzner/DigitalOcean/Vultr):
# 1. Create a VPS with Ubuntu 24.04
# 2. Point a domain to the VPS IP (A record)
# 3. SSH in and run the install command
ssh root@your-server-ip
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

架构概览

理解 Coolify 的架构有助于排查问题和优化设置。Coolify 基于经过验证的成熟组件构建。

• Coolify 应用：基于 Laravel 的 Web UI 和 API，通过 Nginx 提供服务:
• Docker 引擎：所有应用、数据库和服务都作为 Docker 容器运行:
• Traefik：自动反向代理，处理 HTTPS 终止、路由和负载均衡:
• PostgreSQL：存储 Coolify 配置、部署历史和元数据的内部数据库:
• Redis：后台作业和实时更新的队列管理和缓存:
• Sentinel（v4）：可选的监控代理，用于资源指标和健康检查:

# Coolify Architecture Diagram
#
#   Internet
#      |
#   [Traefik] :80/:443
#      |--- app1.yourdomain.com --> [App Container 1]
#      |--- app2.yourdomain.com --> [App Container 2]
#      |--- coolify.yourdomain.com --> [Coolify Dashboard]
#      |
#   [Docker Engine]
#      |--- [PostgreSQL] (Coolify internal DB)
#      |--- [Redis] (Queue & cache)
#      |--- [Sentinel] (Monitoring agent)
#      |--- [App DB: PostgreSQL/MySQL/MongoDB]
#      |--- [App Services: workers, cron, etc.]

部署应用

Coolify 支持从 Git 仓库、Docker 镜像或原始 Dockerfile 部署应用。以下是常见框架的部署示例。

Coolify supports three deployment methods: (1) Dockerfile-based builds where you provide a Dockerfile in your repository, (2) Nixpacks auto-detection that automatically detects your language and framework, and (3) Docker image deployments where you specify a pre-built image from a registry. For most projects, the Dockerfile approach gives you the most control.

Nixpacks Auto-Detection

If your repository does not contain a Dockerfile, Coolify uses Nixpacks to automatically detect your language and framework. Nixpacks supports Node.js, Python, Go, Rust, Ruby, PHP, Java, .NET, and many more. It generates an optimized Dockerfile behind the scenes.

# Nixpacks auto-detects and builds:
# - package.json → Node.js (detects Next.js, Nuxt, Remix, etc.)
# - requirements.txt / pyproject.toml → Python
# - go.mod → Go
# - Cargo.toml → Rust
# - Gemfile → Ruby
# - composer.json → PHP

# Override Nixpacks behavior with nixpacks.toml:
[phases.setup]
nixPkgs = ["...", "ffmpeg"]  # Add system packages

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm start"

Node.js / Next.js

# Dockerfile for Next.js on Coolify
FROM node:20-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
ENV PORT=3000
CMD ["node", "server.js"]

Python (FastAPI / Flask)

# Dockerfile for Python FastAPI
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Go

# Dockerfile for Go application
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o server .

FROM alpine:3.19
WORKDIR /app
COPY --from=builder /app/server .
EXPOSE 8080
CMD ["./server"]

Static Sites

# Dockerfile for static site (Vite, Astro, Hugo, etc.)
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Docker Image Deployment

You can deploy any pre-built Docker image directly. This is useful for third-party services, custom registries, or images built in external CI pipelines.

# Deploy from Docker Hub:
# Image: nginx:alpine
# Port: 80

# Deploy from GitHub Container Registry:
# Image: ghcr.io/your-org/your-app:latest

# Deploy from private registry:
# Image: registry.yourdomain.com/app:v2.1.0
# Add registry credentials in Coolify > Settings > Docker Registries

# Pre-built image with environment variables:
# Image: node:20-alpine
# Command override: node server.js
# Working directory: /app

Docker 和 Docker Compose 部署

对于包含多个服务的复杂应用，Coolify 直接支持 Docker Compose 部署。推送你的 docker-compose.yml，Coolify 会处理其余部分。

When using Docker Compose, Coolify reads your docker-compose.yml file, builds any services that use the build directive, pulls images for others, and manages the entire lifecycle. Coolify automatically injects Traefik labels on the service you designate as the public-facing entry point.

# docker-compose.yml for a full-stack app on Coolify
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=production
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

  worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: node worker.js
    environment:
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

数据库管理

Coolify 提供一键数据库部署，包含自动备份、持久化卷和便捷的连接字符串管理。

Each database is deployed as a Docker container with a persistent volume for data. Coolify automatically generates secure passwords, configures networking so your applications can reach the database by container name, and provides connection strings in the dashboard. You can also expose database ports to the host for external access during development.

Supported Databases

• PostgreSQL (16, 15, 14, 13)
• MySQL (8.4, 8.0)
• MariaDB (11, 10)
• MongoDB (7, 6)
• Redis (7, Stack)
• Dragonfly（快速 Redis 替代方案）
• ClickHouse（分析型数据库）
• KeyDB（多线程 Redis）

# Coolify creates databases with connection details like:
# Internal URL (for services on same server):
# postgresql://postgres:generated_password@db-container:5432/mydb

# You can also connect externally if you expose the port:
# postgresql://postgres:generated_password@your-server-ip:5432/mydb

# Backup a Coolify-managed PostgreSQL database manually:
docker exec coolify-db pg_dump -U postgres mydb > backup.sql

# Restore from backup:
cat backup.sql | docker exec -i coolify-db psql -U postgres mydb

# One-click MongoDB setup produces:
# mongodb://root:generated_password@mongo-container:27017/mydb?authSource=admin

# Redis connection:
# redis://redis-container:6379

环境变量和密钥

Coolify 提供安全的环境变量管理方式，支持跨服务的共享变量、构建时和运行时分离以及预览环境专用覆盖。

Coolify encrypts environment variables at rest in its PostgreSQL database. Variables marked as sensitive are never displayed in the UI after being set. Build-time variables are available during the Docker build process, while runtime variables are injected when the container starts. This separation is important for Next.js applications where NEXT_PUBLIC_ variables must be available at build time.

# Coolify environment variable types:

# 1. Application-level variables (set in app settings)
# These are injected at runtime into the container
DATABASE_URL=postgresql://postgres:pass@db:5432/app
REDIS_URL=redis://redis:6379
NODE_ENV=production
APP_SECRET=your-secret-key-here

# 2. Build-time variables (available during docker build)
# Set "Build Variable" toggle in the Coolify UI
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

# 3. Shared variables (reusable across multiple services)
# Created under "Shared Variables" in team settings
# Reference with: \${SHARED_VAR_NAME}

# 4. Preview-specific variables
# Override variables for pull request preview deployments
# Useful for staging database URLs, test API keys, etc.
DATABASE_URL=postgresql://postgres:pass@staging-db:5432/app_preview

自定义域名和 SSL

Coolify 通过集成的 Traefik 反向代理自动配置 Let's Encrypt SSL 证书。添加自定义域名只需要一条 DNS A 记录和在 Coolify 仪表板中添加域名条目。

Coolify handles both single-domain and wildcard SSL certificates. For standard domains, it uses HTTP-01 challenge validation. For wildcard certificates, you need to configure a DNS provider (Cloudflare, AWS Route53, DigitalOcean DNS) for DNS-01 challenge validation.

# Step 1: Add DNS A record at your registrar
# Type: A
# Name: app (or @ for root domain)
# Value: your-server-ip
# TTL: 300

# Step 2: In Coolify dashboard, set the domain:
# Application Settings > Domains
# Add: app.yourdomain.com

# Step 3: Coolify automatically:
# - Configures Traefik routing rules
# - Requests Let's Encrypt SSL certificate
# - Sets up automatic certificate renewal
# - Enables HTTP -> HTTPS redirect

# For wildcard domains (*.yourdomain.com):
# Requires DNS challenge (Cloudflare, Route53, etc.)
# Configure in Coolify > Settings > DNS Provider

# Traefik configuration is auto-generated:
# - TLS termination at the proxy level
# - WebSocket support enabled by default
# - Custom headers can be added per application

# Multiple domains per application:
# Add comma-separated domains in the settings:
# app.yourdomain.com, www.yourdomain.com, custom.com

GitHub/GitLab 集成和自动部署

Coolify 原生集成 GitHub 和 GitLab。通过 OAuth 连接你的账户，选择仓库，Coolify 会创建 webhook 监听器，在每次推送时自动部署。

The integration supports both GitHub Apps (recommended for organizations) and personal access tokens for simpler setups. For GitLab, both cloud and self-hosted instances are supported. Coolify creates webhook endpoints that listen for push events and automatically trigger the deployment pipeline.

Preview deployments are one of the most powerful features. When a pull request is opened, Coolify automatically deploys a preview instance with a unique URL, injects preview-specific environment variables, and tears it down when the PR is closed. This gives your team a Vercel-like preview experience on your own infrastructure.

# GitHub Integration Setup:
# 1. Go to Coolify dashboard > Sources > Add GitHub App
# 2. Authorize the Coolify GitHub App
# 3. Select repositories to grant access

# GitLab Integration Setup:
# 1. Go to Coolify dashboard > Sources > Add GitLab
# 2. Enter your GitLab instance URL (or gitlab.com)
# 3. Create an application in GitLab for OAuth
# 4. Paste Client ID and Secret in Coolify

# Auto-deploy configuration:
# - Push to main/master branch -> Production deployment
# - Push to other branches -> Preview deployment (optional)
# - Pull request opened -> Preview deployment with unique URL

# Coolify listens for webhooks and triggers:
# 1. git clone / git pull
# 2. Docker build (using Dockerfile or Nixpacks)
# 3. Container restart with zero-downtime deployment
# 4. Health check verification
# 5. Traefik routing update

# Manual deployment trigger:
# Click "Deploy" button in the dashboard
# Or use the Coolify API (see API section below)

Coolify v4 新特性和改进

Coolify v4 是一次重大重写，在可用性、性能和可靠性方面带来了显著改进。

Version 4 was developed over 18 months and represents a near-complete rewrite of the codebase. The most impactful changes include the Sentinel monitoring agent that provides per-container resource metrics, a fully documented REST API for automation, and significantly improved Docker Compose handling that supports complex multi-service stacks out of the box.

• 全新设计的 UI，改进的导航和暗色模式
• 新的 Sentinel 监控代理用于实时资源跟踪
• 改进的 Docker Compose 支持，完整 YAML 兼容
• S3 兼容的备份目标（AWS、Cloudflare R2、MinIO）
• 增强的 API，支持所有资源的完整 CRUD 操作
• 改进的 webhook 处理和部署流水线
• 标签和筛选功能用于组织大量资源
• 从仪表板终端访问运行中的容器
• 改进的多服务器代理管理
• 自动服务器清理和资源回收

多服务器管理

Coolify 可以从单一仪表板管理多台服务器。在主服务器上安装 Coolify，然后通过提供 SSH 凭据添加远程服务器。每台服务器运行自己的 Docker 引擎和 Traefik 实例，而 Coolify 在所有服务器上编排部署。

Multi-server management is one of Coolify's strongest advantages over other self-hosted PaaS tools. You can designate servers for specific purposes: one for production web applications, another for databases, and a third for staging environments. This separation improves security and resource isolation.

# Adding a remote server to Coolify:

# 1. On the remote server, ensure SSH is available:
sudo apt update && sudo apt install -y openssh-server

# 2. Create a dedicated user for Coolify (recommended):
sudo adduser coolify
sudo usermod -aG docker coolify

# 3. Set up SSH key access:
# Copy the public key from Coolify dashboard > Servers > Add Server
ssh-copy-id coolify@remote-server-ip

# 4. In Coolify dashboard:
# Servers > Add Server
# - Name: production-worker-1
# - IP: remote-server-ip
# - User: coolify
# - Private Key: select from Coolify key store
# - Click "Validate Server"

# 5. Coolify will:
# - Install Docker on the remote server
# - Set up Traefik proxy
# - Enable the server for deployments

# Deploy to specific servers:
# When creating a new resource, select the target server
# Each server operates independently with its own Docker and Traefik

监控和日志

Coolify v4 通过 Sentinel 代理内置监控功能。它跟踪每台服务器和每个容器的 CPU、内存、磁盘和网络使用情况。你可以在仪表板中直接查看任何应用或服务的实时日志。

For teams that need more advanced monitoring, Coolify integrates well with external tools. You can deploy Prometheus and Grafana as services within Coolify itself, then configure them to scrape metrics from your applications and the Docker daemon. Coolify's Sentinel agent can also export metrics in a Prometheus-compatible format.

# Coolify Sentinel Agent (v4):
# Automatically installed on each managed server
# Collects metrics every 10 seconds:
# - CPU usage (per server and per container)
# - Memory usage and available memory
# - Disk usage and I/O
# - Network traffic in/out

# View logs in the dashboard:
# Applications > [Your App] > Logs
# Shows real-time stdout/stderr from the container

# CLI access to container logs:
docker logs -f container_name --tail 100

# View all Coolify-managed containers:
docker ps --filter "label=coolify.managed=true"

# External monitoring integration:
# Export metrics to Prometheus/Grafana:
# 1. Deploy Prometheus + Grafana via Coolify
# 2. Configure Sentinel to export metrics
# 3. Create dashboards for all your services

# Health check configuration (per application):
# Settings > Health Check
# Path: /health or /api/health
# Interval: 30s
# Timeout: 5s
# Retries: 3

备份与恢复策略

Coolify 支持将数据库自动备份到本地存储或 S3 兼容的目标。你可以按自定义间隔安排备份并设置保留策略。

A solid backup strategy for Coolify involves three layers: (1) database backups managed by Coolify's built-in scheduler sent to S3, (2) volume backups for persistent data using Docker volume snapshots, and (3) Coolify configuration backup by dumping its internal PostgreSQL database. Combining all three ensures you can fully recover from any failure scenario, including complete server loss.

# Coolify Backup Configuration:

# 1. Configure S3 backup destination:
# Settings > S3 Storages > Add
# - Provider: AWS S3 / Cloudflare R2 / MinIO
# - Bucket: coolify-backups
# - Region: us-east-1
# - Access Key and Secret Key

# 2. Enable database backup:
# Databases > [Your DB] > Backups
# - Schedule: 0 2 * * * (daily at 2 AM)
# - Destination: S3 storage configured above
# - Retention: 7 days

# 3. Backup Coolify itself:
# The internal PostgreSQL database stores all configuration

# Manual Coolify backup:
cd /data/coolify
docker compose exec postgres pg_dumpall -U postgres > coolify-backup.sql

# Restore Coolify from backup:
cat coolify-backup.sql | docker compose exec -T postgres psql -U postgres

# 4. Volume backup strategy:
# For persistent volumes, create periodic snapshots:
docker run --rm -v myapp_data:/data -v /backups:/backup \
  alpine tar czf /backup/myapp-data-$(date +%Y%m%d).tar.gz /data

资源管理和扩展

Coolify 允许你为每个容器设置资源限制（CPU、内存），并通过 Docker Compose 副本配置水平扩展。对于垂直扩展，调整 VPS 大小，Coolify 会自动使用额外的资源。

Resource limits are critical in a self-hosted environment because unlike cloud platforms, there is no automatic scaling beyond your server capacity. Without limits, a single runaway application can consume all available memory and crash other services. Set both limits (hard cap) and reservations (guaranteed minimum) for each service.

# Set resource limits in Coolify dashboard:
# Application > Settings > Resource Limits
# - CPU Limit: 1.0 (1 core)
# - Memory Limit: 512M
# - CPU Reservation: 0.25
# - Memory Reservation: 256M

# Or in docker-compose.yml:
services:
  app:
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 256M
      replicas: 3  # Horizontal scaling

# Monitor resource usage:
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# Disk cleanup (run periodically):
docker system prune -af --volumes
# WARNING: removes unused images, containers, and volumes
# Coolify v4 has automatic cleanup in Settings > Server

成本对比：VPS vs 云平台

Coolify 最大的优势之一是节省成本。以下是一个典型全栈应用（含数据库、后台任务和中等流量）的真实成本对比。

Recommended VPS Providers

Any Linux VPS with root SSH access works with Coolify. Here are popular options sorted by price-to-performance ratio in 2026.

安全加固

运行自己的 PaaS 意味着你需要负责安全。以下是生产环境 Coolify 安装的加固步骤。

• 启用 UFW 防火墙，只允许 22、80、443 端口
• 使用 SSH 密钥认证并禁用密码登录
• 定期更新主机操作系统和 Docker
• 在 Ubuntu 上启用自动安全更新
• 为 Coolify 管理员和所有数据库设置强密码
• 使用 Coolify 内置的环境变量加密
• 通过 IP 白名单或 VPN 限制 Coolify 仪表板访问
• 在用于部署的 GitHub/GitLab 账户上启用双因素认证
• 检查 Docker 容器权限——避免以 root 运行
• 监控服务器访问日志并设置 fail2ban

# Security hardening commands:

# 1. Enable UFW firewall
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

# 2. Disable password authentication
sudo sed -i "s/PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config
sudo systemctl restart sshd

# 3. Enable automatic security updates
sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

# 4. Install fail2ban
sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

# 5. Restrict Coolify dashboard to specific IPs (via Traefik):
# In Coolify Settings > Custom Labels, add:
# traefik.http.middlewares.coolify-ip.ipallowlist.sourcerange=YOUR_IP/32

生产最佳实践

Following these practices will help you run a stable and maintainable Coolify production environment. Most production issues stem from insufficient resource limits, missing backups, or unmonitored disk usage.

• 为 Coolify 使用专用 VPS——不要与其他手动 Docker 设置共享
• 始终为容器设置资源限制（CPU 和内存），防止一个应用耗尽其他应用的资源
• 启用到 S3 目标的自动数据库备份——永远不要仅依赖本地备份
• 如果预算允许，使用不同服务器的独立暂存和生产环境
• 在生产中固定 Docker 镜像版本——永远不要使用 :latest 标签
• 为所有服务设置健康检查以启用自动重启
• 在合并到主分支之前使用拉取请求的预览部署
• 监控磁盘使用——Docker 镜像和构建缓存增长很快
• 定期运行 docker system prune 或启用 Coolify 的自动清理
• 保持 Coolify 更新——定期从仪表板运行内置更新

常见问题排查

以下是运行 Coolify 时最常见的问题及其解决方法。

Most Coolify issues fall into three categories: build failures (Dockerfile or Nixpacks errors), networking issues (DNS, SSL, port conflicts), and resource exhaustion (disk space, memory). The Coolify dashboard provides deployment logs for build issues, and Docker logs for runtime issues. When in doubt, check the Coolify Discord community where the maintainers and community are very active.

# Issue: Deployment fails with "port already in use"
# Solution: Check if another container is using the port
docker ps --format "{{.Names}} {{.Ports}}" | grep 3000
# Stop the conflicting container or change your app port

# Issue: SSL certificate not issuing
# Solution: Verify DNS propagation and Traefik logs
dig +short app.yourdomain.com   # Should show your server IP
docker logs coolify-proxy 2>&1 | grep -i "certificate"
# Ensure ports 80 and 443 are open in firewall

# Issue: Application shows 502 Bad Gateway
# Solution: Check if the container is running and healthy
docker ps -a | grep your-app
docker logs your-app-container --tail 50
# Common causes: app crashed, wrong port, health check failing

# Issue: Out of disk space
# Solution: Clean up Docker resources
docker system df          # Check Docker disk usage
docker system prune -af   # Remove unused images/containers
docker volume prune -f    # Remove unused volumes (careful!)
df -h                     # Check overall disk usage

# Issue: Coolify dashboard not loading
# Solution: Check Coolify containers
cd /data/coolify
docker compose ps
docker compose logs --tail 50
docker compose restart

# Issue: Webhook not triggering deployments
# Solution: Verify webhook URL in GitHub/GitLab
# Check Coolify > Sources > [Your Source] > Webhooks
# GitHub: Settings > Webhooks > Recent Deliveries
# Look for 200 response from Coolify endpoint

# Issue: High memory usage
# Solution: Set container memory limits and check for leaks
docker stats --no-stream
# Set memory limits in Coolify app settings
# Consider adding swap on the VPS:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Zero-Downtime Deployments

Coolify supports zero-downtime deployments through its rolling update strategy. When you deploy a new version, Coolify starts the new container, waits for it to pass health checks, updates Traefik routing to point to the new container, and then stops the old container. This ensures your application remains available during deployments.

# Zero-downtime deployment requires:
# 1. A health check endpoint in your application
#    GET /health -> 200 OK

# 2. Health check configuration in Coolify:
#    Path: /health
#    Interval: 10s
#    Timeout: 5s
#    Retries: 3
#    Start Period: 30s (grace period for slow-starting apps)

# 3. Example health check endpoint (Node.js/Express):
# app.get("/health", (req, res) => {
#   // Check database connection
#   // Check Redis connection
#   res.status(200).json({ status: "healthy" });
# });

Coolify Update and Migration

Keeping Coolify updated is important for security patches and new features. The update process is designed to be non-disruptive — your running applications are not affected during a Coolify update. Only the Coolify management containers restart.

# Update Coolify from the dashboard:
# Settings > Update > Check for Updates > Update

# Update via CLI (alternative):
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# Before major version updates, backup:
cd /data/coolify
docker compose exec postgres pg_dumpall -U postgres > /tmp/coolify-pre-update.sql
cp -r /data/coolify/source/.env /tmp/coolify-env-backup

# Check current version:
cat /data/coolify/source/.env | grep APP_VERSION

# Rollback if needed (restore backup):
cat /tmp/coolify-pre-update.sql | docker compose exec -T postgres psql -U postgres

Coolify API 使用

Coolify v4 提供全面的 REST API 用于编程式管理。在仪表板的 Settings > API Tokens 中生成 API 令牌。

The API follows REST conventions and returns JSON responses. It supports authentication via Bearer tokens and covers all resources: applications, databases, servers, deployments, and environment variables. This makes it easy to integrate Coolify into your existing CI/CD pipelines or build custom automation scripts.

# Generate API token:
# Dashboard > Settings > API Tokens > Create New Token

# List all applications:
curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://coolify.yourdomain.com/api/v1/applications | jq .

# Get application details:
curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://coolify.yourdomain.com/api/v1/applications/APP_UUID | jq .

# Trigger a deployment:
curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://coolify.yourdomain.com/api/v1/applications/APP_UUID/deploy

# Update environment variable:
curl -s -X PATCH \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "APP_VERSION", "value": "2.1.0"}' \
  https://coolify.yourdomain.com/api/v1/applications/APP_UUID/envs

# List all servers:
curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://coolify.yourdomain.com/api/v1/servers | jq .

# List databases:
curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://coolify.yourdomain.com/api/v1/databases | jq .

# CI/CD integration example (GitHub Actions):
# .github/workflows/deploy.yml
# name: Deploy to Coolify
# on:
#   push:
#     branches: [main]
# jobs:
#   deploy:
#     runs-on: ubuntu-latest
#     steps:
#       - name: Trigger Coolify deployment
#         run: |
#           curl -s -X POST \
#             -H "Authorization: Bearer $COOLIFY_TOKEN" \
#             $COOLIFY_URL/api/v1/applications/$APP_UUID/deploy

常见问题

总结

Coolify 代表了 2026 年日趋成熟的自托管生态。它消除了管理 Docker、反向代理和 SSL 证书的复杂性，同时让你完全控制基础设施。无论你是想降低托管成本的独立开发者，还是寻求数据主权的团队，Coolify 都能以云平台定价的一小部分提供生产级部署平台。

Getting Started Checklist

1. Choose a VPS provider and create an Ubuntu 24.04 instance (4GB+ RAM recommended)
2. Point your domain DNS A record to the server IP address
3. SSH into the server and run the Coolify install command
4. Access the dashboard, create an admin account, and set your instance domain
5. Connect your GitHub or GitLab account for automatic deployments
6. Deploy your first application from a Git repository
7. Configure custom domains and verify SSL certificates are issued
8. Set up automated database backups to an S3 destination
9. Apply security hardening: firewall, SSH keys, fail2ban
10. Enable Sentinel monitoring and set up health checks for all services

For additional resources, visit the official Coolify documentation at coolify.io/docs, join the Coolify Discord community for support, and follow the GitHub repository at github.com/coollabsio/coolify for release notes and feature announcements. The self-hosting community is growing rapidly, and Coolify is one of the most mature and actively developed projects in this space. Starting with a small VPS and a single application is the best way to learn, and you can scale from there as your confidence and requirements grow.