openGauss分布式与openLooKeng一键部署宝典
本文将结合 代码示例、ASCII 图解 和 详细说明，手把手教你如何在 Linux 环境下快速部署 openGauss 分布式集群 以及 openLooKeng，帮助你快速上手并理解原理。全程采用“一键部署”思路，减少重复操作，降低学习成本。
目录
- 概述
- 环境与前置准备
- openGauss 分布式集群部署
3.1. 架构概览
3.2. 安装依赖与用户准备
3.3. 安装 openGauss 软件包
3.4. 配置主节点（Primary）
3.5. 配置备节点（Standby）
3.6. 启动集群并验证
3.7. 常见故障排查 - openLooKeng 一键部署
4.1. 架构概览
4.2. 下载与环境准备
4.3. 修改配置文件
4.4. 启动 openLooKeng 并验证
4.5. 使用示例：查询 openGauss
4.6. 常见故障排查 - 图解：整体架构与流程
- 总结与建议
1. 概述
- openGauss 是华为主导的开源关系型数据库，兼容 PostgreSQL 生态，支持主备高可用和分布式部署。
- openLooKeng（前称 LooKeng）是一款轻量级、兼容多种数据源（包括 openGauss）的分布式 SQL 查询引擎。
本宝典旨在帮助你在最短时间内完成以下两项工作：
- 部署一个简单的 openGauss 分布式集群，包含 1 个主节点 和 1 个备节点。
- 一键部署 openLooKeng，通过 openLooKeng 将跨库查询定位到 openGauss 集群。
整个过程将采用 Shell 脚本、配置示例、示意图等多种手段，确保你能够快速复现。
2. 环境与前置准备
以下示例假设你在 两台 Linux 机器（CentOS 7/8 或 Ubuntu 20.04）上运行：
- 主节点 IP：
192.168.1.10 - 备节点 IP：
192.168.1.11 - 用户名：
gsadm（openGauss 默认安装用户） - openLooKeng 运行在主节点上（单节点模式）
2.1. 系统要求
- 操作系统：CentOS 7/8 或 Ubuntu 20.04
- 内存：至少 4 GB
- 磁盘：至少 20 GB 可用空间
- 网络：两节点互通无防火墙阻塞（6379、5432、9000 端口等）
2.2. 依赖软件
在两台机器上均需安装以下包：
# 对于 CentOS 7/8
sudo yum install -y wget vim net-tools lsof tree
# 对于 Ubuntu 20.04
sudo apt update
sudo apt install -y wget vim net-tools lsof tree2.3. 日期与 Locale 校验
确保时钟一致、时区正确，避免主备间时钟漂移导致复制失败。示例：
# 查看当前时间
date
# 确保 NTP 服务正在运行
sudo systemctl enable ntpd
sudo systemctl start ntpd
# 或者使用 chrony
sudo systemctl enable chronyd
sudo systemctl start chronyd3. openGauss 分布式集群部署
3.1. 架构概览
本示例采用双节点主备高可用架构，数据通过 built-in 的 streaming replication 方式同步：
┌───────────────────┐ ┌───────────────────┐
│ Primary Node │ │ Standby Node │
│ 192.168.1.10 │ │ 192.168.1.11 │
│ ┌───────────────┐ │ │ ┌───────────────┐ │
│ │ openGauss │ │ │ │ openGauss │ │
│ │ Port:5432 │ │ │ │ Port:5432 │ │
│ └───────────────┘ │ │ └───────────────┘ │
└───────┬───────────┘ └───┬───────────────┘
│ Streaming Replication │
│ WAL 日志 + PlaceLog │
▼ ▼- Primary Node 负责写入操作，产生 WAL 日志。
- Standby Node 通过
pg_basebackup拉取 Primary 数据，并使用recovery.conf进行日志接收，保持数据一致。 - 当主节点不可用时，可手动或自动切换 Standby 为 Primary。
3.2. 安装依赖与用户准备
两台机器都需要创建同名用户 gsadm，用于运行 openGauss：
# 以下以 CentOS/Ubuntu 通用方式示例
sudo useradd -m -s /bin/bash gsadm
echo "请为 gsadm 设定密码："
sudo passwd gsadm登录到两台机器，并切换到 gsadm 用户：
su - gsadm确保 gsadm 用户具备 sudo 权限（如果需要执行系统级命令）：
# 下面两行在 root 下执行
sudo usermod -aG wheel gsadm # CentOS
sudo usermod -aG sudo gsadm # Ubuntu3.3. 安装 openGauss 软件包
以 openGauss 3.2 为例（请根据官网最新版本下载）：
# 以主节点为例
cd /home/gsadm
wget https://opengauss.obs.cn-north-4.myhuaweicloud.com/3.2.0/openGauss-3.2.0-centos7-x86_64.tar.gz
tar -zxvf openGauss-3.2.0-centos7-x86_64.tar.gz
mv openGauss-3.2.0 openGauss同样在备节点执行相同命令，保证两节点的软件包路径、版本一致。
安装后目录示例：
/home/gsadm/openGauss
├── bin
│ ├── gaussdb
│ ├── gsql
│ └── gs_probackup
├── data # 初始化后生成
├── etc
│ ├── postgresql.conf
│ └── pg_hba.conf
├── lib
└── share3.4. 配置主节点（Primary）
3.4.1. 初始化数据库集群
以 gsadm 用户执行初始化脚本：
cd ~/openGauss
# 初始化集群，指定数据目录 /home/gsadm/openGauss/data
# -D 指定数据目录，-p 指定监听端口，-w 表示无需密码交互
./bin/gs_initdb -D ~/openGauss/data --nodename=primary --port=5432 --locale=zh_CN.UTF-8 --encoding=UTF8完成后，你会看到类似：
[INFO ] ... initdb 完成3.4.2. 修改配置文件
进入 ~/openGauss/etc，编辑 postgresql.conf：
cd ~/openGauss/etc
vim postgresql.conf修改或添加以下关键参数（以流复制为例）：
# ① 打开远程连接
listen_addresses = '*'
port = 5432
# ② WAL 设置：用于流复制
wal_level = replica
max_wal_senders = 5
wal_keep_segments = 128
archive_mode = on
archive_command = 'cp %p /home/gsadm/openGauss/wal_archive/%f'
archive_timeout = 60
# ③ 允许的同步节点
primary_conninfo = ''
# ④ 访问控制 (若使用 password 认证，可改 md5)
# 先关闭 host all all 0.0.0.0/0 trust，改为:
host replication gsadm 192.168.1.11/32 trust
host all all 0.0.0.0/0 md5同目录下编辑 pg_hba.conf，添加（如果上面未生效）：
# 允许 Standby 进行复制
host replication gsadm 192.168.1.11/32 trust
# 允许其他主机连接数据库
host all all 0.0.0.0/0 md5创建 WAL 存档目录：
mkdir -p ~/openGauss/wal_archive3.4.3. 启动 Primary 服务
# 切换到 openGauss 根目录
cd ~/openGauss
# 使用 gs_ctl 启动
./bin/gs_ctl start -D ~/openGauss/data -M primary等待几秒后，可以验证服务是否已启动并监听端口：
# 查看进程
ps -ef | grep gaussdb
# 检查端口
netstat -tnlp | grep 5432
# 尝试连接
./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm
# 默认密码为空，首次无需密码登录后执行：
SELECT version();确认 openGauss 版本输出正常。
3.5. 配置备节点（Standby）
3.5.1. 停止备节点上的任何旧服务
以 gsadm 用户登录备节点：
su - gsadm
cd ~/openGauss
# 如果 data 目录已有残留实例，先停止并清理
./bin/gs_ctl stop -D ~/openGauss/data --mode immediate
rm -rf ~/openGauss/data3.5.2. 使用 pg\_basebackup 复制数据
# 以 gsadm 用户登录备节点
cd ~/openGauss
# 使用 pg_basebackup 从 Primary 拉取全量数据
# -h 指定 Primary 主机 IP
# -p 5432
# -D 指定备节点数据目录
# -U 指定用户名 gsadm
# -Fp 表示 plain 模式
# -X fetch 表示同时拉取 WAL 文件
./bin/pg_basebackup -h 192.168.1.10 -p 5432 -U gsadm -D ~/openGauss/data -Fp -Xs -P --no-password如果出现认证失败，可先在 Primary 的 pg_hba.conf 中暂时设置 trust，或者在执行前设置环境变量 PGPASSWORD（如果 Primary 密码非空）：
export PGPASSWORD='your_primary_password'等待拉取完成后，备节点的 ~/openGauss/data 目录下已经包含和主节点一致的数据。
3.5.3. 创建 recovery.conf
在备节点的 ~/openGauss/data 目录下创建 recovery.conf 文件，内容如下：
# 这里假设 openGauss 版本仍支持 recovery.conf，若为新版本则改为 postgresql.conf 中 standby 配置
standby_mode = 'on'
primary_conninfo = 'host=192.168.1.10 port=5432 user=gsadm application_name=standby01'
trigger_file = '/home/gsadm/openGauss/data/trigger.file'
restore_command = 'cp /home/gsadm/openGauss/wal_archive/%f %p'standby_mode = 'on'：启用流复制模式primary_conninfo：指定 Primary 的连接信息trigger_file：当要手动触发备变主时，创建该文件即可restore_command：WAL 文件的恢复命令，从主节点的wal_archive目录复制
3.5.4. 修改 postgresql.conf 与 pg_hba.conf
备节点也需要在 ~/openGauss/etc/postgresql.conf 中修改如下参数（大多与主节点相同，但无需设置 wal_level）：
listen_addresses = '*'
port = 5432
hot_standby = on在 pg_hba.conf 中添加允许 Primary 访问的行：
# 允许 Primary 推送 WAL
host replication gsadm 192.168.1.10/32 trust
# 允许其他客户端连接
host all all 0.0.0.0/0 md53.5.5. 启动 Standby 服务
cd ~/openGauss
./bin/gs_ctl start -D ~/openGauss/data -M standby等待几秒，在备节点执行：
# 查看复制状态
./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm -c "select * from pg_stat_replication;"
# 备节点上可以通过 pg_stat_wal_receiver 查看接收状态
./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm -c "select * from pg_stat_wal_receiver;"若出现类似 streaming 字样，表示复制正常。
3.6. 启动集群并验证
至此，openGauss 主备模式已部署完成。
在 Primary 节点中，连接并执行：
./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm在其中执行：
CREATE TABLE test_table(id serial PRIMARY KEY, msg text); INSERT INTO test_table(msg) VALUES('hello openGauss'); SELECT * FROM test_table;在 Standby 节点中，尝试只读查询：
./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm执行如下命令应能看到数据：
SELECT * FROM test_table;
若查询结果正常，说明主备同步成功。
主备切换（手动）
在主节点停止服务（或直接 kill 进程）：
./bin/gs_ctl stop -D ~/openGauss/data --mode fast在备节点触发切换（创建 trigger 文件）：
touch ~/openGauss/data/trigger.file备节点会自动变为 Primary，日志中显示切换成功。验证：
# 在备（现 Primary）节点执行写操作 ./bin/gsql -h 127.0.0.1 -p 5432 -d postgres -U gsadm CREATE TABLE after_failover(id int); SELECT * FROM after_failover;
3.7. 常见故障排查
复制卡住：
- 检查网络连通性：
ping 192.168.1.10 - 检查主节点
wal_keep_segments是否足够：如客户端连接较慢导致 WAL 已被删除 - 查看
postgresql.log是否报错
- 检查网络连通性：
无法连接：
- 检查
listen_addresses与pg_hba.conf配置 - 检查防火墙：关闭或开放 5432 端口
- 确认
gsadm密码是否正确
- 检查
切换失败：
- 确保
trigger_file路径正确且备节点读写权限正常 - 检查备节点
hot_standby = on是否生效
- 确保
4. openLooKeng 一键部署
本章节演示如何在主节点上一键部署 openLooKeng，并通过 openLooKeng 查询 openGauss 集群中的数据。
4.1. 架构概览
openLooKeng 作为分布式 SQL 引擎，本示例采用单节点模式（生产可扩展为集群模式）：
┌──────────────┐ ┌─────────────────────────────┐
│ Client (JDBC)│◀────▶│ openLooKeng (Coordinator) │
│ sqoop, BI │ │ port: 9090 │
└──────────────┘ └───────┬─────────▲────────────┘
│ │
│ │
▼ │
┌────────────────┐ │
│ openGauss │ │ （openLooKeng Worker 角色可嵌入应用）
│ Primary/Standby│ │
│ 192.168.1.10 │ │
└────────────────┘ │
▼ │
┌────────────────┐
│ openGauss │
│ Standby │
│ 192.168.1.11 │
└────────────────┘- Client（BI 报表、JDBC 应用等）通过 JDBC 访问 openLooKeng；
- openLooKeng Coordinator 将 SQL 转换为分布式执行计划，并对接 openGauss 获取数据；
- 导出结果给 Client。
4.2. 下载与环境准备
以 openLooKeng 0.9.0 为例（请根据官网最新版本下载）：
# 以 gsadm 用户登录主节点
cd /home/gsadm
wget https://github.com/openlookeng/openLookeng/releases/download/v0.9.0/openlookeng-0.9.0.tar.gz
tar -zxvf openlookeng-0.9.0.tar.gz
mv openlookeng-0.9.0 openlookeng目录示例：
/home/gsadm/openlookeng
├── conf
│ ├── config.properties
│ ├── catalog
│ │ └── openGauss.properties
│ └── log4j2.properties
├── bin
│ └── openlookeng.sh
└── lib4.3. 修改配置文件
4.3.1. 配置 Catalog：openGauss.properties
编辑 conf/catalog/openGauss.properties，内容示例如下：
connector.name = opengauss
opengauss.user = gsadm
opengauss.password =
opengauss.nodes = 192.168.1.10:5432,192.168.1.11:5432
opengauss.database = postgres
opengauss.additional-bind-address =
opengauss.load-balance-type = ROUND_ROBIN
# 其他可选配置connector.name：必须为opengaussopengauss.user/password：openGauss 的连接用户及密码opengauss.nodes：指定 Primary/Standby 节点的 Host\:Port，多节点用逗号分隔，openLooKeng 会自动进行负载均衡load-balance-type：可以设置ROUND_ROBIN、RANDOM、RANGE等多种策略
4.3.2. 全局配置：config.properties
编辑 conf/config.properties，主要关注以下关键配置：
# Coordinator 端口
query.server.binding=0.0.0.0:9090
# Worker 数量：单节点模式可设置为 2
query.scheduler.worker.count=2
# JVM 参数（可视机器资源调整）
jvm.xms=2g
jvm.xmx=2g
# 默认 Catalog：设置为 openGauss
query.default-catalog = openGauss其他配置项可根据官方文档酌情调整，如监控、日志路径等。
4.4. 启动 openLooKeng 并验证
在 openlookeng 根目录下执行：
cd /home/gsadm/openlookeng/bin
chmod +x openlookeng.sh
./openlookeng.sh start等待数秒，可在控制台看到类似：
[INFO ] Starting openLooKeng Coordinator on port 9090 ...
[INFO ] All services started successfully.通过 ps -ef | grep openlookeng 可以看到进程在运行；也可使用 netstat -tnlp | grep 9090 确认端口监听。
4.4.1. 验证监听
curl http://localhost:9090/v1/info若返回 JSON 信息，说明服务已正常启动。例如：
{
"coordinator": "openLooKeng",
"version": "0.9.0",
"startTime": "2023-05-01T12:00:00Z"
}4.5. 使用示例：查询 openGauss
下面展示一个简单的 Java JDBC 客户端示例，通过 openLooKeng 查询 openGauss 中的表数据。
4.5.1. 引入依赖
在 pom.xml 中添加 openLooKeng JDBC 依赖：
<dependency>
<groupId>com.openlookeng</groupId>
<artifactId>openlookeng-jdbc</artifactId>
<version>0.9.0</version>
</dependency>4.5.2. Java 代码示例
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
public class OpenLooKengJDBCTest {
public static void main(String[] args) throws Exception {
// 1. 注册 Driver
Class.forName("com.openlookeng.jdbc.OpenLooKengDriver");
// 2. 连接 openLooKeng Coordinator
String url = "jdbc:opengauss://127.0.0.1:9090/openGauss/postgres";
String user = "gsadm";
String password = ""; // 若 openGauss 密码非空，请填入
Connection conn = DriverManager.getConnection(url, user, password);
Statement stmt = conn.createStatement();
// 3. 查询 openGauss 中 test_table 表
String sql = "SELECT * FROM test_table;";
ResultSet rs = stmt.executeQuery(sql);
while (rs.next()) {
int id = rs.getInt("id");
String msg = rs.getString("msg");
System.out.printf("id=%d, msg=%s%n", id, msg);
}
rs.close();
stmt.close();
conn.close();
}
}- JDBC URL 语法：
jdbc:opengauss://CoordinatorHost:CoordinatorPort/Catalog/Schema - 本例中
Catalog = openGauss，Schema = postgres（默认数据库）
4.6. 常见故障排查
无法连接 Coordinator：
- 检查
openlookeng.sh是否启动成功 - 查看
nohup.out、logs/目录下日志，排查端口冲突或配置语法错误
- 检查
查询报错 no catalog found：
- 确认
conf/catalog/openGauss.properties中connector.name=opengauss与query.default-catalog=openGauss是否一致 - 检查 openGauss 节点 IP\:Port 是否可访问
- 确认
查询结果不一致：
- 如果 openGauss 集群在主备切换期间，可能出现短暂不可用
- 检查 openLooKeng 日志中 “backend unreachable” 信息
5. 图解：整体架构与流程
5.1. openGauss 分布式主备架构
┌───────────────────────────────────────────────────────┐
│ openGauss 分布式集群 │
│ │
│ ┌───────────────┐ Streaming Replication │
│ │ Primary │──────────────────────────────────▶│
│ │ 192.168.1.10 │ WAL 日志 + PlaceLog → Buffer │
│ └───────────────┘ │
│ ▲ │
│ │ (Client 写入、DDL 等) │
│ │ │
│ ┌───────────────┐ │
│ │ Standby │◀───────────────────────────────────┘
│ │ 192.168.1.11 │ Apply WAL → 数据恢复 同步
│ └───────────────┘
└───────────────────────────────────────────────────────┘- 写请求（INSERT/UPDATE/DDL）到 Primary
- Primary 在本地写入 WAL 且推送给 Standby
- Standby 拉取 WAL 并实时应用，保持数据同步
5.2. openLooKeng 与 openGauss 交互架构
┌──────────────────────────────────────────────────────────────────┐
│ openLooKeng │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ Client A │◀───▶ │ Coordinator │◀───▶ │ openGauss │ │
│ │ (JDBC/BI/Shell)│ │ Port:9090 │ │ Primary │ │
│ └───────────────┘ └───────┬───────┘ └───────────────┘ │
│ │ \ │
│ │ \ Streaming Replication │
│ │ ➔ WAL + PlaceLog ➔ Buffer │
│ │ │
│ │ ┌───────────────┐ │
│ └──────▶│ openGauss │ │
│ │ Standby │ │
│ └───────────────┘ │
└──────────────────────────────────────────────────────────────────┘- Client 通过 JDBC 调用 openLooKeng
- Coordinator 将 SQL 解析、优化后，生成针对 openGauss 节点的子查询并发执行
- openGauss Primary/Standby 内部保持高可用，保证数据一致性
6. 总结与建议
本文围绕 openGauss 分布式主备集群 和 openLooKeng 一键部署，提供了从环境准备、软件安装、配置文件修改到命令行验证的一整套宝典级步骤，并辅以图解与代码示例。以下是一些建议与注意事项：
版本匹配：
- 在部署前，请务必确认 openGauss 与 openLooKeng 的兼容版本。
- 如 openGauss 3.x，需配合 openLooKeng 0.9.x；如新版本，请参考官方 Release Note。
安全与权限：
- 生产环境应为 openGauss 设置密码、SSL 加密以及严格的
pg_hba.conf规则； - openLooKeng 生产可启用身份验证、授权与加密（详见官方文档）。
- 生产环境应为 openGauss 设置密码、SSL 加密以及严格的
高可用与监控：
- openGauss 还支持更多节点的 cascade Standby 或 DCF 高可用方案，可根据业务需求扩展；
- 部署 Prometheus + Grafana 对 openGauss 与 openLooKeng 指标进行监控，及时发现性能瓶颈。
扩展与性能调优：
- openGauss 可结合分片方案（如使用 sharding-jdbc）实现更大规模分布式；
- openLooKeng 可水平扩容至多台 Coordinator 与 Worker，提升查询吞吐；
- 调优建议请参考官方调优文档，如
shared_buffers、work_mem、max_connections、scheduler.worker.count等参数。
备份与恢复：
- 定期使用
gs_probackup对 openGauss 集群做物理备份和逻辑备份； - openLooKeng 本身不存储数据，只需备份配置文件与 Catalog，不用担心数据丢失。
- 定期使用
通过本文的一步一步部署示例，你应该能够在数分钟内完成一个简单的 openGauss 主备集群和 openLooKeng 单节点实例。在此基础上，你可以根据业务需求，增加更多节点、加入负载均衡以及安全组件，逐步构建一个高可用、高性能的分布式数据库与大数据查询平台。
