Stories

Detail Return Return

藍易雲cdn:ubuntu編譯安裝nginx及安裝nginx_upstream_check_module模塊 - Stories Detail

下面給出一份Ubuntu 編譯安裝 NGINX 並集成 nginx_upstream_check_module 的標準作業單（SOP）。目標是：最少步驟拿到可用的主動健康檢查，並給出可複用的配置與驗證方法。為避免踩坑，我同時給出兩條路徑：

  • 路徑A：原生 NGINX + 第三方 check 模塊（需打補丁）；
  • 路徑B：Tengine（內建健康檢查，維護成本更低）。
    兩條路線均是當前社區主流實踐，差異與取捨見文末表格。<span style="color:red">重點步驟已用紅色標註</span>。🔥

一、準備環境（Ubuntu 22.04/24.04 適用）

sudo apt update
sudo apt install -y build-essential gcc make git wget curl \
  libpcre3 libpcre3-dev zlib1g-dev libssl-dev \
  libgd-dev uuid-dev

解釋：安裝編譯鏈與 NGINX 依賴；libpcre/zlib/openssl 為 NGINX 常規必需，libgd/uuid 供部分可選模塊使用。

二、路徑A：原生 NGINX + nginx_upstream_check_module（打補丁方式）

該模塊由 yaoweibin 維護，需要對 NGINX 源碼應用對應版本的 patch，然後以 --add-module 方式編譯集成。官方文檔明確説明了需要按 NGINX 版本匹配不同補丁（例如 check_1.7.2+.patch 等）。(GitHub)

1）獲取源碼與模塊

# 選擇一個與補丁相匹配的 NGINX 版本（示例以 1.24.x/1.26.x 為思路，務必對照模塊倉庫的 patch 目錄選擇）
cd /usr/local/src
wget http://nginx.org/download/nginx-1.24.0.tar.gz
tar -xzf nginx-1.24.0.tar.gz
git clone https://github.com/yaoweibin/nginx_upstream_check_module.git

解釋：下載 NGINX 源碼與健康檢查模塊源碼。關鍵點：<span style="color:red">NGINX 版本需與模塊倉庫中提供的補丁版本匹配</span>，否則可能打補丁失敗或運行異常。(GitHub)

2）應用補丁

cd /usr/local/src/nginx-1.24.0
# 示例：若倉庫提供了適配 1.24.x 的補丁文件名（以實際為準）
patch -p1 < ../nginx_upstream_check_module/check_1.7.2+.patch

解釋：將模塊補丁打進 NGINX 的 upstream 相關代碼。不同 NGINX 版本對應不同 patch 名稱（倉庫 README 已列舉多版 patch 的命名規則與適配範圍）。<span style="color:red">不匹配會失敗</span>。(GitHub)

3）配置與編譯安裝

# 僅示例常用開關，請按需增減
./configure \
  --prefix=/usr/local/nginx \
  --sbin-path=/usr/sbin/nginx \
  --conf-path=/etc/nginx/nginx.conf \
  --pid-path=/var/run/nginx.pid \
  --with-http_ssl_module \
  --with-http_gzip_static_module \
  --with-http_stub_status_module \
  --with-pcre \
  --with-threads \
  --add-module=../nginx_upstream_check_module

make -j"$(nproc)"
sudo make install

解釋：--add-module 將第三方模塊編入；其餘參數是常見生產選項。編譯完成後，二進制位於 /usr/sbin/nginx。

4）systemd 服務文件（便於運維）

sudo tee /etc/systemd/system/nginx.service >/dev/null <<'EOF'
[Unit]
Description=NGINX with upstream_check
After=network.target

[Service]
Type=forking
PIDFile=/var/run/nginx.pid
ExecStart=/usr/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/sbin/nginx -s reload
ExecStop=/usr/sbin/nginx -s quit
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now nginx

解釋：將源碼安裝的 NGINX 納入 systemd 管理，方便啓停與開機自啓。

5）驗證模塊已生效

nginx -V 2>&1 | tr ' ' '\n' | grep -i upstream_check || true

解釋：查看編譯參數中是否包含 nginx_upstream_check_module，以確認編譯集成成功。

三、路徑B：直接使用 Tengine（內建健康檢查）

Tengine 是基於 NGINX 的發行版，內置 ngx_http_upstream_check_module。新版 Changelog 仍在修復該模塊相關問題，維護活躍、集成度更高。編譯時打開 --with-http_upstream_check_module 即可，無需額外打 patch。(The Tengine Web Server)

編譯示例：

cd /usr/local/src
wget https://tengine.taobao.org/download/tengine-2.4.0.tar.gz
tar -xzf tengine-2.4.0.tar.gz
cd tengine-2.4.0

./configure \
  --prefix=/usr/local/nginx \
  --sbin-path=/usr/sbin/nginx \
  --conf-path=/etc/nginx/nginx.conf \
  --pid-path=/var/run/nginx.pid \
  --with-http_ssl_module \
  --with-http_gzip_static_module \
  --with-http_stub_status_module \
  --with-pcre \
  --with-threads \
  --with-http_upstream_check_module

make -j"$(nproc)"
sudo make install

解釋：相比路徑A，這裏不需要手工打補丁，維護風險更低，功能直接內置。(The Tengine Web Server)

