本文在专栏中的位置#

这是整个 Nginx 专栏的第一篇。

在学习 server、location、proxy_pass、upstream、缓存和限流之前，首先必须回答一个更基础的问题：为什么一个已经能够监听 8080 端口并返回 HTTP 响应的 Spring Boot 服务，前面还要再放一层 Nginx？

如果不能回答这个问题，后续学习很容易退化成背配置：看到静态资源就写 root，看到转发就写 proxy_pass，看到多实例就写 upstream，但不知道每个能力处于请求链路的哪一层，也不知道什么时候应该使用 Nginx，什么时候应该交给云负载均衡器、API Gateway、CDN 或 Kubernetes Gateway。

本文先建立整体架构认知。下一篇将进入 Nginx 配置模型，系统讲解 main → events/http → server → location 的层级关系，以及一次请求如何匹配到具体配置。

学习目标#

完成本文后，你应该能够：

1. 画出客户端访问后端系统时，从 DNS 到应用服务的完整请求链路；
2. 解释为什么不建议让 Spring Boot 等应用进程直接承担所有公网入口职责；
3. 准确区分正向代理与反向代理；
4. 说明 Nginx 作为 Web Server、反向代理、负载均衡器、TLS 终止点和内容缓存时分别承担什么职责；
5. 解释 Nginx Master/Worker 进程模型与事件驱动、非阻塞 I/O 的关系；
6. 区分客户端到 Nginx 的连接和 Nginx 到后端服务的连接；
7. 区分 Nginx、Spring Cloud Gateway、CDN、云负载均衡器和 Kubernetes Gateway 的职责边界；
8. 使用 Docker Compose 启动一个“静态资源 + Nginx + Spring Boot”最小系统；
9. 通过端口、响应头和日志验证请求究竟经过了哪些组件；
10. 根据业务规模判断是否需要引入 Nginx，以及 Nginx 是否形成了新的单点。

1.1 Spring Boot 已经能提供 HTTP 服务，为什么还要 Nginx#

一个最简单的 Spring Boot 应用可以监听 8080 端口：

1
http://server-ip:8080/api/hello

它能够：

• 接收 HTTP 请求；
• 执行 Controller、Service 和数据访问逻辑；
• 返回 JSON；
• 处理认证、事务和业务异常。

从“能不能运行”的角度，Nginx 并不是必需组件。开发环境、内部工具、小型服务或单机演示完全可以直接访问应用端口。

问题在于：应用服务器擅长执行业务，不等于它适合承担完整的互联网入口职责。

当系统从本地开发走向生产，会逐渐出现以下需求：

• 用户希望通过 https://api.example.com 访问，而不是记住 10.0.1.25:8080；
• 前端静态文件、图片、下载文件不希望占用 Java 应用线程和堆内存；
• 后端扩容为多个实例，需要在实例之间分配流量；
• 证书应集中配置和续期，而不是散落在每个微服务中；
• 希望统一记录访问日志、真实客户端 IP、耗时和上游状态；
• 需要限制请求体大小、连接速率和恶意流量；
• 应用升级或实例故障时，希望入口仍然稳定；
• 对外只开放 80/443，隐藏内部端口和服务拓扑；
• 需要同时代理 Java、Python、Node.js、对象存储等不同后端。

这些问题具有共同特征：它们大多属于入口层、连接层或通用流量处理问题，而不是订单、支付、用户、库存等业务逻辑。

因此，一种常见架构是：

1
客户端只访问 Nginx
2
Nginx 再决定：
3
- 直接返回静态文件；
4
- 将 API 请求转发到应用服务；
5
- 将请求分配到多个实例；
6
- 在入口处完成 TLS、日志、限流和缓存。

这就是 Nginx 经常位于应用服务之前的根本原因：把业务无关、重复出现、适合集中治理的入口能力，从应用进程中剥离出来。

1.2 直接暴露应用端口的主要问题#

1
10.0.1.11:8080
2
10.0.1.12:8080
3
10.0.1.13:8080

1.3 什么时候可以不使用 Nginx#

Nginx 很常用，但不是任何项目都必须部署。

下面这些场景可以暂时不引入：

判断标准不是“大家都用不用”，而是：你的请求链路中是否已经有组件承担了域名入口、TLS、路由、负载均衡、静态资源和基础流量治理。

2.1 一条典型的互联网请求链路#

实际系统不一定拥有图中的所有层。例如：

