Nginx配置文件結構

nginx配置文件由指令（directive）組成，指令分為兩種形式，簡單指令和區塊指令。

一條簡單指令由指令名、參數和結尾的分號（;）組成，例如： listen 80 backlog 4096; ，其中“listen”是指令名，“80”、“backlog”、“4096”都是參數，“;”表示指令結尾。

區塊指令由指令名、參數和花括號（{}）組成，例如： location /imag {} ，其中“location”是指令名，“/imag”是參數，“{}”用於包括其它指令和表示結尾。如果一個區塊指令中的大括號可以包括其它簡單指令或區塊指令，那麽這種區塊指令稱為“語境（context）

不被任何其它區塊指令包含的指令被認為處於main語境中，即main語境是nginx配置文件中最外層語境，任何指令都位於main語境或main語境的子級語境中。請看下面的配置文件例子：

 1 # nginx.conf
 2 worker_processes 2;
 3 events {
 4     use epoll;
 5     worker_connections 1024;
 6 }
 7 http {
 8     include       mime.types;
 9     upstream server_group_a {   
 
10       server 192.168.1.1:8080;
11       server 192.168.1.2:8080;
12     }
13     server {
14         listen       80;
15         server_name  www.example.com;   
16         location / {
17            proxy_pass  http://server_group_a;        
18         } 
19     }
20 }

上例中，worker_processes、event、http指令處於main語境中，use、worker_connections指令位於event語境中，include、upstream、server指令位於http語境中，兩條server指令位於upstream語境中……

nginx軟件是由各種不同功能的模塊組成的，因此配置文件也遵照這種模塊化的結構，nginx核心模塊提供一些全局的配置指令，功能配置指令則由其他的功能模塊提供。上例中的worker_processes、event指令都由nginx的核心模塊提供，而http指令由http功能模塊提供，proxy_pass指令則由http模塊的一個子模塊提供。

在安裝nginx時，默認包含了一些常用功能模塊，使用者也可以通過源碼編譯安裝的方式自由選擇安裝其他功能模塊，在配置nginx時可以查找功能模塊的文檔，文檔中會說明這個功能模塊包括哪些指令，以及這些指令應該在哪些語境下配置，而從語境（指令）查找它包含哪些可以配置的指令卻是不靠譜的，因為安裝的模塊不同，包含的指令也不一樣，因此配置nginx需要有一些經驗，初入門者只能先從參考他人的示例著手。

功能模塊除了http外，還有mail（郵件代理）、stream（TCP、UDP代理，v1.9.0以後）這兩個功能模塊。

全局配置指令

• 語法：include file | mask;
• 默認值：無
• 語境：任意

可在任意語境中使用，將其他配置文件中的指令引入到使用include指令的語境中。被引入的指令需要符合語法和引入的語境要求。舉例：

