在 TencentOS 3 上部署 OpenTenBase：从底层原理到生产级实践的深度指南

摘要

本文基于腾讯云生态体系，从底层技术原理出发，提供一份超万字的深度实战指南，详解在 TencentOS 3（Tlinux 3）操作系统上部署 OpenTenBase 分布式数据库的完整流程。内容涵盖核心架构解析、环境标准化配置、源码编译优化、集群拓扑设计、高可用部署、性能调优、监控告警及故障自愈等生产级实践要点，辅以逐行代码注释与原理解读，旨在帮助读者构建稳定、高效、可扩展的分布式数据库集群，适用于从初学者到资深运维工程师的全阶段学习需求。

第 1 章 技术背景与核心架构深度解析

1.1 技术选型的底层逻辑

1.1.1 TencentOS 3 的技术优势

TencentOS 3 作为腾讯云自研的企业级 Linux 发行版，基于 Linux 5.4 LTS 内核深度优化，其技术优势体现在三个维度：

• 内核级优化：针对云计算场景重构进程调度算法，当系统负载超过 80% 时，数据库进程的 CPU 优先级自动提升 15%，减少上下文切换损耗；集成腾讯自研的 tcfs 分布式文件系统驱动，对数据库 IO 操作提供 20%+ 的吞吐量提升。
• 安全增强：内置 tsec 安全模块，支持基于角色的访问控制（RBAC）与实时入侵检测，可拦截针对数据库端口的异常扫描（如 5432 端口的高频连接试探）。
• 云原生适配：与腾讯云 CVM、CBS 等基础设施深度集成，支持通过 qcloud-utils 工具集实现磁盘 IO 优先级调整、网络带宽隔离等云环境专属优化。

1.1.2 OpenTenBase 的分布式架构优势

OpenTenBase 作为 PostgreSQL 生态的分布式扩展，其架构设计解决了传统单机数据库的三大瓶颈：

• 存储瓶颈：采用水平分片（Sharding）机制，单表数据可按哈希、范围或列表方式分布在多个数据节点，理论存储容量无上限。
• 计算瓶颈：协调节点（CN）将 SQL 解析为分布式执行计划，并行下发至各数据节点（DN）执行，复杂查询性能随节点数量线性提升。
• 可用性瓶颈：通过全局事务管理器（GTM）与两阶段提交（2PC）协议，在节点故障时保证事务 ACID 特性，主备切换时间控制在 30 秒内。

1.2 核心组件工作原理

1.2.1 协调节点（Coordinator, CN）

CN 是客户端的唯一入口，承担四大核心职责：

1. 连接管理：维护客户端 TCP 连接，默认支持 2000 并发连接（可通过 max_connections 调整），采用连接池机制复用会话资源。
2. SQL 解析与优化：将 SQL 语句解析为抽象语法树（AST），通过分布式优化器生成最优执行计划，例如将 WHERE id = 1 的查询直接路由至存储该分片的 DN。
3. 结果聚合：收集各 DN 的执行结果，进行排序、关联等计算后返回给客户端，聚合过程中支持中间结果缓存（通过 work_mem 控制缓存大小）。
4. 元数据管理：维护集群拓扑、表分片规则等元数据，存储在本地系统表（如 pgxc_node、pg_dist_partition），并同步至所有 CN 节点。

1.2.2 数据节点（Datanode, DN）

DN 是实际存储数据的节点，其核心特性包括：

• 分片存储：每个 DN 存储表的部分分片，分片映射关系记录在 CN 的元数据中，支持动态重平衡（通过 rebalance_table_shards 函数）。
• 主备复制：采用 PostgreSQL 流复制技术，主节点（Primary）的 WAL（Write-Ahead Log）实时同步至备节点（Standby），备节点处于只读状态，支持毫秒级延迟。
• 本地事务：处理 CN 下发的子查询，维护本地事务一致性，参与全局事务的 2PC 提交过程（Prepare → Commit/Rollback）。

1.2.3 全局事务管理器（GTM）

GTM 是保证分布式事务一致性的核心组件，其工作机制如下：

• 全局事务 ID（XID）分配：为每个分布式事务分配唯一 XID，确保事务顺序性，XID 采用 64 位整数，支持 18 亿以上事务无重复。
• 全局快照管理：生成全局一致性快照，确保跨节点查询能看到相同版本的数据，快照有效期通过 gtm_snapshot_timeout 控制（默认 30 秒）。
• 故障恢复：主 GTM 故障时，备节点通过日志重演（Replay）恢复 XID 分配状态，确保事务连续性。

1.3 分布式事务实现机制

OpenTenBase 采用改进版 2PC 协议保证分布式事务 ACID 特性，流程如下：

1. 准备阶段（Prepare）：
   • CN 向所有参与事务的 DN 发送 Prepare 请求。
   • 各 DN 执行事务至本地提交点，记录 WAL 并锁定资源，返回 “准备就绪” 或 “失败” 响应。
2. 提交阶段（Commit）：
   • 若所有 DN 均返回就绪，CN 向 GTM 申请全局提交，并广播 Commit 命令。
   • 各 DN 收到命令后完成本地提交，释放资源，更新事务状态。
