OpenObserve Docker Compose 部署指南

‍‍‌> 目标：在一台 Ubuntu 22.04 服务器上用 Docker Compose 从 0 到 1 部署 OpenObserve v1.1.1 单机服务，完成镜像选型、编排文件逐段解析、启动验证、数据持久化实测（down/up 数据不丢）、等价 docker run 命令与日常运维操作；全部命令与回显均在 Ubuntu 22.04.4 LTS（x86_64）+ Docker 29.8.1 + Docker Compose v5.5.1 + OpenObserve v1.1.1 实测通过。

一、环境信息

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

操作系统：Ubuntu 22.04.4 LTS（x86_64，内核 12 vCPU / 31GB 内存 / 786GB 磁盘）
OpenObserve：v1.1.1（镜像 public.ecr.aws/zinclabs/openobserve:v1.1.1，启动日志实测确认）
编排：Docker 29.8.1 + Docker Compose v5.5.1
对外端口：13902（宿主机）→ 5080（OpenObserve HTTP，Web 控制台与 API 共用）
数据目录：/opt/data/openobserve/ui（bind mount 到服务内 /data）
管理账号：root@example.com / Q1w2E3r4!（演示口令，首次启动通过环境变量创建）

二、镜像选型说明

官方发布的 OpenObserve 镜像主要有以下来源（官方文档，查询日期 2026-10-18）：

镜像	说明	适用
`public.ecr.aws/zinclabs/openobserve:<tag>`	AWS Public ECR 官方主仓库，标准构建	本文采用；实测拉取顺畅、版本齐全
`zinclabs/openobserve:<tag>`	Docker Hub 同步发布	Docker Hub 直连更快的网络环境
`public.ecr.aws/zinclabs/openobserve:<tag>-alpine`	Alpine 底座变体，体积更小	追求最小镜像

实测镜像体积：

public.ecr.aws/zinclabs/openobserve:v1.1.1  918MB

本文选型结论：采用 public.ecr.aws/zinclabs/openobserve:v1.1.1 固定版本 tag（而非 latest），理由：① 版本锁定保证回显可复现、升级可控；② ECR Public 在混合网络环境下可用性稳定。生产环境同样建议锁版本，升级时替换 tag 并回归验证。

三、前置条件

服务器已安装 Docker 与 Docker Compose 插件（docker --version、docker compose version 可执行）；
宿主机 13902 端口未被占用（可按需改成其他端口）；
规划好数据目录（本文用 /opt/data/openobserve/ui）；
准备初始管理员邮箱与口令（首次启动必须提供，否则服务启动即 panic，见 10.1）。

四、部署步骤

4.1 准备目录与编排文件

mkdir -p /opt/data/openobserve/ui
vim /opt/data/openobserve/docker-compose.yml

docker-compose.yml 全文（实测采用版本）：

services:
  openobserve:
    image: public.ecr.aws/zinclabs/openobserve:v1.1.1
    container_name: openobserve-v1.1.1-ui
    restart: unless-stopped
    ports:
      - "13902:5080"
    environment:
      ZO_ROOT_USER_EMAIL: "root@example.com"
      ZO_ROOT_USER_PASSWORD: "Q1w2E3r4!"
      ZO_DATA_DIR: "/data"
    volumes:
      - /opt/data/openobserve/ui:/data

逐段解析：

段	说明
`image`	锁定 v1.1.1 官方标准镜像（选型见第二节）
`container_name`	固定实例名，便于 `docker logs`/`docker stats` 定位
`restart: unless-stopped`	随守护进程自启；手动 stop 后不再自动拉起
`ports: "13902:5080"`	宿主机 13902 → 服务 5080；5080 是 OpenObserve 默认 HTTP 端口（Web 控制台与全部 API 共用）
`ZO_ROOT_USER_EMAIL` / `ZO_ROOT_USER_PASSWORD`	首次启动创建初始管理员的邮箱与口令；必须合法邮箱格式
`ZO_DATA_DIR: "/data"`	数据根目录；配合 volumes 挂载实现持久化
`volumes`	数据目录 bind mount 到宿主机，服务重建/升级数据不丢