http {
    include mime.types;
    include vhosts/*.conf;
}

將mime.types和vhosts目錄下以“.conf”結尾的文件引入到http語境中。

• 語法：deamon on | off;
• 默認值：deamon on
• 語境：main

指定nginx是否以守護進程運行。

• 語法：debug_points abort | stop;
• 默認值：無
• 語境：main

用於debug，判斷nginx內部錯誤，特別是判斷工作中進程的socket溢出問題。nginx代碼中包含了一些調試點，如果debug_points設置為abord，當運行到調試點時會產生一個核心運行信息dump文件，當設置為stop時會停止進程。

• 語法：error_log file [level]
• 默認值：error_log logs/error.log error;
• 語境：main, http, mail(v1.9.0後), stream(v1.7.11後), server, location

指定日誌文件和日誌級別。

file可以是指定的文件，也可以是標準錯誤輸出文件stderr、syslog服務器或內存。輸出到syslog服務器使用“syslog:”前綴，輸出到循環內存緩沖區使用“memory:”前綴和緩沖區大小。

level參數指定輸出日誌的級別，高於指定級別的日誌將被輸出。支持的級別從低到高依次有：debug、info、notice、warn、error、crit、alert、emerg。

指定debug級別需要編譯時安裝了debug模塊。

• 語法：env variable[=value];
• 默認值：env TZ;
• 語境：main

默認情況下，nginx只會繼承TZ這個環境變量，這條指令可以將環境變量傳遞到nginx進程中，也可以定義新的變量傳遞到nginx進程中。

• 語法：load_module file;
• 默認值：無
• 語境：main

載入動態模塊。例如：

load_module module/ngx_mail_module.so;

• 語法：lock_file file;
• 默認值：lock_file logs/nginx.lock;
• 語境：main

nginx使用鎖的機制來實現accept_mutex功能和共享內存，大多數操作系統中鎖都是一個原子操作，這種情況下這條指令無效，還有一些操作系統中使用“鎖文件”的的機制來實現鎖，此命令用來指定鎖文件前綴名。

• 語法：master_process on | off;
• 默認值：master_process on;
• 語境：main

是否啟用worker進程，如果設置為off，則不啟用worker進程，由master進程處理請求。

• 語法：pcre_jit on | off;
• 默認值：pcre_jit off;
• 語境：main

在解析配置文件時對正則表達式啟用或禁用實時編譯（PCRE JIT）。

RCRE JIT能顯著提升正則表達式的處理速度。

JIT依賴PCRE庫8.20以後版本，並且在編譯時需要指定--enable-jit參數。也可以將PCRE庫作為nginx的模塊編譯安裝（編譯nginx指定--with-pcre=參數），並在編譯時指定--with-pcre-jit參數啟用JIT功能。

• 語法：pid file;
• 默認值：pid nginx.pid;
• 語境：main

指定pid文件。pid文件存放了master進程的進程號。

語法：ssl_engine device;

默認值：無

語境：main

如果使用了硬件ssl加速設備，使用此指令指定。

• 語法：thread_pool name threads=number [max_queue=number];
• 默認值：thread_pool default threads=32 max_queue=65535;
• 語境：main

在使用異步IO的情況下，定義命名線程池，並設置線程池大小和等待隊列大小。當線程池中所有線程都繁忙時，新任務會放在等待隊列中，如果等待隊列滿了，任務會報錯退出。

命名線程池可以定義多個，供http模塊的異步線程指令（aio）調用。

此指令在v1.7.11中出現。

• 語法：timer_resolution interval;
• 默認值：無
• 語境：main

設置時間精度，減少worker進程調用系統時間函數的次數。默認情況下，每個核心事件都會調用gettimeofday()接口來獲得系統時間，以便nginx計算連接超時等工作，此指令指定更新時間的間隔，nginx在間隔時間內只調用一次系統時間函數。

• 語法：user user [group];
• 默認值：user nobody nodoby;
• 語境：main

指定master啟動worker進程使用的linux用戶和組。如果組（group）沒有指定，那麽會默認用一個和user同名的組名。

• 語法：worker_processes number | auto
• 默認值：worker_processes 1
• 語境：main

指定worker進程的數量。進程數最好是CPU核心數或CPU核心數的倍數。當設置為auto時，nginx會嘗試自動獲取CPU核心數並設置。

auto參數從v1.3.8和v1.2.5版本以後支持。

• 語法：worker_cpu_affinity cpumask ...;
• 　　　worker_cpu_affinity auto [cpumask];
• 默認值：無
• 語境：main

將worker進程綁定到CPU核心，每個worker進程對應一個二進制掩碼，掩碼的每一位對應一個CPU。默認情況下，worker不與cpu核心綁定。此指令只適用於Linux和FreeBSD。

舉例：

worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

表示有4個worker進程，第一個綁定到CPU0，第二個綁定到CPU1，以此類推，4個進程分別綁定一個CPU核心。

再例：

worker_processes 2;
worker_cpu_affinity 0101 0101;

表示將第一個進程綁定到CPU0/CPU2，第二個worker進程綁定到CPU1/CPU3，這個例子適用於超線程場景，即一個核心虛擬出兩個CPU線程。

值auto（v1.9.10）允許自動和可用的CPU綁定：

worker_process auto;
worker_cpu_affinity auto;

掩碼（mask）可用用於限制某些CPU參加綁定。例如：

worker_cpu_affinity auto 01010101;

只有CPU0/2/4/6參與綁定，其他的CPU不分配worker進程。

• 語法：worker_rlimit_core size;
• 默認值：無
• 語境：main

為worker進程修改系統核心轉儲文件（core file）的大小限制。通常提升這個值不需要重啟主進程。

• 語法：worker_rlimit_nofile number;
• 默認值：無
• 語境：main

修改worker進程最大可打開句柄數限制。通常提升這個值不需要重啟主進程。

• 語法：worker_shutdown_timeout time;
• 默認值：無
• 語境：main

此指令在v1.11.11中出現。用於設置安全地結束一個worker進程的超時時間。

當安全結束一個worker進程時，會停止對worker進程分配新連接，並等待他處理完當前的任務後再退出，如果設置了超時時間，超時後nginx會強制關閉worker進程的連接。

• 語法：working_directory directory;
• 默認值：無
• 語境：main

指定默認工作路徑。主要用於worker進程導出內存轉儲文件，為worker進程指定的用戶需要有改文件的寫入權限。

連接處理控制指令

• 語法：events { ... }
• 默認值：無
• 語境：main

作用只是開辟一個指令區塊，events語境中配置的指令用於控制連接處理行為。

• 語法：accept_mutex on | off;
• 默認值：accept_mutex off;
• 語境：events

當啟用這個參數時，會使用互斥鎖交替給worker進程分配新連接，否則話所有worker進程會爭搶新連接，即或造成所謂的“驚群問題”，驚群問題會使nginx的空閑worker進程無法進入休眠狀態，造成系統資源占用過多。啟用此參數會一定程度上導致後臺服務器負載不均衡，但是在高並發的情況下，關閉此參數可以提高nginx的吞吐量。

在支持epoll的操作系統上不需要啟用accept_mutex（v1.11.3後），使用了reuseport功能也不需要啟用（v1.9.1後，需要操作系統支持SO_REUSEPORT socket選項，Linux 3.9+）。

在v1.11.3以前版本中，默認值為on。

• 語法：accept_mutex_delay time;
• 默認值：accept_mutex_delay 500ms;
• 語境：events

如果accept_mutex參數啟用，當一個空閑worker進程嘗試獲取互斥鎖時發現有另一個worker進程已經獲得互斥鎖並處理新連接，這個空閑的worker進程等待下一次獲取互斥鎖嘗試的時間。而獲得互斥鎖的進程在處理完當前連接後，會立即嘗試獲取互斥鎖，因此此數值較大或連接壓力較小時，會造成部分worker進程總是空閑，一部分進程總是繁忙的情況。

• 語法：debug_connection address | network | unix:;
• 默認值：無
• 語境：events

需要debug模塊支持，需確認安裝時包括了debug模塊，可以使用nginx -V命令確定包含--wih-debug參數。

對特定的客戶發起的連接開啟debugging級別日誌，用於分析和拍錯。可以指定IPv4或者IPv6地址（v1.3.0,v1.2.1）或一個無類網段或域名，或UNIX socket（v1.3.0,v1.2.1）。例如：

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.168.2.0/24;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
}

非指定連接的日誌級別依然由error_log指令決定。

• 語法：multi_accept on | off;
• 默認值：multi_accept off;
• 語境：events

當設置為off時，一個worker進程獲得互斥鎖時一次只處理一個新連接，如果設置為on，則一次性將所有新連接都分配給獲得當前互斥鎖的worker進程、當使用kqueue連接處理方式時（use kqueue），此項指令無效。

• 語法：use method;
• 默認值：無
• 語境：events

指定連接處理方式，通常不需要指定，nginx會自動使用最有效的方式。

連接處理方式用於決定用什麽方法從當前的連接池中找出哪些連接已經準備好傳輸/接收數據。常見的連接處理方式有：

select（需要select模塊）、poll（需要poll模塊）、kqueue（macOS/FreeBSD 4.1+/OpenBSD 2.9+）、epoll（Linux 2.6+）、/dev/poll（Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+）、eventport（Solaris 10+）

• 語法：worker_aio_requests number;
• 默認值：worker_aio_requests 32;
• 語境：events

在v1.1.4和1.0.7中出現。當啟用aio（異步IO）和epoll連接處理方式後，單個worker進程最大的未完成異步IO操作數。

• 語法：worker_connections number;
• 默認值：worker_connections 512;
• 語境：events

單個worker進程可處理的最大並發連接數限制。

這個連接數包括和後臺服務器之間的連接在內的所有的連接，而不僅是與客戶的連接。所有worker進程的總連接數（即worker_connections × worker_processes ）不能超過操作系統最大可打開句柄數的限制（nofile），nofile限制可以通過worker_rlimit_nofile指令修改。

如果覺得本文對您有幫助，請掃描後面的二維碼給予捐贈，您的支持是作者繼續寫出更好文章的動力！

Nginx實用教程（二）：配置文件入門