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

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

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

---

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

1. 什么是反向代理

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

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

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

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

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

---

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

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

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

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 保持会话一致性

upstream backend_app {
    ip_hash;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
}

---

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

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

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

完整配置样例：

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 示例：

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 示例：

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 显式设置，如：

proxy_set_header X-App-UserId $http_x_app_userid;

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

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

String userId = request.getHeader("X-App-UserId");

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

---

5. 测试 Header 是否透传成功

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

curl -H "X-App-UserId: 12345" http://app1.example.com/test

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

---

三、Nginx 配置参数详解

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

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 匹配部分

  location /service/ {
      proxy_pass http://app/;  # 请求 /service/test → /test
  }
  

• 不加斜杠：

  location /service/ {
      proxy_pass http://app;   # 请求 /service/test → /service/test
  }
  

2. Upstream 配置详解

示例：

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 结尾请求

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

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