Nginx 反向代理实战：解决 IPv6 报错与跨网段访问指南

文章目录

[Nginx 反向代理实战：解决 IPv6 报错与跨网段访问指南](#Nginx 反向代理实战：解决 IPv6 报错与跨网段访问指南)
- [📖 文档概述](#📖 文档概述)
- [🎯 核心目标](#🎯 核心目标)
- [🛠️ 实施步骤详解](#🛠️ 实施步骤详解)
- - [第一步：修复 IPv6 解析报错](#第一步：修复 IPv6 解析报错)
  - 第二步：配置反向代理 (Server Block)
  - 第三步：验证与调试 (关键技巧)
  - [第四步：DNS 解析与端口误区排查](#第四步：DNS 解析与端口误区排查)
  - - [1. DNS 解析设置](#1. DNS 解析设置)
    - [2. ⚠️ 常见误区：端口号问题](#2. ⚠️ 常见误区：端口号问题)
- [🔍 故障排查清单 (Checklist)](#🔍 故障排查清单 (Checklist))
- [📚 核心知识总结](#📚 核心知识总结)
- [🚀 进阶建议](#🚀 进阶建议)

Nginx 反向代理实战：解决 IPv6 报错与跨网段访问指南

⚠️ 隐私提示：本文档中的所有 IP 地址、域名均为示例占位符。在实际部署时，请将其替换为您真实的配置信息，切勿直接将包含真实内网 IP 的配置文件截图发布到公共网络。

📖 文档概述

本文档记录了如何通过 Nginx 将公网域名请求代理到公司内部网络服务的完整过程。重点解决了 IPv6 解析导致的连接超时 问题，并详细阐述了 端口映射 与 DNS 解析 的核心原理。适用于需要将内网开发/测试环境暴露给公网访问的场景。

🎯 核心目标

场景：用户通过公网域名（如 app.example.com）访问部署在公司内网的 Web 服务（如 192.168.x.x:3000）。
架构：
- 入口：云服务器（公网 IP，运行 Nginx）。
- 出口：公司内网服务器（内网 IP，运行实际业务）。
- 动作：Nginx 作为反向代理，转发请求并返回结果。
关键难点 ：
- Nginx 默认尝试 IPv6 解析域名，若网络环境不支持 IPv6 会导致 connect() failed (101: Network is unreachable)。
- 用户容易混淆"代理端口"与"源服务端口"，导致访问失败。

🛠️ 实施步骤详解

第一步：修复 IPv6 解析报错

在 CentOS/RHEL 等现代 Linux 发行版中，Nginx 默认可能优先尝试 IPv6 解析。如果服务器或上游网络不支持 IPv6，代理请求会失败。

解决方案 ：在 nginx.conf 的 http 块中强制指定 DNS 解析器并关闭 IPv6。

配置文件路径 ：/etc/nginx/nginx.conf

nginx 复制代码

http {
    # ... 其他配置 ...

    # 【关键配置】指定 DNS 服务器并禁用 IPv6
    # 语法：resolver <dns_ip> [ipv6=off];
    # 建议替换为您所在区域稳定的公共 DNS (如 114.114.114.114 或 8.8.8.8)
    resolver 114.114.114.114 8.8.8.8 ipv6=off;

    # ... 其他配置 ...
    
    include /etc/nginx/conf.d/*.conf;
}

操作命令：

bash 复制代码

# 1. 测试配置语法
sudo nginx -t

# 2. 重载配置生效
sudo systemctl reload nginx

💡 知识点 ：ipv6=off 参数告诉 Nginx 在解析域名时只获取 A 记录（IPv4），忽略 AAAA 记录（IPv6），从而避免不必要的网络尝试和超时。

第二步：配置反向代理 (Server Block)

创建独立的配置文件，将特定域名流量转发到内网 IP。

配置文件路径 ：/etc/nginx/conf.d/<your-project>.conf

nginx 复制代码

server {
    listen 80;
    # 替换为您的真实公网域名
    server_name app.example.com; 

    location / {
        # 替换为您的真实内网服务 IP 和端口
        # 注意：此处填写的是 Nginx 能访问到的内网地址，不要写公网地址
        proxy_pass http://<Inner_IP>:<Inner_Port>;

        # 传递真实用户 IP 给后端（重要！否则后端日志全是 Nginx IP）
        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;

        # 优化长连接支持（可选，针对 WebSocket 或大文件）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

操作命令：

bash 复制代码

sudo nginx -t && sudo systemctl reload nginx

第三步：验证与调试 (关键技巧)

在修改 DNS 之前，先在服务器本地验证 Nginx 配置是否正确，避免外部干扰。

测试命令：

bash 复制代码

# 模拟外部请求，强制指定 Host 头，访问本地 127.0.0.1 (即 Nginx 监听口)
# 请将 <your-domain.com> 替换为您的真实域名
curl -I -H "Host: app.example.com" http://127.0.0.1

结果分析：

✅ HTTP/1.1 200 OK：配置成功，Nginx 已成功从内网拉取数据。
❌ 502 Bad Gateway：Nginx 无法连接内网 IP（检查防火墙、路由、内网服务状态）。
❌ 404 Not Found ：域名匹配错误，检查 server_name。

第四步：DNS 解析与端口误区排查

1. DNS 解析设置

确保域名服务商处，app.example.com 的 A 记录 指向 云服务器的公网 IP。

验证命令：ping app.example.com
预期结果：返回云服务器公网 IP。

2. ⚠️ 常见误区：端口号问题

错误做法 ：访问 http://app.example.com:<Inner_Port>
- 原因：:<Inner_Port> 是内网服务的端口，云服务器通常未开放此端口，且 Nginx 也未监听此端口。
正确做法 ：访问 http://app.example.com (默认 80 端口)
- 原理：用户访问 80 端口 -> Nginx 接收 -> Nginx 内部转发请求到内网的 <Inner_Port> 端口 -> 返回结果给用户。用户无需知道内网端口。

🔍 故障排查清单 (Checklist)

现象	可能原因	解决方案
connect() failed (101: Network is unreachable)	Nginx 尝试 IPv6 连接	添加 `resolver ... ipv6=off` 配置
502 Bad Gateway	云服务器无法连通内网 IP	检查云服务器安全组出方向、公司防火墙、内网服务是否存活
404 Not Found	域名不匹配	检查 `server_name` 拼写，确认 Host 头传递
页面空白/加载失败	前端资源路径错误	检查前端代码中 API 请求地址是否为相对路径，或配置了错误的绝对地址
访问 : 不通	端口概念混淆	去掉 URL 中的端口号，直接访问域名

📚 核心知识总结

反向代理 (Reverse Proxy)：
- 充当"中间人"，客户端只与 Nginx 交互，不知道后端真实存在。
- 好处：隐藏内网结构、统一入口、负载均衡、SSL 终止。
Resolver 指令：
- 当 proxy_pass 使用域名而非 IP 时，Nginx 需要 DNS 解析。
- 在生产环境中，显式配置 resolver 并关闭 IPv6 是最佳实践，能避免大量隐蔽的网络超时问题。
Host 头传递：
- proxy_set_header Host $host; 至关重要。如果不加，后端服务收到的 Host 可能是内网 IP，导致某些框架（如 Django, SpringBoot, Vite）拒绝服务或重定向错误。
端口映射逻辑：
- 外部端口 (80/443)：面向公众，由 Nginx 监听。
- 内部端口 (3000/8080/5173)：面向内网，由业务服务监听。
- 两者不需要一致，Nginx 负责桥接。

🚀 进阶建议

启用 HTTPS ：使用 Let's Encrypt (certbot) 免费证书，将 HTTP 强制跳转到 HTTPS，提升安全性。
日志监控 ：定期检查 /var/log/nginx/error.log，监控 upstream 连接状态。
高可用 ：如果内网服务有多台，可在 upstream 块中配置多台服务器实现负载均衡。