OpenTenBase 企业级分布式 HTAP 数据库部署指南

关键配置说明：

• vm.swappiness = 10：减少 swap 使用，提高数据库性能。
• 网络缓冲区设置：优化分布式节点间通信。
• 文件句柄限制：支持高并发连接。

3. OpenTenBase 安装部署

3.1 软件依赖

OpenTenBase 编译需要以下依赖包。推荐使用 dnf 或 yum 安装：

sudo dnf install -y \
    gcc \
    gcc-c++ \
    make \
    cmake \
    readline-devel \
    zlib-devel \
    openssl-devel \
    uuid-devel \
    bison \
    flex \
    git \
    libcurl-devel \
    libxml2-devel \
    libxslt-devel \
    perl-IPC-Run \
    perl-Test-Simple \
    tcl-devel \
    python3-devel \
    rpm-build \
    pkgconfig \
    krb5-devel \
    openldap-devel

此外，还需要手动编译安装 zstd 和 lz4 压缩库：

# 下载 zstd 源码
cd /tmp
wget https://github.com/facebook/zstd/releases/download/v1.5.2/zstd-1.5.2.tar.gz
tar -xzf zstd-1.5.2.tar.gz
cd zstd-1.5.2
make
sudo make install PREFIX=/usr/local
sudo ldconfig
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

# 下载 lz4 源码
cd /tmp
wget https://github.com/lz4/lz4/archive/v1.9.4.tar.gz
tar -xzf v1.9.4.tar.gz
cd lz4-1.9.4
make
sudo make install PREFIX=/usr/local
sudo ldconfig
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

3.2 用户与环境初始化

所有需要安装 OpenTenBase 集群的机器都需要创建专用用户，避免权限问题。

# 创建数据目录
sudo mkdir /data

# 创建 opentenbase 用户
sudo useradd -d /data/opentenbase -s /bin/bash -m opentenbase

# 设置密码
sudo passwd opentenbase

# 切换到 opentenbase 用户
su - opentenbase

3.3 源码编译安装

获取源码

cd /data/opentenbase
git clone https://gitee.com/mirrors/OpenTenBase.git

编译源码

# 设置环境变量
export SOURCECODE_PATH=/data/opentenbase/OpenTenBase
export INSTALL_PATH=/data/opentenbase/install

# 进入源码目录
cd ${SOURCECODE_PATH}
chmod +x configure*

# 清理旧编译产物
make distclean 2>/dev/null || true
rm -rf /data/opentenbase/install/opentenbase_bin_v2.0
rm -f config.status config.log

# 重新配置，添加 SSE4.2 支持
CFLAGS="-g -O2 -w -msse4.2 -mcrc32" \
CXXFLAGS="-g -O2 -w -msse4.2 -mcrc32" \
./configure --prefix=/data/opentenbase/install/opentenbase_bin_v2.0 \
--enable-user-switch \
--with-openssl \
--with-ossp-uuid \
--with-libxml

# 编译
make
make install

# 编译 contrib 模块
chmod +x contrib/pgxc_ctl/make_signature
cd contrib
make
make install

4. 集中式单节点集群配置

4.1 配置环境变量

# 编辑 bashrc 文件
vim ~/.bashrc

# 添加以下内容：
export OPENTENBASE_HOME=/data/opentenbase/install/opentenbase_bin_v2.0
export PATH=$OPENTENBASE_HOME/bin:$PATH
export LD_LIBRARY_PATH=$OPENTENBASE_HOME/lib:${LD_LIBRARY_PATH}
export LC_ALL=C

# 生效环境变量
source ~/.bashrc

4.2 创建集群配置文件

我们需要配置 pgxc_ctl.conf 来定义集群拓扑。这是一个关键步骤，请仔细核对路径和端口。

cat > /data/opentenbase/install/opentenbase_bin_v2.0/pgxc_ctl.conf << 'EOF'
#!/usr/bin/env bash
#---- OVERALL -----------------------------------------------------------------------------
pgxcOwner=opentenbase
pgxcUser=$pgxcOwner
tmpDir=/tmp
localTmpDir=$tmpDir
configBackup=y
configBackupHost=localhost
configBackupDir=$HOME/pgxc
configBackupFile=pgxc_ctl.bak

