Nginx 基本使用配置大全

基本使用

1.1 反向代理

bash 复制代码

location /api/ {
          proxy_pass http://localhost:8080/; 
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
        }

在server块中定义, 会将

http://localhost/api/helloWorld

转发到

http://localhost:8080/helloWorld

注意两边都要以反斜杠结尾 .

1.2 日志输出

首先,在http块添加一个自定义格式 custom

dart 复制代码

log_format  custom  ' $remote_user [$time_iso8601] "$request" '
                     '$status $body_bytes_sent "$http_referer" '
                     '"$http_user_agent" "$http_x_forwarded_for"'
                     '"$request_time" "$scheme" ';

然后在server块中定义日志

ini 复制代码

charset koi8-r;
access_log  /data/logs/localhost.access.log  custom;

访问 http://localhost/api/helloWorld , 可以看到输出以下内容:

$2025-10-21T09:23:56+08:00\] "GET /api/helloWorld HTTP/1.1" 200 127 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" "-""0.017" "http"$

|---------------------------|----------------------------------------------------------|------------------------------------------------------------------------------|-------------------------------------------------------------------|
| $remote_user | 客户端通过 HTTP 认证的用户名（若未开启认证，固定为 "-"） | -（未认证）、admin（已认证） | 用于记录 "是否有用户通过认证访问服务"，若你的服务无需登录认证，该字段主要显示为 "-"。 |
| [$time_local] | Nginx 接收请求的本地时间（默认格式：dd/Mon/yyyy:HH:mm:ss +时区） | [21/Oct/2025:16:30:00 +0800] | 核心时间字段，用于定位 "请求发生的具体时间"，默认格式包含时区（+0800 即东八区）。 |
| $time_iso8601 | ISO 标准格式（`yyyy-MM-ddTHH:mm:ss+时区`） | `2025-10-21T16:30:00+08:00` | | | `"$ request" | 完整的 HTTP 请求行（包含请求方法、请求路径、HTTP 协议版本） |"GET /api/helloWorld HTTP/1.1" | 最核心的字段之一，可快速判断 "用户访问了哪个接口、用的什么请求方法（GET/POST）"。 | | $status` | Nginx 返回给客户端的 HTTP 状态码 | `200`（成功）、`404`（接口不存在）、`502`（后端错误） | 用于统计 "请求成功率"，快速定位异常请求（如大量 404 可能是路径写错，大量 502 可能是后端宕机）。 | | `$ body_bytes_sent | Nginx 发送给客户端的 "响应体字节数"（不含响应头，仅内容大小） |11（返回 "Hello World" 共 11 字节）、2048 | 用于计算 "单请求的数据传输量"，排查 "是否有大文件传输导致带宽占用过高"。 | |" $http_referer"` | 客户端的 "来源页面"（即用户从哪个页面跳转过来访问当前接口，空则为 "-"） | `"https://www.baidu.com/"`、`"-"` | 用于分析 "用户的访问来源"，比如判断是否有外部网站引流，或是否存在 "跨站请求"。 | | `"$ http_user_agent" | 客户端的 "浏览器 / 工具标识"（包含设备、浏览器版本、系统信息） |"Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0 Safari/537.36" | 用于统计 "用户使用的设备 / 浏览器占比"，比如判断是否有手机端用户访问，或是否有爬虫请求（如"curl/7.29.0"）。 | | " $http_x_forwarded_for"` | 多层代理场景下的 "客户端真实 IP"（若只有 1 层 Nginx 代理，取值等于`$ remote_addr） | "192.168.1.100"、"-"（无代理） | 核心用于 "定位真实用户 IP"，若你的服务前面有 CDN 或负载均衡器，必须通过该字段获取真实 IP（需后端配合解析）。 | | " $request_time"` | 整个请求的 "总耗时"（从 Nginx 接收请求到完全发送响应给客户端的时间，单位：秒，保留 3 位小数） | `"0.050"`（50 毫秒）、`"1.234"`（1.234 秒） | 用于排查 "慢请求"，若该值过大（如超过 1 秒），可能是 Nginx 转发慢或后端处理慢。 | | `"$ scheme" | 请求使用的 "协议类型"（HTTP 或 HTTPS） |"http"、"https"` | 用于区分 "HTTP 请求和 HTTPS 请求占比"，若你的服务已配置 HTTPS，可通过该字段验证 HTTPS 是否生效。 |

