InfluxDB 3 Core 配置选项

InfluxDB 3 Core 允许您通过使用 influxdb3 命令选项或设置环境变量来自定义配置。

配置您的服务器

通过命令选项或环境变量传递配置选项。命令选项优先于环境变量。

全局选项与服务器特定选项

有些选项是全局的（在命令之前指定），而另一些是服务器特定的（在 serve 之后指定）。

• 全局选项：适用于 influxdb3 CLI 本身（例如，--num-io-threads）。
• 服务器选项：仅适用于 serve 命令（例如，--node-id、--object-store、--verbose）。

带全局和服务器特定选项的示例命令

influxdb3 --num-io-threads=4 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --verbose \
  --log-filter info

示例环境变量

export INFLUXDB3_NODE_IDENTIFIER_PREFIX=my-node
export INFLUXDB3_OBJECT_STORE=file
export INFLUXDB3_DB_DIR=~/.influxdb3
export LOG_FILTER=info

influxdb3 serve

全局配置选项

以下选项全局适用于 influxdb3 CLI，必须在任何子命令（例如 serve）之前指定。

num-io-threads

设置分配给 IO 运行时线程池的线程数。IO 线程处理 HTTP 请求服务、行协议解析和文件操作。

# Set IO threads (global option before serve)
influxdb3 --num-io-threads=8 serve --node-id=node0 --object-store=file

服务器配置选项

• 通用

• 安全性

• AWS

• Google Cloud Service

• Microsoft Azure

• 对象存储

• 日志

• 跟踪

• DataFusion

• HTTP

• Memory

• 写前日志 (WAL)

• 压缩

• 缓存

• 处理引擎

• 资源限制

• 数据生命周期管理

• 遥测

• TCP 监听器

通用

• data-dir

• node-id

• object-store

• query-file-limit

data-dir

对于 file 对象存储，定义 InfluxDB 3 Core 用于在本地存储文件的位置。在使用 file 对象存储时必需。

node-id

指定用作所有对象存储文件路径前缀的节点标识符。对于共享相同对象存储配置（例如，相同存储桶）的任何主机，此值应唯一。

object-store

指定用于存储 Parquet 文件的对象存储。此选项支持以下值：

• memory：实际上没有对象持久化。
• memory-throttled：类似于 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）。

安全性

• tls-key
• tls-cert
• tls-minimum-versions
• without-auth
• disable-authz
• admin-token-recovery-http-bind
• admin-token-file

tls-key

用于启用 TLS 的密钥文件的路径。

tls-cert

用于启用 TLS 的证书文件的路径。

tls-minimum-version

TLS 的最低版本。有效值为 tls-1.2 或 tls-1.3。默认为 tls-1.2。

without-auth

禁用所有服务器操作（CLI 命令和 API 请求）的身份验证。服务器在不要求令牌或身份验证的情况下处理所有请求。

disable-authz

通过传递逗号分隔的资源列表，可以选择禁用授权。有效值为 health、ping 和 metrics。

admin-token-recovery-http-bind

在单独的端口上启用管理员令牌恢复 HTTP 服务器。此服务器允许在没有现有身份验证的情况下重新生成丢失的管理员令牌。服务器在成功重新生成令牌后自动关闭。

默认值： 127.0.0.1:8182（启用时）

示例用法

# Start server with recovery endpoint
influxdb3 serve --admin-token-recovery-http-bind

# In another terminal, regenerate the admin token
influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182

admin-token-file

指定一个离线管理员令牌文件，如果服务器启动时不存在任何令牌，则使用该文件。启动后，您可以使用提供的令牌与服务器进行交互。离线管理员令牌旨在帮助自动化部署。

离线管理员令牌定义在 JSON 格式的文件中。使用以下命令生成离线管理员令牌文件：

influxdb3 create token --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file 
./path/to/admin-token.json

{
  "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
  "name": "example-admin-token",
  "expiry_millis": 1756400061529
}

