OpenResty の主なコンポーネントは、Lua を NGINX に組み込む ngx_lua などの NGINX モジュール、Lua コードを実行する LuaJIT、lua-resty-redis などの Lua ライブラリ、そして resty、restydoc、opm のコマンドラインツールです。NGINX モジュールはサーバー自体の機能を拡張し、Lua ライブラリは Lua コードから require で呼び出して使います。手元の環境で使えるかは、openresty -V と require で確認できます。

本記事では、日常の開発でよく使う OpenResty のコンポーネントと、それらが手元の環境で利用できるかを確認する方法を紹介します。プラットフォームの位置付けや用途については、前回の記事OpenResty とはをご覧ください。

OpenResty のコアコンポーネントの連携

Redis への問い合わせを例に、リクエストの流れを見てみましょう。まず NGINX がリクエストを受け取り、接続を管理します。ngx_lua により、リクエスト処理の各フェーズに Lua コードを組み込めます。LuaJIT がそのコードを実行し、Redis への問い合わせが必要になった時点で、コードから lua-resty-redis を呼び出します。

OpenResty を使い始めた人が最初に戸惑いやすいのが、NGINX モジュールと Lua ライブラリの違いです。

簡単にいうと、NGINX モジュールはサーバー自体の機能を拡張し、Lua ライブラリは Lua コードから呼び出して使うものです。 ngx_lua は NGINX モジュールで、設定ファイルから Lua を実行する仕組みと ngx.* API を提供します。一方、lua-resty-redis は Lua ライブラリで、require "resty.redis" と書いて読み込み、Redis 通信に使います。

ビジネスロジックから直接呼び出すことは少なくても、欠かせない裏方として lua-resty-core があります。LuaJIT FFI を使って、多くの ngx.* インターフェースを再実装しています。Redis クライアントのように特定の用途を担うわけではありませんが、OpenResty の高性能を支える重要な基盤です。

LuaJIT はターミナルの luajit コマンドで通常の Lua スクリプトを単独実行することもできます。ただし ngx.* API を使うコードは OpenResty の実行環境が必要です。実行エンジンについてはOpenResty における LuaJITをご覧ください。

OpenResty のよく使うモジュールと Lua ライブラリ

よく使うコンポーネントを用途別に紹介します。

サーバーモジュール

  • ngx_lua(lua-nginx-module): 中核となるモジュールです。HTTP リクエスト処理の各フェーズで Lua を実行し、ngx.* API を提供します。
  • ngx_stream_lua(stream-lua-nginx-module): ngx_lua と同様の役割を TCP/UDP の L4 トラフィックに対して担います。
  • headers-more(headers-more-nginx-module): NGINX ディレクティブを使い、HTTP リクエスト/レスポンスヘッダーを簡単に追加、変更、削除できます。

NGINX モジュールは、コンパイル時にサーバーへ静的に組み込むことも、動的モジュールとしてビルドし(モジュールの対応状況によります)、設定ファイルで必要に応じて読み込むこともできます。

Lua ライブラリ

  • lua-resty-core:LuaJIT FFI によって一部の ngx.* インターフェースを実装する基盤ライブラリです。
  • lua-resty-redis、lua-resty-mysql:Redis と MySQL 用の非ブロッキングクライアントです。アカウント、設定、アプリケーションの状態の問い合わせなどに使います。
  • lua-cjson:Lua のテーブルと JSON の相互変換を高速に行います。
  • lua-resty-lrucache、lua-resty-lock:前者はワーカープロセス内の LRU キャッシュ、後者は共有メモリ辞書を使う非ブロッキングロックを提供します。キャッシュスタンピード対策によく使われます。
  • lua-resty-limit-traffic:リクエストレートと同時接続数を制御し、ゲートウェイのレート制限を実装します。
  • lua-resty-websocket:Lua で WebSocket サーバー/クライアント通信を実装できます。
  • lua-resty-upstream-healthcheck:NGINX のアップストリームサーバーをアクティブにヘルスチェックし、異常ノードを自動的に除外します。利用には対応するモジュールと設定が必要です。

上記は一例です。すべてのコンポーネントはOpenResty 公式コンポーネント一覧をご覧ください。掲載されているすべてのコンポーネントがお使いのインストールパッケージに含まれているとは限らず、追加設定が必要なものもあります。コードを書く前に、お使いの環境で確認してください。

コマンドラインツール

OpenResty には、通常は別のオプションパッケージとして提供される便利なツールもあります。

  • resty:ターミナルで OpenResty Lua スクリプトを実行します。簡単なテストやデバッグに便利です。
  • restydoc:ローカルにインストールされた公式ドキュメントをターミナルで参照します。
  • opm:コミュニティの Lua パッケージをインストール・管理する公式パッケージマネージャーです。

インストールディレクトリでのコンポーネントの確認

コンポーネントはどこにインストールされるのでしょうか。例として Ubuntu 24.04 ARM64 向けの公式 DEB パッケージ 1.31.8.1-1~noble1 を見てみます(公式パッケージディレクトリ)。メインパッケージの openresty と、openresty-resty、openresty-restydoc、openresty-opm の各ツールパッケージをインストールすると、/usr/local/openresty/ は次のような構成になります(未インストールの場合は、まずディレクトリ構成で全体像をつかみ、後でOpenResty のインストールを参考に実際に操作してください)。

