进阶 questdb.com 2026-10-13 06:17:07 · 29 阅读

第9章 QuestDB 服务器配置详解

本页介绍了配置 QuestDB 服务器参数的方法。

可以通过以下方式进行配置:

  • 位于根目录的 server.conf 配置文件
  • 环境变量
  • 命令行选项,用于指定根目录、服务标签及 Web 控制台重新部署等启动行为

如果配置文件中未包含某项设置,且环境变量中也未定义,则使用默认值。

note:针对 Windows 用户。输入路径值时,请使用 \\ 或 / 代替原生路径分隔符 \。

👍 C:\\path\\to\\file\\path

👍 C:/path/to/file

👎 C:\path\to\file

单个反斜杠会被 Java 属性解析器视为转义序列的起始。

环境变量

配置文件中所有设置都可以通过环境变量进行设定或覆盖。如果某个键同时在 server.conf 文件和环境中变量中定义,环境变量将优先,配置文件中的值将被忽略。

为了使这些配置在 QuestDB 中通过环境变量生效,它们必须符合以下格式:

QDB_<KEY_OF_THE_PROPERTY>
其中 <KEY_OF_THE_PROPERTY> 等于配置键名称。为了将 server.conf 中的键正确格式化为环境变量,必须满足以下条件:

  • 添加 QDB_ 前缀
  • 使用大写字母
  • 将所有点号 . 替换为下划线 _

例如,查询超时的服务器配置键必须按如下方式传递:

server.conf 键:query.timeout 环境变量:QDB_QUERY_TIMEOUT

note:QuestDB 在启动时应用这些配置更改,必须重启正在运行的实例才能使配置更改生效。

示例

以下配置属性用于自定义查询超时时间:

conf/server.conf
query.timeout=120s
通过环境变量自定义查询超时:
export QDB_QUERY_TIMEOUT=120s

从文件读取密钥

QuestDB 支持通过 _FILE 后缀约定从文件读取敏感配置值。这在 Kubernetes 等容器化环境中非常有用,因为机密数据通常以文件形式挂载,而非作为环境变量传递。

当设置了 _FILE 变体时,QuestDB 将从指定文件路径读取机密值。此机制同时适用于环境变量和 server.conf 中的属性。

用法

环境变量:
QDB_PG_PASSWORD_FILE=/run/secrets/pg-password

属性文件:
server.conf
pg.password.file=/run/secrets/pg-password

优先级 如果同时设置了 _FILE 变体和直接值,则以 _FILE 变体为准。例如,同时设置了 QDB_PG_PASSWORD_FILE 和 QDB_PG_PASSWORD 时,值将从文件中读取。 文件要求 密钥文件必须满足以下要求: 最大 64KB UTF-8 编码 内容处理:自动去除首尾空白字符 出于安全考虑,以下路径不允许使用: 包含 .. 的路径(路径穿越) 以 /dev/、/proc/ 或 /sys/ 开头的路径 目录(包括指向目录的符号链接) 如果密钥文件为空或只包含空白字符,QuestDB 会记录一条提示性警告,因为这可能导致认证强度降低。 错误处理 如果启动时无法读取密钥文件,QuestDB 将启动失败。这包括文件不存在、文件过大或路径不被允许等情况。 运行期间,如果 reload_config() 无法读取某个密钥文件,则重新加载会失败,并保留之前的值。这确保了密钥文件暂时不可用时,服务器仍能继续运行。 重新加载密钥 从文件加载的密钥支持运行时重新加载。更新密钥文件后,调用 reload_config() 即可应用新值。详情参见可重新加载的配置项。 要验证某个密钥是否从文件加载,可运行 SHOW PARAMETERS 并查看 value_source 列,从文件加载的密钥会显示为 file。 支持的配置项 以下配置项支持 _FILE 后缀:

配置项环境变量pg.passwordQDB_PG_PASSWORD_FILEpg.readonly.passwordQDB_PG_READONLY_PASSWORD_FILEhttp.passwordQDB_HTTP_PASSWORD_FILE

企业版配置项

以下额外配置项仅在 QuestDB Enterprise 中可用:

配置项环境变量acl.admin.passwordQDB_ACL_ADMIN_PASSWORD_FILEacl.oidc.tls.keystore.passwordQDB_ACL_OIDC_TLS_KEYSTORE_PASSWORD_FILEreplication.object.storeQDB_REPLICATION_OBJECT_STORE_FILEcold.storage.object.storeQDB_COLD_STORAGE_OBJECT_STORE_FILEbackup.object.store.*QDB_BACKUP_OBJECT_STORE_*_FILE

Kubernetes 相关示例请参见 Kubernetes 部署指南。 可重新加载的配置项 某些配置项无需重启服务器即可重新加载。方法是:在 server.conf 文件中修改配置值,然后执行 reload_config SQL 函数:

重新加载服务器配置SELECT reload_config();