示例用法

# Generate an admin token offline
influxdb3 create token \
  --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file 
./path/to/admin-token.json

# Start InfluxDB 3 Core using the generated token
influxdb3 serve --admin-token-file 
./path/to/admin-token.json

AWS

• aws-access-key-id
• aws-secret-access-key
• aws-default-region
• aws-endpoint
• aws-session-token
• aws-allow-http
• aws-skip-signature
• aws-credentials-file

aws-access-key-id

当使用 Amazon S3 作为对象存储时，将其设置为具有读取和写入指定 S3 存储桶权限的访问密钥。

aws-secret-access-key

当使用 Amazon S3 作为对象存储时，将其设置为与指定访问密钥 ID 对应的秘密访问密钥。

aws-default-region

当使用 Amazon S3 作为对象存储时，将其设置为与指定存储桶对应的区域，如果与回退值不同。

默认值： us-east-1

aws-endpoint

当使用兼容 Amazon S3 的存储服务时，将其设置为端点。

aws-session-token

当使用 Amazon S3 作为对象存储时，将其设置为会话令牌。当使用联合登录或 SSO 并通过 UI 获取凭据时，此功能非常有用。

aws-allow-http

允许与 AWS 进行未加密的 HTTP 连接。

aws-skip-signature

如果启用，S3 对象存储不会获取凭据，也不会签署请求。

aws-credentials-file

指定您的 S3 凭据文件的路径。在使用凭据文件时，文件中的设置会覆盖相应的 CLI 标志。

S3 凭据文件为 JSON 格式，应包含以下内容：

{
  "aws_access_key_id": "
AWS_ACCESS_KEY_ID
",
  "aws_secret_access_key": "
AWS_SECRET_ACCESS_KEY
",
  "aws_session_token": "
AWS_SESSION_TOKEN
",
  "expiry": "
UNIX_SECONDS_TIMESTAMP
"
}

aws_session_token 和 expiry 字段是可选的。文件会在到期时间或每小时的间隔进行自动检查更新。

如果对象存储返回“未授权”错误，InfluxDB 将尝试从该文件更新其内存中的凭据，然后重试对象存储请求。

Google Cloud Service

• google-service-account

google-service-account

当使用 Google Cloud Storage 作为对象存储时，将其设置为包含 Google 凭据的 JSON 文件的路径。

Microsoft Azure

• azure-storage-account
• azure-storage-access-key
• azure-endpoint
• azure-allow-http

azure-storage-account

当使用 Microsoft Azure 作为对象存储时，将其设置为在导航到所有服务 > 存储帐户 > [名称] 时看到的名称。

azure-storage-access-key

当使用 Microsoft Azure 作为对象存储时，将其设置为存储帐户设置 > 访问密钥中的一个密钥值。

azure-endpoint

当使用 Microsoft Azure 作为对象存储时，将其设置为 Azure Blob Storage 端点。

azure-allow-http

当使用 Microsoft Azure 作为对象存储时，允许向 Azure Blob Storage 发送未加密的 HTTP 请求。

默认值： false

对象存储

• bucket
• object-store-connection-limit
• object-store-http2-only
• object-store-http2-max-frame-size
• object-store-max-retries
• object-store-retry-timeout
• object-store-cache-endpoint

bucket

设置要使用的对象存储存储桶的名称。还必须将 --object-store 设置为云对象存储才能使此选项生效。

object-store-connection-limit

当使用基于网络的[^1]对象存储时，将连接数限制为此值。

默认值： 16

object-store-http2-only

强制与基于网络的[^1]对象存储建立 HTTP/2 连接。

object-store-http2-max-frame-size

设置 HTTP/2 连接的最大帧大小（以字节为单位）。

object-store-max-retries

定义重试请求的最大次数。

object-store-retry-timeout

指定自初始请求以来不再尝试重试的最长时间。

object-store-cache-endpoint