/usr/local/openresty/
├── bin/                       # openresty、resty、restydoc、opm コマンド
├── nginx/
│   ├── conf/nginx.conf        # デフォルトのサーバー設定
│   └── sbin/nginx             # サーバーバイナリ
├── luajit/                    # LuaJIT コマンドとランタイムライブラリ
├── lualib/
│   └── resty/
│       ├── core.lua
│       └── redis.lua          # ディストリビューション付属の Redis クライアント
├── pod/                       # restydoc のドキュメントデータ
└── site/
    └── lualib/                # システム全体向け OPM Lua ライブラリの配置先

特に注目したい Lua ライブラリのディレクトリは 2 つあります。

  1. lualib/:公式 OpenResty ディストリビューションに付属する Lua ライブラリを格納します。先ほどの redis.lua もここにあります。
  2. site/lualib/:opm でグローバルにインストールしたコミュニティ製ライブラリが置かれます。opm --cwd を使うと、現在のプロジェクト内にインストールされます。

require でライブラリが見つからない場合は、これらのディレクトリにファイルがあるか確認し、nginx.conf の lua_package_path にそのパスが含まれているか調べます。詳しくはOPM 公式ドキュメントとOpenResty Lua モジュールのチュートリアルをご覧ください。

コンポーネントが使えるか確認する方法

ドキュメントにある機能が手元で使えない場合、コンポーネントの種類に応じて調べ方が異なります。

確認したいこと確認方法注意点・制約
ターミナルで実行されるバイナリcommand -v openresty、openresty -Vターミナルのコマンドと本番稼働中のサービスが異なる場合があります。
C モジュールがバイナリに組み込まれているか対象バイナリの -V 出力を確認動的モジュールはビルド済みでも設定から読み込まれていない場合があります。
動的モジュールが読み込まれているか対象バイナリと設定関連の起動オプションを指定して -T を実行し、load_module を確認結果は指定した設定ファイルに対するものです。
Lua ライブラリを読み込めるか対象の実行コンテキストで require を実行読み込み成功は外部サービスへの接続を保証しません。
ツールコマンドが見つからない理由パッケージ状態と PATH を確認コマンドラインツールがなくてもサーバー自体は動作できます。

以下、順に確認していきます。

バイナリとビルドオプションの確認

まず、ターミナルで openresty と入力した際にどのプログラムが実行されるか、どのモジュールがコンパイル時に含まれたか確認します。

command -v openresty
readlink -f "$(command -v openresty)"
openresty -V

Ubuntu の例では、/usr/bin/openresty は /usr/local/openresty/nginx/sbin/nginx へのシンボリックリンクです。openresty -V は次のような出力を表示します(読みやすさのため改行しています)。

nginx version: openresty/1.31.8.1
--prefix=/usr/local/openresty/nginx
--add-module=../ngx_lua-0.10.32rc7
--add-module=../ngx_stream_lua-0.0.20rc3

この出力の見方は次のとおりです。

  • --prefix:ビルド時に設定されたデフォルトの作業ディレクトリのプレフィックスです。起動時に -p で一時的に変更できます。
  • --add-module:モジュールがサーバーバイナリに静的コンパイルされており、そのまま使用できることを示します。
  • --add-dynamic-module:動的モジュールとしてビルドされたことを示します。利用するには設定ファイルに load_module が必要です。

詳しくはNGINX コマンドラインオプションとNGINX ビルドオプションをご覧ください。

本番環境でよくある落とし穴は、複数の NGINX や OpenResty がインストールされていることです。ターミナルで実行したコマンドが、バックグラウンドで動作中のサービスと同じバイナリとは限りません。systemd 管理の場合は、systemctl show -p ExecStart openresty で実際のバイナリパスと起動引数(-p、-c、-g など)を確認してください。まったく同じバイナリと引数で -T を実行して設定全体を出力し、その中で load_module を検索するのが最も確実です。

Lua ライブラリの読み込み検証

付属の lua-resty-redis はメインパッケージとともにインストールされます。resty コマンドもある場合は、ターミナルで確認できます。

resty -e 'require "resty.redis"; print("resty.redis loaded")'

resty.redis loaded と表示されれば、ライブラリファイルが存在し、読み込み可能です。resty コマンドが見つからない場合はツールパッケージと PATH を確認します。module not found の場合は lualib の場所と Lua の検索パスを調べてください。この確認は resty のデフォルト環境で読み込みを試すだけで、Redis への接続は行いません。ゲートウェイが独自の lua_package_path を設定している場合は、実際のサービス環境でも検証してください。

コマンドラインツールのパッケージの確認

サーバーは正常に動いていても、restydoc や opm を実行すると command not found が出ることがあります。これは通常、これらのツールが別のオプションパッケージに分割されているためです。