若配置值成功重载,reload_config 函数将返回 true,并在服务器日志中输出相应信息: 2025-01-02T09:52:40.833848UTC I i.q.DynamicPropServerConfiguration reloaded config option [update, key=http.net.connection.limit, old=100, new=200]
每个键都有一个可重载属性(reloadable property),用于标识该键是否支持重载。如果支持,即可调用 reload_config 函数重新加载配置。例如,查询、视图刷新和 WAL 应用等基于工作负载的内存限制均支持重载。 所有支持重载的属性也可通过服务器查询获取: Query reloadable properties(SHOW PARAMETERS) WHERE reloadable = true;
命令行选项 QuestDB 可通过命令行启动、停止并传入配置选项。在 Windows 系统上,QuestDB 服务器还支持启动交互式会话。 选项说明 以下章节介绍了通过命令行启动 QuestDB 服务器时可传入的选项。 LinuxmacOS(Homebrew)Windows./questdb.sh [start|stop|status] [-d dir] [-f] [-n] [-t tag]
questdb [start|stop|status] [-d dir] [-f] [-n] [-t tag]
questdb.exe [start|stop|status|install|remove] \
[-d dir] [-f] [-j JAVA_HOME] [-t tag]
启动 start 命令用于将 QuestDB 作为服务启动。 选项 说明 -d 接受一个目录路径作为参数,该目录将用作 QuestDB 的根目录。更多信息及默认值请参见下方的“默认根目录”章节。 -t 接受一个字符串作为服务标签。此选项允许用户运行并独立管理多个 QuestDB 服务。若省略此选项,默认标签为 questdb。 -f 强制重新部署 Web Console。若未指定此选项,Web Console 会被缓存,仅在缺失时才会部署。 -n 不响应 HUP 信号。此设置可使你在关闭启动 QuestDB 的终端窗口后,服务依然保持运行状态。 -j 仅限 Windows 使用!此选项允许指定 JAVA_HOME 的路径。 注意 当运行多个 QuestDB 服务时,必须在 start 和 stop 命令中使用标签来区分不同的服务。如果仅指定了标签标志而启动多个服务,会导致端口和根目录冲突。每个新服务都应拥有独立的配置文件,或者在启动时指定不同的端口和根目录选项。 将 QuestDB 作为 Windows 服务运行时,可通过以下两种方式查看状态: - Windows 事件查看器:在“应用程序和服务”日志中查找源为 "QuestDB" 的事件。 - 服务日志文件:位于 $dataDir\log\service-%Y-%m-%dT%H-%M-%S.txt (默认为 C:\Windows\System32\qdbroot\log\service-%Y-%m-%dT%H-%M-%S.txt )。 Linux macOS (Homebrew) Windows ./questdb.sh start [-d dir] [-f] [-n] [-t tag] questdb start [-d dir] [-f] [-n] [-t tag] questdb.exe start [-d dir] [-f] [-j JAVA_HOME] [-t tag] 默认根目录 QuestDB 的默认根目录如下: Linux macOS (Homebrew) Windows $HOME/.questdb Mac Apple Silicon (M1 或 M2) 芯片路径:/opt/homebrew/var/questdb Mac Intel 芯片路径:/usr/local/var/questdb C:\Windows\System32\qdbroot 停止 stop 命令用于停止服务。 选项 说明 -t 接受一个字符串作为标签,根据标签停止服务。若省略此选项,默认标签为 questdb。 Linux macOS (Homebrew) Windows ./questdb.sh stop questdb stop questdb.exe stop 状态 status 命令用于显示服务状态。 选项 说明 -t 接受一个字符串作为标签,根据标签停止服务。若省略此选项,默认为 questdb。 Linux macOS (Homebrew) Windows ./questdb.sh status questdb status questdb.exe status 安装(Windows) install —— 安装 Windows 版 QuestDB 服务,该服务会在系统启动时自动运行。 questdb.exe install 卸载(Windows) remove —— 移除 Windows 版 QuestDB 服务,之后系统启动时不再自动运行。 questdb.exe remove 交互式运行(Windows) 直接运行 questdb.exe 即可以交互方式启动 QuestDB,它会在当前 Shell 窗口中运行,关闭 Shell 时 QuestDB 也会随之停止。 默认根目录 以交互方式启动时,QuestDB 的根目录默认为当前目录。 停止 在终端中按 Ctrl+C 即可停止,或直接关闭终端。 配置校验 数据库启动时会检查配置问题,例如无效或已废弃的设置项。问题分为提示(advisory)和错误(error)两类。提示类问题只会记录日志,不会阻止数据库启动,通常是设置项已废弃的警告;而配置错误则可以选择性地让数据库启动失败。 config.validation.strict​ 默认值:false 可热更新:否 启用后,如果存在配置错误,启动将失败。建议启用严格校验。 配置参考 完整的配置参考按子系统划分,每个页面列出所有可用的配置项,包括默认值、是否支持运行时热更新,以及说明。 用于指定缓冲区和内存页大小的参数格式为 n,其中 可以是: m 表示 MB k 表示 kB 例如: 将每个 TCP socket 的最大发送缓冲区设置为 2MBhttp.net.connection.sndbuf=2m 各配置区段说明 仅企业版支持 Cairo 引擎 SQL 引擎配置 冷存储 对象存储中的历史分区 支持 COPY 设置 CSV 导入与 Parquet 导出 HTTP 服务 Web 控制台与 REST API IAM 身份与访问管理 支持 Ingestion(ILP/HTTP) InfluxDB Line Protocol 相关设置 Live 视图 Live 视图刷新配置 日志与指标 日志级别及指标采集 物化视图 物化视图刷新设置 最小化 HTTP 服务 健康检查与指标端点 OpenID Connect(OIDC) OIDC 集成 支持 并行 SQL 执行 查询并行度设置 Postgres 线协议 PostgreSQL 线协议连接 QuestDB 线协议(QWP) QWP 协议限制及 UDP 接收器 复制 高可用集群复制 支持 共享工作线程 工作线程池 存储策略 分区生命周期管理 支持 遥测 匿名使用数据遥测 TLS 加密 所有接口的 TLS 设置 支持 WAL 表配置 预写式日志(Write-Ahead Log)设置

评论 (0)