Nginx 配置参数全解版：Nginx 反向代理与负载均衡；Nginx 配置规范与 Header 透传实践指南；Nginx 配置参数详解

郝开2025-04-27 9:52

Nginx 配置参数全解版：Nginx 反向代理与负载均衡；Nginx 配置规范与 Header 透传实践指南；Nginx 配置参数详解

  • [Nginx 反向代理与负载均衡配置，Header 透传到后端应用（参数全解版）](#Nginx 反向代理与负载均衡配置，Header 透传到后端应用（参数全解版）)
  • [一、Nginx 反向代理与负载均衡](#一、Nginx 反向代理与负载均衡)
    • [1. 什么是反向代理](#1. 什么是反向代理)
    • [2. Upstream 配置与负载均衡策略](#2. Upstream 配置与负载均衡策略)
      • [Upstream 的集中配置方式（推荐）](#Upstream 的集中配置方式（推荐）)
      • [Upstream 支持的负载均衡策略](#Upstream 支持的负载均衡策略)
    • [3. 常见部署场景：公网访问后端应用](#3. 常见部署场景：公网访问后端应用)
  • [二、Nginx 配置规范与 Header 透传实践指南](#二、Nginx 配置规范与 Header 透传实践指南)
    • [1. Nginx 配置文件结构推荐](#1. Nginx 配置文件结构推荐)
    • [2. 在 conf.d 中编写自定义配置](#2. 在 conf.d 中编写自定义配置)
      • [app1.conf 示例：](#app1.conf 示例：)
    • [3. 自定义 Header 命名规范](#3. 自定义 Header 命名规范)
    • [4. Header 透传到后端应用](#4. Header 透传到后端应用)
    • [5. 测试 Header 是否透传成功](#5. 测试 Header 是否透传成功)
  • [三、Nginx 配置参数详解](#三、Nginx 配置参数详解)
    • [1. 反向代理基础配置与参数详解](#1. 反向代理基础配置与参数详解)
    • [2. Upstream 配置详解](#2. Upstream 配置详解)
    • [3. Location 匹配规则详解](#3. Location 匹配规则详解)

Nginx 反向代理与负载均衡配置，Header 透传到后端应用（参数全解版）

本篇文档从 反向代理 和 负载均衡 两个核心维度，全面介绍 Nginx 配置方式，细化到每一个可配置参数、其作用、可选值与推荐实践。

一、Nginx 反向代理与负载均衡

1. 什么是反向代理

反向代理（Reverse Proxy）是 Nginx 最核心的功能之一。客户端请求并不直接访问后端服务，而是通过 Nginx 中转，具备以下优势：

  • 安全隔离（隐藏真实后端 IP）
  • 请求调度（负载均衡/转发）
  • 协议转换（如 HTTPS → HTTP）
  • 限流、缓存、熔断等控制能力

示例配置（最简单反向代理）：

bash 复制代码 
server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

2. Upstream 配置与负载均衡策略

在大多数生产环境中，后端往往不止一个服务实例，需要将请求合理分发，这就需要使用 Nginx 的 upstream 模块。

Upstream 的集中配置方式（推荐）

bash 复制代码 
upstream backend_app {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    server 10.0.0.13:8080;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://backend_app;
    }
}

Upstream 支持的负载均衡策略

策略 说明
round-robin（默认） 轮询，平均分配请求
least_conn 分发到连接最少的服务
ip_hash 同一客户端 IP 始终转发给同一服务器
hash $variable 根据某变量做 hash 分配（需 nginx-upstream-hash 模块）

示例：ip_hash 保持会话一致性

bash 复制代码 
upstream backend_app {
    ip_hash;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
}

3. 常见部署场景：公网访问后端应用

场景描述：

外部访问 www.example.com，访问请求由 Nginx 接收并反向代理至某个后端服务：

bash 复制代码 
[外部用户浏览器] ──▶ [Nginx网关服务器] ──▶ [后端 SpringBoot 应用]

完整配置样例：

bash 复制代码 
upstream my_app {
    server 192.168.10.101:8080;
    server 192.168.10.102:8080;
}

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://my_app;

        # 反向代理头部设置（建议标准写法）
        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;

        # 自定义用户上下文透传
        proxy_set_header X-App-UserId $http_x_app_userid;
        proxy_set_header X-App-Device-Type $http_x_app_device_type;

        # 连接超时与读取超时
        proxy_connect_timeout 5s;
        proxy_read_timeout 10s;
    }
}

二、Nginx 配置规范与 Header 透传实践指南

1. Nginx 配置文件结构推荐

在大型项目中，我们强烈建议使用模块化配置管理方式：

推荐目录结构：

复制代码 
/nginx/
├── conf/
│   ├── nginx.conf          # 主配置文件，负责引入其他配置
│   └── conf.d/				# 子配置文件
│       ├── default.conf    # 默认虚拟主机
│       ├── app1.conf       # 自定义业务配置1
│       └── app2.conf       # 自定义业务配置2

nginx.conf 示例：

nginx 复制代码 
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    # 🔽 引入业务配置
    include /nginx/conf.d/*.conf;
}

2. 在 conf.d 中编写自定义配置

app1.conf 示例：

bash 复制代码 
server {
    listen 80;
    server_name app1.example.com;

    location / {
        proxy_pass http://backend_app1;

        # 设置超时时间
        proxy_connect_timeout 3s;
        proxy_read_timeout 10s;

        # 透传 Host 头
        proxy_set_header Host $host;

        # 透传真实 IP
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 透传用户代理
        proxy_set_header User-Agent $http_user_agent;

        # 自定义 Header 示例（透传用户ID）
        proxy_set_header X-User-Id $http_x_user_id;
    }

    # 健康检查或静态文件可在此配置
    location /health {
        return 200 'ok';
        add_header Content-Type text/plain;
    }
}

3. 自定义 Header 命名规范

为了保持系统整洁、避免命名冲突，自定义 Header 推荐使用统一前缀 ，例如：X-App- 或 X-Project-，具体建议如下：

用途 Header 示例 说明
用户标识 X-App-UserId 用户唯一标识
设备类型 X-App-Device-Type mobile / pc / tablet 等
请求来源 X-App-Source 来源区分，如 app、web 等
语言标识 X-App-Lang 如 zh-CN / en-US

统一使用中划线连接，首字母大写，避免使用下划线（Nginx中设置请求头不能正确识别下划线）。

4. Header 透传到后端应用

前提 ：Nginx 中使用 proxy_set_header 显式设置，如：

bash 复制代码 
proxy_set_header X-App-UserId $http_x_app_userid;

$http_x_app_userid 这个变量表示客户端请求中的某个 HTTP 请求头（header），其中 <header_name> 是 全部小写，所有中划线 - 替换为下划线 _ 的形式。

后端读取方式（以 Java 为例）：

java 复制代码 
String userId = request.getHeader("X-App-UserId");

注意 Header 名区分大小写敏感与否根据语言不同略有差异。

5. 测试 Header 是否透传成功

你可以使用工具如 curl 进行测试：

bash 复制代码 
curl -H "X-App-UserId: 12345" http://app1.example.com/test

观察后端日志是否能成功接收到 X-App-UserId 这个 Header。

三、Nginx 配置参数详解

1. 反向代理基础配置与参数详解

bash 复制代码 
location /api/ {
    proxy_pass http://backend_service/;

    # 标准反代头部设置
    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;

    # 自定义头部示例
    proxy_set_header X-Work-No $http_x_work_no;

    proxy_connect_timeout 5s;
    proxy_read_timeout 10s;
}

参数说明：

指令 作用 示例值 / 类型 说明
proxy_pass 设置反向代理地址 http://backend/ 加斜杠 表示替换路径前缀，不加斜杠保留请求路径
proxy_set_header 设置透传头部 host, remote_addr, $http_x_xxx 传递客户端信息、自定义信息到后端
proxy_connect_timeout 连接后端超时时间 5s 超时失败将返回 504
proxy_read_timeout 后端响应超时时间 10s 读取响应超过时间将失败
proxy_send_timeout 向后端发送请求超时 10s 默认为 60s

proxy_pass 加不加斜杠的区别：

  • 加斜杠 /：去除 location 匹配部分

    bash 复制代码 
    location /service/ {
    proxy_pass http://app/;  # 请求 /service/test → /test
}

  • 不加斜杠：

    bash 复制代码 
    location /service/ {
    proxy_pass http://app;   # 请求 /service/test → /service/test
}

2. Upstream 配置详解

示例：

bash 复制代码 
upstream znrpt_backend {
    least_conn;
    server 10.218.0.3:19090 max_fails=3 fail_timeout=10s;
    server 10.218.0.4:19090 backup;
}
参数 说明 可选值
least_conn 将请求转发给连接最少的服务器 N/A
server 指定上游服务器 IP:PORT
max_fails 最大失败次数，超过则标记为不可用 整数（默认1）
fail_timeout 设置不可用的持续时间 秒数，如 10s
backup 备用服务器，仅主服务器全部失效时启用 无参数值

3. Location 匹配规则详解

常用匹配方式：

类型 示例 含义
精确匹配 location = /login 仅匹配 /login
前缀匹配 location /api/ 匹配 /api/xxx
正则匹配 location ~* \.php$ 匹配所有 .php 结尾请求

建议前缀匹配中使用统一命名，如：

bash 复制代码 
location /xxapp_backend/ {
    proxy_pass http://xxapp_backend/;
}
相关推荐
小灰灰__20 分钟前
Linux安装ffmpeg7.1操作说明
linux·运维·服务器
互联网搬砖老肖26 分钟前
运维打铁：Centos 7 安装 redis_exporter 1.3.5
运维·redis·centos
BXCQ_xuan1 小时前
Typecho博客网站头部SEO优化完整指南
运维·服务器·数据库·php·web
鱼饼6号3 小时前
Jenkins Pipeline 构建 CI/CD 流程
linux·运维·服务器·ci/cd·容器·jenkins
国际云，接待3 小时前
[特殊字符]服务器性能优化：从硬件到AI的全栈调优指南
运维·服务器·人工智能·阿里云·性能优化·架构·云计算
ak啊3 小时前
Nginx 常见问题总结与解决
nginx
阿巴～阿巴～3 小时前
云服务器 —— 公有 IP 与 私有 IP
运维·服务器·tcp/ip
程序猿(雷霆之王)4 小时前
Linux——动静态库
linux·运维·服务器
JhonKI4 小时前
【Linux网络】打造初级网络计算器 - 从协议设计到服务实现
linux·运维·网络
敖云岚4 小时前
【Linux】Centos7 安装 Docker 详细教程
linux·运维·服务器
热门推荐
01KGG转MP3工具|非KGM文件|解密音频02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03我决定放弃搞 Java 了04YOLOv5改进 | 添加CA注意力机制 + 增加预测层 + 更换损失函数之GIoU05YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】06DeepSeek各版本说明与优缺点分析07西电B测-计算机网络综合实验(含验收问题)08yolov8，yolo11，yolo12 服务器训练到部署全流程 笔记09苍穹外卖面试总结10最新 Kubernetes 集群部署 + flannel 网络插件（保姆级教程，最新 K8S 版本）