Skip to content

问题现象 ​

通过域名访问系统首页、后台或 API 接口时,页面显示 502 Bad Gateway。


根本原因 ​

502 Bad Gateway 是 Web 服务器(Nginx)返回的标准 HTTP 状态码,表示作为反向代理网关的 Nginx 尝试连接后端上游服务器(Swoole 服务监听的 127.0.0.1:20697)时连接被拒绝或超时。

最常见的原因包括:

  1. 未创建或未正确配置 .env 环境变量文件:Swoole 启动时初始化数据库与 Redis 连接池失败导致进程秒退崩溃。
  2. Swoole 守护进程未启动或崩溃退出。
  3. Nginx 反向代理配置错误或端口不一致:proxy_pass 端口与 Swoole 监听端口不匹配,或缺少必要的代理请求头。
  4. Swoole 进程遭遇致命错误后陷入反复重启(Crash Loop)。

解决与排查流程 ​

第一步:排查是否新建并配置了 .env 文件 ​

新商户部署最常见疏忽是缺少 .env 文件或配置有误:

  1. 检查项目根目录下是否存在 .env 文件:
    bash
    ls -la .env
  2. 若不存在,请从模板文件复制创建:
    bash
    cp .example.env .env
  3. 检查 .env 中的核心连接配置:
    • DATABASE.HOSTNAME、DATABASE.DATABASE、DATABASE.USERNAME、DATABASE.PASSWORD、DATABASE.HOSTPORT 是否与实际数据库一致;
    • REDIS.REDIS_HOSTNAME、REDIS.PORT、REDIS.REDIS_PASSWORD 是否正确;
    • 若 MySQL 或 Redis 密码错误或服务未启动,Swoole 在启动初始化连接池时将直接崩溃退出,造成 Nginx 报 502。

第二步:检查 Swoole 服务是否正在运行 ​

在终端中执行以下命令查看是否有 Swoole 进程存在:

bash
ps -ef | grep "php think swoole"
  • 若无相关进程:说明 Swoole 服务未启动。进入 Supervisor 管理器启动守护进程,或在命令行执行 php think swoole。
  • 若 Supervisor 状态显示 FATAL / BACKOFF:请以前台命令运行 php think swoole 查看启动崩溃的具体报错(常见原因为缺少扩展、proc_open 未解禁或数据库/Redis 无法连接)。

第三步:检查 Nginx 反向代理配置 ​

  1. 查看 Swoole 实际配置端口:打开 config/swoole.php 或 .env,确认 server.port(默认 20697)。
  2. 检查站点 Nginx 反向代理配置:
    nginx
    location / {
        proxy_pass http://127.0.0.1:20697;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
  3. 确保 proxy_pass 端口与 Swoole 监听端口完全一致。

第四步:检查端口监听状态 ​

在终端中检查该端口是否处于监听状态:

bash
netstat -tlpn | grep 20697
lsof -i :20697

若端口处于 LISTEN 状态且反向代理指向正确,再次刷新浏览器即可正常访问。

安徽用易软件科技有限公司 · 承信租 V4 官方技术文档中心