如果您的应用基于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兼容组件守护进程的日志。