• 小型项目可能只有“客户端 → Nginx → Spring Boot”；
• 云上项目可能是“客户端 → 云 LB → Nginx → 应用”；
• Kubernetes 项目可能是“客户端 → 云 LB → Gateway Controller → Service → Pod”；
• 使用 CDN 的静态站点可能在 CDN 命中后根本不会回源；
• 采用托管 API Gateway 时，可能不再需要自建 Nginx。

2.2 每一层分别解决什么问题#

2.3 Nginx 常见部署位置#

1
Internet → Nginx → Application

1
Internet → Cloud Load Balancer → Nginx Cluster → Application

1
Internet → Nginx → API Gateway → Microservices

1
Internet → LoadBalancer Service → Gateway/Ingress Controller → Service → Pod

3.1 正向代理：代表客户端访问外部资源#

典型过程：

1. 客户端知道自己配置了代理；
2. 客户端把目标地址交给代理；
3. 代理代表客户端访问目标服务器；
4. 目标服务器看到的直接连接来源通常是代理。

常见用途：

• 企业统一出口；
• 网络访问控制；
• 隐藏客户端来源；
• 调试和抓包；
• 访问特定网络资源。

3.2 反向代理：代表服务端接收客户端请求#

典型过程：

1. 客户端只知道对外域名，例如 api.example.com；
2. 客户端连接 Nginx；
3. Nginx 根据域名、路径、请求头或配置选择后端；
4. 后端响应 Nginx；
5. Nginx 再将响应返回客户端。

客户端通常不知道真实后端是：

• 10.0.1.11:8080；
• 另一个容器；
• 多个应用实例；
• 一组 Kubernetes Pod；
• 甚至不同语言实现的服务。

3.3 对比总结#

4.1 Web Server：直接处理 HTTP 请求#

Nginx 本身就是 Web 服务器，不是“只能把请求转发给别人”的中间件。

它可以直接：

• 监听端口；
• 匹配域名和 URI；
• 返回状态码；
• 返回本地文件；
• 处理重定向；
• 添加响应头；
• 记录访问日志。

例如：

1
server {
2
    listen 80;
3
    server_name example.com;
4

5
    location = /health {
6
        return 200 "ok\n";
7
    }
8
}

访问 /health 时，请求不会进入 Spring Boot，Nginx 会直接生成响应。

4.2 静态资源服务器#

Nginx 可直接从文件系统读取并返回：

• HTML；
• CSS；
• JavaScript；
• 图片；
• 字体；
• 安装包和下载文件。

典型结构：

1
location /        → 返回前端构建产物
2
location /assets/ → 返回带 Hash 的静态资源
3
location /api/    → 转发到 Spring Boot

好处是静态资源请求不必进入 Java MVC 处理链，也可以独立配置浏览器缓存、压缩和访问日志。

对于大规模互联网分发，CDN 通常比单个 Nginx 更适合；但 Nginx 仍然可以作为 CDN 的源站或内部静态资源服务器。

4.3 反向代理#

反向代理是后端系统中最常见的 Nginx 用途。

1
location /api/ {
2
    proxy_pass http://backend:8080;
3
}

Nginx 接收客户端请求，再创建或复用另一条到后端的连接。

这里必须建立一个重要认知：

1
连接 1：Client ↔ Nginx
2
连接 2：Nginx ↔ Spring Boot

它们不是同一条 TCP 连接。Nginx 是两条连接的终点和起点：

• 对客户端而言，Nginx 是服务器；
• 对后端而言，Nginx 是客户端。

因此，两侧可以拥有不同的：

• HTTP 版本；
• TLS 状态；
• Keep-Alive 生命周期；
• 超时时间；
• 缓冲策略；
• 请求头；
• 源 IP 表现。

后续讨论 proxy_set_header、真实 IP、超时和 upstream keepalive 时，都建立在这个连接模型之上。

4.4 负载均衡器#

当一个服务有多个实例时，Nginx 可以将请求分配给一组后端：

1
upstream backend_cluster {
2
    server backend-a:8080;
3
    server backend-b:8080;
4
    server backend-c:8080;
5
}
6

7
server {
8
    listen 80;
9

10
    location /api/ {
11
        proxy_pass http://backend_cluster;
12
    }
13
}

Nginx Open Source 支持常见的轮询、最少连接、IP Hash 和通用 Hash 等方法。默认未显式指定算法时，HTTP upstream 使用轮询思想分配请求。

需要注意：

• “分发请求”不等于“业务高可用已经完成”；
• 后端故障检测、重试和非幂等请求风险需要专门设计；
• 单个 Nginx 仍然可能是单点；
• Nginx Open Source 的被动故障判断与 NGINX Plus 的主动健康检查能力不能混写。

这些内容会在第 4 篇展开。

4.5 TLS 终止点#

