KurrentDB 服务端配置完全指南：从配置文件到自动调优的完整实践

• 数据库
• 后端
• 流处理

导读

KurrentDB（事件驱动架构原生的数据库）提供了丰富的服务端配置项，覆盖存储路径、集群、网络、日志、认证、投影等方方面面。所有选项都有合理的默认值，但生产环境往往需要按需定制。本文以官方配置文档 configuration.md 为骨架，完整梳理 KurrentDB 的四种配置方式（YAML、JSON、环境变量、命令行）及其优先级关系，并深入仓库源码讲解--what-if生效配置诊断、未知选项校验、以及StreamInfoCacheCapacity、ReaderThreadsCount、WorkerThreads三项自动配置选项的底层实现。读完本文，你将能熟练地以任意一种方式配置并验证 KurrentDB 服务器。

配置方式总览：四种来源与优先级

KurrentDB 支持四种配置方式，按生效优先级从低到高排列：

1. YAML 配置文件（默认kurrentdb.conf）
2. JSON 配置文件（config/目录下的.json文件）
3. 环境变量（KURRENTDB_前缀）
4. 命令行参数（--option）

优先级规则：后一种方式覆盖前一种方式——JSON 覆盖 YAML，环境变量覆盖配置文件，命令行参数覆盖配置文件和环境变量。这一优先级顺序正是由 KurrentConfiguration.cs 中ConfigurationBuilder的 Provider 注册顺序决定的：默认值 → 默认位置 →metricsconfig.json/kestrelsettings.json/logconfig.json→config/目录 JSON → YAML → 环境变量 → 命令行，后注册的 Provider 覆盖先注册的。

值得注意的是，KurrentConfiguration.cs 中同时保留了 EventStore 时代的旧 Provider（AddLegacyEventStoreConfigFile、AddLegacyEventStoreEnvironmentVariables、AddLegacyEventStoreCommandLine），它们会把EventStore:前缀的配置归一化为KurrentDB:前缀（见 KurrentConfigurationKeys.cs），实现向后兼容；同时 EventStoreDefaultLocations.cs 会在 KurrentDB 新默认路径不存在而旧 EventStore 路径存在时自动回退到旧路径。

版本与帮助

使用命令行参数--version可以查看已安装的 KurrentDB 版本：

::: tabs#os @tab Linux

$ kurrentd --version KurrentDB version 25.0.0.1673-build.1 ee (0de5e4be-c415-4230-95d4-0f0d3b1d4a18/80248a9214b3412d5051bac58168ee5666e6cb97)

@tab Windows

> KurrentDB.exe --version KurrentDB version 25.0.0.1673-build.1 ee (0de5e4be-c415-4230-95d4-0f0d3b1d4a18/80248a9214b3412d5051bac58168ee5666e6cb97)

:::

全部可用选项的完整列表，可以通过--help参数从当前安装的服务器实例上获取。在源码层面，--help/--version/--what-if都定义在 ClusterVNodeOptions.cs 的ApplicationOptions记录中（Help、Version、WhatIf三个布尔属性），帮助文本则是在 ClusterVNodeOptions.Framework.cs 的静态构造器中通过反射遍历所有带[OptionGroup]特性的配置分组及[Description]描述自动生成的，因此--help输出始终与当前二进制版本完全一致。

YAML 配置文件

默认的配置文件名为kurrentdb.conf，位于：

• Linux：/etc/kurrentdb/
• Windows：KurrentDB 安装目录

在源码中，Linux 默认路径由 DefaultFiles.cs 的DefaultConfigPath计算（Locations.DefaultConfigurationDirectory+kurrentdb.conf，Windows 下该文件名默认为空字符串）。同时旧版eventstore.conf也仍然被识别为回退路径。

配置文件采用 YAML 格式，选项按下述方式设置：

--- Db: "/volumes/data" Log: "/kurrentdb/logs" ReaderThreadsCount: 4

嵌套配置项按自然的层级表达：

UserCertificates: Enabled: true

提示：YAML 文件顶部必须带三个短划线---，缩进必须使用空格。

配置文件路径可以通过环境变量KURRENTDB_CONFIG修改，或在命令行用--config=path-to-file指定。从源码看，KurrentConfiguration.cs 的ResolveConfigurationFile会先只从环境变量和命令行解析KurrentDB:Config键来确定配置文件路径；如果用户显式指定了路径，该文件被视为必选（optional: false），不存在则启动失败；如果走默认路径，则视为可选（optional: true）。YAML 文件由AddKurrentYamlConfigFile挂载到KurrentDB:配置节下，并开启reloadOnChange（文件变更热重载）。

JSON 配置文件