Nginx 的日志路径（access_log指令）和格式（log_format指令）遵循严格的优先级逻辑，本质是 "更具体的配置覆盖更通用的配置"，具体规则如下：

优先级从高到低：location 块 > server 块 > http 块 > 编译默认值

编译默认值 ：Nginx 编译时会内置一个默认日志路径（如源码安装的nginx/logs/access.log，yum/apt 安装的/var/log/nginx/access.log），这就是你看到的 "nginx 目录自带的 log/access.log" 的来源；
http 块配置 ：在http块中定义的access_log是全局默认值，所有未单独配置的server块都会继承；
server 块配置 ：在server块中定义的access_log会覆盖http块的全局配置，仅对当前虚拟主机生效；
location 块配置 ：在location块中定义的access_log优先级最高，可针对特定接口（如/api/）单独记录日志。

由于我们已经在server块中定义了日志,这个优先级是最高的.

1.3 重定向

有时候会有这样的需求,就是访问 /a 的地址,要直接转到另一个毫不相干的网址, 这就需要重定向.

bash 复制代码

location / {
    location = /a {
        return 301 http://localhost:8080/user/isLogin;
    }
}

301 是 HTTP 状态码中的 "永久重定向"，特点是：

浏览器会缓存该重定向规则（下次访问 /a 时，不发请求直接跳转）；
常用于 "旧地址废弃，引导到新地址"（如你的场景可能是 "废弃 /a 路径，统一用 8080 的 /user/isLogin 接口"）。

1.4 多个server

一个NG配置文件可以写多个Server, 监听不同的端口, 以下配置是增加一个server,监听9292端口, 输出不同名称的日志。

ini 复制代码

server {
    listen       9292;
    server_name  localhost2;

    charset koi8-r;
    access_log  /data/logs/localhost2.access.log  custom;

    location / {
        location = /b {
            return 301 http://localhost:8080/user/isLogin;
        }
    }

}

1.5 upstream 负载均衡模块

upstream是关键字必须要有，后面的www_server_pool为一个Upstream集群组的名字，可以自定义；

ini 复制代码

upstream backend_local {
    # 对 8080 端口的服务器配置：权重1，失败2次后暂时下线10秒
    server 127.0.0.1:8080 weight=1 max_fails=2 fail_timeout=10s;
    # 对 8081 端口的服务器配置：权重2，同样的健康检查规则
    server 127.0.0.1:8081 weight=2 max_fails=2 fail_timeout=10s;
}

1、upstream是关键字必须要有，后面的www_server_pool为一个Upstream集群组的名字，可以自定义；

2、server是关键字固定，后面可以接域名或IP。如果不指定端口，默认是80。结尾有分号。

3、weight代表权重，数值越大分配的请求就越多。

upstream 必须和 server 块（Nginx 的虚拟主机配置）一起使用，两者是配合工作的关系：

upstream 的作用是定义后端服务器集群（比如 backend_local 就是一个集群，包含 8080 和 8081 两个服务）；而 server 块的作用是接收客户端请求，并将请求转发到 upstream 定义的集群中。

如果只有 upstream 而没有 server 块，Nginx 虽然能加载配置，但这个集群不会被任何请求使用（因为没有入口接收请求并转发）；反之，如果 server 块想要转发请求到多个后端，就必须通过 upstream 定义集群（否则只能硬编码单个后端地址）。

具体看代码:

ini 复制代码

server {
    listen       80;
    server_name  localhost;

    charset koi8-r;
    access_log  /data/logs/localhost.access.log  custom;

    location / {
        location = /a {
            return 301 http://localhost:8080/user/isLogin;
        }
    }

    location /api/ {
    #   proxy_pass http://localhost:8080/; 
        proxy_pass http://backend_local/;  # 关键：通过 upstream 名称转发
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   html;
    }

}

用IDEA两个端口各启动一个服务

多次请求http://localhost/api/helloWorld

发现两台服务都有接收到请求,其中8081更多一些(因为权重高)