Coolify 安装脚本失败

如果 Coolify 安装脚本已完成，但你无法访问 Coolify，或者容器缺失，本指南将帮助你调试和修复该问题。

常见症状

安装脚本完成，但未显示访问 URL
脚本显示成功，但无法通过 8000 端口访问 Coolify Web 界面
Docker 容器缺失或未运行
安装看似完成，但某些功能无法正常工作

重要

在遵循本指南之前，请确保阅读安装前置条件，以确保你的系统满足所有要求。

启用详细模式进行调试

如果你遇到安装问题，可以以详细模式运行安装脚本，以查看确切执行的命令：

curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o install.sh
bash -x install.sh 2>&1 | tee installation-debug.log

这将：

显示每个执行的命令 (bash -x)
显示 stdout 和 stderr (2>&1)
将所有输出保存到 installation-debug.log 以供后续查看 (tee)

详细模式对于准确识别安装失败的位置非常有帮助。在 Discord 中寻求帮助时，请包含详细日志。

第 1 步：检查安装日志

安装脚本会创建包含安装期间发生情况的宝贵信息的日志文件。

查找你的日志

安装过程会在 /data/coolify/source/ 中创建两个日志文件：

安装日志：installation-YYYYMMDD-HHMMSS.log
升级日志：upgrade-YYYY-MM-DD-HH-MM-SS.log

安装脚本内部会调用升级脚本，因此在初始安装期间会创建两个日志。

查看你的日志

找到最近的日志文件：

