Nginx SafeUpgrade クイックスタート

バージョンアップを安全に実施しよう

バージョンアップのような大規模更新は、ダウンタイムや不具合のリスクが大きく、計画的な対応が求められます。
SafeUpgradeでは、新旧バージョンを同一環境で並行稼働させることで、互換性や安定性を事前に確認。
安全性を確保したうえで切り替えを行うため、サービスを止めることなく大規模アップデートを実現します。
ここでは、KUSANAGI Security EditionのSafeUpgradeでNginxのバージョンをアップグレードする手順を説明します。

KUSANAGI Security Editionをセットアップするまでの手順は KUSANAGI Security Editionクイックスタート を参照してください。

サイトの表示の確認

アップグレードを行う前に、現在のサイトで表示くずれなどが発生していないかどうかを確認しておきます。
サイトの全てのページで確認を行うのは難しいので、いくつか代表的なページを選択して確認するとよいでしょう。

Nginxのエラーの確認

アップグレードを行う前から現在のサイトでNginxのエラーが発生していると、そのエラーがアップグレードに起因するものかどうかの判断ができません。
そのため、現在のサイトでといったNginxのエラー (HTTP 500 Internal Server Errorなど) が発生していないことを確認しておいてください。

仮想マシンにログイン

まずは、仮想マシンにログインしてください。
クライアントがLinuxであればsshコマンドを利用してログインしてください。
クライアントがWindowsであれば以下のリンクを参照してください。
WindowsでKUSANAGI 9にsshでログイン - KUSANAGI

現在のNginxのバージョンの確認

仮想マシンにログインできたら、現在のNginxのバージョンを確認しましょう。
設定にはSecurity Editionの「KUSANAGIコマンド」を使用します。
従来の「KUSANAGIコマンド」に加えて、セキュリティ運用のためのコマンドが追加されています。
「KUSANAGIコマンド」については以下のリンクに一覧があります。
KUSANAGI 9コマンド - KUSANAGI
Security Editionコマンド - KUSANAGI

仮想マシンにログインしたユーザーが root ユーザではない場合は、 以下のように入力して root ユーザーへ切り替えてください。
仮想マシンにログインしたユーザーが root ユーザである場合は、この手順は不要です。

# sudo su -

ステータスを取得

ステータスの取得には以下のコマンドを用います。

# kusanagi status

次のように「status completed.」というメッセージが表示され、現在のミドルウェアの種類やバージョンが得られます。
なお、種類やバージョンについてはお使いの環境によっては異なる場合がありますので、適宜読み替えてください。

# kusanagi status

(途中省略)

status completed.

続いて、ステータスの内容を確認していきます。

KUSANAGIのバージョンとプラットフォームの確認

最初にKUSANAGIの「バージョン」「プラットフォーム」「ベースのOS」が出力されます。

KUSANAGI Version 10.3.12-1.el9
azure-security
AlmaLinux 9

KUSANAGIの「バージョン」が10.3.12-1.el9、「プラットフォーム」がAzureで稼動するSecurity Edition、「ベースのOS」がAlmaLinux 9であることが分かります。

Webサーバ構成の確認