设置兼容 S3 的 HTTP/2 对象存储缓存的端点。

日志

• log-filter
• log-destination
• log-format
• query-log-size

log-filter

设置日志的过滤器指令。

log-destination

指定日志的去向。

此选项支持以下值：

• stdout （默认）
• stderr

默认值： stdout

log-format

定义日志的消息格式。

此选项支持以下值：

• full （默认）

默认值： full

query-log-size

定义查询日志的大小。在旧查询被驱逐以腾出空间给新查询之前，最多保留此数量的查询。

默认值： 1000

跟踪

• traces-exporter
• traces-exporter-jaeger-agent-host
• traces-exporter-jaeger-agent-port
• traces-exporter-jaeger-service-name
• traces-exporter-jaeger-trace-context-header-name
• traces-jaeger-debug-name
• traces-jaeger-tags
• traces-jaeger-max-msgs-per-second

traces-exporter

设置跟踪导出器的类型。

默认值： none

traces-exporter-jaeger-agent-host

指定用于跟踪的 Jaeger 代理网络主机名。

默认值： 0.0.0.0

traces-exporter-jaeger-agent-port

定义用于跟踪的 Jaeger 代理网络端口。

默认值： 6831

traces-exporter-jaeger-service-name

设置用于跟踪的 Jaeger 服务名称。

默认值： iox-conductor

traces-exporter-jaeger-trace-context-header-name

指定用于传递跟踪上下文的标头名称。

默认值： uber-trace-id

traces-jaeger-debug-name

指定用于强制采样跟踪的标头名称。

默认值： jaeger-debug-id

traces-jaeger-tags

定义一组 key=value 对，用于注释跟踪跨度。

traces-jaeger-max-msgs-per-second

指定每秒发送到 Jaeger 服务的最大消息数。

默认值： 1000

DataFusion

• datafusion-num-threads
• datafusion-max-parquet-fanout
• datafusion-use-cached-parquet-loader
• datafusion-config

datafusion-num-threads

设置要使用的 DataFusion 运行时线程的最大数量。

datafusion-max-parquet-fanout

当需要以排序方式处理多个 Parquet 文件时（例如，去重），指定最大扇出。

默认值： 1000

datafusion-use-cached-parquet-loader

读取对象存储中的 Parquet 文件时，使用缓存的 Parquet 加载器。

datafusion-config

提供自定义配置到 DataFusion，作为逗号分隔的 key:value 对列表。

HTTP

• max-http-request-size
• http-bind

max-http-request-size

指定 HTTP 请求的最大大小。

默认值： 10485760

http-bind

定义 InfluxDB 提供 HTTP API 请求的地址。

默认值： 0.0.0.0:8181

Memory

• exec-mem-pool-bytes
• force-snapshot-mem-threshold

exec-mem-pool-bytes

指定用于查询处理和数据操作的内存池大小。InfluxDB 3 Core 处理查询和执行内部数据管理任务时使用此内存池。可以按字节的绝对值或按总可用内存的百分比给出，例如：8000000000 或 10%。

默认值： 8589934592

force-snapshot-mem-threshold

指定内部内存缓冲区的阈值。支持百分比（可用内存的一部分）或兆字节的绝对值，例如：70% 或 1000。

默认值： 70%

写前日志 (WAL)

• wal-flush-interval
• wal-snapshot-size
• wal-max-write-buffer-size
• snapshotted-wal-files-to-keep
• wal-replay-fail-on-error
• wal-replay-concurrency-limit

wal-flush-interval

指定将缓冲数据刷新到 WAL 文件的间隔。等待 WAL 确认的写入操作最多需要此间隔才能完成。使用 s 表示秒或 ms 表示毫秒。对于本地磁盘，建议使用 100 ms。

默认值： 1s

wal-snapshot-size

定义在快照中尝试删除的 WAL 文件数量。此数量乘以间隔，决定了快照的频率。

