日期：2025年 11月 15日

標籤： Asp.NET Core Asp.NET Core Web MVC C# Nginx Docker

摘要：C# 學習筆記

第一部分：前置作業 - 環境架構

Step 1：前置作業 - 環境架構

以下是此次說明用到的環境架構

Step 2：前置作業 - Web 開放的 API

並且運行的 Web 應用程式安裝在容器上，並且開放了以下端口：
※取得 IP 使用的屬性 : HttpContext.Connection.RemoteIpAddress

/// <summary>
/// 當前訪問者(用戶) 後端紀錄的 IP
/// </summary>        
[HttpGet]
public IActionResult CallAPI()
{
    var remoteIp = HttpContext.Connection.RemoteIpAddress;
    // 方便 Demo 說明轉換成純 IPv4
    var ipv4 = remoteIp?.MapToIPv4();
    var result = new
    {
        RemoteIp = ipv4.ToString(),
        Scheme = HttpContext.Request.Scheme,
        Host = HttpContext.Request.Host.Value
    };
    return Ok(result);
}

並且對應的呼叫 API 路由如下：

http://{Domain}//Home//CallAPI

第二部分：問題描述

Step 1：用戶端-直連 - 可以正常取得

我們透過本機電腦訪問容器位址，中間過程沒有任何 反向代理 ，視為直連

輸入以下 URL 網址列，可以看到 API 反饋的 IP 為 192.168.242.76 正確的獲得了訪問者的 IP

http://192.168.51.93:8888/Home/CallAPI

Step 2：用戶端-經過代理 - 問題出現

我們透過本機電腦訪問 Nginx 對外位址，有 經過反向代理

輸入以下 URL 網址列，可以看到 API 反饋的 IP 為 192.168.51.93 這是 伺服器IP 而非用戶IP

http://192.168.51.93:8889/Home/CallAPI

Step 3：問題描述 - 為何無法取得真實 IP

這實際上與轉發標頭 X-Forwarded-For 有關，以下是不同訪問模式下的轉發層級：

直連時,HttpContext.Connection.RemoteIpAddress 會顯示用戶的真實 IP
經過代理時,HttpContext.Connection.RemoteIpAddress 只能看到最近一層代理的 IP (Nginx IP),而不是用戶的真實 IP

第三部分：解決方案

Step 1：範例代碼架構

打開本篇範例代碼後，架構基本分成以下：
※ 調整前專案 ：NotUseForwardedHeadersExample
※ 調整後專案 ：UseForwardedHeadersExample

Step 2：解決方案 - 設定初始化配置

在初始化配置中設定以下，添加 ForwardedHeaders，以下是解決此問題所需參數與說明：

using Microsoft.AspNetCore.HttpOverrides;
try
{
    var builder = WebApplication.CreateBuilder(args);

    // Add services to the container.
    builder.Services.AddControllersWithViews();

    var app = builder.Build();

    // 1. 添加 ForwardedHeaders 
    var forwardedHeadersOptions = new ForwardedHeadersOptions
    {
        ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto,
        ForwardLimit = 5
    };  
    app.UseForwardedHeaders(forwardedHeadersOptions);

    //... 略

    app.Run();

}
catch (Exception ex)
{
    Console.WriteLine(ex);
}

至此設定完成後，可以直接進到 第四部分：DEMO 成果 ，第三部份後半段為安全性、建議說明

Step 3：完整配置 ForwardedHeaders

以下是說明 ForwardedHeaders 的其他參數，基本上會用到的只有 3 種參數配置，其餘多半在生產環境上可以不用配置

以下是預設代碼參考：

var forwardedHeadersOptions = new ForwardedHeadersOptions
{
    // 處理所有轉發標頭
    ForwardedHeaders = ForwardedHeaders.XForwardedFor 
                     | ForwardedHeaders.XForwardedProto 
                     | ForwardedHeaders.XForwardedHost,        
    // 合理的轉發                
    ForwardLimit = 5,    
};

// 信任特定的代理伺服器
forwardedHeadersOptions.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));

