メッセージキュー
EMQX 6.0で導入されたメッセージキュー機能は、MQTTのサブスクライブ/パブリッシュパターンを耐久性のあるキューセマンティクスで拡張し、信頼性の高い非同期メッセージ配信を可能にします。RabbitMQのようなエンタープライズグレードのメッセージキューに見られる機能をネイティブMQTTに追加し、追加のインフラを必要としません。
本ページでは、EMQXのメッセージキュー機能の設計動機、主要概念、内部アーキテクチャ、メッセージフロー、実際の適用シナリオについて包括的に解説します。
メッセージキューとは?
EMQXのメッセージキューは、サブスクライバーの有無に関係なくMQTTメッセージを保持する名前付きの耐久性のあるサーバー側バッファです。各キューは一意のキュー名で識別され、トピックフィルターはパブリッシュされたメッセージのうちどれがキューに格納されるかを定義します(キューの識別子としては機能しません)。トピックフィルターに一致するメッセージは、キューの保持および配信ポリシーに従って自動的に永続化されます。
従来のMQTTの動作とは異なり、メッセージキューはクライアントがオンラインでない場合でもメッセージを保持します。クライアントは特別なサブスクライブトピック形式 $queue/<name> または $queue/<name>/<topic_filter> を使用してこれらのメッセージを消費できます。
メッセージキューは組み込みの耐久ストレージを使用しています。メッセージキューを有効にする前に、EMQXのデータディレクトリがローカルファイルシステムを使用していることを確認してください。組み込み耐久ストレージバックエンドはNFSやSMB/CIFSなどのネットワークファイルシステムをサポートしていません。
リスナーマウントポイントとの非互換性
マウントポイントが設定されたリスナー経由で接続したクライアントにはメッセージキューは動作しません。EMQXはマウントポイントを$queue/プレフィックスのマッチング前に適用するため、サブスクリプションはマウントされたリテラルトピックへの通常のサブスクリプションとして扱われ、クライアントにエラーは返されません。

