日期：2025 年 9 月 14日

作者：林涛， 李枨

概述

作为 OpenTenBase 俱乐部的一员，我们基于在 CentOS 7 操作系统上成功编译和部署 OpenTenBase 5.0 的实践经验，完整实现了从源代码构建到系统功能验证的全流程技术落地，并重点解决了因第三方组件引起的许可证兼容性等问题，最终形成了一套具备高度可复用性的安装与配置指南。

OpenTenBase 是一款具备高可靠性和横向扩展能力的分布式关系型数据库，其采用的“GTM+CN+DN”体系结构逻辑清晰、部署灵活，仅需常规 x86 服务器即可搭建完整集群。该系统不仅适用于高校教学实验和科研验证环境，也能为校内各类中小型应用系统提供稳定可靠的数据底层支撑，非常契合校园实践环境中对低成本、易维护与高可扩展性的综合需求。

在实际操作过程中，我们以 CentOS 7 为基础平台，系统完成了依赖库安装、许可证合规处理、源码编译与链接等关键环节，成功生成 OpenTenBase 5.0 可执行程序。随后完成了单机环境下多节点集群的初始化与启动，通过精准配置全局事务管理器（GTM）、协调节点（CN）及数据节点（DN）的角色与通信参数，有效确保了集群内部的事务一致性与服务稳定运行。

本指南详细记录了编译过程中常见的许可证冲突问题及其对应解决方案，涵盖了环境准备、编译流程、集群配置及服务启停等完整步骤，具有较强的实操性与可复制性。未来，我们将以此为基础，进一步探索 OpenTenBase 在校园实际业务中的深度应用，积极推动“数据库与 AI”“分布式架构与教学管理”等融合创新场景的实践，助力 OpenTenBase 在高校生态中的广泛落地与发展。

环境要求

系统环境

• 操作系统 : centos7
• 内存 : 至少 4GB RAM (推荐 8GB+)
• 磁盘空间 : 至少 20GB 可用空间
• 网络 : 需要访问外网下载依赖包

用户权限

• 需要具有 sudo 权限的用户账户
• 建议创建专用的 opentenbase 用户

一、环境准备

1.1 创建专用用户

# 创建数据目录
sudo mkdir /data
# 创建 opentenbase 用户
sudo useradd -d /data/opentenbase -s /bin/bash -m opentenbase
# 设置密码
sudo passwd opentenbase
# 添加 sudo 权限
sudo visudo
# 在文件中添加：opentenbase ALL=(ALL) ALL

1.2 安装系统依赖

# 切换到 opentenbase 用户
su - opentenbase
#更换为国内镜像源
sudo mv /etc/yum.repos.d/CentOS-Base.repo /etc/yum.repos.d/CentOS-Base.repo.backup 	#备份原有仓库配置
sudo curl -o /etc/yum.repos.d/CentOS-Base.repo http://mirrors.aliyun.com/repo/Centos-7.repo	
#更新组信息的缓存格式
sudo yum groups mark convert
# 安装基础开发工具
sudo yum groupinstall -y "Development Tools"
# 1. 安装 EPEL 仓库
#使用阿里云镜像
curl -O https://mirrors.aliyun.com/epel/7/x86_64/Packages/e/epel-release-7-14.noarch.rpm
#检查文件类型
file epel-release-*.rpm		# 如果显示 "RPM v3.0 package" 或类似信息，则表示是有效的 RPM 包
安装 EPEL 发布包
sudo rpm -ivh epel-release-*.rpm
# 2. 安装 SCL 仓库
#下载阿里云的 CentOS-Base 配置（包含 SCL 仓库）
sudo curl -o /etc/yum.repos.d/CentOS-Base.repo http://mirrors.aliyun.com/repo/Centos-7.repo
# 下载阿里云的 EPEL 配置
sudo curl -o /etc/yum.repos.d/epel.repo http://mirrors.aliyun.com/repo/epel-7.repo
#安装 SCL 仓库
sudo yum install -y centos-release-scl
# 替换 scl 仓库的镜像地址
sudo sed -i 's/mirrorlist=http:\/\/mirrorlist.centos.org/#mirrorlist=http:\/\/mirrorlist.centos.org/g' /etc/yum.repos.d/CentOS-SCLo*.repo
sudo sed -i 's/#baseurl=http:\/\/mirror.centos.org/baseurl=https:\/\/mirrors.aliyun.com\/centos/g' /etc/yum.repos.d/CentOS-SCLo*.repo
##手动编辑配置文件，确保它们指向正确的阿里云镜像：
# 编辑 scl-rh 仓库配置文件
sudo vi /etc/yum.repos.d/CentOS-SCLo-scl-rh.repo
#将文件内容修改为：
[centos-sclo-rh]
name=CentOS-7 - SCLo rh
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/rh/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
[centos-sclo-rh-source]
name=CentOS-7 - SCLo rh - Sources
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/rh/Source/
gpgcheck=1
enabled=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
  
