pdbcli配置说明-阿里云帮助中心

pdbcli 配置文件是安装、部署和运维PolarDB PostgreSQL轻量版数据库集群的重要组成部分。它用于定义集群的拓扑结构、主机信息、端口配置、数据库参数等关键内容。正确理解和使用这些配置文件，对于保障集群的稳定运行至关重要。本文将详细介绍 polarflex-${version}/ 目录下各配置文件及其参数说明。

配置清单

配置文件名称	主要用途	使用场景	注意事项
`config.yaml`	默认使用的配置文件；用于日常维护数据库集群。	日常维护、集群管理、运维操作。	• 不要随意删除 • 修改后需验证配置语法 • 生产环境修改前建议备份
`config_template.yaml`	一主两备集群的配置文件模板。	一键部署三节点集群。	• 安装部署需要3台服务器 • 安装后该文件不再使用
`config_master_slave.yaml`	一主一备集群配置模板。	一键部署双节点集群。	• 安装部署需要2台服务器 • 安装后该文件不再使用
`config_single_node.yaml`	单节点集群配置模板。	一键部署单节点集群。	• 安装部署只需要1台服务器 • 安装后该文件不再使用

部署与运维

可以使用一键部署脚本polarflex-deploy.sh用于首次创建集群。您需要根据期望的集群架构选择并修改对应的模板文件。

工作原理：polarflex-deploy.sh 脚本会读取您选择的模板文件，结合您传入的 IP 地址等参数，自动生成并覆盖 config.yaml 文件，然后基于这个新生成的 config.yaml 来执行部署。
操作流程：
1. 选择一个模板文件config_single_node.yaml， config_master_slave.yaml，或config_template.yaml。
2. 根据需求修改该模板文件中的参数。
3. 运行 polarflex-deploy.sh 进行一键部署。
4. 脚本会自动生成 config.yaml 文件。
5. 部署完成后，检查 config.yaml 的内容是否符合预期。
6. 集群部署完成后，所有的日常管理和维护操作都应直接针对 config.yaml 文件。

参数解析

以下以 config_template.yaml 为例，解析文件结构与关键参数。该文件用于在三台主机上部署一个包含集群管理（cm）、数据库（db）与代理（proxy）的三节点 PolarDB 集群。

说明

默认配置文件不做任何修改也可以成功安装部署集群，如您需要快速安装，可以跳过配置文件修改步骤，直接安装创建集群。

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
        host03: null
      var: null
  hosts:
    host01:
      ansible_host: {{host1}} # HOST01_IP
    host02:
      ansible_host: {{host2}} # HOST02_IP
    host03:
      ansible_host: {{host3}} # 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
    polardb_init_username: {{polardb_init_username}}
    polardb_base_init_password: {{polardb_base_init_password}}
    polardb_init_database_name: {{polardb_init_database_name}}
    primary_db_host: host01
    ue_node_driver_service_port: 12355
    password_encrypt: true
    cpu_cores: {{cpu_cores}}
    memory_limit: {{memory_limit}}
    lc_ctype: en_US.UTF8
    global_type: {{global_type}}
    global_master_hosts_ip: {{global_master_hosts_ip}}
    maintenance_user: {{maintenance_user}}
    global_stream_mode: {{global_stream_mode}}
    compatibility_mode: pg
    # Each parameter can be passed in through environment variable. Here is an example.
    # alternative_parameters: {{alternative_parameters}}

一、整体结构与编辑原则

文件结构：
- all.children：按功能（cm, db, proxy）对主机进行分组，并定义组级别的变量。
- all.hosts：定义集群中所有主机的别名及其对应的 IP 地址。
- all.vars：定义适用于整个集群的全局变量。
编辑原则：
- all.hosts 部分不要手动修改。运行polarflex-deploy.sh脚本会把传参中机器IP自动替换到配置文件中。
- all.children.*.hosts 部分不要手动修改，默认会在所有节点上部署完整的 cm, db, proxy 组件。
- 按需在全局 all.vars和分组 all.children.*.vars中调整参数。
- 修改后的YAML必须保持缩进与键名正确，布尔值使用 true/false，端口为整数，字符串无空格时可不加引号。

二、分组定义 (`all.children`)

cm：
- children.cm.hosts：部署集群管理（CM）服务的主机列表。通常为1台或3台以实现高可用。
  说明
  增加/减少 CM 节点通常需要重新运行部署或进行 CM 的集群级操作。

db ：

children.db.hosts.*.polardb_polar_hostid：数据库节点在集群内的唯一数字ID，必须唯一。
children.db.hosts.*.polardb_node_type：节点类型。主节点（Primary）可省略，备节点（Standby）必须显式指定为 standby。

children.db.vars.polardb_custom_params：自定义数据库参数，会透传给 PostgreSQL 内核。

