NGINX 模組組態與重寫規則深度解析

NGINX 作為網頁伺服器和反向代理伺服器，其模組化設計和靈活的組態能力是其廣受歡迎的重要原因。理解 NGINX 的內部請求處理機制以及如何有效地利用 error_page 和 rewrite 指令，對於構建高效能、易維護的網路應用至關重要。內部重新導向和子請求是 NGINX 處理請求的兩種主要方式，前者會改變請求的 URI 並可能比對到不同的 location 區塊，後者則用於生成補充主請求內容的資料。error_page 指令允許我們自定義錯誤頁面，而 rewrite 指令則可以根據正規表示式修改請求的 URI，實作 URL 重寫、重定向等功能。在使用 rewrite 指令時，需要注意避免無限迴圈的問題，可以透過 break 旗標來終止重寫流程。此外，NGINX 提供了條件結構和變數操作等功能，可以根據不同的條件執行不同的重寫規則。理解位置區塊和 if 區塊的差異，以及如何使用 set 指令操作變數，對於編寫複雜的組態至關重要。最後，透過日誌記錄和除錯技巧，可以更好地理解 NGINX 的行為，並快速排查問題。

NGINX 模組組態探討

NGINX 是一個強大且靈活的網頁伺服器，其模組組態功能非常豐富。本篇將探討 NGINX 的內部請求處理機制及模組組態，特別是 error_page 和 rewrite 指令的使用。

內部請求處理

NGINX 中有兩種主要的內部請求處理機制：內部重新導向和子請求。

內部重新導向

內部重新導向是指 NGINX 在內部將客戶端的請求重新導向到另一個 URI。這通常會改變請求的 URI，並可能使其比對到不同的位置區塊。最常見的情況是使用 rewrite 指令來重寫請求 URI。

子請求

子請求是指在主請求處理過程中，NGINX 觸發的額外請求，以生成補充主請求內容的資料。例如，add_after_body 指令會在原始請求處理完畢後，處理一個新的 URI，並將其結果附加到原始請求的主體中。SSI 模組也使用子請求來插入內容。

`error_page` 指令

error_page 指令允許你定義伺服器在發生特定錯誤碼時的行為。最簡單的形式是將一個 URI 與錯誤碼關聯：

server {
    server_name website.com;
    error_page 403 /errors/forbidden.html;
    error_page 404 /errors/not_found.html;
}

當客戶端嘗試存取一個不存在的檔案時，NGINX 會根據錯誤碼來提供相應的錯誤頁面。這些頁面可以位於伺服器上的任意位置，但通常會放在一個專門的目錄中。

實際範例

以下是一個更複雜的範例，展示瞭如何使用 error_page 指令來處理 404 錯誤：

server {
    server_name website.com;
    root /var/www/vhosts/website.com/httpdocs/;
    error_page 404 /errors/404.html;

    location /errors/ {
        alias /var/www/common/errors/;
        internal;
    }
}

在這個範例中，當客戶端嘗試存取一個不存在的檔案時，NGINX 會觸發一個內部重新導向到 /errors/404.html。這個 URI 會比對到 location /errors/ 區塊，並使用該區塊中的組態。

`rewrite` 指令

rewrite 指令允許你在內部重新導向客戶端的請求。當客戶端嘗試存取一個不存在的檔案時，可以使用 error_page 指令來指定錯誤頁面。當 NGINX 接收到這樣的錯誤時，它會生成一個新的內部請求來處理該錯誤頁面。

實際範例

以下是一個使用 rewrite 指令來重寫 URI 的範例：

server {
    server_name website.com;
    root /var/www/vhosts/website.com/httpdocs/;

    location /storage/ {
        internal;
        alias /var/www/storage/;
    }

    location /documents/ {
        rewrite ^/documents/(.*)$ /storage/$1;
    }
}

在這個範例中，當客戶端存取 http://website.com/documents/file.txt 時，NGINX 會將該請求重寫為 /storage/file.txt。這樣做會觸發一次內部重新導向，使得新的 URI 再次比對到 location /storage/ 區塊。

日誌記錄

在處理重新導向和 URL 重寫時，日誌記錄可以提供非常有用的資訊。要檢視內部重新導向的資訊，你需要設定 error_log 指令為 debug 模式。以下是一段經過精簡的除錯日誌摘錄：

