安装 Coolify 并部署第一个应用
在 Debian 或 Ubuntu 上安装 Coolify 而不暴露其仪表板,保护实例安全,通过 HTTPS 部署应用,并管理更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
Coolify 是一个自托管平台,可将您的应用、数据库和服务部署到您自己的服务器上。它基于 Docker 以及一个负责管理域名和 HTTPS 证书的反向代理。
完成本指南后,仪表板将通过 https://coolify.您的域名.com 响应,其直连端口不会暴露在互联网上,管理员账户受到保护,第一个应用也将在 https://app.您的域名.com 上运行。
订购服务器
本指南适用于由您自行管理的服务器:
前提条件
- 最好是一台专用于 Coolify 的服务器,运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04
- 至少 2 个核心、2 GB 内存和 10 GB 可用空间,并根据您的应用和构建需求增加
- 使用
root或具有sudo权限的用户进行 SSH 访问 - Docker Engine 24 或更高版本,按照指南安装 Docker Engine 和 Docker Compose安装。否则,Coolify 安装程序会尝试自行安装,但它不接受 snap 版本
- 一个由您管理 DNS 区域的域名
- 没有其他服务占用 80 和 443 端口,例如 Nginx、Apache 或 Caddy
本指南使用 4.7.5 版本,这是撰写本文时的稳定版本。请在 Coolify 版本文件中查看最新版本。
使用的端口
| 端口 | 作用 | 本指南中的暴露方式 |
|---|---|---|
| 22/tcp | SSH,包括 Coolify 与服务器的连接 | 开放 |
| 80/tcp | HTTP 和证书验证 | 公开,经由代理 |
| 443/tcp | HTTPS | 公开,经由代理 |
| 443/udp | HTTP/3 | 公开,经由代理 |
| 8000/tcp | 直接访问仪表板 | 仅 127.0.0.1 |
| 6001/tcp | 实时更新 | 仅 127.0.0.1 |
| 6002/tcp | Web 终端 | 仅 127.0.0.1 |
| 8080/tcp | 默认 Traefik 配置发布的端口 | 在步骤 7 中移除 |
如果您使用 UFW,请用 sudo ufw allow 22/tcp 保持 SSH 开放,不要使用 limit 规则:它可能会切断 Coolify 的重复连接。
步骤 1:准备 DNS
创建两条指向 您的服务器IP 的 A 记录:
| 名称 | 用途 |
|---|---|
coolify.您的域名.com |
仪表板 |
app.您的域名.com |
第一个应用 |
如果您的域名由 HostMyServers 管理,请按照指南指向 IP操作。然后进行检查:
dig +short A coolify.您的域名.com
dig +short A app.您的域名.com
dig +short AAAA coolify.您的域名.com前两条命令应返回服务器的地址。如果最后一条命令返回了 IPv6 地址,该地址也必须指向这台服务器,否则证书创建可能会失败。
步骤 2:允许 Coolify 的 SSH 连接
Coolify 使用 root 账户和专用密钥通过 SSH 连接服务器。请检查当前生效的设置:
sudo sshd -T | grep -i '^permitrootlogin'prohibit-password、without-password 和 yes 这些值都可以。如果结果为 no,请仅允许 root 通过密钥登录:
echo 'PermitRootLogin prohibit-password' | sudo tee /etc/ssh/sshd_config.d/00-coolify.conf
sudo sshd -t
sudo systemctl reload ssh请保持当前会话打开,并在关闭它之前测试新的连接。
如果您已按照保护您的服务器操作,SSH 将监听 2222 端口。请将本指南 UFW 规则中的 22 替换为 2222,并在安装 Coolify 后于 Servers > localhost > General 中填写此端口。
步骤 3:将端口限制在本地地址
如果不采取预防措施,仪表板会通过 HTTP 发布在 8000 端口上,第一位访问者就可以在那里创建管理员账户。因此,请在安装之前创建自定义文件。Coolify 在更新时会保留该文件。
切换到 root:
sudo -i
mkdir -p /data/coolify/source
nano /data/coolify/source/docker-compose.custom.yml粘贴以下内容:
services:
coolify:
ports: !override
- "127.0.0.1:${APP_PORT:-8000}:8080"
- "127.0.0.1:${SOKETI_PORT:-6001}:6001"
- "127.0.0.1:6002:6002"步骤 4:安装 Coolify
仍以 root 身份下载官方脚本,浏览其内容,然后使用所选版本运行:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
less /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5该脚本会安装所需的软件包,调整 Docker 配置,创建 /data/coolify,生成 Coolify 的 SSH 密钥并启动其容器。它可能会重启 Docker:这也是建议从全新服务器开始的又一个原因。
结束时,它会显示一个 http://...:8000 形式的地址。该地址无法从互联网访问,这正是预期结果。请检查端口:
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'coolify 这一行应显示 healthy,且端口以 127.0.0.1: 开头。
步骤 5:打开 SSH 隧道
在您的电脑上的终端中,打开通往这三个端口的隧道:
ssh -N -L 8000:127.0.0.1:8000 -L 6001:127.0.0.1:6001 -L 6002:127.0.0.1:6002 您的用户名@您的服务器IP该命令会保持运行,不输出任何内容。配置期间请保持此终端打开。您的电脑与服务器之间的流量由 SSH 加密。
步骤 6:创建管理员账户
打开 http://localhost:8000,立即创建账户,并使用一个长且唯一的密码。Coolify 仅在启动后的 10 分钟 内接受第一个账户的创建。
然后按照向导操作,选择使用此服务器(localhost)。在 Servers > localhost 中,连接应显示为已验证。如果不是,请参阅故障排除部分。
请立即将实例的加密密钥复制到密码管理器中:
grep '^APP_KEY=' /data/coolify/source/.env步骤 7:启动代理
打开 Servers > localhost > Proxy。Traefik 是默认代理。
在 Configuration 中,删除下面这一行(此部署方式不需要它),然后保存:
- '8080:8080'然后单击 Start Proxy,如果代理已在运行,则重启它。在服务器上确认它正在监听:
docker ps --filter name=coolify-proxy --format '{{.Names}} {{.Status}} {{.Ports}}'80 和 443 端口应显示在 0.0.0.0 上,而 8080 不应再出现在列表中。
步骤 8:通过 HTTPS 发布仪表板
打开 Settings > General。在 URL 中输入:
https://coolify.您的域名.com保持 Redirect HTTP to HTTPS 处于启用状态,然后单击 Save changes。稍等片刻后,打开 https://coolify.您的域名.com 并检查证书:
curl -I https://coolify.您的域名.com请确认数据实时更新;如果您使用 Web 终端,也请确认其正常工作。然后您可以用 Ctrl+C 关闭隧道。如果域名不再响应,隧道仍是您的备用访问方式。
步骤 9:保护实例
| 设置 | 位置 | 建议值 |
|---|---|---|
| 注册 | Settings > Advanced > Registration | Registration disabled |
| 双重身份验证 | Profile > Two-factor Authentication > Configure 2FA | 启用,并单独保存恢复代码 |
| API | Settings > Advanced > API access | 如果不使用,设为 Disabled |
| MCP 服务器 | Settings > Advanced | 禁用,除非有明确需求 |
| 允许的地址 | Settings > Advanced > Allowed IPs | 如果启用 API,填写您的地址 |
| 团队 | Team | 为每位成员分配最低权限角色 |
从另一台机器上,在不使用隧道的情况下检查可访问的内容:
nmap -Pn -p 22,80,443,6001,6002,8000,8080 您的服务器IP只有 22、80 和 443 应显示为 open。
步骤 10:部署第一个应用
此示例使用现成的镜像:不需要 Git 仓库,也不需要构建。
- 打开 Projects,创建一个名为
demo的项目,然后打开它。 - 单击 + New(或 Create New Resource),然后选择 Docker Image。
- 输入镜像
nginx:1.30-alpine并继续。 - 在 Ports Exposes 中填写
80。 - 在 Domains 中单击 Add domain,选择
https,然后输入app.您的域名.com。 - 单击 Deploy 并查看部署日志。
然后验证结果:
curl -I https://app.您的域名.com响应应为 200 状态码,浏览器应显示 Nginx 欢迎页面且证书有效。
从公开 Git 仓库部署
在项目中单击 + New,选择 Public Repository,粘贴仓库的 HTTPS 地址,然后单击 Check repository。接着选择 Build pack、应用端口及其域名,然后运行 Deploy。
构建默认在此服务器上进行,可能消耗大量 CPU 和内存。
更新 Coolify
Coolify 更新不会修改您的应用、系统或 Docker。开始之前,请阅读发行说明,等待正在进行的部署完成,并进行备份。
通过仪表板
打开 Settings > Updates,保留 Stable 通道,然后在有新版本时单击 Upgrade now。Automatic updates 设置决定 Coolify 是否自行安装新版本。如果您希望自己掌控更新时间,请将其禁用。
通过终端
以 root 身份运行,并指定所需版本(不带 v):
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | bash -s 4.7.5请勿使用 install.sh 进行日常更新:它会重置 /data/coolify 下的所有者和权限。docker-compose.custom.yml 文件仍会生效。之后请检查仪表板中显示的版本,必要时查看日志 /data/coolify/source/upgrade-*.log。
备份与恢复
请将以下内容保存在服务器之外:
| 项目 | 位置 | 原因 |
|---|---|---|
| Coolify 数据库 | .dmp 备份 |
项目、设置和加密的机密信息 |
APP_KEY 密钥和 .env 文件 |
/data/coolify/source/.env |
没有此密钥,恢复的机密信息将无法读取 |
| SSH 密钥 | /data/coolify/ssh/keys/ |
连接受管服务器 |
| 端口自定义配置 | /data/coolify/source/docker-compose.custom.yml |
保留端口保护 |
| 应用数据 | 数据卷和数据库 | 不包含在 Coolify 备份中 |
通过仪表板
打开 Settings > Backup,单击 Configure backup,然后单击 Back up now。在 Executions 中检查结果,并使用 Download 获取副本。您也可以添加 S3 存储。请保持 Backup before update 处于启用状态,以便在每次从界面发起更新前获得一份备份。
通过终端
以 root 身份执行:
mkdir -p /data/backups
docker exec coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify > "/data/backups/coolify-db-$(date +%F).dmp"
test -s "/data/backups/coolify-db-$(date +%F).dmp" && echo OK
tar czf "/data/backups/coolify-files-$(date +%F).tar.gz" -C /data/coolify source/.env source/docker-compose.custom.yml ssh/keys
chmod 600 /data/backups/*这些文件包含机密信息:请将它们复制到加密位置。
在同一台服务器上恢复
将 YYYY-MM-DD 替换为备份日期。当前数据库将被替换。请先确认 /data/coolify/source/.env 中的 APP_KEY 与已保存的密钥一致,然后以 root 身份执行:
docker stop coolify coolify-redis
docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < /data/backups/coolify-db-YYYY-MM-DD.dmp
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5请指定备份时安装的版本。在新服务器上,请按照官方恢复流程操作,该流程也包括 SSH 密钥的恢复。
故障排除
Setup window closed
已超过 10 分钟的期限。请重启 Coolify,然后重新加载页面:
docker restart coolify:8000 地址无响应
从互联网访问时这是正常现象。请使用步骤 5 的隧道并打开 http://localhost:8000。如果隧道失败,请用 docker ps 检查容器状态。
仪表板中的数据不更新
实时连接未能建立。使用隧道时,请确认其中包含 6001 和 6002 端口。使用域名时,请确认代理正在运行,且没有其他代理阻止 WebSocket。
验证服务器时出现 Permission denied (publickey)
root 缺少 Coolify 的密钥,或 root 无法登录。请检查步骤 2。安装程序不会将公钥保存在磁盘上:请以 root 身份根据私钥重新计算公钥,然后添加它:
ssh-keygen -y -f /data/coolify/ssh/keys/id.root@host.docker.internal | sed 's/$/ coolify/' >> /root/.ssh/authorized_keys如果该文件不存在,请用 ls /data/coolify/ssh/keys/ 列出该文件夹,并使用其中的密钥。
localhost 服务器无法访问或不稳定
Coolify 从其 Docker 网络连接服务器。ufw limit 22/tcp 规则或将 SSH 限制为仅您的地址,都可能阻止连接。请将该限制替换为 sudo ufw allow 22/tcp,或允许 Coolify 的网络:
docker network inspect coolify --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw allow from 子网 to any port 22 proto tcp将 子网 替换为显示的值。
代理无法启动:address already in use
另一个服务正在使用 80 或 443 端口:
sudo ss -ltnp | grep -E ':(80|443) '请停止并禁用该服务,然后重新启动代理。
代理只能在本地访问
请确认 /etc/docker/daemon.json 中不包含 "ip": "127.0.0.1" 或 host_binding_ipv4。删除这些键,重启 Docker,然后重启代理。
证书无效(TRAEFIK DEFAULT CERT)
Let's Encrypt 未能验证该域名。请检查 A 和 AAAA 记录,然后检查能否从外部访问 80 端口。如果域名经过 Cloudflare 代理,请在验证期间将其停用,或使用 DNS 质询。如果服务器上一切正常,但该端口仍无法访问,请通过客户中心联系支持团队。
502 Bad Gateway 错误
代理能够连接到容器,但无法连接到应用。请确认 Ports Exposes 与应用的实际端口一致,并且应用监听在 0.0.0.0 而不是 127.0.0.1 上。
no available server
Traefik 找不到该域名对应的健康容器。请检查部署状态、应用的健康检查,以及 Domains 中域名的拼写。
8000 端口仍可从互联网访问
自定义文件未生效。请检查其位置和语法,然后以 root 身份应用它:
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config --quiet
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml up -d --remove-orphans部署期间服务器明显变慢
构建会消耗服务器资源。请部署已构建好的镜像,在其他地方构建(例如在您的 CI 中),或增加资源。
恢复后出现 Invalid MAC
APP_KEY 密钥与备份中的不一致。请将已保存的密钥放回 /data/coolify/source/.env,然后使用相同版本重新运行安装程序。