安装部署(兼容MongoDB语法)

如果您的应用基于MongoDB协议开发,但希望将其运行在具备ACID特性、支持复杂查询的关系型数据库之上,您可以使用PolarDB PostgreSQL轻量版。本文介绍如何部署一个兼容MongoDB语法的PolarDB PostgreSQL轻量版集群,使您无需修改应用代码,即可通过MongoDB客户端和驱动程序连接并使用数据库。

功能简介

PolarDB PostgreSQL轻量版通过内置的语法兼容层,实现了对MongoDB协议和语法的支持。当您启用MongoDB兼容模式后,数据库实例会同时监听两个端口:

  • PostgreSQL协议端口(默认为1523):用于接收和处理标准的SQL请求。

  • MongoDB协议端口(默认为27030):用于接收和处理来自MongoDB客户端的请求。

前提条件

  1. 您已获取部署所需的软件包。请参考购买商业化服务以了解详情。其中,PolarDB PostgreSQL轻量版数据库引擎中包含MongoDB语法兼容。

  2. 您的部署环境满足以下软硬件要求:

    需求项

    配置说明

    硬件

    服务器架构

    仅支持X86架构。

    CPU

    ≥ 2

    内存

    ≥ 8 GB

    硬盘

    系统盘:根分区(/)至少预留10 GB可用空间。

    数据盘:至少一个本地数据盘,容量不小于256 GB。

    网络

    千兆以太网或更高。

    软件

    操作系统

    Linux CentOS 7.2及以上或其他Red Hat兼容的操作系统(如麒麟、统信、龙蜥等)。

    说明

    建议字符集设置为LANG=en_US.UTF-8

    文件系统

    本地盘文件系统为ext4

    glibc版本

    ≥ 2.15

    说明

    您可以通过以下命令查看glibc版本。根据输出的glibc版本号列表,查看是否包含GLIBC_2.15或以上版本。

    strings /lib64/libc.so.6 | grep "^GLIBC_2."

    Python

    已安装Python 3,并将其软链接为python

    说明

    安装命令及设置软链接命令:

    sudo yum install -y python3
    sudo ln -sf $(which python3) /usr/bin/python

计费说明

PolarDB PostgreSQL轻量版为商业化产品,部署和使用需要购买授权(License)。您可以联系我们获取为期30天的单节点免费试用版本,试用期结束后,数据库将被自动限流。

注意事项

在开始部署前,请仔细阅读以下限制与建议,以确保部署过程顺利:

  • 版本兼容性:MongoDB语法兼容功能目前仅支持PostgreSQL 16版本,请务必使用对应的专用软件包。

  • 用户权限:所有安装操作均需要使用root用户执行。

  • 部署后无法修改的配置:以下两个参数在集群创建后无法修改。如需变更,只能卸载集群后重新部署。

    • compatibility_mode:兼容模式。启用MongoDB兼容功能,必须在配置文件中设置为mongodb

    • polardb_data_root_dir:数据库文件目录。默认路径/var/lib/thirdDB所在分区空间可能不足,强烈建议您根据数据量规划,将其配置到容量充足的数据盘路径。

  • 配置文件格式:配置文件必须遵循严格的YAML格式,禁止使用Tab(制表符)。

  • 密码安全性:在使用一键部署脚本时,如果密码包含!等特殊字符,建议使用单引号' '将密码括起来,以避免执行失败。

操作步骤

请按照以下步骤完成集群的部署与验证。

步骤一:安装集群管理工具(pdbcli)

  1. 获取名为polarflex-mongodb-${version}-${build-date}.tar.gz的软件包,并上传至目标主机。

  2. root用户登录主机,执行以下命令解压并安装管理工具。以2.3.2.4版本为例:

    # 创建工作目录version=2.3.2.4
    mkdir -p polarflex-mongodb-${version}
    # 解压软件包至工作目录
    tar -C polarflex-mongodb-${version}/ -xf polarflex-mongodb-${version}-${build-date}.tar.gz
    # 进入工作目录并执行安装脚本
    cd polarflex-mongodb-${version}/
    ./scripts/install.sh
  3. 安装完成后,执行pdbcli version命令验证。如果成功返回版本号,则表示pdbcli工具已安装成功。

步骤二:准备并检查配置文件