1
Client --HTTPS--> Nginx --HTTP/HTTPS--> Backend

Nginx 可以在入口处：

• 加载证书和私钥；
• 完成 TLS 握手；
• 选择域名证书；
• 将解密后的 HTTP 请求转发给内部服务；
• 或者再次使用 HTTPS 连接后端。

把 TLS 集中在入口层，可以减少每个应用重复管理证书的成本。但是否允许 Nginx 到后端使用明文 HTTP，要根据网络边界、合规要求和威胁模型决定，不能简单认为“内网就一定安全”。

4.6 内容缓存#

Nginx 可以缓存后端响应：

1
第一次请求：Client → Nginx → Backend
2
后续命中：Client → Nginx Cache

缓存能够减少后端压力和响应延迟，但必须区分：

• 浏览器缓存；
• CDN 缓存；
• Nginx 代理缓存；
• 应用内缓存；
• Redis 等数据缓存。

包含用户身份、Cookie、Authorization 或个性化数据的响应不能在没有完整缓存键与隔离策略的情况下共享缓存。

4.7 基础流量治理和可观测性#

Nginx 还常用于：

• 请求速率限制；
• 并发连接限制；
• 请求体大小限制；
• 超时控制；
• 基于域名和路径的路由；
• 统一 Access Log；
• 透传 Request ID；
• 记录 upstream 地址、状态和耗时；
• 返回统一错误页。

这些能力适合处理与单个业务领域无关的通用入口问题。

5.1 Master 与 Worker 进程模型#

典型 Nginx 进程结构如下：

5.2 事件驱动不是“没有进程或线程”#

Nginx 仍然运行在操作系统进程中。所谓事件驱动，指的是一个 Worker 不会为每个连接都长期占用一个独立线程并阻塞等待。

可以把网络请求理解成许多同时进行的状态机：

1
连接 A：等待客户端发送请求体
2
连接 B：等待后端返回数据
3
连接 C：等待套接字可写
4
连接 D：读取本地文件
5
连接 E：已经可以继续解析请求头

Worker 会处理当前“已经就绪”的事件，而不是在连接 A 尚未发送完数据时一直停在那里。

在 Linux 上，Nginx 通常利用 epoll 等操作系统事件通知机制：

1. Worker 将大量套接字交给内核监控；
2. 内核通知哪些套接字已经可读、可写或发生错误；
3. Worker 处理这些就绪事件；
4. 某个连接需要继续等待时，Worker 转去处理其他连接。

5.3 非阻塞 I/O 解决什么问题#

传统“一连接一线程”模型中，如果线程正在等待慢客户端、慢后端或网络数据，线程本身仍然占用栈空间和调度资源。

非阻塞事件模型的目标是：

• 减少大量连接对应的大量线程；
• 降低上下文切换；
• 让少量 Worker 管理大量处于不同等待状态的连接；
• 在慢连接较多时保持更可控的资源开销。

这并不意味着 Nginx 的任何操作都天然不会阻塞。如果在 Worker 中引入阻塞式第三方模块、同步磁盘操作或耗时脚本，仍可能阻塞该 Worker，影响它管理的其他连接。

5.4 worker_processes auto 的意义#

常见配置：

1
worker_processes auto;

它让 Nginx 根据可见 CPU 资源选择 Worker 数量。常见经验是使 Worker 数量接近可用 CPU 核心数，以减少不必要的进程调度，同时让多个核心并行处理事件。

但“Worker 数量 = CPU 核数”不是所有场景的绝对最优公式，还会受到以下因素影响：

• 容器 CPU 限额；
• CPU 亲和性；
• 磁盘 I/O；
• TLS 开销；
• 第三方模块；
• NUMA；
• 实际压测结果。

5.5 Nginx 与应用服务器不是替代关系#

Nginx 的事件模型擅长连接、代理、文件和通用流量处理；Spring Boot 擅长：

• 业务对象建模；
• 事务；
• 数据访问；
• 认证授权；
• 复杂业务规则；
• 领域服务编排。

不要因为 Nginx 能高效处理连接，就试图把复杂业务全部塞进入口配置或脚本。正确关系通常是：

1
Nginx 管入口和流量
2
Application 管业务和数据一致性

6.1 重载过程#

执行：

1
nginx -t
2
nginx -s reload

典型过程如下：

官方文档说明，Master 在收到重载信号后会验证新配置；成功时启动新 Worker 并要求旧 Worker 停止接收新连接，旧 Worker 会继续服务已有请求，完成后退出；失败时继续使用旧配置。

6.2 “优雅重载”不等于永远零风险#

