EMQX 文档

简体中文

English

简体中文

English

Appearance

联系我们

快速体验 MQTT 文件传输 ​

本页提供了在 EMQX 中快速开始使用 MQTT 文件传输功能的指南。它涵盖了两种场景：使用本地磁盘和使用 S3 存储桶进行文件存储。

您可以按照以下说明在 EMQX 启用文件传输功能、使用客户端上传文件并通过 EMQX 提供的 API 访问上传的文件。

上传文件并将其存储在本地磁盘 ​

  1. 在 EMQX 配置文件 etc/emqx.conf 中添加以下配置启用文件传输功能，并启动 EMQX：

    bash
    file_transfer {
   enable = true
}

    该配置使用本地磁盘存储上传的分片文件，传输完成后并不会对分片文件进行合并。

  2. 运行以下命令下载文件传输示例程序 emqx-ft，并设置测试客户端环境：

    bash
    git clone https://github.com/emqx/emqx-ft.git
cd emqx-ft
python3 -m venv .venv
source .venv/bin/activate
pip install .

  3. 使用 emqx-ft 命令行工具运行以下命令以上传文件：

    bash
    emqx-ft --file test-file.txt \
   --file-id file-id-1 --segment-size 10 \
   --client-id client-1 \
   --file-name uploaded-test-file.txt

    命令参数说明：

    参数含义
    --file要上传的文件的路径。
    --file-id上传文件的唯一标识符。
    --segment-size文件的分片大小，以字节为单位，该参数用于将大文件分成较小的段进行上传。
    --client-id客户端 ID，用于标识进行文件上传操作的客户端。
    --file-name上传后的文件名。

  4. 运行以下命令列出已上传的分片文件：

    bash
    $ tree /var/lib/emqx/file_transfer/exports
/var/lib/emqx/file_transfer/exports
_./data/file_transfer/exports
├── 8E
│   └── B5
│       └── 7023DA998C12F0B2A6CA586027E48BEC6271
│           └── client-1
│               └── file-id-1
│                   ├── uploaded-test-file.txt
│                   └── uploaded-test-file.txt.MANIFEST.json
└── tmp

  5. 使用 REST API 列出已上传文件列表，列表包含已上传文件的详细信息，包括名称、大小和时间戳：

    bash
    $ curl -u '...' -s 'http://127.0.0.1:18083/api/v5/file_transfer/files' | jq
{
  "files": [
    {
      "clientid": "client-1",
      "fileid": "file-id-1",
      "metadata": {
        "checksum": "8CFE0BE8A1A5C9BF0F019ABAA8AEEA5D1E26251A0B000883C8875C99A5CFF2F8",
        "name": "uploaded-test-file.txt",
        "size": 168
      },
      "name": "uploaded-test-file.txt",
      "size": 168,
      "timestamp": "2023-06-13T00:43:25+02:00",
      "uri": "/api/v5/file_transfer/file?node=emqx%40127.0.0.1&fileref=8E%2FB5%2F7023DA998C12F0B2A6CA586027E48BEC6271%2Fclient-1%2Ffile-id-1%2Fuploaded-test-file.txt"
    }
  ]
}

  6. 运行以下命令以使用提供的 API 下载文件：

    bash
    curl -u '...' -s 'http://127.0.0.1:18083/api/v5/file_transfer/file?node=emqx%40127.0.0.1&fileref=8E%2FB5%2F7023DA998C12F0B2A6CA586027E48BEC6271%2Fclient-1%2Ffile-id-1%2Fuploaded-test-file.txt'

上传文件并将其存储在 S3 存储桶 ​

文件传输允许将已上传的文件导出到兼容 S3 的对象存储系统，如 Amazon S3 和 MinIO。在使用 S3 存储桶的情况下，EMQX 仅存储文件传输列表，而不存储文件本身。

  1. 在 EMQX 配置文件 etc/emqx.conf 中启用文件传输功能并配置 S3 存储桶，并启动 EMQX：

    bash
    file_transfer {
   # 启用文件传输功能
   enable = true

   # 启用 s3 存储桶文件导出
   storage.local.exporter.s3 {
      host = "s3.us-east-1.amazonaws.com"
      port = 443

      # 用于访问 S3 的凭证
      access_key_id = "AKIA27EZDDM9XLINWXFE"
      secret_access_key = "******"

      # 导出文件存储桶
      bucket = "my-bucket"

      # 用于与 S3 的底层 HTTP(S) 连接的设置，允许安全文件上传和连接池管理。
      transport_options {
         ssl.enable = true
         connect_timeout = 15s
      }
   }
}

  2. 运行以下命令下载文件传输示例程序 emqx-ft，并设置测试客户端环境：

    bash
    git clone https://github.com/emqx/emqx-ft.git
cd emqx-ft
python3 -m venv .venv
source .venv/bin/activate
pip install .

  3. 使用 emqx-ft 命令行工具运行以下命令以上传文件：

    bash
    emqx-ft --file test-file.txt \
   --file-id file-id-1 --segment-size 10 \
   --client-id client-1 \
   --file-name uploaded-test-file.txt

    命令参数说明：

    参数含义
    --file要上传的文件的路径。
    --file-id上传文件的唯一标识符。
    --segment-size文件的分片大小，以字节为单位，该参数用于将大文件分成较小的段进行上传。
    --client-id客户端 ID，用于标识进行文件上传操作的客户端。
    --file-name上传后的文件名。

  4. 使用 S3 命令行工具运行以下命令，手动列出已上传的文件：

    请确保已安装并正确配置了s3cmd，您可以参考 Official s3cmd repo 获取更多信息。

    bash
    $ s3cmd ls -r s3://YOURBUCKET/
2023-06-12 22:58          168  s3://YOURBUCKET/client-1/file-id-1/uploaded-test-file.txt

    输出将显示指定 S3 存储桶中的文件。

  5. 运行以下命令，使用 REST API 列出已上传文件的列表。

    bash
    $ curl -u '...' -s 'http://127.0.0.1:18083/api/v5/file_transfer/files' | jq
{
  "files": [
    {
      "clientid": "client-1",
      "fileid": "file-id-1",
      "name": "uploaded-test-file.txt",
      "size": 168,
      "timestamp": "2023-06-13T00:58:53+02:00",
      "uri": "https://s3.eu-north-1.amazonaws.com/YOURBUCKET/client-1/file-id-1/uploaded-test-file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-SignedHeaders=host&X-Amz-Signature=..."
    }
  ]
}

  6. 运行以下命令，使用提供的 URI 直接从 S3 存储下载文件。

    TIP

    在使用 S3 存储桶的情况下，提供的下载链接不会指向 EMQX，而是直接指向 S3 存储，因此文件不会存储在 EMQX 本地。

    bash
    curl "https://s3.eu-north-1.amazonaws.com/YOURBUCKET/client-1/file-id-1/uploaded-test-file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-SignedHeaders=host&X-Amz-Signature=..."