->http request line: "GET /page.html HTTP/1.1"
->http uri: "/page.html"
->test location: "/errors/"
->using configuration ""
->http filename: "/var/www/vhosts/website.com/httpdocs/page.html"
-> open() "/var/www/vhosts/website.com/httpdocs/page.html" failed (2: No such file or directory), client: 127.0.0.1, server: website.com, request: "GET /page.html HTTP/1.1", host:"website.com"
->http finalize request: 404, "/page.html?" 1
->http special response: 404, "/page.html?"
->internal redirect: "/errors/404.html?"
->test location: "/errors/"
->using configuration "/errors/"
->http filename: "/var/www/common/errors/404.html"
->http finalize request: 0, "/errors/404.html?" 1

這段日誌記錄展示了 NGINX 是如何處理一個不存在檔案的請求，並觸發了一次內部重新導向來提供錯誤頁面。

小段落標題

認識 NGINX 的內部請求處理機制
探討 error_page 指令
探索 rewrite 指令及其應用
日誌記錄與除錯技巧

NGINX Rewrite 模組的探討

在 NGINX 中，Rewrite 模組是一個非常強大的工具，可以讓你重寫 URL、控制流量重定向以及處理條件性組態。然而，如果不小心處理，可能會導致無限迴圈、組態混亂等問題。這篇文章將探討如何避免這些常見錯誤，並提供一些實務案例來幫助你更好地理解和應用 Rewrite 模組。

無限迴圈的風險

NGINX 的 Rewrite 模組提供了多種語法和指令，但如果不謹慎使用，可能會導致組態混亂甚至無限迴圈。以下是一個常見的錯誤範例：

server {
    server_name website.com;
    location /documents/ {
        rewrite ^(.*)$ /documents/2018/$1;
    }
}

在這個組態中，我們希望將 /documents/ 下的所有請求重寫到 /documents/2018/ 下。然而，這樣的組態會導致內部重定向無限迴圈：

最初的請求是 /documents/anything。
重寫後變成 /documents/2018//documents/anything。
由於位置模式在內部重定向後會重新評估，所以再次重寫成 /documents/2018//documents/2018//documents/anything。

這樣的無限迴圈會導致 NGINX 產生 500 Internal Server Error。為了避免這種情況，我們可以使用 break 旗標來阻止內部重定向：

server {
    server_name website.com;
    location /documents/ {
        rewrite ^(.*)$ /documents/2018/$1 break;
    }
}

內容解密：

rewrite ^(.*)$ /documents/2018/$1;: 這行指令會將所有以 /documents/ 開始的請求重寫到 /documents/2018/ 下。正規表示式 ^(.*)$ 比對所有字元，並將其捕捉到 $1 中。
break: 這個旗標會在重寫後停止進一步的處理，避免無限迴圈。

條件結構與指令

Rewrite 模組引入了一些新的指令和區塊，其中包含 if 條件結構。這允許我們根據特定條件來應用組態。以下是一些常見的條件運算元：

server {
    if ($request_method = POST) {
        [...]
    }
}

內容解密：

$request_method: 這個變數表示請求方法（如 GET、POST）。
=: 這個運算元用於比較變數與指定值是否相等。
在這個例子中，如果請求方法是 POST，則應用相應的組態。

以下是一些其他常見的條件運算元：

~: 案敏比對正規表示式。
~*: 案不敏比對正規表示式。
-f: 測試指設定檔案是否存在。
-d: 測試指定目錄是否存在。

位置區塊與 if 區塊的差異

在 NGINX 中，位置區塊和 if 區塊有時看起來效果相似，但實際上它們有很大的不同：

if ($uri ~ /search/) {
    [...]
}

location ~ /search/ {
    [...]
}

內容解密：

if ($uri ~ /search/): 這行指令檢查 URI 是否包含 /search/，如果比對則應用相應的組態。
location ~ /search/：這行指令則是定義了一個位置區塊，用於處理所有比對 /search/ 的請求。

主要的差異在於可以使用的指令不同。位置區塊可以使用幾乎所有指令，而 if 區塊則只能使用 Rewrite 模組中的部分指令。

指令詳細說明

Rewrite 模組提供了一些強大的指令來操作 URL 和控制流量。以下是一些關鍵指令及其使用情境：