[centos-sclo-rh-debuginfo]
name=CentOS-7 - SCLo rh - Debug
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/rh/debug/
gpgcheck=1
enabled=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
  
# 编辑 scl 仓库配置文件
sudo vi /etc/yum.repos.d/CentOS-SCLo-scl.repo
#将文件内容修改为：
[centos-sclo-sclo]
name=CentOS-7 - SCLo sclo
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/sclo/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
  
[centos-sclo-sclo-source]
name=CentOS-7 - SCLo sclo - Sources
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/sclo/Source/
gpgcheck=1
enabled=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
  
[centos-sclo-sclo-debuginfo]
name=CentOS-7 - SCLo sclo - Debug
baseurl=https://mirrors.aliyun.com/centos/7/sclo/x86_64/sclo/debug/
gpgcheck=1
enabled=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
# 更新 yum 缓存
sudo yum clean all
sudo yum makecache
安装开发工具和库
sudo yum install -y \
    gcc \
    gcc-c++ \
    make \
    cmake \
    readline-devel \
    zlib-devel \
    openssl-devel \
    libuuid-devel \
    bison \
    flex \
    git \
    libcurl-devel \
    libxml2-devel \
    libxslt-devel \
    perl-IPC-Run \
    perl-Test-Simple \
    tcl-devel \
    python-devel \
    rpm-build \
    pkgconfig \
    krb5-devel \
    openldap-devel
#安装 wget（如果尚未安装）
sudo yum install -y wget
# 下载zstd源码
cd /tmp
curl -L -o zstd-1.5.2.tar.gz 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 PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
# 安装libxml2-devel及其依赖包
sudo yum install -y libxml2-devel libxml2 cmake-filesystem xz-devel zlib-devel pkgconfig
# 验证安装
rpm -qa | grep libxml2
# 检查xml2-config命令是否可用
which xml2-config
# 检查pkg-config是否能找到libxml-2.0
pkg-config --exists libxml-2.0 && echo "libxml2 found" || echo "libxml2 NOT found"
# 查看libxml2的配置信息
xml2-config --version
xml2-config --cflags
xml2-config --libs
#升级 CMake版本至3.28.3
cd /tmp
wget https://github.com/Kitware/CMake/releases/download/v3.28.3/cmake-3.28.3.tar.gz
tar -xzf cmake-3.28.3.tar.gz
cd cmake-3.28.3
./bootstrap --prefix=/usr/local
make -j$(nproc)
sudo make install
#设置 CMAKE_ROOT 环境变量
export CMAKE_ROOT=/usr/local/share/cmake-3.28.3
echo 'export CMAKE_ROOT=/usr/local/share/cmake-3.28.3' >> ~/.bashrc
# 确保 /usr/local/bin 在 PATH 中
export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
# 应用更改
source ~/.bashrc
# 下载CLI11源码
cd /tmp
git clone https://github.com/CLIUtils/CLI11.git
cd CLI11
mkdir build 
cd build
cmake ..
make clean
make -j4
sudo make install
yum repolist

二、源码获取与编译

2.1 获取源码

# 获取源码
cd /data/opentenbase
git clone -b v5.0-release_new https://github.com/OpenTenBase/OpenTenBase.git
# 设置环境变量
export SOURCECODE_PATH=/data/opentenbase/OpenTenBase
export INSTALL_PATH=/data/opentenbase/install

2.2 编译主程序

# 进入源码目录
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
安装 UUID 开发包
sudo yum install -y uuid uuid-devel
# 配置编译 - 关键：添加 SSE4.2 支持和 DNOLIC 标志
CFLAGS="-g -O2 -w -msse4.2 -mcrc32 -DNOLIC" \
CXXFLAGS="-g -O2 -w -msse4.2 -mcrc32 -DNOLIC" \
./configure --prefix=/data/opentenbase/install/opentenbase_bin_v2.0 \
    --enable-user-switch \
    --with-openssl \
    --with-ossp-uuid \
    --with-libxml
