Appearance
问题现象
通过域名访问系统首页、后台或 API 接口时,页面显示 502 Bad Gateway。
根本原因
502 Bad Gateway 是 Web 服务器(Nginx)返回的标准 HTTP 状态码,表示作为反向代理网关的 Nginx 尝试连接后端上游服务器(Swoole 服务监听的 127.0.0.1:20697)时连接被拒绝或超时。
最常见的原因包括:
- 未创建或未正确配置
.env环境变量文件:Swoole 启动时初始化数据库与 Redis 连接池失败导致进程秒退崩溃。 - Swoole 守护进程未启动或崩溃退出。
- Nginx 反向代理配置错误或端口不一致:
proxy_pass端口与 Swoole 监听端口不匹配,或缺少必要的代理请求头。 - Swoole 进程遭遇致命错误后陷入反复重启(Crash Loop)。
解决与排查流程
第一步:排查是否新建并配置了 .env 文件
新商户部署最常见疏忽是缺少 .env 文件或配置有误:
- 检查项目根目录下是否存在
.env文件:bashls -la .env - 若不存在,请从模板文件复制创建:bash
cp .example.env .env - 检查
.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 反向代理配置
- 查看 Swoole 实际配置端口:打开
config/swoole.php或.env,确认server.port(默认20697)。 - 检查站点 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; } - 确保
proxy_pass端口与 Swoole 监听端口完全一致。
第四步:检查端口监听状态
在终端中检查该端口是否处于监听状态:
bash
netstat -tlpn | grep 20697
lsof -i :20697若端口处于 LISTEN 状态且反向代理指向正确,再次刷新浏览器即可正常访问。