KurrentDB 会在<installation-directory>/config/目录中查找 JSON 配置文件；在 Linux 和 OS X 上，服务器还会额外查找/etc/kurrentdb/config/。JSON 配置可以拆分成多个文件，也可以合并到单个文件中；除了.json扩展名之外，文件名本身不重要。

所有配置项都嵌套在KurrentDB键下：

{ "KurrentDB": { "Db": "/volumes/data", "Log": "/kurrentdb/logs", "ReaderThreadsCount": 4, "UserCertificates": { "Enabled": true } } }

在 JSON 配置中设置的选项会覆盖 YAML 配置中的同名选项。

从源码实现看（EventStoreJsonFile.cs 与 KurrentConfiguration.cs），config/子目录下所有*.json文件都会被加载（AddKurrentConfigFiles("*.json")），并且支持optional与reloadOnChange（文件系统轮询监听变更）。此外，metricsconfig.json、kestrelsettings.json、logconfig.json三个特殊文件也会被显式加载到对应的配置节（如KurrentDB:Metrics），这是为了向后兼容而保留的行为。

环境变量

通过环境变量设置选项时，为选项名加上KURRENTDB_前缀，并使用双下划线__表示嵌套层级。例如：

KURRENTDB_DB KURRENTDB_LOG KURRENTDB_READER_THREADS_COUNT KURRENTDB_USER_CERTIFICATES__ENABLED

通过环境变量设置的选项会覆盖配置文件中的同名选项。

这种命名规范在源码中由 KurrentConfigurationKeys.cs 实现：环境变量键的KURRENTDB_前缀被剥离、__被转换为配置路径分隔符:、单词间的单下划线被转换为 PascalCase（例如READER_THREADS_COUNT→ReaderThreadsCount），再映射到KurrentDB:节下；由于使用了OrdinalIgnoreCase比较，键的匹配不区分大小写。环境变量读取由 KurrentDBEnvironmentVariablesConfigurationProvider.cs 完成，它会枚举进程环境中的所有变量并仅收录带KURRENTDB_（或兼容的EVENTSTORE_）前缀的键。

命令行参数

以命令行参数启动 KurrentDB 时，例如使用--log选项覆盖默认日志目录：

::: tabs#os @tab Linux

kurrentd --log /tmp/kurrentdb/logs

@tab Windows

KurrentDB.exe --log C:\Temp\KurrentDB\Logs

:::

与环境变量一样，使用双下划线__表示嵌套层级。更多示例：

--db --log --reader-threads-count --user-certificates__enabled

命令行选项覆盖配置文件和环境变量。

命令行参数由 KurrentDBCommandLineConfigurationSource.cs 解析，其NormalizeKeys/NormalizeBooleans做了几件关键的事：

• 短横线参数（-x）自动规范为长横线形式（--x）；
• 布尔开关支持三种写法：--option+（真）、--option-（假）、以及裸--option（自动补=true，除非后跟一个非--开头的值）；
• 键随后同样经过 PascalCase 归一化（如--reader-threads-count→ReaderThreadsCount），与 YAML/环境变量写法殊途同归。

测试配置：使用--what-if

当同时使用多种方式配置服务器时，很难判断服务器启动时实际生效的配置是什么。这时可以使用--what-if选项来理清配置细节。

当以--what-if运行 KurrentDB 时，它会将来自所有可用来源（默认值、自定义配置文件、环境变量、命令行参数）合并后的生效配置打印到控制台。

下面是一个--what-if输出的示例（节选）：