rewrite regexp replacement [flag];

內容解密：

regexp: 用於比對 URL 的正規表示式。
replacement: 用於替換比對部分的字串。
[flag]: 用於控制重寫行為的旗標（如 break、redirect）。

流程圖示

此圖示展示了 NGINX Rewrite 模組中的常見流程：

  graph TD
    E[E]
    A[請求進入] --> B{URI 比對正規表示式?}
    B -- 是 --> C[應用替換規則]
    B -- 否 --> D[繼續處理請求]
    C --> E{包含 break 旗標?}
    E -- 是 --> D
    E -- 否 --> B

內容解密：

此圖示展示了 NGINX 在處理 Rewrite 模組時的決策流程。當請求進入時，會檢查 URI 是否比對正規表示式。如果比對，則應用替換規則；如果不比對或包含 break 旗標，則繼續處理請求。

總結來說，NGINX 的 Rewrite 模組非常強大且靈活，但在使用時需要特別小心避免無限迴圈和組態混亂。透過合理設計條件結構和使用適當的旗標，我們可以有效地控制流量並提高伺服器效能。希望這篇文章能夠幫助你更好地理解和應用 NGINX 的 Rewrite 模組。

NGINX 重寫模組深度探討與應用案例

NGINX 作為一個強大的反向代理伺服器，其重寫模組（Rewrite Module）是其中非常重要的一部分。它允許我們根據特定的規則來修改請求的 URI，這對於 SEO 最佳化、URL 美化以及多樣化的網站需求來說都是不可或缺的。這篇文章將探討 NGINX 的重寫模組，並提供一些實際應用的案例。

重寫指令與其應用

常見重寫指令

在 NGINX 中，有幾個常見的重寫指令，每個指令都有其特定的用途和行為。以下是一些常見的重寫指令及其說明：

last：將當前重寫規則設為最後一個被應用的規則。應用後，新的 URI 將由 NGINX 處理，並搜尋對應的 location 塊，但不會再進行進一步的重寫指令。
break：應用當前重寫規則後，NGINX 不會為修改後的 URI 發起新的請求（即不會重新搜尋對應的 location 塊），並忽略所有後續的重寫指令。
redirect：傳回一個 302 Moved Temporarily 的 HTTP 回應，並將替換 URI 作為位置頭部的值。
permanent：傳回一個 301 Moved Permanently 的 HTTP 回應，並將替換 URI 作為位置頭部的值。

這些指令可以根據需要靈活組態，以滿足不同的網站需求。

執行範例

以下是一些常見重寫規則的範例：

rewrite ^/search/(.*)$ /search.php?q=$1;
rewrite ^/search/(.*)$ /search.php?q=$1?;
rewrite ^ http://website.com;
rewrite ^ http://website.com permanent;

內容解密：

rewrite ^/search/(.*)$ /search.php?q=$1;：這條規則將所有比對 /search/ 的請求重寫到 /search.php，並將捕捉到的引數作為 q 引數傳遞。
rewrite ^/search/(.*)$ /search.php?q=$1?;：這條規則與上一條相似，但多了一個 ? 在引數末尾，表示不包含原始 URL 中的其他引數。
rewrite ^ http://website.com;：這條規則將所有請求重定向到 http://website.com。
rewrite ^ http://website.com permanent;：這條規則與上一條相似，但使用了 permanent 標誌，表示永久重定向。

break 指令和 return 指令

break 指令

break 指令用於阻止進一步的重寫操作。當 break 指令被執行後，URI 將被固定且無法再被修改。

if (-f $uri) {
    break; # 如果檔案存在，則停止進一步重寫
}
if ($uri ~ ^/search/(.*)$) {
    set $query $1;
    rewrite ^ /search.php?q=$query?;
}

內容解密：

這段程式碼首先檢查請求的 URI 是否對應到一個實際存在的檔案。如果存在，則使用 break 指令停止進一步的重寫操作。如果不存在，則將 URI 中捕捉到的引數設定到變數 $query 中，並將請求重寫到 /search.php。

return 指令

return 指令用於中斷請求處理並傳回指定的 HTTP 狀態碼或文字。

if ($uri ~ ^/admin/) {
    return 403;
    # 下面這行不會執行
    # rewrite ^ http://website.com;
}

