解决 Piwigo 上传图片时报 504 Gateway Time-out 的方法

在使用 Piwigo 等图片管理系统上传大图片或批量图片时，有些用户会遇到 504 Gateway Time-out (nginx/1.28.0) 的报错。这通常意味着 Nginx 等待上游（PHP-FPM 或 Apache、数据库等）响应超时，导致连接被中断。下面我们从常见原因、配置调整和优化方案三个方面来分析和解决这个问题。

一、常见原因

1. 上传图片过大或数量过多
   PHP 对上传大小和执行时间有限制，超出阈值会导致处理时间过长，从而被 Nginx 判定超时。

2. Nginx 超时设置过低
   默认情况下，Nginx 的请求和响应等待时间往往不超过 60 秒，长时间的图片处理会触发超时。

3. PHP-FPM 设置不合理
   php.ini 和 php-fpm.conf 的执行时间或请求超时设置过小，会导致脚本提前中断。

4. 服务器资源不足
   如果服务器内存或 CPU 紧张，图片解析、缩略图生成等操作会变慢，从而拖长请求时间。

二、解决方法

1. 修改 Nginx 配置

编辑 Nginx 配置文件（如 /etc/nginx/nginx.conf 或 /etc/nginx/sites-enabled/piwigo.conf），在 http 或 server 区域中增加超时设置和上传限制：

http {
    client_max_body_size 100M;     # 设置最大上传文件大小
    client_body_timeout 300s;      # 请求体超时
    send_timeout 300s;             # 响应发送超时
    proxy_connect_timeout 300s;    # 上游连接超时
    proxy_send_timeout 300s;       # 向上游发送超时
    proxy_read_timeout 300s;       # 读取上游响应超时
    keepalive_timeout 300s;        # 长连接保持时间
}

保存后重新加载 Nginx：

sudo systemctl reload nginx

2. 修改 PHP 配置

找到并编辑 php.ini（通常位于 /etc/php/7.x/fpm/php.ini 或 /etc/php/8.x/fpm/php.ini），调整如下参数：

upload_max_filesize = 100M     # 最大单文件上传大小
post_max_size = 120M           # 最大POST请求大小
max_execution_time = 300       # 最大执行时间
max_input_time = 300           # 最大输入时间
memory_limit = 512M            # 内存限制

修改后重启 PHP-FPM：

sudo systemctl restart php7.x-fpm   # 或 php8.x-fpm

3. 修改 PHP-FPM 配置

编辑 PHP-FPM 池配置文件（如 /etc/php/7.x/fpm/pool.d/www.conf），添加或修改以下参数：

request_terminate_timeout = 300s  # 请求超时时间
pm.max_children = 50              # 最大子进程数

保存并重启 PHP-FPM：

sudo systemctl restart php7.x-fpm

三、优化建议

1. 使用 ImageMagick 替代 GD
   在 Piwigo 设置中启用 ImageMagick，可以更高效地处理大图和缩略图生成。

2. 分批上传
   对于大量图片，建议分多次上传，减少单次请求压力。

3. 检查服务器性能
   确保内存和 CPU 足够支撑大图处理，必要时可以增加资源。

四、总结

Piwigo 上传图片时报 504 Gateway Time-out，主要原因是 Nginx 超时、PHP 配置限制或服务器性能不足。通过合理调整 Nginx 超时参数、PHP 上传和执行限制，以及优化图片处理方式，就能有效解决问题。

这种方法不仅适用于 Piwigo，也适用于 WordPress、Joomla 等基于 PHP 的 Web 应用在处理大文件上传时遇到的超时问题。