仍需注意：

• 配置语法正确不代表业务路由正确；
• 长时间 WebSocket、SSE 或下载连接会让旧 Worker 长期存在；
• 频繁 reload 可能积累多代旧 Worker；
• 新配置引用的证书、文件、DNS 和后端地址可能在运行时失败；
• 容器编排平台可能直接替换整个 Pod，而不是原地 reload；
• 必须设计配置发布、验证、监控和回滚流程。

因此生产流程至少应是：

1
编辑配置
2
→ 静态检查
3
→ nginx -t
4
→ 测试环境验证
5
→ 灰度发布
6
→ reload
7
→ 观察错误率和延迟
8
→ 必要时回滚

7.1 Nginx 与 Spring Cloud Gateway#

Spring Cloud Gateway 官方将自身定位为构建在 Spring 生态之上的 API Gateway，重点是 API 路由以及安全、监控和弹性等横切能力。

两者可以组合：

1
Client → Nginx → Spring Cloud Gateway → Microservices

但不要为了“架构完整”机械增加层数。每增加一层都会增加：

• 网络跳数；
• 配置复杂度；
• 故障点；
• 日志关联难度；
• 运维成本。

7.2 Nginx 与 API Gateway#

“API Gateway”是架构角色，不是某个固定产品。Nginx 可以承担部分 API Gateway 能力，但完整 API Gateway 往往还包括：

• API Key/OAuth/JWT 认证；
• 租户配额；
• 开发者门户；
• API 生命周期管理；
• 协议转换；
• 复杂插件体系；
• 服务发现；
• 业务级审计；
• 消费者管理。

如果系统只需要域名、路径路由、TLS 和简单限流，Nginx 可能已经足够；如果需要大量动态业务策略和平台化治理，应评估专门的 API Gateway。

7.3 Nginx 与云负载均衡器#

云负载均衡器通常提供：

• 稳定公网 IP；
• 多可用区；
• 托管高可用；
• 四层或七层负载均衡；
• 与云安全组、证书和监控集成。

Nginx 则提供更可控、更细粒度的代理和内容处理能力。

常见组合：

1
Cloud LB → 多台 Nginx → 多个应用实例

云 LB 解决 Nginx 节点自身的高可用入口，Nginx 解决应用层的详细路由和治理。

7.4 Nginx 与 CDN#

CDN 的关键价值是将内容缓存到离用户更近的边缘节点。

1
Client → Nearby CDN Edge → Origin Nginx → Application

Nginx 即使性能很好，也无法改变物理距离。跨国家或跨洲访问时，CDN 的边缘网络和专线回源能力通常更有价值。

合理分工：

• CDN：大范围边缘分发、DDoS/WAF、静态缓存；
• Nginx：源站入口、回源控制、动态代理、内部路由。

7.5 Nginx 与 Kubernetes Ingress/Gateway#

必须区分三个概念：

1. Ingress/Gateway API 对象：声明“流量应该如何进入集群”；
2. Controller：监听这些 API 对象并将其转化为真实配置；
3. 数据平面代理：真正接收连接和转发流量，可能是 Nginx、Envoy、HAProxy 或云厂商负载均衡器。

所以“Ingress 是不是 Nginx”这个问题本身不准确。Ingress 是 API；某个 Ingress Controller 可能使用 Nginx 作为数据平面。

截至 2026 年，Kubernetes 官方建议优先评估 Gateway API，Ingress API 保持稳定但已冻结。新项目应根据 Controller 维护状态、Gateway API 一致性和迁移成本选择方案，而不是只搜索一份旧的 ingress-nginx YAML 就直接用于生产。

7.6 Nginx 与 Service Mesh#

Service Mesh 主要面向服务之间的东西向流量：

1
Service A → Sidecar/Node Proxy → Service B

Nginx 常见的入口代理主要面向南北向流量：

1
External Client → Nginx → Internal Service

两者可以同时存在。是否需要 Mesh 取决于：

• 服务数量；
• mTLS；
• 流量策略；
• 可观测性；
• 多集群；
• 团队运维能力。

不要把 Nginx 入口层和 Service Mesh 简单理解成互斥替代。

8.1 最终请求链路#

外部只映射 Nginx 的 8088 端口。Spring Boot 只在 Docker 内部网络暴露 8080，不直接映射到宿主机。

8.2 目录结构#

1
nginx-column-demo/
2
├── docker-compose.yml
3
├── nginx/
4
│   ├── nginx.conf
5
│   ├── conf.d/
6
│   │   └── default.conf
7
│   └── html/
8
│       └── index.html
9
└── backend/
10
    ├── Dockerfile