默认值： 600

wal-max-write-buffer-size

指定在必须执行并成功刷新之前可以缓冲的写入请求的最大数量。

默认值： 100000

snapshotted-wal-files-to-keep

指定在对象存储中保留的快照 WAL 文件数量。刷新 WAL 文件不会立即清除 WAL 文件；当快照 WAL 文件的数量超过此数量时，它们将被删除。

默认值： 300

wal-replay-fail-on-error

确定 WAL 重放是否应在遇到错误时失败。

默认值： false

wal-replay-concurrency-limit

WAL 重放期间的并发限制。设置此数字过高可能导致 OOM。默认值是动态确定的。

默认值： max(num_cpus, 10)

压缩

• gen1-duration

gen1-duration

指定 Parquet 文件的排列持续时间。数据时间戳会将每一行放入此持续时间的文件中。支持的持续时间为 1m、5m 和 10m。这些文件被称为“第一代”文件，InfluxDB 3 Enterprise 中的压缩器可以将其合并为更大的代。

默认值： 10m

缓存

• preemptive-cache-age

• parquet-mem-cache-size

• parquet-mem-cache-prune-percentage

• parquet-mem-cache-prune-interval

• parquet-mem-cache-query-path-duration

• disable-parquet-mem-cache

• table-index-cache-max-entries

• table-index-cache-concurrency-limit

• last-cache-eviction-interval

• distinct-cache-eviction-interval

preemptive-cache-age

指定在压缩期间预取到 Parquet 缓存的间隔。

默认值： 3d

parquet-mem-cache-size

指定 Parquet 内存缓存的大小。接受兆字节的值（作为整数）或总可用内存的百分比（例如，20%，4096）。

默认值： 20%

parquet-mem-cache-prune-percentage

指定在 Parquet 内存缓存的修剪操作期间要修剪的条目百分比。

默认值： 0.1

parquet-mem-cache-prune-interval

设置检查 Parquet 内存缓存是否需要修剪的间隔。

默认值： 1s

parquet-mem-cache-query-path-duration

指定

缓存最近 Parquet 文件在内存中的时间窗口。默认值为 5h。

只有包含时间戳在 now 和 now - duration 之间的数据的文件才会在查询期间被缓存，例如，使用默认的 5h 设置。

• 当前时间：2024-06-10 15:00:00
• 缓存窗口：最近 5 小时（2024-06-10 10:00:00 到现在）

如果查询请求的数据来自 2024-06-09（旧）和 2024-06-10 14:00（近）

• 已缓存：数据时间戳在 5 小时窗口内（2024-06-10 14:00）的 Parquet 文件
• 未缓存：数据时间戳不在 5 小时窗口内（2024-06-09）的 Parquet 文件

disable-parquet-mem-cache

禁用 Parquet 内存缓存。默认情况下，缓存是启用的。

table-index-cache-max-entries

指定表索引缓存的最大条目数。

默认值： 1000

table-index-cache-concurrency-limit

限制表索引缓存操作的并发级别。

默认值： 8

last-cache-eviction-interval

指定从 Last-N-Value 缓存中逐出过期条目的间隔，表示为人类可读的持续时间，例如：20s、1m、1h。

默认值： 10s

distinct-cache-eviction-interval

指定从不同值缓存中逐出过期条目的间隔，表示为人类可读的持续时间，例如：20s、1m、1h。

默认值： 10s

query-file-limit

限制查询可以访问的 Parquet 文件数量。如果查询尝试读取的数量超过此限制，InfluxDB 3 Core 将返回错误。

默认值： 432

使用默认的 432 设置和 10 分钟的默认 gen1-duration 设置，查询可以访问最多 72 小时的数据，但具体取决于在同一时间段内是否摄取了给定 10 分钟块的所有数据。

您可以增加此限制以允许查询更多文件，但请注意以下副作用：