3. 异常处理：
   • 若任一 DN 准备失败，CN 广播 Rollback 命令，所有节点回滚事务。
   • 若 Commit 阶段网络中断，DN 重启后会向 CN 查询事务状态，避免数据不一致。

第 2 章 环境准备与标准化配置

2.1 硬件与系统规格

2.1.1 推荐硬件配置

根据集群角色差异，硬件配置需差异化设计：

• CN 节点：4 核 8GB 起步，推荐 8 核 16GB（高并发场景），CPU 选用 Intel Xeon Gold 或 AMD EPYC（支持 AVX2 指令集加速 SQL 计算）。
• DN 节点：8 核 16GB 起步，推荐 16 核 32GB，磁盘采用 NVMe SSD（随机 IOPS 需 1 万以上，支持 TRIM 指令）。
• GTM 节点：2 核 4GB 起步，推荐 4 核 8GB，网络需低延迟（集群内节点间 ping 值 < 1ms）。

2.1.2 系统环境检查

部署前需验证系统版本与架构：

# 检查操作系统版本（需 TencentOS 3.1+）
cat /etc/tencentos-release
# 输出示例：TencentOS Server 3.1 (Final)# 验证架构（需 x86_64）
uname -m
# 输出：x86_64# 检查内核版本（需 5.4+）
uname -r
# 输出示例：5.4.119-19-0009.12

2.2 基础环境标准化配置

2.2.1 主机名与 DNS 配置

主机名需体现节点角色，便于运维管理：

# 设置主机名（master 节点）
sudo hostnamectl set-hostname otb-cn-gtm-01
# dn1 节点
sudo hostnamectl set-hostname otb-dn-01
# dn2 节点
sudo hostnamectl set-hostname otb-dn-02# 配置 /etc/hosts（所有节点）
cat << EOF | sudo tee -a /etc/hosts
192.168.1.10 otb-cn-gtm-01  # CN + GTM 主节点
192.168.1.11 otb-dn-01      # DN1 主节点
192.168.1.12 otb-dn-02      # DN2 主节点
EOF# 验证主机解析
ping -c 3 otb-dn-01  # 确保无丢包

2.2.2 安全策略配置

生产环境需精细化配置防火墙，而非直接关闭：

# 启动 firewalld 并设置开机自启
sudo systemctl start firewalld
sudo systemctl enable firewalld# 开放必要端口（所有节点）
# CN 端口：5432（客户端连接）
# DN 端口：15432（数据节点通信）
# GTM 端口：6666（全局事务管理）
# SSH 端口：22（运维管理）
sudo firewall-cmd --permanent --add-port=5432/tcp
sudo firewall-cmd --permanent --add-port=15432/tcp
sudo firewall-cmd --permanent --add-port=6666/tcp
sudo firewall-cmd --permanent --add-port=22/tcp# 重新加载规则
sudo firewall-cmd --reload# 验证端口开放状态
sudo firewall-cmd --list-ports

2.2.3 SELinux 配置

SELinux 需设置为 permissive 模式（记录日志但不阻止操作）：

# 临时设置为 permissive 模式
sudo setenforce 0# 永久生效（重启后保持）
sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config# 验证状态
getenforce  # 输出：Permissive

2.3 系统资源优化配置

2.3.1 内核参数深度调优

编辑 /etc/sysctl.conf，针对数据库 workload 优化：

sudo vim /etc/sysctl.conf

添加以下参数（附详细解读）：

# 共享内存配置（关键参数）
# shmmax：最大共享内存段大小，建议为物理内存的 75%
kernel.shmmax = 16106127360  # 16GB 内存节点设置为 12GB（12*1024^3）
# shmall：系统总共享内存页数（每页 4KB），需 ≥ shmmax/4KB
kernel.shmall = 3932160      # 16GB/4KB = 4,194,304，此处设为 3.8GB# 信号量配置（数据库进程间通信）
# SEMMSL: 每个信号量集的最大信号量数
# SEMMNS: 系统总信号量数
# SEMOPM: 每个 semop 调用的最大操作数
# SEMMNI: 系统信号量集总数
kernel.sem = 250 32000 100 128# 文件描述符限制（数据库会打开大量文件句柄）
fs.file-max = 1048576  # 系统级最大文件数
fs.aio-max-nr = 1048576  # 异步 IO 事件上限# 网络优化（减少连接延迟与丢包）
net.ipv4.ip_local_port_range = 1024 65535  # 可用端口范围
net.core.somaxconn = 4096  # 监听队列长度（默认 128 过小）
net.ipv4.tcp_max_syn_backlog = 4096  # SYN 队列长度
net.ipv4.tcp_slow_start_after_idle = 0  # 禁用空闲后的慢启动
net.ipv4.tcp_tw_reuse = 1  # 允许 TIME_WAIT 端口复用
net.ipv4.tcp_fin_timeout = 15  # 缩短 FIN_WAIT2 超时（默认 60s）# 内存管理（减少 swap 使用率）
vm.overcommit_memory = 1  # 允许内存过量分配（数据库常见配置）
vm.swappiness = 10  # 仅当内存使用率 >90% 时使用 swap
vm.dirty_ratio = 40  # 脏页占总内存 40% 时触发刷盘
vm.dirty_background_ratio = 10  # 后台刷盘阈值

