Eclipse Zenoh

Eclipse Zenoh：零开销的Pub/Sub、存储/查询和计算。

Zenoh（发音为 /zeno/）统一了运动中的数据、静止数据和计算。它将传统的pub/sub与地理分布式存储、查询和计算完美融合，同时保持了超越任何主流堆栈的时间和空间效率。

请访问网站 zenoh.io 和 路线图 获取更多信息。

InfluxDB后端

在Zenoh中，后端是一种存储技术（如DBMS、时序数据库、文件系统等），允许通过Zenoh存储键/值发布，并在查询时返回它们。有关更多信息，请参阅Zenoh文档。

此后端依赖于一个InfluxDB服务器来实现存储。Zenoh将依赖以下库名（不带特定于操作系统的前缀和扩展名）来找到并加载它：zenoh_backend_influxdb。

👉 安装最新版本：见下面

👉 构建"main"分支：见下面

:note: 此版本完全支持Influxdb 1.x，部分支持InfluxDB 2.x。

⚠️ 旧版本0.5的文档

以下是与"main"分支中当前正在开发的0.6.x版本相关的文档。

有关旧版本，请参阅相应标记版本的README和代码

• 0.5.0-beta.9
• 0.5.0-beta.8

使用示例

先决条件

• 您已安装了一个zenoh路由器（zenohd），并且zenoh_backend_influxdb库文件位于~/.zenoh/lib中。
• 您有一个正在运行的InfluxDB服务，并监听于https://127.0.0.1:8086

您可以通过配置文件在zenoh路由器启动时设置存储，或者通过zenoh管理空间在运行时设置，例如使用REST API。

通过JSON5配置文件设置

• 创建一个包含以下内容的zenoh.json5配置文件

  {
    plugins: {
      // configuration of "storage_manager" plugin:
      storage_manager: {
        volumes: {
          // configuration of a "influxdb" volume (the "zenoh_backend_influxdb" backend library will be loaded at startup)
          //this should be named influxdb for v1
          influxdb: {
            // URL to the InfluxDB service
            url: "https://127.0.0.1:8086",
            private: {
              //For Influxdb v1.x:
              // If needed: InfluxDB credentials, preferably admin for databases creation and drop
                //username: "admin",
                //password: "password"
              
              //For Influxdb v2.x:
              // If needed: InfluxDB credentials, preferably ALL-ACCESS for databases creation and drop
              //if not ALL-ACCESS then atleast with authorization to create/delete buckets
              //Note: this should not be left empty for the plugin to work; if you have no admin creds, you can copy the user creds instead
              //  token: "access token"
  
            }
          }
        },
        storages: {
          // configuration of a "demo" storage using the "influxdb" volume
          demo: {
            // the key expression this storage will subscribes to
            key_expr: "demo/example/**",
            // this prefix will be stripped from the received key when converting to database key.
            // i.e.: "demo/example/a/b" will be stored as "a/b"
            // this option is optional
            strip_prefix: "demo/example",
            volume: {
              //this will be influxdb for v1 (exactly the same name as in volumes section)
              id: "influxdb",
              // the database/bucket name within InfluxDB
              db: "zenoh_example",
              // if the database doesn't exist, create it
              create_db: false,
              // strategy on storage closure
              on_closure: "do_nothing",
              private: {
  
                //For Influxdb v1.x:
                //Required: InfluxDB credentials to read-write on the bucket
                //username: "admin",
                //password: "password"
              
              //For Influxdb v2.x:
                //Required 
                //InfluxDB credentials, with read/write privileges for the database
                  //this is a token with either:
                  //a.) Read-Write access to the existing DB named above in the config (case where db/bucket already exists)
                  //b.) Read-write access to ALL buckets in the organization so it can access the new bucket created by zenoh;
                              //(case where a new db/bucket has to be created)
                 // token: "user access token" 
              }
            }
          }
        }
      },
      // Optionally, add the REST plugin
      rest: { http_port: 8000 }
    }
  }
  

• 使用以下命令运行zenoh路由器
  zenohd-c zenoh.json5

通过curl命令在管理空间中运行时设置

• 运行zenoh路由器，拥有对其管理空间的读写权限
  zenohd--adminspace-permissions rw
• 添加“influxdb”卷（将加载“zenoh_backend_fs”库），连接到InfluxDB服务https://127.0.0.1:8086：curl -X PUT -H 'content-type:application/json' -d '{url:"https://127.0.0.1:8086"}' https://127.0.0.1:8000/@/router/local/config/plugins/storage_manager/volumes/influxdb
• 使用“influxdb”卷添加“demo”存储：curl -X PUT -H 'content-type:application/json' -d '{key_expr:"demo/example/**",volume:{id:"influxdb",db:"zenoh_example",create_db:true}}' https://127.0.0.1:8000/@/router/local/config/plugins/storage_manager/storages/demo

使用REST API进行测试

使用curl发布和查询键/值，您可以

# Put some values at different time intervals
curl -X PUT -d "TEST-1" https://127.0.0.1:8000/demo/example/test
curl -X PUT -d "TEST-2" https://127.0.0.1:8000/demo/example/test
curl -X PUT -d "TEST-3" https://127.0.0.1:8000/demo/example/test

# Retrive them as a time serie where '_time=[..]' means "infinite time range"
curl -g 'https://127.0.0.1:8000/demo/example/test?_time=[..]'

卷配置

基于InfluxDB的卷需要一些配置才能工作

• "url"（必需）: InfluxDB服务的URL。例如：https://127.0.0.1:8086

管理员级别的凭据

对于v1.x

• "username"（可选）: 一个InfluxDB管理员用户名。它将用于创建数据库、授权映射到存储的数据库的读写权限以及删除数据库和度量。

• "password"（可选）: 管理员用户的密码。

这两个username和password都应该隐藏在一个private对象后面，如上面所示示例。通常，如果您希望在查询配置时隐藏配置的一部分，您应该将其隐藏在一个private对象后面。

对于v2.x

• "token" (可选) : 管理用户的令牌。它将被用于创建和删除数据库。在Influxdb2.x中，您可以使用ALL ACCESS令牌（https://docs.influxdb.org.cn/influxdb/cloud/admin/tokens/#all-access-token）

该token应隐藏在private对象之后，如上例中的“用户名”和“密码”所示。一般来说，如果您希望在查询配置时隐藏配置的一部分，您应该将其隐藏在private对象之后。

特定卷的存储配置

依赖于由influxdb支持的卷的存储可能通过volume部分进行额外的配置

• "db" (可选，字符串) : 存储将映射到的InfluxDB数据库名。如果未指定，将生成随机名称，并创建相应的数据库（即使未设置"create_db"）。

• "create_db" (可选，布尔值) : 如果数据库不存在，则创建InfluxDB数据库。默认情况下，不会创建数据库，除非未指定"db"属性。（值无关紧要，只需检查属性是否存在）

• "on_closure" (可选，字符串) : 当存储被移除时使用的策略。有三个选项

  • 未设置或"do_nothing"：数据库保持不变（这是默认行为）
  • "drop_db"：删除数据库（即移除）
  • "drop_series"：删除所有系列（度量），数据库保持为空。

• "token" (可选，字符串) : InfluxDB访问令牌，通常是非管理员。它将用于GET/PUT/DELETE zenoh操作中的数据库中的读/写点。

后端的行为

映射到InfluxDB概念

每个storage将映射到InfluxDB的database。
每个要存储的key将映射到InfluxDB的以键去除"strip_prefix"属性（见下文）命名的measurement。
放入存储的每个key/value将映射到InfluxDB的point，重用zenoh设置的时标（但精度为纳秒）。点的字段和标签如下

• "kind"标签：zenoh更改类型（对已放入的值使用"PUT"，对标记键删除的操作使用"DEL"）
• "timestamp" 字段：原始zenoh时间戳
• "encoding" 字段：值的编码标志
• "base64" 字段：表示值是否以base64编码的布尔值
• "value" 字段：作为字符串的值，可能是二进制值以base64编码。

删除时的行为

在删除键时，所有在删除消息之前的时间戳的点都被删除。插入具有 "kind"="DEL" 的点（以避免无序消息时重新插入较旧时间戳的点）。在v1中，如果删除的键对应的测量值在5秒后仍然没有点，zenoh会丢弃它。然而，influxdb 2.x 不支持此功能。

GET操作时的行为

在GET操作中，默认情况下，存储只返回每个键/测量的最新点。这是为了与其他只存储每个键1个值的后端技术保持一致。
如果您想通过GET操作获取时间序列作为结果，您需要通过您的 选择器 中的 "_time" 参数指定时间范围。

:note: 目前，像 * 和 ** 这样的通配符块仅适用于 Influxdb 1.x。这是由于 Influxdb 2.x API 对我们的方法缺乏支持。

选择器的示例

  # get the complete time-series
  /demo/example/**?_time=[..]

  # get points within a fixed date interval
  /demo/example/influxdb/**?_time=[2020-01-01T00:00:00Z..2020-01-02T12:00:00.000000000Z]

  # get points within a relative date interval
  /demo/example/influxdb/**?_time=[now(-2d)..now(-1d)]

有关时间范围格式的完整描述，请参阅 "_time" RFC

如何安装它

要安装此后端库的最新版本，您可以按照以下步骤操作

手动安装（所有平台）

所有发布包都可以从以下网址下载

• https://download.eclipse.org/zenoh/zenoh-backend-influxdb/latest/

每个子目录都使用Rust目标命名。请参阅https://doc.rust-lang.net.cn/stable/rustc/platform-support.html上每个目标对应的平台

选择您的平台，下载 .zip 文件。
将其解压缩到与 zenohd 相同的目录中，或到任何可以找到后端库的目录中（例如 /usr/lib 或 ~/.zenoh/lib）

Linux Debian

将Eclipse Zenoh私有存储库添加到源列表，并安装 zenoh-backend-influxdb-v1 软件包

echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-influxdb-v1

如何构建它

⚠️ 警告 ⚠️ : Zenoh及其生态系统正在积极开发中。当您从git构建时，请确保您也构建您计划使用的任何其他Zenoh存储库（例如，绑定、插件、后端等）。可能会发生某些git中的更改与最新封装的Zenoh版本（例如deb、docker、pip）不兼容的情况。我们在维护Zenoh项目中的各个git存储库之间的兼容性方面付出了特别努力。

首先，安装 Cargo和Rust。如果您已经安装了Rust工具链，请确保它与以下内容保持最新

$ rustup update

⚠️ 警告 ⚠️ : 由于 Rust 没有稳定的 ABI，后端库应该使用与 zenohd 完全相同的 Rust 版本进行构建，并且使用与 zenoh 依赖相同的版本（或提交号）'zenohd'。否则，zenohd 和库之间共享类型内存映射的不兼容性可能导致 "SIGSEV" 崩溃。

要了解 zenohd 构建的 Rust 版本，请使用 --version 选项。

下载版本示例

$ zenohd --version
The zenoh router v0.10.0-rc built with rustc 1.72.0 (5680fa18f 2023-08-23)

在这里，zenohd 版本 0.10.0-rc 使用 rustc 版本 1.72.0 构建。
使用以下命令安装和使用此相同的工具链

$ rustup default 1.72.0

然后编辑更新 Cargo.toml 文件，使所有 zenoh 依赖项使用相同的版本号

zenoh = { version = "0.10.0-rc", features = [ "unstable" ] }

然后仅构建 v1 后端库，您必须在构建命令中指定它

$ cargo build --release --all-targets -p zenoh-backend-influxdb-v1

您也可以同时构建这两个版本

$ cargo build --release --all-targets

=======

从源代码构建的版本示例

$ zenohd --version
The zenoh router v0.11.0-dev-37-g9f7a37ee built with rustc 1.72.0 (5680fa18f 2023-08-23)

在这里，zenohd 版本是 v0.110-dev-37-g9f7a37ee，其中

• -v0.110-dev 表示它是未来 -v0.110 发布的开发版本
• -37 表示自 0.11.0-dev 标记此未来版本的开始以来的 37 次提交
• -g9f7a37ee 表示源代码的提交号：9f7a37ee（前缀 g 仅表示 "git"，应忽略）

$ rustup default 1.72.0

$ cargo update -p zenoh --precise 9f7a37ee