ファイル転送サーバー側設定の構成
EMQXでは、MQTTファイル転送機能はデフォルトで有効になっていません。この機能を利用する場合は、設定ファイルで有効化する必要があります。
本ページでは、EMQXでファイル転送機能を有効化し、サーバー側でのファイル転送に関する各種機能を設定する方法を主に紹介します。これには、セグメントの保存やマージされたファイルのローカルディスクおよびS3バケットへのエクスポートが含まれます。また、ファイル転送の処理を最適化するためのMQTT転送設定の構成についても解説します。以下のセクションでは、設定ファイルを通じたこれらの設定方法を詳細に説明します。
また、Dashboardからファイル転送機能を有効化および設定することも可能です。詳細はDashboardによるファイル転送の有効化と設定を参照してください。
さらに、REST APIを使ったエクスポート済みファイルの管理方法についても紹介します。詳細はエクスポートファイルの管理をご覧ください。
ファイル転送の有効化
EMQXでは、ファイル転送機能はデフォルトで無効になっており、設定ファイルで有効化する必要があります。
file_transfer {
enable = true
}この設定により、EMQXはデフォルトでセグメントファイルを data/file_transfer/segments ディレクトリに保存し、ローカルディスクへのエクスポートを有効化して、マージ済みファイルを data/transfers/exports ディレクトリにエクスポートします。
ファイル転送機能をさらに詳細に設定する場合は、以下の設定例を参照してください。
セグメント保存の設定
EMQXはクライアントからファイルのセグメントをアップロードさせ、すべてのセグメント受信後に完全なファイルとしてマージします。これをサポートするために、EMQXはセグメントファイルを一時的に保存し管理する必要があります。
現状、EMQXはセグメントファイルの保存先としてディスクのみをサポートしており、セグメントの保存場所を設定できます。
ファイルアップロードが完了すると、セグメントは自動的にクリーンアップされます。アップロードがタイムアウト期間内に完了しなかったファイルについては、セグメントの有効期間とクリーンアップスケジュールを設定し、ディスク容量の無駄な占有を防止できます。
file_transfer {
# ファイル転送機能の有効化
enable = true
# セグメント保存の設定
storage.local.segments = {
# セグメント保存ディレクトリ。I/O性能の高いディスクに設定することが望ましい。
root = "./data/file_transfer/segments"
# 有効期限切れセグメントファイルの定期クリーンアップ
gc {
# クリーンアップ間隔
interval = "1h"
# セグメント保存の最大有効期間。これを超えたセグメントはマージされていなくても削除される。
# クライアント側で指定する有効期間はこの値を超えてはならない。
maximum_segments_ttl = "24h"
}
}
}想定されるファイルサイズ、同時転送数、利用可能なディスク容量に応じて適切な設定を行ってください。
ファイルエクスポートの設定
すべてのセグメント転送完了後、EMQXはセグメントをマージして完全なファイルを作成し、ローカルディスクまたはS3バケットにエクスポートしてアプリケーションと連携できます。
TIP
ファイルエクスポートを設定しない場合は、デフォルトでローカルディスクへのエクスポートとなります。EMQXは両方のエクスポート方法を同時に設定することはできず、いずれか一方のみ利用可能です。
ローカルディスクへのファイルエクスポート
以下の設定例は、マージ済みの完全ファイルをローカルディスクに保存する方法です。エクスポートファイルの保存場所と有効期間を設定できます。
file_transfer {
# ファイル転送機能の有効化
enable = true
# セグメント保存の設定
# ...
# ローカルディスクへのファイルエクスポートを有効化
storage.local.exporter.local {
# エクスポートファイル保存ディレクトリ。I/O性能の高いディスクに設定することが望ましい。
root = "./data/transfers/exports"
}
}S3バケットへのファイルエクスポート
以下の設定例は、マージ済みの完全ファイルをS3バケットに保存する方法です。
file_transfer {
# ファイル転送機能の有効化
enable = true
# セグメント保存の設定
# ...
storage.local.exporter.s3 {
host = "s3.us-east-1.amazonaws.com"
port = 443
# S3アクセス用の認証情報
access_key_id = "AKIA27EZDDM9XLINWXFE"
secret_access_key = "******"
# エクスポートファイル保存用バケット
bucket = "my-bucket"
# 共有URLの有効期限
# EMQXはクライアントがS3から直接ファイルをダウンロードできる一時共有URLを生成します。このパラメータはEMQX APIが返すファイルダウンロードURLの有効期限を指定します。有効期限切れ後はURLは無効になりますが、実際のファイルはS3に残ります。
#url_expire_time = "1h"
# S3とのHTTP(S)接続設定。安全なファイルアップロードと接続プール管理を可能にします。
transport_options {
ssl.enable = true
connect_timeout = 15s
}
}
}MQTT転送設定の構成
ファイル転送処理を最適化し、クライアントの過度な待機を防ぐために、各ファイル転送操作に対するタイムアウトを設定できます。以下のMQTT設定を構成可能です。
file_transfer {
enable = true
init_timeout = "10s"
store_segment_timeout = "10s"
assemble_timeout = "60s"
}init_timeout：初期化操作のタイムアウト時間store_segment_timeout：ファイルセグメント保存のタイムアウト時間assemble_timeout：ファイル組み立てのタイムアウト時間
これらの操作のいずれかが指定時間を超過すると、MQTTクライアントは RC_UNSPECIFIED_ERROR コード付きのPUBACKパケットを受け取ります。
Dashboardによるファイル転送の有効化と設定
このセクションでは、Dashboard上でファイル転送機能を有効化し、機能を設定する方法を説明します。
EMQX Dashboardにアクセスし、管理 -> ファイル転送をクリックします。ファイル転送ページで、有効化のトグルスイッチをクリックしてファイル転送機能を有効化できます。一般設定および詳細設定を参照しながら機能を設定してください。設定完了後、変更を保存をクリックします。
一般設定
以下の一般設定を構成できます。
- 初期化タイムアウト：
initコマンドの実行に許容される最大時間です。例えば、システムが過負荷でinitコマンドをこの時間内に処理できない場合、タイムアウトとなり、エラーコード（0x80）付きのPUBACKメッセージが送信されます。デフォルト値は10sです。 - セグメントルートディレクトリ：アップロードされたファイルの一時セグメントを保存するディレクトリパスです。絶対パスを指定し、I/O性能の高いディスク上に配置することが重要です。これにより、特に負荷が高い状況でのセグメント処理が効率化されます。
- ファイル保存方法：ファイルのエクスポート方法を選択します。選択肢は
ローカルストレージとS3ストレージです。S3ストレージを選択した場合は、以下の追加設定が必要です：- ホスト：S3サービスのエンドポイント。例：
s3.us-east-1.amazonaws.com - ポート：S3サービス接続に使用するポート。例：
443（安全なHTTPS接続） - アクセスキーID と シークレットアクセスキー：S3バケットへのアクセスに必要な認証情報。安全に管理してください。
- バケット：ファイルを保存するS3バケット名。例：
my-bucket - TLS有効化：安全なファイル転送のためにTLS（Transport Layer Security）を使用するかどうか。詳細は外部リソースアクセスのTLSを参照してください。
- ホスト：S3サービスのエンドポイント。例：
- ファイルルートディレクトリ：ファイル保存用のルートディレクトリを絶対パスで指定します。
ローカルストレージを選択した場合に、組み立て済みファイルの保存先として使用されます。
詳細設定
一般設定で選択したファイル保存方法に応じて、異なる詳細設定が用意されています。
ローカルストレージ
ファイルをローカルストレージにエクスポートする場合、以下の詳細設定を構成できます。
| 項目名 | 説明 | 推奨値 |
|---|---|---|
| セグメント保存タイムアウト | segment コマンドによるファイルセグメント保存に許容される最大時間。これを超過すると（例：システム過負荷時）、エラーコード（0x80）付きのPUBACKメッセージが送信され、タイムアウトを通知します。 | 5分 |
| 組み立てタイムアウト | fin コマンドによるファイル組み立て処理の最大許容時間。タイムアウト時はエラーコード（0x80）付きPUBACKが送信されます。リソース制約による遅延が予想される場合に重要です。 | 5分 |
| ストレージGC間隔 | ファイル保存システムのガベージコレクション実行間隔。不要データの削除によりストレージ管理を行います。 | 1時間 |
| 最大セグメントTTL | 保存されたセグメントの最大有効期間。これを超えたセグメントは、完全ファイルにマージされていなくても自動的に削除されます。ファイル転送時に指定されたTTLより優先されます。 | 24時間 |
| 最小セグメントTTL | セグメントの最小有効期間。完全ファイルにマージ済み、または短いTTL指定があっても、この期間内は削除されません。後処理や冗長性確保のために最低限の保持期間を保証します。 | 5分 |
S3ストレージ
ファイルをS3ストレージにエクスポートする場合、ローカルストレージと共通の設定を除き、以下の詳細設定も構成可能です。
| 項目名 | 説明 | 推奨値 |
|---|---|---|
| URL有効期限 | S3にアップロードされたファイルにアクセスするために生成されるURLの有効期間。期限切れ後はURLでのアクセスができなくなります。 | - |
| 最小パートサイズ | S3へのマルチパートアップロード時の各パートの最小サイズ。小さいパートサイズはアップロード回数を増やしますが、不安定な環境で大容量ファイルを扱う際に有効です。 | 5 MB |
| 最大パートサイズ | マルチパートアップロードの各パートの最大サイズ。大きいパートはアップロード回数を減らし、高帯域環境で効率的ですが、メモリ消費が増えます。 | 5 MB |
| ACL | アップロードオブジェクトのアクセス権限を指定するアクセスコントロールリスト。以下のオプションがあります：private：所有者のみフルアクセス。public_read：全員が読み取り可能。public_read_write：全員が読み書き可能。authenticated_read：認証ユーザーのみ読み取り可能。bucket_owner_read：バケット所有者が読み取り可能。bucket_owner_full_control：バケット所有者がフルコントロール。 | - |
| IPV6プローブ | IPv6接続の有無をチェックするかどうか。ネットワークがIPv6対応の場合、有効化すると互換性や性能向上が期待できます。 | 有効 |
| 接続タイムアウト | S3サーバーへの接続確立に許容される最大時間。これを超えるとタイムアウトとなり、サーバーの応答性を保証します。 | - |
| プールタイプ | S3接続管理に使用するコネクションプールの種類：random：ランダム選択。hash：ハッシュ関数による選択。接続の性能や信頼性に影響します。 | random |
| プールサイズ | S3接続用コネクションプールのサイズ。大きいほど同時接続数を処理可能ですが、リソース消費も増加します。 | 8 |
| HTTPパイプライニング | 応答を待たずに送信するHTTPリクエスト数。スループット向上に寄与しますが、複雑さが増します。 | 100 |
| HTTPヘッダー | S3リクエストに追加するカスタムHTTPヘッダー。追加情報や制御パラメータの送信に利用可能。追加ボタンでキー・バリューを指定します。 | - |
| 最大リトライ回数 | エラー発生時のS3リクエスト再試行の最大回数。値を増やすと信頼性向上が期待できますが、遅延も増加します。 | - |
| リクエストタイムアウト | S3リクエスト完了までの最大許容時間。超過するとタイムアウトとなります。 | - |
エクスポートファイルの管理
エクスポート済みファイルの一覧表示や詳細情報の閲覧、移動、削除、ダウンロードなどの管理操作が可能です。これらの管理はREST APIまたは手動で行えます。将来的にはDashboard上での管理インターフェースも追加予定です。
REST APIによるエクスポートファイル管理
EMQXはエクスポートファイル管理用のREST APIを提供しており、MQTTファイル転送管理APIを利用してファイルの閲覧やダウンロードが可能です。
重要なお知らせ
ファイル転送ストアはグローバルであり、ネームスペースを認識しません。ネームスペースに紐づくDashboardユーザーやAPIキーは、ロールやスコープに関わらずファイル転送エンドポイントを使ってファイル一覧表示やローカル保存ファイルのダウンロードができません。グローバルDashboardユーザーまたはグローバルAPIキーで認証してください。/file_transfer 設定エンドポイントは影響を受けません。
ローカルディスクエクスポートファイルの手動管理
ディスク上のエクスポートファイルを直接管理する場合（ファイルの移動やFTP・HTTPサービスを使ったダウンロードなど）、以下のファイル保存場所の仕様を参照してください。
ファイル名の衝突や単一ディレクトリ内のファイル数過多を避けるため、EMQXはバケットストレージ方式でエクスポートファイルを保存します。仕組みは以下の通りです。
- まず、ファイルIDとクライアントIDのsha256ハッシュ値を計算します。例：
ABCDEFG012345... - 6階層のディレクトリ構造でファイルを保存します。各階層は以下のように定義されます：
- ハッシュの最初の2バイトを第1階層ディレクトリ名とする
- 次の2バイトを第2階層ディレクトリ名とする
- 残りのハッシュを第3階層ディレクトリ名とする
- エスケープされたクライアントID
- エスケープされたファイルID
- メタデータのファイル名を最下層とする
例として、エクスポートファイルは以下のようなディレクトリ構造に保存されます：AB/CD/EFGH.../{clientid}/{file_id}/{filename}
S3バケットエクスポートファイルの手動管理
S3バケットの場合は、S3クライアントツールやS3のREST APIを使ってファイル削除やダウンロードなどの管理が可能です。ファイル保存場所の仕様は以下の通りです。
ローカルエクスポーターのバケットストレージ方式とは異なり、S3エクスポーターでエクスポートされたファイルはよりシンプルな3階層の階層構造で保存されます。
- エスケープされたクライアントID
- エスケープされたファイルID
- ファイル名
例として、エクスポートファイルは以下のようなディレクトリ構造に保存されます：{clientid}/{file_id}/{filename}