OpenObserve v1.1.1 配置参数详解

‍‍‌> 目标：逐项讲清 OpenObserve v1.1.1 单机模式的核心配置参数（全部以 ZO_ 前缀环境变量注入），给出每个参数的默认值、实测验证方法与踩坑实录，并附生产配置模板。全部命令与回显均在 Ubuntu 22.04.4 LTS（x86_64）+ OpenObserve v1.1.1 实测通过。

一、环境信息

本文所有命令与回显的实测环境：

操作系统：Ubuntu 22.04.4 LTS（x86_64，12 vCPU / 31.3GB 内存 / 786GB 磁盘）
OpenObserve：v1.1.1（官方 linux-amd64 二进制，启动日志与 /config 实测确认）
服务端口：5080（HTTP）/ 5081（gRPC）
数据目录：/data（ZO_DATA_DIR 指定）
参数验证方式：启动日志观测 + API 行为验证（见第三节）

二、前置条件

已按《OpenObserve 快速入门》或《OpenObserve Docker Compose 部署指南》跑通一个 v1.1.1 实例；
了解 OpenObserve 的配置模型：无默认配置文件，所有参数等价于 ZO_ 前缀环境变量，修改后需重启服务生效；
准备好重启手段（二进制场景杀进程重启；Compose 场景 docker compose up -d 重建）。

三、参数查看与修改方式

3.1 查看运行时公开配置：/config

/config 端点返回构建信息与少量 UI/遥测状态（注意：它不是全量参数清单，v1.1.1 实测仅返回以下内容）：

curl -s -u "root@example.com:Q1w2E3r4!" http://localhost:5080/config

实测回显：

{
    "build_type": "opensource",
    "commit_hash": "5ddbb78268041273e2b347eaf0dbef87cf671b5a",
    "telemetry_enabled": true,
    "sso_enabled": false,
    "native_login_enabled": true,
    "custom_logo_text": "",
    "custom_logo_img": null,
    "custom_logo_dark_img": null,
    "custom_hide_self_logo": false,
    "rum": {"enabled": false, ...}
}

（节选；rum 为对象，此处省略。）

其中 build_type（opensource/enterprise）与 commit_hash 可用于核对版本真伪；telemetry_enabled 直接反映 ZO_TELEMETRY 的生效状态（见 5.7）。

3.2 修改参数：环境变量 + 重启

所有参数通过 ZO_ 前缀环境变量注入。二进制方式：

ZO_HTTP_PORT=5080 ZO_GRPC_PORT=5081 ZO_DATA_DIR=/data nohup ./openobserve > openobserve.log 2>&1 &

Compose 方式（写入 environment: 段后 docker compose up -d 重建）：

    environment:
      ZO_HTTP_PORT: "5080"
      ZO_DATA_DIR: "/data"

3.3 验证参数生效：启动日志

多数核心参数在启动日志首部即可看到生效结果，最有代表性的是缓存容量行：

2026-10-18T04:15:16.394655475+00:00 INFO openobserve: Starting OpenObserve v1.1.1
2026-10-18T04:15:16.394732612+00:00 INFO openobserve: System info: CPU cores 12, MEM total 31.30 GB, Disk total 785.88 GB, free 534.89 GB
2026-10-18T04:15:16.394738971+00:00 INFO openobserve: Caches info: Disk max size 267.53 GB, MEM max size 7.82 GB, Datafusion pool size: 11.74 GB

该行展示了磁盘缓存、内存缓存、DataFusion 查询内存池的实际生效值（未设缓存参数时的默认值，按主机资源自动计算）。行为类参数（端口、UI 开关、日志格式等）用第五节各小节的验证命令逐一确认。

四、参数总览

v1.1.1 单机部署核心参数速查（默认值以官方环境变量手册 https://openobserve.ai/docs/environment-variables/ 与本机 31.3GB 内存实测为准，查询日期 2026-10-18）：

