SeekDB安装部署指南：详解Docker、二进制包及三种生产部署模式

本文旨在指导用户通过多种分发方式安装 OceanBase SeekDB，并详细阐述其三种核心部署架构，帮助您根据开发测试或生产环境的需求选择最佳方案。

安装方法概述

OceanBase SeekDB 主要提供三种安装途径，以适应不同的使用场景：

Docker容器安装

对于快速测试和开发环境，Docker 是最便捷的方式。官方镜像已预置了适用于独立运行的 observer 服务。

快速开始

通过以下命令即可快速启动一个SeekDB实例：

docker run -d \
  --name seekdb \
  -p 2881:2881 \
  -v ./data:/var/lib/oceanbase/store \
  oceanbase/seekdb:latest

Docker配置说明

参数	描述	默认值
-p 2881:2881	映射MySQL协议端口	2881
-v ./data:/var/lib/oceanbase/store	挂载数据持久化目录	无（临时存储）
--name seekdb	指定容器名称	随机生成

该镜像在启动时会执行初始化脚本，以独立模式配置并启动 observer 进程。

Docker文件结构

镜像内部的文件组织如下：

二进制包安装

对于Linux系统的生产环境部署，推荐使用 RPM 或 DEB 二进制包。它们提供了完整的 observer 和 obproxy 二进制文件，并与 systemd 集成。

RPM安装（适用于RHEL/CentOS/AlmaLinux等）

# 安装RPM包
rpm -ivh seekdb-1.x.x.x-xxxxxxx.el8.x86_64.rpm

# 启动服务（如果包含systemd集成）
systemctl start oceanbase-seekdb

DEB安装（适用于Ubuntu/Debian等）

# 安装DEB包
dpkg -i seekdb-1.x.x.x-xxxxxxx_amd64.deb

# 如有需要，解决依赖关系
apt-get install -f

Systemd集成

二进制包包含了用于服务生命周期管理的脚本：

脚本	用途	位置
preinst	安装前检查	tools/systemd/profile/preinst
postinst	安装后设置	tools/systemd/profile/postinst
prerm	卸载前清理	tools/systemd/profile/prerm
postrm	卸载后清理	tools/systemd/profile/postrm
telemetry.sh	遥测配置	tools/systemd/profile/telemetry.sh

此外，也提供了 RHEL 风格的等价脚本：pre_install.sh, post_install.sh, pre_uninstall.sh, post_uninstall.sh。

Python SDK安装

Python SDK (pyseekdb) 提供了一种嵌入式数据库模式，无需独立数据库服务进程，非常适合 AI/ML 工作流 和快速原型开发。

安装

pip install -U pyseekdb

嵌入式模式使用

该SDK封装了 observer 二进制文件，可将其作为进程内嵌的数据库运行：

import pyseekdb

# 嵌入式模式 - observer运行在应用程序进程内
client = pyseekdb.Client(
    path="./seekdb.db",  # 本地数据库文件
    database="test"
)

在此模式下，observer 的生命周期由 SDK 自动管理，所有数据存储在指定的 .db 文件中。

部署模式详解

OceanBase SeekDB 支持三种部署架构，每种架构对应不同的资源配置和适用场景。

嵌入式模式

在嵌入式模式下，observer 作为库函数运行在应用程序进程内部，数据库文件（.db）直接存储在本地文件系统。

核心特点：

• 无需独立数据库服务进程。
• 单用户访问（不通过网络协议）。
• 资源占用极低。
• 适用于开发、测试及边缘计算场景。

配置说明：

• 无需外部配置文件。
• 通过 SDK 连接字符串指定数据库文件路径。
• 所有数据集中于单个 .db 文件。

单节点模式

单节点模式将 observer 作为独立服务器进程运行，监听 2881 端口（MySQL协议），是最常见的开发及小型生产环境部署方式。

核心特点：

