Nginx配置学习 - 技术栈

今天学习了一下Nginx配置，现提供的是一份完整的 Nginx 配置文件，核心目标是为 dg.top 域名搭建一个统一的 HTTPS 入口，同时反向代理 MinIO（控制台+对象存储）和 SpringBoot 后端服务，并解决了 MinIO 访问的 403 等关键问题。下面我会从配置思路、核心模块、关键细节三个维度全面解析这份配置。

一、整体配置思路

这份配置的核心逻辑是：统一入口 + 协议强制升级 + 分路径代理 + 问题兜底，具体拆解为：

协议层：强制 HTTP 跳转 HTTPS（适配小程序等禁止 HTTP 的场景）；
入口层：所有请求通过 443 端口（HTTPS）统一进入 Nginx；
路由层：按 URL 路径区分不同服务（MinIO API/控制台/WebSocket、SpringBoot），精准反向代理到对应后端端口；
问题层 ：针对 MinIO 常见的 403 错误(权限或校验类错误的核心表现)、WebSocket 连接失败、大文件上传等问题做专项配置；
兜底层：未匹配到特定路径的请求，全部转发给 SpringBoot 后端，同时处理跨域。

二、核心模块解析

1. HTTP 强制跳转 HTTPS 模块

nginx 复制代码

server {
    listen 80;
    server_name dg.top www.dg.top;
    return 301 https://$host$request_uri;
}

作用：拦截所有 80 端口（HTTP）的请求，通过 301 永久重定向跳转到 HTTPS 地址；
关键变量 ：
- $host：保留请求的域名（如 dg.top 或 www.dg.top）；
- $request_uri：保留完整的请求路径和参数（如 /minio/login?user=test），确保跳转后请求不丢失；
适配场景：小程序、部分浏览器强制要求 HTTPS，避免因 HTTP 导致的访问失败。

2. HTTPS 基础配置模块

nginx 复制代码

server {
    listen 443 ssl;
    server_name dg.top www.dg.top;

    ssl_certificate        /etc/nginx/cert/dg.top.pem;
    ssl_certificate_key    /etc/nginx/cert/dg.top.key;

    ssl_session_cache      shared:SSL:1m;
    ssl_session_timeout    5m;
    ssl_protocols          TLSv1.2 TLSv1.3;
    ssl_ciphers            ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_prefer_server_ciphers on;
    # ... 后续路由配置
}

核心作用：开启 443 端口的 HTTPS 服务，配置证书和安全加密规则；
关键配置解读 ：
- ssl_certificate/ssl_certificate_key：指定 HTTPS 证书（PEM 公钥）和私钥路径，是 HTTPS 生效的核心；
- ssl_protocols：仅启用 TLS1.2/TLS1.3（淘汰老旧的 SSLv3、TLS1.0/1.1），提升安全性；
- ssl_ciphers：指定高强度加密套件，禁用弱加密算法（如 MD5、RC4）；
- ssl_prefer_server_ciphers on：优先使用服务端指定的加密套件，避免客户端选择弱加密方式。

3. MinIO 核心路由模块（解决 403/连接失败关键）

MinIO 分为「控制台（9001 端口）」和「对象存储 API（9000 端口）」，配置按功能拆分，核心是解决 403 Forbidden 和 WebSocket 连接问题。

