OpenTenBase数据库单机部署实战：新手从零到一避坑指南

原创

穿过生命散发芬芳

发布于 2025-09-17 00:00:14

5400

代码可运行

运行总次数：0

代码可运行

在当前数据库国产化替代浪潮中，OpenTenBase作为腾讯开源的分布式HTAP数据库，凭借其双内核架构、高兼容性和金融级高可用特性，正逐渐成为企业级应用的首选。

本文将分享部署和使用OpenTenBase单机版的全流程经验，包括安装部署、配置调试等关键环节。

一、环境准备与单机版安装部署

1.1 环境要求确认

在开始部署前，我首先确认了系统环境要求：

操作系统：CentOS 7.9
内存：8GB
磁盘空间：100GB
网络：确保主机间网络互通，关闭防火墙

1.2 依赖安装

在CentOS系统上执行了以下依赖安装命令：

# 安装编译依赖
yum -y install git sudo gcc make readline-devel zlib-devel openssl-devel uuid-devel bison flex cmake postgresql-devel libssh2-devel sshpass  libcurl-devel libxml2-devel

1.3 用户与目录准备

创建专用用户并设置目录权限：

mkdir /data
useradd -d /data/opentenbase -s /bin/bash -m opentenbase
passwd opentenbase # set password
usermod -aG wheel opentenbase

取消注释 "% wheel" 行，保存并退出。

为 wheel 组启用 sudo 权限（通过 visudo）
visudo

1.4 源码获取与编译

源码获取。

su - opentenbase
cd /data/opentenbase/
git clone https://github.com/OpenTenBase/OpenTenBase

设置环境变量。

export SOURCECODE_PATH=/data/opentenbase/OpenTenBase
export INSTALL_PATH=/data/opentenbase/install

开始编译，切换到OpenTenbase。

cd ${SOURCECODE_PATH}
rm -rf ${INSTALL_PATH}/opentenbase_bin_v2.0
chmod +x configure*

./configure --prefix=${INSTALL_PATH}/opentenbase_bin_v2.0  --enable-user-switch --with-openssl  --with-ossp-uuid CFLAGS=-g

make clean

make -sj
make install

chmod +x contrib/pgxc_ctl/make_signature
cd contrib

make -sj
make install

1.5 配置文件初始化

单机版配置相对简单，只需配置一个节点。

先创建配置文件。

mkdir /data/opentenbase/pgxc_ctl
cd /data/opentenbase/pgxc_ctl
vim pgxc_ctl.conf

配置文件内容如下，按照自己环境的IP进行修改即可。

#!/bin/bash
# Single Node Config

IP_1=172.16.30.76
IP_2=

pgxcInstallDir=/data/opentenbase/install/opentenbase_bin_v2.0
pgxcOwner=opentenbase
defaultDatabase=postgres
pgxcUser=$pgxcOwner
tmpDir=/tmp
localTmpDir=$tmpDir
configBackup=n
configBackupHost=pgxc-linker
configBackupDir=$HOME/pgxc
configBackupFile=pgxc_ctl.bak


#---- GTM ----------
gtmName=gtm
gtmMasterServer=$IP_1
gtmMasterPort=50001
gtmMasterDir=/data/opentenbase/data/gtm
gtmExtraConfig=none
gtmMasterSpecificExtraConfig=none
gtmSlave=n
#gtmSlaveServer=$IP_2
#gtmSlavePort=50001
#gtmSlaveDir=/data/opentenbase/data/gtm
#gtmSlaveSpecificExtraConfig=none

#---- Coordinators -------
coordMasterDir=/data/opentenbase/data/coord
coordArchLogDir=/data/opentenbase/data/coord_archlog

coordNames=(cn001 )
coordPorts=(30004 )
poolerPorts=(31110 )
coordPgHbaEntries=(0.0.0.0/0)
coordMasterServers=($IP_1 )
coordMasterDirs=($coordMasterDir )
coordMaxWALsernder=1
coordMaxWALSenders=($coordMaxWALsernder )
coordSlave=n
coordSlaveSync=n
coordArchLogDirs=($coordArchLogDir )

coordExtraConfig=coordExtraConfig
cat > $coordExtraConfig <<EOF
#================================================
# Added to all the coordinator postgresql.conf
# Original: $coordExtraConfig

include_if_exists = '/data/opentenbase/global/global_opentenbase.conf'

wal_level = replica
wal_keep_segments = 256 
max_wal_senders = 4
archive_mode = on 
archive_timeout = 1800 
archive_command = 'echo 0' 
log_truncate_on_rotation = on 
log_filename = 'postgresql-%M.log' 
log_rotation_age = 4h 
log_rotation_size = 100MB
hot_standby = on 
wal_sender_timeout = 30min 
wal_receiver_timeout = 30min 
shared_buffers = 1024MB 
max_pool_size = 2000
log_statement = 'ddl'
log_destination = 'csvlog'
logging_collector = on
log_directory = 'pg_log'
listen_addresses = '*'
max_connections = 2000