• 单个 observer 进程。
• 支持多用户通过网络访问。
• 提供完整的 SQL 及事务支持。

配置文件：	文件	用途	位置
single.yaml	基础单节点配置	tools/deploy/single.yaml
single-with-proxy.yaml	单节点+代理配置	tools/deploy/single-with-proxy.yaml
standalone_default_parameter.json	独立模式默认参数	src/share/parameter/standalone_default_parameter.json
standalone_default_system_variable.json	独立模式系统变量	src/share/system_variable/standalone_default_system_variable.json

手动启动示例：

./observer -r 127.0.0.1:2881:2882 \
           -p 2881 \
           -P 2882 \
           -z zone1 \
           -d /var/lib/oceanbase/store \
           -n seekdb

分布式模式

分布式模式由多个 observer 节点、共享存储后端以及前端的 obproxy（负责连接路由与负载均衡）构成。对于大规模的分布式数据库集群管理与编排，可以参考 云原生/IaaS 相关的实践。

核心特点：

• 多个 observer 节点。
• 共享存储后端（如NFS、对象存储）。
• 通过 obproxy 实现高可用和水平扩展。

配置文件：	文件	用途	位置
distributed.yaml	基础分布式配置	tools/deploy/distributed.yaml
distributed-with-proxy.yaml	分布式+代理配置	tools/deploy/distributed-with-proxy.yaml
shared_storage_default_parameter.json	共享存储默认参数	src/share/parameter/shared_storage_default_parameter.json
shared_storage_default_system_variable.json	共享存储系统变量	src/share/system_variable/shared_storage_default_system_variable.json

架构组件：

• obproxy：服务入口，监听 2883 端口，将连接路由至后端 observer。
• observer 节点：数据库引擎，监听 2881 端口，访问共享存储。
• 共享存储：统一的数据持久化层。

配置系统

SeekDB 为独立部署和共享存储部署准备了不同的配置系统，每种模式拥有独立的参数和变量文件。

参数文件

参数主要用于控制数据库内部行为，如内存分配、线程池和存储设置。这些文件在构建时生成：

• 独立参数：src/share/parameter/standalone_default_parameter.json
• 共享存储参数：src/share/parameter/shared_storage_default_parameter.json
  部分参数支持在运行时动态修改。

系统变量

系统变量控制 SQL 行为、兼容性模式和会话设置：

• 独立变量：src/share/system_variable/standalone_default_system_variable.json
• 共享存储变量：src/share/system_variable/shared_storage_default_system_variable.json

部署YAML配置参考

tools/deploy 目录下提供了用于 OBD（OceanBase Deployer） 或手动部署的 YAML 模板。

主要配置模板

文件	部署类型	包含组件	适用场景
single.yaml	单节点	observer	开发、测试
single-with-proxy.yaml	单节点+代理	observer, obproxy	带代理的单节点环境
distributed.yaml	分布式	observer (多个)	生产集群
distributed-with-proxy.yaml	分布式+代理	observer (多个), obproxy	带负载均衡的生产环境

测试专用配置

此外，还包含用于特定测试的配置，如 tpchobp_test.yaml (TPC-H基准测试)、bmsqlobp_test.yaml (BM-SQL基准测试) 等，主要用于CI/CD流水线和集成测试。

OBD集成

OceanBase Deployer (OBD) 是一个基于 YAML 配置的集群部署与管理工具。

目录结构

tools/deploy/
  ├── .obd/              # OBD 工作目录
  ├── obd_profile.sh     # OBD 环境设置脚本
  ├── single.yaml        # 单节点模板
  ├── distributed.yaml   # 分布式模板
  └── [其他配置文件]

使用示例

通过 obd_profile.sh 设置环境后，即可使用 OBD 部署集群：

source tools/deploy/obd_profile.sh
obd cluster deploy seekdb-cluster -c distributed.yaml
obd cluster start seekdb-cluster