$ KurrentDB.exe --what-if [13816, 1,12:02:34.627,INF] KurrentDB DB VERSION: 25.0.0.1673-build.1 ee (...) [13816, 1,12:02:34.630,INF] KurrentDB OS ARCHITECTURE: X64 [13816, 1,12:02:34.631,INF] KurrentDB RUNTIME: .NET 8.0.12/89ef51c5d (64-bit) [13816, 1,12:02:34.632,INF] KurrentDB LOGS: C:\Users\hayle\Downloads\kurrentdb.25.0.0-build.1\logs [13816, 1,12:02:34.635,INF] KurrentDB MODIFIED OPTIONS: APPLICATION OPTIONS: WHAT IF: true (Command Line) DEFAULT OPTIONS: APPLICATION OPTIONS: ALLOW ANONYMOUS ENDPOINT ACCESS: False (<DEFAULT>) ALLOW ANONYMOUS STREAM ACCESS: False (<DEFAULT>) ... MAX APPEND SIZE: 1048576 (<DEFAULT>) WORKER THREADS: 0 (<DEFAULT>) AUTHENTICATION/AUTHORIZATION OPTIONS: AUTHENTICATION TYPE: internal (<DEFAULT>) AUTHORIZATION TYPE: internal (<DEFAULT>) CERTIFICATE OPTIONS (FROM FILE): CERTIFICATE FILE: (<DEFAULT>) CERTIFICATE PASSWORD: ******** (<DEFAULT>) CLUSTER OPTIONS: CLUSTER DNS: fake.dns (<DEFAULT>) CLUSTER GOSSIP PORT: 2113 (<DEFAULT>) CLUSTER SIZE: 1 (<DEFAULT>) GOSSIP INTERVAL MS: 2000 (<DEFAULT>) LEADER ELECTION TIMEOUT MS: 1000 (<DEFAULT>) NODE PRIORITY: 0 (<DEFAULT>) DATABASE OPTIONS: CACHED CHUNKS: -1 (<DEFAULT>) CHUNK SIZE: 268435456 (<DEFAULT>) DB: C:\kurrentdb.25.0.0-build.1\data (<DEFAULT>) DB LOG FORMAT: V2 (<DEFAULT>) READER THREADS COUNT: 0 (<DEFAULT>) STATS STORAGE: File (<DEFAULT>) TRANSFORM: identity (<DEFAULT>) DEFAULT USER OPTIONS: DEFAULT ADMIN PASSWORD: ******** (<DEFAULT>) DEV MODE OPTIONS: DEV: False (<DEFAULT>) GRPC OPTIONS: KEEP ALIVE INTERVAL: 10000 (<DEFAULT>) KEEP ALIVE TIMEOUT: 10000 (<DEFAULT>) INTERFACE OPTIONS: NODE IP: 127.0.0.1 (<DEFAULT>) NODE PORT: 2113 (<DEFAULT>) REPLICATION IP: 127.0.0.1 (<DEFAULT>) REPLICATION PORT: 1112 (<DEFAULT>) LOGGING OPTIONS: LOG FILE RETENTION COUNT: 31 (<DEFAULT>) LOG FILE SIZE: 1073741824 (<DEFAULT>) PROJECTION OPTIONS: PROJECTION THREADS: 3 (<DEFAULT>) RUN PROJECTIONS: None (<DEFAULT>) START STANDARD PROJECTIONS: False (<DEFAULT>)

输出分为MODIFIED OPTIONS（被修改过的选项）与DEFAULT OPTIONS（保持默认的选项）两大部分，每个选项末尾的括号标注了它的来源，例如(Command Line)、(Environment Variables)、(Json)、(<DEFAULT>)，敏感值（如证书密码、默认管理员密码）会被脱敏为********。

这一输出由 ClusterVNodeOptionsPrinter.cs 生成：它遍历所有配置 Provider 与全部选项元数据，对每个选项记录"是否来自默认值 Provider"，从而区分 MODIFIED 与 DEFAULT；--what-if本身是一个ApplicationOptions.WhatIf布尔选项（定义于 ClusterVNodeOptions.cs），在 Program.cs 中检测到该选项后打印配置并退出，不会真正启动服务器。

未知选项校验：错误的配置会阻止服务器启动

如果配置文件、环境变量或命令行中出现了未知的配置选项，服务器将不会启动。例如以下写法都会阻止启动：

• 命令行：--UnknownConfig
• 环境变量：KURRENTDB_UnknownConfig
• 配置文件：UnknownConfig: value

此时stdout上只会输出：Error while parsing options: The option UnknownConfig is not a known option. (Parameter 'UnknownConfig')。

其背后的校验逻辑：KurrentConfigurationKeys在静态构造器中通过反射收集ClusterVNodeOptions所有分组下的已知键（AllKnownKeys），ClusterVNodeOptionsValidator.cs 据此检查解析出的UnknownOptions；默认情况下AllowUnknownOptions为false，一旦检测到未知键即中止启动。仅当你显式设置--allow-unknown-options（对应ApplicationOptions.AllowUnknownOptions，见 ClusterVNodeOptions.cs）时，未知选项才被容忍。提示：该功能也能在你配置拼写错误时立即暴露问题——用--what-if配合检查是排查配置错误的黄金组合。

自动配置选项（Autoconfigured options）

部分选项会在启动时根据机器可用资源自动配置，以便在较大规模的实例上更好地利用资源。这三项选项是：StreamInfoCacheCapacity、ReaderThreadsCount和WorkerThreads。

注意：自动配置不适用于容器化环境。容器场景下使用固定值（见下文各节），因为容器内的 CPU/内存视图可能与宿主机不同。仓库中 ContainerizedEnvironment.cs 通过RuntimeInformation.IsRunningInContainer检测容器环境。

StreamInfoCacheCapacity