使配置生效：

sudo sysctl -p  # 立即生效

2.3.2 用户资源限制配置

编辑 /etc/security/limits.conf，提升 opentenbase 用户资源配额：

sudo vim /etc/security/limits.conf

添加以下配置：

# 进程数限制（软限制/硬限制）
opentenbase    soft    nproc       65536
opentenbase    hard    nproc       65536
# 文件句柄限制
opentenbase    soft    nofile      65536
opentenbase    hard    nofile      65536
# 内存锁定限制（禁止内存交换至磁盘）
opentenbase    soft    memlock     unlimited
opentenbase    hard    memlock     unlimited
# 栈空间限制
opentenbase    soft    stack       8192
opentenbase    hard    stack       8192

注意：需重新登录 opentenbase 用户使配置生效，验证方法：

su - opentenbase  # 重新登录
ulimit -n  # 应输出 65536
ulimit -u  # 应输出 65536

2.4 磁盘与文件系统配置

2.4.1 数据盘挂载（生产环境必备）

数据库数据建议存储在独立数据盘，采用 xfs 文件系统（支持大文件与高并发）：

# 查看磁盘列表（假设数据盘为 /dev/vdb）
lsblk# 分区（MBR 分区表）
sudo parted /dev/vdb mklabel msdos
sudo parted /dev/vdb mkpart primary xfs 0% 100%# 格式化（xfs 文件系统，启用 CRC 校验）
sudo mkfs.xfs -m crc=1 /dev/vdb1# 创建挂载点
sudo mkdir -p /data/opentenbase
sudo chown opentenbase:opentenbase /data/opentenbase# 配置自动挂载（/etc/fstab）
sudo echo "/dev/vdb1 /data/opentenbase xfs defaults,noatime,nodiratime 0 0" >> /etc/fstab# 挂载并验证
sudo mount -a
df -h /data/opentenbase  # 确认挂载成功

参数解读：

• noatime：禁用文件访问时间更新（减少 IO 操作）。
• nodiratime：禁用目录访问时间更新。

第 3 章 依赖安装与源码编译优化

3.1 开发工具与依赖库安装

3.1.1 基础工具集安装

# 更新系统包索引
sudo yum update -y# 安装编译工具链
sudo yum groupinstall -y "Development Tools"# 安装基础依赖（所有节点）
sudo yum install -y \wget curl vim git net-tools telnet \readline-devel zlib-devel openssl11-devel \pam-devel libxml2-devel libxslt-devel \tcl-devel gcc-c++ flex bison perl-ExtUtils-Embed \openldap-devel libevent-devel python3-devel

依赖作用说明：

• readline-devel：提供命令行编辑与历史记录功能（psql 客户端依赖）。
• openssl11-devel：支持 SSL 加密连接（生产环境必备）。
• libxml2-devel/libxslt-devel：支持 XML 数据类型与 XSLT 转换。
• flex/bison：语法分析器生成工具（编译 SQL 解析器需要）。

3.1.2 特殊依赖处理（TencentOS 专属）

TencentOS 3 需手动安装 libzstd-devel（ZSTD 压缩库）：

# 从 EPEL 源安装
sudo yum install -y epel-release
sudo yum install -y libzstd-devel

3.2 源码获取与版本选择

3.2.1 克隆源码仓库

# 切换至 opentenbase 用户
su - opentenbase# 创建工作目录
mkdir -p ~/src && cd ~/src# 克隆官方仓库（国内可使用 Gitee 镜像加速）
git clone https://github.com/tencent-opentenbase/OpenTenBase.git
# 国内加速：git clone https://gitee.com/opentenbase/OpenTenBase.gitcd OpenTenBase# 查看稳定版本标签（选择最新 LTS 版本）
git tag | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V# 检出指定版本（以 v2.5.0 为例）
git checkout v2.5.0

3.2.2 源码目录结构解析

# 查看核心目录
ls -l

关键目录说明：

• src/backend：数据库核心模块（事务、存储、执行器等）。
• src/gtm：全局事务管理器源码。
• src/xc：分布式相关代码（CN/DN 通信、分片管理等）。
• contrib：扩展模块（如 pg_stat_statements 性能分析工具）。

3.3 编译参数优化与执行

3.3.1 配置编译选项

创建独立编译目录（避免污染源码）：

# 创建编译目录
mkdir -p ~/build/opentenbase && cd ~/build/opentenbase# 运行 configure 配置（精细化参数）
~/src/OpenTenBase/configure \--prefix=/home/opentenbase/opentenbase \  # 安装目录--exec-prefix=/home/opentenbase/opentenbase \--bindir=/home/opentenbase/opentenbase/bin \--libdir=/home/opentenbase/opentenbase/lib \--sysconfdir=/home/opentenbase/opentenbase/etc \--with-openssl \  # 启用 SSL 支持--with-pam \      # 支持 PAM 认证--with-ldap \     # 支持 LDAP 认证--with-libxml \   # 支持 XML 函数--with-libxslt \  # 支持 XSLT 转换--with-zstd \     # 启用 ZSTD 压缩--enable-thread-safety \  # 线程安全支持--enable-cassert \  # 开发调试（生产环境可关闭）--enable-debug \    # 生成调试符号（生产环境可关闭）CFLAGS='-O3 -march=native -mtune=native' \  # 编译器优化CXXFLAGS='-O3 -march=native -mtune=native'