配置文件(默认使用的配置文件为polarflex-${version}/文件夹下的config.yaml)定义了集群的拓扑、端口、数据库参数等关键信息。您可以根据部署架构,选择并修改对应的模板文件。

  1. 选择配置模板

    为便于您选择config.yaml的配置,在相同目录下提供了不同场景的配置文件模板。

    配置文件模板

    说明

    config_template.yaml

    一主两备集群的配置文件模板。一主两备形态可保证高可用,RTO(恢复时间目标)小于60秒,同时确保RPO(恢复点目标)为0。

    config_master_slave.yaml

    一主一备集群的配置文件模板。一主一备形态可保证高可用,RTO(恢复时间目标)小于60秒,但无法保证RPO(恢复点目标)为0。

    config_single_node.yaml

    单节点集群的配置文件模板。单节点形态无法保证高可用和高可靠,不建议在生产环境中使用。

  2. 修改关键配置 打开您选择的模板文件,务必修改以下两个参数以启用MongoDB兼容功能并规划数据存储:

    • 兼容模式

      # ... 其他配置 ...
      compatibility_mode: mongodb # 启用 MongoDB 语法兼容模式
      # ... 其他配置 ...
    • 文件目录

      # ... 其他配置 ...
      polardb_data_root_dir: /path/to/your/data_directory # 强烈建议修改为大容量数据盘路径
      # ... 其他配置 ...

    同时,您还需要根据实际环境填写所有主机的IP地址(ansible_host)。以下为一个一主两备集群的配置示例:

    # 请结合实际部署环境的情况,修改配置文件中的内容。修改完成后,可执行 pdbcli validate 验证配置是否有问题。
    # 配置文件需要符合yaml格式,不能包含=(等号)或者⇥(tab)等
    
    # 以下配置文件示例展示了如何搭建一个由三台主机构建的集群,主机IP分别为10.XX.XX.1、
    # 10.XX.XX.2、10.XX.XX.3。请您根据实际情况进行配置。
    all:
      children:
        cm:
          hosts:
            host01: null
            host02: null
            host03: null
          var: null
        db:
          hosts:
            host01:
              polardb_polar_hostid: 1
            host02:
              polardb_polar_hostid: 2
              polardb_node_type: standby
            host03:
              polardb_polar_hostid: 3
              polardb_node_type: standby
          vars:
            polardb_custom_params:
            - max_standby_streaming_delay = 900000
            - max_connections = 3300
            - polar_max_super_conns = 1500
            - max_slot_wal_keep_size = 64000
            - log_statement = 'ddl'
            polardb_service_restart_sec: 5
            hugepage_enabled: off
        proxy:
          hosts:
            host01: null
            host02: null
          var: null
      hosts:
        host01:
          ansible_host: 10.XX.XX.1 # HOST01_IP 【必填】
        host02:
          ansible_host: 10.XX.XX.2 # HOST02_IP 【必填】
        host03:
          ansible_host: 10.XX.XX.3 # HOST03_IP 【必填】
      vars:
        ansible_group_priority: 99
        ansible_python_interpreter: /usr/bin/python
        cluster_id: polardb1
        cm_consensus_port: 7001
        cm_service_port: 5001
        cm_tls_service_port: 6001
        cm_db_sync_mode: SYNC
        polardb_data_root_dir: /var/lib/thirdDB
        license_dir: license
        polardb_enable_direct_io: false
        polardb_multi_instance_per_host: true
        polardb_polar_enable_pfs_mode: false
        polardb_port: 1523
        polardb_proxy_port: 12369
        polardb_proxy_port_rwlb: 12370
        polardb_proxy_admin_port: 12371
        polardb_storage_mode: local_filesystem_mode
        polardb_user: polar1
        primary_db_host: host01
        ue_node_driver_service_port: 12355
        password_encrypt: true
        lc_ctype: en_US.UTF8
        compatibility_mode: mongodb # 启用 mongodb 语法兼容模式
        # Each parameter can be passed in through environment variable. Here is an example.
  3. 验证配置 修改完成后,执行pdbcli validate命令检查配置文件是否存在语法错误。

步骤三:预配置操作系统

在创建集群前,需确保操作系统已关闭透明大页(Transparent Huge Pages)。

  1. 执行cat /sys/kernel/mm/transparent_hugepage/enabled命令检查状态。

  2. 如果输出不是always madvise [never],请执行以下命令关闭它:

    echo never > /sys/kernel/mm/transparent_hugepage/enabled

步骤四:一键安装并创建数据库集群

工作目录下提供了polarflex-deploy.sh脚本,用于一键完成集群部署。该脚本会自动处理SSH免密、生成config.yaml文件以及安装和创建集群等步骤。

根据您规划的集群架构,执行对应命令。请将10.XX.XX.X{{password}}替换为实际的主机IProot密码。

  • 部署一主两备集群

    bash polarflex-deploy.sh -m "10.XX.XX.1" -p '{{password}}' -m "10.XX.XX.2" -p '{{password}}' -m "10.XX.XX.3" -p '{{password}}'
  • 部署一主一备集群

    bash polarflex-deploy.sh -m "10.XX.XX.1" -p '{{password}}' -m "10.XX.XX.2" -p '{{password}}'
  • 部署单节点集群

    bash polarflex-deploy.sh -m "10.XX.XX.1" -p '{{password}}'

步骤五:验证部署结果

