PostgreSQL SSL 连接错误全排查：从“SSL is required”到生产级安全配置

它解决什么问题 / 适用场景

当你从客户端（psql、应用代码、BI 工具）连接 PostgreSQL 数据库时，遇到以下错误之一，本文就是为你准备的：

• psql: error: connection to server failed: SSL is required
• FATAL: no pg_hba.conf entry for host "xxx.xxx.xxx.xxx", user "xxx", database "xxx", SSL off
• SSL error: certificate verify failed
• sslmode value "require" invalid when SSL support is not compiled in

这些错误通常出现在以下场景：

本文覆盖从最简单的“加个参数就能连”到“配置 CA 证书验证”的完整链路，并提供多语言代码示例和常见报错的具体解决方案。

核心配置 / 参数说明

sslmode 参数详解

PostgreSQL 的 SSL 连接行为由 sslmode 参数控制，共 6 个级别，安全性递增：

关键区别：require 只加密数据流，不验证服务器身份，容易被中间人劫持。verify-full 是唯一能确保你连接的是“真正的”目标服务器的模式。

连接方式对比

与同类方案对比

客户端库配置差异

核心原则：无论哪种语言，底层都映射到 PostgreSQL 的 sslmode 参数。配置方式不同，但语义一致。

自签名证书 vs 云提供商证书

常见报错与排查

错误 1：FATAL: no pg_hba.conf entry for host "192.168.1.100", user "myuser", database "mydb", SSL off

根因：服务器端的 pg_hba.conf 配置了 hostssl 规则，但客户端连接时未启用 SSL。

解决步骤：

1. 在服务器上编辑 pg_hba.conf，添加允许 SSL 连接的记录：

   hostssl mydb myuser 192.168.1.100/32 scram-sha-256
   

2. 重载配置：

   SQL
   SELECT pg_reload_conf();
   

   或命令行：

   BASH
   pg_ctl reload
   

3. 客户端连接时指定 sslmode=require 或更高模式。

错误 2：psql: error: connection to server failed: SSL is required

根因：客户端未启用 SSL，但服务器要求 SSL。

解决方案（任选其一）：

• 连接字符串方式：

  BASH
  psql "host=myhost.example.com dbname=mydb user=myuser sslmode=require"
  

• 环境变量方式：

  BASH
  export PGSSLMODE=require
  psql -h myhost.example.com -d mydb -U myuser
  

• 代码方式（Python 示例）：

  PYTHON
  import psycopg2
  conn = psycopg2.connect(
      host="myhost.example.com",
      dbname="mydb",
      user="myuser",
      password="mypass",
      sslmode="require"
  )
  

错误 3：SSL error: certificate verify failed

根因：客户端无法验证服务器证书的 CA 签名。

解决方案：

1. 使用云数据库（如 AWS RDS）：

   BASH
   wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
   psql "host=myinstance.xxxxxx.us-east-1.rds.amazonaws.com dbname=mydb user=myuser sslmode=verify-full sslrootcert=global-bundle.pem"
   

2. 使用自签名证书：

   • 将服务器 CA 证书（ca.crt）复制到客户端
   • 连接时指定：

     BASH
     psql "host=myhost.example.com dbname=mydb user=myuser sslmode=verify-ca sslrootcert=/path/to/ca.crt"
     

错误 4：sslmode value "require" invalid when SSL support is not compiled in

根因：PostgreSQL 客户端库未编译 SSL 支持。

解决方案：

• Ubuntu/Debian：

  BASH
  sudo apt-get install libpq-dev
  

• macOS：

  BASH
  brew install libpq
  

• Python：使用包含 SSL 支持的二进制包：

  BASH
  pip install psycopg2-binary
  

生产环境实践与注意事项

安全性警告

绝对不要在生产环境中使用以下配置：

• sslmode=require 而不验证证书
• Node.js 的 rejectUnauthorized: false
• Python 的 sslmode=require 而不指定 sslrootcert