• 查询性能下降，特别是对于读取更多 Parquet 文件的查询。
• 内存使用量增加。
• 系统因内存不足 (OOM) 错误而终止 influxdb3 进程。
• 如果使用对象存储来存储数据，则会产生大量 GET 请求来访问数据（每个文件最多 2 个）。

处理引擎

• plugin-dir
• plugin-repo
• virtual-env-location
• package-manager

plugin-dir

指定包含 Python 插件及其测试文件的本地目录。

plugin-repo

指定用于引用带有 gh: 前缀的插件的远程存储库的基 URL。当您创建带有以 gh: 开头的插件文件名触发器时，InfluxDB 会从该存储库 URL 获取插件代码。

URL 构建会自动处理尾部斜杠—这两种格式功能相同：

• https://example.com/plugins/（带尾部斜杠）
• https://example.com/plugins（不带尾部斜杠）

默认值： 官方 InfluxDB 3 插件存储库 https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/

示例用法

# Use a custom organization repository
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://raw.githubusercontent.com/myorg/influxdb-plugins/main/"

# Use an internal mirror
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://internal.company.com/influxdb-plugins/"

# Set via environment variable
export INFLUXDB3_PLUGIN_REPO="https://custom-repo.example.com/plugins/"
influxdb3 serve --plugin-dir ~/.plugins

virtual-env-location

指定处理引擎使用的 Python 虚拟环境的位置。

package-manager

指定处理引擎用于安装插件依赖项的 Python 包管理器。

此选项支持以下值：

• discover（默认）：自动检测并使用可用的包管理器（uv 或 pip）。
• pip：仅使用 pip 包管理器。
• uv：仅使用 uv 包管理器。
• disabled：禁用自动包安装（所有依赖项必须预先安装）。

默认值： discover

安全模式（已禁用）

当设置为 disabled 时，InfluxDB 3 Core 会出于安全和合规性要求阻止所有包安装尝试。处理引擎和插件继续正常运行，但包安装请求（通过 CLI 或 API）会返回 403 Forbidden 错误。

此模式专为以下场景设计：

• 企业安全要求：防止任意包安装。
• 合规环境：精确控制可用包。
• 隔离部署：在部署前预装所有依赖项。
• 多租户场景：防止租户安装潜在的恶意包。

示例

# Start InfluxDB 3 with disabled package manager
influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --plugin-dir ~/.plugins \
  --package-manager disabled

有关插件和包管理的更多信息，请参阅 处理引擎插件。

资源限制

• datafusion-num-threads
• num-io-threads - 请参阅 全局配置选项。 | |

datafusion-num-threads

设置分配给 DataFusion 运行时线程池的线程数。DataFusion 线程处理：

• 查询执行和处理
• 数据聚合和转换
• 快照创建（排序/去重操作）
• Parquet 文件生成

默认值： 所有可用核心减去 IO 线程。

数据生命周期管理

• gen1-lookback-duration
• retention-check-interval
• delete-grace-period
• hard-delete-default-duration

gen1-lookback-duration

指定创建第一代 Parquet 文件时要回溯的时间。

默认值： 24h

retention-check-interval

检查和强制执行保留策略的间隔。输入为人类可读的时间，例如：30m 或 1h。

默认值： 30m

delete-grace-period

指定永久删除数据之前的宽限期。

默认值： 24h

hard-delete-default-duration

设置数据硬删除的默认持续时间。

默认值： 90d

遥测

• disable-telemetry-upload
• telemetry-endpoint

disable-telemetry-upload

禁用向 InfluxData 上传遥测数据。

默认值： false

telemetry-endpoint

指定遥测数据上传的端点。

TCP 监听器

• tcp-listener-file-path
• admin-token-recovery-tcp-listener-file-path

tcp-listener-file-path

指定 TCP 监听器配置的文件路径。

admin-token-recovery-tcp-listener-file-path

指定管理员令牌恢复操作的 TCP 监听器文件路径。