# Nginx 专家 ## 何时使用 * 创建或检查 nginx 配置文件 * 设置反向代理或负载均衡器 * 配置 SSL/TLS 和 HTTPS * 实施速率限制或访问控制 * 优化性能（缓存、gzip、keepalive） * WebSocket代理 * 提供静态内容 * 调试 nginx 问题（502、504、连接错误） **超出范围**（推荐专用技能）： * Docker容器化->docker专家 * Kubernetes 入口控制器 -> kubernetes 专家 * 应用级代码->相关框架技能 ## 核心原则 1. **安全第一** \-- 仅 TLS 1.2+、强密码、无服务器令牌、速率限制 2. **最小暴露** \--只暴露需要的内容，隐藏上游细节 3. **性能** \-- 利用缓存、gzip、keepalive 连接、sendfile 4. **清晰度** \-- 组织良好的配置，带有注释、逻辑服务器/位置块 ## 配置文件结构主要（全局） ├── events { } -- 连接处理 ├── http { } -- HTTP 服务器配置 │ ├──上游{ } -- 后端服务器组 │ ├── 服务器 { } -- 虚拟主机 │ │ ├── location { } -- 请求路由 │ │ └── 地点 { } │ └── 服务器 { } └── Stream { } -- TCP/UDP 代理 **关键规则：** * 简单指令以分号 (`;`) 结尾 * 块指令使用大括号 (`{` `}`) * 指令继承自父上下文，除非被覆盖 * 注释以“#”开头 * 默认配置路径：`/etc/nginx/nginx.conf` ## 流程管理 nginx -t # 测试配置语法 nginx -s reload # 优雅地重新加载（重新读取配置） nginx -s quit # 优雅关闭 nginx -s stop #快速关闭 nginx -sreopen#重新打开日志文件 ## 位置匹配优先级顺序（从高到低）：修改器|类型 |示例 ---|---|--- `=` |精确匹配 | `位置= /` `^~` |前缀（跳过正则表达式）| `位置^~ /图像/` `~` |正则表达式（区分大小写）| `位置 ~ \.php$` `~*` |正则表达式（不区分大小写）| `位置 ~* \.(jpg|png)$` （无）|前缀| `位置/文档/` **算法：** 检查所有前缀位置（记住最长） -> 如果最长有 `^~`，则使用它 -> 按配置顺序检查正则表达式（第一个匹配获胜） -> 回退到最长前缀。 ## 提供静态内容服务器{ 听80；服务器名称 example.com；根/var/www/html；地点/{ try_files $uri $uri //index.html; } 位置 ~* \.(js|css|png|jpg|gif|ico|svg|woff2?)$ { 1 年到期； add_header Cache-Control“公共，不可变”； } } ### 根与别名 # root: 将 URI 附加到路径位置/图像/ { 根/数据； # /images/photo.jpg -> /data/images/photo.jpg } # 别名：替换匹配的位置位置/图像/ { 别名/数据/照片/； # /images/photo.jpg -> /data/photos/photo.jpg } ## 反向代理服务器{ 听80；服务器名称 example.com；地点/{ proxy_pass http://localhost:3000; proxy_set_header 主机 $host; proxy_set_header X-真实IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for； proxy_set_header X-Forwarded-Proto $scheme; } } ### proxy_pass URI 行为 # 带尾部斜杠 -- 去除位置前缀位置/api/ { proxy_pass http://backend/; # /api/用户 -> /用户 } # 不带尾部斜杠 -- 传递完整的 URI 位置/api/ { proxy_pass http://backend; # /api/用户 -> /api/用户 } 完整代理和上游参考：[references/proxy-upstream.md]() ## 负载均衡 # 循环（默认）上游后端{ 服务器 backend1.example.com；服务器 backend2.example.com； } # 加权上游后端{ 服务器 backend1.example.com 权重=5；服务器 backend2.example.com 权重=1； } # 最少连接数上游后端{ 最少连接；服务器 backend1.example.com；服务器 backend2.example.com； } # IP 哈希（会话持久性）上游后端{ ip_哈希；服务器 backend1.example.com；服务器 backend2.example.com； } ### 服务器参数 * `weight=N` \-- 服务器权重（默认1） * `max_fails=N` \-- 标记为不可用之前失败（默认 1） * `fail_timeout=T` \-- 失败窗口和不可用持续时间（默认 10 秒） * `max_conns=N` \-- 最大同时连接数（默认 0 = 无限制） * `backup` \-- 仅当主服务器全部关闭时使用 * `down` \--永久标记为不可用 ### 上游保持活动上游后端{ 服务器 backend1.example.com；保持活动 32； } 服务器{ 地点/{ proxy_pass http://backend; proxy_http_版本 1.1； proxy_set_header 连接“”； } } 完整代理和上游参考：[references/proxy-upstream.md]() ## SSL/TLS 服务器{ 监听 443 ssl；服务器名称 example.com； ssl_certificate /etc/nginx/ssl/example.com.crt; ssl_certificate_key /etc/nginx/ssl/example.com.key; ssl_协议 TLSv1.2 TLSv1.3； ssl_session_cache 共享：SSL：10m； ssl_session_timeout 10m； } # HTTP 到 HTTPS 重定向服务器{ 听80；服务器名称 example.com；返回 301 https://$host$request_uri; } 完整的 SSL/TLS 参考（OCSP、SNI、证书链、强化）：[references/ssl-tls.md]() ## 速率限制 http{ limit_req_zone $binary_remote_addr zone=api:10m 速率=10r/s; 服务器{ 位置/api/ { limit_req zone=apiburst=20nodelay; 限制请求状态429； proxy_pass http://backend; } } } * `rate=Nr/s` 或 `rate=Nr/m` \-- 每秒/分钟的请求数（漏桶） * `burst=N` \--允许N个多余的请求排队 * `nodelay` \--进程立即爆发，无延迟 * `$binary_remote_addr` \-- 优于 `$remote_addr` （4/16 字节 vs 字符串）完整的安全参考：[references/security.md]() ## Gzip 压缩 http{ gzip 打开； gzip_comp_level 5； gzip_min_length 256； gzip_vary 开启； gzip_proxied 任何； gzip_types 文本/纯文本/css 文本/javascript 应用程序/javascript 应用程序/json 应用程序/xml 图像/svg+xml; } `text/html` 总是被压缩的——不要将它列在 `gzip_types` 中。 ## WebSocket 代理 http{ 映射 $http_upgrade $connection_upgrade { 默认升级； '' 关闭; } 服务器{ 位置 /ws/ { proxy_pass http://websocket_backend; proxy_http_版本 1.1； proxy_set_header 升级 $http_upgrade; proxy_set_header 连接 $connection_upgrade; proxy_read_timeout 3600s； proxy_send_timeout 3600s； } } } 默认 `proxy_read_timeout` 是 60 秒——空闲的 WebSocket 连接将被关闭。增加超时或使用后端 ping 帧。 ## 日志记录 http{ log_format main '$remote_addr - $remote_user [$time_local] ' '“$request”$status $body_bytes_sent' '“$http_referer”“$http_user_agent”' '$request_time $upstream_response_time'; access_log /var/log/nginx/access.log main; error_log /var/log/nginx/error.log 警告；服务器{ 位置/健康状况{ 访问_注销；返回 200“确定”； } } } ## 性能调优自动worker_processes；事件{ 工人连接1024；多重接受； } http{ 发送文件； tcp_nopush 开启； tcp_nodelay 开启； keepalive_timeout 65s； keepalive_requests 1000； open_file_cache max=1000 inactive=20s; open_file_cache_valid 30s； open_file_cache_min_uses 2；打开文件缓存错误； } 完整的缓存和性能参考：[references/caching-performance.md]() ## 生产清单 * `nginx -t` 通过 * `server_tokens 关闭` * 仅支持 TLSv1.2+ 的 SSL/TLS * HTTP 到 HTTPS 重定向 * 启用 HSTS 标头 * 安全标头（X-Frame-Options、CSP、X-Content-Type-Options） * 敏感端点的速率限制 * 适当设置`client_max_body_size` * 启用 Gzip 压缩 * 带有“expires”的静态资源缓存 * 日志记录配置为轮换 * 隐藏文件被阻止 (`location ~ /\. { 拒绝所有; }`) * 使用 `proxy_http_version 1.1` 保持上游保持活动状态 * `worker_processes auto`, `sendfile on`, `tcp_nopush on` ## 反模式不要|而是做 ---|--- 使用“if”进行复杂路由 |使用 `map` \+ 变量或多个 `location` 块将 `server_tokens` 保留为 | `server_tokens 关闭；` 允许 TLSv1.0/1.1 | `ssl_协议 TLSv1.2 TLSv1.3;` 使用不带“Host”标头的“proxy_pass” |设置 `proxy_set_header 主机 $host;` 使用 keepalive 跳过 `proxy_http_version` | `proxy_http_version 1.1;` 并清除连接标头在配置中硬编码 IP |将“upstream”块与命名服务器一起使用忽略长请求的“proxy_read_timeout” |根据预期响应时间调整每个位置在“if”块中使用“root” |将“root”放在“server”或“location”上下文中 ## 诊断 ### 502 网关错误 * 后端已关闭或未监听 * 检查 `proxy_pass` URL 和后端连接 ### 504 网关超时 * 后端太慢 -- 增加 `proxy_read_timeout` ### 413 请求实体太大 * 增加`client_max_body_size` ### 配置错误 * 始终在重新加载之前进行测试：`nginx -t` * 检查错误日志： `tail -f /var/log/nginx/error.log` ## 关键变量变量|描述 ---|--- `$host` |主机标头或服务器名称 `$remote_addr` |客户端IP地址 `$binary_remote_addr` |二进制形式的客户端 IP（用于限制区域） `$proxy_add_x_forwarded_for` | X-Forwarded-For + 客户端 IP `$方案` | `http` 或 `https` `$request_uri` |带有查询字符串的完整原始 URI `$uri` |标准化 URI（无查询字符串） `$args` |查询字符串 `$upstream_response_time` |上游响应时间 `$upstream_cache_status` |缓存命中/未命中状态 ## 参考索引主题 |文件 ---|--- 代理模块、上游、负载平衡、超时、缓冲、保活 | [references/proxy-upstream.md]() SSL/TLS、HTTPS、证书、OCSP、SNI、HTTP/2、HTTP/3 | [references/ssl-tls.md]() 安全标头、速率限制、访问控制、客户端限制 | [references/security.md]() 代理缓存、gzip、性能调优、打开文件缓存 | [references/caching-performance.md]() 完整的配置模式：API 网关、SPA、微服务、日志记录 | [references/common-patterns.md]()

nginx

包含技能