openGauss分布式与openLooKeng一键部署宝典‌

openGauss分布式与openLooKeng一键部署宝典

本文将结合 代码示例、ASCII 图解 和 详细说明，手把手教你如何在 Linux 环境下快速部署 openGauss 分布式集群 以及 openLooKeng，帮助你快速上手并理解原理。全程采用“一键部署”思路，减少重复操作，降低学习成本。

目录

1. 概述
2. 环境与前置准备
3. openGauss 分布式集群部署
   3.1. 架构概览
   3.2. 安装依赖与用户准备
   3.3. 安装 openGauss 软件包
   3.4. 配置主节点（Primary）
   3.5. 配置备节点（Standby）
   3.6. 启动集群并验证
   3.7. 常见故障排查
4. openLooKeng 一键部署
   4.1. 架构概览
   4.2. 下载与环境准备
   4.3. 修改配置文件
   4.4. 启动 openLooKeng 并验证
   4.5. 使用示例：查询 openGauss
   4.6. 常见故障排查
5. 图解：整体架构与流程
6. 总结与建议

1. 概述

• openGauss 是华为主导的开源关系型数据库，兼容 PostgreSQL 生态，支持主备高可用和分布式部署。
• openLooKeng（前称 LooKeng）是一款轻量级、兼容多种数据源（包括 openGauss）的分布式 SQL 查询引擎。

本宝典旨在帮助你在最短时间内完成以下两项工作：

1. 部署一个简单的 openGauss 分布式集群，包含 1 个主节点 和 1 个备节点。
2. 一键部署 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 tree

2.3. 日期与 Locale 校验

确保时钟一致、时区正确，避免主备间时钟漂移导致复制失败。示例：

# 查看当前时间
date

# 确保 NTP 服务正在运行
sudo systemctl enable ntpd
sudo systemctl start ntpd

# 或者使用 chrony
sudo systemctl enable chronyd
sudo systemctl start chronyd

3. 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     # Ubuntu

3.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
└── share

3.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_archive

3.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/data

3.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            md5

3.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;

若查询结果正常，说明主备同步成功。

主备切换（手动）

1. 在主节点停止服务（或直接 kill 进程）：

   ./bin/gs_ctl stop -D ~/openGauss/data --mode fast

2. 在备节点触发切换（创建 trigger 文件）：

   touch ~/openGauss/data/trigger.file

3. 备节点会自动变为 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
└── lib

4.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：必须为 opengauss
• opengauss.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 一键部署，提供了从环境准备、软件安装、配置文件修改到命令行验证的一整套宝典级步骤，并辅以图解与代码示例。以下是一些建议与注意事项：

1. 版本匹配：

   • 在部署前，请务必确认 openGauss 与 openLooKeng 的兼容版本。
   • 如 openGauss 3.x，需配合 openLooKeng 0.9.x；如新版本，请参考官方 Release Note。

2. 安全与权限：

   • 生产环境应为 openGauss 设置密码、SSL 加密以及严格的pg_hba.conf规则；
   • openLooKeng 生产可启用身份验证、授权与加密（详见官方文档）。

3. 高可用与监控：

   • openGauss 还支持更多节点的 cascade Standby 或 DCF 高可用方案，可根据业务需求扩展；
   • 部署 Prometheus + Grafana 对 openGauss 与 openLooKeng 指标进行监控，及时发现性能瓶颈。

4. 扩展与性能调优：

   • openGauss 可结合分片方案（如使用 sharding-jdbc）实现更大规模分布式；
   • openLooKeng 可水平扩容至多台 Coordinator 与 Worker，提升查询吞吐；
   • 调优建议请参考官方调优文档，如 shared_buffers、work_mem、max_connections、scheduler.worker.count 等参数。

5. 备份与恢复：

   • 定期使用 gs_probackup 对 openGauss 集群做物理备份和逻辑备份；
   • openLooKeng 本身不存储数据，只需备份配置文件与 Catalog，不用担心数据丢失。

通过本文的一步一步部署示例，你应该能够在数分钟内完成一个简单的 openGauss 主备集群和 openLooKeng 单节点实例。在此基础上，你可以根据业务需求，增加更多节点、加入负载均衡以及安全组件，逐步构建一个高可用、高性能的分布式数据库与大数据查询平台。