EOF

coordSpecificExtraConfig=(none none)
coordExtraPgHba=coordExtraPgHba
cat > $coordExtraPgHba <<EOF

local   all             all                                     trust
host    all             all             0.0.0.0/0               trust
host    replication     all             0.0.0.0/0               trust
host    all             all             ::1/128                 trust
host    replication     all             ::1/128                 trust


EOF


coordSpecificExtraPgHba=(none none)
coordAdditionalSlaves=n	
cad1_Sync=n

#---- Datanodes ---------------------
dn1MstrDir=/data/opentenbase/data/dn001
#dn2MstrDir=/data/opentenbase/data/dn002
dn1SlvDir=/data/opentenbase/data/dn001
#dn2SlvDir=/data/opentenbase/data/dn002
dn1ALDir=/data/opentenbase/data/datanode_archlog
#dn2ALDir=/data/opentenbase/data/datanode_archlog

primaryDatanode=dn001
datanodeNames=(dn001 )
datanodePorts=(40004 )
datanodePoolerPorts=(41110 )
datanodePgHbaEntries=(0.0.0.0/0)
datanodeMasterServers=($IP_1 )
datanodeMasterDirs=($dn1MstrDir )
dnWALSndr=2
datanodeMaxWALSenders=($dnWALSndr )

datanodeSlave=n
#datanodeSlaveServers=($IP_2 $IP_1)
#datanodeSlavePorts=(50004 54004)
#datanodeSlavePoolerPorts=(51110 51110)
#datanodeSlaveSync=n
#datanodeSlaveDirs=($dn1SlvDir $dn2SlvDir)
datanodeArchLogDirs=($dn1ALDir/dn001 )

datanodeExtraConfig=datanodeExtraConfig
cat > $datanodeExtraConfig <<EOF
#================================================
# Added to all the coordinator postgresql.conf
# Original: $datanodeExtraConfig

include_if_exists = '/data/opentenbase/global/global_opentenbase.conf'
listen_addresses = '*' 
wal_level = replica 
wal_keep_segments = 256 
max_wal_senders = 4
archive_mode = on 
archive_timeout = 1800 
archive_command = 'echo 0' 
log_directory = 'pg_log' 
logging_collector = on 
log_truncate_on_rotation = on 
log_filename = 'postgresql-%M.log' 
log_rotation_age = 4h 
log_rotation_size = 100MB
hot_standby = on 
wal_sender_timeout = 30min 
wal_receiver_timeout = 30min 
shared_buffers = 1024MB 
max_connections = 4000 
max_pool_size = 4000
log_statement = 'ddl'
log_destination = 'csvlog'
wal_buffers = 1GB

EOF

datanodeSpecificExtraConfig=(none )
datanodeExtraPgHba=datanodeExtraPgHba
cat > $datanodeExtraPgHba <<EOF

local   all             all                                     trust
host    all             all             0.0.0.0/0               trust
host    replication     all             0.0.0.0/0               trust
host    all             all             ::1/128                 trust
host    replication     all             ::1/128                 trust


EOF


datanodeSpecificExtraPgHba=(none )

datanodeAdditionalSlaves=n
walArchive=n

#---- 新增修复项：协调节点和数据节点的转发端口配置
coordForwardPorts=(10001)  # 与 coordNames 数量一致（1 个）
datanodeForwardPorts=(20001)  # 与 datanodeNames 数量一致（1 个）

1.6 初始化与启动

启动 pgxc_ctl 工具后，安装包的分发（deploy all）。

在填写好配置文件后，运行 pgxc_ctl 工具，然后输入 "deploy all" 命令，将安装包分发到每个节点的IP机器上。这里只有本机一个节点。

cd /data/opentenbase/install/opentenbase\_bin\_v2.0/bin
./pgxc_ctl   

# 执行 deploy all 命令

初始化集群的每个节点（init all）。在安装包分发完成后，在 pgxc_ctl 工具中输入 "init all" 命令，初始化配置文件 pgxc_ctl.conf 中的所有节点，并启动。

init all

这个过程需要输入无数次密码，保持耐心。

当显示如下图，初始化完成。

使用monitor all 查看节点启动状态。

二、OpenTenBase 快速使用

2.1 访问集群

psql -h 172.16.30.77 -p 30004 -d postgres -U opentenbase

2.2 创建默认组和sharding表

使用数据库前需要创建default group以及sharding表

postgres=# create default node group default_group  with (dn001);

postgres=# create sharding group to group default_group;

2.3 数据库操作

创建数据库，用户，创建表，增删查改等操作

postgres=# create database feng;
CREATE DATABASE
postgres=# create user feng with password '12345678';
CREATE ROLE
postgres=# alter database feng owner to feng;
ALTER DATABASE
postgres=# \c feng feng
You are now connected to database "feng" as user "feng".
feng=> create table foo(id bigint, str text) distribute by shard(id);
CREATE TABLE
feng=> insert into foo values(1, 'tencent'), (2, 'beijing');
COPY 2
feng=> select * from foo;
 id |   str   
