部署兼容MongoDB语法的PolarDB PostgreSQL轻量版集群-云原生数据库 PolarDB-阿里云

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

功能简介

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

PostgreSQL协议端口（默认为1523）：用于接收和处理标准的SQL请求。
MongoDB协议端口（默认为27030）：用于接收和处理来自MongoDB客户端的请求。

前提条件

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

您的部署环境满足以下软硬件要求：

需求项		配置说明
硬件	服务器架构	仅支持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）

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

以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

安装完成后，执行pdbcli version命令验证。如果成功返回版本号，则表示pdbcli工具已安装成功。

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

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

选择配置模板

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

配置文件模板	说明
`config_template.yaml`	一主两备集群的配置文件模板。一主两备形态可保证高可用，RTO（恢复时间目标）小于60秒，同时确保RPO（恢复点目标）为0。
`config_master_slave.yaml`	一主一备集群的配置文件模板。一主一备形态可保证高可用，RTO（恢复时间目标）小于60秒，但无法保证RPO（恢复点目标）为0。
`config_single_node.yaml`	单节点集群的配置文件模板。单节点形态无法保证高可用和高可靠，不建议在生产环境中使用。

修改关键配置 打开您选择的模板文件，务必修改以下两个参数以启用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.

验证配置 修改完成后，执行pdbcli validate命令检查配置文件是否存在语法错误。

步骤三：预配置操作系统

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

执行cat /sys/kernel/mm/transparent_hugepage/enabled命令检查状态。
如果输出不是always madvise [never]，请执行以下命令关闭它：
```
echo never > /sys/kernel/mm/transparent_hugepage/enabled
```

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

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

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

部署一主两备集群

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}}'

步骤五：验证部署结果

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

检查集群状态 执行pdbcli status命令。若cluster_manager、master、standby、proxy等组件的状态均为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": ""
	}

检查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）。则说明数据库安装成功，且数据库内核版本检查正常。

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

安装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

连接并测试
将命令中的{{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子目录下。如果您的集群ID为polardb1，且未修改数据目录，则路径为：

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

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

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

后续操作

常见问题

如果安装失败，如何清理环境并重新安装？

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

pdbcli delete cluster && pdbcli uninstall cluster