参数优化说明：

• -O3：最高级别优化（比默认 -O2 多循环展开、函数内联等优化）。
• -march=native：针对当前 CPU 架构生成最优指令（如 AVX2、SSE4.2）。
• --with-zstd：启用 ZSTD 压缩（比默认 ZLIB 压缩率更高，速度更快）。

3.3.2 并行编译与安装

# 查看 CPU 核心数（确定并行任务数）
nproc  # 输出示例：8# 并行编译（-j 后接核心数，建议不超过核心数的 1.5 倍）
make -j 12  # 8 核 CPU 用 12 个任务加速编译# 安装（无错误则继续）
make install

编译时间参考：8 核 16GB 服务器约 15-20 分钟，4 核 8GB 约 30-40 分钟。

3.3.3 二进制文件分发

将编译结果分发至其他节点（避免重复编译）：

# 在 master 节点打包
cd ~
tar -czf opentenbase-bin.tar.gz opentenbase/# 分发至 dn1 节点
scp opentenbase-bin.tar.gz opentenbase@otb-dn-01:~/# 分发至 dn2 节点
scp opentenbase-bin.tar.gz opentenbase@otb-dn-02:~/# 在 dn1/dn2 节点解压
# 登录 dn1 节点
ssh opentenbase@otb-dn-01
tar -xzf opentenbase-bin.tar.gz
exit# 登录 dn2 节点执行相同解压操作

3.4 环境变量配置与验证

3.4.1 配置环境变量

编辑 ~/.bashrc 持久化环境变量：

vim ~/.bashrc

添加以下内容：

# OpenTenBase 环境变量
export OPENTENBASE_HOME=/home/opentenbase/opentenbase
export PATH=$OPENTENBASE_HOME/bin:$PATH
export LD_LIBRARY_PATH=$OPENTENBASE_HOME/lib:$LD_LIBRARY_PATH
export MANPATH=$OPENTENBASE_HOME/share/man:$MANPATH
# 默认数据目录（可被具体命令覆盖）
export PGDATA=/data/opentenbase/data

使配置生效：

source ~/.bashrc

3.4.2 验证安装结果

# 检查版本
initdb --version
# 输出示例：initdb (OpenTenBase) 13.9 (v2.5.0)# 检查依赖库
ldd $OPENTENBASE_HOME/bin/postgres | grep -i ssl
# 输出应包含 libssl.so.1.1（确认 SSL 支持生效）

第 4 章 集群拓扑设计与配置

4.1 集群架构规划

4.1.1 节点角色分配

本文采用 “1+2” 最小集群架构（生产环境建议 3+3 架构）：

节点 hostname	IP 地址	角色	端口	数据目录
otb-cn-gtm-01	192.168.1.10	CN（主）、GTM（主）	5432	/data/opentenbase/cn
			6666	/data/opentenbase/gtm
otb-dn-01	192.168.1.11	DN1（主）、DN2（备）	15432	/data/opentenbase/dn1
			15433	/data/opentenbase/dn2_standby
otb-dn-02	192.168.1.12	DN2（主）、DN1（备）	15432	/data/opentenbase/dn2
			15433	/data/opentenbase/dn1_standby

4.1.2 目录结构标准化

所有节点创建统一目录结构：

# 切换至 opentenbase 用户
su - opentenbase# 创建核心目录（所有节点执行）
mkdir -p \/data/opentenbase/{cn,gtm,dn1,dn2,dn1_standby,dn2_standby} \/data/opentenbase/logs/{cn,gtm,dn1,dn2,dn1_standby,dn2_standby} \/data/opentenbase/backup \/data/opentenbase/tmp# 设置目录权限（确保属主正确）
chmod -R 700 /data/opentenbase

4.2 GTM 节点配置

4.2.1 初始化 GTM 数据目录

# 在 otb-cn-gtm-01 节点执行
initdb -D /data/opentenbase/gtm \--nodename=gtm_master \--username=opentenbase \--auth-local=trust \  # 本地信任认证--auth-host=md5       # 远程 MD5 认证

参数说明：

• --nodename：GTM 节点名称（集群内唯一）。
• --username：超级用户名称（默认 postgres，此处统一为 opentenbase）。

4.2.2 配置 gtm.conf

编辑 GTM 核心配置文件：

vim /data/opentenbase/gtm/gtm.conf

关键配置（完整配置需保留默认值，仅修改以下项）：

# 监听地址（* 表示所有网卡）
listen_addresses = '*'# 端口（默认 6666，需与防火墙开放端口一致）
port = 6666# 日志文件路径
log_file = '/data/opentenbase/logs/gtm/gtm.log'# 日志级别（生产环境用 WARNING，调试用 LOG）
log_min_messages = WARNING# 节点名称（与初始化时一致）
node_name = 'gtm_master'# 启动模式（ACTIVE 表示主节点）
startup = ACTIVE# 最大连接数（CN + DN 总数的 2 倍）
max_connections = 100# 全局事务 ID 起始值（默认即可）
xid_start_value = 10000# 快照超时时间（秒）
snapshot_timeout = 30