部署完成后,请进行以下检查以确认集群状态正常。

  1. 检查集群状态 执行pdbcli status命令。若cluster_managermasterstandbyproxy等组件的状态均为RUNNING,则表示集群部署成功。

    Using config file: ./config.yaml
    Cluster Status:
    {
    	"phase": "RunningPhase",
    	"cluster_manager": [
    		{
    			"endpoint": "172.xxx.xxx.xxx:5001",
    			"phase": "RUNNING"
    		},
    		{
    			"endpoint": "172.xxx.xxx.xxx:5001",
    			"phase": "RUNNING"
    		},
    		{
    			"endpoint": "172.xxx.xxx.xxx:5001",
    			"phase": "RUNNING"
    		}
    	],
    	"master": {
    		"endpoint": "172.xxx.xxx.xxx:1523",
    		"cust_id": "0",
    		"work_path": "/var/lib/thirdDB/clusters/polardb1",
    		"phase": "RUNNING",
    		"start_at": "2025-03-13 19:41:50"
    	},
    	"standby": [
    		{
    			"endpoint": "172.xxx.xxx.xxx:1523",
    			"cust_id": "0",
    			"work_path": "/var/lib/thirdDB/clusters/polardb1",
    			"phase": "RUNNING",
    			"start_at": "2025-03-13 19:42:02",
    			"sync_status": "SYNC"
    		},
    		{
    			"endpoint": "172.xxx.xxx.xxx:1523",
    			"cust_id": "0",
    			"work_path": "/var/lib/thirdDB/clusters/polardb1",
    			"phase": "RUNNING",
    			"start_at": "2025-03-13 19:42:02",
    			"sync_status": "SYNC"
    		}
    	],
    	"proxy": [
    		{
    			"endpoint": "172.xxx.xxx.xxx:12369",
    			"phase": "RUNNING"
    		},
    		{
    			"endpoint": "172.xxx.xxx.xxx:12369",
    			"phase": "RUNNING"
    		}
    	],
    	"plugins": [
    		{
    			"name": "golang-manager",
    			"status": "Plugin run err topo is null errCount 2"
    		}
    	],
    	"disk": {
    		"state": "UNLOCK",
    		"quota": "UNSET",
    		"usage": ""
    	}
  2. 检查PostgreSQL协议连通性 集群默认创建用户admin(密码postgres)和数据库admin_db。执行以下命令测试PostgreSQL端口连通性:

    PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h localhost -p1523 -U admin -d admin_db -c 'show polardb_version'

    如果成功返回PolarDB版本号(如PolarDB V2.0.16.8.0)。则说明数据库安装成功,且数据库内核版本检查正常。

  3. 检查MongoDB协议连通性 使用MongoDB客户端(如mongosh)连接MongoDB端口(默认为27030),验证兼容功能是否生效。

    1. 安装mongosh客户端(以CentOS为例)

      sudo vim /etc/yum.repos.d/mongodb-org-6.repo
      
      # 将下面的内容粘贴至文档中
      [mongodb-org-6.0]
      
      name=MongoDB Repository
      baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/6.0/x86_64/
      gpgcheck=1
      enabled=1
      gpgkey=https://pgp.mongodb.com/server-6.0.asc
      
      # 退出 vim,执行下面安装 mongodb-org 命令
      sudo yum install -y mongodb-org
    2. 连接并测试

      将命令中的{{HOST01_IP}}替换为主节点的实际IP地址,{{polar_mongodb_port}}替换为MongoDB的监听端口(默认为27030)。

      mongosh "mongodb://test_user:superuser_20250530@{{HOST01_IP}}:{{polar_mongodb_port}}"

      连接成功后,提示符会变为admin_db>。您可以尝试插入数据进行验证:

      db.users.insertMany([
        { name: "Alice", age: 25, email: "alice@example.com" },
        { name: "Bob", age: 30, email: "bob@example.com" },
        { name: "Charlie", age: 22, email: "charlie@example.com" }
      ])

      如果数据插入成功,则表示MongoDB兼容功能已完全就绪。

故障排查与运维

在日常使用和问题排查中,您可能需要检查服务进程或查看日志文件。

检查服务进程

数据库启动后,您可以通过检查操作系统的进程列表来确认服务状态。数据库主进程的PID记录在数据目录下的postmaster.pid文件中。

  • PolarDB PostgreSQL轻量版核心进程

    • postgres: logger:日志打印进程。

    • postgres: checkpointer:周期性检查点进程。

    • postgres: background writer:周期性刷脏页进程。

    • postgres: walwriter:WAL日志刷盘进程。

    • postgres: autovacuum launcher:自动清理调度进程。

    • postgres: stats collector:统计信息收集进程。

  • MongoDB兼容组件进程

    • python2 /u01/polar_documentdb_daemon/polar_documentdb_daemon.py:MongoDB兼容组件的守护进程,负责其探活和自动拉起。

查看日志文件

所有日志文件默认保存在数据目录的log子目录下。如果您的集群IDpolardb1,且未修改数据目录,则路径为:

cd /var/lib/thirdDB/clusters/polardb1/log/
ls

其中,与MongoDB兼容功能相关的日志文件为:

polar_documentdb_daemon.log:MongoDB兼容组件守护进程的日志。

后续操作

常见问题

如果安装失败,如何清理环境并重新安装?

如果部署过程中断或出错,您需要先执行清理命令,再重新从步骤四:一键安装并创建数据库集群开始执行。请勿直接重新运行部署脚本。

pdbcli delete cluster && pdbcli uninstall cluster