参数	默认值	说明	实测验证
`ZO_HTTP_PORT`	5080	HTTP 监听端口（Web+API）	✅ 生效（5.1）
`ZO_GRPC_PORT`	5081	gRPC 监听端口	✅ 生效（5.1）
`ZO_DATA_DIR`	`./data/openobserve/`	数据根目录（相对工作目录）	✅ 生效（5.2）
`ZO_ROOT_USER_EMAIL`	无	初始管理员邮箱（全新目录必填）	✅ 生效（5.3）
`ZO_ROOT_USER_PASSWORD`	无	初始管理员口令（全新目录必填）	✅ 生效（5.3）
`ZO_MEMORY_CACHE_MAX_SIZE`	物理内存 25%（实测 7.82GB）	查询结果内存缓存上限（MB）	✅ 生效（5.4）
`ZO_DISK_CACHE_MAX_SIZE`	磁盘 50%（实测 267.53GB）	磁盘缓存上限（MB）	✅ 生效（5.4）
`ZO_LOG_JSON_FORMAT`	false	结构化 JSON 日志输出	✅ 生效（5.5）
`ZO_UI_ENABLED`	true	是否内嵌 Web 控制台	✅ 生效（5.6）
`ZO_TELEMETRY`	true	匿名遥测上报	✅ 生效（5.7）
`ZO_INGEST_FLATTEN_LEVEL`	3	摄入 JSON 展平深度	官方文档，未单独实测
`ZO_FEATURE_FULLTEXT_EXTRA_FIELDS`	无	自动加入全局全文检索的字段	⚠️ 实测未见生效（5.9）
`ZO_MAX_QUERY_RANGE`	—	旧版最大查询范围	⚠️ 实测无效（5.8）
`ZO_DEFAULT_MAX_QUERY_RANGE_DAYS`	—	最大查询范围（天）	⚠️ 实测未见生效（5.8）

💡 说明：OpenObserve 参数量很大（二进制内实存 ZO_ 变体数百个），上表只覆盖单机部署的高频核心项。集群、Kafka 摄入、对象存储类参数属于进阶场景，等价机制同理：环境变量注入 + 重启生效 + 日志验证。

五、核心参数分类详解

5.1 网络端口：ZO_HTTP_PORT / ZO_GRPC_PORT

HTTP（Web 控制台与 API）默认 5080，gRPC 默认 5081——gRPC 恒等于 HTTP+1 的隐含关系是改端口的头号坑。实测把 HTTP 改为 5081 而不动 gRPC 时，两个监听器撞车：

Address already in use (os error 98)

同步指定 ZO_GRPC_PORT 错开后启动成功：

ZO_DATA_DIR=/data ZO_HTTP_PORT=5081 ZO_GRPC_PORT=5082 ./openobserve

curl -s http://localhost:5081/healthz

实测回显：

{"status":"ok"}

结论：改 ZO_HTTP_PORT 必须同步规划 ZO_GRPC_PORT；Compose 部署同理调整 ports 映射。

5.2 数据目录：ZO_DATA_DIR

默认值为相对路径 ./data/openobserve/（官方手册默认列与本机实测一致）。相对路径意味着目录落点跟随启动时的工作目录，工程上必须显式指定绝对路径。实测在只读工作目录下不设该参数启动：

thread 'main' (9973) panicked at src/config/src/config.rs:3769:9:
disk cache config error: create cache dir ./data/openobserve/cache/: Read-only file system (os error 30)

panic 信息同时验证了两件事：默认目录确实是 ./data/openobserve/；缓存目录创建失败会直接阻断启动。生产部署永远显式设置：

ZO_DATA_DIR=/data ./openobserve

5.3 初始管理员：ZO_ROOT_USER_EMAIL / ZO_ROOT_USER_PASSWORD

全新数据目录首次启动时，用这两个变量创建 root 管理员。实测换用自定义凭据启动：

ZO_DATA_DIR=/data/alt3b ZO_ROOT_USER_EMAIL="admin@corp.io" ZO_ROOT_USER_PASSWORD="Newpass#123" ./openobserve

启动后用新凭据登录：

curl -s -X POST http://localhost:5080/auth/login -H "Content-Type: application/json" \
  -d '{"name":"admin@corp.io","password":"Newpass#123"}'

实测回显：

{"status":true,"message":""}

不设置时直接 panic（全新目录场景实测，完整实录见《OpenObserve 快速入门》3.3）：

