1
--conf-path=/etc/nginx/nginx.conf

1
/etc/nginx/
2
├── nginx.conf
3
├── mime.types
4
├── conf.d/
5
│   ├── api.conf
6
│   ├── static.conf
7
│   └── default.conf
8
├── snippets/
9
│   ├── proxy-common.conf
10
│   └── security-headers.conf
11
├── sites-available/
12
└── sites-enabled/

1
http {
2
    include /etc/nginx/mime.types;
3
    include /etc/nginx/conf.d/*.conf;
4
}

1
http {
2
    include /etc/nginx/conf.d/*.conf;
3
}

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

1
http {
2
    server {
3
        listen 80;
4
        server_name api.example.com;
5
    }
6
}

1
server {
2
    include /etc/nginx/http-level.conf;
3
}

1
map $http_upgrade $connection_upgrade {
2
    default upgrade;
3
    '' close;
4
}

1
"map" directive is not allowed here

1
user nginx;
2
worker_processes auto;
3
pid /var/run/nginx.pid;
4
error_log /var/log/nginx/error.log warn;

1
main {
2
    worker_processes auto;
3
}

1
events {
2
    worker_connections 1024;
3
}

1
http {
2
    include mime.types;
3
    default_type application/octet-stream;
4
    sendfile on;
5

6
    server {
7
        listen 80;
8
    }
9
}

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

5
    location /api/ {
6
        proxy_pass http://backend;
7
    }
8
}

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

1
http {
2
    upstream backend {
3
        server app:8080;
4
    }
5

6
    map $http_upgrade $connection_upgrade {
7
        default upgrade;
8
        '' close;
9
    }
10

11
    log_format main '$remote_addr $request $status';
12
}

1
server {
2
    upstream backend {
3
        server app:8080;
4
    }
5
}

1
“我在 http 里写过，所以所有 location 一定都有。”

1
http {
2
    root /srv/default;
3

4
    server {
5
        root /srv/site;
6

7
        location /images/ {
8
            # 未配置 root 时，通常使用 server 层 root
9
        }
10

11
        location /downloads/ {
12
            root /srv/files;
13
        }
14
    }
15
}

1
server {
2
    listen 10.0.0.8:80;
3
    server_name api.example.com;
4
}
5

6
server {
7
    listen 10.0.0.9:80;
8
    server_name api.example.com;
9
}
10

11
server {
12
    listen 10.0.0.8:8080;
13
    server_name api.example.com;
14
}

1
先筛选监听地址与端口
2
→ 再在候选 server 中匹配主机名

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

6
server {
7
    listen 80;
8
    server_name static.example.com;
9
}

1
GET / HTTP/1.1
2
Host: api.example.com

1
GET / HTTP/1.1
2
Host: static.example.com

1
server_name api.example.com;
2
server_name *.example.com;
3
server_name mail.*;
4
server_name ~^(?<tenant>.+)\.tenant\.example\.net$;

1
server {
2
    listen 80 default_server;
3
    server_name _;
4
    return 404;
5
}

1
listen 80 default_server;

1
server_name _;

1
server {
2
    listen 80 default_server;
3
    server_name "";
4
    return 444;
5
}

1
https://api.example.com/images/logo.png?v=2

1
/images/logo.png

1
https://api.example.com/images/logo.png?v=2

1
location = /health {
2
    return 200 'ok';
3
}

1
/health/
2
/health/check
3
/Health

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

1
/api/users
2
/api/orders/1
3
/api/

1
location / {
2
    return 200 'root';
3
}
4

5
location /api/ {
6
    return 200 'api';
7
}
8

9
location /api/admin/ {
10
    return 200 'admin';
11
}

1
location ^~ /assets/ {
2
    root /srv/www;
3
}

1
location @backend_fallback {
2
    proxy_pass http://backend;
3
}

1
location / {
2
    try_files $uri $uri/ @backend_fallback;
3
}

1
location = / {
2
    return 200 'exact-root';
3
}
4

5
location / {
6
    return 200 'prefix-root';
7
}
8

9
location /documents/ {
10
    return 200 'documents';
11
}
12

13
location ^~ /images/ {
14
    return 200 'images-prefix';
15
}
16

17
location ~* \.(gif|jpg|jpeg|png)$ {
18
    return 200 'image-regex';
19
}
20

21
location ~ ^/documents/private/ {
22
    return 200 'private-regex';
23
}

1
/api
2
/api/

1
location /api { ... }
2
location /api/ { ... }

1
/apix
2
/api-v2

1
location = /api {
2
    return 308 /api/;
3
}
4

5
location /api/ {
6
    proxy_pass http://backend;
7
}

1
/api/users?id=42

1
$request_uri = /api/users?id=42

1
$uri = /api/users

1
/api/users?id=42&sort=name

1
$args = id=42&sort=name
2
$arg_id = 42
3
$arg_sort = name

1
location /assets/ {
2
    root /srv/www;
3
}

1
/assets/logo.png

1
/srv/www/assets/logo.png

1
root 值 + 当前 URI

1
location /assets/ {
2
    alias /srv/static/;
3
}

1
/assets/logo.png

1
/srv/static/logo.png

1
用 alias 目录替换匹配到的 location 前缀

1
location /downloads/ {
2
    alias /srv/files/;
3
}

1
location /downloads/ {
2
    alias /srv/files;
3
}

1
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
2
    alias /data/w3/images/$1;
3
}

1
add_header X-Debug-Uri $uri always;
2
add_header X-Debug-Document-Root $document_root always;
3
add_header X-Debug-Request-Filename $request_filename always;

1
location /docs/ {
2
    root /srv/www;
3
    index index.html;
4
}

1
/docs/

1
/docs/index.html

1
location ~ \.html$ {
2
    add_header X-HTML yes;
3
}

1
location / {
2
    try_files $uri $uri/ /index.html;
3
}

1
location / {
2
    root /usr/share/nginx/html;
3
    try_files $uri $uri/ /index.html;
4
}

1
/usr/share/nginx/html/dashboard/users

1
location / {
2
    try_files $uri $uri/ /index.html;
3
}

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

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

1
location / {
2
    try_files $uri /index.html;
3
}
4

5
location = /index.html {
6
    try_files $uri /index.html;
7
}

1
rewrite or internal redirection cycle

1
location = /old-page {
2
    return 308 /new-page;
3
}

1
rewrite ^/old-page$ /new-page permanent;

1
location /download/ {
2
    rewrite ^/download/(.*)$ /download/$1 last;
3
}

1
if ($request_method = POST) {
2
    return 405;
3
}

1
set $backend_name default;

1
map $http_upgrade $connection_upgrade {
2
    default upgrade;
3
    ''      close;
4
}

1
map $uri $loggable {
2
    default 1;
3
    /health 0;
4
}

1
access_log /var/log/nginx/access.log main if=$loggable;

1
proxy_pass http://backend;

1
proxy_pass http://$backend;

1
curl
2
  → 宿主机 127.0.0.1:8088
3
  → Nginx 容器 8080
4
  → 根据 Host 选择 server
5
  → 根据 URI 选择 location
6
  → 静态文件 / return / Spring Boot

1
nginx-config-matching-lab/
2
├── docker-compose.yml
3
├── nginx/
4
│   ├── nginx.conf
5
│   ├── conf.d/
6
│   │   ├── 00-default.conf
7
│   │   ├── 10-api.conf
8
│   │   └── 20-static.conf
9
│   └── html/
10
│       ├── index.html
11
│       ├── app/
12
│       │   └── index.html
13
│       ├── assets/
14
│       │   └── logo.txt
15
│       └── public-files/
16
│           └── manual.txt
17
└── backend/
18
    ├── Dockerfile
19
    ├── pom.xml
20
    └── src/main/java/com/example/demo/
21
        ├── DemoApplication.java
22
        └── DebugController.java

1
services:
2
  backend:
3
    build:
4
      context: ./backend
5
    expose:
6
      - "8080"
7
    environment:
8
      INSTANCE_ID: backend-a
9
    networks:
10
      - lab-net
11

12
  nginx:
13
    image: nginx:1.30.3-alpine
14
    depends_on:
15
      - backend
16
    ports:
17
      - "8088:8080"
18
    volumes:
19
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
20
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
21
      - ./nginx/html:/srv/www:ro
22
    networks:
23
      - lab-net
24

25
networks:
26
  lab-net:
27
    driver: bridge

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 matching
16
        '$remote_addr host=$host http_host=$http_host '
17
        'server=$server_name request="$request" '
18
        'uri=$uri request_uri=$request_uri status=$status';
19

20
    access_log /var/log/nginx/access.log matching;
21

22
    sendfile on;
23
    keepalive_timeout 65s;
24

25
    map $uri $is_health {
26
        default 0;
27
        /health 1;
28
    }
29

30
    include /etc/nginx/conf.d/*.conf;
31
}

1
server {
2
    listen 8080 default_server;
3
    server_name "";
4

5
    add_header X-Debug-Server default always;
6

7
    location / {
8
        return 404 "unknown host\n";
9
    }
10
}

1
server {
2
    listen 8080;
3
    server_name api.local.test;
4

5
    add_header X-Debug-Server api always;
6

7
    location = / {
8
        return 200 "api exact root\n";
9
    }
10

11
    location = /health {
12
        add_header X-Is-Health $is_health always;
13
        return 200 "ok\n";
14
    }
15

16
    location = /debug/server {
17
        default_type text/plain;
18
        return 200 "server_name=$server_name\nhost=$host\nhttp_host=$http_host\nrequest_uri=$request_uri\nuri=$uri\nargs=$args\n";
19
    }
20

21
    location ^~ /api/static/ {
22
        return 200 "api static prefix\n";
23
    }
24

25
    location /api/ {
26
        proxy_set_header Host $host;
27
        proxy_set_header X-Original-URI $request_uri;
28
        proxy_set_header X-Nginx-URI $uri;
29
        proxy_pass http://backend:8080;
30
    }
31

32
    location ~* \.(jpg|jpeg|png)$ {
33
        return 200 "api image regex\n";
34
    }
35

36
    location /legacy/ {
37
        rewrite ^/legacy/(.*)$ /api/echo/$1 last;
38
    }
39
}

1
server {
2
    listen 8080;
3
    server_name static.local.test;
4

5
    root /srv/www;
6
    add_header X-Debug-Server static always;
7

8
    location = / {
9
        try_files /index.html =404;
10
    }
11

12
    location ^~ /assets/ {
13
        try_files $uri =404;
14
    }
15

16
    location ^~ /downloads/ {
17
        alias /srv/www/public-files/;
18
    }
19

20
    location /app/ {
21
        try_files $uri $uri/ /app/index.html;
22
    }
23

24
    location ~* \.(txt)$ {
25
        add_header X-Debug-Location txt-regex always;
26
        try_files $uri =404;
27
    }
28

29
    location /fallback/ {
30
        try_files $uri @backend_fallback;
31
    }
32

33
    location @backend_fallback {
34
        proxy_set_header Host $host;
35
        proxy_set_header X-Original-URI $request_uri;
36
        proxy_set_header X-Nginx-URI $uri;
37
        proxy_pass http://backend:8080;
38
    }
39
}

1
<!doctype html>
2
<html lang="zh-CN">
3
<head>
4
  <meta charset="UTF-8">
5
  <title>Nginx Config Matching Lab</title>
6
</head>
7
<body>
8
  <h1>static.local.test</h1>
9
</body>
10
</html>

1
<!doctype html>
2
<html lang="zh-CN">
3
<head>
4
  <meta charset="UTF-8">
5
  <title>SPA Fallback</title>
6
</head>
7
<body>
8
  <h1>SPA index fallback</h1>
9
</body>
10
</html>

1
asset from root mapping

1
manual from alias mapping

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
5
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
6
    <modelVersion>4.0.0</modelVersion>
7

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

15
    <groupId>com.example</groupId>
16
    <artifactId>nginx-matching-demo</artifactId>
17
    <version>1.0.0</version>
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>

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
    public static void main(String[] args) {
9
        SpringApplication.run(DemoApplication.class, args);
10
    }
11
}

1
package com.example.demo;
2

3
import jakarta.servlet.http.HttpServletRequest;
4
import org.springframework.beans.factory.annotation.Value;
5
import org.springframework.http.MediaType;
6
import org.springframework.web.bind.annotation.GetMapping;
7
import org.springframework.web.bind.annotation.PathVariable;
8
import org.springframework.web.bind.annotation.RequestMapping;
9
import org.springframework.web.bind.annotation.RestController;
10

11
import java.util.LinkedHashMap;
12
import java.util.Map;
13

14
@RestController
15
@RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE)
16
public class DebugController {
17

18
    @Value("${INSTANCE_ID:local}")
19
    private String instanceId;
20

21
    @GetMapping("/api/echo/{value}")
22
    public Map<String, Object> echo(
23
            @PathVariable String value,
24
            HttpServletRequest request) {
25

26
        Map<String, Object> result = new LinkedHashMap<>();
27
        result.put("instanceId", instanceId);
28
        result.put("value", value);
29
        result.put("requestUri", request.getRequestURI());
30
        result.put("queryString", request.getQueryString());
31
        result.put("host", request.getHeader("Host"));
32
        result.put("xOriginalUri", request.getHeader("X-Original-URI"));
33
        result.put("xNginxUri", request.getHeader("X-Nginx-URI"));
34
        return result;
35
    }
36

37
    @GetMapping("/fallback/**")
38
    public Map<String, Object> fallback(HttpServletRequest request) {
39
        Map<String, Object> result = new LinkedHashMap<>();
40
        result.put("instanceId", instanceId);
41
        result.put("fallback", true);
42
        result.put("requestUri", request.getRequestURI());
43
        result.put("xOriginalUri", request.getHeader("X-Original-URI"));
44
        result.put("xNginxUri", request.getHeader("X-Nginx-URI"));
45
        return result;
46
    }
47
}

1
FROM maven:3.9.11-eclipse-temurin-21-alpine AS builder
2
WORKDIR /workspace
3
COPY pom.xml .
4
RUN mvn -q -DskipTests dependency:go-offline
5
COPY src ./src
6
RUN mvn -q -DskipTests package
7

8
FROM eclipse-temurin:21-jre-alpine
9
WORKDIR /app
10
COPY --from=builder /workspace/target/*.jar app.jar
11
EXPOSE 8080
12
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

1
HTTP/1.1 404 Not Found
2
X-Debug-Server: default
3

4
unknown host

1
location = /

1
api exact root

1
server_name=api.local.test
2
host=api.local.test
3
http_host=api.local.test:8088
4
request_uri=/debug/server?id=42
5
uri=/debug/server
6
args=id=42

1
location ^~ /api/static/

1
api static prefix