# Nginx企业级全套配置\+排错手册

Nginx企业级全套配置+排错手册

说明：本文档整合Nginx企业生产全场景配置、日志切割脚本、高频报错排错方案，适配Nginx 1.18~1.24主流版本，可直接保存离线查阅，修改对应参数即可一键部署上线。

第一部分：Nginx完整生产配置（nginx.conf）
第二部分：日志自动切割脚本（生产必装）
第三部分：上线修改指南（快速适配自身业务）
第四部分：高频报错排错速查表
第五部分：常用运维命令（离线备查）

第一部分：Nginx完整生产配置（nginx.conf）

整合全部企业场景：反向代理、跨域CORS、负载均衡、HTTPS、动静分离、限流、黑白名单、WebSocket、日志规范、大文件上传、防盗链、Gzip、安全加固、URL重写、缓存、等保合规。

nginx 复制代码

# 运行用户
user nginx;
# 进程数 一般等于CPU核心数
worker_processes auto;
# 错误日志
error_log /usr/local/nginx/logs/error.log warn;
pid /usr/local/nginx/logs/nginx.pid;

# 事件模块
events {
    worker_connections 10240;   # 单进程最大连接数
    use epoll;                  # 高效IO模型
    multi_accept on;
}

# 核心HTTP全局配置
http {
    include       mime.types;
    default_type  application/octet-stream;

    # ========== 基础安全配置 ==========
    server_tokens off;                     # 隐藏Nginx版本号
    charset utf-8;                         # 全局编码
    add_header X-Frame-Options SAMEORIGIN always;       # 防iframe嵌套
    add_header X-XSS-Protection "1; mode=block" always; # XSS防护
    add_header X-Content-Type-Options nosniff always;   # MIME类型防护

    # ========== 文件上传/请求限制 ==========
    client_max_body_size 500M;     # 全局最大上传
    client_body_buffer_size 10M;
    client_header_timeout 15s;
    client_body_timeout 60s;
    send_timeout 60s;

    # ========== Gzip压缩 性能优化 ==========
    gzip on;
    gzip_min_length 1k;
    gzip_buffers 4 16k;
    gzip_http_version 1.1;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/javascript application/json 
               application/javascript application/xml image/svg+xml;
    gzip_vary on;

    # ========== 限流防刷 全局规则 ==========
    # 单IP 20次/秒 限制
    limit_req_zone $binary_remote_addr zone=api_limit:20m rate=20r/s;
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    # ========== 长连接/缓存基础 ==========
    keepalive_timeout 65;
    keepalive_requests 100;

    # ========== 日志格式 ==========
    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 /usr/local/nginx/logs/access.log main;

    # ========== 后端集群负载均衡 ==========
    upstream backend_cluster {
        server 192.168.1.10:8080 weight=5 max_fails=3 fail_timeout=30s;
        server 192.168.1.11:8080 weight=3 max_fails=3 fail_timeout=30s;
        server 192.168.1.12:8080 backup;  # 备用节点
    }

    # WebSocket专用upstream
    upstream ws_cluster {
        server 192.168.1.10:8888;
    }

    # =============================================
    # 下面为各个业务站点Server，按需启用/注释
    # =============================================

    # 1、HTTP 强制跳转 HTTPS
    server {
        listen 80;
        server_name xxx.com www.xxx.com api.xxx.com;
        return 301 https://$host$request_uri;
    }

    # 2、全站HTTPS 主站配置（前端+动静分离+接口代理）
    server {
        listen 443 ssl;
        server_name xxx.com www.xxx.com;

        # SSL证书配置
        ssl_certificate /usr/local/nginx/ssl/xxx.pem;
        ssl_certificate_key /usr/local/nginx/ssl/xxx.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4;
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL:10m;
        ssl_session_timeout 10m;
        add_header Strict-Transport-Security "max-age=31536000;includeSubDomains" always;

        # 网站根目录
        root /data/www/xxx_web;
        index index.html;

        # ---------- 动静分离：静态资源缓存 ----------
        location ~* \.(jpg|png|gif|jpeg|ico|svg|js|css|woff|ttf|mp4)$ {
            expires 30d;
            add_header Cache-Control "public,max-age=2592000";
            access_log off;
            add_header Accept-Ranges bytes always; # 断点续传
        }

        # ---------- 资源防盗链 ----------
        location ~* \.(jpg|png|gif|mp4)$ {
            valid_referers none blocked xxx.com www.xxx.com *.xxx.com;
            if ($invalid_referer) {
                return 403;
            }
        }

        # ---------- 后端API反向代理 ----------
        location /api/ {
            limit_req zone=api_limit burst=5 nodelay; # 接口限流
            proxy_pass http://backend_cluster;
            proxy_redirect off;

            # 透传客户端真实信息
            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 30s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
            proxy_buffer_size 128k;
            proxy_buffers 4 128k;
        }

        # ---------- Vue/React History路由模式 ----------
        location / {
            try_files $uri $uri/ /index.html;
        }
    }

    # 3、HTTPS 跨域CORS 接口专属站点
    server {
        listen 443 ssl;
        server_name api.xxx.com;
        ssl_certificate /usr/local/nginx/ssl/xxx.pem;
        ssl_certificate_key /usr/local/nginx/ssl/xxx.key;

        location / {
            # 企业级CORS跨域配置（支持Token+Cookie）
            add_header Access-Control-Allow-Origin https://www.xxx.com always;
            add_header Access-Control-Allow-Credentials true always;
            add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS always;
            add_header Access-Control-Allow-Headers Content-Type,Authorization,X-Requested-With always;
            add_header Access-Control-Max-Age 86400 always;

            # 处理OPTIONS预检请求
            if ($request_method = OPTIONS) {
                add_header Content-Length 0;
                add_header Content-Type text/plain;
                return 204;
            }

            proxy_pass http://backend_cluster;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }

    # 4、WebSocket 长连接配置（WSS）
    server {
        listen 443 ssl;
        server_name ws.xxx.com;
        ssl_certificate /usr/local/nginx/ssl/xxx.pem;
        ssl_certificate_key /usr/local/nginx/ssl/xxx.key;

        location /ws/ {
            proxy_pass http://ws_cluster;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            # WebSocket协议升级
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;

            # 长连接超时
            proxy_connect_timeout 300s;
            proxy_send_timeout 300s;
            proxy_read_timeout 300s;

            proxy_set_header X-Real-IP $remote_addr;
        }
    }

    # 5、内部文件服务（目录浏览+限速+内网白名单）
    server {
        listen 8090;
        server_name 127.0.0.1;
        charset utf-8;
        root /data/file;

        autoindex on;
        autoindex_exact_size off;
        autoindex_localtime on;
        limit_rate 500k;

        # 禁止执行脚本
        location ~* \.(php|jsp|asp|sh|py|exe)$ {
            deny all;
        }

        # 内网白名单
        allow 192.168.0.0/16;
        allow 127.0.0.1;
        deny all;
    }

    # 6、后台管理系统 IP白名单防护
    server {
        listen 443 ssl;
        server_name admin.xxx.com;
        ssl_certificate /usr/local/nginx/ssl/xxx.pem;
        ssl_certificate_key /usr/local/nginx/ssl/xxx.key;

        location / {
            allow 192.168.1.0/24;
            allow 办公出口IP;
            deny all;
            proxy_pass http://127.0.0.1:8080;
        }
    }

}

第二部分：日志自动切割脚本（生产必装）

功能：按天自动切割access/error日志，自动压缩7天前日志，删除30天前日志，不重启Nginx，平滑切换日志写入。

1. 日志切割脚本（nginx_log_cut.sh）

bash 复制代码

#!/bin/bash
# 日志目录（请确认与nginx.conf中日志路径一致）
LOG_DIR="/usr/local/nginx/logs"
# 日期后缀（取前一天日期）
DATE=$(date -d yesterday +%Y-%m-%d)

# 1. 重命名日志文件（切割）
mv ${LOG_DIR}/access.log ${LOG_DIR}/access_${DATE}.log
mv ${LOG_DIR}/error.log ${LOG_DIR}/error_${DATE}.log

# 2. 平滑重读Nginx配置，生成新的空日志文件（不中断业务）
/usr/local/nginx/sbin/nginx -s reopen

# 3. 压缩7天前的日志（节省磁盘空间），删除30天前的日志（清理过期日志）
find ${LOG_DIR} -name "access_*.log" -mtime +7 -exec gzip {} \;
find ${LOG_DIR} -name "error_*.log" -mtime +7 -exec gzip {} \;
find ${LOG_DIR} -name "*.log*.gz" -mtime +30 -delete

2. 定时任务配置（每日自动执行）

bash 复制代码

# 1. 给脚本授权（可执行权限）
chmod +x /usr/local/nginx/sbin/nginx_log_cut.sh

# 2. 编辑定时任务
crontab -e

# 3. 添加以下内容（每日凌晨0点1分执行切割脚本）
1 0 * * * /bin/bash /usr/local/nginx/sbin/nginx_log_cut.sh

第三部分：上线修改指南（快速适配自身业务）

无需修改全部配置，仅修改以下6处，即可部署上线：

server_name：替换为自身业务域名（如www.xxx.com、api.xxx.com）；
ssl_certificate / ssl_certificate_key：修改为SSL证书的绝对路径（确保路径正确，证书文件未损坏）；
upstream 集群：将backend_cluster、ws_cluster内的IP:端口，改为自身后端服务的真实地址；
root路径：将主站server内的root /data/www/xxx_web，改为前端打包文件的实际目录；
跨域配置：将Access-Control-Allow-Origin的值，改为前端真实域名（如https://www.xxx.com）；
IP白名单：将admin.xxx.com站点内的allow规则，改为自身办公/内网IP段。

第四部分：高频报错排错速查表

覆盖企业生产中最常见的报错，对照报错信息，直接查找根因和解决方案，秒级修复。

一、HTTP状态码类错误

1. 403 Forbidden（禁止访问）

常见根因：

目录/文件权限不足，Nginx运行用户（nginx）无读权限；
IP黑白名单配置错误，被deny all拦截；
防盗链规则拦截（invalid_referer）；
root路径配置错误，目录不存在；
开启autoindex但目录无访问权限。

解决方案：

bash 复制代码

# 1. 修复文件/目录权限（最常用）
chown -R nginx:nginx /data/www
chmod -R 755 /data/www

# 2. 检查IP白名单，注释错误的deny all，或修正allow规则
# 3. 临时关闭防盗链测试（注释valid_referer相关配置）

2. 404 Not Found（页面/接口不存在）

常见根因：

root/alias路径配置错误，文件/目录不存在；
Vue/React history模式缺少try_files配置；
proxy_pass转发地址错误，后端接口路径不对；
静态资源路径缺失、文件名大小写不匹配。

核心解决方案：

nginx 复制代码

# 前端Vue/React history模式必加（解决刷新404）
location / {
    try_files $uri $uri/ /index.html;
}

# 检查proxy_pass路径，确保后端接口地址正确
location /api/ {
    proxy_pass http://backend_cluster; # 确认backend_cluster内IP/端口正确
}

3. 413 Request Entity Too Large（请求体过大）

根因：上传文件/请求体大小，超过Nginx默认限制（默认较小）。

解决方案（全局+局部双重配置，避免遗漏）：

nginx 复制代码

http {
    client_max_body_size 500M; # 全局最大限制，可根据需求调整（如100M、1G）
}

# 上传接口单独配置（可选，优先级高于全局）
location /upload {
    client_max_body_size 500M;
}

4. 502 Bad Gateway（网关错误）

常见根因：

后端服务宕机、端口未启动；
proxy_pass配置的后端IP/端口错误；
后端进程卡死、端口监听异常；
防火墙/安全组拦截内网端口（如后端8080端口）。

排查&修复步骤：

bash 复制代码

# 1. 测试后端服务是否可达
curl http://127.0.0.1:8080/api # 替换为自身后端IP和接口路径

# 2. 查看后端端口是否正常监听
ss -lntp | grep 8080 # 替换为后端端口

# 3. 放行防火墙端口（如CentOS）
firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

# 4. 重启后端服务（若服务宕机）

5. 504 Gateway Timeout（网关超时）

根因：后端接口处理速度慢，Nginx代理超时时间设置过短，提前断开连接。

解决方案（直接复制，适配所有接口代理场景）：

nginx 复制代码

location /api { # 替换为自身接口路径
    proxy_connect_timeout 30s; # 连接后端超时时间
    proxy_send_timeout 60s;    # 发送请求超时时间
    proxy_read_timeout 60s;    # 读取后端响应超时时间
    proxy_pass http://backend_cluster;
}

二、跨域CORS类错误（最常见，对应初始报错）

常见报错：

No 'Access-Control-Allow-Origin' header is present on the requested resource

Response to preflight request doesn't pass access control check

常见根因：

未配置CORS相关响应头；
未处理OPTIONS预检请求；
带Cookie/Token时，Access-Control-Allow-Origin用了*通配符；
未加always参数，CORS头被后端服务覆盖。

一键修复配置：

nginx 复制代码

location / { # 接口根路径，根据自身需求调整
    # 允许的前端域名（带Cookie/Token时，不能用*，必须写具体域名）
    add_header Access-Control-Allow-Origin https://www.xxx.com always;
    add_header Access-Control-Allow-Credentials true always; # 允许携带Cookie/Token
    add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS always; # 允许的请求方法
    add_header Access-Control-Allow-Headers Content-Type,Authorization,X-Requested-With always; # 允许的请求头
    add_header Access-Control-Max-Age 86400 always; # 预检请求缓存1天，减少重复预检

    # 拦截OPTIONS预检请求，直接返回204放行（无需转发到后端）
    if ($request_method = OPTIONS) {
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }

    proxy_pass http://backend_cluster; # 转发到后端服务
}

三、SSL/HTTPS证书类错误

1. 浏览器提示：不安全、证书无效

根因：证书过期、域名不匹配、pem/key路径错误、文件损坏、缺少中间证书链。

修复：更换有效证书、修正证书路径、补充中间证书。

2. 混合内容报错（页面HTTPS，加载HTTP资源）

修复：添加强制升级头，将HTTP资源自动转为HTTPS加载：

nginx 复制代码

add_header Content-Security-Policy upgrade-insecure-requests always;

3. 80端口无法跳转443

根因：server_name不匹配、缺少301跳转配置。

修复：确保跳转server的server_name包含所有需要跳转的域名（如xxx.com、www.xxx.com）。

四、WebSocket/WSS断连、握手失败

常见报错：WebSocket connection failed

根因：

未配置Upgrade/Connection升级头；
proxy_http_version不是1.1；
超时时间太短，自动断开长连接。

修复模板：

nginx 复制代码

location /ws { # 替换为自身WebSocket路径
    proxy_pass http://ws_cluster; # 后端WebSocket服务地址
    proxy_http_version 1.1; # 必须为1.1，支持长连接
    proxy_set_header Connection ""; # 清空连接头，避免干扰
    # WebSocket协议升级核心配置
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    # 拉长超时时间，避免自动断连（根据业务调整，如300s）
    proxy_read_timeout 300s;
}

五、其他高频问题

1. 静态资源加载慢、缓存失效

nginx 复制代码

location ~* \.(jpg|css|js|png|mp4)$ {
    expires 30d; # 缓存30天
    add_header Cache-Control public; # 允许客户端缓存
    access_log off; # 关闭静态资源日志，减少IO压力
}

2. 中文乱码

nginx 复制代码

http {
    charset utf-8; # 全局编码，或在对应server内添加
}

3. 限流触发503 Service Unavailable

根因：单IP请求频率超过limit_req配置的限制。

临时修复：调低rate值（如改为10r/s），或注释限流规则测试：

nginx 复制代码

# limit_req zone=api_limit burst=5 nodelay; # 注释该行，临时关闭限流

4. Nginx并发高、卡顿

根因：worker_connections值太小，未开启epoll模型。

修复：

nginx 复制代码

events {
    worker_connections 10240; # 增大连接数，根据服务器配置调整
    use epoll; # 开启高效IO模型，提升并发能力
}

第五部分：常用运维命令（离线备查）

日常运维必用，无需记复杂命令，直接复制执行。

bash 复制代码

# 1. 检查Nginx配置语法（部署前必做）
nginx -t

# 2. 平滑重启Nginx（修改配置后生效，不中断业务）
nginx -s reload

# 3. 停止Nginx服务（谨慎使用，会中断业务）
nginx -s stop

# 4. 查看错误日志（排错核心，实时监控报错）
tail -f /usr/local/nginx/logs/error.log

# 5. 查看访问日志（查看请求情况）
tail -f /usr/local/nginx/logs/access.log

# 6. 查看Nginx进程是否正常运行
ps -ef | grep nginx

# 7. 测试接口是否正常（区分Nginx和后端问题）
curl -I https://api.xxx.com # 替换为自身接口域名
curl -X POST https://api.xxx.com/test -d "param=1" # 测试POST接口

# 8. 手动执行日志切割脚本（测试脚本是否正常）
bash /usr/local/nginx/sbin/nginx_log_cut.sh

# 9. 查看Nginx监听端口
ss -lntp | grep nginx

补充：快速排错通用流程（标准化）

执行nginx -t，先检查配置语法是否错误（最基础，避免低级错误）；
执行tail -f /usr/local/nginx/logs/error.log，查看具体报错信息，精准定位根因；
临时注释安全、限流、跨域等规则，缩小问题范围（判断是规则问题还是基础配置问题）；
用curl测试接口，区分是Nginx配置问题，还是后端服务问题；
修改配置后，执行nginx -s reload生效，再次测试验证。

（注：文档部分内容可能由 AI 生成）