thread '<unnamed>' (9854) panicked at src/jobs/src/job/mod.rs:365:13:
Please set root user email-id & password using ZO_ROOT_USER_EMAIL & ZO_ROOT_USER_PASSWORD environment variables. This can also indicate an invalid email ID. Email ID must comply with ([a-z0-9_+]([a-z0-9_+.-]*[a-z0-9_+])?)@([a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,6})
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Error: backend job init failed: channel closed

结论：① 邮箱必须符合标准格式，口令建议强口令；② 数据目录已有用户库（重启/复用）时不再依赖这两个变量，此时改它们不会改已有口令（改口令走控制台或用户 API）。

5.4 缓存容量：ZO_MEMORY_CACHE_MAX_SIZE / ZO_DISK_CACHE_MAX_SIZE

两者单位均为 MB。实测 31.3GB 内存主机默认值：MEM max size 7.82 GB（约 25%）、Disk max size 267.53 GB（磁盘剩余空间约 50%，官方手册口径）。显式设置后实测：

ZO_MEMORY_CACHE_MAX_SIZE=1024 ZO_DISK_CACHE_MAX_SIZE=2048 ./openobserve

启动日志实测回显：

2026-10-18T04:15:16.394738971+00:00 INFO openobserve: Caches info: Disk max size 2.00 GB, MEM max size 1024.00 MB, Datafusion pool size: 15.15 GB

Disk max size 2.00 GB（2048MB）、MEM max size 1024.00 MB 与设定值完全一致，参数生效。选型建议：内存缓存建议 8%-25% 物理内存；磁盘缓存与 Parquet 数据共盘时注意给 WAL 留足余量。

5.5 日志输出：ZO_LOG_JSON_FORMAT

v1.1.1 的结构化日志开关是 ZO_LOG_JSON_FORMAT。默认人读格式：

2026-10-18T04:00:12.264217889+00:00 INFO openobserve: Starting OpenObserve v1.1.1

设置 ZO_LOG_JSON_FORMAT=true 后实测：

{"timestamp":"2026-10-18T03:50:10.171930941+00:00","level":"INFO","fields":{"message":"Starting OpenObserve v1.1.1","log.target":"openobserve","log.module_path":"openobserve","log.file":"src/main.rs","log.line":138},"target":"openobserve"}

⚠️ 注意：旧版资料常提到的 ZO_LOG_JSON 在 v1.1.1 实测无效（设置后日志仍为人读格式）；从 v1.1.1 二进制内实存的变量名核对，结构化开关为 ZO_LOG_JSON_FORMAT。接日志收集器（Filebeat/Vector）时建议开启 JSON 格式。

5.6 内嵌控制台：ZO_UI_ENABLED

默认 true，服务在 /web/ 提供 Web 控制台。实测关闭后：

ZO_UI_ENABLED=false ./openobserve

验证（关闭前 vs 关闭后，同一端口）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5080/web/

实测回显对比：

200   # 默认（UI 开启）
401   # ZO_UI_ENABLED=false（UI 关闭，仅 API 可用）

API 不受影响（同一实测中 GET /api/default/streams 返回 200）。适用场景：纯采集网关节点不对外暴露控制台。

5.7 匿名遥测：ZO_TELEMETRY

默认开启（/config 实测 "telemetry_enabled": true）。内网/合规环境关闭：

ZO_TELEMETRY=false ./openobserve

验证（关闭后 /config 实测）：

"telemetry_enabled": false

5.8 查询范围限制：ZO_MAX_QUERY_RANGE / ZO_DEFAULT_MAX_QUERY_RANGE_DAYS

实测环境 v1.1.1（开源单机）下，以下两项均未观察到生效，如实记录供参考：

设 ZO_MAX_QUERY_RANGE=1 后发起 24 小时范围查询：正常返回结果（未报错拦截）；
设 ZO_DEFAULT_MAX_QUERY_RANGE_DAYS=1 后发起 48 小时范围查询：同样正常返回（"took":9,...,"is_partial":false）。

推断与建议：该族参数在 v1.1.1 的生效路径可能依赖组织级设置或企业版能力；生产上若要强制限制查询时间范围，可在反代层（Nginx/OpenResty）对请求体做时间窗校验兜底。

5.9 摄入与索引特性

