SafeUpgrade クイックスタート

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

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

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

サイトの表示の確認

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

PHPのエラーの確認

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

仮想マシンにログイン

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

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

仮想マシンにログインできたら、現在のPHPのバージョンを確認しましょう。
設定には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 をそれぞれで使用しています。また、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を使用しています。このPHPのバージョンをアップデートします。

残りの構成の確認

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

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

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

8	.	3	.	30
メジャーバージョン		マイナーバージョン		リリースバージョン

リリースバージョン (例えば 8.3.31) はバグ修正やセキュリティ修正のみのため、アップデートによる非互換が発生しにくくなります。
しかし、マイナーバージョンのアップデートでは機能追加や下位互換性のない変更が含まれるため、非互換が発生する可能性があります。

PHPは毎年11月頃に新しい マイナーバージョン (例えば 8.4) がリリースされます。
それと合わせて古いマイナーバージョンのサポートが終了されます。そのため、現在のバージョンのサポートが終了する前に、継続してセキュリティ修正が行わているサポートされたマイナーバージョンへのアップグレードが必要となります。

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

# kusanagi php --help

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

# kusanagi php --help

(途中省略)

  --staging {php82,php83,php84,php85,latest}
                        select PHP version for staging

(途中省略)

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

SafeUpgradeへの切り替え

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

# kusanagi php --staging php84 --staging-days 7

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

# kusanagi php --staging php84 --staging-days 7

(途中省略)

php 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 : nginx129@staging ***
● nginx129@staging.service - The NGINX HTTP and reverse proxy server (staging)
     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

*** (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.29 をステージングに使用しています。

PHPの構成の確認

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

*** (active) php : php84-fpm@staging ***
● php84-fpm@staging.service - The PHP 8.4 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php84-fpm@.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 12:19:02 JST; 4s ago

*** (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 12:19:02 JST; 4s ago

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

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

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つまで指定できます。

マニュアルでの表示確認

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

X-Staging: on

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

X-Production: on

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ステータスを取得

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

# 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 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)

Nginx 1.29 のステージング環境がないことが確認できます。

PHPの構成の確認

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

*** (active) php : php84-fpm ***
● php84-fpm - The PHP 8.4 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php84-fpm.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-04-08 12:19:02 JST; 4s ago

*** (inactive) php : php83-fpm ***
○ php83-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php83-fpm.service; disabled; preset: disabled)
     Active: inactive (dead)

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

SafeUpgradeを中断する

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

# kusanagi php --nostaging

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

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