# 编译主程序
make -j4
make install

2.3 编译扩展模块

# 设置执行权限
chmod +x contrib/pgxc_ctl/make_signaturerpm -q postgresql-devel
安装 PostgreSQL 的开发包
sudo yum install -y postgresql-devel
#启用SCL仓库
sudo yum install -y centos-release-scl
#安装较新版本的 GCC
sudo yum install -y devtoolset-9
#启用新版本的 GCC
echo 'source /opt/rh/devtoolset-9/enable' >> ~/.bashrc
source ~/.bashrc
scl enable devtoolset-9 bash
# 下载 libpqxx
cd /tmp
wget https://github.com/jtv/libpqxx/archive/6.4.7.tar.gz
tar -xzf 6.4.7.tar.gz
cd libpqxx-6.4.7
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc)
sudo make install
sudo ldconfig
# 进入 contrib 目录
cd contrib
make clean
make -j4
# 安装扩展模块
make install

四、环境配置

4.1 设置环境变量

# 编辑 ~/.bashrc
vi ~/.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关闭 SELINUX 和 配置防火墙

sudo vim /etc/sysconfig/selinux

● 临时关闭 SELinux

 ○ 使用命令getenforce查看 SELinux 当前状态，如果返回Enforcing，表明 SELinux 处于强制模式。

 ○ 执行命令setenforce 0，将 SELinux 设置为宽容模式（Permissive），即临时关闭 SELinux。此时 SELinux 会记录违反策略的行为但不会阻止它们，不过系统重新启动后 SELinux 将会恢复到之前的状态。

● 关闭 SELinux

 ○ 编辑 SELinux 配置文件/etc/selinux/config，可以使用命令vi /etc/selinux/config。

 ○ 在文件中找到SELINUX=enforcing这一行，将其改为SELINUX=disabled。

 ○ 保存文件并重启系统，命令为reboot。重启后 SELinux 就会被关闭。

配置防火墙

# 开放GTM端口
sudo firewall-cmd --permanent --add-port=6666/tcp
# 开放Coordinator端口
sudo firewall-cmd --permanent --add-port=30004/tcp
# 开放Datanode端口
sudo firewall-cmd --permanent --add-port=20008/tcp
# 重新加载防火墙规则
sudo firewall-cmd --reload

4.3配置 SSH 免密登录（opentenbase 用户下进行

su - opentenbase
ssh-keygen -t rsa # 一路回车即可
ssh-copy-id -i ~/.ssh/id_rsa.pub opentenbase@localhost # 回答yes
# 修复权限
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
chmod 600 ~/.ssh/authorized_keys
# 测试ssh登录（如果成功则不需要输入密码）
ssh localhost
# 如果ssh登录需要密码，则检查/etc/ssh/sshd_config配置：
sudo vim /etc/ssh/sshd_config
#确保以下配置未被注释（去掉前面的#号）：
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys
RSAAuthentication yes
PasswordAuthentication yes
# 重启ssh服务
sudo systemctl restart sshd
# 再次测试
ssh localhost

五、集群配置与启动

5.1单节点集群部署（推荐入门）

创建集群配置文件

# 创建配置文件
cat > /data/opentenbase/install/opentenbase_bin_v2.0/pgxc_ctl.conf << 'EOF'
#!/usr/bin/env bash
#---- OVERALL -----------------------------------------------------------------------------
pgxcOwner=opentenbase
pgxcUser=$pgxcOwner
pgxcInstallDir=/data/opentenbase/install/opentenbase_bin_v2.0
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)
coordMasterServers=(localhost)
coordMasterDirs=(/data/opentenbase/data/coord_master/cn001)
coordMaxWALsender=5
coordMaxWALSenders=(5)
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)
datanodeMasterServers=(localhost)
datanodeMasterDirs=(/data/opentenbase/data/dn_master/dn001)
datanodeMaxWalSender=5
datanodeMaxWALSenders=(5)
datanodeSlave=n
datanodeSlaveServers=(none)
datanodeSlavePorts=(20009)
datanodeSlavePoolerPorts=(20019)
datanodeSlaveForwardPorts=(20029)
datanodeSlaveDirs=(none)
datanodeArchLogDirs=(none)
datanodeExtraConfig=none
datanodeSpecificExtraConfig=(none)
datanodeSpecificExtraPgHba=(none)
walArchive=n
EOF

5.2 初始化和启动集群

