Nginx 使用指南Nginx发音 “engine-x”是一个高性能的 HTTP 和反向代理服务器以其高并发、低内存消耗和稳定性著称。它最初为解决 C10K 问题而设计采用事件驱动的异步架构能够处理大量并发连接。Nginx 主要用作 Web 服务器、反向代理、负载均衡器和 HTTP 缓存。一、安装与基本管理1.1 在 Ubuntu/Debian 上安装sudoaptupdatesudoaptinstallnginx1.2 在 CentOS/RHEL 上安装sudoyuminstallepel-releasesudoyuminstallnginx# 较新版本使用 dnfsudodnfinstallnginx1.3 在 macOS 上安装使用 Homebrewbrewinstallnginx1.4 在 Windows 上安装访问 nginx.org下载 Stable version 稳定版 Windows 压缩包将压缩包解压到不含中文或空格的目录如D:\nginx双击nginx.exe运行通过任务管理器确认nginx.exe进程存在即表示启动成功1.5 服务管理命令systemd# 启动 Nginxsudosystemctl start nginx# 停止 Nginxsudosystemctl stop nginx# 重启 Nginxsudosystemctl restart nginx# 重新加载配置不中断服务推荐sudosystemctl reload nginx# 查看运行状态sudosystemctl status nginx# 设置开机自启sudosystemctlenablenginx二、核心概念2.1 配置文件结构Nginx 的主配置文件通常位于Linux:/etc/nginx/nginx.confmacOS:/usr/local/etc/nginx/nginx.confWindows:{解压目录}/conf/nginx.conf典型的目录结构Debian/Ubuntu 风格/etc/nginx/ ├── nginx.conf # 主配置文件 ├── conf.d/ # 额外配置文件目录 ├── sites-available/ # 可用站点配置文件 └── sites-enabled/ # 已启用站点配置文件软链接2.2 基本配置示例# 全局设置main 上下文 user nginx; worker_processes auto; error_log /var/log/nginx/error.log; pid /run/nginx.pid; # 事件模块配置 events { worker_connections 1024; use epoll; multi_accept on; } # HTTP 模块配置核心部分 http { include /etc/nginx/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 $http_x_forwarded_for; access_log /var/log/nginx/access.log main; # 性能优化参数 sendfile on; tcp_nopush on; tcp_nodelay on; keepalive_timeout 65; types_hash_max_size 2048; # 模块化配置引入 include /etc/nginx/conf.d/*.conf; include /etc/nginx/sites-enabled/*; # 虚拟主机配置server 块 server { listen 80; server_name localhost; root /usr/share/nginx/html; index index.html index.htm; location / { try_files $uri $uri/ 404; } } }2.3 核心上下文上下文说明main全局配置如 worker 进程数、用户、错误日志等events事件驱动相关配置如连接数、I/O 模型等httpHTTP 协议相关配置包含所有 Web 服务指令server虚拟主机配置定义域名、端口和网站根目录locationURL 路由规则匹配特定路径并配置相应处理方式upstream后端服务器组定义用于负载均衡2.4 配置加载顺序Nginx 加载主配置文件nginx.conf处理http块中的include指令按文件名顺序加载加载conf.d/*.conf和sites-enabled/*中的所有配置如果同一指令在多个文件中出现以最后加载的为准server块按listen端口和server_name优先级匹配请求三、Web 服务器基础配置3.1 最简单的静态网站server { listen 80; server_name example.com www.example.com; root /var/www/example; index index.html index.htm; location / { try_files $uri $uri/ 404; } }3.2 处理不同文件类型server { listen 80; server_name example.com; root /var/www/example; # 默认首页 index index.html index.php; # 处理 PHP 请求通过 FastCGI 转发 location ~ \.php$ { include fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } # 图片缓存设置 location ~* \.(jpg|jpeg|png|gif|ico|svg)$ { expires 30d; add_header Cache-Control public, immutable; } # CSS/JS 缓存 location ~* \.(css|js)$ { expires 7d; add_header Cache-Control public, immutable; } }3.3 重写规则server { listen 80; server_name example.com; # 强制 HTTPS 重定向 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name example.com; # URL 重写永久重定向 rewrite ^/old-page$ /new-page permanent; # 条件重写仅对特定 User-Agent if ($http_user_agent ~* bot|crawler|spider) { rewrite ^ /bot-handler last; } # 路径重写隐藏真实路径 location /api/ { rewrite ^/api/(.*)$ /api/v2/$1 break; proxy_pass http://backend_server; } }四、反向代理配置4.1 基本反向代理反向代理是 Nginx 最常见的用途它将客户端请求转发给后端服务器然后将响应返回给客户端。这种方式可以隐藏后端服务器的真实 IP 和端口同时实现负载均衡和请求缓冲。server { listen 80; server_name app.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 连接超时设置 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } }4.2 代理 WebSocketWebSocket 协议与普通 HTTP 不同需要额外配置以支持持久连接。Nginx 1.3.13 以上版本对 WebSocket 有原生支持location /ws/ { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 长连接保持 proxy_connect_timeout 3600s; proxy_send_timeout 3600s; proxy_read_timeout 3600s; }4.3 代理多个后端负载均衡upstream backend_servers { # 负载均衡算法默认轮询 server 127.0.0.1:3000 weight3; # 权重 3 server 127.0.0.1:3001 weight1; server 127.0.0.1:3002 backup; # 备用服务器 # 启用健康检查 keepalive 32; } server { listen 80; server_name api.example.com; location / { proxy_pass http://backend_servers; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_http_version 1.1; proxy_set_header Connection ; } }4.4 负载均衡算法算法配置指令说明轮询默认按顺序轮流分配权重轮询weightn按权重比例分配最少连接least_conn;分配给活跃连接数最少的服务器IP 哈希ip_hash;根据客户端 IP 哈希分配保证同一 IP 固定到同一台服务器随机random;随机选择可配合two指令优化upstream example { # 使用 IP 哈希适合会话保持场景 ip_hash; server 127.0.0.1:3000; server 127.0.0.1:3001; } upstream example2 { # 最少连接 权重 least_conn; server 127.0.0.1:3000 weight2; server 127.0.0.1:3001 weight1; }4.5 服务器健康检查upstream backend { server 127.0.0.1:3000 max_fails3 fail_timeout30s; server 127.0.0.1:3001 max_fails2 fail_timeout20s; server 127.0.0.1:3002 down; # 标记为下线 } # 主动健康检查需要 nginx-plus 或第三方模块 location /health { proxy_pass http://backend; health_check interval5s fails3 passes2 uri/health; }五、HTTPS 与 SSL/TLS 配置5.1 生成 SSL 证书自签名# 生成私钥openssl genrsa-outserver.key2048# 生成证书签名请求openssl req-new-keyserver.key-outserver.csr# 生成自签名证书有效期 365 天openssl x509-req-days365-inserver.csr-signkeyserver.key-outserver.crt5.2 基本 HTTPS 配置server { listen 443 ssl http2; server_name example.com; # SSL 证书配置 ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; # SSL 协议和安全配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers on; # HSTS强制 HTTPS add_header Strict-Transport-Security max-age31536000; includeSubDomains always; root /var/www/example; }5.3 HTTP 自动跳转 HTTPSserver { listen 80; server_name example.com www.example.com; return 301 https://$server_name$request_uri; } # 或使用更复杂的写法 server { listen 80; server_name example.com; # 对所有请求返回 301 永久重定向 rewrite ^(.*)$ https://$host$1 permanent; }5.4 完整的安全配置server { listen 443 ssl http2; server_name example.com; # SSL 证书 ssl_certificate /etc/nginx/ssl/example.com.crt; ssl_certificate_key /etc/nginx/ssl/example.com.key; # 强制使用 TLS 1.2 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_prefer_server_ciphers on; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 安全头部 add_header X-Frame-Options SAMEORIGIN always; add_header X-XSS-Protection 1; modeblock always; add_header X-Content-Type-Options nosniff always; add_header Referrer-Policy strict-origin-when-cross-origin always; # HSTS add_header Strict-Transport-Security max-age31536000; includeSubDomains; preload always; root /var/www/example; }六、性能优化6.1 worker 进程配置# 自动匹配 CPU 核心数 worker_processes auto; # 每个 worker 的连接数根据系统资源调整 events { worker_connections 10240; use epoll; multi_accept on; }6.2 静态文件缓存location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { root /var/www/example; expires 30d; add_header Cache-Control public, immutable; # 启用 gzip 压缩 gzip on; gzip_types text/plain text/css application/javascript; # 打开文件缓存 open_file_cache max1000 inactive20s; open_file_cache_valid 30s; open_file_cache_min_uses 2; open_file_cache_errors on; }6.3 Gzip 压缩http { gzip on; gzip_vary on; gzip_proxied any; gzip_comp_level 6; gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xmlrss application/atomxml image/svgxml; gzip_disable msie6; gzip_min_length 1024; # 小于 1KB 的文件不压缩 gzip_buffers 16 8k; }6.4 缓冲区调优http { # 客户端请求缓冲区 client_body_buffer_size 128k; client_max_body_size 10M; # 代理缓冲区 proxy_buffer_size 4k; proxy_buffers 32 4k; proxy_busy_buffers_size 64k; # FastCGI 缓冲区 fastcgi_buffer_size 4k; fastcgi_buffers 32 4k; fastcgi_busy_buffers_size 64k; }6.5 连接超时优化http { # 保持连接超时 keepalive_timeout 65; keepalive_requests 100; # 客户端超时 client_header_timeout 10; client_body_timeout 10; # 代理超时 proxy_connect_timeout 60; proxy_send_timeout 60; proxy_read_timeout 60; # 发送超时 send_timeout 60; }6.6 限流配置http { # 定义限流区域 limit_req_zone $binary_remote_addr zoneperip:10m rate10r/s; limit_conn_zone $binary_remote_addr zoneaddr:10m; server { location /api/ { # 每个 IP 每秒最多 10 个请求 limit_req zoneperip burst20 nodelay; # 每个 IP 最多 10 个并发连接 limit_conn addr 10; proxy_pass http://backend; } } }七、日志管理7.1 日志格式定义http { # 标准日志格式 log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for; # JSON 格式日志便于 ELK 等日志系统分析 log_format json escapejson { time_local:$time_local, remote_addr:$remote_addr, request:$request, status:$status, body_bytes_sent:$body_bytes_sent, http_referer:$http_referer, http_user_agent:$http_user_agent }; access_log /var/log/nginx/access.log main; access_log /var/log/nginx/access.json.log json; error_log /var/log/nginx/error.log warn; }7.2 按站点分离日志server { server_name example.com; access_log /var/log/nginx/example.com.access.log main; error_log /var/log/nginx/example.com.error.log; # 特定路径不记录日志 location /health { access_log off; return 200 OK; } }7.3 日志轮转logrotate创建/etc/logrotate.d/nginx配置文件/var/log/nginx/*.log { daily missingok rotate 52 compress delaycompress notifempty create 640 nginx adm sharedscripts postrotate [ -f /var/run/nginx.pid ] kill -USR1 cat /var/run/nginx.pid endscript }手动执行轮转sudologrotate-vf/etc/logrotate.d/nginx八、安全配置8.1 隐藏 Nginx 版本http { # 隐藏版本号防止信息泄露 server_tokens off; } # 或仅对特定 server 隐藏 server { server_tokens off; }8.2 限制访问server { # 限制 IP 访问 location /admin/ { allow 192.168.1.0/24; allow 10.0.0.1; deny all; proxy_pass http://backend; } # 密码保护 location /private/ { auth_basic Restricted Area; auth_basic_user_file /etc/nginx/.htpasswd; # 创建密码文件htpasswd -c /etc/nginx/.htpasswd username } }8.3 防止常见攻击server { # 防止目录遍历 location ~ /\. { deny all; } # 防止 SQL 注入通过 User-Agent 过滤 if ($http_user_agent ~* (sqlmap|nmap|nikto) ) { return 444; } # 防止跨站脚本 add_header X-XSS-Protection 1; modeblock; # 防止 MIME 类型嗅探 add_header X-Content-Type-Options nosniff; }8.4 限制请求方法server { # 只允许 GET 和 POST 方法 if ($request_method !~ ^(GET|POST)$) { return 405; } # 更精确的控制 location /api/ { limit_except GET { allow 192.168.1.0/24; deny all; } proxy_pass http://backend; } }九、常见场景配置9.1 前后端分离SPAserver { listen 80; server_name app.example.com; root /var/www/spa/dist; # SPA 路由处理所有请求返回 index.html location / { try_files $uri $uri/ /index.html; } # API 代理 location /api/ { proxy_pass http://backend_server:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }9.2 同一端口配置多个站点基于域名server { listen 80; server_name site1.com www.site1.com; root /var/www/site1; } server { listen 80; server_name site2.com www.site2.com; root /var/www/site2; }9.3 同一域名配置多个站点基于路径server { listen 80; server_name example.com; location /app1/ { alias /var/www/app1/; index index.html; } location /app2/ { alias /var/www/app2/; index index.html; } }9.4 静态资源 CDN 加速server { listen 80; server_name static.example.com; root /var/www/static; # 设置缓存头 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|webp)$ { expires max; add_header Cache-Control public, immutable; add_header Access-Control-Allow-Origin *; } }9.5 代理 PHP-FPMserver { listen 80; server_name example.com; root /var/www/example; index index.php; location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.1-fpm.sock; # 或使用 TCPfastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; } }9.6 代理 Node.js 应用server { listen 80; server_name node.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; # 添加超时配置 proxy_connect_timeout 120s; proxy_send_timeout 120s; proxy_read_timeout 120s; } }9.7 代理 Python 应用Gunicorn/uWSGI# Gunicorn location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # uWSGI location / { include uwsgi_params; uwsgi_pass 127.0.0.1:3031; }十、调试与故障排查10.1 测试配置文件# 测试配置文件语法在修改配置后使用推荐sudonginx-t# 显示配置文件路径sudonginx-T# 测试后如果显示 syntax is ok 和 test is successful 表示配置正确10.2 查看错误日志# 实时查看错误日志sudotail-f/var/log/nginx/error.log# 查看最近 100 行错误sudotail-100/var/log/nginx/error.log# 查找特定错误greperror/var/log/nginx/error.log10.3 调试模式运行# 前台运行输出详细日志sudonginx-gdaemon off; error_log /dev/stderr debug;# 以调试模式运行需要编译时启用 debugsudonginx-gdebug_connection 192.168.1.1;10.4 查看访问日志# 实时查看访问日志sudotail-f/var/log/nginx/access.log# 按 IP 统计访问量sudocat/var/log/nginx/access.log|awk{print $1}|sort|uniq-c|sort-nr# 统计状态码分布sudocat/var/log/nginx/access.log|awk{print $9}|sort|uniq-c|sort-nr10.5 常用诊断命令# 检查 Nginx 是否运行psaux|grepnginx# 检查端口是否监听sudonetstat-tlnp|grepnginx# 查看进程 PIDcat/run/nginx.pid# 平滑重启sudokill-HUP$(cat/run/nginx.pid)# 优雅停止sudokill-QUIT$(cat/run/nginx.pid)# 强制停止sudokill-TERM$(cat/run/nginx.pid)十一、高可用与集群11.1 Nginx Keepalived 高可用# 安装 Keepalivedsudoaptinstallkeepalived# 配置 /etc/keepalived/keepalived.confvrrp_script check_nginx{script/etc/keepalived/check_nginx.shinterval2weight2}vrrp_instance VI_1{state MASTER# BACKUP 节点为 BACKUPinterface eth0 virtual_router_id51priority100# BACKUP 节点为 90advert_int1authentication{auth_type PASS auth_pass1111}virtual_ipaddress{192.168.1.100/24# 虚拟 IP}track_script{check_nginx}}11.2 健康检查脚本#!/bin/bash# /etc/keepalived/check_nginx.shif[-f/var/run/nginx.pid];thenexit0elseexit1fi11.3 多级代理架构客户端 → Nginx负载均衡器→ Nginx应用服务器→ 后端服务# 第一层负载均衡器 upstream app_servers { server 192.168.1.10:80; server 192.168.1.11:80; server 192.168.1.12:80; } server { listen 80; location / { proxy_pass http://app_servers; } } # 第二层应用服务器 server { listen 80; location / { proxy_pass http://127.0.0.1:3000; } }十二、与 Docker 配合使用12.1 使用官方镜像# 拉取官方镜像dockerpull nginx:alpine# 运行容器dockerrun--namemy-nginx-p80:80-dnginx12.2 自定义配置# 使用自定义配置dockerrun--namemy-nginx\-v/path/to/nginx.conf:/etc/nginx/nginx.conf:ro\-v/path/to/html:/usr/share/nginx/html:ro\-p80:80-dnginx12.3 Docker Compose 示例version:3.8services:nginx:image:nginx:alpinecontainer_name:nginx-proxyports:-80:80-443:443volumes:-./nginx.conf:/etc/nginx/nginx.conf:ro-./conf.d:/etc/nginx/conf.d:ro-./ssl:/etc/nginx/ssl:ro-./html:/usr/share/nginx/html:ro-./logs:/var/log/nginxdepends_on:-appapp:build:.container_name:app-serverexpose:-3000十三、常用变量速查变量说明$remote_addr客户端 IP 地址$remote_user客户端认证用户名$time_local本地时间$request完整请求行方法 URI 协议$request_uri完整请求 URI含参数$uri当前请求 URI不含参数$args请求参数$status响应状态码$body_bytes_sent响应体字节数$http_refererReferer 头$http_user_agentUser-Agent 头$http_x_forwarded_forX-Forwarded-For 头$host请求的域名$server_name服务器名称$server_port服务器端口$scheme请求协议http/https$request_method请求方法GET/POST 等$content_typeContent-Type 头$content_lengthContent-Length 头$document_root网站的根目录路径$document_uri同$uri$query_string同$args$cookie_name指定名称的 Cookie 值十四、常见问题与解决问题解决方法502 Bad Gateway检查后端服务是否运行检查防火墙是否允许端口504 Gateway Timeout增加proxy_read_timeout检查后端响应速度413 Request Entity Too Large增加client_max_body_size403 Forbidden检查目录权限检查index指令是否正确404 Not Found检查root路径是否正确检查文件是否存在无法加载静态资源检查location规则是否正确检查文件路径权限端口被占用使用sudo netstat -tlnp查看占用更换端口HTTPS 证书错误检查证书路径和有效期使用 Let’s Encrypt 更新日志文件过大配置 logrotate设置日志切割策略Nginx 无法启动使用nginx -t测试配置检查错误日志内存占用过高减少worker_connections调整缓冲区大小缓存不生效检查 Cache-Control 头设置检查文件修改时间十五、快速参考常用命令速查# 启动sudosystemctl start nginx# 停止sudosystemctl stop nginx# 重启sudosystemctl restart nginx# 重载配置平滑sudosystemctl reload nginx# 测试配置sudonginx-t# 查看状态sudosystemctl status nginx# 启用开机自启sudosystemctlenablenginx# 查看版本nginx-vnginx-V# 显示编译参数常用配置文件目录系统主配置文件站点配置Debian/Ubuntu/etc/nginx/nginx.conf/etc/nginx/sites-enabled/CentOS/RHEL/etc/nginx/nginx.conf/etc/nginx/conf.d/macOS (Homebrew)/usr/local/etc/nginx/nginx.conf/usr/local/etc/nginx/servers/Windows{解压目录}/conf/nginx.conf{解压目录}/conf/conf.d/端口说明端口用途80HTTP默认443HTTPSSSL/TLS8080备用 HTTP8443备用 HTTPS十六、资源与参考官方文档: https://nginx.org/en/docs/中文文档: https://nginx.org/zh/配置示例: https://github.com/nginx/nginx/tree/master/confNginx 可视化配置生成器: https://nginxconfig.io/Let’s Encrypt 免费 SSL: https://letsencrypt.org/zh-cn/Nginx 性能调优指南: https://www.nginx.com/blog/tuning-nginx/十七、配置模板基础静态站点模板server { listen 80; server_name example.com; root /var/www/example; index index.html index.htm; # Gzip 压缩 gzip on; gzip_types text/plain text/css text/xml text/javascript application/javascript; # 缓存静态资源 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 30d; add_header Cache-Control public, immutable; } location / { try_files $uri $uri/ 404; } # 错误页面 error_page 404 /404.html; error_page 500 502 503 504 /50x.html; location /50x.html { root /usr/share/nginx/html; } }反向代理模板upstream backend { server 127.0.0.1:3000 weight2; server 127.0.0.1:3001 weight1; keepalive 32; } server { listen 80; server_name api.example.com; access_log /var/log/nginx/api.access.log main; error_log /var/log/nginx/api.error.log; location / { proxy_pass http://backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Connection ; # 超时设置 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; # 缓冲设置 proxy_buffering on; proxy_buffer_size 4k; proxy_buffers 8 4k; proxy_busy_buffers_size 8k; } # 健康检查端点 location /health { access_log off; return 200 OK; } }结语Nginx 是一个功能强大且灵活的服务器软件掌握其核心配置可以应对绝大多数 Web 服务场景。建议从基础配置开始逐步深入反向代理、负载均衡和性能优化。在生产环境中务必使用nginx -t测试配置并优先使用reload而非restart来更新配置。更多高级功能如 Lua 脚本扩展、流媒体代理、动态模块加载等可以参考官方文档进一步学习。祝使用愉快