OpenObserve 快速入门

用一条最快的路径在 Linux 服务器上把 OpenObserve v1.1.1 跑起来，并完整走一遍"启动服务 → 登录控制台 → 摄入日志 → SQL 查询 → 创建仪表盘"的最小闭环。全部命令与回显已在 Ubuntu 22.04.4 LTS（x86_64）+ OpenObserve v1.1.1 实测通过。

OpenObserveOpenObserve2026/10/18

OpenObserve 快速入门

‍‍​​‌​> 目标：用一条最快的路径在 Linux 服务器上把 OpenObserve v1.1.1 跑起来，并完整走一遍"启动服务 → 登录控制台 → 摄入日志 → SQL 查询 → 创建仪表盘"的最小闭环。全部命令与回显已在 Ubuntu 22.04.4 LTS（x86_64）+ OpenObserve v1.1.1 实测通过。

一、环境信息

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

  • 操作系统：Ubuntu 22.04.4 LTS（x86_64）
  • OpenObserve：v1.1.1（官方 linux-amd64 musl 静态链接二进制，启动日志实测确认版本号）
  • 服务端口：5080（HTTP，Web 控制台与 API 共用）
  • 数据目录：/data（通过 ZO_DATA_DIR 指定）
  • 管理账号：root@example.com / Q1w2E3r4!（首次启动通过环境变量设定，演示口令）

二、前置条件

  1. 一台 Linux 服务器（x86_64/aarch64 均可，OpenObserve 是静态链接二进制，无任何运行时依赖）；
  2. 开放 TCP 5080 端口（或自定义端口，见第七节）；
  3. 磁盘余量建议 ≥ 20GB（WAL 与缓存写入）；
  4. 能访问官方下载站 downloads.openobserve.ai（受网络限制的服务器可走代理或离线传输二进制）。

💡 说明：OpenObserve 单个二进制即包含 Web 控制台、摄入与查询 API、告警调度全部能力，无外部数据库依赖——单机模式的元数据内置 SQLite 存储，这也是它比 ELK 部署面小得多的根本原因。

三、获取并启动服务

3.1 下载二进制

官方 Quick Start 提供的下载命令（版本号以官方 Releases 页为准，当前最新稳定版为 v1.1.1）：

curl -L https://downloads.openobserve.ai/releases/openobserve/v1.1.1/openobserve-linux-amd64-musl.tar.gz -o openobserve.tar.gz
tar -zxvf openobserve.tar.gz
chmod +x openobserve

⚠️ 注意：downloads.openobserve.ai 是官方发布分发站，部分网络环境直连可能被拒（返回 403 Access Denied），此时为 curl 配置代理即可；本文后续所有实测均基于该官方 v1.1.1 二进制完成。

3.2 启动

首次启动必须同时指定数据目录与初始管理员邮箱/口令，缺一不可（原因见 3.3 排障实录）：

ZO_DATA_DIR=/data \
ZO_ROOT_USER_EMAIL="root@example.com" \
ZO_ROOT_USER_PASSWORD="Q1w2E3r4!" \
nohup ./openobserve > openobserve.log 2>&1 &

等待数秒后验证服务就绪：

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

实测回显：

{"status":"ok"}

启动日志头部（节选，实测）：

2026-10-18T04:02:11.194517690+00:00 INFO openobserve: Starting OpenObserve v1.1.1
2026-10-18T04:02:11.194596869+00:00 INFO openobserve: System info: CPU cores 12, MEM total 31.30 GB, Disk total 785.88 GB, free 535.07 GB

第一行即确认了实际运行版本为 v1.1.1。

3.3 首启排障实录：缺 root 凭据直接 panic

实测中，用全新数据目录启动但不设置 ZO_ROOT_USER_EMAIL / ZO_ROOT_USER_PASSWORD 时，服务在后台任务初始化阶段直接 panic 退出：

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

结论：数据目录中尚无用户库（SQLite）时，OpenObserve 用这两个环境变量初始化 root 账号；若目录已有用户数据（重启场景），则不再依赖它们。邮箱必须符合标准格式（xxx@yyy.zz），口令无复杂度强校验但建议 ≥ 8 位含大小写与符号。

四、登录控制台

浏览器访问 http://<服务器IP>:5080，会进入登录页。命令行可先验证 Web 控制台入口与登录接口：

# Web 控制台入口
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5080/web/
# 登录接口（会话 Cookie）
curl -s -X POST http://localhost:5080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"name":"root@example.com","password":"Q1w2E3r4!"}'

实测回显：

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