#---- GTM --------------------------------------------------------------------------------
gtmName=gtm
gtmMasterServer=localhost
gtmMasterPort=6666
gtmMasterDir=/data/opentenbase/data/gtm
gtmExtraConfig=none
gtmMasterSpecificExtraConfig=none
gtmSlave=n
gtmSlaveName=gtmSlave
gtmSlaveServer=none
gtmSlavePort=20001
gtmSlaveDir=none
gtmSlaveSpecificExtraConfig=none
gtmProxy=n
gtmProxyNames=()
gtmProxyServers=()
gtmProxyPorts=()
gtmProxyDirs=()
gtmPxyExtraConfig=none
gtmPxySpecificExtraConfig=()

#---- Coordinators --------------------------------------------------------------------
coordMasterDir=/data/opentenbase/data/coord_master
coordSlaveDir=/data/opentenbase/data/coord_slave
coordArchLogDir=/data/opentenbase/data/coord_archlog

# 协调器配置数组 - 所有数组必须有相同数量的元素
coordNames=(cn001)
coordPorts=(30004)
poolerPorts=(30014)
coordForwardPorts=(30024)
coordPgHbaEntries=(0.0.0.0/0)

# Master Coordinators
coordMasterServers=(localhost)
coordMasterDirs=(/data/opentenbase/data/coord_master/cn001)
coordMaxWALsender=5
coordMaxWALSenders=(5)

# Coordinator Slave - disabled
coordSlave=n
coordSlaveSync=n
coordSlaveServers=(none)
coordSlavePorts=(30005)
coordSlavePoolerPorts=(30015)
coordSlaveForwardPorts=(30025)
coordSlaveDirs=(none)
coordArchLogDirs=(none)
coordExtraConfig=none
coordSpecificExtraConfig=(none)
coordSpecificExtraPgHba=(none)

#---- Datanodes -----------------------------------------------------------------------
datanodeMasterDir=/data/opentenbase/data/dn_master
datanodeSlaveDir=/data/opentenbase/data/dn_slave
datanodeArchLogDir=/data/opentenbase/data/datanode_archlog

# 数据节点配置数组 - 所有数组必须有相同数量的元素
primaryDatanode=dn001
datanodeNames=(dn001)
datanodePorts=(20008)
datanodePoolerPorts=(20018)
datanodeForwardPorts=(20028)
datanodePgHbaEntries=(0.0.0.0/0)

# Master Datanodes
datanodeMasterServers=(localhost)
datanodeMasterDirs=(/data/opentenbase/data/dn_master/dn001)
datanodeMaxWalSender=5
datanodeMaxWALSenders=(5)

# Datanode Slave - disabled
datanodeSlave=n
datanodeSlaveServers=(none)
datanodeSlavePorts=(20009)
datanodeSlavePoolerPorts=(20019)
datanodeSlaveForwardPorts=(20029)
datanodeSlaveDirs=(none)
datanodeArchLogDirs=(none)
datanodeExtraConfig=none
datanodeSpecificExtraConfig=(none)
datanodeSpecificExtraPgHba=(none)
walArchive=n
EOF

检查配置文件语法：

bash -n /data/opentenbase/install/opentenbase_bin_v2.0/pgxc_ctl.conf
echo "配置文件语法检查结果： $?"

4.3 部署和初始化集群

配置 SSH 免密登录是集群管理的必要前提：

# 生成 SSH 密钥（如果还没有）
if [ ! -f ~/.ssh/id_rsa ]; then
    ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
fi

# 配置本地免密登录
ssh-copy-id opentenbase@localhost
# 或者手动添加
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

启动 pgxc_ctl 工具进行部署：

# 启动 pgxc_ctl 工具
pgxc_ctl

# 在 pgxc_ctl 命令行中执行：
deploy all
init all
start all
monitor all

验证集群状态，正常情况下应显示所有组件 Running：

Running: gtm master
Running: coordinator master cn001
Running: datanode master dn001

4.4 配置防火墙（可选）

如果启用了防火墙，需要开放相应端口：

# 开放 GTM 端口
sudo firewall-cmd --permanent --add-port=50001/tcp

# 开放 Coordinator 端口
sudo firewall-cmd --permanent --add-port=30004/tcp
sudo firewall-cmd --permanent --add-port=31110/tcp

# 开放 Datanode 端口
sudo firewall-cmd --permanent --add-port=40004/tcp
sudo firewall-cmd --permanent --add-port=41110/tcp

# 重新加载防火墙规则
sudo firewall-cmd --reload

5. 数据库初始化和使用

5.1 连接数据库

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

5.2 创建必要的节点组和分片组