参数	示例值	含义	修改建议
`max_standby_streaming_delay`	900000	备库在应用主库流式 WAL 时，遇到冲突查询最多等待的时间（毫秒）。超出则取消冲突查询以保证回放推进。900000=15 分钟。	通常可保持默认值。
`max_connections`	3300	实例允许的最大并发连接数	结合业务需要和连接管理策略设定，避免设置过大导致内存耗尽。修改需重启实例。通常可保持默认值。
`polar_max_super_conns`	1500	PolarDB 中超级用户允许的最大并发连接上限。	保持默认值。
`max_slot_wal_keep_size`	64000	每个复制槽可保留的 WAL 上限（MB）。达到上限后会回收最老的 WAL ，同时主备流复制会断开，防止磁盘被无限占满。默认值约为62.5GB。	基于磁盘容量、下游滞后与发送延迟设定，关键是监控复制槽延迟，避免因参数设置上限过低导致快速写入场景下主库生成的wal被回收，导致主备流复制中断，备库会处于不可用状态，需要手动重建。如果主备流复制为同步模式，主备流复制中断会导致主节点无法写入。
`log_statement`	ddl	控制记录到日志的 SQL 粒度：none/ddl/mod/all。默认仅记录 DDL 语句。	按需求设置。避免长期开启 all，避免日志暴涨与性能影响。

children.db.vars.polardb_service_restart_sec：服务滚动重启时节点间等待秒数，建议保持默认值。
children.db.vars.hugepage_enabled：是否启用操作系统大页内存 (on/off)。若开启，需在操作系统层面完成配置。

proxy ：
children.proxy.hosts：部署代理服务的主机列表。通常部署在多台以保证可用性。

三、全局变量 (`all.vars`)

本小节介绍全局变量all.vars参数含义。配置文件中有部分参数带{{}}，这部分参数在一键部署中会进行自动替换，不需要手动修改。不在列表中的参数也建议保持默认值，不需要修改，安装程序会自动管理和配置，无需手动干预。下面列表中参数（数据目录、使用端口等）安装后不支持修改，如需修改需要先卸载并删除集群后重新部署。

参数名	作用与说明	示例/默认	修改建议
`polardb_data_root_dir`	存储数据文件的目录	/var/lib/thirdDB	建议修改，修改为大容量数据盘路径，以保证性能和空间。
`compatibility_mode`	数据库兼容类型	pg	按需修改，可选 `pg` 或 `ora`。若需兼容 Oracle 语法，请设置为 `ora`。
`ansible_group_priority`	控制 Ansible 变量覆盖顺序	99	建议保持默认。
`ansible_python_interpreter`	Ansible 在目标机的 Python 路径	/usr/bin/{{python}}	建议保持默认。
`cluster_id`	集群标识	polardb1	建议保持默认，或自定义为有意义的名称。
`cm_consensus_port`	CM 内部一致性通信端口	7001	建议保持默认，避免端口冲突。
`cm_service_port`	CM 对外服务端口	5001	按需修改，避免端口冲突并放通防火墙
`cm_db_sync_mode`	主备复制模式：同步/异步	SYNC/ASYNC	建议保持默认，一主一备默认异步复制ASYNC模式，一主两备默认同步复制SYNC模式。
`polardb_storage_mode`	存储模式	local_filesystem_mode	建议保持默认。
`polardb_port`	数据库端口	1523	按需修改，避免端口冲突并放通防火墙，客户端需按需连接此端口。
`polardb_proxy_port`	代理服务强一致读写端口	12369	按需修改，避免端口冲突并放通防火墙。
`polardb_proxy_port_rwlb`	代理服务读写分离端口	12370	按需修改，避免端口冲突并放通防火墙。
`polardb_proxy_admin_port`	代理管理端口	12371	按需修改，避免端口冲突。
`polardb_user`	运行数据库服务的操作系统用户	polar1	建议保持默认。
`primary_db_host`	逻辑上指定主库所在的主机别名	host01	建议保持默认。
`ue_node_driver_service_port`	节点驱动服务端口	12355	按需修改，避免端口冲突。
`polardb_init_username`	安装初始化时创建的管理/业务超级用户	admin	建议保持默认。
`polardb_base_init_password`	初始超级用户的登录口令	cG9zdGdyZXM=	建议保持默认，默认值经过base64加密
`polardb_init_database_name`	安装完成后自动创建的业务库名	admin_db	建议保持默认，语义化命名，避免与系统库冲突。
`password_encrypt`	配置文件中密码是否启用base64加密	true	建议保持默认。
`lc_ctype`	字符集区域设置	en_US.UTF8	建议保持默认，确保操作系统已安装此 locale （`locale -a`）。否则，需先安装或更换为已有的 locale（如 `zh_CN.UTF-8`）。

说明

数据目录、端口等参数在集群安装后不支持修改。如需变更，必须卸载并重新部署集群。

注意事项

端口冲突：检查所有端口是否与其他服务冲突。
路径权限：确保配置文件中使用的 polardb_user 对数据目录有读写权限，如当前操作系统没有该用户，安装过程中会自动进行创建。
网络要求：确保所有节点间网络互通，防火墙规则正确配置。
配置文件：检查YAML语法是否正确。