4.3 数据节点（DN）配置

4.3.1 初始化 DN1 主节点（otb-dn-01）

# 在 otb-dn-01 节点执行
initdb -D /data/opentenbase/dn1 \--nodename=dn1_primary \--username=opentenbase \--auth-local=trust \--auth-host=md5 \--encoding=UTF8 \  # 字符集--lc-collate=en_US.UTF-8 \--lc-ctype=en_US.UTF-8

4.3.2 配置 DN1 主节点 postgresql.conf

vim /data/opentenbase/dn1/postgresql.conf

核心配置（按 16GB 内存节点优化）：

# 基础配置
listen_addresses = '*'
port = 15432
db_name = 'postgres'
node_name = 'dn1_primary'# 日志配置
log_destination = 'csvlog'  # 结构化日志（便于分析）
logging_collector = on
log_directory = '/data/opentenbase/logs/dn1'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
log_rotation_age = 1d       # 每日轮转
log_rotation_size = 100MB   # 100MB 轮转
log_min_messages = WARNING
log_min_error_statement = ERROR
log_checkpoints = on        # 记录检查点信息
log_connections = on        # 记录连接信息
log_disconnections = on# 资源限制
max_connections = 500       # 最大连接数
shared_buffers = 4GB        # 共享缓冲区（内存的 25%）
work_mem = 64MB             # 排序/哈希操作内存（按并发数调整）
maintenance_work_mem = 1GB  # 维护操作内存（如 VACUUM）
effective_cache_size = 12GB # 估计缓存大小（优化器用）# 存储配置
data_directory = '/data/opentenbase/dn1'
max_wal_size = 10GB         # WAL 最大容量
min_wal_size = 1GB          # WAL 最小容量
wal_buffers = 16MB          # WAL 缓冲区
checkpoint_completion_target = 0.9  # 检查点完成目标比例
archive_mode = on           # 启用 WAL 归档（主备复制基础）
archive_command = 'test ! -f /data/opentenbase/backup/wal_archive/%f && cp %p /data/opentenbase/backup/wal_archive/%f'  # 归档命令# 复制配置
wal_level = replica         # 复制级别（支持流复制）
max_wal_senders = 10        # 最大 WAL 发送进程数
wal_keep_size = 1GB         # 保留的 WAL 大小（避免备库跟不上）
hot_standby = on            # 备库支持只读查询

4.3.3 配置 DN1 主节点 pg_hba.conf

vim /data/opentenbase/dn1/pg_hba.conf

添加以下规则（控制访问权限）：

# 允许本地连接（信任）
local   all             all                                     trust# 允许 GTM 节点连接（信任）
host    all             all             192.168.1.10/32         trust# 允许 CN 节点连接（信任）
host    all             all             192.168.1.10/32         trust# 允许其他 DN 节点连接（复制权限）
host    replication     all             192.168.1.12/32         md5# 允许管理机连接（密码认证）
host    all             opentenbase     192.168.1.0/24          md5

4.3.4 初始化 DN1 备节点（otb-dn-02）

备节点通过主节点基础备份初始化：

# 在 otb-dn-02 节点创建归档目录（主节点已创建）
mkdir -p /data/opentenbase/backup/wal_archive# 从 DN1 主节点（otb-dn-01）拉取基础备份
pg_basebackup -h otb-dn-01 -p 15432 -U opentenbase \-D /data/opentenbase/dn1_standby \-F p -X stream -P \--slot=dn1_standby_slot  # 复制槽（避免 WAL 被清理）

参数说明：

• -X stream：流式传输 WAL 文件（确保备份一致性）。
• -P：显示进度条。
• --slot：创建复制槽（防止主节点删除备节点未接收的 WAL）。

4.3.5 配置 DN1 备节点 recovery.conf

备节点需创建恢复配置文件：

vim /data/opentenbase/dn1_standby/recovery.conf

添加以下内容：

standby_mode = on  # 启用备库模式# 主库连接信息
primary_conninfo = 'host=otb-dn-01 port=15432 user=opentenbase password=YourSecurePassword123! application_name=dn1_standby'# 恢复结束后是否提升为只读（备库保持 on）
promote_trigger_file = '/data/opentenbase/dn1_standby/promote.trigger'# WAL 归档恢复命令
restore_command = 'cp /data/opentenbase/backup/wal_archive/%f %p'# 复制槽名称（与主库一致）
primary_slot_name = 'dn1_standby_slot'

注意：需在 DN1 主节点创建复制槽：

# 在 DN1 主节点执行（连接至 dn1 实例）
psql -h 127.0.0.1 -p 15432 -U opentenbase postgres# 创建复制槽
SELECT * FROM pg_create_physical_replication_slot('dn1_standby_slot');
\q

4.3.6 DN2 主备节点配置

参照 DN1 配置流程，在 otb-dn-02 节点初始化 DN2 主节点（端口 15432），在 otb-dn-01 节点初始化 DN2 备节点（端口 15433），核心配置保持一致，仅修改节点名称、端口与目录路径。

4.4 协调节点（CN）配置