（1）MinIO 控制台 API 路由（/api/v1/*）

bash 复制代码

处理 MinIO 控制台的 后端 API 请求（如登录认证、桶操作、对象管理的接口调用）

nginx 复制代码

location /api/v1/ {
    proxy_pass          http://127.0.0.1:9001;
    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_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Proto $scheme;
    proxy_set_header    Origin ''; # ✅ 解决403 Forbidden 核心配置！！！
    proxy_buffering off;
    proxy_connect_timeout 600s;
    proxy_read_timeout    600s;
    proxy_send_timeout    600s;
}

核心问题解决 ：proxy_set_header Origin '' 是解决 MinIO 403 的关键------MinIO 默认会校验请求的 Origin 头，如果 Origin 与配置的允许列表不匹配，会直接返回 403，清空 Origin 头可绕过该校验；
WebSocket 兼容 ：proxy_http_version 1.1 + Upgrade/Connection 头，确保 API 中包含的 WebSocket 连接能正常升级；
超时配置：600s 超时（10 分钟），避免大文件操作或慢请求被 Nginx 主动断开；
关闭缓冲 ：proxy_buffering off，实时转发请求/响应，避免 MinIO 控制台实时交互延迟。

（2）MinIO 控制台 WebSocket 路由（/ws/*）

nginx 复制代码

location /ws/ {
    proxy_pass          http://127.0.0.1:9001;
    # 同/api/v1/的核心配置，仅路径不同
}

专属作用：MinIO 控制台的实时日志、通知等功能依赖 /ws 路径的 WebSocket，单独配置可确保 WebSocket 连接稳定，避免被其他路由覆盖；
核心配置复用：与 /api/v1/ 保持一致的 Origin、超时、缓冲配置，确保 WebSocket 不会因配置缺失导致连接失败。

（3）MinIO 对象存储 API 路由（/minio-api/*）

nginx 复制代码

location /minio-api/ {
    proxy_pass          http://127.0.0.1:9000/;
    proxy_set_header    Host $host;
    # ... 其他头配置
    client_max_body_size 500m; # ✅ 大文件上传关键
}

路径注意点 ：proxy_pass 末尾的 / 是关键------Nginx 会将 /minio-api/xxx 转发为 9000/xxx，而非 9000/minio-api/xxx，避免路径冗余；
大文件支持 ：client_max_body_size 500m，允许最大 500MB 的文件上传，解决 MinIO 上传大文件时 Nginx 因默认 1MB 限制返回 413 错误；
适配场景：对接 MinIO 的 S3 兼容 API（如上传、下载、删除对象）。

（4）MinIO 控制台入口路由（/minio）

bash 复制代码

处理 MinIO 控制台的 前端页面入口请求（如访问 https://域名/minio 时的页面加载）

nginx 复制代码

location /minio {
    proxy_pass          http://127.0.0.1:9001;
    # 同/api/v1/的核心配置
}

作用：MinIO 控制台的主入口（如 https://darlingift.top/minio），转发到 9001 端口的 MinIO 控制台；
无末尾 / ：proxy_pass 末尾无 /，意味着 Nginx 会将 /minio/xxx 转发为 9001/minio/xxx，与 MinIO 控制台的路径保持一致。

（5）MinIO 控制台静态资源路由

nginx 复制代码

location /_minio { proxy_pass http://127.0.0.1:9001/_minio; proxy_set_header Origin ''; proxy_buffering off; }
location /static { proxy_pass http://127.0.0.1:9001/static; proxy_set_header Origin ''; proxy_buffering off; }
# ... 其他静态资源路径

作用：MinIO 控制台的前端静态资源（CSS、JS、图片、图标等）都在这些路径下，单独配置确保静态资源能正常加载；
极简配置 ：仅保留核心的 proxy_pass、Origin 和 proxy_buffering，满足静态资源访问即可，无需 WebSocket 相关配置。

4. SpringBoot 后端兜底路由（/）

nginx 复制代码

location / {
    proxy_pass          http://127.0.0.1:8080;
    # 基础代理头配置
    proxy_connect_timeout 600s;
    proxy_read_timeout    600s;
    proxy_send_timeout    600s;

    # 跨域配置
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
    add_header Access-Control-Allow-Headers 'Content-Type, Authorization, token, X-Requested-With';
    if ($request_method = 'OPTIONS') {
        return 204;
    }
}

兜底逻辑：Nginx 按「精准路径优先」匹配，所有未匹配到 /api/v1/、/ws/、/minio-api/、/minio 等路径的请求，都会走到这个 / 路由，转发到 8080 端口的 SpringBoot 后端；
跨域解决 ：
- add_header Access-Control-Allow-Origin *：允许所有域名跨域（生产环境可改为指定域名，更安全）；
- OPTIONS 请求处理：前端跨域预检请求（OPTIONS）直接返回 204，避免后端处理预检请求的冗余逻辑；
- 允许常见的请求方法（GET/POST 等）和自定义头（token 等），适配 SpringBoot 后端的接口规范。

三、关键细节与最佳实践

Origin 头清空（MinIO 403 核心） ：
MinIO 有严格的 CORS 校验，默认会拒绝 Origin 不匹配的请求，通过 proxy_set_header Origin '' 清空 Origin 头，可绕过该校验（生产环境也可在 MinIO 中配置允许的 Origin，更规范）。
超时配置（600s） ：
MinIO 大文件上传、控制台长连接等场景需要较长的超时时间，默认 60s 会导致请求被断开，600s 是兼顾性能和稳定性的合理值。
proxy_buffering off ：
关闭 Nginx 代理缓冲，确保 MinIO 控制台的实时交互（如日志、进度条）能实时返回给前端，避免缓冲导致的延迟。
路径匹配优先级 ：
Nginx 路径匹配规则是「精准路径 > 前缀路径（带 /） > 前缀路径（不带 /） > 通用路径（/）」，这份配置的路径顺序（/api/v1/ → /ws/ → /minio-api/ → /minio → 静态资源 → /）完全符合优先级规则，不会出现路由覆盖问题。
证书与加密规范 ：
仅启用 TLS1.2/TLS1.3，禁用弱加密套件，符合现代 HTTPS 安全规范，避免被浏览器标记为「不安全」。

总结

这份 Nginx 配置的核心亮点和关键思路可总结为：

协议统一：强制 HTTP 跳转 HTTPS，适配小程序等 HTTPS 强制场景；
路由精准：按 MinIO 功能拆分路径（API/WebSocket/静态资源/对象存储），兜底转发 SpringBoot，无路由冲突；
问题兜底：针对性解决 MinIO 403（清空 Origin）、WebSocket 连接失败（Upgrade 头）、大文件上传（client_max_body_size）、跨域（CORS 头）等核心问题；
性能稳定：合理配置超时、关闭缓冲，确保长连接和实时交互稳定。

proxy_pass 末尾的 / 是「是否删除前缀」的开关：

如果 proxy_pass 末尾加了 / → 强制删除 location 匹配的前缀，只转发剩余路径；
如果 proxy_pass 末尾没加 / → 保留完整路径（包括 location 匹配的前缀），原样转发；
location 末尾的 / 只决定「是否匹配子路径」，不决定「是否删前缀」。location /test { #

bash 复制代码

location /test {         # location 无
    proxy_pass http://127.0.0.1:8080/; # proxy_pass 有 /
}
这个有风险转发成http://127.0.0.1:8080//xxx