InfluxDB 3 Core 配置选项

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

配置服务器

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

TOML 配置文件

DEB 和 RPM 安装包包含一个位于 /etc/influxdb3/influxdb3-core.conf 的 TOML 配置文件。systemd 启动程序会读取此文件，并在调用 influxdb3 serve 之前，将每个条目转换为 INFLUXDB3_* 环境变量（转换模式为 INFLUXDB3_<KEY>，并将连字符替换为下划线并转换为大写）。

influxdb3 serve 目前尚不支持原生读取 TOML；该文件的作用是通过启动程序设置的环境变量来实现的。传递给 influxdb3 serve 的 CLI 标志仍然会覆盖 TOML 文件中定义的值，因为它们会覆盖该文件所转换成的环境变量。

有关日常的 systemd 操作（包括应用更改时的“编辑并重启”工作流程），请参阅 作为系统服务运行 (Linux)。

全局选项与 serve 特定选项

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

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

包含全局选项和 serve 特定选项的示例命令

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 INFLUXDB3_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

• 对象存储

• 日志

• 跟踪 (Traces)

• DataFusion

• HTTP

• Memory

• 预写日志 (WAL)

• 压缩 (Compaction)

• 缓存

• 处理引擎

• 资源限制

• 数据生命周期管理

• 遥测

• 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 存储（必须同时设置 --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 字段是可选的。系统会在过期时间或每 1 小时自动检查文件更新。

如果对象存储返回“未认证”错误，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 存储终端节点。

azure-allow-http

使用 Microsoft Azure 作为对象存储时，允许对 Azure Blob 存储进行未加密的 HTTP 请求。

默认值： false

对象存储

• bucket
• object-store-connection-limit
• object-store-http2-only
• object-store-http2-max-frame-size
• object-store-request-timeout
• object-store-max-retries
• object-store-retry-timeout
• object-store-cache-endpoint
• object-store-tls-allow-insecure
• object-store-tls-ca

bucket

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

object-store-connection-limit

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

默认值： 16

object-store-http2-only

强制使用 HTTP/2 连接到基于网络的对象存储。

object-store-http2-max-frame-size

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

object-store-request-timeout

设置对象存储请求的 HTTP 请求超时时间。

默认值： 30s

object-store-max-retries

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

object-store-retry-timeout

指定从初始请求开始，不再尝试进一步重试的最大时间长度。

object-store-cache-endpoint

设置兼容 S3、支持 HTTP/2 的对象存储缓存的终端节点。

object-store-tls-allow-insecure

连接对象存储时允许无效的 TLS 证书。

object-store-tls-ca

指定用于验证对象存储连接的自定义 CA 证书文件（PEM 格式）路径。当对象存储使用由私有 CA 签名的证书时，请使用此项。

日志

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

log-filter

设置日志的过滤指令。使用此选项可全局或针对特定组件控制服务器日志的详细程度。

日志级别

以下是可用的日志级别（从最简洁到最详细）

基本用法

要全局设置日志级别，请传入其中一个日志级别

influxdb3 serve --log-filter debug

针对性过滤

全局启用 debug 或 trace 会产生大量日志输出。为了更具针对性的调试，您可以使用 <global_level>,<component>=<level> 格式为特定组件设置不同的日志级别。

调试写入缓冲区操作

influxdb3 serve --log-filter info,influxdb3_write_buffer=debug

跟踪 WAL 操作

influxdb3 serve --log-filter info,influxdb3_wal=trace

多个针对性过滤

influxdb3 serve --log-filter info,influxdb3_write_buffer=debug,influxdb3_wal=debug

常用组件名称

以下是可用于针对性过滤的常用组件名称

log-destination

指定日志的目标位置。

此选项支持以下值：

• stdout (默认)
• stderr

默认值： stdout

log-format

定义日志的消息格式。

此选项支持以下值：

• full (默认)

默认值： full

query-log-size

定义查询日志的大小。在为新查询腾出空间而清除旧查询之前，日志中最多可保留这么多查询。

默认值： 1000

跟踪 (Traces)

• 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 对，用于标注跟踪跨度 (tracing spans)。

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 文件时（例如去重），指定最大扇出 (fanout)。

默认值： 1000

datafusion-use-cached-parquet-loader

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

datafusion-config

以逗号分隔的 key:value 对列表形式向 DataFusion 提供自定义配置。

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

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

默认值： 70%

预写日志 (WAL)

• checkpoint-interval
• 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

checkpoint-interval

设置将 快照 合并为月度检查点的时间间隔，以加快服务器启动速度。快照会随着时间的推移在对象存储中积累，且不会自动删除。

如果不进行检查点设置，服务器在启动时会加载单个快照。快照的数量由回溯窗口（gen1-lookback-duration，默认为 1 个月）除以 gen1-duration（默认为 10 分钟）确定，最少为 100 个。在默认设置下，这可能多达 ~4,320 个快照。

启用检查点后，服务器会定期将快照元数据合并到对象存储中的检查点。启动时，服务器每个日历月加载一到两个检查点，然后仅加载自上次检查点以来创建的快照。启用检查点不会删除旧快照。

启动期间最多可同时加载 10 个检查点。服务器每个日历月保留两个检查点，并自动处理月份滚动更新。

接受 持续时间 值，例如：1h、30m、10m。

默认值： 未设置（已禁用）

示例

influxdb3 serve --checkpoint-interval 1h

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 文件数量超过此数字时，它们才会被删除。

默认值： 300

wal-replay-fail-on-error

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

默认值： false

wal-replay-concurrency-limit

WAL 重放期间的并发限制。将此数字设置得过高可能导致内存溢出 (OOM)。默认值是动态确定的。

默认值： max(num_cpus, 10)

压缩 (Compaction)

• gen1-duration

gen1-duration

指定 Parquet 文件被编排成的持续时间。数据时间戳将每一行放入此持续时间的文件中。支持的持续时间为 1m、5m 和 10m。这些文件被称为“第 1 代”文件，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（最近）

• 已缓存：包含来自 2024-06-10 14:00 的数据的 Parquet 文件（在 5 小时窗口内）
• 未缓存：包含来自 2024-06-09 的数据的 Parquet 文件（在 5 小时窗口外）

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
• restrict-plugin-triggers-to

plugin-dir

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

不同部署类型的默认行为

禁用处理引擎

要禁用处理引擎，请确保未配置 plugin-dir。

Docker: 使用自定义入口点 (entrypoint)

docker run --entrypoint /bin/sh influxdb:3-core -c 'unset INFLUXDB3_PLUGIN_DIR && exec influxdb3 serve --object-store memory'

systemd (DEB/RPM): 在配置文件中注释掉或删除 plugin-dir

sudo nano /etc/influxdb3/influxdb3-core.conf

# plugin-dir="/var/lib/influxdb3/plugins"

然后重启服务

sudo systemctl restart influxdb3-core

当处理引擎被禁用时：

• Python 环境和 PyO3 绑定不会被初始化
• 插件相关操作返回“未配置插件目录”错误
• 服务器以更少的资源占用运行

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)

当设置为 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

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

restrict-plugin-triggers-to

将插件触发器限制为一种或多种触发器类型。提供 wal、schedule 或 request 中的一种或多种。

资源限制

• max-concurrent-queries

• datafusion-num-threads

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

   |                                  |
  

max-concurrent-queries

限制可以并发运行的查询数量。您还可以使用 POST /api/v3/configure/query_concurrency_limit 在运行时更新此限制。

datafusion-num-threads

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

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

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

数据生命周期管理

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

gen1-lookback-duration

指定创建第 1 代 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 监听器文件路径。