⚠️ 注意：示例口令仅作演示。生产环境请改用强口令，并可通过 ZO_ROOT_USER_PASSWORD 先设定，首登后再在控制台修改；更完善的 TLS/网络加固见《OpenObserve 安全加固指南》规划（本专栏后续篇目）。

4.2 启动与验证

cd /opt/data/openobserve
docker compose up -d

实测回显（节选）：

 Container openobserve-v1.1.1-ui Started

验证服务状态与健康检查：

docker compose ps --format '{{.Name}} {{.Status}}'
curl -s http://localhost:13902/healthz

实测回显：

openobserve-v1.1.1-ui Up 4 seconds
{"status":"ok"}

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

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

浏览器访问 http://<服务器IP>:13902，用 root@example.com 与设定口令登录即完成部署。资源占用参考（空载实测 docker stats --no-stream）：

openobserve-v1.1.1-ui: CPU 1.05% MEM 130.8MiB / 31.3GiB

五、数据持久化说明

数据全部落在 ZO_DATA_DIR（即挂载点 /opt/data/openobserve/ui），目录结构与用途：

cache   # 查询/对象缓存
db      # SQLite 元数据（用户、流配置、仪表盘、告警等）
mmdb    # GeoIP 数据库（IP 地理定位用）
stream  # 各数据流的本地 Parquet 数据文件
tmp     # 临时文件
wal     # Write-Ahead Log，摄入缓冲，先于 Parquet 落盘

down/up 持久化实测：先向 persist_test 流写入一条标记数据，然后 docker compose down 彻底销毁服务与网络，再 up -d 重建并查询该数据，验证不丢：

# 1. 写入标记数据
curl -s -u root@example.com:'Q1w2E3r4!' -X POST "http://localhost:13902/api/default/persist_test/_json" \
  -H "Content-Type: application/json" -d '[{"msg":"before-restart","v":1}]'

# 2. 销毁并重建
docker compose down
docker compose up -d

down 实测回显（节选，容器停止/移除之后）：

 Network openobserve_default Removing
 Network openobserve_default Removed

down 之后宿主机数据目录原样保留：

cache
db
mmdb
stream
tmp
wal

up 重建后查询标记数据（最近 24 小时）：

NOW=$(date +%s)
curl -s -u root@example.com:'Q1w2E3r4!' -X POST "http://localhost:13902/api/default/_search" \
  -H "Content-Type: application/json" \
  -d "{\"query\":{\"sql\":\"SELECT * FROM persist_test LIMIT 2\",\"start_time\":$(( (NOW-86400)*1000000 )),\"end_time\":$(( NOW*1000000 ))}}"

实测回显（节选）：

{"took":31,...,"hits":[{"_timestamp":1792293846205223,"msg":"before-restart","v":1}],"total":1,...,"is_partial":false}

before-restart 记录在重建后完好可查，持久化验证通过。

六、环境变量表

部署中最常用的环境变量（完整参数见《OpenObserve v1.1.1 配置参数详解》）：

环境变量	默认值	说明
`ZO_ROOT_USER_EMAIL`	无（首次初始化必填）	初始管理员邮箱
`ZO_ROOT_USER_PASSWORD`	无（首次初始化必填）	初始管理员口令
`ZO_DATA_DIR`	`./data/openobserve/`	数据根目录；必须显式设置为挂载点
`ZO_HTTP_PORT`	5080	HTTP 监听端口（改它需同步改 ports 映射）
`ZO_GRPC_PORT`	5081	gRPC 监听端口（内部通信用）
`ZO_MEMORY_CACHE_MAX_SIZE`	物理内存 25%（实测 31.3GB 主机默认 7.82GB）	内存结果缓存上限（MB）
`ZO_TELEMETRY`	true	是否上报匿名遥测，内网环境建议 false

七、配置参数说明

单机部署的配置全部通过环境变量注入（OpenObserve 无默认配置文件，所有参数等价于 ZO_ 前缀环境变量）。上文 compose 已包含最小必需集；常用增强项：

数据留存：ZO_COMPACT_DATA_RETENTION_DAYS（全局数据保留天数）；
缓存上限：ZO_MEMORY_CACHE_MAX_SIZE、ZO_DISK_CACHE_MAX_SIZE（防缓存吃满资源）；
关闭 UI（纯 API 网关模式）：ZO_UI_ENABLED=false；
日志结构化输出：ZO_LOG_JSON_FORMAT=true。

