CONFIGURATION PARAMETER连接和认证 / SSL

ssl_passphrase_command

设置获取用于解密私钥等 SSL 文件的口令时要调用的外部命令。

Command to obtain passphrases for SSL.

字符串重载生效引入 11 现存至 20 devel 0 次默认值变更

类型: 字符串string
上下文: 重载生效改配置文件后重载（pg_ctl reload / SIGHUP）即可生效
默认值: 空字符串原始值 ''
分类: 连接和认证 / SSL
引入版本: 11
状态: 现存

PostgreSQL 18.7 手册官方文档引入提交 8a3d942529

版本轨迹

相对 PostgreSQL 17 仅简述或分类有更新。

默认值变迁

空字符串 11 – 19

已记录的默认值在 PostgreSQL 11–19 之间未变。带单位的取值换算成了可读形式，原始的 boot_val 与单位写在悬浮提示里。

手册说明

PostgreSQL 18.7 手册 · 19.3 连接和认证本站手册官方原文

设置获取用于解密私钥等 SSL 文件的口令时要调用的外部命令。默认值为空，表示使用内置的提示机制。

该命令必须将口令输出到标准输出，并以退出码 0 结束。参数值中的 %p 会被替换为提示字符串。（要表示字面值 %，应写成 %%。）提示字符串可能包含空白，因此务必正确加引号。如果输出末尾有一个换行符，会将其去掉。

该命令不一定要提示用户输入口令，也可以从文件读取口令、从钥匙链获取口令等。用户应自行确保所选机制足够安全。

此参数只能在 postgresql.conf 文件中或服务器命令行上设置。

机制详解

ssl_passphrase_command 是 PostgreSQL 需要解密加密私钥等 SSL 文件时调用的外部助手。助手必须把口令写到标准输出并以状态零退出；PostgreSQL 会去掉输出末尾的一个换行。

配置命令中的 %p 会替换为可能包含空白的提示字符串，因此必须安全引用；%% 输出字面百分号。命令以 PostgreSQL 服务账号运行，其环境、路径、参数、输出与错误日志都不得泄漏秘密。

它属于 SIGHUP 上下文，但重载时能否替换加密私钥还取决于 ssl_passphrase_command_supports_reload。非交互 keychain/文件助手可支持重载；TTY 提示通常只适合受控启动，Windows 另有重载要求。

调优建议

按典型负载给出的取值思路，不是放之四海皆准的配方：实际取值要看数据量、并发度与硬件。

OLTP在线事务处理

使用绝对路径、最小化、非交互助手，并由受保护 keychain 或文件描述符提供秘密。测试精确标准输出、退出状态、%p 引用、超时/失败、启动、重载和故障节点可用性，且不得记录口令。
OLAP分析与批处理

分析节点使用相同助手与秘密源；负载类型不会改变私钥信任要求。安排证书轮换前测试无人值守重启。
小规格低配实例与开发机

优先使用最简单且可审计、能无人值守重启的助手。若保留 TTY 提示，应记录：除非安全启用 supports_reload，否则重载无法替换加密私钥。

常见问题

在标准输出中写入口令以外内容，或返回非零状态。
没有引用 %p，而替换后的提示可能含空白；或忘记字面百分号需要写成 %%。
通过命令参数、进程列表、环境变量、shell 跟踪、标准错误或服务器日志泄漏口令。
部署只在一个主库交互运行成功，却在无人值守重启、重载或故障转移时失败的助手。

演化历史

相邻两个大版本之间的差异，新的在前。版本号链到该版的快照。

PostgreSQL 18 ← 17 仅描述更新

补充说明 （无） An empty string means use the built-in prompting mechanism.
PostgreSQL 11 ← 10 新增此参数

PostgreSQL 11 起可用

逐版本快照

每个收录版本里的 7 项事实，与上一个存在的版本不同的格子带底色。版本号链到该版。

版本	默认值	单位	上下文	类型	最小值	最大值	枚举值
11	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
12	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
13	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
14	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
15	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
16	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
17	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
18	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
19	`空字符串`	`—`	`重载生效`	`字符串`	`—`	`—`	`—`
20	—	—	—	`字符串`	—	—	—

参考资料

同类参数

参数	类型	上下文	默认值	最近变更
Connections and Authentication 连接和认证 17 个 ↗
SSL 17
`ssl`	布尔	重载生效	`off`	101 次
启用 SSL 连接。				现存
`ssl_ca_file`	字符串	重载生效	`空字符串`	101 次
指定包含 SSL 服务器证书颁发机构（CA）的文件名。				现存
`ssl_cert_file`	字符串	重载生效	`server.crt`	101 次
指定包含 SSL 服务器证书的文件名。				现存
`ssl_ciphers`	字符串	重载生效	`HIGH:MEDIUM:+3DES:!aNULL`	103 次
指定允许用于 TLS 1.2 及更低版本连接的 SSL 密码套件列表；对于 TLS 1.3 连接，请参见 ssl_tls13_ciphers。				现存
`ssl_crl_dir`	字符串	重载生效	`空字符串`	—
指定包含 SSL 客户端证书吊销列表（CRL）的目录名称。				现存
`ssl_crl_file`	字符串	重载生效	`空字符串`	101 次
指定包含 SSL 客户端证书吊销列表（CRL）的文件名。				现存
`ssl_dh_params_file`	字符串	重载生效	`空字符串`	—
指定包含 Diffie-Hellman 参数的文件名，这些参数用于所谓临时 DH 系列的 SSL 密码套件。				现存
`ssl_ecdh_curve`	字符串	重载生效	`prime256v1`	101 次
指定在 ECDH 密钥交换中使用的曲线名称。				于 18 移除
`ssl_groups`	字符串	重载生效	`X25519:prime256v1`	—
指定用于 TLS 密钥交换的命名组。				现存
`ssl_key_file`	字符串	重载生效	`server.key`	101 次
指定包含 SSL 服务器私钥的文件名。				现存
`ssl_max_protocol_version`	枚举	重载生效	`空字符串`	—
设置要使用的最高 SSL/TLS 协议版本。				现存
`ssl_min_protocol_version`	枚举	重载生效	`TLSv1.2`	131 次
设置要使用的最低 SSL/TLS 协议版本。				现存
`ssl_passphrase_command`	字符串	重载生效	`空字符串`	—
设置获取用于解密私钥等 SSL 文件的口令时要调用的外部命令。				现存
`ssl_passphrase_command_supports_reload`	布尔	重载生效	`off`	—
此参数决定：配置重载期间，如果密钥文件需要口令，是否也调用 ssl_passphrase_command 设置的口令命令。				现存
`ssl_prefer_server_ciphers`	布尔	重载生效	`on`	101 次
指定是否使用服务器的 SSL 密码套件优先顺序，而非客户端的优先顺序。				现存
`ssl_sni`	布尔		—	—
启用 SSL 连接的 SNI 配置。				现存
`ssl_tls13_ciphers`	字符串	重载生效	`空字符串`	—
指定允许用于 TLS 版本 1.3 连接的密码套件列表。				现存

快速链接