OpenTenBase 使用数据节点组来增加节点管理的灵活性。通常，所有数据节点都会被添加到默认组中：

-- 创建默认节点组
CREATE DEFAULT NODE GROUP default_group WITH (dn001);

-- 创建分片组
CREATE SHARDING GROUP TO GROUP default_group;

5.3 创建数据库和表

-- 创建测试数据库
CREATE DATABASE testdb;

-- 创建用户
CREATE USER testuser WITH PASSWORD 'testpass';

-- 授权
ALTER DATABASE testdb OWNER TO testuser;

-- 切换到测试数据库
\c testdb testuser

-- 创建分片表
CREATE TABLE test_table(
    id BIGINT,
    name TEXT,
    created_time TIMESTAMP DEFAULT NOW()
) DISTRIBUTE BY SHARD(id);

-- 插入测试数据
INSERT INTO test_table(id, name) VALUES (1, 'OpenTenBase'), (2, 'TencentCloud'), (3, 'OpenCloudOS');

-- 查询测试
SELECT * FROM test_table;

6. 集群管理与运维

6.1 集群管理命令

• 启动集群：pgxc_ctl start all
• 停止集群：pgxc_ctl stop all
• 清理集群：pgxc_ctl clean all（重新初始化时使用）

6.2 查看日志

如果初始化失败，可以查看日志定位问题：

# 查看 pgxc_ctl 日志
ls ~/pgxc_ctl/pgxc_log/
cat ~/pgxc_ctl/pgxc_log/最新的日志文件

# 查看各组件日志
ls /data/opentenbase/data/gtm/pg_log/
ls /data/opentenbase/data/coord/pg_log/
ls /data/opentenbase/data/dn001/pg_log/

6.3 性能监控查询

-- 集群节点状态查询
SELECT node_name, node_type, node_host, node_port, 
       CASE WHEN status = 'N' THEN '正常' WHEN status = 'D' THEN '下线' ELSE '未知' END AS node_status 
FROM pgxc_node ORDER BY node_type, node_name;

-- 分布式表统计信息
SELECT schemaname, tablename, n_tup_ins as "插入行数", n_tup_upd as "更新行数", n_tup_del as "删除行数", last_analyze as "最近分析时间" 
FROM pg_stat_user_tables WHERE schemaname NOT IN ('information_schema', 'pg_catalog') ORDER BY n_tup_ins DESC LIMIT 10;

-- 数据节点负载分析
WITH node_stats AS (
    SELECT node_name, pg_stat_get_db_blocks_fetched(oid) as blocks_read, pg_stat_get_db_blocks_hit(oid) as blocks_hit 
    FROM pg_database, pgxc_node WHERE datname = current_database()
)
SELECT node_name, blocks_read, blocks_hit, 
       CASE WHEN (blocks_read + blocks_hit) > 0 THEN round(blocks_hit::numeric / (blocks_read + blocks_hit) * 100, 2) ELSE 0 END as cache_hit_ratio 
FROM node_stats ORDER BY cache_hit_ratio DESC;

7. 性能优化建议

7.1 内存优化

根据服务器配置调整 postgresql.conf 中的内存参数：

shared_buffers = 25% of RAM
effective_cache_size = 75% of RAM
work_mem = 4MB
maintenance_work_mem = 64MB

7.2 连接优化

max_connections = 200
max_pool_size = 1000

7.3 日志优化

log_min_duration_statement = 1000
log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h '
log_checkpoints = on
log_connections = on
log_disconnections = on

8. 实战经验总结

在实际部署过程中，我们需要注意以下几点：

1. 兼容性：OpenTenBase 继承了 PostgreSQL 的特性，大部分现有 SQL 语句无需修改即可迁移。
2. 弹性扩展：支持在线扩容，从 4 个数据节点扩展到 8 个节点时，数据重分布过程对业务影响最小。
3. 监控体系：建议配合 Prometheus + Grafana 构建监控，重点关注分布式事务延迟和跨节点查询响应时间。
4. 故障恢复：节点故障时的自动恢复机制运作良好，但需定期检查 WAL 归档状态。

总的来说，OpenTenBase 在企业级分布式 HTAP 场景下表现优异，特别是在处理大规模数据查询和高并发写入方面。虽然分布式事务性能相比单机略有下降，但整体满足业务需求。

参考链接

1. OpenTenBase 官方文档
2. PostgreSQL 分布式扩展最佳实践