# 启动集群管理工具
pgxc_ctl -c /data/opentenbase/install/opentenbase_bin_v2.0/pgxc_ctl.conf
# 在 pgxc_ctl 命令行中执行：
deploy all    # 分发二进制文件
init all      # 初始化集群

5.3 集群管理命令

# 在 pgxc_ctl 中可用的命令：
monitor all   # 监控集群状态
stop all      # 停止集群
start all     # 启动集群
clean all     # 清理集群数据

六、使用指南

6.1 连接数据库和创建节点分片

  # 连接到协调节点
psql -h 127.0.0.1 -p 30004 -d postgres -U opentenbase

OpenTenBase使用数据节点组来增加节点管理的灵活性。需要创建一个默认组来使用，因此需要提前创建。通常，所有数据节点都会被添加到默认组中：

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

6.2 创建数据库和表

-- 创建数据库（包括 library217）
CREATE DATABASE library217;
-- 连接到新数据库
\c library217
-- 创建分布式表
CREATE TABLE books (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255),
    author VARCHAR(255),
    isbn VARCHAR(20)
) DISTRIBUTE BY SHARD(id);
-- 插入测试数据
INSERT INTO books (title, author, isbn) VALUES 
('OpenTenBase Guide', 'TencentDB Team', '978-0000000001'),
('Distributed Database', 'Tech Author', '978-0000000002');
-- 查询数据
SELECT * FROM books;

八、opentenbase_ai 插件使用文档

opentenbase_ai 插件为 PostgreSQL 数据库提供了集成人工智能大语言模型能力的接口，让您能够直接在 SQL 中使用 AI 功能。该插件支持多种 AI 模型提供商（包括 OpenAI、DeepSeek、腾讯混元、阿里通义千问等），提供文本生成、翻译、情感分析、问答提取、文本摘要、嵌入向量生成以及图像分析等功能。

接下来为了方便演示，我将使用Navicat Premium 17连接数据库进行插件的演示。

8.1 使用前提

已成功安装 opentenbase_ai 扩展（可通过 SELECT * FROM pg_extension WHERE extname = 'opentenbase_ai'; 验证）

8.2 快速开始（以混元大模型为例）

配置混元大模型

1. 获取混元大模型的 API Token（腾讯SDK有SecretId 和 SecretKey，openai SDK则为"sk-...."），前往腾讯云控制台申请，参考混元大模型官方文档。

1. 添加混元大模型的模型定义到模型元数据表中。

  SELECT ai.add_completion_model(
      model_name => 'hunyuan_chat', -- 自定义模型名称
      uri => 'https://api.hunyuan.cloud.tencent.com/v1/chat/completions', -- API接口地址
      default_args => '{"model": "hunyuan-lite"}'::jsonb, -- 默认参数（指定模型版本）
      token => 'your_hunyuan_api_key', -- 替换为你的混元API密钥，推荐使用格式 'SecretId|SecretKey'
      model_provider => 'tencent' -- 模型提供商
  );	

2. 执行成功后，返回 t 表示模型定义添加成功

3. 若后续希望默认使用混元模型，可通过 SET 命令配置会话级参数，配置混元大模型为默认模型。

SET ai.completion_model = 'hunyuan_chat';

、

4. 网络连接不稳定问题（可选）

1. 延长数据库的 HTTP 请求超时时间（关键）
   默认 1001 毫秒（约 1 秒）可能不足以应对偶尔的网络延迟，将超时时间延长至 5-10 秒：

# 临时生效（当前会话）
SET http.timeout = 5000;  -- 单位：毫秒，5000 = 5秒
# 长时间生效（需修改配置文件）
# 1. 打开数据库配置文件（以 OpenTenBase 为例）
sudo vi /data/opentenbase/data/coord_master/cn001/postgresql.conf
# 2. 添加或修改以下配置
http.timeout = 5000
# 3. 重启 Coordinator 节点使配置生效
pgxc_ctl -c /data/opentenbase/install/opentenbase_bin_v2.0/pgxc_ctl.conf
pgxc_ctl (PGXC: default) > stop coord cn001
pgxc_ctl (PGXC: default) > start coord cn001

混元大模型问答

配置好默认混元大模型后就可以开始体验。

文本生成

SELECT ai.generate_text('为高校开源技术社团写一段招新宣传文案，要求：
1. 突出「零基础友好」「技术实战」「社区协作」三大亮点；
2. 包含具体活动形式（如开源项目贡献、技术分享会、代码 hackathon）；
3. 语言活泼有感染力，适合学生群体，结尾附加入方式引导。');