# 按日期列出所有日志文件（最新的在前）
ls -lt /data/coolify/source/*.log | head -5

查看安装日志：

# 将日期/时间替换为你的实际日志文件
tail -100 /data/coolify/source/installation-YYYYMMDD-HHMMSS.log

# 或者查看整个日志
cat /data/coolify/source/installation-YYYYMMDD-HHMMSS.log

查看升级日志：

# 将日期/时间替换为你的实际日志文件
tail -100 /data/coolify/source/upgrade-YYYY-MM-DD-HH-MM-SS.log

# 或者查看整个日志
cat /data/coolify/source/upgrade-YYYY-MM-DD-HH-MM-SS.log

查找内容

查找包含以下内容的错误消息：

ERROR:
Failed to
could not
Connection refused
Permission denied
No such file or directory

第 2 步：验证 Docker 安装

检查 Docker 是否正确安装并运行：

# 检查 Docker 版本
docker --version

# 检查 Docker Compose 插件
docker compose version

# 检查 Docker 守护进程是否运行
sudo systemctl status docker

docker --version 的预期输出：

Docker version 27.0.x, build xxxxx

如果 Docker 未安装或未运行：

# 启动 Docker 服务
sudo systemctl start docker

# 启用 Docker 在启动时运行
sudo systemctl enable docker

不支持通过 Snap 安装 Docker

如果你通过 snap 安装了 Docker，必须将其删除并重新正确安装 Docker。安装脚本将检测并阻止基于 snap 的 Docker 安装。

# 删除 Docker snap
sudo snap remove docker

# 然后重新运行 Coolify 安装脚本
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

第 3 步：检查端口可用性

Coolify 需要特定的端口可用。初始安装最关键的是8000 端口。

检查 8000 端口（Coolify Web 界面）

关键端口

8000 端口必须可用于 Coolify 的 Web 界面。如果其他程序正在使用此端口，安装将静默失败。

在 Linux 上使用 ss（推荐）：

sudo ss -tulpn | grep :8000

在 Linux 上使用 lsof：

sudo lsof -i :8000

在 Linux 上使用 netstat：

sudo netstat -tulpn | grep :8000

如果这些命令返回无输出，则端口空闲 ✓

如果它们显示输出，则有程序正在使用 8000 端口。示例：

tcp   LISTEN  0  4096  *:8000  *:*  users:(("some-app",pid=1234,fd=3))

检查其他 Coolify 端口

# 6001 端口 (Soketi/实时)
sudo ss -tulpn | grep :6001

# 5432 端口 (PostgreSQL - 通常仅限内部使用)
sudo ss -tulpn | grep :5432

# 6379 端口 (Redis - 通常仅限内部使用)
sudo ss -tulpn | grep :6379

修复端口冲突

如果 8000 端口正在使用中，你有两个选择：

选项 1：停止冲突的服务

# 从 ss/lsof 输出中找到进程 ID (PID)
sudo kill <PID>

# 或者如果你知道是什么服务，停止该服务
sudo systemctl stop <service-name>

选项 2：更改 Coolify 的端口（高级）

修改 /data/coolify/source/.env 并更改 APP_PORT 变量，然后重新运行安装脚本。

第 4 步：验证 Docker 容器

检查所有 Coolify 容器是否正在运行：

# 列出所有容器（运行中和已停止的）
docker ps -a

# 仅筛选 Coolify 容器
docker ps -a --filter "name=coolify"

预期容器

你应该看到以下容器：

容器名称	状态	用途
`coolify`	Up	主 Coolify 应用程序
`coolify-realtime`	Up	实时更新 (Soketi)
`coolify-db`	Up	PostgreSQL 数据库
`coolify-redis`	Up	Redis 缓存

注意

coolify-proxy 容器在安装期间不会创建。它是在你部署第一个应用程序或启用代理时创建的。

检查容器状态

如果容器已停止或已退出，请检查它们的日志：

# 查看特定容器的日志
docker logs coolify
docker logs coolify-realtime
docker logs coolify-db
docker logs coolify-redis

# 实时跟踪日志
docker logs -f coolify

重启已停止的容器

如果容器已停止，尝试启动它们：

# 启动所有 Coolify 容器
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml up -d

第 5 步：验证 Docker 镜像

检查是否成功拉取了所有必需的 Docker 镜像：

# 列出与 Coolify 相关的镜像
docker images | grep coolify
docker images | grep ghcr.io/coollabsio

预期镜像

你应该至少看到：

ghcr.io/coollabsio/coolify（或你的自定义注册表）
ghcr.io/coollabsio/coolify-helper
ghcr.io/coollabsio/coolify-realtime

缺失的镜像

如果镜像缺失，可能在安装期间出现了网络问题。尝试手动拉取它们：

# 拉取最新的 Coolify 镜像
docker pull ghcr.io/coollabsio/coolify:latest
docker pull ghcr.io/coollabsio/coolify-helper:latest
docker pull ghcr.io/coollabsio/coolify-realtime:latest

# 然后重启 Coolify
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml up -d --force-recreate

注册表认证

如果你使用的是需要认证的自定义 Docker 注册表，你可能需要先运行 docker login。

第 6 步：检查 Docker 网络

验证 Coolify Docker 网络是否存在：

# 列出 Docker 网络
docker network ls | grep coolify

预期输出：

<network-id>   coolify   bridge   local

如果网络不存在，请创建它：

# 首先尝试创建支持 IPv6 的网络
docker network create --attachable --ipv6 coolify

# 如果失败，则创建不支持 IPv6 的网络
docker network create --attachable coolify

第 7 步：验证磁盘空间

检查可用磁盘空间：

df -h /

Coolify 需要：

最小 30GB 总磁盘空间
最小 20GB 可用空间

磁盘空间不足

如果你的空间少于所需空间，安装可能会完成，但在运行期间失败。考虑：

清理未使用的 Docker 资源：docker system prune -a
扩展你的磁盘/卷
使用更大的服务器

常见问题及解决方案

问题：脚本完成但未显示访问 URL

症状：

安装脚本完成
无错误消息
但未显示类似 http://your-ip:8000 的 URL

可能原因：

容器创建静默失败
网络问题导致无法获取公共 IP
Docker 镜像拉取失败

解决方案：

# 检查容器是否正在运行
docker ps --filter "name=coolify"

# 如果容器缺失，检查升级日志
cat /data/coolify/source/upgrade-*.log

# 在日志中查找错误，然后重新运行升级
cd /data/coolify/source
bash upgrade.sh latest latest ghcr.io false

问题：8000 端口已被占用

症状：

安装完成
容器看似正在运行
但无法访问 Coolify Web 界面

解决方案：

请参阅上面的第 3 步：检查端口可用性。

问题：Docker 镜像拉取失败

症状：

安装耗时很长
出现类似“failed to pull image”或“manifest unknown”的错误
某些 Docker 镜像缺失

可能原因：

网络连接问题
DNS 解析问题
注册表速率限制
自定义注册表认证问题

解决方案：

# 测试到 GitHub Container Registry 的网络连接
curl -I https://ghcr.io

# 检查 DNS 解析
nslookup ghcr.io

# 尝试手动拉取镜像
docker pull ghcr.io/coollabsio/coolify:latest

# 如果使用自定义注册表，请先登录
docker login your-registry.com

问题：权限不足

症状：

日志中出现“Permission denied”错误
无法创建目录
无法修改 /data/coolify/ 中的文件

解决方案：

安装脚本必须以 root 用户身份或以 sudo 运行：

# 使用 sudo 重新运行
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

问题：SSH 配置问题

症状：

安装完成
可访问 Coolify，但无法连接到本地服务器
Coolify 界面中出现 SSH 相关错误

可能原因：

SSH PermitRootLogin 已禁用
SSH 密钥未正确配置

解决方案：

检查 SSH 配置：

# 检查 PermitRootLogin 设置
sudo sshd -T | grep permitrootlogin

应显示：

permitrootlogin yes，或
permitrootlogin prohibit-password，或
permitrootlogin without-password

如果显示 permitrootlogin no，请参阅OpenSSH 配置指南。

手动验证清单

运行以下命令以获取完整的诊断报告：

echo "=== COOLIFY 安装诊断 ==="
echo ""

echo "1. 安装日志："
ls -lt /data/coolify/source/*.log 2>/dev/null | head -5 || echo "未找到日志"
echo ""

echo "2. Docker 版本："
docker --version
docker compose version
echo ""

echo "3. Docker 服务状态："
sudo systemctl status docker --no-pager -l
echo ""

echo "4. Coolify 容器："
docker ps -a --filter "name=coolify" --format "table {{.Names}}	{{.Status}}	{{.Ports}}"
echo ""

echo "5. Docker 镜像："
docker images --format "table {{.Repository}}	{{.Tag}}	{{.Size}}" | grep -E "REPOSITORY|coolify"
echo ""

echo "6. Docker 网络："
docker network ls | grep -E "NETWORK|coolify"
echo ""

echo "7. 8000 端口状态："
sudo ss -tulpn | grep :8000 || echo "8000 端口空闲"
echo ""

echo "8. 磁盘空间："
df -h /
echo ""

echo "9. 环境文件："
ls -lh /data/coolify/source/.env 2>/dev/null || echo ".env 文件未找到"
echo ""

在寻求帮助时，复制此诊断脚本的输出。

恢复步骤

干净重新安装

如果你想完全卸载并重新开始：

警告

这将删除所有 Coolify 数据，包括应用程序、数据库和设置！

遵循卸载指南正确移除 Coolify，然后重新运行安装脚本：

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

重试安装而不完全重置

如果你只想重试而不丢失数据：

# 重新运行安装脚本
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

该脚本设计为幂等（可安全运行多次）。

使用手动安装

如果自动脚本持续失败，请尝试手动安装方法。

获取帮助

如果你已遵循上述所有步骤但仍遇到问题，请在我们的 Discord 社区中寻求帮助。

需要提供的信息

在寻求帮助时，请包含：

你的系统信息：

cat /etc/os-release uname -m


2. **安装日志：**（最后 100 行）

   ```bash
tail -100 /data/coolify/source/installation-*.log
tail -100 /data/coolify/source/upgrade-*.log

Docker 状态：

docker ps -a --filter "name=coolify" docker images | grep coolify


4. **你在日志或屏幕上看到的任何错误消息**

5. **你已经尝试过的修复措施**

这些信息将帮助社区更快地诊断你的问题！

## 相关文档

- [安装指南](/get-started/installation)
- [手动安装](/get-started/installation#manual-installation)
- [防火墙配置](/knowledge-base/server/firewall)
- [OpenSSH 配置](/knowledge-base/server/openssh)
- [树莓派 OS 设置](/knowledge-base/how-to/raspberry-pi-os)
- [Docker 安装失败](/troubleshoot/installation/docker-install-failed)

On this page