Nginx同域名端口多服务反向代理/docs路径异常问题求助

解决方案 #

问题根源 #

你的配置问题出在Nginx的proxy_pass路径匹配逻辑上：当proxy_pass目标路径末尾不带斜杠时，Nginx会将location匹配的前缀与后续请求路径拼接后转发，导致/train/docs被错误转发到http://127.0.0.1:6004/train/docs（而非服务端实际存在的/docs端点）；同时部分文档页面的静态资源引用路径会因前缀代理出现错误，导致页面加载异常。

正确配置方案 #

以下两种方案均可彻底解决问题：

方案1：利用proxy_pass斜杠特性简化配置

通过在proxy_pass目标路径末尾添加斜杠，让Nginx自动剥离location匹配的前缀，直接转发剩余路径到服务端根路径：

# 6004端口的train服务
location ^~ /train {
    proxy_pass http://127.0.0.1:6004/;
    # 必要的代理请求头，避免后端服务识别异常
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# 6005端口的predict服务
location ^~ /predict {
    proxy_pass http://127.0.0.1:6005/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

方案2：路径重写实现精准转发

通过rewrite指令显式转换请求路径，适合需要更精细控制的场景：

# train服务（兼容带/不带末尾斜杠的请求）
location ^~ /train/ {
    rewrite ^/train/(.*)$ /$1 break;
    proxy_pass http://127.0.0.1:6004/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location = /train {
    return 302 /train/;
}

# predict服务（兼容带/不带末尾斜杠的请求）
location ^~ /predict/ {
    rewrite ^/predict/(.*)$ /$1 break;
    proxy_pass http://127.0.0.1:6005/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location = /predict {
    return 302 /predict/;
}

关键配置说明 #

1. ^~修饰符：确保该location优先于其他正则匹配规则，避免路径匹配冲突。
2. 代理请求头：添加Host、X-Real-IP等头部，让后端服务（如FastAPI、Flask）能正确识别客户端信息和请求协议，避免文档页面静态资源加载失败。
3. 斜杠兼容：方案2中location = /train用于处理用户直接访问/train（不带斜杠）的情况，重定向到带斜杠的路径，确保静态资源引用路径正确。

验证步骤 #

配置完成后，执行以下命令重载Nginx：

sudo nginx -t && sudo systemctl reload nginx

访问classifier.domain.net/train/docs和classifier.domain.net/predict/docs即可正常加载文档页面。

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