登录成功后进入默认组织（Organization）default 的日志检索页。后续所有 API 调用既可以用 HTTP Basic 认证（邮箱:口令），也可以用控制台导出的 Bearer Token。

五、摄入第一条日志

OpenObserve 的数据组织单位是流（Stream），相当于日志集/表。流无需预先创建——第一次向其写入数据时自动建立并推断 schema。用 JSON 摄入 API 向 app_logs 流写入 5 条应用日志：

curl -s -u "root@example.com:Q1w2E3r4!" \
  -X POST "http://localhost:5080/api/default/app_logs/_json" \
  -H "Content-Type: application/json" \
  -d '[
  {"level":"info","job":"api-gateway","message":"POST /api/v1/orders 200 in 12ms","status":200,"duration_ms":12,"host":"web-01"},
  {"level":"warn","job":"api-gateway","message":"GET /api/v1/cart slow response","status":200,"duration_ms":860,"host":"web-01"},
  {"level":"error","job":"payment","message":"upstream timeout while charging","status":504,"duration_ms":3005,"host":"pay-02"},
  {"level":"info","job":"payment","message":"charge succeeded order=A-1024","status":200,"duration_ms":45,"host":"pay-02"},
  {"level":"info","job":"auth","message":"user login ok uid=1001","status":200,"duration_ms":8,"host":"auth-01"}
]'

实测回显：

{"code":200,"status":[{"name":"app_logs","successful":5,"failed":0}]}

successful:5, failed:0 表示 5 条全部入库。此时打开控制台的 Logs → Streams 页面，已能看到 app_logs 流及其自动推断的字段（level/job/message/status/duration_ms/host）。

六、SQL 查询日志

通过查询 API 用标准 SQL 检索刚写入的数据（时间范围以微秒时间戳表示，示例取最近 1 小时）：

NOW=$(date +%s)
curl -s -u "root@example.com:Q1w2E3r4!" \
  -X POST "http://localhost:5080/api/default/_search" \
  -H "Content-Type: application/json" \
  -d "{\"query\":{\"sql\":\"SELECT level, job, message, duration_ms FROM app_logs ORDER BY duration_ms DESC LIMIT 3\",\"start_time\":$(( (NOW-3600)*1000000 )),\"end_time\":$(( NOW*1000000 ))}}"

实测回显（节选）：

{"took":9,"took_detail":{"total":9,"cache_took":0,"file_list_took":0,"wait_in_queue":0,"idx_took":0,"search_took":8},"hits":[{"_timestamp":1792296280528199,"level":"error","job":"payment","message":"upstream timeout while charging","duration_ms":3005},{"_timestamp":1792296280528198,"level":"warn","job":"api-gateway","message":"GET /api/v1/cart slow response","duration_ms":860},{"_timestamp":1792296280528199,"level":"info","job":"payment","message":"charge succeeded order=A-1024","duration_ms":45}],"total":3,"from":0,"size":3,"cached_ratio":0,"scan_size":0,"idx_scan_size":0,"scan_records":5,"is_partial":false}

要点解读：hits 按自定义字段 duration_ms 倒序返回前 3 条；scan_records:5 说明全量扫描了 5 条记录；is_partial:false 表示结果完整。控制台的 Logs 页与该 API 能力等价——在搜索框直接写 SQL 即可。

💡 技术拓展：查询时间参数业界常见三种表示——秒级时间戳（Prometheus 风格）、毫秒（JS 生态常用）、微秒（OpenObserve 的 start_time/end_time）。换算口诀：秒 ×1,000,000。给错量级是新手最常见的"查不到数据"原因。

七、创建第一个仪表盘

仪表盘同样可由 API 创建（控制台操作等价）：

curl -s -u "root@example.com:Q1w2E3r4!" \
  -X POST "http://localhost:5080/api/default/dashboards" \
  -H "Content-Type: application/json" \
  -d '{"title":"app_logs overview","description":"demo dashboard"}'

实测回显（节选）：

{"v8":{"version":8,"dashboardId":"7517435508599816192","title":"app_logs overview","description":"demo dashboard","owner":"root@example.com",...},"hash":"1333..."}

返回的 dashboardId 用于后续更新/删除。登录控制台进入 Dashboards，打开"app_logs overview"即可开始添加面板：选数据流 app_logs，例如用 SELECT histogram(_timestamp, '1 minute') AS t, count(*) FROM app_logs GROUP BY t 做一张每分钟日志量折线图。

至此最小闭环完成：启动 → 登录 → 摄入 → 查询 → 仪表盘。后续深入：

八、参考链接