AltServer部署BookStack后出现Nginx 502 Bad Gateway错误求助

问题背景 #

在AltServer 10上部署BookStack后出现502 Bad Gateway错误，相关信息如下：

Nginx配置（/etc/nginx/sites-available.d/bookstack.conf） #

server {
  listen 80;
  listen [::]:80;

  server_name 127.0.0.1;

  root /var/www/bookstack/public;
  index index.php index.html;

  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  
  location ~ \.php$ {
    include fastcgi.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
  }
}

BookStack .env配置（/var/www/bookstack/.env） #

APP_URL=http://127.0.0.1

# Database details
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=bookstack

# Mail system to use
# Can be 'smtp' or 'sendmail'
MAIL_DRIVER=smtp

# Mail sender details
MAIL_FROM_NAME="BookStack"
MAIL_FROM=bookstack@example.com

# SMTP mail options
# These settings can be checked using the "Send a Test Email"
# feature found in the "Settings > Maintenance" area of the system.
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

Nginx错误日志（/var/log/nginx/error.log） #

2023/04/27 02:59:57 [crit] 20019#20019: *1 connect() to unix:/run/php/php7.4-fpm.sock failed (2: No such file or directory) while connecting to upstream, client: 127.0.0.1, server: 127.0.0.1, request: "GET / HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.2-fpm.sock:", host: "127.0.0.1"

已尝试操作 #

• 重建BookStack数据库及用户权限
• 删除Nginx配置中的PHP处理块，仍报502，刷新页面会下载PHP源码文件
• 确认/run/目录下无php文件夹及php8.2-fpm.sock文件

排查方向与解决方案 #

1. 核心问题定位：PHP-FPM服务未正常运行 #

从日志和文件缺失来看，Nginx无法找到PHP-FPM的socket文件，说明PHP-FPM 8.2要么未安装，要么未启动。

操作步骤：

• 检查PHP-FPM 8.2状态：

  systemctl status php8.2-fpm
  

• 如果未安装，执行安装命令（基于Debian/Ubuntu系，AltServer通常兼容）：

  apt update && apt install php8.2-fpm
  

• 如果服务未启动，启动并设置开机自启：

  systemctl start php8.2-fpm && systemctl enable php8.2-fpm
  

2. 验证PHP-FPM Socket路径配置 #

如果PHP-FPM已安装但socket路径不符，需确认配置一致性：

• 打开PHP-FPM池配置文件：

  nano /etc/php/8.2/fpm/pool.d/www.conf
  

• 查找listen配置项，确认路径是否为/run/php/php8.2-fpm.sock：

  listen = /run/php/php8.2-fpm.sock
  

• 若路径不同，要么修改Nginx配置中的fastcgi_pass匹配该路径，要么修改PHP-FPM的listen路径为Nginx配置中的值，修改后重启PHP-FPM：

  systemctl restart php8.2-fpm
  

3. 修复Nginx配置问题 #

删除PHP处理块导致下载源码是因为Nginx无法解析PHP，必须保留该块。同时需确保配置生效：

• 确认Nginx配置已软链到启用目录：

  ln -s /etc/nginx/sites-available.d/bookstack.conf /etc/nginx/sites-enabled/
  

• 测试Nginx配置语法：

  nginx -t
  

• 重载Nginx配置：

  systemctl reload nginx
  

4. 检查文件权限 #

确保Nginx和PHP-FPM的运行用户（通常为www-data）对BookStack目录和socket文件有访问权限：

• 设置BookStack目录权限：

  chown -R www-data:www-data /var/www/bookstack
  

• 如果socket文件已生成但权限不足，调整权限：

  chmod 660 /run/php/php8.2-fpm.sock && chown www-data:www-data /run/php/php8.2-fpm.sock
  

5. 排查其他潜在问题 #

• 查看PHP-FPM错误日志，排查运行异常：

  cat /var/log/php8.2-fpm.log
  

• 验证数据库连接是否正常：

  mysql -u bookstack -p bookstack
  

  输入密码后若能正常登录，说明数据库配置无问题；若无法登录，需重新检查数据库用户权限或密码。
• 确认BookStack所需PHP扩展已安装：

  php -m | grep -E "mysql|mbstring|xml|gd|curl"
  

  若有缺失，安装对应扩展（例如apt install php8.2-mysql php8.2-mbstring php8.2-xml php8.2-gd php8.2-curl）

内容的提问来源于stack exchange，提问作者Ronin