なぜメッセージキューを使うのか?
MQTTは軽量で広く採用されているパブリッシュ/サブスクライブプロトコルですが、そのデフォルトの動作はメッセージ配信をサブスクライバーのオンライン状態に強く依存しており、非同期や遅延消費のシナリオには制約があります。
MQTTの制約
MQTTは共有サブスクリプション($share/{group}/topic)を通じてキューのような機能を一部サポートしていますが、以下の制約があります。
- サブスクライバーがオンラインでない場合、メッセージは保持されません。
- TTL(有効期限)、キューサイズ制限、オーバーフロー制御の組み込みサポートがありません。
- キーごとに最新値のみを保持するようなメッセージの重複排除機能がありません。
- キューの明示的なライフサイクル管理がありません。
これらの制約により、以下のようなパターンの実装が困難です。
- デバイスがオンラインになる前にコマンドを送信する。
- 常時接続していないワーカーにタスクを送る。
- 最新の状態や設定更新のみを保持する。
メッセージキューによるMQTTの拡張
メッセージキューはEMQXでMQTTプロトコルを拡張し、サブスクライバーのオンライン状態に関わらずメッセージを永続化して後続処理を可能にします。主な特徴は以下の通りです。
- クライアントがオフラインでもメッセージを永続化:キューは厳密な順序付けを保証しませんが、信頼性の高い非同期配信を実現し、軽量なMQTT通信と高度なエンタープライズメッセージングの橋渡しをします。
- 明示的なキュー宣言とプロパティ設定:TTL、サイズ制限、配信戦略などを設定可能で、メッセージの保持と配信を細かく制御できます。
- オプションの最新値セマンティクス:同じキーを持つメッセージは前の未消費メッセージを上書きし、最新の状態や設定更新のみを保持できます。
メッセージキューの概念
キュー名
メッセージキューを明示的に識別する一意の名前です。
キュー名に使用できる文字は以下のみです。
- 英数字(
A–Z、a–z、0–9) - アンダースコア(
_) - ハイフン(
-) - ドット(
.)
TIP
EMQX 6.1.1以降、キューはトピックフィルターではなく名前で指定します。トピックフィルターはキューの設定の一部であり、識別子ではありません。
- 英数字(
トピックフィルター
devices/+/commandのようなMQTTトピックフィルターで、どのパブリッシュメッセージがキューに書き込まれるかを決定します。設定されたフィルターに一致するメッセージのみがキューに格納されます。1つのメッセージが複数のキューにマッチし、複数のキューに書き込まれることもあります。TIP
トピックフィルターは名前付きキューの設定メタデータであり、キュー作成後に変更できません。
キューサブスクリプション
キューからメッセージを消費するための特別なMQTTサブスクリプションです。クライアントは以下の形式でサブスクライブします。
SUBSCRIBE $queue/<name> SUBSCRIBE $queue/<name>/<topic_filter>ここで、
<name>はキュー名(必須)<topic_filter>は既存キューにサブスクライブする場合は省略可能- 自動作成が有効な場合、
$queue/<name>/<topic_filter>は存在しないキューを指定されたトピックフィルターで作成します。
キューサブスクリプションは通常のMQTTサブスクリプションとは独立して動作し、メッセージキューのコンシューマーメカニズムで処理されます。
最新値セマンティクス
キュー宣言時にキューキー式を設定することで有効化できるオプション機能です。有効化すると、EMQXは各メッセージから
キューキーを抽出し、同じキーの新しいメッセージが未消費メッセージを上書きします。この動作は状態管理や設定更新のように最新値のみを保持したい場合に最適です。詳細はキューキー式を参照してください。
キュー宣言
耐久性のあるキューを作成し、トピックフィルター、配信戦略、保持制限、キー式などの設定を行うプロセスです。
キュー削除
キューとその格納メッセージおよび関連状態を削除します。EMQX 6.3.3以降、削除リクエストはキューを削除対象としてマークし、バックグラウンドでデータ削除を開始します。削除マーク後はメッセージの受け入れや配信は行われません。
キューのプロパティ
メッセージ保持時間や配信戦略など、キューの動作を制御するカスタマイズ可能な設定です。
QoS(サービス品質)
メッセージキュー内のすべてのメッセージは、パブリッシュやサブスクライブ時のQoSレベルに関係なくQoS 1(少なくとも一度配信)で配信されます。これにより信頼性の高いメッセージ配信が保証され、キューの配信動作が統一されます。
メッセージの永続化
サブスクライバーが接続していなくてもメッセージは保持されます。デフォルトでは最新値セマンティクスが適用されます。キー式が設定されていない通常のキューでは、メッセージは受信順に格納されます。
メッセージキューの動作
EMQXのメッセージキュー機能は疎結合な拡張として実装されており、内部フックを使ってパブリッシュおよびサブスクライブ操作をインターセプトします。これらのフックはレジストリやストレージ層と連携してメッセージを永続化し、信頼性の高い配信を実現します。
主なコンポーネント
以下の主要コンポーネントが関与します。
- メッセージキューレジストリ:すべてのメッセージキューのライフサイクルを管理し、キューの作成、削除、検索を担当します。
- メッセージキューメッセージDB:キューにパブリッシュされた実際のメッセージを格納し、EMQXの耐久ストレージ上に構築されています。
- メッセージキュー状態ストレージ:消費進捗やキューのメタデータ(TTL、プロパティなど)を永続化します。
- メッセージキューコンシューマー:キューからメッセージを取得し、接続されたサブスクライバーに配信戦略に基づいて配信します。
- メッセージキューサブスクリプションレジストリ:どのチャネル(クライアント)がどのキューにサブスクライブしているかを追跡し、各チャネルのコンテキストにサブスクリプション状態を保持します。
- メッセージキューフック:パブリッシュおよびサブスクライブイベントにフックし、メッセージをキューやコンシューマーにルーティングします。
メッセージキューデータフローダイアグラム
以下の図はメッセージキューの主要コンポーネント間のデータフローを示しています。

パブリッシュのワークフロー
- クライアントが通常のトピック(例:
some/topic)にメッセージをパブリッシュします。 - 内部のMQフックがトリガーされ、メッセージを処理します。
- フックはメッセージキューレジストリを参照し、パブリッシュトピックにマッチするキューを検索します。
- マッチするキューがあれば、メッセージはキューのメッセージDBに書き込まれます。
サブスクライブと消費のワークフロー
- クライアントが
$queue/<name>または$queue/<name>/<topic_filter>にサブスクライブします。 - MQフックがトリガーされ、サブスクリプションを処理します。
- フックはキュー名でキューを解決し、クライアントセッションコンテキスト内にサブスクリプションを初期化し、メッセージキューコンシューマーへの接続を確立します。
- キューに対応するコンシューマープロセスが存在しなければ、新規にメッセージキューコンシューマーを起動します。
- コンシューマーはメッセージ消費の進捗を復元し、メッセージDBからデータの取得を開始します。
- コンシューマーは設定された配信戦略に従い、受信したメッセージをサブスクライバーのクライアントセッションに配信します。
- サブスクライバーのクライアントセッションは標準MQTTメカニズムを通じてクライアントにメッセージを届けます。
メッセージキューのコア機能
EMQXのメッセージキュー機能は、信頼性が高く疎結合で設定可能なメッセージ配信を実現するための一連のコア機能を提供します。
メッセージのエンキュー
キューの設定されたトピックフィルターにマッチするトピックにパブリッシュされたメッセージは自動的にキューに格納されます。
キューキー式(最新値セマンティクス)を設定している場合、EMQXは各メッセージに対して式を評価します。
- キーが導出されれば、同じキーの未消費メッセージを置き換えます。
- キーが評価できない場合は、そのメッセージは破棄されます。
メッセージのデキュー
サブスクライブしたクライアントは設定された配信戦略に従ってキューからメッセージを受け取ります。メッセージキュー内のすべてのメッセージはQoS 1(少なくとも一度配信)で配信されます。クライアントがメッセージをアックすると、キューから削除されます。
配信戦略
メッセージをサブスクライバー間でどのように分配するかを定義できます。
random:ランダムに分配round_robin:順番にローテーションleast_inflight:処理中メッセージ数が少ないサブスクライバーを優先
キュー管理
作成、更新、削除、クエリなどのキューのライフサイクル操作はREST APIで利用可能です。
ユースケース
メッセージキューは、IoTやイベント駆動型アプリケーションで重要な信頼性の高い非同期メッセージングパターンを実現します。特にデバイスやコンシューマーが常時オンラインでない場合に有効です。
- デバイスコマンドキューイング:クラウドアプリケーションがIoTデバイス向けコマンドをキューに蓄積し、デバイスがオフラインでもコマンドを失わないようにする。
- バッチ処理:大規模データやワークロードを小さなタスクに分割し、ワーカークライアントに並列または遅延処理させる。
- センサーデータ処理:高頻度のセンサーデータを一時的にキューに蓄積し、後でバッチ処理や集約、分析を行う。
- 最新設定の配信:デバイスが常に最新の設定コマンドを取得・処理するようにし、同じ設定項目・キーの古い未処理コマンドはキュー内で上書きまたは無効化する。
関連機能リファレンス
メッセージキューはMQTTを基盤とし、EMQXの他のメッセージング機能を補完します。
- 共有サブスクリプション:複数サブスクライバー間でメッセージを分配しますが、クライアントがオンラインでない場合はメッセージを保持しません。
- 保持メッセージ:トピックごとに最後のメッセージを保存しますが、新規サブスクライバーに1メッセージのみ配信します。
- MQTT耐久セッション:個々のクライアントのセッション状態(サブスクリプションやQoS 1/2メッセージ)を再接続間で保持します。
- ルールエンジン:SQLライクなルールでキュー内メッセージをフィルタリング・処理し、変換や転送を行います。
セキュリティ考慮事項
EMQXはキューサブスクリプションの認可を、$queue/プレフィックスとキュー名を含む完全なサブスクリプショントピックフィルターに対して行います。書き込み認可ルールはこの完全なフィルターに対して記述してください。キューサブスクリプションは、サブスクライブ作成前にキューが保持していたメッセージも配信します。
キューサブスクリプションは専用ルールが必要
通常のトピック空間用のルールは対応するキューサブスクリプションをカバーしません。
t/#のルールは$queue/orders/t/#には適用されません。EMQXは両者を異なるトピックとして扱います。#や+で始まる認可トピックフィルターは$で始まるサブスクライブトピックフィルターにマッチしません。デフォルトのacl.confにある{eq, "#"}ルールを含む#を拒否するルールは$queue/orders/#を拒否しません。
# が拒否されているクライアントでも $queue/orders/# にサブスクライブしてキュー内のすべてのメッセージを受信可能です。$queue/ ネームスペースに対して明示的なルールを追加し、キューのトピックフィルターに対する通常トピックの認可ルールと同等かそれ以上に厳しくしてください。
%% 自動作成を許可せず、事前作成済みの "orders" キューを1つのコンシューマーに許可
{allow, {username, "order_worker"}, subscribe, ["$queue/orders"]}.
%% その他すべてのキューサブスクリプションを拒否(廃止予定プレフィックスも含む)
{deny, all, subscribe, ["$queue/#", "$q/#"]}.クライアントがまだ使用している限り、廃止予定の $q/ プレフィックスもルールに残してください。廃止予定のプレフィックスを参照。
この動作は共有サブスクリプションとは異なります。$share/<group>/t/# はEMQXがプレフィックスを除去し t/# の認可を行いますが、$queue/<name>/t/# は完全なサブスクライブトピックフィルターで認可します。
自動作成はクライアント指定のトピックフィルターを許可
キューの自動作成が有効な場合、サブスクライブするクライアントが新規キューのトピックフィルターを決定します。EMQXは $queue/<name>/<topic_filter> の <topic_filter> を使ってキューを作成し、クライアントが <topic_filter> への直接サブスクライブ権限を持つかは別途チェックしません。
例えば、クライアントが $queue/+/# へのサブスクライブを許可されていれば、$queue/orders/# にサブスクライブ可能です。orders キューが存在しなければ、EMQXはトピックフィルター # でキューを作成します。結果として、クライアントは直接サブスクライブ権限のないトピックのメッセージも受信する可能性があります。
自動作成はデフォルトで最新値キューに対して有効、通常キューでは無効ですが、メッセージキュー機能が有効な間のみ効果を持ちます。デフォルトの mq.enable = auto では少なくとも1つのキューが存在してからメッセージキューが有効になるため、最初のキューはサブスクライブで作成できません。信頼できないクライアントを受け入れる環境では、$queue/orders のような特定の事前作成済みキューのみアクセスを許可し、$queue/# や $q/# にマッチするその他のサブスクリプションはすべて拒否してください。あるいは自動作成を無効にして、ダッシュボードやREST APIからキューを作成してください。ダッシュボードによるキューの自動作成を参照。
ネームスペースのトピック分離は別途設定が必要
ネームスペースは単独ではトピック空間を分割しません。トピック分離にはマウントポイントが必要です。マウントポイントがない場合、異なるネームスペースのクライアントは単一のトピック空間を共有し、あるネームスペースで作成されたキューは別のネームスペースでパブリッシュされたメッセージをキャプチャします。詳細はネームスペース概要を参照してください。
互換性に関する注意
本節はEMQX 6.1.1で導入された互換性に関するポイントをまとめています。
名前付きキュー
EMQX 6.1.1以降、すべてのキューは明示的に名前付きリソースです。キューの識別は一意の名前に基づき、トピックフィルターではありません。
レガシーキュー
以前に作成された名前なしキューには、トピックフィルターから派生した名前が自動的に割り当てられます。
派生名の形式:
/<topic_filter>この派生名は既存の
$q/<topic_filter>サブスクリプションとの互換性を保ちます。
廃止予定のプレフィックス
$q プレフィックスはレガシーサブスクリプションで引き続きサポートされますが、廃止予定です。
新規導入では以下を使用してください。
$queue/<name>共有サブスクリプション制限
メッセージキューが有効な場合、$queue/ プレフィックスはキューサブスクリプション専用であり、共有サブスクリプションには使用できません。
次のステップ
メッセージキューの基本を理解したら、実際の利用方法を学びましょう。
- キューの作成と設定:ダッシュボードやREST APIでキューを宣言し、配信戦略や保持ポリシーを設定する方法を学べます。
- クイックスタートチュートリアル:MQTTXを使った実践的なパブリッシャー・サブスクライバーシナリオのステップバイステップガイドです。