xfy
972eab4267
将 docs/ 根目录下的 nginx 相关文档统一移动到 docs/nginx/ 子目录， 提高文档组织性和可维护性。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
434 lines
8.9 KiB
Markdown
434 lines
8.9 KiB
Markdown
# NGINX HTTP 核心模块指南
|
||
|
||
## 1. 核心配置结构
|
||
|
||
### http 上下文
|
||
|
||
```nginx
|
||
http {
|
||
# HTTP 服务全局配置
|
||
include 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"';
|
||
|
||
server {
|
||
# 虚拟服务器配置
|
||
}
|
||
}
|
||
```
|
||
|
||
### server 虚拟服务器
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name example.com www.example.com;
|
||
|
||
location / {
|
||
root /var/www/html;
|
||
index index.html index.htm;
|
||
}
|
||
}
|
||
```
|
||
|
||
### location 请求路由
|
||
|
||
**语法**：`location [ = | ~ | ~* | ^~ ] uri { ... }`
|
||
|
||
| 修饰符 | 说明 |
|
||
|--------|------|
|
||
| `=` | 精确匹配，必须完全匹配 URI |
|
||
| `^~` | 前缀匹配，成功后不再检查正则 |
|
||
| `~` | 正则匹配（区分大小写） |
|
||
| `~*` | 正则匹配（不区分大小写） |
|
||
| `@` | 命名 location，用于内部重定向 |
|
||
|
||
**匹配优先级**：
|
||
1. 精确匹配 (`=`)
|
||
2. 前缀匹配 (`^~`) - 不再检查正则
|
||
3. 正则匹配 (按配置文件顺序)
|
||
4. 普通前缀匹配 (最长匹配优先)
|
||
|
||
```nginx
|
||
location = /exact {
|
||
# 精确匹配 /exact
|
||
}
|
||
|
||
location ^~ /images/ {
|
||
# 前缀匹配，优先于正则
|
||
}
|
||
|
||
location ~ \.php$ {
|
||
# 正则匹配 .php 文件（区分大小写）
|
||
}
|
||
|
||
location ~* \.(gif|jpg|png)$ {
|
||
# 正则匹配图片（不区分大小写）
|
||
}
|
||
|
||
location / {
|
||
# 普通前缀匹配，作为默认
|
||
}
|
||
|
||
location @fallback {
|
||
# 命名 location，用于内部重定向
|
||
proxy_pass http://backend;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 监听与服务器名称
|
||
|
||
### listen 指令
|
||
|
||
**语法**：`listen address[:port] [parameters];`
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
listen 443 ssl;
|
||
listen [::]:80; # IPv6
|
||
listen unix:/var/run/nginx.sock; # Unix Socket
|
||
listen 80 default_server; # 默认服务器
|
||
listen 443 ssl http2; # SSL + HTTP/2
|
||
}
|
||
```
|
||
|
||
**常用参数**：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `default_server` | 设置为默认服务器 |
|
||
| `ssl` | 启用 SSL |
|
||
| `http2` | 启用 HTTP/2 |
|
||
| `http3` | 启用 HTTP/3 (QUIC) |
|
||
| `quic` | 启用 QUIC 协议 |
|
||
| `reuseport` | 每个 worker 独立监听 |
|
||
| `proxy_protocol` | 启用 PROXY 协议 |
|
||
| `backlog=N` | 连接队列长度 |
|
||
| `rcvbuf=N` | 接收缓冲区大小 |
|
||
| `sndbuf=N` | 发送缓冲区大小 |
|
||
|
||
### server_name 指令
|
||
|
||
```nginx
|
||
server {
|
||
server_name example.com; # 精确名称
|
||
server_name www.example.com; # 多个精确名称
|
||
server_name *.example.com; # 通配符前缀
|
||
server_name example.*; # 通配符后缀
|
||
server_name ~^(www\.)?(.+)$; # 正则表达式
|
||
server_name .example.com; # 匹配 example.com 和 *.example.com
|
||
server_name ""; # 匹配空 Host 头（默认）
|
||
server_name _; # catch-all（无效域名）
|
||
}
|
||
```
|
||
|
||
**匹配优先级**：
|
||
1. 精确名称
|
||
2. 最长的以 `*` 开头的通配符
|
||
3. 最长的以 `*` 结尾的通配符
|
||
4. 第一个匹配的正则表达式（按配置顺序）
|
||
|
||
---
|
||
|
||
## 3. 请求处理流程
|
||
|
||
### 服务器选择流程
|
||
|
||
1. 根据 IP 地址和端口匹配 `listen` 指令
|
||
2. 在匹配的 server 块中测试 `Host` 头是否匹配 `server_name`
|
||
3. 如果未找到匹配的服务器名称，使用该 IP:Port 的默认服务器
|
||
|
||
### Location 选择流程
|
||
|
||
1. 首先搜索最具体的字面字符串前缀位置
|
||
2. 按配置文件顺序检查正则表达式位置
|
||
3. 第一个匹配的正则表达式停止搜索并被使用
|
||
4. 如果没有正则匹配，使用之前找到的最具体前缀位置
|
||
|
||
**注意**：所有类型的 location 仅测试请求行中的 URI 部分，不包含查询参数。
|
||
|
||
---
|
||
|
||
## 4. 文件服务指令
|
||
|
||
### root 指令
|
||
|
||
设置请求的根目录，路径构造为 `root 值 + URI`。
|
||
|
||
```nginx
|
||
location /i/ {
|
||
root /data/w3;
|
||
# 请求 /i/top.gif -> /data/w3/i/top.gif
|
||
}
|
||
```
|
||
|
||
### alias 指令
|
||
|
||
替换指定 location 的路径。
|
||
|
||
```nginx
|
||
location /i/ {
|
||
alias /data/w3/images/;
|
||
# 请求 /i/top.gif -> /data/w3/images/top.gif
|
||
}
|
||
```
|
||
|
||
**root 与 alias 区别**：
|
||
|
||
```nginx
|
||
# root：URI 附加到路径后
|
||
location /images/ {
|
||
root /data; # /images/logo.png -> /data/images/logo.png
|
||
}
|
||
|
||
# alias：URI 替换 location 部分
|
||
location /images/ {
|
||
alias /data/photos/; # /images/logo.png -> /data/photos/logo.png
|
||
}
|
||
```
|
||
|
||
### index 指令
|
||
|
||
定义索引文件。
|
||
|
||
```nginx
|
||
location / {
|
||
index index.html index.htm index.php;
|
||
}
|
||
```
|
||
|
||
### try_files 指令
|
||
|
||
按顺序检查文件是否存在。
|
||
|
||
```nginx
|
||
location / {
|
||
try_files $uri $uri/ /index.html =404;
|
||
# 1. 尝试 $uri（精确文件）
|
||
# 2. 尝试 $uri/（目录）
|
||
# 3. 尔回 /index.html（内部重定向）
|
||
# 4. 最后返回 404
|
||
}
|
||
|
||
# 配合命名 location
|
||
location / {
|
||
try_files $uri $uri/ @fallback;
|
||
}
|
||
|
||
location @fallback {
|
||
proxy_pass http://backend;
|
||
}
|
||
```
|
||
|
||
### error_page 指令
|
||
|
||
定义错误页面。
|
||
|
||
```nginx
|
||
error_page 404 /404.html;
|
||
error_page 500 502 503 504 /50x.html;
|
||
error_page 404 =200 /empty.gif; # 修改响应码为 200
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 客户端请求控制
|
||
|
||
### client_max_body_size
|
||
|
||
设置请求体最大允许大小。
|
||
|
||
```nginx
|
||
client_max_body_size 10m; # 默认 1m
|
||
client_max_body_size 0; # 禁用检查（不限制）
|
||
```
|
||
|
||
### client_body_timeout / client_header_timeout
|
||
|
||
读取请求体/头部超时。
|
||
|
||
```nginx
|
||
client_body_timeout 60s; # 默认 60s
|
||
client_header_timeout 60s; # 默认 60s
|
||
```
|
||
|
||
### keepalive_timeout
|
||
|
||
设置长连接超时时间。
|
||
|
||
```nginx
|
||
keepalive_timeout 75s; # 默认 75s
|
||
keepalive_timeout 75s 70s; # 第二个参数设置响应头 Keep-Alive
|
||
```
|
||
|
||
### keepalive_requests
|
||
|
||
单个长连接最大请求数。
|
||
|
||
```nginx
|
||
keepalive_requests 1000; # 默认 1000
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 性能优化指令
|
||
|
||
### sendfile
|
||
|
||
启用高效的文件传输。
|
||
|
||
```nginx
|
||
sendfile on; # 默认 off
|
||
```
|
||
|
||
### tcp_nopush / tcp_nodelay
|
||
|
||
```nginx
|
||
tcp_nopush on; # sendfile 时优化（发送完整数据包）
|
||
tcp_nodelay on; # 减少网络延迟（不等待完整数据包）
|
||
```
|
||
|
||
### aio
|
||
|
||
启用异步文件 I/O。
|
||
|
||
```nginx
|
||
location /video/ {
|
||
sendfile on;
|
||
aio threads; # 使用线程池
|
||
directio 8m; # 大于 8MB 的文件使用直接 I/O
|
||
}
|
||
```
|
||
|
||
### open_file_cache
|
||
|
||
缓存打开的文件描述符。
|
||
|
||
```nginx
|
||
open_file_cache max=1000 inactive=20s;
|
||
open_file_cache_valid 30s;
|
||
open_file_cache_min_uses 2;
|
||
open_file_cache_errors on;
|
||
```
|
||
|
||
### server_tokens
|
||
|
||
隐藏版本信息。
|
||
|
||
```nginx
|
||
server_tokens off; # 错误页和响应头不显示版本
|
||
```
|
||
|
||
---
|
||
|
||
## 7. MIME 类型配置
|
||
|
||
### types 指令
|
||
|
||
映射文件扩展名到 MIME 类型。
|
||
|
||
```nginx
|
||
types {
|
||
text/html html htm shtml;
|
||
text/css css;
|
||
text/xml xml;
|
||
image/gif gif;
|
||
image/jpeg jpeg jpg;
|
||
application/javascript js;
|
||
application/json json;
|
||
}
|
||
```
|
||
|
||
### default_type
|
||
|
||
设置默认 MIME 类型。
|
||
|
||
```nginx
|
||
default_type application/octet-stream;
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 内部请求控制
|
||
|
||
### internal
|
||
|
||
指定 location 仅用于内部请求。
|
||
|
||
```nginx
|
||
location /internal/ {
|
||
internal; # 外部请求返回 404
|
||
proxy_pass http://backend;
|
||
}
|
||
|
||
# 内部请求触发方式：
|
||
# 1. error_page 重定向
|
||
# 2. try_files 最后一个参数
|
||
# 3. rewrite ... last 重定向到命名 location
|
||
# 4. X-Accel-Redirect 响应头
|
||
```
|
||
|
||
### limit_rate
|
||
|
||
限制响应传输速率。
|
||
|
||
```nginx
|
||
limit_rate 100k; # 限制为 100KB/s
|
||
limit_rate_after 1m; # 传输 1MB 后开始限速
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 常用嵌入式变量
|
||
|
||
| 变量名 | 说明 |
|
||
|--------|------|
|
||
| `$arg_name` | 请求行中的参数 name |
|
||
| `$args` | 请求行中的所有参数 |
|
||
| `$host` | 请求行中的主机名或 Host 头 |
|
||
| `$http_name` | 任意请求头字段（小写，下划线） |
|
||
| `$remote_addr` | 客户端 IP 地址 |
|
||
| `$remote_port` | 客户端端口 |
|
||
| `$remote_user` | 基础认证用户名 |
|
||
| `$request` | 完整原始请求行 |
|
||
| `$request_body` | 请求体内容 |
|
||
| `$request_filename` | 当前请求的文件路径 |
|
||
| `$request_method` | 请求方法（GET, POST 等） |
|
||
| `$request_uri` | 完整原始请求 URI（含参数） |
|
||
| `$scheme` | 请求协议（http/https） |
|
||
| `$server_addr` | 服务器 IP 地址 |
|
||
| `$server_name` | 服务器名称 |
|
||
| `$server_port` | 服务器端口 |
|
||
| `$status` | 响应状态码 |
|
||
| `$uri` | 当前请求中的 URI（规范化后） |
|
||
| `$document_root` | root 指令的值 |
|
||
| `$document_uri` | 同 $uri |
|
||
| `$query_string` | 同 $args |
|
||
|
||
### 示例
|
||
|
||
```nginx
|
||
# 获取查询参数
|
||
location /search {
|
||
set $q $arg_q; # ?q=value 中的 value
|
||
proxy_pass http://backend/search?q=$q;
|
||
}
|
||
|
||
# 获取请求头
|
||
location /api {
|
||
proxy_set_header X-Auth $http_x_auth;
|
||
proxy_pass http://backend;
|
||
}
|
||
|
||
# 获取客户端 IP
|
||
location /ip {
|
||
return 200 "Your IP: $remote_addr";
|
||
}
|
||
``` |