QuestDB 10.0.1 配置参数详解

目标：详解 QuestDB 10.0.1 服务端配置文件 server.conf 的核心参数：HTTP、PostgreSQL wire、ILP 协议组，存储引擎与 WAL 组，安全认证与资源控制，并给出生产配置模板与部署形态说明。所有默认值均以 QuestDB 10.0.1 实际安装环境核实。

环境信息

• QuestDB 版本：10.0.1
• 配置文件：/var/lib/questdb/conf/server.conf（安装后 1,833 行，几乎全部为注释，生效参数极少）
• 日志配置：/var/lib/questdb/conf/log.conf
• 数据目录：/var/lib/questdb（db 存放表数据）
• 默认认证：http.user=admin、http.password=quest、pg.user=admin、pg.password=quest
• 默认端口：9000（HTTP）、9009（ILP TCP）、8812（PG wire）

前置条件

• 已按《Ubuntu 22.04 安装 QuestDB 10.0.1 指南》或《CentOS 8 安装 QuestDB 10.0.1 指南》完成安装
• 拥有对 /var/lib/questdb/conf/server.conf 的写权限（属主为 questdb 用户）
• 修改配置后需要重启服务生效：systemctl restart questdb 或 questdb.sh restart

参数查看与修改方式

查看当前生效配置

QuestDB 不提供一条命令打印全部生效参数，可通过启动日志确认各协议监听地址，并通过 SQL 查询引擎内部信息：

执行命令：

grep -aE "listening|server-main" /var/lib/questdb/log/questdb-rolling.log.20261003 | tail -5

执行结果：

2026-10-03T09:57:09.889837Z A server-main server is ready to be started
2026-10-03T09:57:10.572061Z A pg-server listening on 0.0.0.0:8812 [fd=839666106657 backlog=64]
2026-10-03T09:57:10.576852Z A tcp-line-server listening on 0.0.0.0:9009 [fd=848256041251 backlog=256]
2026-10-03T09:57:10.612922Z A http-server listening on 0.0.0.0:9000 [fd=856845975845 backlog=256]

修改方式

配置文件每行一个参数，格式为 参数名=值，# 开头为注释（默认值即写在注释中，取消注释并修改即生效）。

示例：修改 PG wire 密码并限制监听地址

pg.password=mysecret
pg.net.bind.to=0.0.0.0:8812

保存后重启：

systemctl restart questdb

环境变量映射

Docker 部署时（见《QuestDB 10.0.1 Docker Compose 部署指南》），所有配置项可用 QDB_ 前缀环境变量注入，规则：配置项大写、点号转下划线。例如 pg.password → QDB_PG_PASSWORD、http.bind.to → QDB_HTTP_BIND_TO。

参数总览

一、协议与端口配置

QuestDB 同时暴露三种接入协议，端口均可独立配置与启停。

1.1 HTTP / REST / Web Console（9000）

http 组控制 REST API、Web Console 与 ILP over HTTP（POST /write）服务：

http.enabled=true
http.bind.to=0.0.0.0:9000
http.worker.count=4
http.security.readonly=false

💡 说明：http.security.readonly=true 时 Web Console 只能执行查询，不能建表/插入，适合报表与只读业务接入。

1.2 PostgreSQL wire（8812）

pg 组控制 PG wire 协议（psql / 各类 PG 驱动可直连）：

pg.enabled=true
pg.net.bind.to=0.0.0.0:8812
pg.user=admin
pg.password=quest
pg.worker.count=4

⚠️ 注意：默认密码 quest 为公开已知值，生产环境必须修改。修改 pg.password 后重启生效。

1.3 ILP（InfluxDB Line Protocol）（9009）

line 组控制 ILP TCP 与 UDP 数据接入：

line.tcp.enabled=true
line.tcp.net.bind.to=0.0.0.0:9009
line.tcp.timestamp=n
line.udp.enabled=false

💡 说明：line.tcp.timestamp=n 表示 ILP 行内时间戳为纳秒。若上游只发送毫秒时间戳，改 line.tcp.timestamp=ms 可避免时间被误解析为 1970 年。ILP 也可走 HTTP 9000 端口的 POST /write，无需单独开 TCP。

二、存储引擎与 WAL 配置

cairo 组控制表存储、分区与写入提交行为：