11
    ├── pom.xml
12
    └── src/
13
        └── main/
14
            └── java/
15
                └── com/example/demo/
16
                    ├── DemoApplication.java
17
                    └── HelloController.java

8.3 docker-compose.yml#

1
services:
2
  backend:
3
    build:
4
      context: ./backend
5
    container_name: nginx-column-backend
6
    expose:
7
      - "8080"
8
    environment:
9
      SERVER_PORT: "8080"
10
    networks:
11
      - nginx-lab
12

13
  nginx:
14
    image: nginx:1.30.3-alpine3.23
15
    container_name: nginx-column-entry
16
    depends_on:
17
      - backend
18
    ports:
19
      - "8088:80"
20
    volumes:
21
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
22
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
23
      - ./nginx/html:/usr/share/nginx/html:ro
24
    networks:
25
      - nginx-lab
26

27
networks:
28
  nginx-lab:
29
    driver: bridge

说明：

• 使用固定镜像 nginx:1.30.3-alpine3.23，避免 latest 随时间变化；
• backend 只使用 expose 声明容器内端口，不映射到宿主机；
• nginx 映射宿主机 8088 到容器 80；
• 两个容器加入同一个 Compose 网络；
• Nginx 可以通过服务名 backend 使用 Docker DNS 找到后端；
• depends_on 只表达启动依赖顺序，不等价于“后端业务已经健康”，生产环境应配合健康检查和重试边界。

8.4 nginx/nginx.conf#

1
user  nginx;
2
worker_processes auto;
3

4
error_log  /var/log/nginx/error.log notice;
5
pid        /var/run/nginx.pid;
6

7
events {
8
    worker_connections 1024;
9
}
10

