Liferay 7.2 から 7.4 へのアップグレード手順とハマりどころ - aegif Labo Blog Liferay
こんにちは。
皆さんがご覧になっているこの LABO BLOG も Liferay で動いています。
ブログ開設時の Liferay CE 7.2 のままとなっていましたが、今回 Liferay CE 7.4 へアップグレードしました。
そこで、アップグレードの実施手順と、作業中につまずいたポイントをご紹介します。
7.2 から 7.4 への移行では、Liferay 本体だけでなく JDK・データベース・Elasticsearch もあわせて見直す必要があり、事前準備が大切でした。
これからアップグレードを検討されている方の参考になれば幸いです。
今回の環境
LABO BLOG は AWS 上で、次の構成で動いています。
- Amazon EC2（Amazon Linux 2）：Liferay（Tomcat バンドル）と Elasticsearch を同じインスタンスで動かしています。
- Amazon Aurora（MySQL 互換）：Liferay のデータベースです。
- Amazon S3：ドキュメントライブラリのファイルの保存先です。
アップグレード前後のバージョンは次のとおりです。
| アップグレード前 | アップグレード後 | |
|---|---|---|
| Liferay | Liferay CE 7.2.1 GA2 | Liferay CE 7.4.3.132 GA132 |
| JDK | 8 | 21 |
| データベース | Aurora MySQL 2.11（MySQL 5.7 互換） | Aurora MySQL 3.11（MySQL 8.0 互換） |
| 検索エンジン | Elasticsearch 7.7.0（リモートモード） | Elasticsearch 8.17.4（リモートモード） |
アップグレードの全体像
本番作業の前に、テーマやテンプレートを 7.4 向けに直す「作業準備」（0）を済ませておき、本番当日は 1 から順番に作業するのがおすすめです。
- 作業準備：リハーサル環境を用意し、テーマ・テンプレート・カスタムモジュールなどを 7.4 向けに修正しておく
- Liferay を停止し、データベース・ドキュメントライブラリ・設定ファイルなどのバックアップを取得する
- データベースを MySQL 8.0 にアップグレードする
- Elasticsearch を 7.4 に対応したバージョンに入れ替える
- JDK と 7.4 のバンドルを準備し、設定ファイルとドキュメントライブラリを移す
- データベースアップグレードツールを実行する
- Liferay を起動し、検索インデックスを再構築する
- 事前に 7.4 向けに修正しておいたテーマやテンプレートを反映する
- 動作を確認する
データベースは 7.2 のままでも動作確認ができるので、Liferay 本体より先に単独で上げておきます。一度に全部を変えると、問題が起きたときに原因を切り分けにくくなるためです。一方、Elasticsearch 8 は 7.2 からは使えないため、アップグレードツールを実行する直前に入れ替えます。
また、いきなり本番環境で作業するのではなく、本番のデータベースとデータをコピーした環境で一度リハーサルすることを強くおすすめします。今回もリハーサルで多くの問題を事前に洗い出せました。リハーサルで所要時間を測っておけば、本番のメンテナンス時間も見積もれます。
本番作業にかかった時間
参考までに、本番作業の所要時間を載せておきます。記事（Web コンテンツ）が数百件の、小さな規模のサイトです。
| 作業 | 所要時間 |
|---|---|
| バックアップの取得、データベースの MySQL 8.0 へのアップグレード | 約1時間半 |
| Elasticsearch のアップグレード | 約40分 |
| データベースアップグレードツールの実行 | 約10分 |
| やり直し（原因の調査、データベースの復元、アップグレードの再実行） | 約1時間 |
| 合計 | 約3時間20分 |
当初は約1時間半で終わる予定でしたが、「ハマりどころ 2」のやり直しで約1時間かかり、データベースのアップグレードにも想定より時間がかかりました。トラブルが起きたときのやり直しの時間も含めて、余裕のあるメンテナンス時間を確保しておくことをおすすめします。
手順の詳細は公式ドキュメントもあわせてご確認ください。
0. 作業準備
本番作業の前に、ローカルやリハーサル環境に 7.4 を用意して、次の準備を済ませておきます。本番では、ここで用意したものを反映するだけにしておけば、メンテナンス時間を短くできます。
リハーサル環境の用意
本番のデータベースとドキュメントライブラリをコピーした環境を用意し、7.4 へのアップグレードを一通り試します。今回は、EC2・Aurora・S3 をそれぞれ複製してリハーサル環境を作りました。この記事で紹介しているハマりどころの多くも、リハーサルの段階で見つかったものです。
複製した環境では、接続先を複製したものに向け直すことを忘れないでください。複製した EC2 の portal-ext.properties は本番のデータベースを指したままです。また、S3 ストアの設定をシステム設定で保存している場合、その設定はデータベースに入っているため、複製したデータベースでも本番のバケットを指したままになります。そのまま起動したりアップグレードツールを実行したりすると、本番のデータベースやファイルを書き換えてしまいます。
- Liferay を起動する前に、
portal-ext.propertiesのデータベース接続先を、複製したデータベースに変更する - 起動後、［システム設定］＞［ファイルストレージ］の S3 の設定を、複製したバケットに変更する（EC2 のロールにも、複製したバケットへのアクセス権限が必要です）
テーマのアップグレード
7.2 向けに作ったテーマは、7.4 にそのままデプロイできません。デプロイすると does not support this version of Liferay というエラーになります。Liferay Theme Generator で作ったテーマであれば、gulp upgrade で更新できます。ただし gulp upgrade は1回で1バージョンずつしか上がらないため、7.2 からは 7.3、7.4 の2段階で更新します。
事前にテーマを 7.4 向けに更新してビルドし、リハーサル環境にデプロイして表示を確認しておきます。手順は、別の記事「Liferay 7.2 のテーマを 7.4 向けにアップグレードする」で紹介しています。
レイアウトテンプレート
カスタムのレイアウトテンプレートも、7.4 向けにビルドし直す必要がありました。テーマと同じく、ビルドした war ファイルを用意しておきます。
ADT の 7.4 対応
FreeMarker で書いた ADT（アプリケーション表示テンプレート。7.4 の画面では「ウィジェットテンプレート」）の中には、7.4 で修正が必要なものがありました。今回は、アセットパブリッシャー（記事一覧、閲覧ランキング、関連記事）とカテゴリ表示の ADT を、リハーサル環境で 7.4 向けに書き換えました。表示を確認したうえで、修正後のコードを手元に保存しておきます。
カスタムモジュール
7.2 向けに開発したモジュールは、7.4 ではそのまま動かないことが多いです。API の変更や OSGi の依存関係を確認して 7.4 向けに修正し、ビルドしておきます（Updating Customizations）。
言語キー
7.4 では、Liferay の言語キーが Portal Language モジュールにまとめられ、多くのキーの名前が変わりました。テーマや ADT、モジュールで Liferay の言語キーを使っていたり上書きしていたりする場合は、Renamed Language Keys で名前が変わっていないか確認してください。
1. 停止とバックアップ
ここからが本番当日の作業です。
サーバーの監視をしている場合は、作業中にアラートが飛ばないよう、先に通知を止めておきます。
そのうえで Liferay を停止し、次のものをバックアップします。データの整合性を保つため、バックアップは Liferay を止めてから取得します。
sudo systemctl stop liferay
- サーバー全体（仮想マシンのイメージなど）
- データベース
- ドキュメントライブラリ（ファイルシステムに保存している場合は
[Liferay Home]/data配下、S3 などの外部ストレージの場合はその保存先） portal-ext.propertiesやosgi/configsなどの設定ファイル- カスタマイズしたテーマやモジュール
- Elasticsearch のインデックス（公式ドキュメントでは、Elasticsearch をアップグレードする前にスナップショットでバックアップするよう案内されています）
今回は、EC2 のイメージ（AMI）の作成、S3 バケットの別バケットへのコピー（aws s3 sync）、Aurora のスナップショットの取得でバックアップしました。
アップグレードが途中で失敗すると、データベースは中途半端な状態で残ります。失敗したときにデータベースをバックアップから戻して再実行するところまで、手順を確認しておくと安心です。実際、今回の本番作業でもデータベースを戻して再実行することになりました（「ハマりどころ 2」参照）。
2. データベースを MySQL 8.0 にアップグレードする
7.4 GA132 の互換性マトリクスでは MySQL 5.7 もまだ対象に含まれています。ただ、MySQL 5.7 自体のサポートがすでに終了しているため、この機会に MySQL 8.0 へアップグレードしました。
今回は Aurora のブルー/グリーンデプロイを使い、エンジンを Aurora MySQL 3.11（MySQL 8.0 互換）にしたグリーン環境を作ってから切り替えました。
データベースを 8.0 に上げたら、7.2 のまま Liferay が起動できることを確認してから次へ進みます。MySQL クライアントで接続して SELECT VERSION(); でバージョンを確認し、Liferay を起動して画面が表示されることを確かめました。
sudo systemctl start liferay
確認できたら、次の作業のために Liferay を再び停止しておきます。
sudo systemctl stop liferay
ここで問題がなければ、データベースのバックアップをもう一度取得しておきます。このバックアップが、Liferay 本体のアップグレードに失敗したときの戻り先になります。
なお、データ量が多い環境では、公式ドキュメントにあるアップグレード用のデータベースチューニングや、不要なデータの削除（古い記事のバージョンなど）も検討するといいと思います。アップグレードにかかる時間を短くできます。今回はデータ量が少なかったため実施していません。
3. Elasticsearch を入れ替える
7.2 では、別途インストールした Elasticsearch 7.7.0 を使っていました。しかし、7.4 の Elasticsearch コネクタはこのバージョンに接続できません。そこで、7.4 が対応している Elasticsearch 8.17.4 に入れ替えました。なお、7.4 に同梱されているのは Elasticsearch 7 用のコネクタですが、Elasticsearch 8 には REST API の互換モードで接続する仕組みになっています（Upgrading to Elasticsearch 8）。
ここで大事なのは、データベースアップグレードツールを実行する前に Elasticsearch を入れ替えておくことです。公式ドキュメントの検索基盤のアップグレード手順でも、Elasticsearch のアップグレードと接続設定を済ませてから Liferay をアップグレードする順番になっています。古い Elasticsearch のままアップグレードツールを実行すると、アップグレードが完了しません（「ハマりどころ 2」で詳しく説明します）。
Liferay の検索インデックスの多くはデータベースの内容から再構築できるため、今回は Elasticsearch のデータを引き継がず、新しく入れ直しました（旧データは念のため退避しています）。ただし 7.2 では、DXP の検索チューニング（シノニムセットや結果ランキング）のデータは Elasticsearch のインデックスにしか保存されていません。新しい Elasticsearch に入れ替える場合、このデータは自動では引き継がれないため、公式ドキュメントの手順でインデックスをバックアップ・リストアしてください。
インストールの流れは次のとおりです（RPM パッケージでインストールした例です）。
1. 古い Elasticsearch を停止し、データとプラグインを片付けます。
古いバージョン用のプラグインが残っていると、新しい Elasticsearch が起動しません。プラグインを削除し、データディレクトリは退避して空のディレクトリを作り直します。
sudo systemctl stop elasticsearch
sudo rm -rf /usr/share/elasticsearch/plugins/*
sudo mv /var/lib/elasticsearch /var/lib/elasticsearch_backup
sudo mkdir /var/lib/elasticsearch
sudo chown elasticsearch:elasticsearch /var/lib/elasticsearch
2. リポジトリを登録して、バージョンを指定してインストールします。
sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
リポジトリの定義ファイルを作成し、次の内容を書き込みます。7.x 用の定義ファイルがすでにある場合は、8.x 用に書き換えます。
sudo vi /etc/yum.repos.d/elasticsearch.repo
[elasticsearch]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=0
autorefresh=1
type=rpm-md
sudo yum install --enablerepo=elasticsearch elasticsearch-8.17.4
3. Liferay が必要とするプラグインをインストールします。
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu analysis-kuromoji analysis-smartcn analysis-stempel
4. elasticsearch.yml を設定します。
cluster.name は、Liferay 側の設定（デフォルトは LiferayElasticsearchCluster）とそろえます。
Elasticsearch 8 では、認証と TLS がデフォルトで有効になっています。今回は Liferay と同じサーバーに置き、localhost からのみ接続する構成のため、これらを無効にしました。
設定ファイルを開き、次の内容になるように編集します。
sudo vi /etc/elasticsearch/elasticsearch.yml
cluster.name: LiferayElasticsearchCluster
xpack.security.enabled: false
xpack.security.enrollment.enabled: false
xpack.security.http.ssl:
enabled: false
xpack.security.transport.ssl:
enabled: false
ほかのサーバーから接続する構成の場合は、セキュリティを有効にしたまま、Liferay 側に認証情報を設定してください（Securing Elasticsearch）。
5. ヒープサイズを設定します。
Elasticsearch はサーバーのメモリ量から自動でヒープサイズを決めるため、Liferay と同じサーバーに置くとメモリを取り合います。今回は、インデックスの再構築中にサーバーが固まってしまったため、ヒープを 1GB に抑えました。
Elasticsearch 8 では、jvm.options を直接編集するのではなく、jvm.options.d 配下にファイルを置くのが推奨されています。次のファイルを新しく作成し、ヒープサイズを書き込みます。
sudo vi /etc/elasticsearch/jvm.options.d/heap.options
-Xms1g
-Xmx1g
6. サービスを有効にして起動します。
sudo systemctl daemon-reload
sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch
起動したら、応答が返ってくることと、バージョンが 8.17.4 になっていることを確認します。
curl http://localhost:9200
4. JDK と 7.4 のバンドルを準備する
JDK
7.4 GA132 の互換性マトリクスでは、対応する JDK は 17 と 21（推奨）です。JDK 8 では動かないため、今回は JDK 21（Amazon Corretto 21）を使いました。
まず JDK 21 をインストールします。Amazon Linux 2 の標準リポジトリには Corretto 21 がないため、RPM パッケージを直接指定しました。
sudo yum install -y https://corretto.aws/downloads/latest/amazon-corretto-21-x64-linux-jdk.rpm
次に、使う Java を JDK 21 に切り替えます。一覧が表示されるので、JDK 21 の番号を入力します。切り替えたら、java -version で 21 になっていることを確認します。
sudo alternatives --config java
java -version
OS のデフォルトの Java を切り替えると、旧環境の 7.2 は起動できなくなります。リハーサル中に旧環境でデータを修正する必要が出た場合は注意してください。
バンドルの配置
旧環境を上書きせず、新しいバンドルを別のディレクトリに展開します。wget が入っていない場合は、先にインストールしておきます。
sudo yum install -y wget
wget https://github.com/liferay/liferay-portal/releases/download/7.4.3.132-ga132/liferay-portal-tomcat-7.4.3.132-ga132-1739912568.tar.gz
sudo tar -zxvf liferay-portal-tomcat-7.4.3.132-ga132-1739912568.tar.gz -C /opt/
以降、展開してできたディレクトリを [新Liferay Home]、旧環境のディレクトリを [旧Liferay Home] と書きます。
展開したら、旧環境から次のものをコピーします。
[旧Liferay Home]/data/document_library（ファイルシステムに保存しているドキュメントライブラリ）portal-ext.properties
sudo cp -R [旧Liferay Home]/data/document_library [新Liferay Home]/data/
sudo cp [旧Liferay Home]/portal-ext.properties [新Liferay Home]/
セットアップウィザードでデータベースなどを設定した環境では、接続情報が portal-setup-wizard.properties に入っています。その場合はこのファイルもコピーし、中の liferay.home を新しいパスに書き換えます。
コピーしたら、Liferay を実行するユーザーにファイルの所有者を変更しておきます（今回は liferay ユーザーで実行しています）。
sudo chown -R liferay:liferay [新Liferay Home]
設定ファイルの棚卸し
旧環境の設定ファイルをそのまま持っていくのではなく、7.4 で必要なものかどうかを一つずつ確認します。移行するファイルの一覧や注意点は、公式ドキュメントの Migrating Configurations and Properties にまとまっています。また、7.4 で変わったデフォルト値や非推奨になった機能は Deprecations and Breaking Changes Reference で確認できます。
portal-ext.properties
今回は主に次の点を修正しました。
liferay.homeを新しいパスに変更するvirtual.hosts.valid.hostsに、実際にアクセスで使うホスト名を追加する（「ハマりどころ 4」参照）json.web.service.enabled=falseを削除するcompany.security.strangers.verify=falseを追加する（デフォルトが 7.2 のfalseから 7.4 ではtrueに変わったため、7.2 と同じ動作にしました）
sudo vi [新Liferay Home]/portal-ext.properties
liferay.home=[新Liferay Home]
virtual.hosts.valid.hosts=127.0.0.1,localhost,www.example.com
json.web.service.enabled=false → 削除
company.security.strangers.verify=false
json.web.service.enabled は見落としやすいので補足します。7.2 では、セキュリティ対策として JSON Web サービスを無効にしていました。しかし 7.4 では、この設定のままだと管理画面でのカテゴリ設定が失敗しました。7.4 の portal.properties にも、「false にすると、JSON Web サービスを呼び出すポートレットが動かなくなる」と書かれています。
virtual.hosts.valid.hosts や company.security.strangers.verify のように、7.4 でデフォルト値が変わったプロパティもあります。旧環境で設定していないプロパティは引き継ぎの対象にならないので、新旧の portal.properties を比べて確認しておくと安心です。
Blade CLI の upgradeProps コマンドを使うと、旧環境の portal-ext.properties を新しいバンドルと比べて、プロパティごとにどう対応すればよいかを一覧で確認することができます。
blade upgradeProps -p [旧環境の portal-ext.properties] -d [新Liferay Home]
osgi/configs
*-default.configは自動で生成されるファイルなので、移行しません。- システム設定の画面で保存した設定はデータベースに入っているので、自動で引き継がれます。一方、
.configファイルで設定していたもの（Elasticsearch の接続や S3 ストアの設定など）は、アップグレードツールを実行する前に新しいosgi/configsに置いておきます。 - 今回は、どちらも画面から設定していたため、移行が必要なファイルはありませんでした。
バンドル内のファイル
Tomcat の web.xml など、バンドル内のファイルを直接編集していた場合（セッションタイムアウトの変更など）は、新しいバンドルにも同じ変更を入れる必要があります。今回は、セッションタイムアウトを延ばす設定を入れ直しました。
sudo vi [新Liferay Home]/tomcat/webapps/ROOT/WEB-INF/web.xml
<session-timeout>180</session-timeout>
5. データベースアップグレードツールを実行する
設定
アップグレードツールは [Liferay Home]/tools/portal-tools-db-upgrade-client にあります。同じフォルダの設定ファイルを編集します。
portal-upgrade-database.properties（データベースの接続先）
sudo vi [新Liferay Home]/tools/portal-tools-db-upgrade-client/portal-upgrade-database.properties
jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
jdbc.default.url=jdbc:mysql://<DBホスト>/lportal?characterEncoding=UTF-8&dontTrackOpenResources=true&holdResultsOpenOverStatementClose=true&serverTimezone=GMT&useFastDateParsing=false&useUnicode=true
jdbc.default.username=<ユーザー名>
jdbc.default.password=<パスワード>
portal-upgrade-ext.properties
sudo vi [新Liferay Home]/tools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties
# portal-ext.properties の内容をすべてコピーしたうえで、次を追記
upgrade.report.enabled=true
upgrade.log.context.enabled=true
upgrade.report.enabled は、アップグレード結果のレポートを出力する設定です（最近のバージョンではデフォルトで有効です）。upgrade.log.context.enabled を有効にすると、ログにアップグレード処理の識別子（どのモジュールの処理か）が付くようになります。
また、公式ドキュメントでは、portal-ext.properties のプロパティをすべて portal-upgrade-ext.properties にもコピーしておくことがベストプラクティスとされています。
実行
Liferay を動かしているユーザー（今回は liferay）で実行します。root で実行すると、アップグレード中に作られるファイルの所有者が root になり、後で Liferay を起動するときに権限エラーの原因になります。
cd [新Liferay Home]/tools/portal-tools-db-upgrade-client
sudo -u liferay ./db_upgrade_client.sh -j "-Dfile.encoding=UTF-8 -Duser.timezone=GMT -Xmx4096m"
実行すると、設定ファイルにない項目（アプリケーションサーバーの場所など）を対話形式で聞かれます。標準的な Tomcat バンドルの構成であれば、デフォルトのまま Enter で進められます。
-j は、アップグレードツールの JVM オプションの指定です。データ量が多い環境では、-Xmx をさらに増やします。
処理が終わると、次のようなログが出ます。今回の規模では数分で終わりました。
Completed Liferay upgrade process in 298 seconds
処理の途中で例外が出た場合は、Completed ではなく Failed Liferay upgrade process in N seconds と表示されます。
ただし、Completed のメッセージが出ても、アップグレードが成功したとは限りません。失敗した場合や未完了の場合は、続けて次のメッセージが出て Gogo シェルに接続されます。
Connecting to Gogo shell because the upgrade failed or is incomplete
この場合は、Gogo シェルの upgrade:check コマンドで、アップグレードが終わっていないモジュールを確認できます（コマンドの一覧は Upgrading Modules Using Gogo Shell を参照）。原因を取り除いたら、データベースをバックアップから戻して、アップグレードを最初からやり直すのが確実です。
アップグレードレポートの確認
レポートは [新Liferay Home]/tools/portal-tools-db-upgrade-client/reports に出力されます。
upgrade_report.txt
冒頭の Result と Status で結果を確認します。成功した場合は次のようになります。
Result: success
Status: There are no pending upgrades
Portal initial build number: 7201
Portal final build number: 7403
公式ドキュメントによると、Result は次の3種類です。
- success：コア、モジュール、検証処理のアップグレードがすべて成功し、コンポーネントの依存関係にも問題がない
- failure：コア、モジュール、検証処理のいずれかが失敗した
- unresolved：コンポーネントの依存関係のチェックに失敗した
upgrade_report_diagnostics.txt
エラー（Errors）、失敗した SQL（Failed sqls）、警告（Warnings）、時間のかかった処理などがまとめて出力されます。Result が success でも、Failed sqls に何か出ていないかは必ず確認してください（「ハマりどころ 3」の例を参照）。
6. 起動と検索インデックスの再構築
起動
起動する前に、アップグレードツールの実行で作られたキャッシュや一時ファイルを削除しておきます。
sudo rm -rf [Liferay Home]/osgi/state/*
sudo rm -rf [Liferay Home]/work/*
sudo rm -rf [Liferay Home]/tomcat/temp/*
sudo rm -rf [Liferay Home]/tomcat/work/*
systemd などで Liferay を起動している場合は、起動スクリプトのパスを新しいバンドルのものに変更します。今回は、ユニットファイルの次の行を書き換えました。
sudo vi /etc/systemd/system/liferay.service
PIDFile=[新Liferay Home]/liferay.pid
ExecStart=[新Liferay Home]/tomcat/bin/startup.sh
ExecStop=[新Liferay Home]/tomcat/bin/shutdown.sh
ユニットファイルを再読み込みしてから、Liferay を起動します。
sudo systemctl daemon-reload
sudo systemctl start liferay
[Liferay Home]/tomcat/logs/catalina.out に Server startup in [xxx] milliseconds と出れば、起動は完了です。
Elasticsearch との接続確認とインデックスの再構築
起動したら管理者でログインし、コントロールパネルの［システム設定］＞［検索］＞［Elasticsearch 7］を開きます。動作モードを REMOTE、ネットワークホストアドレスを http://localhost:9200 に設定して保存します。
続いて、コントロールパネルの［検索］を開き、［つながり］タブで接続を確認します。「有効な接続」にリモートの接続が表示され、ヘルスが GREEN になっていれば接続できています。
接続を確認したら、［インデックス管理］タブで「すべての検索インデックス」の［再インデクス］をクリックし、検索インデックスを再構築します。同じ画面の「すべてのスペルチェック辞書」も合わせて［再インデクス］を実行しておきます。
7. テーマやテンプレートを反映する
「作業準備」で 7.4 向けに用意しておいたテーマやテンプレートを反映します。
テーマとレイアウトテンプレート
ビルドしておいた war ファイルをサーバーに転送します（手元の PC で実行します）。
scp xxx-theme.war ec2-user@<サーバー>:/home/ec2-user/
サーバー側で、war ファイルの所有者を Liferay を実行するユーザーに変更し、deploy フォルダに置いてデプロイします。レイアウトテンプレートの war ファイルも同じ手順です。
sudo chown liferay:liferay xxx-theme.war
sudo cp -a xxx-theme.war [Liferay Home]/deploy/
ADT
ADT はデータベースに保存されているため、アップグレード後に画面から、用意しておいた修正済みのコードに差し替えます。ADT は、サイトメニューの［デザイン］＞［テンプレート］＞［ウィジェットテンプレート］から編集できます。グローバルサイトに置いている ADT は、グローバルサイトのメニューから開きます。差し替えたら、ADT を使っているページを重点的に確認してください。
カスタムモジュール
修正・ビルドしておいたモジュールの jar ファイルを、テーマと同じようにサーバーに転送します（手元の PC で実行します）。
scp xxx-module.jar ec2-user@<サーバー>:/home/ec2-user/
サーバー側で、所有者を Liferay を実行するユーザーに変更し、deploy フォルダに置いてデプロイします。
sudo chown liferay:liferay xxx-module.jar
sudo cp -a xxx-module.jar [Liferay Home]/deploy/
モジュールが起動すると、[Liferay Home]/logs 配下のログに STARTED xxx.module_1.0.0 [1234] のようなメッセージが出ます。依存関係が解決できないなどの理由で起動できなかった場合はエラーが出るので、デプロイ後にログを確認してください。
8. 動作確認
最後に、記事の閲覧・作成・更新など、普段の運用で使う操作を一通り確認します。問題がなければ、止めていた監視の通知を元に戻して完了です。
9. ハマりどころと対処
ここからは、実際の作業でつまずいたポイントを紹介します。
ハマりどころ 1：アップグレードツールが起動しない（UnsupportedClassVersionError）
症状
アップグレードツールを実行すると、次のエラーが出て起動しませんでした。
Exception in thread "main" java.lang.UnsupportedClassVersionError: com/liferay/portal/tools/DBUpgrader has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0
原因
class file version 61.0 は Java 17、52.0 は Java 8 を指します。7.4 のアップグレードツールを、旧環境で使っていた JDK 8 のまま実行していたのが原因です。
対処
JDK 17 以上（今回は 21）をインストールし、使う Java を切り替えます。java -version で切り替わったことを確認してから、アップグレードツールを実行します。環境変数 JAVA_HOME が設定されている場合、アップグレードツールはそちらの Java を使うので、JAVA_HOME も JDK 21 に向いているか確認してください。
ハマりどころ 2：Elasticsearch に接続できず、アップグレードが完了しない
症状
アップグレードツールのログに、次のエラーが繰り返し出ていました。
ERROR [main][ROOT:47] bundle com.liferay.portal.search.elasticsearch7.impl:... : The activate method has thrown an exception
org.elasticsearch.ElasticsearchStatusException: Elasticsearch exception [type=exception, reason=Content-Type header [application/vnd.elasticsearch+json;compatible-with=7] is not supported]
アップグレードレポートの結果も、成功ではありませんでした。
Result: unresolved
Status: Unsatisfied components prevent upgrade processes to be registered
原因
7.2 で使っていた Elasticsearch 7.7.0 に接続したまま、アップグレードツールを実行していました。7.2 で画面から行った Elasticsearch の接続設定はデータベースに保存されているため、アップグレードツールの実行時にも、その接続先が使われていました。
7.4 の Elasticsearch コネクタは、Elasticsearch 8 と REST API の互換モードでやり取りするため、compatible-with=7 という Content-Type ヘッダーを付けてリクエストを送ります。エラーメッセージのとおり、Elasticsearch 7.7.0 はこのヘッダーに対応していませんでした。
その結果、検索エンジンのコンポーネントが起動できず、それに依存するコンポーネントも起動できませんでした。Result: unresolved は、公式ドキュメントでも「コンポーネントの依存関係のチェックに失敗した」状態とされています。一部のアップグレード処理が登録されないまま、アップグレードが未完了で終わっていたのです。
対処
Elasticsearch を 8.17.4 に入れ替えたうえでデータベースをバックアップから戻し、アップグレードを再実行したところ、Result: success になりました。
ハマりどころ 3：フレンドリー URL の登録で SQL が失敗する
症状
アップグレードレポート（upgrade_report_diagnostics.txt）の Failed sqls に、次の内容が出ていました。
SQL: insert into FriendlyURLEntryLocalization (..., languageId, urlTitle, ...) values (..., 'ja_JP', '/home', ...);
Error: Duplicate entry '...-/home' for key 'FriendlyURLEntryLocalization.IX_8AB5CAE'
原因
7.2 の時代に作られた一意インデックス IX_8AB5CAE が、アップグレード中も残っていたことが原因です。このインデックスは (groupId, classNameId, urlTitle) の組み合わせで一意になっていて、言語（languageId）を含みません。
7.4 のアップグレード処理は、ページのフレンドリー URL を言語ごとに登録します。そのため、同じページで英語と日本語の両方に /home が設定されていると、2つ目の言語を登録するときに一意制約に違反します。今回は、日本語（ja_JP）の登録が失敗していました。
この処理は1件ずつエラーを受け止めて続行するため、Result は success になります。ただし、失敗した行は移行されません。Result が success でも Failed sqls を確認すべきなのは、このためです。
なお、この問題は 2025年3月に修正され（LPD-50844）、アップグレード処理の前にこのインデックスを削除するようになりました。
対処
GA132 にアップグレードする場合は、Failed sqls に出たページを開いて、フレンドリー URL が正しく使えるか確認してください。今回は、サイトの表示に問題は出ていません。
同じページで複数の言語に同じフレンドリー URL が設定されているかは、たとえば次の SQL で事前に確認できます。
SELECT plid, friendlyURL, COUNT(*)
FROM LayoutFriendlyURL
GROUP BY plid, friendlyURL
HAVING COUNT(*) > 1;
ハマりどころ 4：起動後に「Invalid host name」で画面が表示されない
症状
アップグレード後に起動してアクセスすると、画面が 500 エラーになり、ログに次のエラーが出ていました。
java.lang.RuntimeException: Invalid host name xxx.xxx.xxx.xxx
at com.liferay.portal.servlet.filters.validhostname.ValidHostNameFilter.doFilterTry(...)
原因
virtual.hosts.valid.hosts のデフォルト値が変わっていました。以前のデフォルトは *（すべて許可）でしたが、7.4 の新しいバージョンでは localhost などのローカルアドレスだけになっています。この一覧にないホスト名や IP アドレスでアクセスすると拒否されます。
対処
portal-ext.properties に、実際にアクセスで使うホスト名を列挙します。
virtual.hosts.valid.hosts=localhost,127.0.0.1,www.example.com
おわりに
7.2 から 7.4 へのアップグレードを通して、特に大事だと感じたのは次の点です。
- 本番の前に、本番データのコピーでリハーサルする
- Liferay 本体だけでなく、JDK・データベース・Elasticsearch も互換性マトリクスで確認する
- データベースは Liferay より先に単独で上げ、7.2 のまま動作確認とバックアップをする
- Elasticsearch は、アップグレードツールを実行する前にアップグレードしておく
- アップグレードレポートを有効にし、
Resultと Failed sqls の両方を確認する - 失敗したときにデータベースを戻して再実行できるよう、バックアップと復元の手順を準備しておく
バージョンの差が大きいアップグレードほど、事前の準備とリハーサルが重要になってきます。
今回の紹介は以上です。アップグレードを検討されている方は、ぜひ参考にしてみてください。
※本記事の内容は Liferay CE 7.4.3.132 GA132 時点のものです。