这些配置虽然能解决“SSL is required”错误，但会暴露于中间人攻击。攻击者可以伪造服务器，窃取所有传输的数据。

证书管理

• 云提供商证书：定期检查证书有效期（AWS RDS 证书通常 5 年更新一次），提前下载新证书并更新客户端配置。
• 自签名证书：使用脚本自动化生成和分发，避免手动操作出错。示例脚本：

  BASH
  # 生成 CA 证书
  openssl req -new -x509 -days 365 -nodes -text -out ca.crt \
    -keyout ca.key -subj "/CN=MyCA"
  # 生成服务器证书
  openssl req -new -nodes -text -out server.csr \
    -keyout server.key -subj "/CN=myhost.example.com"
  openssl x509 -req -in server.csr -days 365 -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out server.crt
  

性能调优

SSL 加密会增加 CPU 开销和网络延迟。在高并发场景下：

• 使用连接池（如 PgBouncer）复用 SSL 连接，避免频繁握手
• 启用 SSL 会话复用：PostgreSQL 13+ 支持 ssl_cert_file 和 ssl_key_file 配置
• 监控 SSL 握手耗时：通过 pg_stat_ssl 视图查看

在 AI 客户端中的集成配置

如果你在 Claude Desktop 或 Cursor 等 AI 工具中配置 PostgreSQL MCP 服务，需要正确设置 SSL 参数。

Claude Desktop MCP 配置示例（claude_desktop_config.json）：

JSON
{
  "mcpServers": {
    "postgres-ssl-fix": {
      "command": "psql",
      "args": [
        "host=myhost.example.com",
        "dbname=mydb",
        "user=myuser",
        "sslmode=require"
      ]
    }
  }
}

Cursor MCP 配置示例（~/.cursor/mcp.json）：

JSON
{
  "mcpServers": {
    "postgres-ssl-fix": {
      "command": "psql",
      "args": [
        "host=myhost.example.com",
        "dbname=mydb",
        "user=myuser",
        "sslmode=verify-full",
        "sslrootcert=/path/to/global-bundle.pem"
      ]
    }
  }
}

常见问题 FAQ

Q: 在开发环境中，我可以使用 sslmode=require 而不验证证书吗？

A: 可以，但仅限开发/测试环境。sslmode=require 会加密连接，但不会验证服务器证书的真实性，因此容易受到中间人攻击。在开发环境中，如果使用自签名证书且不想配置 CA，可以临时使用 sslmode=require（CLI）或 rejectUnauthorized: false（Node.js）。但在生产环境中，必须使用 sslmode=verify-full 并配置正确的 CA 证书。

Q: 如何为 AWS RDS PostgreSQL 配置 SSL 连接？

A: 步骤如下：

1. 下载 AWS 全局 CA 捆绑包：

   BASH
   wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
   

2. 连接时指定 sslmode=verify-full 和 sslrootcert：

   BASH
   psql "host=myinstance.xxxxxx.us-east-1.rds.amazonaws.com dbname=mydb user=myuser sslmode=verify-full sslrootcert=global-bundle.pem"
   

3. 确保 RDS 实例的“强制 SSL”选项已启用（在 AWS 控制台 RDS 实例的“连接性”选项卡中设置）。

Q: 我使用自签名证书，但连接时出现“hostname mismatch”错误，如何解决？

A: 这个错误是因为 sslmode=verify-full 要求服务器证书的 CN（Common Name）或 SAN（Subject Alternative Name）与连接的主机名完全匹配。解决方法有两种：

1. 推荐：重新生成服务器证书，确保 CN 或 SAN 包含正确的主机名：

   BASH
   openssl req -new -nodes -text -out server.csr \
     -keyout server.key -subj "/CN=your-server-hostname"
   

2. 临时方案：降级使用 sslmode=verify-ca，它只验证 CA 证书而不验证主机名，但安全性略低。