ファイル転送サーバー側設定の構成

EMQXでは、MQTTファイル転送機能はデフォルトで有効になっていません。この機能を利用する場合は、設定ファイルで有効化する必要があります。

本ページでは、EMQXでファイル転送機能を有効化し、サーバー側でのファイル転送の各種機能を設定する方法を主に紹介します。これには、セグメントの保存やマージ後のファイルをローカルディスクやS3バケットにエクスポートする設定が含まれます。また、ファイル転送の処理を最適化するためのMQTT転送設定についても説明します。以下のセクションで、設定ファイルを通じた詳細な設定方法を紹介します。

• ファイル転送の有効化
• セグメント保存の設定
• ファイルエクスポートの設定
• 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を参照してください。
• ファイルルートディレクトリ：ファイル保存のルートディレクトリを絶対パスで指定します。ローカルストレージを選択した場合、マージ済みファイルの保存先として使用されます。

詳細設定

一般設定で選択したファイル保存方法に応じて、異なる詳細設定が用意されています。

ローカルストレージ

ファイルをローカルストレージにエクスポートする場合、以下の詳細設定を構成できます。

項目名	説明	推奨値
セグメント保存タイムアウト	segment コマンドでファイルセグメントを保存する最大許容時間。これを超えると（例：システム過負荷時）、エラーコード（0x80）付きPUBACKメッセージが送信されタイムアウトとなります。	5分
マージタイムアウト	fin コマンドでファイルマージ処理を完了する最大許容時間。タイムアウト時はエラーコード（0x80）付きPUBACKが送信されます。リソース制約下での遅延対策に重要です。	5分
ストレージGC間隔	ファイル保存システムのガベージコレクション実行間隔。不要データの削除によりストレージ管理を行います。	1時間
最大セグメントTTL	保存されたセグメントの最大有効期間。この期間を超えたセグメントは、完全ファイルにマージ済みか否かに関わらず自動的に削除されます。ファイル転送時に指定されたTTLより優先されます。	24時間
最小セグメントTTL	セグメントの最小有効期間。完全ファイルにマージ済み、またはファイル転送時に短いTTLが指定されていても、この期間までは削除されません。後処理や冗長性確保のために最低限の保持期間を保証します。	5分

S3ストレージ

S3ストレージにエクスポートする場合、ローカルストレージと共通の設定を除き、以下の詳細設定も構成可能です。

項目名	説明	推奨値
URL有効期限	S3にアップロードしたファイルにアクセスするために生成されるURLの有効期間。期限切れ後はURLでのアクセスができなくなります。	-
最小パートサイズ	S3のマルチパートアップロード時の各パートの最小サイズ。小さいとアップロード回数が増えますが、不安定な環境で大きなファイルを扱う際に有用です。	5MB
最大パートサイズ	マルチパートアップロードの各パートの最大サイズ。大きいとアップロード回数は減りますが、メモリ消費が増える可能性があります。	5MB
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を利用してファイルの閲覧やダウンロードが可能です。

ディスクエクスポートファイルの手動管理

ディスク上のエクスポート済みファイルを直接管理する場合（ファイル移動やFTP/HTTPサービスでのダウンロードなど）、以下のファイル保存場所のルールを参照してください。

ファイル名の重複や単一ディレクトリ内のファイル数過多を回避するため、EMQXはバケットストレージ方式でエクスポートファイルを保存しています。仕組みは以下の通りです。

• まず、ファイルIDとクライアントIDのsha256ハッシュ値を計算します（例：ABCDEFG012345...）。
• 6階層のディレクトリ構造でファイルを保存します。各階層は以下のように定義されます：
  1. ハッシュの最初の2バイトを1階層目のディレクトリ名とする
  2. 次の2バイトを2階層目のディレクトリ名とする
  3. 残りのハッシュを3階層目のディレクトリ名とする
  4. エスケープされたクライアントID
  5. エスケープされたファイルID
  6. メタデータのファイル名（最下層）

例えば、エクスポートファイルは以下のようなディレクトリ構造に保存されます：
AB/CD/EFGH.../{clientid}/{file_id}/{filename}

S3バケットエクスポートファイルの手動管理

S3バケットの場合は、S3クライアントツールやS3のREST APIを利用してファイルの削除やダウンロードなどの管理が可能です。ファイル保存場所のルールは以下の通りです。

ローカルエクスポーターのバケットストレージ方式とは異なり、S3エクスポーターでエクスポートされたファイルはよりシンプルな3階層構造で保存されます。

1. エスケープされたクライアントID
2. エスケープされたファイルID
3. ファイル名

例えば、エクスポートファイルは以下のようなディレクトリ構造に保存されます：
{clientid}/{file_id}/{filename}

TIP

S3クライアントツールやREST APIの利用方法については、以下のリソースを参照してください。

• Amazon S3 および ユーザーガイド
• MinIO オブジェクトストレージシステム