网关超时 (504) 错误

当 Coolify 代理在配置的超时时间内无法从您的应用程序获取响应时，就会发生网关超时错误。这与错误网关 (502) 错误不同，后者表示代理根本无法连接到您的应用程序。

常见原因

在 Coolify 中，导致 504 网关超时错误主要有两种情况：

自定义 Docker 网络隔离 - 代理无法访问使用自定义网络的应用程序
大文件上传/下载超时 - 默认的超时设置对于大文件传输来说太短

问题 1：自定义 Docker 网络隔离

症状

部署后应用程序最初可以正常工作
几小时或几天后出现 504 网关超时错误
可以通过直接 IP 和端口访问应用程序（需要手动端口映射）
重启应用程序可以暂时解决问题
在配置中使用了自定义 Docker 网络

根本原因

当您在 Docker Compose 文件中定义自定义 Docker 网络时，coolify-proxy 容器运行在 Coolify 自己的网络中，而您的应用程序运行在自定义网络中。这种网络隔离会阻止代理访问您的应用程序，特别是当 Docker 的内部 DNS 根据时间和网络加入情况返回不同的 IP 地址时。

诊断

检查您的应用程序是否使用了自定义网络：

docker inspect <your-container-name> --format='{{range $k,$v := .NetworkSettings.Networks}}Network: {{$k}}, IP: {{$v.IPAddress}}, Gateway: {{$v.Gateway}}{{println}}{{end}}'

验证代理的网络连接：

docker inspect coolify-proxy --format='{{range $k,$v := .NetworkSettings.Networks}}Network: {{$k}}, IP: {{$v.IPAddress}}, Gateway: {{$v.Gateway}}{{println}}{{end}}'

解决方案

解决方案 1：使用 Coolify 目标（推荐）

通过使用目标而不是自定义网络，让 Coolify 自动管理网络：

从您的 Docker Compose 文件中删除自定义网络定义
在 Coolify UI 的目标下配置网络目标
将您的应用程序/服务移动到所需的目标
重新部署

之前（有问题）：

services:
  app:
    image: myapp:latest
    networks:
      - custom-network

networks:
  custom-network:
    driver: bridge

之后（推荐）：

services:
  app:
    image: myapp:latest
    # 让 Coolify 处理网络

解决方案 2：手动网络连接（临时）

如果您必须使用自定义网络，请手动连接代理：

docker network connect <your-network-name> coolify-proxy

注意： 这是一个临时修复措施，在代理重启后可能需要重新应用。

问题 2：大文件上传/下载超时

症状

上传大文件 (>100MB) 时出现 504 错误
向注册表推送大型 Docker 镜像时出现 504 错误
长时间运行的请求期间出现 504 错误（Traefik/Nginx 超过 60 秒）
小文件和快速请求正常工作

根本原因

默认超时行为取决于您的代理：

Traefik：默认读取超时为 60 秒
Caddy：没有默认超时（请求可以无限期运行）
Nginx（一键数据库）：默认超时为 60 秒

任何超过配置超时的请求都会导致 504 网关超时错误，即使后端应用程序仍在处理该请求。

诊断

检查您使用的是哪种代理：
- 导航到 Coolify UI 中的 服务器 > [您的服务器] > 代理
- 将显示代理类型（Traefik、Caddy 等）
检查当前代理配置：
- 导航到 服务器 > [您的服务器] > 代理 并查找任何超时设置
- 检查您的应用程序/服务是否有可能覆盖默认值的自定义标签
在应用程序日志中监控请求持续时间：
- 在 Coolify 中导航到您的应用程序/服务日志
- 查找超过 60 秒的长时间运行请求
使用较小的文件进行测试以确认是否与大小相关

解决方案

解决方案 1：增加代理超时

配置方法取决于您的代理类型：

对于 Traefik（默认代理）

添加自定义 Traefik 配置以增加超时。根据您的需要，有多种选项可以实现此目的：

导航到服务器的代理设置，并在命令部分下添加新的超时时间：

command:
  - '--entrypoints.https.transport.respondingTimeouts.readTimeout=5m'
  - '--entrypoints.https.transport.respondingTimeouts.writeTimeout=5m'
  - '--entrypoints.https.transport.respondingTimeouts.idleTimeout=5m'

在官方文档中阅读更多关于 Traefik 超时的信息。

对于 Caddy

由于 Caddy 没有默认超时，您通常不会遇到超时问题。但是，如果您需要设置超时（出于安全或资源管理原因）：

将以下内容添加到 Coolify 中的 容器标签：

# 设置 5 分钟超时 (300 秒)
caddy.servers.timeouts.read_body=300s
caddy.servers.timeouts.read_header=300s
caddy.servers.timeouts.write=300s
caddy.servers.timeouts.idle=5m

在官方文档中阅读更多关于 Caddy 超时的信息。

对于 Nginx（一键数据库）

无法直接修改 Coolify 中一键数据库的 Nginx 配置。相反，完全绕过 Nginx 以避免超时问题：

导航到 Coolify 中的数据库设置
禁用 "使其公开可用？" 选项
使用 端口映射 直接暴露数据库端口并重启数据库
这将从容器直接映射端口，绕过 Nginx 及其超时限制

示例： 对于 PostgreSQL 数据库，映射端口 5432:5432 以直接访问它，而无需任何代理超时。

在此处阅读有关公共数据库访问的更多信息：一键数据库。

解决方案 2：实现分块上传

对于非常大的文件，请考虑在您的应用程序中实现分块上传：

在客户端将大文件拆分为较小的块
单独上传块（每个块都在超时限制之下）
在服务器端重新组装

解决方案 3：使用后台处理

对于长时间运行的操作：

接受请求并立即返回作业 ID
在后台处理请求
提供一个端点来检查作业状态

快速诊断清单

按以下步骤操作以识别您的具体问题：

检查错误代码：
- 504 = 网关超时（本指南）
- 502 = 错误网关（请参阅错误网关故障排除）
检查时间：
- 立即 = 可能是网络/配置问题
- 大约 60 秒后 = 可能是超时问题
- 几小时/几天后随机出现 = 可能是网络隔离问题

检查网络配置：

# 列出所有 Docker 网络
docker network ls

# 检查您的容器正在使用哪些网络
docker ps --format "table {{.Names}}	{{.Networks}}"

预防提示

避免使用自定义 Docker 网络，除非绝对必要
在初始设置期间为您的应用程序需求设置适当的超时时间
实施健康检查 以保持连接性
定期监控代理日志 以查找超时模式
对于长时间运行的操作使用进度指示器 以防止客户端超时

支持

如果这些解决方案无法解决您的网关超时问题：

收集诊断信息：

# 保存此输出
docker ps --format "table {{.Names}}	{{.Networks}}	{{.Status}}"
docker logs coolify-proxy --tail 200 > proxy-logs.txt
docker logs <your-container-name> --tail 200 > app-logs.txt

加入我们的 Discord 社区
分享您的配置、日志以及您尝试过的具体步骤

On this page