企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

当 PostgreSQL 服务器配置了强制 SSL/TLS 加密策略时，直接用psql连接会立即被服务器拒绝并报错。本文基于 til 仓库中 force-ssl-when-making-a-psql-connection.md 的实战笔记，系统讲解通过sslmode=require强制建立加密连接的两种主流方式（连接字符串与命令行参数），并延伸到 SSL 模式取值、常见运维场景（RDS、Heroku、dump 恢复）以及 SSL 支持缺失时的排查思路。读完本文你将能独立解决 "FATAL: SSL/TLS required" 报错，并为任意远程 PostgreSQL 建立加密的 psql 会话。

问题场景：服务器要求 SSL，psql 却被拒之门外

现代 PostgreSQL 服务器（尤其是云托管实例）通常会在postgresql.conf中开启强制 SSL 策略（例如ssl = on配合pg_hba.conf中的hostssl规则）。此时如果直接以明文方式发起连接，服务器会立刻终止握手并返回：

psql: error: FATAL: SSL/TLS required

这一报错含义非常明确：服务器要求 SSL/TLS 加密，而当前连接没有携带加密协商参数。psql 默认的sslmode是prefer（优先加密但不强制），在服务器明确要求加密时，psql 需要显式声明sslmode=require才能完成连接。

解法核心：在连接参数中加入 sslmode=require

解决方式非常直接：在 psql 的连接参数中追加sslmode=require键值对，让客户端主动声明"本连接必须使用 SSL 加密"。该参数可通过两种途径传入——连接字符串（URI）或命令行参数标志。

方式一：连接字符串（URI）追加查询参数

使用形如postgres://的完整连接字符串时，直接在末尾追加?sslmode=require查询参数即可：

$ psql postgres://username:password@host.com/dbname?sslmode=require

参数拆解：

• postgres://：PostgreSQL 的标准 URI 协议前缀；
• username:password：数据库用户名与密码（也可省略密码，改用PGPASSWORD环境变量注入，避免密码出现在 shell 历史中）；
• host.com：数据库主机地址；
• dbname：目标数据库名；
• ?sslmode=require：查询参数形式的 SSL 模式声明，这是强制加密的关键。

URI 形式也适用于其他 libpq 系工具，例如pg_dump、pg_restore同样可以复用postgres://...?sslmode=require形式的连接串。

方式二：命令行参数标志，使用 --set 传递

如果习惯使用-h、-U等独立连接标志，可以借助--set（短写-c）向 psql 注入 libpq 参数：

$ PGPASSWORD=password psql \ --set=sslmode=require \ -h host.com \ -U username \ dbname

参数拆解：

• PGPASSWORD=password：以环境变量方式提供密码，避免在命令行明文暴露；
• --set=sslmode=require：通过--set设置 libpq 连接参数sslmode为require，等价于连接串中的?sslmode=require；
• -h host.com：指定主机；
• -U username：指定用户；
• 末尾dbname：目标数据库名。

psql 在解析连接时会把--set传入的键值对并入连接参数集合，与 URI 查询参数遵循同一套 libpq 参数语义，因此两种写法效果等价，可按使用习惯任选其一。

纵深扩展：sslmode 的取值与加密强度

sslmode是 libpq 连接参数，除require外还有多个取值，理解它们有助于在不同安全需求下选择正确档位：

当服务器策略是"必须 SSL"时，最低要求是require；若需要抵御中间人攻击、确认服务器身份，应升级到verify-ca或verify-full（后者还要求证书中的主机名与连接目标一致，云数据库通常需要配合 CA 证书文件使用）。

实战场景：为远程 PostgreSQL 强制加密连接

该技巧在连接各类远程 PostgreSQL 时几乎必然用到，仓库中的其他笔记提供了若干可直接套用的上下文：

连接 AWS RDS PostgreSQL

仓库笔记 devops/connect-to-an-rds-postgresql-database.md 展示了通过安全组放行 5432 端口后用psql连接 RDS 实例的方式。由于 RDS 默认启用 SSL，将原文命令与sslmode=require结合即可得到加密版本：

$ psql "postgres://rdsusername@my-rds-endpoint.cbazqrhkmyo.us-east-1.rds.amazonaws.com:5432/postgres?sslmode=require"

其中--port 5432已内联到 URI 的:5432段，--user rdsusername对应 URI 中的用户名，数据库postgres对应路径段。

连接 Heroku 托管数据库

Heroku 的 PostgreSQL 也默认要求加密连接。仓库笔记 heroku/connect-to-a-database-by-color.md 使用heroku pg:psql --app my-app连接默认库，底层同样会携带加密参数；当通过heroku config:get DATABASE_URL拿到原始连接串后，可直接拼接?sslmode=require用 psql 手动连接。批量执行 SQL 时也可参考 heroku/run-sql-against-remote-postgres-database.md 的重定向思路，对加密连接同样成立。

恢复 dump 时强制加密

在 postgres/dump-all-databases-to-a-sql-file.md 中，pg_dumpall导出的 SQL 通过以下命令恢复：

$ psql -f postgres_13_1_cluster_dump.sql postgres

若目标服务器要求 SSL，将恢复命令改造为：

$ psql "postgres://username:password@host.com/postgres?sslmode=require" -f postgres_13_1_cluster_dump.sql

这样既保留了-f执行脚本的能力，又满足了服务器的加密要求。

常见问题排查：SSL support 未编译进客户端

如果已经加上sslmode=require，却仍出现类似以下提示，说明当前安装的 PostgreSQL 客户端在编译时未启用 SSL 支持：

psql: error: ... SSL support not compiled in

这种情况通常发生在通过asdf、Homebrew 等包管理器安装的 PostgreSQL 上——部分安装路径默认不链接 OpenSSL。原文档给出的解决思路是重新安装带 SSL 支持的 PostgreSQL（仓库笔记 postgres/dump-all-databases-to-a-sql-file.md 中也有提及）。在重装前，可用以下命令快速确认当前客户端是否具备 SSL 能力：

$ psql --version # 查看版本 $ pg_config --configure # 查看编译配置中是否包含 --with-openssl

若pg_config --configure的输出中没有--with-openssl，即可确认客户端缺少 SSL 支持，需要以带 OpenSSL 的方式重新编译安装（例如 asdf 安装时启用 openssl 插件、brew 安装postgresql@15时选择含 SSL 的构建），重装后sslmode=require即可正常工作。

小结

• 服务器报FATAL: SSL/TLS required时，在连接参数中追加sslmode=require即可强制建立加密连接；
• 两种等价写法：URI 追加?sslmode=require，或使用--set=sslmode=require配合-h/-U/PGPASSWORD；
• 生产环境建议进一步使用verify-full以校验服务器身份，抵御中间人攻击；
• 若提示 SSL support 未编译进客户端，需重新安装带 OpenSSL 支持的 PostgreSQL；
• 该技巧可无缝套用于 RDS、Heroku 等强制加密的托管数据库，以及pg_dumpall/pg_restore等 libpq 系工具的恢复流程。

• 文档
• 教程
• 知识库