// 或信任整個內網
forwardedHeadersOptions.KnownNetworks.Add(
    new IPNetwork(IPAddress.Parse("10.0.0.0"), 8)
);
forwardedHeadersOptions.KnownNetworks.Add(
    new IPNetwork(IPAddress.Parse("172.16.0.0"), 12)
);
forwardedHeadersOptions.KnownNetworks.Add(
    new IPNetwork(IPAddress.Parse("192.168.0.0"), 16)
);

第四部分：DEMO 成果

Step 1：重新佈署

延續 第三部分 Step 2. 將調整後的代碼，重新部署代碼到環境

Step 2：用戶端-直連 - 可以正常取得

直連的方式


仍可以正常取得 IP - 符合預期

Step 2：用戶端-經過代理 - 可以正常取得

經過反向代理 的方式


也可以正常取得 IP - 在有反向代理的情況下，仍能更有機會取得真實的用戶IP，解決了無法取得用戶真實 IP 的問題
※強調：始終不可以相信前端用戶傳給伺服器的任何東西，包含 IP，這是可以偽造的，但透過此方法是讓我們能更有高精確 + 安全性的取得用戶IP

第五部分：生產環境實務探討

Step 1：為何要用 ForwardedHeadersOptions

問題 ： 在這邊點出個問題，有必要使用 ForwardedHeadersOptions 來取得真實 IP 嗎? 即使不用此方法，不也可以取得
解答 ： 是的，但一般代碼可能實作如下(Web API):

[HttpGet]
public IActionResult GetClientIP()
{
    char[] Separator = { ',' };
    var httpRequest = HttpContext.Request;
    var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString() ?? string.Empty;
    if (HttpContext.Request.Headers.Count == 0)
    {
        Console.WriteLine("沒有請求 Header 視為異常，不解析 IP");
        return BadRequest();
    }
    // 1. 檢查標頭 X-Forwarded-For - 自己實作
    if (Request.Headers.TryGetValue("X-Forwarded-For", out var forwardedIps))
    {
        var ips = forwardedIps.ToString().Split(Separator, StringSplitOptions.RemoveEmptyEntries);
        clientIp = ips[0];// 2. 直接取第 1 個 IP，缺少驗證任何來源，任何偽造都無方防護
    }

    // 3. 自己刻信任的網段、白名單 IP、黑名單 IP ... 略

    var result = new
    {
        RemoteIp = clientIp,                
    };
    return Ok(result);
}

開發團隊可以自己解析 Headers 內的東西，然後取得 IP，更完整實作的會檢查此 IP 是否符合公司內部信任域名 … 等
回到原本的問題：微軟已經有現成的 ForwardedHeadersOptions 並實作 KnownNetworks、KnownProxies 更安全的封裝方法，現代開發者應該避免自己花時間重刻方法。

Step 2：ForwardLimit 應該設定多少值

微軟給定的 ForwardLimit 預設值為 1 ，但實務上環境的架構很多種可能：

用戶 => CloudFlare => LoadBalnce => Nginx => 容器Nginx => 容器 
用戶 => Amazon Cloud => CloudFlare => LoadBalnce => Nginx => 容器
... 
...
...
太多種可能

以下是可以使用的常見架構下的參考值：

因此多數的情況下，ForwardLimit 設定 5 已可解決常見的部署架構。

Step 3：生產環境面臨的問題 - 原則

X-Forwared-For 標頭是由客戶端提供給後端的，因此是可以輕易偽造，透過以下 Windows Batch 指令可以輕鬆偽造

curl -H "X-Forwarded-For: 8.8.8.8, 1.1.1.1" https://your-api.com/api/TestAPI

所以需保持一個原則 不可能 100% 取得客戶端真實IP

Step 4：生產環境面臨的問題 - 環境太多,配置複雜

雖然最終部署到生產環境，但開發的過程是循序漸進，不可能為每個環境都配置信任的域名、Limit

本機開發 → DEV → QAT → STG → PRO   

其次每個企業組織架構不同，當開發並 不能管理生產環境 時，往往面臨的將會是 開發團隊不清楚網路架構，因為是由另一個部門處理公司的對外網路與機器管理
因此 不要過度追求完美，符合實際部署需求，實用至上!