四、健康檢查配置範例（兩條路徑通用）

# /etc/nginx/nginx.conf 片段
http {
  upstream app_backend {
    server 10.0.0.11:8080 weight=2;
    server 10.0.0.12:8080;
    # 主動健康檢查（間隔/判定閾值/超時/類型）
    check interval=3000 rise=2 fall=3 timeout=2000 type=http;
    # 自定義探活報文與判活標準（可選）
    check_http_send "GET /healthz HTTP/1.1\r\nHost: example\r\nConnection: close\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
  }

  server {
    listen 80;
    location / {
      proxy_pass http://app_backend;
      proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
    }
    # 可視化查看探活結果（支持 html/csv/json）
    location /up_status {
      check_status json;
      allow 127.0.0.1;
      deny all;
    }
  }
}

解釋：

  • check：<span style="color:red">主動健康檢查</span>，interval（毫秒）為探活週期；rise/fall 控制上/下線閾值；type 選擇探活協議（http/tcp/ssl_hello/fastcgi…）。
  • check_http_send/expect_alive：自定義 HTTP 探活請求與認為“存活”的狀態碼集合。
  • check_status：提供探活狀態頁，可輸出 html/csv/json，便於監控採集。以上指令均來自模塊 README 的指令集説明。(GitHub)

五、驗證與回滾

# 1) 語法檢查
sudo nginx -t

# 2) 平滑重載
sudo systemctl reload nginx

# 3) 本地校驗 upstream 探活狀態（示例 JSON 輸出）
curl -s http://127.0.0.1/up_status?format=json | jq .

解釋：nginx -t 先行兜底；reload 無縫應用配置；/up_status 用於確認每台後端的 up/down 與 rise/fall 計數是否按預期變化。若上線異常，<span style="color:red">立即回滾</span>上一版配置文件並 reload。

六、能力邊界與替代方案（務實提醒）

  • 原生 NGINX 的官方主動健康檢查在 NGINX Plus 中提供（health_check 指令）；開源版沒有官方同等功能，需要第三方模塊或 OpenResty 方案。(nginx.org)
  • OpenResty 可用 lua-resty-upstream-healthcheck 實現探活，靈活度高，無需給 NGINX 打底層補丁，但實現成本略高。(GitHub)
  • 運營角度：<span style="color:red">追求長期穩定與低維護</span>，優先 Tengine 或 OpenResty；<span style="color:red">追求最小改動</span>，走路徑A，但需嚴控 NGINX 版本與補丁適配。

七、工作流程（Mermaid）

flowchart TD
A[選擇路線] -->|低維護| B[Tengine 構建]
A -->|原生 NGINX| C[獲取源碼與模塊]
C --> D[匹配並應用補丁]
D --> E[./configure --add-module]
E --> F[make && make install]
B --> G[寫配置 check+status]
F --> G
G --> H[nginx -t && reload]
H --> I{探活結果是否符合預期?}
I -- 否 --> J[回滾配置/檢查補丁與版本匹配]
I -- 是 --> K[接入監控/上線]

八、方案對比表（WordPress 經典編輯器可用）

選項 集成方式 運維複雜度 功能完備度 版本適配風險 適用場景
原生 NGINX + check 模塊 <span style="color:red">打補丁 + add-module</span> 中等 主動探活、狀態頁 <span style="color:red">中-高</span>（需跟隨 NGINX 版本） 已有 NGINX 源碼編譯鏈，能接受補丁維護
Tengine --with-http_upstream_check_module <span style="color:red">低</span> 主動探活、持續維護 低 追求穩定、少改造的生產環境
OpenResty Lua 庫實現 中-高 高度靈活 中 需要定製探活邏輯/配合業務自定義

九、風控清單 ✅

  • <span style="color:red">嚴格匹配補丁與 NGINX 版本</span>；打補丁失敗或警告不可忽視。(GitHub)
  • 首次上線將 rise/fall 設置更保守（如 rise=2, fall=5），避免抖動誤判。
  • check_status 暴露在內網或受控 IP，避免泄露拓撲與健康信息。
  • 與 proxy_next_upstream 策略配合，確保請求在後端抖動期仍可回退至健康節點。
  • 將 /up_status 接入監控（Prom/自研採集），做 SLO 看板 與告警分層。

十、收尾

這套 SOP 走完，你就擁有了可觀測、可回滾、可持續維護的 NGINX 主動健康檢查能力。要快，選 Tengine；要原生，選打補丁；要擴展，選 OpenResty。架構路線沒有唯一正確答案，<span style="color:red">關鍵是把複雜度留在可控邊界內</span>。😉

參考事實：

  • nginx_upstream_check_module 為第三方模塊，需按版本補丁集成；提供 check/check_status 等指令。(GitHub)
  • Tengine 內建同名模塊，配置開關即可啓用，近期仍有相關修復記錄。(The Tengine Web Server)
  • 官方主動健康檢查（health_check）為 NGINX Plus 功能；開源版需第三方或 Lua 方案。(nginx.org)
微服務 , Ubuntu , Nginx , Debian , 服務器
user avatar jfren Avatar junxiudedoujiang Avatar leguandepaiqiu_buelwl Avatar xiaoyi_ces Avatar
Favorites 4 users favorite the story!
Favorites

Add a new Comments

Some HTML is okay.