问题现象
应用程序或客户端工具（如 KSQL、KStudio）尝试连接 KingbaseES 数据库时，返回如下错误之一：
could not connect to server: Connection refusedFATAL: no pg_hba.conf entry for host "x.x.x.x"FATAL: password authentication failed for user "system"the database system is starting up
排查步骤
第一步：确认服务是否正常运行
# Linux 系统 systemctl status kingbase # 或使用金仓管理工具 sys_ctl status -D /data/kingbase/data
第二步：确认监听端口
# 检查 postgresql.conf 中的监听配置 grep -E "listen_addresses|port" /data/kingbase/data/kingbase.conf # 检查端口是否在监听 ss -tlnp | grep 54321
第三步：检查 sys_hba.conf 访问控制规则
sys_hba.conf 是金仓数据库的客户端认证配置文件，控制哪些主机可以连接哪个数据库。
# sys_hba.conf 示例条目（允许特定 IP 以密码方式连接） # TYPE DATABASE USER ADDRESS METHOD host all all 192.168.1.0/24 md5 host all all 127.0.0.1/32 trust local all all peer
修改 sys_hba.conf 后需执行
sys_ctl reload 或 SELECT sys_reload_conf(); 使配置生效，不需要重启数据库。第四步：防火墙检查
# 开放 54321 端口（金仓默认端口） firewall-cmd --permanent --add-port=54321/tcp firewall-cmd --reload # 或 iptables iptables -I INPUT -p tcp --dport 54321 -j ACCEPT
常见原因汇总
| 错误信息 | 可能原因 | 解决方法 |
|---|---|---|
| Connection refused | 服务未启动或端口错误 | 启动服务，确认端口配置 |
| no pg_hba.conf entry | 客户端 IP 未在白名单 | 在 sys_hba.conf 添加条目并 reload |
| password authentication failed | 密码错误或用户不存在 | 重置密码，确认用户名 |
| database system is starting up | 实例正在恢复或启动 | 等待实例就绪（检查日志） |
预防建议
- 生产环境避免使用
trust认证方式，统一采用md5或scram-sha-256。 - 定期审查 sys_hba.conf，删除不再使用的 IP 条目。
- 监控 54321 端口可达性，接入告警系统。