OBD 负责管理二进制分发、配置生成、服务启停、健康监控和升级流程。

端口与网络配置

不同组件使用不同的网络端口：

组件	端口	协议	描述
observer	2881	MySQL	SQL客户端连接
observer	2882	RPC	内部集群通信
obproxy	2883	MySQL	代理服务入口

防火墙配置示例

单节点部署需开放 observer 端口：

firewall-cmd --permanent --add-port=2881/tcp
firewall-cmd --reload

分布式部署需开放全部相关端口：

firewall-cmd --permanent --add-port=2881/tcp
firewall-cmd --permanent --add-port=2882/tcp
firewall-cmd --permanent --add-port=2883/tcp
firewall-cmd --reload

数据目录结构

observer 将数据存储于指定的数据目录中（Docker默认为 /var/lib/oceanbase/store）。

目录布局

/var/lib/oceanbase/store/
  ├── clog/           # 提交日志
  ├── ilog/           # 索引日志
  ├── sstable/        # SSTable数据文件
  ├── slog/           # 系统日志
  └── etc/            # 运行时配置

.gitignore 文件排除了各类运行时数据和日志目录，避免误提交至版本库。

二进制文件位置

安装后，关键二进制文件位于以下路径：

安装方式	observer 路径	obproxy 路径
二进制包	/usr/bin/observer	/usr/bin/obproxy (如包含)
Docker 镜像	/opt/oceanbase/bin/observer	/opt/oceanbase/bin/obproxy
源码构建	build_debug/src/observer/observer 等	build_debug/src/obproxy/obproxy 等

安装验证与测试

部署完成后，可通过以下步骤进行验证：

1. 检查版本

./observer --version
./obproxy --version

2. 验证服务状态

# 检查端口监听
netstat -tlnp | grep 2881

# 查看systemd服务状态
systemctl status oceanbase-seekdb

3. 连接数据库

使用 Python SDK 进行连接是验证服务的一种灵活方式，特别是对于嵌入式或快速原型场景。更多关于 Python 的数据库操作实践可供参考。

# 使用mysql客户端
mysql -h 127.0.0.1 -P 2881 -u root

# 使用Python SDK
python3 << EOF
import pyseekdb
client = pyseekdb.Client(host="127.0.0.1", port=2881, database="test")
print("Connected successfully")
EOF

故障排查指南

常见问题

问题	可能原因	解决方案
端口 2881 被占用	其他MySQL服务冲突	停止冲突服务或修改监听端口
数据目录权限不足	文件系统权限设置错误	使用 chown 更改目录属主
启动失败提示缺少库	系统依赖未安装	安装缺失的共享库
Observer 启动失败	磁盘空间不足	确保数据目录有足够空间

关键日志文件

• observer.log*：主服务日志。
• tools/deploy/mytest.log*：部署测试日志。
• tools/obtest/mytest.log*：集成测试日志。

调试模式

对于开发问题排查，可使用调试模式构建并运行：

bash build.sh debug --init --make
./build_debug/src/observer/observer -d /tmp/seekdb-debug

调试版本包含更详细的日志和断言信息。

---

附录：配置系统的动态管理与运维调优

SeekDB的配置系统区分了“独立参数”与“共享存储参数”，并支持部分参数在运行时动态修改，这极大提升了运维灵活性。在性能调优或故障排除时，可以直接通过SQL命令调整运行参数，例如调整日志级别：set ob_log_level=debug;。这避免了重启服务，是实现 运维/DevOps 中快速响应和变更的关键能力。

当遇到性能瓶颈或启动失败时，运维人员应首先查看 observer.log 等日志文件。SeekDB的日志系统集成了 Trace ID，可以将单个SQL请求的所有相关日志串联起来。结合动态可调的参数（如内存上限 memory_limit_percentage），可以快速分析出问题是源于资源配置不足，还是特定的业务配置错误，从而实现精准定位与调优。