该选项设置流信息缓存（stream info cache）中条目的最大数量。这个缓存保存了任何最近被读取或写入过的流的信息。在大数据库上，缓存中的条目能显著提升对已缓存流的读写性能。

默认情况下，缓存会根据可用内存量动态调整大小，其最小值可设为 100,000 条。

该选项默认设为0，表示启用动态调整大小。KurrentDB 旧版本的默认值是 100,000 条。

从源码可以验证其实现逻辑（ClusterVNode.cs 的启动路径）：

• 当StreamInfoCacheCapacity > 0时，创建静态缓存（固定容量）；
• 当其为 0 且处于容器环境时，使用ContainerizedEnvironment.StreamInfoCacheCapacity（100,000）创建静态缓存；
• 当其为 0 且非容器环境时，创建动态缓存，由DynamicCacheManager每 15 秒根据空闲内存与 GC 状态（保持约 25% 空闲内存、最少 6 GiB 缓冲、最小调整间隔 10 分钟、200 MiB 调整阈值）自动扩容/缩容，并通过MonitoringMessage.DynamicCacheManagerTick订阅持续调整。

注意：StreamInfoCacheCapacity的默认值 0 并不总是性能最优解。理想情况下，它应设置为预期工作集中流数量的两倍。

要获取流的总数，可以查看$streams系统流中的事件计数。该流由 $streams 系统投影 创建。

需要说明的是，流的总数并不一定等同于你预期的工作集（working set）。工作集是你打算主动读取、写入和/或订阅的流集合，它在某些场景下可能远低于流总数——尤其是在存在大量短生命周期流的系统中。

ReaderThreadsCount

该选项配置可供 KurrentDB 使用的读取线程数量。增加读取线程数量可以处理更多并发读操作。

警告：如果磁盘无法承受增加的负载，将读取线程数设置得过高会导致读超时。

读取线程数会在启动时设置为可用处理器数量的两倍，下限为四个，上限为十六个线程。

该选项默认设为0，表示启用自动配置。KurrentDB 旧版本的默认值是四个线程。

底层实现可直接在 ThreadCountCalculator.cs 中看到：

• 若配置值> 0，直接采用配置值；
• 若配置值为 0 且处于容器环境，采用ContainerizedEnvironment.ReaderThreadCount（固定 4）；
• 否则按Math.Clamp(processorCount * 2, 4, 16)计算，即两倍 CPU 数、下限 4、上限 16——与文档所述完全一致。计算得到的值会被记录到日志中，便于启动时核对。

WorkerThreads

WorkerThreads选项配置可供工作服务线程池（pool of worker services）使用的线程数量。

在启动时，如果读取线程数大于四个，工作线程数将被设置为十；否则，将设置为五个线程。

该选项默认设为0，表示启用自动配置。KurrentDB 旧版本的默认值是五个线程。

需要特别说明的是：在 ClusterVNodeOptions.cs 中，WorkerThreads属性带有[Deprecated("This setting no longer has an effect. The workers automatically scale as necessary")]标记——即该设置自新版本起已不再生效，工作线程池会自动按需扩缩容，设置此选项仅为保持向后兼容。这与文档"旧版本默认五个线程"的描述相互印证，说明文档描述的自动配置行为针对的是早期版本；当前版本建议直接使用默认值 0。

实战建议：组合使用四种方式

综合上文，推荐的生产实践如下：

1. 基础路径与规模参数（Db、Log、ReaderThreadsCount等）放入kurrentdb.conf（YAML），或使用config/目录下的 JSON 文件统一管理；
2. 环境差异参数（如不同环境的NodeIp、ClusterSize、RunProjections）通过KURRENTDB_*环境变量注入，便于容器与编排平台覆盖；仓库自带的 docker-compose.yaml 即是典型示范，其中使用KURRENTDB_CLUSTER_SIZE=1、KURRENTDB_RUN_PROJECTIONS=All、KURRENTDB_INSECURE=true等环境变量配置容器化节点；
3. 临时调试/单次启动参数使用命令行传入，优先级最高；
4. 每次变更配置后，先运行kurrentd --what-if（或KurrentDB.exe --what-if）核对生效配置与来源，再正式启动，避免因配置冲突或未知选项导致启动失败。

延伸阅读

• 配置体系实现：KurrentConfiguration.cs、KurrentConfigurationKeys.cs
• 全部选项定义：ClusterVNodeOptions.cs
• 自动配置计算：ThreadCountCalculator.cs、ContainerizedEnvironment.cs
• --what-if输出：ClusterVNodeOptionsPrinter.cs
• 缓存动态调整：ClusterVNode.cs、DynamicCacheManager.cs
• 其他配置专题：集群配置、数据库配置、网络配置、Kontrol Plane

• 数据库
• 后端
• 流处理