各参数的默认值、实测验证与踩坑实录详见《OpenObserve v1.1.1 配置参数详解》。

八、配置文件挂载

OpenObserve 自身不依赖配置文件，常规部署无需挂载配置。如需自定义 GeoIP 库等静态资源，可追加挂载，例如：

    volumes:
      - /opt/data/openobserve/ui:/data
      - /opt/data/openobserve/conf:/etc/openobserve   # 可选：自定义静态资源

修改编排文件后执行 docker compose up -d 重建即可生效（配置仅以环境变量方式存在，重建时随服务注入）。

九、等价 docker run

不使用 Compose 时，以下单条 docker run 与上文编排完全等价（同镜像、同端口、同环境变量、同挂载）：

docker run -d \
  --name openobserve-v1.1.1-equiverify \
  --restart unless-stopped \
  -p 13913:5080 \
  -v /opt/data/openobserve/equiv:/data \
  -e ZO_ROOT_USER_EMAIL="root@example.com" \
  -e ZO_ROOT_USER_PASSWORD="Q1w2E3r4!" \
  -e ZO_DATA_DIR="/data" \
  public.ecr.aws/zinclabs/openobserve:v1.1.1

等价性验证（本机实测，端口用 13913 避免与 Compose 实例冲突）：

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

实测回显：

{"status":"ok"}

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

2026-10-18T03:24:30.407166383+00:00 INFO openobserve: Starting OpenObserve v1.1.1
2026-10-18T03:24:30.407228926+00:00 INFO openobserve: System info: CPU cores 12, MEM total 31.30 GB, Disk total 785.88 GB, free 538.46 GB

十、常用运维命令

# 查看实时日志
docker logs -f openobserve-v1.1.1-ui --tail 100
# 查看资源占用
docker stats --no-stream openobserve-v1.1.1-ui
# 重启服务
docker compose restart
# 停止并移除（数据保留在宿主机挂载目录）
docker compose down
# 升级版本：改 compose 中 image tag 后重建
docker compose up -d

💡 说明：升级前建议备份 /opt/data/openobserve/ui/db（SQLite 元数据）。小版本升级（如 v1.1.1 → 后续补丁版）数据格式由服务自动迁移；跨大版本升级前先阅读官方 Release Notes。

十一、常见问题（FAQ）

Q1：启动立即退出，日志报 "Please set root user email-id & password"

首次用全新数据目录启动时未设置 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

解决：在 compose 的 environment 补上这两个变量再 up -d。注意邮箱必须合法（xxx@yyy.zz 格式）；已有用户数据的服务重启不依赖这两个变量。

Q2：修改 ZO_HTTP_PORT 后启动失败

OpenObserve 的 gRPC 端口默认是 HTTP 端口 +1（5080/5081）。若只把 HTTP 改成 5081 而未动 gRPC，两者会撞车，实测日志出现 Address already in use 且服务起不来。解决：同时设置 ZO_HTTP_PORT 与 ZO_GRPC_PORT（错开即可），并同步调整 ports 映射。

Q3：不设置 ZO_DATA_DIR 会怎样

默认值是相对路径 ./data/openobserve/，落在服务内工作目录；若该目录不可写（例如以只读方式运行）会在启动阶段直接报错退出。务必显式设置 ZO_DATA_DIR 并挂载到宿主机——这也是本文 compose 的必需配置项。

Q4：控制台能打开但搜索无数据

先确认摄入 API 返回了 successful 计数（{"code":200,"status":[{"name":"app_logs","successful":5,"failed":0}]}），再检查查询时间范围是否覆盖数据时间戳；OpenObserve 查询时间参数是微秒时间戳（秒 ×1,000,000），给成秒/毫秒是最常见的"查不到"原因。

十二、参考链接

官方安装文档：https://openobserve.ai/docs/installation/docker/
镜像仓库（ECR Public）：https://gallery.ecr.aws/zinclabs/openobserve
环境变量手册：https://openobserve.ai/docs/environment-variables/
本专栏姊妹篇：《OpenObserve 快速入门》《OpenObserve v1.1.1 配置参数详解》《OpenObserve v1.1.1 API 使用详解》