4.4.1 初始化 CN 节点

# 在 otb-cn-gtm-01 节点执行
initdb -D /data/opentenbase/cn \--nodename=cn_master \--username=opentenbase \--auth-local=trust \--auth-host=md5 \--encoding=UTF8

4.4.2 配置 CN 节点 postgresql.conf

vim /data/opentenbase/cn/postgresql.conf

核心配置（CN 侧重连接与调度优化）：

# 基础配置
listen_addresses = '*'
port = 5432  # 客户端默认端口
node_name = 'cn_master'# 日志配置（同 DN，略）# 资源限制（CN 需更多连接）
max_connections = 2000  # 支持高并发客户端
shared_buffers = 2GB    # CN 计算为主，共享缓冲区可较小
work_mem = 32MB         # 多个并发查询共享，需控制单查询内存
maintenance_work_mem = 512MB
effective_cache_size = 8GB# GTM 配置（关键）
gtm_host = 'otb-cn-gtm-01'  # GTM 节点地址
gtm_port = 6666             # GTM 端口# 分布式优化参数
max_parallel_workers_per_gather = 4  # 并行查询 worker 数
parallel_setup_cost = 1000.0         # 并行设置成本
parallel_tuple_cost = 0.1            # 并行元组成本

4.4.3 配置 CN 节点 pg_hba.conf

vim /data/opentenbase/cn/pg_hba.conf

允许客户端与节点间通信：

# 允许本地连接
local   all             all                                     trust# 允许所有节点间通信（信任）
host    all             all             192.168.1.0/24          trust# 允许外部客户端连接（密码认证）
host    all             all             0.0.0.0/0               md5

4.5 集群节点注册

4.5.1 启动各节点服务

按顺序启动服务（GTM → DN → CN）：

# 启动 GTM（otb-cn-gtm-01）
gtm -D /data/opentenbase/gtm > /data/opentenbase/logs/gtm/startup.log 2>&1 &# 启动 DN1 主节点（otb-dn-01）
pg_ctl -D /data/opentenbase/dn1 -l /data/opentenbase/logs/dn1/startup.log start# 启动 DN1 备节点（otb-dn-02）
pg_ctl -D /data/opentenbase/dn1_standby -l /data/opentenbase/logs/dn1_standby/startup.log start# 启动 DN2 主节点（otb-dn-02）
pg_ctl -D /data/opentenbase/dn2 -l /data/opentenbase/logs/dn2/startup.log start# 启动 DN2 备节点（otb-dn-01）
pg_ctl -D /data/opentenbase/dn2_standby -l /data/opentenbase/logs/dn2_standby/startup.log start# 启动 CN 节点（otb-cn-gtm-01）
pg_ctl -D /data/opentenbase/cn -l /data/opentenbase/logs/cn/startup.log start

4.5.2 注册节点到集群

连接 CN 执行 SQL 注册节点：

# 连接 CN 节点
psql -h 127.0.0.1 -p 5432 -U opentenbase postgres

执行注册命令：

-- 1. 注册 GTM 节点
CREATE NODE gtm_master WITH (TYPE = 'gtm',HOST = 'otb-cn-gtm-01',PORT = 6666
);-- 2. 注册 DN1 主备节点
CREATE NODE dn1_primary WITH (TYPE = 'datanode',HOST = 'otb-dn-01',PORT = 15432
);
CREATE NODE dn1_standby WITH (TYPE = 'datanode',HOST = 'otb-dn-02',PORT = 15433
);-- 3. 注册 DN2 主备节点
CREATE NODE dn2_primary WITH (TYPE = 'datanode',HOST = 'otb-dn-02',PORT = 15432
);
CREATE NODE dn2_standby WITH (TYPE = 'datanode',HOST = 'otb-dn-01',PORT = 15433
);-- 4. 创建节点组（主备成对）
CREATE NODE GROUP group1 WITH (dn1_primary, dn1_standby);
CREATE NODE GROUP group2 WITH (dn2_primary, dn2_standby);-- 5. 初始化工作节点
EXECUTE DIRECT ON (dn1_primary) 'SELECT INIT_WORKER_NODES()';
EXECUTE DIRECT ON (dn2_primary) 'SELECT INIT_WORKER_NODES()';-- 6. 刷新配置
SELECT * FROM PGXC_NODE_RELOAD_CONF();-- 验证节点状态
SELECT node_name, node_type, node_port, node_host, node_status FROM pgxc_node;

预期结果：所有节点 node_status 为 u（up）。

第 5 章 集群验证与功能测试

5.1 集群状态检查工具

5.1.1 节点状态监控

使用 pgxc_ctl 工具（OpenTenBase 自带）检查集群状态：

# 启动 pgxc_ctl 交互模式
pgxc_ctl

在交互界面执行：

# 查看所有节点状态
show all# 检查 GTM 状态
gtm status# 检查 DN 状态
datanode status# 检查 CN 状态
coordinator status

5.1.2 日志验证

检查各节点日志确认启动正常：

# 检查 GTM 日志
tail -n 20 /data/opentenbase/logs/gtm/gtm.log# 检查 CN 日志
tail -n 20 /data/opentenbase/logs/cn/postgresql-*.log# 检查 DN1 主节点日志
ssh opentenbase@otb-dn-01 "tail -n 20 /data/opentenbase/logs/dn1/postgresql-*.log"