コマンド用途Debian / Ubuntu、AlpineRPM 系(RHEL / CentOS など)
openrestyサーバー起動、設定確認openrestyopenresty
restyターミナルから OpenResty Lua を実行openresty-restyopenresty-resty
restydocローカルのオフラインドキュメントを参照openresty-restydocopenresty-doc
opmコミュニティ Lua パッケージの管理openresty-opmopenresty-opm

Ubuntu では APT がメインの openresty パッケージとともに openresty-resty、openresty-opm を推奨パッケージとしてインストールすることが多いものの、openresty-restydoc は通常、手動で追加する必要があります。dpkg -s openresty-restydoc でインストール状態を確認し、dpkg -L openresty-restydoc でインストール先を調べ、そのディレクトリが PATH に含まれているかを確認してください。各 OS のパッケージ構成については、公式の DEB、RPM、Alpine パッケージの説明をご覧ください。

補足として、コミュニティで広く使われるテストフレームワーク Test::Nginx は Perl 環境に個別にインストールするモジュールで、/usr/local/openresty/ 配下にはありません。本チュートリアルシリーズの後半で、小さなゲートウェイのテストに使用します。

よくある質問

OpenResty に含まれるモジュールはどう確認しますか?

openresty -V を実行し、ビルドオプションを確認します。--add-module に並ぶモジュールはサーバーバイナリに静的コンパイルされており、そのまま使えます。--add-dynamic-module は動的モジュールで、設定ファイルの load_module で読み込む必要があります。本番で動いているサービスと同じバイナリかどうかも、あわせて確認してください。

NGINX モジュールと Lua ライブラリの違いは何ですか?

NGINX モジュールはサーバー自体の機能を拡張するもので、ビルド時に組み込むか、動的モジュールとして読み込みます。Lua ライブラリは Lua コードから require で読み込んで使うものです。たとえば ngx_lua は NGINX モジュールで、lua-resty-redis は Lua ライブラリです。

使わないモジュールやツールを削除できますか?

コンポーネントの種類によります。

  • 静的モジュール: サーバーバイナリに組み込まれています。バイナリサイズやセキュリティ上の理由で削除する必要があれば、該当する --add-module を外して OpenResty を再ビルドします。
  • 動的モジュール: まずアプリケーションの設定や他のモジュールが依存していないことを確認します。関連ディレクティブと load_module を削除し、対象バイナリで -t を実行して設定を検査します。
  • コマンドラインツール: restydoc や opm などのツールを削除するには、システムのパッケージマネージャー(apt、yum など)で対応するオプションパッケージをアンインストールします。表示される依存関係の警告も確認してください。

まとめと次のステップ

OpenResty を使い始める段階で、コンポーネント名をすべて覚える必要はありません。まず、NGINX がネットワークと転送を担当し、ngx_lua が NGINX と Lua をつなぎ、LuaJIT がコードを実行するという基本の関係を理解しましょう。データベースへの問い合わせ、キャッシュ、レート制限が必要になったら、対応する lua-resty-* ライブラリを調べれば十分です。モジュールやライブラリの読み込みエラーが起きたら、コードを変える前に、確認しているインスタンスが正しいかを調べ、ビルドオプション、ライブラリパス、ツールパッケージを確認してください。環境に起因する問題の大半は、これで解決できます。

本記事はOpenResty チュートリアルシリーズの一部です。構成要素を把握したら、次は「NGINX で Lua スクリプトを書く入門」で、NGINX 設定ファイルに Lua コードを直接書く方法を実践します。

このチュートリアルが気に入っていただけましたら、ぜひ本ブログサイトおよび弊社の YouTube チャンネルをご購読ください。ありがとうございます!

著者について

章亦春(GitHub ハンドル: agentzh)は、OpenResty® オープンソースプロジェクトのオリジナル作成者であり、OpenResty Inc. の CEO です。

章亦春は「オープンソース技術」の最も初期の提唱者およびリーダーの一人です。Cloudflare や Yahoo! など、国際的に著名な複数のテック企業で勤務しました。「エッジコンピューティング」「動的トレーシング」「マシンコーディング」の先駆者であり、22 年以上のプログラミング経験と 16 年のオープンソース経験を持ちます。章亦春はオープンソース界で OpenResty® のプロジェクトリーダーとして広く知られており、同プロジェクトは全世界で 4,000 万以上のWeb サイトドメインに採用されています。

OpenResty Inc. は章亦春が 2017 年に設立したエンタープライズソフトウェアスタートアップで、世界最大級の企業を顧客に持ちます。フラッグシップ製品の OpenResty XRay は、動的トレーシング技術を大幅に強化・活用する非侵入型のプロファイリングおよびトラブルシューティングツールです。また、OpenResty Edge 製品は、強力な分散トラフィック管理およびプライベート CDN ソフトウェア製品です。

熱心なオープンソースコントリビューターとして、章亦春は Linux カーネル、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl など、数多くのオープンソースプロジェクトに 100 万行以上のコードを貢献しています。また、60 以上のオープンソースソフトウェアライブラリを開発しています。

翻訳

英語版の原文と日本語訳版(本文)をご用意しております。読者の皆様による他の言語への翻訳版も歓迎いたします。全文翻訳で省略がなければ、採用を検討させていただきます。心より感謝申し上げます!