cairo.wal.enabled=true
cairo.max.uncommitted.rows=100000
cairo.commit.lag=120000
cairo.sql.copy.root=import

💡 说明：需要更低写入延迟时调小 cairo.commit.lag（如 500）；需要更高批量吞吐时调大 cairo.max.uncommitted.rows（如 1000000）。两者需按业务写入峰值权衡。

三、安全认证与访问控制

QuestDB 10 内置三类认证体系：

⚠️ 注意：QuestDB 10 不支持 ALTER USER admin ADD PASSWORD 一类 DDL 修改密码，密码只能通过配置文件（或 QDB_ 环境变量）修改后重启生效。

四、资源与性能调优

五、部署形态与扩展方式

QuestDB 开源版为单机部署形态，本身不提供多节点集群能力（集群属于企业版 QuestDB Enterprise）。

生产环境水平扩展的可行路径：

1. 多实例水平拆分：在多台服务器各自部署单节点（见两篇安装指南），应用层按时间范围或业务维度路由写入与查询。
2. docker-compose 多实例：同一台服务器上通过多个 compose 服务（不同数据卷、不同 http.bind.to 端口）拆分数据集，Web Console 分别访问（见《QuestDB 10.0.1 Docker Compose 部署指南》）。
3. 外部集成扩展：写入端用 ILP 批量灌入、查询端用 PG wire 供 BI/报表工具接入；只读场景开启 http.security.readonly=true。
4. 企业版升级：需要原生集群（高可用、水平分区）时评估 QuestDB Enterprise。

💡 说明：QuestDB 单节点本身具备极高性能（列式存储 + SIMD 向量化 + 分区裁剪），多数时序场景单机即可支撑，先做容量评估再决定是否多实例。

生产配置模板

根据内存与写入量分级给出最小可用配置（写入 server.conf 并重启生效）。

小规模（4C/8G，写入 < 5 万行/秒）

config.validation.strict=true
query.timeout=60s

http.bind.to=0.0.0.0:9000
http.user=admin
http.password=change_me_http

pg.net.bind.to=0.0.0.0:8812
pg.user=admin
pg.password=change_me_pg

line.tcp.net.bind.to=0.0.0.0:9009
line.tcp.timestamp=n

cairo.max.uncommitted.rows=200000
cairo.commit.lag=1000
telemetry.enabled=false

中大规模（16C/32G，写入 10~50 万行/秒）

config.validation.strict=true
query.timeout=300s

shared.worker.count=16
http.worker.count=8
pg.worker.count=8

http.bind.to=0.0.0.0:9000
http.user=admin
http.password=change_me_http

pg.net.bind.to=0.0.0.0:8812
pg.user=admin
pg.password=change_me_pg

line.tcp.net.bind.to=0.0.0.0:9009
line.tcp.timestamp=n

cairo.max.uncommitted.rows=1000000
cairo.commit.lag=500
telemetry.enabled=false

⚠️ 注意：生产部署务必修改两处密码（http.password、pg.password），并将 systemd 单元中 LimitNOFILE 保持 65536 及以上。

常见问题

Q1. 修改配置后重启提示配置校验失败

• 现象：systemctl restart questdb 后服务进入 failed，日志报 Unknown configuration property。
• 定位：config.validation.strict=true 时任何非法参数都会阻止启动。
• 解决：journalctl -u questdb -n 50 查看具体参数名，修正或删除该行后重启。

Q2. 端口 9000 被占用如何改端口

• 现象：启动失败，address already in use。
• 解决：改 http.bind.to=0.0.0.0:19000，同时调整系统防火墙放行新端口。

Q3. 改了 pg.password 后 psql 还是报密码错误

• 现象：改配置重启后仍无法登录。
• 定位：Docker 部署时环境变量 QDB_PG_PASSWORD 优先级高于挂载配置文件。
• 解决：检查 compose 环境变量，或直接删掉该环境变量让配置文件生效。

Q4. ILP 时间戳总是 1970 年

• 现象：ILP 写入成功，查询时间列为 1970-01-01。
• 解决：确认 line.tcp.timestamp=n（纳秒），写入端使用 date +%s%N 生成纳秒时间戳。

参考链接

• 官方配置参考：https://questdb.io/docs/reference/configuration/
• 认证与安全：https://questdb.io/docs/operations/security/
• ILP 配置：https://questdb.io/docs/reference/api/ilp/tcp/