正常启动标志：日志中无 FATAL 或 PANIC 级别错误，最后一行显示 database system is ready to accept connections。

5.2 分布式功能测试

5.2.1 分布式表创建与数据分布

-- 连接 CN 创建测试库
CREATE DATABASE testdb;
\c testdb-- 创建哈希分片表（按 id 字段分片）
CREATE TABLE dist_hash (id INT PRIMARY KEY,name VARCHAR(50),create_time TIMESTAMPTZ DEFAULT NOW()
) DISTRIBUTE BY HASH(id);-- 插入测试数据（10 万行）
INSERT INTO dist_hash (id, name)
SELECT generate_series(1, 100000), 'test_' || generate_series(1, 100000);-- 查看数据分布情况（通过执行计划）
EXPLAIN (VERBOSE, COSTS OFF) SELECT * FROM dist_hash;

预期结果：执行计划显示数据分布在 dn1_primary 和 dn2_primary 两个节点，比例接近 1:1（哈希分片特性）。

5.2.2 分布式事务测试

-- 开启分布式事务
BEGIN;-- 跨节点更新（假设 id=1 在 dn1，id=100000 在 dn2）
UPDATE dist_hash SET name = 'tx_test_1' WHERE id = 1;
UPDATE dist_hash SET name = 'tx_test_100000' WHERE id = 100000;-- 查看未提交的更改（仅当前事务可见）
SELECT name FROM dist_hash WHERE id IN (1, 100000);-- 提交事务
COMMIT;-- 验证更改（所有节点可见）
SELECT name FROM dist_hash WHERE id IN (1, 100000);

5.2.3 主备切换测试

手动触发 DN1 主备切换：

# 在 DN1 备节点（otb-dn-02）创建触发文件
ssh opentenbase@otb-dn-02 "touch /data/opentenbase/dn1_standby/promote.trigger"# 查看 DN1 备节点日志（确认切换）
ssh opentenbase@otb-dn-02 "tail -n 50 /data/opentenbase/logs/dn1_standby/postgresql-*.log"

切换成功标志：日志中出现 promoted to primary 信息，CN 中查询 pgxc_node 显示 dn1_standby 状态为 u，dn1_primary 状态为 d（down）。

5.3 性能基准测试

使用 pgbench 进行简单性能测试：

# 在 CN 节点初始化测试数据
pgbench -h 127.0.0.1 -p 5432 -U opentenbase -i -s 10 testdb  # 10 倍默认数据量# 运行测试（16 客户端，60 秒）
pgbench -h 127.0.0.1 -p 5432 -U opentenbase -c 16 -T 60 testdb

结果解读：关注 tps（每秒事务数）和 latency（平均延迟），16GB 内存节点集群 tps 应在 1000 以上。

第 6 章 生产级运维实践

6.1 自动化启停脚本

创建 clusterctl.sh 统一管理集群：

#!/bin/bash
# 集群管理脚本（放置在 otb-cn-gtm-01 节点 ~/bin 目录）# 节点信息
CN_HOST="otb-cn-gtm-01"
DN1_HOST="otb-dn-01"
DN2_HOST="otb-dn-02"start() {echo "=== 启动 GTM ==="ssh $CN_HOST "gtm -D /data/opentenbase/gtm > /data/opentenbase/logs/gtm/startup.log 2>&1 &"sleep 2echo "=== 启动 DN1 主节点 ==="ssh $DN1_HOST "pg_ctl -D /data/opentenbase/dn1 -l /data/opentenbase/logs/dn1/startup.log start"echo "=== 启动 DN2 备节点（在 DN1 主机） ==="ssh $DN1_HOST "pg_ctl -D /data/opentenbase/dn2_standby -l /data/opentenbase/logs/dn2_standby/startup.log start"sleep 2echo "=== 启动 DN2 主节点 ==="ssh $DN2_HOST "pg_ctl -D /data/opentenbase/dn2 -l /data/opentenbase/logs/dn2/startup.log start"echo "=== 启动 DN1 备节点（在 DN2 主机） ==="ssh $DN2_HOST "pg_ctl -D /data/opentenbase/dn1_standby -l /data/opentenbase/logs/dn1_standby/startup.log start"sleep 2echo "=== 启动 CN 节点 ==="ssh $CN_HOST "pg_ctl -D /data/opentenbase/cn -l /data/opentenbase/logs/cn/startup.log start"sleep 2echo "=== 集群启动完成 ==="ssh $CN_HOST "pgxc_ctl -c 'show all'"
}stop() {echo "=== 停止 CN 节点 ==="ssh $CN_HOST "pg_ctl -D /data/opentenbase/cn stop -m fast"echo "=== 停止 DN1 主节点 ==="ssh $DN1_HOST "pg_ctl -D /data/opentenbase/dn1 stop -m fast"echo "=== 停止 DN2 备节点（在 DN1 主机） ==="ssh $DN1_HOST "pg_ctl -D /data/opentenbase/dn2_standby stop -m fast"echo "=== 停止 DN2 主节点 ==="ssh $DN2_HOST "pg_ctl -D /data/opentenbase/dn2 stop -m fast"echo "=== 停止 DN1 备节点（在 DN2 主机） ==="ssh $DN2_HOST "pg_ctl -D /data/opentenbase/dn1_standby stop -m fast"echo "=== 停止 GTM ==="ssh $CN_HOST "pkill -f 'gtm -D /data/opentenbase/gtm'"echo "=== 集群停止完成 ==="
}status() {echo "=== 集群状态 ==="ssh $CN_HOST "pgxc_ctl -c 'show all'"
}case "$1" instart)start;;stop)stop;;status)status;;restart)stopsleep 5start;;*)echo "Usage: $0 {start|stop|status|restart}"exit 1;;
esac

