快捷導(dǎo)航

Nginx代理導(dǎo)致API 500錯誤的排查與修復(fù)指南

更新時間：2026年07月02日 08:38:05 作者：SebastianLiam

前端訪問 http://localhost:9527/dev-api/Login/getStaticResource 返回 500 Internal Server Error,直接訪問 http://anyu-portal.test/ 正常,所以本文給大家介紹了Nginx代理導(dǎo)致API 500錯誤的排查與修復(fù)指南,需要的朋友可以參考下

問題描述

前端訪問 http://localhost:9527/dev-api/Login/getStaticResource 返回 500 Internal Server Error，直接訪問 http://anyu-portal.test/ 正常。

技術(shù)棧

前端：Vue.js + Vue CLI (devServer proxy)
后端：ThinkPHP 5.x + PHP 7.4
容器：Docker Compose (nginx, php-fpm)
代理：Nginx 反向代理

請求鏈路分析

瀏覽器 localhost:9527/dev-api/Login/getStaticResource
    ↓ Vue devServer proxy (vue.config.js)
Nginx anyu-portal-frontend.test/api/Login/getStaticResource
    ↓ Nginx location /api/ proxy_pass (anyu-front.conf)
Nginx anyu-portal.test/Login/getStaticResource
    ↓ Nginx location ~ .php$ fastcgi_pass (anyu-portal.conf)
PHP-FPM anyu-portal/Public/index.php

配置文件檢查

1. Vue devServer 代理配置

vue.config.js：

proxy: {
  [process.env.VUE_APP_BASE_API]: {
    target: 'http://anyu-portal-frontend.test/api',
    changeOrigin: true,
    pathRewrite: {
      ['^' + process.env.VUE_APP_BASE_API]: ''
    }
  }
}

VUE_APP_BASE_API = /dev-api，所以：

請求 /dev-api/Login/getStaticResource
被轉(zhuǎn)發(fā)到 http://anyu-portal-frontend.test/api/Login/getStaticResource

2. Nginx 前端站點(diǎn)配置

anyu-front.conf：

server {
    listen 80;
    server_name anyu-frontend.test *.anyu-frontend.test;
    root "/www/anyu-portal-frontend";
    location / {
        try_files $uri $uri/ /index.html;
    }
    location /api/ {
        proxy_set_header Host $http_x_forwarded_host;
        proxy_pass http://anyu-portal.test/;
    }
}

3. Nginx 后端站點(diǎn)配置

anyu-portal.conf：

server {
    listen 80;
    server_name anyu-portal.test;
    root /www/anyu-portal/Public;
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
    }
    location ~ \.php$ {
        fastcgi_pass php:9000;
        include fastcgi-php.conf;
        include fastcgi_params;
    }
}

4. Docker Compose 網(wǎng)絡(luò)配置

docker-compose.yml：

services:
  nginx:
    extra_hosts:
      - "openapi:127.0.0.1"
      - "lvs:127.0.0.1"
      - "admin:127.0.0.1"
      - "portal:127.0.0.1"
    # 缺少: anyu-portal.test:127.0.0.1

排查過程

步驟 1：直接測試后端 API

從 nginx 容器內(nèi)部直接訪問后端：

docker exec nginx curl -v http://anyu-portal.test/Login/getStaticResource

結(jié)果：返回 200 OK，后端 API 本身正常。

步驟 2：測試代理鏈路

從 nginx 容器內(nèi)部通過前端域名訪問：

docker exec nginx curl -v http://anyu-portal-frontend.test/api/Login/getStaticResource

結(jié)果：返回 500 Internal Server Error。

步驟 3：檢查 Host 頭問題

直接訪問時 curl 會發(fā)送 Host: anyu-portal.test，但通過 /api/ 代理時：

proxy_set_header Host $http_x_forwarded_host;

$http_x_forwarded_host 是客戶端請求的 X-Forwarded-Host 頭，通常為空。當(dāng) Host 頭為空時，后端 ThinkPHP 的 getStaticResource 方法無法正確識別 SERVER_NAME，導(dǎo)致找不到合作伙伴配置。

步驟 4：檢查域名解析

nginx 容器的 extra_hosts 中沒有配置 anyu-portal.test，雖然之前已經(jīng)添加了，但需要確認(rèn)是否生效。

根因分析

問題有兩個層面：

Host 頭為空：proxy_set_header Host $http_x_forwarded_host; 設(shè)置了一個通常為空的變量，導(dǎo)致轉(zhuǎn)發(fā)到后端時沒有正確的 Host 頭。
域名解析：nginx 容器內(nèi)部無法解析 anyu-portal.test（雖然之前已添加到 extra_hosts）。

后端 ThinkPHP 的 getStaticResource 方法依賴 SERVER_NAME 獲取合作伙伴配置：

public function getStaticResource() {
    $server_name = SERVER_NAME;  // 依賴 $_SERVER['SERVER_NAME']
    $redis = new Redis();
    $redis->connect(C("REDIS_HOST"), C("REDIS_PORT"));
    // ...
    if(!C('PARTNER')) {
        $this->setPartner($redis, $server_name);  // 根據(jù) server_name 獲取合作伙伴
    }
    // ...
}

當(dāng) Host 頭為空或不正確時，SERVER_NAME 無法正確識別，導(dǎo)致 C('PARTNER') 為空，后續(xù)操作失敗。

修復(fù)方案

修復(fù) 1：修改 Nginx 代理配置

文件：services/nginx/conf.d/anyu-front.conf

# 修改前
location /api/ {
    proxy_set_header Host $http_x_forwarded_host;
    proxy_pass http://anyu-portal.test/;
}
# 修改后
location /api/ {
    proxy_set_header Host anyu-portal.test;
    proxy_pass http://anyu-portal.test/;
}

修復(fù) 2：添加域名解析

文件：docker-compose.yml

services:
  nginx:
    extra_hosts:
      - "openapi:127.0.0.1"
      - "lvs:127.0.0.1"
      - "admin:127.0.0.1"
      - "portal:127.0.0.1"
      - "anyu-portal.test:127.0.0.1"  # 新增

修復(fù) 3：重載 Nginx 配置

docker exec nginx nginx -s reload

驗證

docker exec nginx curl -v http://anyu-portal-frontend.test/api/Login/getStaticResource

結(jié)果：返回 200 OK，JSON 數(shù)據(jù)正常。

總結(jié)

經(jīng)驗教訓(xùn)

Host 頭很重要：反向代理時，proxy_set_header Host 必須設(shè)置正確的值，后端框架（如 ThinkPHP）依賴它來識別當(dāng)前站點(diǎn)。
容器內(nèi)部域名解析：Docker Compose 的 extra_hosts 只對容器內(nèi)部生效，宿主機(jī)的 hosts 文件不會自動同步到容器。
排查順序：先測試直接訪問后端，再測試完整代理鏈路，定位問題出在哪一層。
變量陷阱：$http_x_forwarded_host 是客戶端請求頭，不是 Nginx 內(nèi)置變量，不要誤以為它會自動填充。

最佳實踐

location /api/ {
    proxy_set_header Host $proxy_host;  # 使用 proxy_pass 中指定的主機(jī)名
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://backend/;
}

使用 $proxy_host 可以自動獲取 proxy_pass 中指定的主機(jī)名，比硬編碼更靈活。

以上就是Nginx代理導(dǎo)致API 500錯誤的排查與修復(fù)指南的詳細(xì)內(nèi)容，更多關(guān)于Nginx代理導(dǎo)致API 500錯誤的資料請關(guān)注腳本之家其它相關(guān)文章！

您可能感興趣的文章: