InfluxDB 3 Core 和 Enterprise 的 CLI 操作

作者：Anais Dotis-Georgiou / 开发者
2025 年 2 月 4 日

导航至

注意：此博客是为 InfluxDB 3 Core 和 Enterprise Alpha 版本编写的。请查看文档，因为当前 Beta 版本可能存在细微变化。

这篇博客深入探讨了基本的命令行工具和工作流程，以便有效地管理和与您的 InfluxDB 3 Core 和 Enterprise 实例交互。无论您是使用内存、文件或对象存储等配置启动或停止服务器，本指南都将引导您完成整个过程。我们还将了解如何使用身份验证令牌创建数据库并将数据写入数据库，探索直接行协议输入与基于文件的方法，以用于诸如测试之类的任务。您将学习如何使用 SQL 和 InfluxQL 高效地查询数据，设置诸如最后值缓存和元数据缓存之类的性能提升功能，并在必要时通过删除数据库和表来进行清理。让我们开始掌握 InfluxDB 3 Core 和 Enterprise CLI！

要求

本博客文章假定您满足以下要求：InfluxDB 3 Core 或 InfluxDB Enterprise。如果您刚刚入门，我建议从 InfluxDB 3 Core 开始。作为 InfluxDB 3 Enterprise 的开源版本，它是学习的坚实基础，并且是作为边缘数据收集器的绝佳选择。或者，您可以使用 Enterprise 的免费试用版，或者从 Core 升级到 Enterprise——Core 中的 CLI 命令与 Enterprise 中的命令完全相同。要从 Core 升级到 Enterprise，用户需要在安装 Core 的同一环境中下载并安装 InfluxDB 3 Enterprise 的免费试用模式或使用有效许可证的版本，确保它指向相同的对象存储。

使用单个 cURL 命令安装 CLI 后的图像。有选项可以作为简单下载或使用 docker 进行安装。

命名约定注意： 如果您是之前的 InfluxDB 用户，一些术语上的变化可能会令人困惑；请注意，以下术语是同义的

Bucket ↔ 数据库

Measurement ↔ 表

Field, Tags ↔ 列

首先获取 –-help

一旦您安装了 InfluxDB v3 OSS，influxdb3 命令行界面 (CLI) 将成为您与数据库交互的首选工具。这个多功能的 CLI 允许您管理您的 InfluxDB 实例，创建诸如数据库和令牌之类的资源，并执行诸如查询和写入数据之类的基本操作。运行 influxdb3 –-help 将提供命令和选项的完整列表，并提供示例以帮助您入门。无论您是使用 influxdb3 serve 设置服务器，使用 influxdb3 write 写入数据，还是使用 influxdb3 query 运行查询，此工具都可以简化您处理时间序列数据的过程。

以下是 influxdb3 –-help 输出中列出的每个命令的详细解释，以帮助您理解它们的目的和用法

  • serve：启动 InfluxDB 3 Core 或 Enterprise 服务器，这是使数据库运行的核心进程。
  • query：针对正在运行的 InfluxDB 3 Core 或 Enterprise 服务器执行查询，允许您检索和分析存储的数据。
  • write：将时间序列数据写入 InfluxDB 3 Core 或 Enterprise 服务器。此命令允许您手动或以编程方式从其他工具添加数据。
  • create：帮助您在 InfluxDB 实例中创建新资源，例如数据库或令牌。
  • help：显示 influxdb3 CLI 或特定命令的帮助信息。例如，influxdb3 query –-help 提供了 query 命令的详细使用说明。

使用不同的配置启动服务器

当您首次安装 InfluxDB 3 时，CLI 会引导您完成服务器配置选项。在初始设置之后，使用 serve 命令启动实例

influxdb3 serve --object-store file --data-dir ~/.influxdb3 --node-id node0

InfluxDB 3 默认在端口 8181 上运行，但是您可以添加 --http-bind='0.0.0.0:8181 来指定不同的端口。您还必须指定 --node-id 标识符，该标识符确定服务器在配置的存储位置内的存储路径。对于共享相同对象存储配置（例如，相同的 bucket）的任何节点，它必须是唯一的。Parquet 文件充当 InfluxDB 3 Core 和 Enterprise 的持久数据格式，使对象存储成为长期数据保留的首选解决方案。这种方法显著降低了存储成本，同时保持了出色的性能。--object-store 选项允许用户指定他们想要将 Parquet 文件写入的位置。您可以选择将这些文件写入内存、本地文件系统、Amazon S3、Azure Blob Storage、Google Cloud Storage 或任何云存储。云存储选项包括

  • memory（默认）：实际上没有对象持久性。
  • memorythrottled：类似于 memory，但具有在一定程度上类似于云对象存储的延迟和吞吐量。适用于测试和基准测试。
  • file：将对象存储在本地文件系统中。还必须设置 --data-dir。
  • s3：Amazon S3。还必须设置 --bucket、--aws-access-key-id、--aws-secret-access-key，并且可能需要设置 --aws-default-region。
  • google：Google Cloud Storage。还必须设置 --bucket 和 --google-service-account。
  • azure：Microsoft Azure blob storage。还必须设置 --bucket、--azure-storage-account 和 --azure-storage-access-key。

例如，我可以使用 serve 命令来启动实例，使用内存作为“对象存储”，命令如下：

influxdb3 serve --object-store memory --node-id node0

内存存储不提供永久对象存储，并且数据在重启时会被清除，但它是运行 InfluxDB 3 的最快方法。

创建一个数据库并使用普通令牌写入数据

现在我们准备好创建一个数据库并使用一个命令写入数据

influxdb3 write --database [your database name] --file [path to your line protocol data]`

例如，如果我们想写入以下行协议数据，我们可以使用

influxdb3 write --database airSensors --file /Desktop/airsensors.lp

其中 airsensors.lp 是一个文件，其中包含 行协议 数据，这是 InfluxDB 的摄取格式。您可以在此处找到一些行协议实时数据集。例如，您可以下载一些空气传感器数据，其外观如下：

airSensors,sensor_id=TLM0100 temperature=71.24021491535241,humidity=35.0752743309533,co=0.5098629816173851 1732669098000000000
airSensors,sensor_id=TLM0101 temperature=71.84309523593232,humidity=34.934199682459,co=0.5034259382294339 1732669098000000000
airSensors,sensor_id=TLM0102 temperature=71.95391915782443,humidity=34.92433120092046,co=0.5175197455105179 1732669098000000000

此数据集包含来自八个不同传感器的温度、一氧化碳和湿度数据。

或者，我们可以直接写入这些少量数据，而不是指向文件，命令如下：

influxdb3 write --database [your database name]
'airSensors,sensor_id=TLM0100 temperature=71.24021491535241,humidity=35.0752743309533,co=0.5098629816173851 1732669098000000000
airSensors,sensor_id=TLM0101 temperature=71.84309523593232,humidity=34.934199682459,co=0.5034259382294339 1732669098000000000
airSensors,sensor_id=TLM0102 temperature=71.95391915782443,humidity=34.92433120092046,co=0.5175197455105179 1732669098000000000'

使用 influxdb3 write 命令写入数据后，您应该看到以下确认信息

success

在此示例中，默认情况下，我们使用普通 Token 提供 InfluxDB 3 Core 服务。在下一节中，我们将学习如何使用 Hashed Token 将数据写入 InfluxDB 3 Core 或 Enterprise，以及两者之间的区别。

您可以使用 influxdb3 write 命令在写入时创建数据库。但是，您也可以选择使用 influxdb3 create database [您的数据库名称] 命令创建数据库。

使用身份验证令牌写入数据库

如果您想使用 HTTP API 或 SDK 访问您的数据，您需要创建一个令牌。要使用 InfluxDB CLI 创建令牌，您可以使用以下命令：influxdb3 create token

您应该看到以下输出

Token: apiv3_xxx
Hashed Token: zzz
Start the server with `influxdb3 serve --bearer-token zzz
HTTP requests require the following header: "Authorization: Bearer apiv3_xxx"
This will grant you access to every HTTP endpoint or deny it otherwise

现在，您可以选择使用 bearer-token 提供 influxdb3 服务

influxdb3 serve --object-store memory --bearer-token zzz --node-id node0

您还可以选择提供实例服务并将对象存储在本地文件系统中

influxdb3 serve --object-store file --data-dir ~/.influxdb3 --bearer-token zzz --node-id node0

哈希令牌是普通令牌的加密表示形式。通过将哈希令牌传递给服务器，您可以避免在命令行、日志或配置文件中暴露普通令牌。因此，当客户端在 HTTP 请求中发送普通 bearer 令牌时，服务器会对接收到的令牌进行哈希处理，并将哈希结果与您在启动时提供的哈希令牌进行比较。这确保了服务器可以安全地验证普通令牌，而无需直接存储或处理它。最佳实践是使用 Hashed Token 提供 InfluxDB 3 Core 和 Enterprise 服务。

现在我们正在使用 Hashed Token 提供服务，我们可以使用上面的相同 CLI 命令将数据写入数据库。或者，如果我们想使用 cURL 写入，我们可以执行以下操作

curl \
"http://127.0.0.1:8181/api/v2/write?bucket=[your database name]&precision=s" \
--header "Authorization: Bearer zzz" \
--data-binary 'home,room=kitchen temp=72 1732669098'

使用 InfluxQL 和 SQL 查询数据

现在我们准备好使用 SQL 查询我们的 InfluxDB 3 Core 实例

influxdb3 query --database=[your database name] "SELECT * FROM airSensors LIMIT 10"

如果您是现有的 InfluxDB 用户，并且更熟悉 InfluxQL 语言，您也可以选择将语言设置为 InfluxQL 而不是 SQL。只需使用以下命令指定语言：--language=influxql

influxdb3 query --database=[your database name] --language=influxql "SHOW MEASUREMENTS"

使用 InfluxDB 3 CLI 查询 InfluxQL 的输出。

设置最后值缓存和去重值缓存

InfluxDB 3 Core 支持 last-n 值缓存 (LVC)，它将序列或列层次结构中的最后 N 个值存储在内存中，以及一个去重值缓存，它在 RAM 中保留单个列或列层次结构的唯一值。最后值缓存允许 InfluxDB 3 在 10 毫秒内响应 last-n 值查询，而去重值缓存非常适合快速元数据查找。

在未来的博客文章中，我们将深入研究这些缓存的性能基准测试，但对于这篇博客，让我们专注于创建和使用它们。创建两种缓存的过程几乎相同，因此让我们通过使用以下命令创建最后值缓存来演示该过程

influxdb3 create last_cache --database [your database name] --table [your database table] [CACHE_NAME]

[CACHE_NAME] 是可选的，如果未提供，该命令将自动生成名称。因此，例如，如果我们想为 airSensors 表/measurement 创建一个最后值缓存。

influxdb3 create last_cache --database [your database name] --table airSensors airSensorsLVC

您应该看到以下输出

new cache created: {
  "table": "airSensors",
  "name": "airSensorsLVC",
  "key_columns": [
    0
  ],
  "value_columns": "all_non_key_columns",
  "count": 1,
  "ttl": 14400
}

现在我们可以返回利用缓存的最后 10 个值，命令如下：

influxdb3 query --database=[your database name] "SELECT * FROM last_cache(airSensors, airSensorsLVC) LIMIT 10"

最后值缓存很有用，因为它能够快速、高效地访问特定键列值组合的最新数据。这有助于用户确保他们拥有最新的数据用于警报或决策。当您处理基于事件的时间序列应用程序（您不定期写入数据子集）时，它也非常有用。在这种情况下，您希望避免对专注于最新值的查询进行历史数据的完整扫描。

为 foo 创建最后值缓存

为了更好地理解该输出，我们需要深入研究我们在 LVC 创建期间未使用的其他 create last_cache 选项。create last_cache 命令具有以下选项，如文档中所述

  • --key-columns：用作缓存中键的逗号分隔的列列表。例如：foo,bar,baz。这提供了缓存的顶层。
  • --value-columns：要作为缓存中的值存储的逗号分隔的列列表。例如：foo,bar,baz。在层次结构的叶节点（或终端节点）处，维护一个缓冲区以存储值。缓冲区大小由 --count 参数确定。
  • --count：每个唯一键列组合要存储在缓存中的条目数。此处的最大数字可以是 10。
  • --ttl：缓存条目的生存时间 (TTL)，采用 Humantime 格式——例如：10s, 1min 30sec, 3 hours。如果缓冲区中的任何条目存在时间超过 TTL，则无论缓冲区大小和包含多少条目，都将删除该条目。

写入数据时，值将添加到与键列值的匹配组合对应的缓冲区中。例如，假设我们使用以下命令创建一个缓存：influxdb3 create last_cache --database [您的数据库名称] --table [您的数据库表] --key-columns t1,t2 --value-columns f1 --count 5

考虑以下行协议数据，其中 1 表示在第一个时间戳写入的数据

foo,t1=A,t2=A f1=1 1 
foo,t1=A,t2=B f1=2 1 
foo,t1=B,t2=C f1=3 1 
foo,t1=B,t2=D f1=4 1

数据将以下列方式添加到缓存中的缓冲区： 用于组织数据的分层缓存结构，具有基于键列的最后值缓存，并在 InfluxDB 3 的缓冲区中存储值。

现在假设我们写入另一行数据：foo,t1=A,t2=A f1=2 2。现在我们看到它已添加到以下缓冲区

仅当值的时间比其各自缓冲区的最新值更新时，才会缓冲这些值。

去重值缓存的运行方式与最后值缓存类似，但文档中说明了以下选项差异

  • --columns（必需）：要缓存去重值的逗号分隔的列列表。例如：col1,col2,col3。
  • --max-cardinality：缓存中要保存的去重值组合的最大数量。
  • --max-age：缓存中条目的最大存在时间，以人类可读的持续时间形式输入。例如：30d, 24h。

如上所述，去重值缓存最适合快速元数据查找。它们通过遍历缓存结构，并查找与查询中的键匹配的叶节点，帮助将查询引导到正确的数据子集。例如，在物联网场景中，这可以帮助开发人员快速检查特定传感器（可能是跨多个工厂的数千个相同传感器之一）是否正在报告数据并按预期运行。

删除

我们还可以使用influxdb3 delete 命令来删除数据库、去重值缓存、数据库的文件索引、最后值缓存、插件、数据库中的表和触发器。我们将在下一篇博客文章中详细了解插件和触发器。但是，让我们删除我们创建的数据库，命令如下：

influxdb3 delete database [您的数据库名称]

停止服务器

最后，如果您想停止运行 influxdb3 服务器，您可以首先通过返回 PID 来终止该进程，命令如下：

pgrep influxdb3

然后使用

kill [PID]

最终想法

我希望这篇博客文章能够帮助您开始使用 InfluxDB 3 Core 或 Enterprise。在即将发布的博客文章中，我们将学习如何为 InfluxDB 3 Enterprise 的处理引擎创建 Python 插件，这也是通过 CLI 控制的功能。与往常一样，请从此处开始使用 InfluxDB 3 Cloud，并在此处开始使用 Core 和 Enterprise。如果您需要帮助，请通过我们的社区站点或 Slack 频道联系我们。如果您也在进行 InfluxDB 数据处理项目，我很乐意与您交流！