ZO_INGEST_FLATTEN_LEVEL（默认 3，官方手册）：控制摄入 JSON 的展平深度，设 0 展平全部嵌套。未单独实测，摄入嵌套 JSON 时按官方口径调整。
ZO_FEATURE_FULLTEXT_EXTRA_FIELDS：官方说明为"把指定字段自动加入全局全文检索"。实测设 ZO_FEATURE_FULLTEXT_EXTRA_FIELDS=custom_msg 后向 ft_test 流摄入含该字段的数据，查询流 schema 返回 "full_text_search_keys":[]，未观察到该字段被自动注册——v1.1.1 开源版实测未见生效。替代方案：用流设置 API 为流显式配置全文字段（PUT /api/{org}/streams/{stream}/settings，设置 full_text_search_keys），实测可用。

六、生产配置模板

适用场景：8 核 CPU / 16GB 内存 / 500GB SSD 单机，日增日志 50GB 以内，日志+指标+追踪一体：

# ── 基础 ──
ZO_DATA_DIR=/data                                  # 数据根目录（必须绝对路径并挂持久盘）
ZO_ROOT_USER_EMAIL="ops@example.com"               # 初始管理员（首启必需）
ZO_ROOT_USER_PASSWORD="ChangeMe#2026"              # 首登后建议在控制台改掉
# ── 端口 ──
ZO_HTTP_PORT=5080                                  # HTTP：Web+API
ZO_GRPC_PORT=5081                                  # gRPC：必须与 HTTP 错开
# ── 缓存（16GB 内存主机）──
ZO_MEMORY_CACHE_MAX_SIZE=4096                      # 查询结果内存缓存 4GB
ZO_DISK_CACHE_MAX_SIZE=102400                      # 磁盘缓存 100GB，与数据共盘时留足余量
# ── 运行时行为 ──
ZO_LOG_JSON_FORMAT=true                            # 结构化日志，便于接入采集器
ZO_TELEMETRY=false                                 # 内网环境关闭遥测
ZO_COMPACT_DATA_RETENTION_DAYS=30                  # 数据保留 30 天

资源占用参考（v1.1.1 空载实测）：CPU 约 1%，内存 130-300MB；随摄入/查询负载上升，缓存上限是主要内存变量。

七、常见问题（FAQ）

Q1：改了环境变量重启后不生效？

确认三点：① 变量名拼写（v1.1.1 存在改名，如 ZO_LOG_JSON → ZO_LOG_JSON_FORMAT）；② 是否真的重启（Compose 必须 up -d 重建而非仅 restart，环境变量只在创建时注入）；③ 参数属于行为类还是启动类——启动类看启动日志（如 Caches info），行为类按 5.1-5.7 的验证命令核对。排查顺序建议：启动日志首部 30 行包含绝大多数参数的生效证据（版本、System info、Caches info），先看它再怀疑参数没生效。

Q2：全新数据目录启动 panic "Please set root user email-id & password"

见 5.3，补 ZO_ROOT_USER_EMAIL / ZO_ROOT_USER_PASSWORD 后重启即可；邮箱必须合法格式。

Q3：启动 panic "disk cache config error: create cache dir ... Read-only file system"

ZO_DATA_DIR 未设置时默认相对路径 ./data/openobserve/，落在只读工作目录导致缓存目录创建失败（见 5.2 实测 panic 回显）。解决：显式设置 ZO_DATA_DIR 指向可写绝对路径。

Q4：把 HTTP 端口改成 5081 后服务起不来

gRPC 默认 5081 与新 HTTP 端口冲突（Address already in use）。见 5.1，同步设置 ZO_GRPC_PORT 错开。

Q5：ZO_MAX_QUERY_RANGE 设置后查询超范围仍能返回

v1.1.1 开源单机实测该族参数未拦截（见 5.8）。需要硬限制时在反代层兜底。

八、参考链接

官方环境变量手册：https://openobserve.ai/docs/environment-variables/
本专栏姊妹篇：《OpenObserve 快速入门》《OpenObserve Docker Compose 部署指南》《OpenObserve v1.1.1 API 使用详解》
版本核对：/config 端点 build_type/commit_hash 与 GitHub Releases（https://github.com/openobserve/openobserve/releases）