赋予执行权限并使用：

chmod +x ~/bin/clusterctl.sh
~/bin/clusterctl.sh start  # 启动集群

6.2 备份与恢复策略

6.2.1 逻辑备份（通过 CN）

# 全库备份（自定义格式，支持并行）
pg_dump -h otb-cn-gtm-01 -p 5432 -U opentenbase \-F c -b -v -f /data/opentenbase/backup/testdb_full_$(date +%Y%m%d).dump \testdb# 单表备份
pg_dump -h otb-cn-gtm-01 -p 5432 -U opentenbase \-F c -t dist_hash -f /data/opentenbase/backup/dist_hash_$(date +%Y%m%d).dump \testdb

6.2.2 物理备份（各 DN 独立）

# 备份 DN1 主节点（使用 pg_basebackup）
pg_basebackup -h otb-dn-01 -p 15432 -U opentenbase \-D /data/opentenbase/backup/dn1_$(date +%Y%m%d) \-F p -X stream -P

6.2.3 恢复测试

# 恢复全库
pg_restore -h otb-cn-gtm-01 -p 5432 -U opentenbase \-C -d postgres /data/opentenbase/backup/testdb_full_20240501.dump

6.3 监控告警配置

6.3.1 集成 Prometheus 与 Grafana

1. 安装 postgres_exporter：

# 下载 exporter
wget https://github.com/prometheus-community/postgres_exporter/releases/download/v0.15.0/postgres_exporter-0.15.0.linux-amd64.tar.gz
tar -xzf postgres_exporter-0.15.0.linux-amd64.tar.gz
cd postgres_exporter-0.15.0.linux-amd64# 创建连接配置
cat << EOF > pg_exporter.yml
data_source_name: "postgresql://opentenbase:YourSecurePassword123!@otb-cn-gtm-01:5432/testdb?sslmode=disable"
EOF# 启动 exporter（后台运行）
nohup ./postgres_exporter --config.file=pg_exporter.yml --web.listen-address=":9187" &

1. 配置 Prometheus 抓取规则：

# prometheus.yml 中添加
scrape_configs:- job_name: 'opentenbase'static_configs:- targets: ['otb-cn-gtm-01:9187', 'otb-dn-01:9187', 'otb-dn-02:9187']

1. 导入 Grafana 仪表盘：使用 PostgreSQL 官方仪表盘（ID: 9628），监控关键指标如连接数、锁等待、WAL 生成速率等。

6.4 常见故障处理

6.4.1 节点无法启动

• 检查端口占用：netstat -tulpn | grep 5432（替换为对应端口），杀死占用进程。
• 权限问题：确保数据目录属主为 opentenbase：ls -ld /data/opentenbase/cn。
• 日志定位：查看节点日志中的 FATAL 错误，例如 could not create lock file 通常是权限问题。

6.4.2 主备复制中断

• 检查复制槽状态：

-- 在主节点执行
SELECT slot_name, active, restart_lsn FROM pg_replication_slots;

• 重新创建复制槽：若 active 为 f，删除并重新创建复制槽。
• 同步 WAL 归档：若备节点缺失 WAL，从主节点归档目录复制后重启备库。

第 7 章 总结与进阶方向

本文详细讲解了在 TencentOS 3 上部署 OpenTenBase 集群的全流程，从环境准备、源码编译到集群配置、功能验证，覆盖了从基础到生产级的关键要点。通过本文的实践，读者可掌握分布式数据库的核心原理与运维技巧。

进阶探索方向

1. 高可用架构升级：部署 GTM 备节点与多个 CN 节点，结合 Keepalived 实现自动故障切换。
2. 性能深度调优：根据业务场景优化 postgresql.conf 参数，如调整 shared_buffers 与系统缓存的比例、优化 WAL 写入策略等。
3. 安全加固：配置 SSL 加密连接、启用审计日志、定期更换密码、限制 pg_hba.conf 访问规则。
4. 弹性扩展：学习如何在线添加 DN 节点并重新分片数据，实现集群容量动态扩展。

引用出处

1. TencentOS 官方文档：https://cloud.tencent.com/document/product/213/38008
2. OpenTenBase GitHub 仓库：https://github.com/tencent-opentenbase/OpenTenBase
3. OpenTenBase 官方文档：https://opentenbase.github.io/
4. PostgreSQL 官方文档：https://www.postgresql.org/docs/13/index.html
5. Linux 内核参数调优指南：https://www.kernel.org/doc/Documentation/sysctl/