----+---------
  1 | tencent
  2 | beijing
(2 rows)

三、OpenTenBase 调优

3.1 系统参数调优

1、内存管理：调整内核参数（需在 /etc/sysctl.conf 中配置）：

# 减少 Swap 使用，优先使用物理内存
vm.swappiness = 4

# 控制脏页刷新频率，避免频繁刷盘
vm.dirty_background_ratio = 3
vm.dirty_ratio = 10

# 提高内存分配灵活性
vm.overcommit_memory = 2
vm.overcommit_ratio = 90
 
# 生效命令
  sysctl -p

2、用户级限制（在 /etc/security/limits.conf 中配置）：

opentenbase soft nofile 65536
opentenbase hard nofile 65536

3.2 数据库参数调优

1、共享缓冲区（shared_buffers）：推荐值：分配物理内存的 25%-40%，默认1024MB。

SET shared_buffers = '2GB';

2、最大连接数（max_connections）：推荐值：根据业务负载调整，避免资源争用。默认4000。

SET max_connections = 200;

3、预写日志（wal_buffers）：推荐值：分配物理内存的 1%-2%。默认1GB。

SET wal_buffers = '64MB';

4、开启慢查询日志，便于性能分析。慢查询阈值500ms。

SET log_min_duration_statement = 500;

四、部署问题汇总

4.1 zstd依赖问题

问题：在编译的时候报错如下

checking for inflate in -lz... yes
checking for ZSTD_compress in -lzstd... no
configure: error: zstd library not found.

解决方法：下载zstd-1.5.6包，离线安装zstd。

设置软连接。

ln -s /home/zstd-1.5.6/lib/libzstd.so.1 /usr/lib64/libzstd.so.1

4.2 lz4依赖问题

问题报错如下：

checking for LZ4_compress_default in -llz4... no
configure: error: lz4 library not found.

解决方法：

下载源码
cd /tmp
git clone https://github.com/lz4/lz4.git
cd lz4

编译并安装
make
sudo make install

4.3 c99mode报错

问题报错如图：

解决方法：

make CFLAGS+='-std=gnu99' -j4

4.4 不支持C++17报错

报错如下图所示：

在 CentOS 7.9 中，默认的 GCC 版本可能不支持 C++17。CentOS 7 默认使用的是 GCC 4.8.5，而 C++17 支持是从 GCC 6.1 开始引入的。

解决方法：升级到GCC8以上版本。

首先解决Cannot find a valid baseurl for repo: centos-sclo-rh/x86_64报错。

进入/etc/yum.repos.d目录，删除目录下面所有的软件包，删除命令如下：

sudo rm -rf *

下载安装阿里云镜像仓库：两条命令都行

sudo curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo

sudo wget -O /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo

下载安装阿里云epel.repo：

sudo curl -o /etc/yum.repos.d/epel.repo https://mirrors.aliyun.com/repo/epel-7.repo

sudo wget -O /etc/yum.repos.d/epel.repo https://mirrors.aliyun.com/repo/epel-7.repo

清除缓存：

yum clean all 
yum makecache
yum makecache fast

sudo yum install centos-release-scl

sudo yum install devtoolset-8-gcc\*

scl enable devtoolset-8 bash

echo "source /opt/rh/devtoolset-8/enable" >> ~/.bashrc

source ~/.bashrc

查看版本如下为安装成功

gcc --version
g++ --version

4.5 运行pgxc_ctl报错

报错如下图所示

解决方法：在pgxc_ctl.conf中最后添加如下两行。

协调节点和数据节点的转发端口配置
coordForwardPorts=(10001)  # 与 coordNames 数量一致（1 个）
datanodeForwardPorts=(20001)  # 与 datanodeNames 数量一致（1 个）

五、经验总结

环境准备是关键：虽然系统最小内存4G，但是建议配置8G以上。内存太低，在编译时总会报错。
git安装总是失败：使用github和gitee安装了4次，在make install时总有各种error，初始化时报错缺少initdb 和 pg_ctl ，无法完成部署。最后通过下载源码压缩包安装一次成功。
实践才是硬道理：步骤看起来很简单，却也花费了两三天时间，主要是编译中的报错比较多。
期待一键安装：当前的安装方式效率比较低，且特别用出错，针对不同的操作系统可能有各种未知问题，期望可以出一个镜像版，把所有依赖打包好，一键安装，多快好省。
利用社区资源：遇到问题可参考官方文档或社区讨论，也要积极求助大模型。

通过这次部署实践，我掌握了OpenTenBase的安装配置技巧和初步调优。OpenTenBase作为国产数据库的优秀代表，正在金融、政务等关键领域发挥越来越重要的作用。

OpenTenBase的双内核架构带来的巨大优势——既保持了MySQL的易用性，又具备了PostgreSQL的高级特性。其分布式架构设计为未来扩展预留了空间，即使从单机版起步，也能平滑过渡到集群环境。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

腾讯云数据库