11
http {
12
    include       /etc/nginx/mime.types;
13
    default_type  application/octet-stream;
14

15
    log_format main '$remote_addr - $remote_user [$time_local] '
16
                    '"$request" $status $body_bytes_sent '
17
                    '"$http_referer" "$http_user_agent" '
18
                    'request_time=$request_time '
19
                    'upstream_addr=$upstream_addr '
20
                    'upstream_status=$upstream_status '
21
                    'upstream_time=$upstream_response_time';
22

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

25
    sendfile on;
26
    keepalive_timeout 65;
27

28
    include /etc/nginx/conf.d/*.conf;
29
}

8.5 nginx/conf.d/default.conf#

1
server {
2
    listen 80;
3
    server_name _;
4

5
    location / {
6
        root /usr/share/nginx/html;
7
        index index.html;
8
    }
9

10
    location /api/ {
11
        proxy_pass http://backend:8080;
12

13
        proxy_set_header Host $host;
14
        proxy_set_header X-Real-IP $remote_addr;
15
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16
        proxy_set_header X-Forwarded-Proto $scheme;
17

18
        add_header X-Entry-Proxy nginx always;
19
    }
20

21
    location = /nginx-health {
22
        access_log off;
23
        default_type text/plain;
24
        return 200 "nginx ok\n";
25
    }
26
}

本文只解释整体职责，不深入分析 location 匹配和 proxy_pass URI 改写；它们分别是第 2、3 篇的重点。

8.6 nginx/html/index.html#

1
<!doctype html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>Nginx 专栏实验</title>
7
</head>
8
<body>
9
    <h1>Nginx 静态资源响应成功</h1>
10
    <p>这个页面由 Nginx 直接从文件系统返回，没有经过 Spring Boot。</p>
11
    <p><a href="/api/hello">访问后端 API</a></p>
12
</body>
13
</html>

8.7 backend/pom.xml#

1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
5
    <modelVersion>4.0.0</modelVersion>
6

7
    <parent>
8
        <groupId>org.springframework.boot</groupId>
9
        <artifactId>spring-boot-starter-parent</artifactId>
10
        <version>4.0.2</version>
11
        <relativePath/>
12
    </parent>
13

14
    <groupId>com.example</groupId>
15
    <artifactId>nginx-column-backend</artifactId>
16
    <version>1.0.0</version>
17
    <name>nginx-column-backend</name>
18

19
    <properties>
20
        <java.version>21</java.version>
21
    </properties>
22

23
    <dependencies>
24
        <dependency>
25
            <groupId>org.springframework.boot</groupId>
26
            <artifactId>spring-boot-starter-web</artifactId>
27
        </dependency>
28
    </dependencies>
29

30
    <build>
31
        <plugins>
32
            <plugin>
33
                <groupId>org.springframework.boot</groupId>
34
                <artifactId>spring-boot-maven-plugin</artifactId>
35
            </plugin>
36
        </plugins>
37
    </build>
38
</project>

说明：示例使用 Spring Boot 4.0.2 与 Java 21。若你的本地依赖仓库尚未同步该版本，可改为组织内已经验证的 Spring Boot 4.0.x 版本；这不影响 Nginx 实验的核心逻辑。

8.8 DemoApplication.java#

1
package com.example.demo;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5

6
@SpringBootApplication
7
public class DemoApplication {
8

9
    public static void main(String[] args) {
10
        SpringApplication.run(DemoApplication.class, args);
11
    }
12
}

8.9 HelloController.java#

1
package com.example.demo;
2

3
import jakarta.servlet.http.HttpServletRequest;
4
import org.springframework.web.bind.annotation.GetMapping;
5
import org.springframework.web.bind.annotation.RequestMapping;
6
import org.springframework.web.bind.annotation.RestController;
7

8
import java.net.InetAddress;
9
import java.util.LinkedHashMap;
10
import java.util.Map;
11

12
@RestController
13
@RequestMapping("/api")
14
public class HelloController {
15

16
    @GetMapping("/hello")
17
    public Map<String, Object> hello(HttpServletRequest request) throws Exception {
18
        Map<String, Object> result = new LinkedHashMap<>();
19
        result.put("message", "hello from Spring Boot");
20
        result.put("instance", InetAddress.getLocalHost().getHostName());
21
        result.put("serverPort", request.getLocalPort());
22
        result.put("remoteAddrSeenByBackend", request.getRemoteAddr());
23
        result.put("host", request.getHeader("Host"));
24
        result.put("xRealIp", request.getHeader("X-Real-IP"));
25
        result.put("xForwardedFor", request.getHeader("X-Forwarded-For"));
26
        result.put("xForwardedProto", request.getHeader("X-Forwarded-Proto"));
27
        return result;
28
    }
29
}

8.10 backend/Dockerfile#

1
FROM maven:3.9.11-eclipse-temurin-21-alpine AS builder
2
WORKDIR /workspace
3

4
COPY pom.xml ./
5
COPY src ./src
6
RUN mvn -B -DskipTests package
7

8
FROM eclipse-temurin:21-jre-alpine
9
WORKDIR /app
10

11
COPY --from=builder /workspace/target/nginx-column-backend-1.0.0.jar app.jar
12

13
EXPOSE 8080
14
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

8.11 启动实验#

在项目根目录执行：

1
docker compose config
2
docker compose build
3
docker compose up -d

查看状态：

1
docker compose ps

查看日志：

1
docker compose logs -f nginx backend

8.12 配置检查#

1
docker compose exec nginx nginx -t

预期输出包含：

1
syntax is ok
2
test is successful

查看 Nginx 实际加载的完整配置：

1
docker compose exec nginx nginx -T

nginx -T 比只查看某个配置文件更可靠，因为它会展开 include 后打印当前完整配置。

8.13 验证静态资源#

1
curl -i http://localhost:8088/

预期：

• 状态码 200；
• Content-Type 为 HTML；
• 响应体包含“Nginx 静态资源响应成功”；
• Spring Boot 日志中不会出现对应 Controller 请求。

这证明请求由 Nginx 直接完成。

8.14 验证 Nginx 自身健康接口#

1
curl -i http://localhost:8088/nginx-health

预期响应：

1
HTTP/1.1 200 OK
2
...
3

4
nginx ok

该请求也不会到达 Spring Boot。

8.15 验证反向代理#

1
curl -i http://localhost:8088/api/hello

预期响应头包含：

1
X-Entry-Proxy: nginx

响应体类似：

1
{
2
  "message": "hello from Spring Boot",
3
  "instance": "2d7f...",
4
  "serverPort": 8080,
5
  "remoteAddrSeenByBackend": "172.20.0.3",
6
  "host": "localhost",
7
  "xRealIp": "172.20.0.1",
8
  "xForwardedFor": "172.20.0.1",
9
  "xForwardedProto": "http"
10
}

不同环境的容器 IP 会不同。

此结果说明：

1. 客户端连接的是宿主机 8088；
2. 宿主机端口转发到 Nginx 容器 80；
3. Nginx 再连接 backend:8080；
4. Spring Boot 看到的直接网络来源是 Nginx 容器，而不是原始客户端；
5. 原始客户端信息需要通过受控的代理 Header 传递。

8.16 证明后端没有直接暴露给宿主机#

执行：

1
curl -i http://localhost:8080/api/hello

正常情况下应连接失败，因为 Compose 没有将 backend 的 8080 映射到宿主机。

这就是“隐藏内部应用端口”的最小示例。注意：它只是 Docker 网络隔离，不等同于完整安全体系；生产环境还需要安全组、防火墙、网络策略和身份认证。

8.17 查看访问日志#

1
docker compose exec nginx tail -f /var/log/nginx/access.log

再次请求：

1
curl http://localhost:8088/api/hello

可以观察：

• 请求方法和 URI；
• Nginx 返回状态码；
• 总请求时间；
• upstream 地址；
• upstream 状态码；
• upstream 响应时间。

这体现了入口层集中日志的价值。

8.18 停止与清理#

1
docker compose down --remove-orphans

如需同时删除本实验构建的镜像：

1
docker compose down --rmi local --remove-orphans

9.1 请求 /#

1
curl localhost:8088/
2
    ↓
3
宿主机 8088 映射至 Nginx 容器 80
4
    ↓
5
命中 server { listen 80; }
6
    ↓
7
命中 location /
8
    ↓
9
Nginx 从 /usr/share/nginx/html 读取 index.html
10
    ↓
11
Nginx 直接返回文件

Spring Boot 完全不参与。

9.2 请求 /api/hello#

1
curl localhost:8088/api/hello
2
    ↓
3
Client 与 Nginx 建立连接
4
    ↓
5
Nginx 匹配 location /api/
6
    ↓
7
Nginx 解析 Docker DNS 名称 backend
8
    ↓
9
Nginx 与 backend:8080 建立另一条连接
10
    ↓
11
Spring Boot 返回 JSON 给 Nginx
12
    ↓
13
Nginx 添加 X-Entry-Proxy 响应头
14
    ↓
15
Nginx 返回响应给 Client

9.3 两条连接的状态对照#

这一张表是理解后续代理配置的基础。

10.1 第一阶段：最小可运行#

能力：

• 静态文件；
• 单后端代理；
• 基础访问日志；
• 固定 Nginx 镜像版本。

缺失：

• HTTPS；
• 多实例；
• 健康检查；
• 限流；
• 缓存；
• 安全加固；
• 日志采集；
• 监控和告警；
• Nginx 自身高可用。

10.2 第二阶段：统一入口#

增加：

• 正式域名；
• 默认拒绝未知 Host；
• TLS 证书；
• 安全响应头；
• 请求体大小；
• 统一错误页；
• 真实 IP 信任边界。

10.3 第三阶段：后端多实例#

增加：

• upstream；
• 负载均衡算法；
• upstream keepalive；
• 被动故障判断；
• 安全的重试边界；
• 应用幂等机制。

10.4 第四阶段：性能与保护#

增加：

• 静态资源缓存；
• gzip/Brotli 评估；
• proxy cache；
• 请求限流；
• 连接限制；
• 超时分层；
• 大文件和流式接口策略。

10.5 第五阶段：可观测与发布#

增加：

• JSON 结构化日志；
• Request ID / Trace ID；
• Nginx 指标；
• upstream 延迟监控；
• 4xx/5xx 告警；
• 配置版本管理；
• 自动 nginx -t；
• 灰度、回滚和变更审计。

10.6 第六阶段：入口高可用#

单个 Nginx 容器或虚拟机仍然是单点。可选方案包括：

• 云负载均衡器 + 多个 Nginx；
• Keepalived + 双节点虚拟 IP；
• Kubernetes Deployment + Service/Gateway；
• DNS 多记录配合外部健康检查；
• 托管 API Gateway 或边缘平台。

生产架构不能只考虑“后端有几个实例”，还要考虑“入口本身是否可用”。

11.1 错误一：认为用了 Nginx 就自动高可用#

11.2 错误二：把 Nginx 当成业务服务替代品#

11.3 错误三：认为反向代理只是“透明转发同一条连接”#

11.4 错误四：直接信任客户端传入的 X-Forwarded-For#

11.5 错误五：所有流量都经过应用服务#

11.6 错误六：为了“层次完整”同时部署太多网关#

11.7 错误七：修改配置后只看文件，不检查实际加载结果#

1
nginx -t
2
nginx -T
3
ps -ef | grep nginx
4
curl -v http://target

12.1 标准排查路径#

12.2 第一步：确认客户端到入口#

1
curl -v http://localhost:8088/nginx-health

关注：

• DNS 解析结果；
• 连接的 IP 和端口；
• TCP 是否成功；
• HTTP 状态码；
• 响应头是否能证明请求经过目标入口。

12.3 第二步：确认 Nginx 正在运行#

1
docker compose ps
2
docker compose logs nginx

非容器环境：

1
ps -ef | grep nginx
2
ss -lntp | grep nginx

12.4 第三步：确认实际配置#

1
docker compose exec nginx nginx -t
2
docker compose exec nginx nginx -T

不要只根据编辑器中的文件判断。

12.5 第四步：确认 Nginx 能访问后端#

进入 Nginx 容器：

1
docker compose exec nginx sh

Alpine 镜像可能没有 curl，可使用 wget：

1
wget -qO- http://backend:8080/api/hello

如果容器内可以访问，而从外部通过 Nginx 不行，重点检查 Nginx 路由与代理配置；如果容器内也不能访问，重点检查 Docker DNS、网络、端口和应用状态。

12.6 第五步：区分 Nginx 状态码与后端状态码#

访问日志中建议同时记录：

• $status：Nginx 最终返回客户端的状态；
• $upstream_status：上游返回状态，可能包含多次尝试；
• $request_time：入口观察到的总时间；
• $upstream_response_time：上游响应时间。

例如：

• $status=502、$upstream_status=-：可能根本没连上后端；
• $status=500、$upstream_status=500：后端明确返回 500；
• $status=504：常见于等待 upstream 超时；
• $status=404、$upstream_status=-：可能由 Nginx 本地路由或文件查找产生；
• $status=404、$upstream_status=404：后端返回 404。

13.1 什么规模下 Nginx 足够#

下面的系统通常可以从 Nginx 开始：

• 单体应用或少量服务；
• 固定域名和路径路由；
• 简单 TLS 和静态资源；
• 少量后端实例；
• 团队能够维护 Linux 和配置文件；
• 不需要复杂 API 生命周期平台。

13.2 什么时候需要 CDN#

• 大量静态资源；
• 用户分布跨地区；
• 源站带宽压力大；
• 希望边缘缓存和 DDoS/WAF 能力；
• 下载、图片、视频等内容分发占比高。

13.3 什么时候需要云负载均衡器#

• Nginx 节点不止一台；
• 需要托管公网 IP；
• 需要多可用区高可用；
• 不希望自己维护 Keepalived 和公网故障切换；
• 需要与云证书、安全组、监控体系集成。

13.4 什么时候需要 API Gateway#

• 多租户与消费者管理；
• OAuth/JWT/API Key 集中认证；
• 复杂配额与计费；
• 动态服务发现；
• 插件化协议转换；
• 开发者门户和 API 生命周期治理；
• 路由规则频繁由平台动态下发。

13.5 什么情况下 Nginx 不应承担该职责#

• 复杂订单状态机；
• 领域事务；
• 细粒度数据权限；
• 用户画像和实时风控决策；
• 需要数据库事务的业务编排；
• 大量可测试、可演进的业务代码。

这些逻辑应留在应用或专门的业务网关中。

13.6 Nginx 的核心价值总结#

Nginx 的价值不是“多加一层”，而是建立清晰边界：

1
公网与内部服务之间的边界
2
静态内容与动态业务之间的边界
3
通用流量治理与领域逻辑之间的边界
4
客户端连接与应用连接之间的边界
5
单一稳定入口与内部可变拓扑之间的边界

15.1 核心问题#

15.2 场景分析题#

15.3 配置排错题#

内容完整性#

• 说明 Nginx 在后端架构中的位置；
• 说明直接暴露应用端口的限制；
• 区分正向代理和反向代理；
• 讲解 Web Server、静态资源、反向代理、负载均衡、TLS、缓存和流量治理职责；
• 讲解 Master/Worker 与事件驱动模型；
• 明确客户端连接与 upstream 连接不是同一条连接；
• 对比 Nginx、API Gateway、CDN、云 LB、Kubernetes Gateway 和 Service Mesh；
• 提供完整 Docker Compose + Spring Boot 实验；
• 提供故障排查流程；
• 提供面试题、场景题和配置排错题。

技术准确性#

• 核验 2026-07-06 Nginx 官方稳定版与主线版；
• 固定 Docker 镜像版本，不使用 latest；
• 没有把 NGINX Plus 主动健康检查写成开源版默认能力；
• 没有把 Ingress、Ingress Controller 与 Nginx 混为一谈；
• 说明 Kubernetes Ingress API 已冻结并推荐 Gateway；
• 没有把 CORS、WAF 或入口代理当成业务鉴权替代品；
• 说明单个 Nginx 仍然是单点。

配置可运行性#

• 给出完整目录结构；
• 给出 Compose、Nginx、Maven、Java 和 Dockerfile；
• 给出启动、检查、验证、日志和清理命令；
• 给出 nginx -t 和 nginx -T；
• 说明预期响应和网络表现。