次に現在のWebサーバ構成が出力されます。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) nginx : nginx129@proxy ***
● nginx129@proxy.service - The NGINX HTTP and reverse proxy server (proxy)
     Loaded: loaded (/usr/lib/systemd/system/nginx129@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:14:03 JST; 1h 9min ago

*** (active) nginx : nginx129@production ***
● nginx129@production.service - The NGINX HTTP and reverse proxy server (production)
     Loaded: loaded (/usr/lib/systemd/system/nginx129@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:14:02 JST; 1h 9min ago

*** (inactive) httpd : httpd24 ***
○ httpd24.service - The Apache HTTP Server
     Loaded: loaded (/usr/lib/systemd/system/httpd24.service; disabled; preset: disabled)
     Active: inactive (dead)

1. nginxリバースプロキシ + nginxモード で Nginx 1.29 をそれぞれで使用しています。このNginxのバージョンをアップデートします。また、Apache HTTP Serverは使用していません。
Webサーバ構成の違いについては KUSANAGI Security EditionのWebサーバ構成 を参照してください。

SafeUpgradeを行うにはWebサーバ構成が 1. nginxリバースプロキシ + nginxモード である必要があります。
上記のような出力ではない場合は、1. nginxリバースプロキシ + nginxモード の構成に切り替えてください。
切り替えには以下のコマンドを用います。既に 1. nginxリバースプロキシ + nginxモード の場合は、この手順は不要です。

# kusanagi nginx

次のように「nginx completed.」というメッセージが出力されたら、再度ステータスを取得して、Webサーバ構成を確認してください。

# kusanagi nginx

(途中省略)

nginx completed.

PHPの構成の確認

続いて、PHPの構成が出力されます。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) php : php83-fpm ***
● php83-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php83-fpm.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:07:57 JST; 1h 15min ago

現在はPHP 8.3を使用しています。

残りの構成の確認

続いて、データベースのバージョンやPythonのバージョンなどの情報が出力されますが、ここでは割愛します。

新しいNginxのバージョンの確認

アップグレード先として利用できるNginxのバージョンを確認します。
Nginxのバージョンは次のような形式を取ります。

1	.	30	.	0
1番目のバージョン		2番目のバージョン		3番目バージョン

3番目のバージョン (例えば 1.30.1) はバグ修正やセキュリティ修正のみのため、アップデートによる非互換が発生しにくくなります。
しかし、2番目のバージョンのアップデートでは機能追加や下位互換性のない変更が含まれるため、非互換が発生する可能性があります。
また、Nginxでは2番目のバージョンが奇数のもの (1.29、1.31など) を「メインライン版」、偶数のもの (1.28、1.30など) を「安定版」と呼んでいます。同じメインライン版や安定版であっても、2番目のバージョンが変わる場合は、非互換が発生する可能性があります。

Nginxは毎年5月頃に新しい安定版とメインライン版がリリースされます。それまでのメインライン版 (例えば 1.29) が新しい安定版 (1.30) としてリリースされ、新たなメインライン版 (1.31) がリリースされます。
それと合わせて古い安定版・メインライン版のサポートが終了されます。そのため、新しい安定版・メインライン版がリリースされた際には、速やかに次の安定版・メインライン版へのアップグレードが必要となります。

KUSANAGIで利用できるNginxのバージョンを確認するには、以下のコマンドを使用します。

# kusanagi proxy --help

次のように利用できるPHPのバージョンが出力されます。

# kusanagi proxy --help

(途中省略)

  --staging {nginx128,nginx129,nginx130,nginx131,latest}
                        select NGINX version for staging

(途中省略)

Nginx 1.28、1.29、1.30、1.31が利用できることが分かります。
なお、バージョンについては毎年更新されていくため、適宜読み替えてください。

SafeUpgradeへの切り替え

ここでは次のメインライン版である 1.31 へのアップグレードを行います。
NginxのSafeUpgradeを行うために、Webサーバ構成を 3. nginxリバースプロキシ + 運用nginx + 検証nginxモード に切り替えます。
切り替えには以下のコマンドを用います。
例として、ステージングの期間を7日としています。

# kusanagi proxy --staging nginx131 --staging-days 7

次のように「proxy completed.」というメッセージが出力されれば、切り替えは完了です。

# kusanagi proxy --staging nginx131 --staging-days 7

(途中省略)

proxy completed.

ステータスを取得

あらためて、切り替えた後のステータスを取得します。
ステータスの取得には以下のコマンドを用います。

# kusanagi status

次のように「status completed.」というメッセージが表示され、現在のミドルウェアの種類やバージョンが得られます。
なお、種類やバージョンについてはお使いの環境によっては異なる場合がありますので、適宜読み替えてください。

# kusanagi status

(途中省略)

status completed.

Webサーバ構成の確認

Webサーバ構成の出力を確認します。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) nginx : nginx129@proxy ***
● nginx129@proxy.service - The NGINX HTTP and reverse proxy server (proxy)
     Loaded: loaded (/usr/lib/systemd/system/nginx129@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 12:19:02 JST; 4s ago

*** (active) nginx : nginx129@production ***
● nginx129@production.service - The NGINX HTTP and reverse proxy server (production)
     Loaded: loaded (/usr/lib/systemd/system/nginx129@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:14:02 JST; 2h 5min ago

*** (active) nginx : nginx131@staging ***
● nginx131@staging.service - The NGINX HTTP and reverse proxy server (staging)
     Loaded: loaded (/usr/lib/systemd/system/nginx131@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 12:19:02 JST; 4s ago

*** (inactive) httpd : httpd24 ***
○ httpd24.service - The Apache HTTP Server
     Loaded: loaded (/usr/lib/systemd/system/httpd24.service; disabled; preset: disabled)
     Active: inactive (dead)

新しく Nginx 1.31 をステージングに使用しています。

PHPの構成の確認

PHPの構成の出力を確認します。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) php : php83-fpm ***
● php83-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php83-fpm.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:07:57 JST; 1h 15min ago

引き続き PHP 8.3 を使用しています。

新しいNginxのバージョンでの検証

KUSANAGI Appの表示差異テストに登録

KUSANAGI Appにいくつか代表的なページを登録することで、自動的にページの表示くずれを検証することができます。
検証の結果、表示くずれなどが確認されると、SafeUpgradeを中止して、もとのPHPバージョンに切り戻します。
KUSANAGI Appにに仮想マシンを登録するまでの手順は KUSANAGI Security Editionクイックスタート を参照してください。

表示差異テストの設定ページに登録

左メニューより表示差異テストを選択します。
そして、KUSANAGI Appに登録した仮想マシンの「設定ページへ」を選択します。

共通実行時間設定

表示差異テストは、1日1回、ここで指定した時間内に行われます。負荷が高い時間帯や、メンテナンスを行う時間帯がある場合は、それを避けるように時間帯を設定してください。

テスト対象のURLの登録

「+ URLグループを追加」を選択します。
対象URLに、スクリーンショットを取得して表示差異の比較を行う対象となるページのURLを指定します。
除外エリアには、スクリーンショットで比較を行う際に除外するCSSクラス名やID名を指定します。広告の画像や、リコメント・トレンドを表示するエリアなど、アクセスのたびに内容が変わるエリアを指定してください。
スクリーンショットの取得はデスクトップブラウザとモバイルブラウザの2種類で行います。

テスト対象のURLは、1つの仮想マシンにつき最大5つまで指定できます。

マニュアルでの表示確認

マニュアルで新しいNginxのバージョンを使用したページを確認することもできます。
WordPressの管理画面での表示のように、ログインした状態が必要となるなど、自動的な表示差異テストが難しいページをテストするにはこの手順を用います。
ブラウザで以下のHTTPヘッダを設定してください。

X-Staging: on

HTTPヘッダを設定してサイトにアクセスすると、新しいNginxのバージョンを使用して表示します。
なお、以下のHTTPヘッダを設定すると、元のPHPバージョンを使用して表示します。

X-Production: on

いずれのHTTPヘッダも設定されていない場合は、5:1の重み付けで元のNginxのバージョンと、新しいNginxのバージョンでロードバランスします。

WordPressの管理画面上で、新しいNginxのバージョンを利用してログインしている場合には、以下のように「KUSANAGIのStaging環境にアクセスしています。」とツールバーに表示されます。
なお、ステージング環境は本番環境のWordPressは運用とデータベースを共用しています。検証で加えた変更は本番にも適用されますので注意してください。

元のNginxのバージョンへの自動切り戻し

KUSANAGI Appの表示差異テストで差異がある場合

ステージング期間の間に、KUSANAGI Appに登録したページにおいて表示差異テストで差異が確認されると、新しいNginxのバージョンによるステージングを終了して、元のNginxのバージョンに自動的に切り戻します。
元のNginxのバージョンで動作しているかどうかはステータスより確認できます。
切り戻した場合は、SafeUpgradeを実行する前のWebサーバ構成に戻ります。

表示差異テストの差異はKUSANAGI Appから確認できます。

表示差異テストの結果を確認する

左メニューより表示差異テストを選択します。
そして、KUSANAGI Appに登録した仮想マシンの「結果ページへ」を選択します。

登録したテスト対象のURLごとに、比較、ステータス、差分率を確認できます。差分率が10%以上の場合にはエラーとなります。

「比較」を選択して、デスクトップとモバイルのそれぞれのスクリーンショットを比較することができます。

差分が出ているブロックには赤枠が示されます。真ん中のハンドルを動かすことで運用のNginxの出力結果と、検証のNginxの出力結果を比較できます。右が運用のNginxの出力結果、左が検証のNginxの出力結果になります。

Nginxのエラーを検知した場合

ステージング期間の間にNginxでエラー (HTTP 500 Internal Server Error) を検知すると、新しいNginxのバージョンによるステージングを終了して、元のNginxのバージョンに自動的に切り戻します。
元のNginxのバージョンで動作しているかどうかはステータスより確認できます。
切り戻した場合は、SafeUpgradeを実行する前のWebサーバ構成に戻ります。

新しいNginxのバージョンへの自動切り替え

ステージングの期間の完了までに、KUSANAGI Appに登録したページにおいて表示の差異がなく、Nginxのエラーを検知しなかった場合、ステージング環境を終了して新しいNginxのバージョンを本番環境に自動的に切り替えます。
新しいNginxのバージョンで動作しているかどうかはステータスより確認できます。

ステータスを取得

切り替えた後のステータスを取得します。
ステータスの取得には以下のコマンドを用います。

# kusanagi status

次のように「status completed.」というメッセージが表示され、現在のミドルウェアの種類やバージョンが得られます。
なお、種類やバージョンについてはお使いの環境によっては異なる場合がありますので、適宜読み替えてください。

# kusanagi status

(途中省略)

status completed.

Webサーバ構成の確認

切り替えた後のWebサーバ構成が出力されます。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) nginx : nginx131@proxy ***
● nginx131@proxy.service - The NGINX HTTP and reverse proxy server (proxy)
     Loaded: loaded (/usr/lib/systemd/system/nginx131@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:14:03 JST; 1h 9min ago

*** (active) nginx : nginx131@production ***
● nginx131@production.service - The NGINX HTTP and reverse proxy server (production)
     Loaded: loaded (/usr/lib/systemd/system/nginx131@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:14:02 JST; 1h 9min ago

*** (inactive) nginx : nginx129 ***
○ nginx129.service - The NGINX HTTP and reverse proxy server
     Loaded: loaded (/usr/lib/systemd/system/nginx129.service; enabled; preset: disabled)
     Active: inactive (dead)

*** (inactive) httpd : httpd24 ***
○ httpd24.service - The Apache HTTP Server
     Loaded: loaded (/usr/lib/systemd/system/httpd24.service; disabled; preset: disabled)
     Active: inactive (dead)

Nginx 1.31 を利用していることが確認できます。また、元のバージョンである Nginx 1.29 を使用していないことが分かります。

PHPの構成の確認

PHPの構成の出力を確認します。
「●」は使用しているサービス、「○」は使用していないサービスを示します。

*** (active) php : php83-fpm ***
● php83-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php83-fpm.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 10:07:57 JST; 1h 15min ago

PHP 8.3 を利用していることが確認できます。

SafeUpgradeを中断する

ステージング期間の間に、SafeUpgradeを中断して新しいNginxのバージョンによるステージングを終了して、元のNginxのバージョンに自動的に切り戻すには、以下のコマンドを用います。

# kusanagi proxy --nostaging

元のnginxのバージョンで動作しているかどうかはステータスより確認できます。
切り戻した場合は、SafeUpgradeを実行する前のWebサーバ構成に戻ります。

SafeUpgradeのコマンドをよびオプションをさらに詳しく知りたい方は、以下のページを参照してください。
KUSANAGI 9コマンド - KUSANAGI
Security Editionコマンド - KUSANAGI