內容解密：

這段程式碼檢查請求的 URI 是否以 /admin/ 開頭。如果是，則傳回 403 Forbidden 狀態碼。由於 return 指令已經完成了請求處理，因此後續的重寫操作不會執行。

set 指令和變數操作

set 指令

set 指令用於初始化或重新定義變數。注意，某些變數（如 $uri）是不可重新定義的。

set $var1 "some text";
if ($var1 ~ ^(.*) (.*)$) {
    set $var2 $1$2; # 操作字串拼接
    rewrite ^ http://website.com/$var2;
}

內容解密：

這段程式碼首先設定變數 $var1 為 “some text”。然後檢查 $var1 是否比對特定模式（即包含空格）。如果比對成功，則將比對到的兩部分拼接起來儲存在變數 $var2 中，並在最後將請求重寫到一個新的 URL。

其他重要指令

uninitialized_variable_warn 指令和 rewrite_log 指令

uninitialized_variable_warn：當設為 on 時，NGINX 會在日誌中發出未初始化變數使用時發出警告資訊。

uninitialized_variable_warn on;

rewrite_log：當設為 on 時，NGINX 會在每次重寫操作時發出日誌資訊。

rewrite_log off;

實際應用案例

以下是一些實際應用中的常見案例：

搜尋功能

許多網站都有搜尋功能，可以根據關鍵字來展示搜尋結果頁面。例如：

輸入 URI：http://website.com/search/some-search-keywords
重寫後 URI：http://website.com/search.php?q=some-search-keywords
重寫規則： rewrite ^/search/(.*)$ /search.php?q=$1?;

使用者個人頁面

許多網站允許使用者註冊並提供個人頁面檢視功能：

輸入 URI：http://website.com/user/31/James
重寫後 URI：http://website.com/user.php?id=31&name=James
重寫規則： rewrite ^/user/([0-9]+)/(.+)$ /user.php?id=$1&name=$2?;

複雜引數處理

有些網站可能使用不同形式來表示引數：

輸入 URI：http://website.com/index.php/param1/param2/param3
重寫後 URI：http://website.com/index.php?p1=param1&p2=param2&p3=param3
重寫規則： rewrite ^/index.php/(.*)/(.*)/(.*)$ /index.php?p1=$1&p2=$2&p3=$3?;

概念圖示

此圖示展示了 NGINX 的各種重寫操作及其流程。

  graph TD;
    A[請求進入] --> B{檢查 break};
    B -- 無 --> C{檢查 redirect};
    C -- 是 --> D[傳回 302/Moved Temporarily];
    C -- 否 --> E{檢查 permanent};
    E -- 是 --> F[傳回 301/Moved Permanently];
    E -- 無 --> G[正常處理];
    B -- 有 --> H[URI 停止修改];

差異化觀點

玄貓認為在實際應用中，選擇適合自己的規則非常重要。不同網站有不同需求和架構，切勿照搬他人的組態，要根據自己的業務邏輯和技術需求進行調整和最佳化。此外，日誌記錄和錯誤排除也是必不可少的一環，確保您瞭解每一次操作背後發生了什麼。

希望這篇文章能幫助您更好地理解和使用 NGINX 的重寫模組。如果您有任何問題或需要更多幫助，歡迎留言討論！

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。

NGINX 模組組態與重寫規則深度解析

NGINX 模組組態探討

內部請求處理

內部重新導向

子請求

error_page 指令

實際範例

rewrite 指令

實際範例

日誌記錄

小段落標題

NGINX Rewrite 模組的探討

無限迴圈的風險

內容解密：

條件結構與指令

內容解密：

位置區塊與 if 區塊的差異

內容解密：

指令詳細說明

內容解密：

流程圖示

內容解密：

NGINX 重寫模組深度探討與應用案例

重寫指令與其應用

常見重寫指令

執行範例

內容解密：

break 指令和 return 指令

break 指令

內容解密：

return 指令

內容解密：

set 指令和變數操作

set 指令

內容解密：

其他重要指令

uninitialized_variable_warn 指令和 rewrite_log 指令

實際應用案例

搜尋功能

使用者個人頁面

複雜引數處理

概念圖示

差異化觀點

玄貓

`error_page` 指令

`rewrite` 指令