这是本节的多页打印视图。 .

连接与认证

Connections and Authentication 分类下的 45 个 PostgreSQL 核心配置参数档案。

1: authentication_timeout
2: bonjour
3: bonjour_name
4: client_connection_check_interval
5: db_user_namespace
6: gss_accept_delegation
7: krb_caseins_users
8: krb_server_keyfile
9: krb_srvname
10: listen_addresses
11: max_connections
12: md5_password_warnings
13: oauth_validator_libraries
14: password_encryption
15: password_expiration_warning_threshold
16: port
17: reserved_connections
18: scram_iterations
19: ssl
20: ssl_ca_file
21: ssl_cert_file
22: ssl_ciphers
23: ssl_crl_dir
24: ssl_crl_file
25: ssl_dh_params_file
26: ssl_ecdh_curve
27: ssl_groups
28: ssl_key_file
29: ssl_max_protocol_version
30: ssl_min_protocol_version
31: ssl_passphrase_command
32: ssl_passphrase_command_supports_reload
33: ssl_prefer_server_ciphers
34: ssl_renegotiation_limit
35: ssl_sni
36: ssl_tls13_ciphers
37: superuser_reserved_connections
38: tcp_keepalives_count
39: tcp_keepalives_idle
40: tcp_keepalives_interval
41: tcp_user_timeout
42: unix_socket_directories
43: unix_socket_directory
44: unix_socket_group
45: unix_socket_permissions

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

1 - authentication_timeout

authentication_timeout 定义完成客户端认证所允许的最长时间。

说明

Fact — 官方简述译文：设置完成客户端认证所允许的最长时间。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值s: 原始单位
范围 , 值1 – 600: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值60: 1 min

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`60`	`s`	1 min

机制详解

authentication_timeout：设置完成客户端认证所允许的最长时间。计时覆盖普通后端会话建立前的认证交互，用于限制停滞或恶意握手长期占用连接资源。

authentication_timeout 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按认证架构与安全策略设置 authentication_timeout，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP	分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格	优先保留 authentication_timeout 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 authentication_timeout 后没有重新加载配置，也没有核对有效值与后续行为。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
没有回滚计划及客户端或运维兼容测试，就全局修改 authentication_timeout。

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval

参考资料

2 - bonjour

bonjour 是控制是否启用通过 Bonjour 广播服务器的 PostgreSQL 开关。

说明

Fact — 官方简述译文：启用通过 Bonjour 广播服务器。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`off`	—	off

机制详解

bonjour：启用通过 Bonjour 广播服务器。它只在具备 Bonjour 支持的平台与构建上通过 mDNS 发布可发现服务；不会自行打开监听地址，也不会修改 pg_hba.conf。

bonjour 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Bonjour 广播依赖平台支持，只把监听器作为元数据发布；实际可达性与信任仍由 listen_addresses、port、pg_hba.conf、TLS 和防火墙决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有客户端明确在可信本地网络使用 Bonjour/mDNS 时才启用 bonjour。它只是发现元数据，不能替代认证或高可用服务注册。
OLAP	分析负载形态不构成改变 bonjour 的理由；应采用同一套经评审发现策略与稳定服务身份。
小规格	除非明确需要本地零配置发现，否则保持 bonjour 关闭或为空；它不会提升数据库容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重新加载或 SET 激活 bonjour，而它实际需要受控重启服务器。
把 mDNS 广播当作访问控制、认证或高可用机制。
在不受信广播域发布意外的服务名称或端点。
没有回滚计划及客户端或运维兼容测试，就全局修改 bonjour。

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

3 - bonjour_name

bonjour_name 定义 Bonjour 服务名称。

说明

Fact — 官方简述译文：设置 Bonjour 服务名称。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`""`	—	empty string

机制详解

bonjour_name：设置 Bonjour 服务名称。空值会从计算机名派生广播服务名，而且只有启用 Bonjour 广播时该参数才有作用。

bonjour_name 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Bonjour 广播依赖平台支持，只把监听器作为元数据发布；实际可达性与信任仍由 listen_addresses、port、pg_hba.conf、TLS 和防火墙决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有客户端明确在可信本地网络使用 Bonjour/mDNS 时才启用 bonjour_name。它只是发现元数据，不能替代认证或高可用服务注册。
OLAP	分析负载形态不构成改变 bonjour_name 的理由；应采用同一套经评审发现策略与稳定服务身份。
小规格	除非明确需要本地零配置发现，否则保持 bonjour_name 关闭或为空；它不会提升数据库容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重新加载或 SET 激活 bonjour_name，而它实际需要受控重启服务器。
把 mDNS 广播当作访问控制、认证或高可用机制。
在不受信广播域发布意外的服务名称或端点。
没有回滚计划及客户端或运维兼容测试，就全局修改 bonjour_name。

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

4 - client_connection_check_interval

client_connection_check_interval 定义查询运行期间检查客户端断连的时间间隔。

说明

Fact — 官方简述译文：设置查询运行期间检查客户端断连的时间间隔。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值ms: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / TCP Settings: 上游分类
最后 boot 值 , 值0: 0 ms

生命周期

Fact	值
首次观测	PG14
在档版本	PG14–19 Beta 3
移除版本	否
引入提交	`c30f54ad732c` — Detect POLLHUP/POLLRDHUP while running queries.
提交日期	2021-04-03
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG14–19 Beta 3	`0`	`ms`	0 ms

机制详解

client_connection_check_interval：设置查询运行期间检查客户端断连的时间间隔。非零间隔让长查询在下一次套接字写入前发现客户端已断开；检查是否有效取决于操作系统支持。

client_connection_check_interval 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有客户端丢失后放弃工作能显著节省容量且平台支持检查时，才为 client_connection_check_interval 使用非零值；应测量所选间隔的轮询开销。
OLAP	长分析查询可从周期断连检测获益，避免客户端消失后继续运行；该间隔并不限制健康查询的执行时长。
小规格	除非观察到孤儿长查询，否则保持零；启用时选择既能发现浪费又不过度检查活动查询的间隔。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

只在一个会话中修改 client_connection_check_interval，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
忘记零通常表示禁用超时或把行为交给操作系统。
设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
没有回滚计划及客户端或运维兼容测试，就全局修改 client_connection_check_interval。

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · authentication_timeout

参考资料

5 - db_user_namespace

db_user_namespace 是控制是否启用按数据库划分的用户名空间的 PostgreSQL 开关。

说明

Fact — 官方简述译文：启用按数据库划分的用户名空间。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–16
移除版本	PG17
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–16	`off`	—	off

机制详解

db_user_namespace：启用按数据库划分的用户名空间。这一遗留功能在内部用 user@database 表示用户，并已于 PostgreSQL 17 移除；它不是现代的租户隔离机制。

db_user_namespace 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	不应采用或调优 db_user_namespace：它是遗留兼容功能，并已从 PostgreSQL 17 起移除。应迁移到普通集群级角色与显式授权。
OLAP	不要基于 db_user_namespace 构建分析租户隔离；应按边界要求使用角色、模式、数据库与行级安全。
小规格	旧版本中保持 db_user_namespace 关闭，并在升级前移除依赖；它没有小节点优化价值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG16 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–16 未修改；OLAP: PG9.0–16 未修改；CRIT: PG9.0–16 未修改；TINY: PG9.0–16 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 db_user_namespace 后没有重新加载配置，也没有核对有效值与后续行为。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
没有回滚计划及客户端或运维兼容测试，就全局修改 db_user_namespace。

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

6 - gss_accept_delegation

gss_accept_delegation 定义是否接受客户端的 GSSAPI 凭据委派。

说明

Fact — 官方简述译文：设置是否接受客户端的 GSSAPI 凭据委派。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG16
在档版本	PG16–19 Beta 3
移除版本	否
引入提交	`9c0a0e2ed92a` — rename “gss_accept_deleg” to “gss_accept_delegation”.
提交日期	2023-05-20
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG16–19 Beta 3	`off`	—	off

机制详解

gss_accept_delegation：设置是否接受客户端的 GSSAPI 凭据委派。接受委派凭据后，服务器端代码可代表客户端的 GSS 身份行动，因此信任范围超出普通认证。

gss_accept_delegation 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按认证架构与安全策略设置 gss_accept_delegation，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP	分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格	优先保留 gss_accept_delegation 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 gss_accept_delegation 后没有重新加载配置，也没有核对有效值与后续行为。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
没有回滚计划及客户端或运维兼容测试，就全局修改 gss_accept_delegation。

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

7 - krb_caseins_users

krb_caseins_users 定义 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。

说明

Fact — 官方简述译文：设置 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`off`	—	off

机制详解

krb_caseins_users：设置 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。它影响已认证 Kerberos/GSS 名称与数据库角色名的比较；大小写折叠可能合并现有映射中原本不同的身份。

krb_caseins_users 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按认证架构与安全策略设置 krb_caseins_users，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP	分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格	优先保留 krb_caseins_users 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 krb_caseins_users 后没有重新加载配置，也没有核对有效值与后续行为。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
没有回滚计划及客户端或运维兼容测试，就全局修改 krb_caseins_users。

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

8 - krb_server_keyfile

krb_server_keyfile 定义 Kerberos 服务器密钥文件的位置。

说明

Fact — 官方简述译文：设置 Kerberos 服务器密钥文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值FILE:/etc/postgresql-common/krb5.keytab: FILE:/etc/postgresql-common/krb5.keytab

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0	`""`	—	empty string
PG9.1–19 Beta 3	`FILE:/etc/postgresql-common/krb5.keytab`	—	FILE:/etc/postgresql-common/krb5.keytab

机制详解

krb_server_keyfile：设置 Kerberos 服务器密钥文件的位置。该文件包含 GSSAPI 认证使用的服务密钥；操作系统所有权与 keytab 轮换也是有效配置的一部分。

krb_server_keyfile 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按认证架构与安全策略设置 krb_server_keyfile，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP	分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格	优先保留 krb_server_keyfile 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 krb_server_keyfile 后没有重新加载配置，也没有核对有效值与后续行为。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
没有回滚计划及客户端或运维兼容测试，就全局修改 krb_server_keyfile。

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries

参考资料

9 - krb_srvname

krb_srvname：设置 Kerberos 服务名称。实测在档范围为 PG9.0–9.3；最后在档的 PG9.3 启动默认值为 postgres，context 为 sighup。它在 PG9.4 被移除。

说明

Fact — 官方简述译文：设置 Kerberos 服务名称。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Security and Authentication: 上游分类
最后 boot 值 , 值postgres: postgres

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–9.3
移除版本	PG9.4
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–9.3	`postgres`	—	postgres

机制详解

krb_srvname：设置 Kerberos 服务名称。重新加载配置即可让服务器采用新值，无需完整重启。本站在 PG9.0–9.3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个历史认证参数选择服务器使用的 Kerberos 服务主体名称，PG9.3 后退出。现代部署应从 pg_hba.conf、krb_server_keyfile 指定的 keytab、DNS 与客户端服务名选项共同设计 GSS/Kerberos，而不是继续携带这个旧 GUC。

应与 krb_server_keyfile、hba_file、ssl、password_encryption 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP	升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格	记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.3 未修改；OLAP: PG9.0–9.3 未修改；CRIT: PG9.0–9.3 未修改；TINY: PG9.0–9.3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

把 krb_srvname 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

krb_server_keyfile · hba_file · ssl · password_encryption

参考资料

10 - listen_addresses

listen_addresses 定义服务器监听的主机名或 IP 地址。

说明

Fact — 官方简述译文：设置服务器监听的主机名或 IP 地址。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值localhost: localhost

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`localhost`	—	localhost

机制详解

listen_addresses：设置服务器监听的主机名或 IP 地址。服务器启动时绑定所列接口；是否可达仍取决于 port、pg_hba.conf、主机防火墙与网络路由。

listen_addresses 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

监听端点在启动时由 listen_addresses 与 port 组合，而 pg_hba.conf、TLS、防火墙、路由与服务发现决定哪些客户端能够使用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按服务拓扑设置 listen_addresses，只暴露必要接口或端口，并联合验证连接池、健康检查、pg_hba.conf、防火墙、故障转移与重启顺序。
OLAP	需要隔离时使用明确的分析端点或网络，但在各故障转移目标间保持连接信息一致。
小规格	除非需要远程访问，否则优先仅本地暴露；修改 listen_addresses 并重启前保留经过测试的管理路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重新加载或 SET 激活 listen_addresses，而它实际需要受控重启服务器。
误以为绑定地址或端口会授予访问权限；pg_hba.conf 与操作系统或网络控制仍然生效。
修改仅启动时生效的端点，却未同步服务发现、健康检查、防火墙、客户端与管理恢复路径。
没有回滚计划及客户端或运维兼容测试，就全局修改 listen_addresses。

port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

11 - max_connections

PostgreSQL 客户端并发连接的启动时上限，也是多项共享资源的尺寸输入。

说明

Fact — 官方简述译文：设置数据库并发连接的最大数量。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值1 – 262143: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值100: 100

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`100`	—	100

机制详解

max_connections 限制数据库服务器的并发连接数，只能在服务器启动时修改。PostgreSQL 会直接按该值确定部分资源规模，因此即使连接槽未全部使用，调高上限也会增加包括共享内存在内的分配。

reserved_connections 与 superuser_reserved_connections 从同一个总上限中划出应急或特权容量，因此普通应用通常不能占满所有配置槽位。

备用库的取值必须不低于主库。连接池可以把大量客户端连接与较少、受控的 PostgreSQL 后端连接解耦。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	面对大量客户端时优先使用事务池，按峰值活跃数据库工作量，加上监控、维护和故障转移余量来确定后端数；不要默认把每个客户端连接映射为一个服务器槽位。
OLAP	分析会话通常更少但更重，应把后端上限控制在能约束 work_mem 与并行工作进程总需求的范围，并为 ETL 与管理预留明确容量。
小规格	使用较低上限配合连接池并保留应急槽位。验证启动所需共享内存，不要通过不断提高上限掩盖连接泄漏。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`500`	不同于 boot 值	`{{ pg_max_connections }}`
OLAP	`500`	不同于 boot 值	`{{ pg_max_connections }}`
CRIT	`500`	不同于 boot 值	`{{ pg_max_connections }}`
TINY	`250`	不同于 boot 值	`{{ pg_max_connections }}`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 500 (dcs)；OLAP: PG9.0–19 Beta 3 = 500 (dcs)；CRIT: PG9.0–19 Beta 3 = 500 (dcs)；TINY: PG9.0–19 Beta 3 = 250 (dcs)。建议（待人工复核）——编辑推断：模板在连接池后提供较宽松的兼容性上限，并为小节点降低上限，但实际活跃后端数与内存边界仍需按负载复核。

常见坑

修改后没有安排重启，也没有保证备用库取值至少与主库相同。
忽略更高连接上限带来的共享内存与每后端开销。
计算应用容量时忘记预留连接与超级用户预留槽。
同时使用很高的连接上限和宽松的单操作内存，却认为二者不会相乘。

reserved_connections · superuser_reserved_connections · work_mem · max_worker_processes · max_prepared_transactions · max_wal_senders

参考资料

12 - md5_password_warnings

md5_password_warnings 是控制是否启用关于 MD5 密码的弃用警告的 PostgreSQL 开关。

说明

Fact — 官方简述译文：启用关于 MD5 密码的弃用警告。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值on: on

生命周期

Fact	值
首次观测	PG18
在档版本	PG18–19 Beta 3
移除版本	否
引入提交	`db6a4a985bc0` — Deprecate MD5 passwords.
提交日期	2024-12-02
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG18–19 Beta 3	`on`	—	on

机制详解

md5_password_warnings 控制 PostgreSQL 18 的弃用 WARNING：只有 CREATE ROLE 或 ALTER ROLE 设置 MD5 密码密文时才产生。它不会报告使用既有 MD5 密文进行的认证，因此不能作为活跃 MD5 客户端或角色的完整清单。

它属于 USER 上下文，获授权角色可在当前会话中修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。只有会话既执行设置密码语句又启用本参数时，才可能产生警告。

password_encryption 控制以明文设置密码时生成的格式，而既有 pg_authid 密文只有重置密码后才会改变。因此迁移除警告外，还需要受保护的密文类型清点、客户端兼容测试与凭据轮换。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	保持 md5_password_warnings 为 on，但每条警告只能证明某个设置密码语句创建或提交了 MD5 密文。另行清点既有密文类型，并在强制仅 SCRAM 访问前测试所有认证路径。
OLAP	分析角色采用同一规则：遗留驱动可能继续用旧 MD5 密文认证而不产生本警告，因此必须显式测试并轮换这些凭据。
小规格	保持警告启用，其开销可忽略。不要把没有警告误当成不存在 MD5 密文或仅支持 MD5 客户端的证据。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

误以为使用既有 MD5 密文认证时会告警；它只在 CREATE ROLE 或 ALTER ROLE 设置 MD5 密文时触发。
把没有警告当成集群中不存在 MD5 密文或仅支持 MD5 客户端的证明。
在创建或轮换角色的部署会话中关闭警告，从而隐藏新 MD5 密文的产生。
修改 password_encryption 却不轮换既有角色密码，使其存储密文格式保持不变。

password_encryption · scram_iterations · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

13 - oauth_validator_libraries

oauth_validator_libraries 声明可用于验证 OAuth 2.0 Bearer Token 的库。

说明

Fact — 官方简述译文：列出可用于验证 OAuth 2.0 Bearer Token 的库。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG18
在档版本	PG18–19 Beta 3
移除版本	否
引入提交	`b3f0be788afc` — Add support for OAUTHBEARER SASL mechanism
提交日期	2025-02-20
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG18–19 Beta 3	`""`	—	empty string

机制详解

oauth_validator_libraries 列出可验证 OAuth 2.0 Bearer Token 的受信服务器模块。PostgreSQL 18 不附带任何验证器实现，默认空值会拒绝所有 OAuth 连接；可用部署必须安装并列出至少一个兼容模块。

列表只有一个库时，PostgreSQL 默认将其用于 OAuth 连接；存在多个库时，pg_hba.conf 中每条 oauth 记录都必须从列表中显式指定 validator。该参数属于 SIGHUP 上下文，更改允许列表需要重新加载配置，并影响后续认证尝试。

验证器在服务器认证路径内执行受信本地代码。其令牌颁发者、受众、声明到角色映射、失败行为、依赖、软件包版本，以及在所有主库和故障转移节点上的可用性，都必须与 pg_hba.conf 和身份提供方一致。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	先安装一个经过评审的验证器，在所有故障转移目标固定其软件包与版本，并在启用 oauth HBA 记录前测试颁发者、受众、过期、吊销、角色映射、畸形令牌和身份提供方故障。
OLAP	分析访问采用同一验证器信任策略。若需要不同颁发者或声明映射，应显式列出经评审模块，并在每条匹配 HBA 记录中选择预期 validator。
小规格	空值会安全地禁用 OAuth，但不是可工作的 OAuth 配置。小节点优先使用一个充分测试的验证器，并预算其令牌验证延迟，而不是削弱检查。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

列表为空时创建 oauth HBA 规则；PostgreSQL 会拒绝所有 OAuth 连接。
误以为 PostgreSQL 提供内置验证器实现。
列出多个库，却未在每条 oauth HBA 记录中选择 validator。
只在主库安装验证器而未覆盖故障转移目标，或信任未经颁发者、受众与角色映射评审的本地代码。

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · krb_server_keyfile

参考资料

14 - password_encryption

password_encryption 是 PostgreSQL 中用于选择生成密码密文时使用的算法的参数。

说明

Fact — 官方简述译文：选择生成密码密文时使用的算法。

身份

类型 , 值enum: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值md5, scram-sha-256: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值scram-sha-256: scram-sha-256

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–9.6	`on`	—	on
PG10–13	`md5`	—	md5
PG14–19 Beta 3	`scram-sha-256`	—	scram-sha-256

机制详解

password_encryption：选择生成密码密文时使用的算法。它影响 CREATE ROLE、ALTER ROLE 等设置密码命令新生成的密文；既有密文不会自动重新哈希。

password_encryption 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按认证架构与安全策略设置 password_encryption，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP	分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格	优先保留 password_encryption 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`scram-sha-256`	等于 boot 值	`{{ pg_pwd_enc\|default('scram-sha-256') }}`
OLAP	`scram-sha-256`	等于 boot 值	`{{ pg_pwd_enc\|default('scram-sha-256') }}`
CRIT	`scram-sha-256`	等于 boot 值	`{{ pg_pwd_enc\|default('scram-sha-256') }}`
TINY	`scram-sha-256`	等于 boot 值	`{{ pg_pwd_enc\|default('scram-sha-256') }}`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；OLAP: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；CRIT: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；TINY: PG9.0–19 Beta 3 = scram-sha-256 (dcs)。建议（待人工复核）——编辑推断：SCRAM-SHA-256 在各模板与受支持 PostgreSQL 版本上建立一致的现代密码密文基线。

常见坑

只在一个会话中修改 password_encryption，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
更改算法后误以为既有角色密文会自动转换。

scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

15 - password_expiration_warning_threshold

password_expiration_warning_threshold：设置密码到期告警的提前时间阈值。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 7 d，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。

说明

Fact — 官方简述译文：设置密码到期告警的提前时间阈值。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值s: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值604800: 7 d

生命周期

Fact	值
首次观测	PG19 Beta 3
在档版本	PG19 Beta 3
移除版本	否
引入提交	`1d92e0c2cc47` — Add password expiration warnings.
提交日期	2026-02-11
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG19 Beta 3	`604800`	`s`	7 d

机制详解

password_expiration_warning_threshold：设置密码到期告警的提前时间阈值。重新加载配置即可让服务器采用新值，无需完整重启。本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

密码认证成功后，如果带 VALID UNTIL 的角色剩余有效期小于该区间，PostgreSQL 会发出警告。0 禁用告警；默认七天窗口只负责提醒，不会创建、轮换或延长凭据，使用非密码认证也不会让密码生命周期自动化。

应与 password_encryption、authentication_timeout、md5_password_warnings、hba_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP	批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格	优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

把 password_expiration_warning_threshold 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

password_encryption · authentication_timeout · md5_password_warnings · hba_file

参考资料

16 - port

port 定义服务器监听的 TCP 端口。

说明

Fact — 官方简述译文：设置服务器监听的 TCP 端口。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值1 – 65535: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值5432: 5432

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`5432`	—	5432

机制详解

port：设置服务器监听的 TCP 端口。所有 TCP 监听地址共用一个端口，它会进入客户端连接串、服务发现、防火墙规则与健康检查。

port 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

监听端点在启动时由 listen_addresses 与 port 组合，而 pg_hba.conf、TLS、防火墙、路由与服务发现决定哪些客户端能够使用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按服务拓扑设置 port，只暴露必要接口或端口，并联合验证连接池、健康检查、pg_hba.conf、防火墙、故障转移与重启顺序。
OLAP	需要隔离时使用明确的分析端点或网络，但在各故障转移目标间保持连接信息一致。
小规格	除非需要远程访问，否则优先仅本地暴露；修改 port 并重启前保留经过测试的管理路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重新加载或 SET 激活 port，而它实际需要受控重启服务器。
误以为绑定地址或端口会授予访问权限；pg_hba.conf 与操作系统或网络控制仍然生效。
修改仅启动时生效的端点，却未同步服务发现、健康检查、防火墙、客户端与管理恢复路径。
没有回滚计划及客户端或运维兼容测试，就全局修改 port。

listen_addresses · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

17 - reserved_connections

reserved_connections 定义为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。

说明

Fact — 官方简述译文：设置为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值0 – 262143: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值0: 0

生命周期

Fact	值
首次观测	PG16
在档版本	PG16–19 Beta 3
移除版本	否
引入提交	`6e2775e4d4e4` — Add new GUC reserved_connections.
提交日期	2023-01-20
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG16–19 Beta 3	`0`	—	0

机制详解

reserved_connections：设置为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。这些槽位只向获授 pg_use_reserved_connections 的角色开放，位于普通容量之上、超级用户专用预留之下。

reserved_connections 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

reserved_connections 与 superuser_reserved_connections 从 max_connections 中划出特权层；连接池、监控、复制、维护与故障转移必须共同纳入同一后端总预算。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	在 max_connections 总量内，按独立应急主体数量、连接池行为与故障转移操作确定 reserved_connections；测试普通连接饱和后管理入口仍可用。
OLAP	为重型分析会话之外的控制、监控与取消预留足够槽位，但不要让预留吞噬本就较小后端池的过高比例。
小规格	让 reserved_connections 相对 max_connections 保持适度，同时至少保留一条经过测试的应急路径；饱和时预留槽不会供普通客户端使用。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重新加载或 SET 激活 reserved_connections，而它实际需要受控重启服务器。
把预留槽计算在 max_connections 之外，而所有层级实际共享同一总上限。
应急响应预留过少，或预留过多以致饱和时普通应用容量骤降。
规划普通、预留与超级用户预留槽时，没有确保总量纳入 max_connections。

listen_addresses · port · max_connections · superuser_reserved_connections · unix_socket_directories

参考资料

18 - scram_iterations

scram_iterations 定义生成 SCRAM 密文时使用的迭代次数。

说明

Fact — 官方简述译文：设置生成 SCRAM 密文时使用的迭代次数。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值—: 原始单位
范围 , 值1 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Authentication: 上游分类
最后 boot 值 , 值4096: 4096

生命周期

Fact	值
首次观测	PG16
在档版本	PG16–19 Beta 3
移除版本	否
引入提交	`b577743000cd` — Make SCRAM iteration count configurable
提交日期	2023-03-27
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG16–19 Beta 3	`4096`	—	4096

机制详解

scram_iterations 会写入每个新生成的 SCRAM-SHA-256 密文。提高它会增加离线猜测成本，也会增加正常设置密码与认证工作；既有密文会保留创建时的迭代次数，直至重置密码。

它属于 USER 上下文，因此执行 CREATE ROLE 或 ALTER ROLE 的会话决定写入新密文的次数。即使 postgresql.conf 只有一个值，角色、数据库或应用级覆盖也可能造成多种次数并存。

PostgreSQL 警告：当角色存储次数不同于服务器配置值时，未认证观察者可能通过响应行为差异推断角色存在。因此改变次数需要统一会话策略并轮换所有 SCRAM 密文，而不只是修改 GUC。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	通过安全与认证延迟压测选择唯一次数，在所有密码管理会话中强制使用，并轮换全部角色密码使存储密文收敛。提高前应压测重连风暴与故障转移。
OLAP	分析角色使用相同次数；负载类型不是暴露不同密文次数的理由。安排凭据轮换，避免长期服务账号保留旧次数。
小规格	除非测试证明需要改变，否则保留上游次数。小服务器可通过连接池降低连接抖动，但仍必须让所有新密文使用一致次数。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

修改 GUC 却不重置既有密码；其密文仍保留旧次数。
允许角色或数据库会话默认值生成不同于 postgresql.conf 的密文次数，从而形成角色存在性侧信道。
提高次数却未压测认证风暴、故障转移、连接池重连与密码轮换作业。
误以为更高次数能修复弱密码或弥补已泄漏密文材料。

password_encryption · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

19 - ssl

ssl 是控制是否启用 SSL/TLS 连接的 PostgreSQL 开关。

说明

Fact — 官方简述译文：启用 SSL/TLS 连接。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`off`	—	off

机制详解

ssl：启用 SSL/TLS 连接。开启后，在证书与私钥有效时提供 TLS 监听能力；真正要求特定客户端使用 TLS 的是 pg_hba.conf hostssl 规则。

ssl 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`on`	不同于 boot 值	`'on'`
OLAP	`on`	不同于 boot 值	`'on'`
CRIT	`on`	不同于 boot 值	`'on'`
TINY	`on`	不同于 boot 值	`'on'`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。建议（待人工复核）——编辑推断：所有模板启用 TLS，使基于证书的加密传输成为统一基线；策略要求处仍需由 pg_hba.conf 强制使用。

常见坑

编辑 ssl 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl。

ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

20 - ssl_ca_file

ssl_ca_file 定义 SSL 证书颁发机构文件的位置。

说明

Fact — 官方简述译文：设置 SSL 证书颁发机构文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG9.2
在档版本	PG9.2–19 Beta 3
移除版本	否
引入提交	`a445cb92ef5b` — Add parameters for controlling locations of server-side SSL files
提交日期	2012-02-22
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.2–19 Beta 3	`""`	—	empty string

机制详解

ssl_ca_file：设置 SSL 证书颁发机构文件的位置。PEM CA 包定义客户端证书验证的信任根，以及 TLS 协商期间发送的可接受颁发机构列表。

ssl_ca_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有经评审且用于验证客户端证书的 CA 包才写入 ssl_ca_file。CA 轮换期间规划新旧信任根重叠，限制文件写权限，并在重载后测试每条 cert/clientcert HBA 路径。
OLAP	除非分析访问属于刻意分离的 PKI 域，否则使用相同信任根。不要为解决客户端部署问题而扩大 CA 包。
小规格	不使用客户端证书验证时保持空值。启用后让 CA 包尽量精简，监控到期，并在故障转移节点保持一致。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`/pg/cert/ca.crt`	不同于 boot 值	`'/pg/cert/ca.crt'`
OLAP	`/pg/cert/ca.crt`	不同于 boot 值	`'/pg/cert/ca.crt'`
CRIT	`/pg/cert/ca.crt`	不同于 boot 值	`'/pg/cert/ca.crt'`
TINY	`/pg/cert/ca.crt`	不同于 boot 值	`'/pg/cert/ca.crt'`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)。建议（待人工复核）——编辑推断：统一托管 CA 路径让各模板的信任材料保持一致，并支持可重复证书部署。

常见坑

编辑 ssl_ca_file 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_ca_file。

ssl · ssl_cert_file · ssl_key_file · ssl_crl_file · ssl_min_protocol_version

参考资料

21 - ssl_cert_file

ssl_cert_file 定义 SSL 服务器证书文件的位置。

说明

Fact — 官方简述译文：设置 SSL 服务器证书文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值server.crt: server.crt

生命周期

Fact	值
首次观测	PG9.2
在档版本	PG9.2–19 Beta 3
移除版本	否
引入提交	`a445cb92ef5b` — Add parameters for controlling locations of server-side SSL files
提交日期	2012-02-22
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.2–19 Beta 3	`server.crt`	—	server.crt

机制详解

ssl_cert_file：设置 SSL 服务器证书文件的位置。PEM 文件提供服务器叶证书，也可包含向客户端呈现完整链所需的中间证书。

ssl_cert_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	部署的证书应在密钥用途、SAN、有效期和证书链上匹配所有对外数据库端点。删除旧证书前，测试重载和新的客户端握手。
OLAP	分析端点需要相同身份保证；若使用独立名称，应签发正确 SAN，而不是复用名称不匹配的证书。
小规格	自动化续期与到期告警。小节点不会因缩短到客户端无法建立信任的链获益，只保留必要叶证书与中间证书。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`/pg/cert/server.crt`	不同于 boot 值	`'/pg/cert/server.crt'`
OLAP	`/pg/cert/server.crt`	不同于 boot 值	`'/pg/cert/server.crt'`
CRIT	`/pg/cert/server.crt`	不同于 boot 值	`'/pg/cert/server.crt'`
TINY	`/pg/cert/server.crt`	不同于 boot 值	`'/pg/cert/server.crt'`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)。建议（待人工复核）——编辑推断：统一托管服务器证书路径让所有模板遵循同一证书生命周期布局。

常见坑

编辑 ssl_cert_file 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_cert_file。

ssl · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

22 - ssl_ciphers

ssl_ciphers 定义 TLS 1.2 及更低版本允许使用的密码套件列表。

说明

Fact — 官方简述译文：设置 TLS 1.2 及更低版本允许使用的密码套件列表。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值HIGH:MEDIUM:+3DES:!aNULL: HIGH:MEDIUM:+3DES:!aNULL

生命周期

Fact	值
首次观测	PG9.1
在档版本	PG9.1–19 Beta 3
移除版本	否
引入提交	不作断言：名称在 2008 Git 历史边界已经存在
提交日期	≤ 2008-01-01
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.1–9.2	`ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH`	—	ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
PG9.3	`DEFAULT:!LOW:!EXP:!MD5:@STRENGTH`	—	DEFAULT:!LOW:!EXP:!MD5:@STRENGTH
PG9.4–19 Beta 3	`HIGH:MEDIUM:+3DES:!aNULL`	—	HIGH:MEDIUM:+3DES:!aNULL

机制详解

ssl_ciphers 名称在本项目 2008 年历史边界以及 PG9.0 的 GUC 源码中已经存在，但只在定义 USE_SSL 时编译。本项目可审计的 PG9.0 备用构建没有启用 OpenSSL，因此该名称首次出现在 PG9.1 官方镜像快照；这个矩阵边界反映构建能力，而不是功能最初发明时间。

该 OpenSSL 密码字符串控制 TLS 1.2 及更低版本握手；PG18+ 的 TLS 1.3 套件由 ssl_tls13_ciphers 单独配置。SIGHUP reload 会改变新 TLS 上下文和新连接使用的策略，但不会重新协商已经建立的会话。

应把 ssl_ciphers 视为完整传输策略的一部分，与 ssl、pg_hba.conf、证书和私钥、CA 与吊销设置、协议上下限、ssl_groups 及客户端能力联合验证。必须针对实际安装的 OpenSSL 构建测试，因为可接受的密码名称与安全级别依赖库版本。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_ciphers。

ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

23 - ssl_crl_dir

ssl_crl_dir 定义 SSL 证书吊销列表目录的位置。

说明

Fact — 官方简述译文：设置 SSL 证书吊销列表目录的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG14
在档版本	PG14–19 Beta 3
移除版本	否
引入提交	`f5465fade908` — Allow specifying CRL directory
提交日期	2021-02-18
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG14–19 Beta 3	`""`	—	empty string

机制详解

ssl_crl_dir 指定客户端证书吊销列表目录。OpenSSL 需要哈希查找链接，因此每次新增或替换 CRL 后都必须再次运行 openssl rehash 或 c_rehash。它补充 ssl_crl_file，两种来源可以同时启用。

更改目录路径属于 SIGHUP 上下文配置变化，但配置目录中的 CRL 文件会在连接时按需加载。因此新安装且正确 rehash 的 CRL 可由新连接立即使用，无需重载 PostgreSQL。

这不同于 ssl_crl_file：后者的文件内容在服务器启动或配置重载时加载。两者都不会追溯吊销既有 TLS 会话；应使用新的客户端证书握手测试吊销，并监控 CRL 的颁发者、签名与到期。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_crl_dir 作为按颁发者索引的 CRL 仓库管理：加入最新 CRL，运行 openssl rehash 或 c_rehash，并用新连接验证吊销。只有能运维按需多颁发者更新时才使用。
OLAP	分析证书使用同一吊销仓库；不能仅因这些客户端连接较少就建立独立且陈旧的目录。
小规格	除非已具备自动 CRL 获取、rehash、到期监控与故障转移同步，否则保持空目录；无人维护的目录会造成虚假安全感。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

新增或替换 CRL 后没有运行 openssl rehash 或 c_rehash，导致 OpenSSL 无法发现。
只重载 PostgreSQL 却不刷新过期 CRL，或误以为目录变化会追溯影响既有 TLS 会话。
把 ssl_crl_dir 当成 ssl_crl_file，忽略目录 CRL 会为新连接按需加载。
只同步目录路径，却未把 CRL 与哈希链接同步到所有故障转移节点。

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

24 - ssl_crl_file

ssl_crl_file 定义 SSL 证书吊销列表文件的位置。

说明

Fact — 官方简述译文：设置 SSL 证书吊销列表文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG9.2
在档版本	PG9.2–19 Beta 3
移除版本	否
引入提交	`a445cb92ef5b` — Add parameters for controlling locations of server-side SSL files
提交日期	2012-02-22
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.2–19 Beta 3	`""`	—	empty string

机制详解

ssl_crl_file：设置 SSL 证书吊销列表文件的位置。验证客户端证书时会读取该 PEM 吊销列表，并应随颁发机构发布的新吊销状态更新。

ssl_crl_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	在颁发 CA 的 next-update 截止前刷新 ssl_crl_file，验证签名与颁发者覆盖，重载 PostgreSQL，并证明新吊销客户端证书会被拒绝。
OLAP	分析客户端遵循相同吊销策略；不能因会话更长或频率更低而延后 CRL 刷新。
小规格	若没有受管 CRL 源，应明确记录客户端证书吊销状态不再新鲜，而不是依赖过期文件；在每个故障转移节点监控文件与重载流程。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 未修改；OLAP: PG9.2–19 Beta 3 未修改；CRIT: PG9.2–19 Beta 3 未修改；TINY: PG9.2–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_crl_file 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_crl_file。

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_min_protocol_version

参考资料

25 - ssl_dh_params_file

ssl_dh_params_file 定义 SSL DH 参数文件的位置。

说明

Fact — 官方简述译文：设置 SSL DH 参数文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG10
在档版本	PG10–19 Beta 3
移除版本	否
引入提交	`c0a15e07cd71` — Always use 2048 bit DH parameters for OpenSSL ephemeral DH ciphers.
提交日期	2017-07-31
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG10–19 Beta 3	`""`	—	empty string

机制详解

ssl_dh_params_file：设置 SSL DH 参数文件的位置。空值使用 PostgreSQL 编译内置的 DH 参数；该文件只影响采用有限域 Diffie-Hellman 交换的密码套件。

ssl_dh_params_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有有意支持有限域临时 DH 密码套件，且参数由当前获批流程生成时才使用自定义 ssl_dh_params_file。上线前测试 OpenSSL 接受与重载。
OLAP	分析吞吐量不是削弱 DH 参数的理由。采用相同的经评审密钥交换策略，并只在证明客户端兼容后测量性能。
小规格	除非策略要求受管自定义参数，否则保持空值使用 PostgreSQL 编译内置参数；生成或加载自定义参数不会提升容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_dh_params_file 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_dh_params_file。

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

26 - ssl_ecdh_curve

ssl_ecdh_curve 定义 ECDH 使用的椭圆曲线。

说明

Fact — 官方简述译文：设置 ECDH 使用的椭圆曲线。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值prime256v1: prime256v1

生命周期

Fact	值
首次观测	PG9.4
在档版本	PG9.4–17
移除版本	PG18
引入提交	`3164721462d5` — SSL: Support ECDH key exchange
提交日期	2013-12-07
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.4–17	`prime256v1`	—	prime256v1

机制详解

ssl_ecdh_curve：设置 ECDH 使用的椭圆曲线。这一单曲线控制项存在至 PostgreSQL 17，并在 PostgreSQL 18 被支持多组的 ssl_groups 取代。

ssl_ecdh_curve 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	PostgreSQL 18+ 不应调优 ssl_ecdh_curve，应把经评审策略迁移到 ssl_groups。旧版本也只能在完成 TLS 库兼容测试后修改。
OLAP	采用与 OLTP 相同的经评审密钥交换策略；分析吞吐量不是保留已移除单曲线控制项的理由。
小规格	PostgreSQL 17 及更早版本保留受支持的安全默认值，升级时验证 ssl_groups 替代配置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG17 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–17 未修改；OLAP: PG9.4–17 未修改；CRIT: PG9.4–17 未修改；TINY: PG9.4–17 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_ecdh_curve 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
在 PostgreSQL 18 配置中保留已移除名称，而未迁移到 ssl_groups。

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

27 - ssl_groups

ssl_groups 定义 Diffie-Hellman 密钥交换使用的组。

说明

Fact — 官方简述译文：设置 Diffie-Hellman 密钥交换使用的组。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值X25519:prime256v1: X25519:prime256v1

生命周期

Fact	值
首次观测	PG18
在档版本	PG18–19 Beta 3
移除版本	否
引入提交	`3d1ef3a15c3e` — Support configuring multiple ECDH curves
提交日期	2024-10-24
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG18–19 Beta 3	`X25519:prime256v1`	—	X25519:prime256v1

机制详解

ssl_groups：设置 Diffie-Hellman 密钥交换使用的组。PostgreSQL 18 接受按优先顺序排列、以冒号分隔的列表，取代原先单一的 ssl_ecdh_curve，并覆盖支持的密钥交换组。

ssl_groups 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_groups 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_groups 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_groups 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_groups。

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers

参考资料

28 - ssl_key_file

ssl_key_file 定义 SSL 服务器私钥文件的位置。

说明

Fact — 官方简述译文：设置 SSL 服务器私钥文件的位置。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值server.key: server.key

生命周期

Fact	值
首次观测	PG9.2
在档版本	PG9.2–19 Beta 3
移除版本	否
引入提交	`a445cb92ef5b` — Add parameters for controlling locations of server-side SSL files
提交日期	2012-02-22
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.2–19 Beta 3	`server.key`	—	server.key

机制详解

ssl_key_file：设置 SSL 服务器私钥文件的位置。该文件包含与 ssl_cert_file 匹配的私钥；PostgreSQL 会先强制检查严格的所有权与权限。

ssl_key_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	让 ssl_key_file 由 PostgreSQL 服务账号拥有，使用 PostgreSQL 接受的严格权限，确认与 ssl_cert_file 匹配，并通过可审计秘密交付路径轮换。
OLAP	分析节点采用相同私钥控制；负载类型绝不构成共享、组可写或脱离受管 PKI 流程复制私钥的理由。
小规格	优先使用一个受管私钥并测试到期/续期与受保护备份。私钥加密时，在无人值守重启前测试 ssl_passphrase_command 与重载行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`/pg/cert/server.key`	不同于 boot 值	`'/pg/cert/server.key'`
OLAP	`/pg/cert/server.key`	不同于 boot 值	`'/pg/cert/server.key'`
CRIT	`/pg/cert/server.key`	不同于 boot 值	`'/pg/cert/server.key'`
TINY	`/pg/cert/server.key`	不同于 boot 值	`'/pg/cert/server.key'`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)。建议（待人工复核）——编辑推断：统一托管私钥路径与服务器证书配对，并集中所有权与续期约定。

常见坑

编辑 ssl_key_file 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
私钥所有权或权限被 PostgreSQL 拒绝，或意外向可读组泄漏。

ssl · ssl_cert_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

29 - ssl_max_protocol_version

ssl_max_protocol_version 定义允许使用的最高 SSL/TLS 协议版本。

说明

Fact — 官方简述译文：设置允许使用的最高 SSL/TLS 协议版本。

身份

类型 , 值enum: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值"", TLSv1, TLSv1.1, TLSv1.2, TLSv1.3: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG12
在档版本	PG12–19 Beta 3
移除版本	否
引入提交	`e73e67c71959` — Add settings to control SSL/TLS protocol version
提交日期	2018-11-20
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG12–19 Beta 3	`""`	—	empty string

机制详解

ssl_max_protocol_version：设置允许使用的最高 SSL/TLS 协议版本。空值不在 SSL 库之外施加 PostgreSQL 专属上限；指定版本可为兼容测试有意阻止更新协议。

ssl_max_protocol_version 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_max_protocol_version 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_max_protocol_version 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_max_protocol_version 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_max_protocol_version。

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

30 - ssl_min_protocol_version

ssl_min_protocol_version 定义允许使用的最低 SSL/TLS 协议版本。

说明

Fact — 官方简述译文：设置允许使用的最低 SSL/TLS 协议版本。

身份

类型 , 值enum: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值TLSv1, TLSv1.1, TLSv1.2, TLSv1.3: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值TLSv1.2: TLSv1.2

生命周期

Fact	值
首次观测	PG12
在档版本	PG12–19 Beta 3
移除版本	否
引入提交	`e73e67c71959` — Add settings to control SSL/TLS protocol version
提交日期	2018-11-20
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG12	`TLSv1`	—	TLSv1
PG13–19 Beta 3	`TLSv1.2`	—	TLSv1.2

机制详解

ssl_min_protocol_version：设置允许使用的最低 SSL/TLS 协议版本。协商版本低于下限的连接会被拒绝；上游默认值从 PostgreSQL 12 的 TLSv1 提升为 PostgreSQL 13 的 TLSv1.2。

ssl_min_protocol_version 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_min_protocol_version 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_min_protocol_version 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_min_protocol_version 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_min_protocol_version。

ssl_ciphers · ssl_tls13_ciphers · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

31 - ssl_passphrase_command

ssl_passphrase_command 定义用于获取 SSL 私钥口令的命令。

说明

Fact — 官方简述译文：设置用于获取 SSL 私钥口令的命令。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG11
在档版本	PG11–19 Beta 3
移除版本	否
引入提交	`8a3d9425290f` — Add ssl_passphrase_command setting
提交日期	2018-02-26
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG11–19 Beta 3	`""`	—	empty string

机制详解

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

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

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

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	使用绝对路径、最小化、非交互助手，并由受保护 keychain 或文件描述符提供秘密。测试精确标准输出、退出状态、%p 引用、超时/失败、启动、重载和故障节点可用性，且不得记录口令。
OLAP	分析节点使用相同助手与秘密源；负载类型不会改变私钥信任要求。安排证书轮换前测试无人值守重启。
小规格	优先使用最简单且可审计、能无人值守重启的助手。若保留 TTY 提示，应记录：除非安全启用 supports_reload，否则重载无法替换加密私钥。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

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

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

32 - ssl_passphrase_command_supports_reload

ssl_passphrase_command_supports_reload 是 PostgreSQL 中用于控制重新加载服务器配置时是否调用 ssl_passphrase_command的参数。

说明

Fact — 官方简述译文：控制重新加载服务器配置时是否调用 ssl_passphrase_command。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG11
在档版本	PG11–19 Beta 3
移除版本	否
引入提交	`8a3d9425290f` — Add ssl_passphrase_command setting
提交日期	2018-02-26
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG11–19 Beta 3	`off`	—	off

机制详解

ssl_passphrase_command_supports_reload 决定重新加载配置时，如替换 SSL 私钥需要口令，是否可以调用 ssl_passphrase_command。设为 off 时，重载会忽略该命令；若私钥需要口令，PostgreSQL 将不重载 SSL 配置。

该参数属于 SIGHUP 上下文，影响新握手使用的替换 TLS 材料；既有 TLS 会话不会重新协商。只有助手无需交互、可靠可用且能在运行中的服务器环境安全调用时才应开启。

Windows 上该参数必须为 on，因为 Windows 进程模型会使每个连接执行配置重载。这一平台要求优先于 Unix 环境中把依赖 TTY 的助手限制在启动阶段的通常选择。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有 ssl_passphrase_command 已证明无需交互、幂等、快速且重新加载时可用，才启用本项；否则证书刷新可能在运维上失败。
OLAP	各负载类型采用相同重载能力，使每个节点的证书轮换行为可预测。
小规格	Windows 上必须设为 on。Unix 上只有在完全不需要重载时取口令时才保持 off；若需要无人值守轮换，应先在服务器运行环境中验证助手再开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

Windows 上设为 off；该平台因每个连接都会执行配置重载而强制要求 on。
助手仍需交互、执行缓慢、不可用或无法安全重复调用，却开启重载支持。
误以为重新加载会重新协商既有会话；替换后的 TLS 材料只影响新握手。
重载后未检查服务器日志；若口令获取失败，PostgreSQL 会继续使用旧 SSL 配置。

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

33 - ssl_prefer_server_ciphers

ssl_prefer_server_ciphers 是 PostgreSQL 中用于优先采用服务器端的密码套件顺序的参数。

说明

Fact — 官方简述译文：优先采用服务器端的密码套件顺序。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值on: on

生命周期

Fact	值
首次观测	PG9.4
在档版本	PG9.4–19 Beta 3
移除版本	否
引入提交	`ef3267523d1e` — SSL: Add configuration option to prefer server cipher order
提交日期	2013-12-07
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.4–19 Beta 3	`on`	—	on

机制详解

ssl_prefer_server_ciphers：优先采用服务器端的密码套件顺序。它只影响 TLS 1.2 及更低版本采用服务器还是客户端顺序；TLS 1.3 协商不使用该开关。

ssl_prefer_server_ciphers 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_prefer_server_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_prefer_server_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_prefer_server_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
误以为它控制 TLS 1.3 密码套件顺序。

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_groups

参考资料

34 - ssl_renegotiation_limit

ssl_renegotiation_limit：设置重新协商加密密钥前允许收发的流量。实测在档范围为 PG9.0–9.4；最后在档的 PG9.4 启动默认值为 0 B，context 为 user。它在 PG9.5 被移除。

说明

Fact — 官方简述译文：设置重新协商加密密钥前允许收发的流量。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值kB: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Security and Authentication: 上游分类
最后 boot 值 , 值0: 0 B

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–9.4
移除版本	PG9.5
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–9.4	`0`	`kB`	0 B

机制详解

ssl_renegotiation_limit：设置重新协商加密密钥前允许收发的流量。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。本站在 PG9.0–9.4 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

该参数在 TLS 流量达到阈值后发起密钥重新协商。随着协议、库行为和安全建议转向避免 renegotiation，PostgreSQL 在 PG9.5 移除了它；现代 TLS 策略应管理协议版本、密码套件、证书与连接轮换。

应与 ssl_min_protocol_version、ssl_max_protocol_version、ssl_ciphers、ssl 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP	升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格	记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.4 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.4 未修改；OLAP: PG9.0–9.4 未修改；CRIT: PG9.0–9.4 未修改；TINY: PG9.0–9.4 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

把 ssl_renegotiation_limit 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
忽略 pg_settings 报告的 user context，误以为修改会立即生效。
孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

ssl_min_protocol_version · ssl_max_protocol_version · ssl_ciphers · ssl

参考资料

35 - ssl_sni

ssl_sni：设置是否解释 SSL 连接中的 SNI 扩展。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。

说明

Fact — 官方简述译文：设置是否解释 SSL 连接中的 SNI 扩展。

身份

类型 , 值bool: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值off: off

生命周期

Fact	值
首次观测	PG19 Beta 3
在档版本	PG19 Beta 3
移除版本	否
引入提交	`4f433025f666` — ssl: Serverside SNI support for libpq
提交日期	2026-03-18
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG19 Beta 3	`off`	—	off

机制详解

ssl_sni：设置是否解释 SSL 连接中的 SNI 扩展。重新加载配置即可让服务器采用新值，无需完整重启。本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

在 TLS 下启用后，PostgreSQL 读取客户端的 Server Name Indication，并通过 hosts_file 选择凭据。主机名不区分大小写匹配，/no_sni/ 与 * 提供明确的回退行为；证书身份、客户端校验、CRL、文件权限和 reload 失败仍需独立验证。

应与 hosts_file、ssl、ssl_cert_file、ssl_key_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP	批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格	优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

把 ssl_sni 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

hosts_file · ssl · ssl_cert_file · ssl_key_file · ssl_ca_file

参考资料

36 - ssl_tls13_ciphers

ssl_tls13_ciphers 定义 TLS 1.3 允许使用的密码套件列表。

说明

Fact — 官方简述译文：设置 TLS 1.3 允许使用的密码套件列表。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值sighup: 配置 reload 后生效
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / SSL: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG18
在档版本	PG18–19 Beta 3
移除版本	否
引入提交	`45188c2ea239` — Support configuring TLSv1.3 cipher suites
提交日期	2024-10-24
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG18–19 Beta 3	`""`	—	empty string

机制详解

ssl_tls13_ciphers：设置 TLS 1.3 允许使用的密码套件列表。空值把 TLS 1.3 套件选择交给 SSL 库默认值，其语法也不同于 ssl_ciphers。

ssl_tls13_ciphers 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 ssl_tls13_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP	分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格	保持 ssl_tls13_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

编辑 ssl_tls13_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
对 TLS 1.3 使用 ssl_ciphers 的语法或名称，意外拒绝所有预期套件。

ssl_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

37 - superuser_reserved_connections

superuser_reserved_connections 定义为超级用户保留的连接槽数量。

说明

Fact — 官方简述译文：设置为超级用户保留的连接槽数量。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值0 – 262143: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值3: 3

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`3`	—	3

机制详解

superuser_reserved_connections：设置为超级用户保留的连接槽数量。普通槽位与 reserved_connections 容量耗尽后，只有超级用户能使用这些槽位，从而保留应急入口。

superuser_reserved_connections 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

reserved_connections 与 superuser_reserved_connections 从 max_connections 中划出特权层；连接池、监控、复制、维护与故障转移必须共同纳入同一后端总预算。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	在 max_connections 总量内，按独立应急主体数量、连接池行为与故障转移操作确定 superuser_reserved_connections；测试普通连接饱和后管理入口仍可用。
OLAP	为重型分析会话之外的控制、监控与取消预留足够槽位，但不要让预留吞噬本就较小后端池的过高比例。
小规格	让 superuser_reserved_connections 相对 max_connections 保持适度，同时至少保留一条经过测试的应急路径；饱和时预留槽不会供普通客户端使用。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`10`	不同于 boot 值	`10`
OLAP	`10`	不同于 boot 值	`10`
CRIT	`10`	不同于 boot 值	`10`
TINY	`10`	不同于 boot 值	`10`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10 (dcs)；OLAP: PG9.0–19 Beta 3 = 10 (dcs)；CRIT: PG9.0–19 Beta 3 = 10 (dcs)；TINY: PG9.0–19 Beta 3 = 10 (dcs)。建议（待人工复核）——编辑推断：十个应急槽在连接池前置服务中提供高于上游的监控、修复与故障转移操作余量。

常见坑

期待重新加载或 SET 激活 superuser_reserved_connections，而它实际需要受控重启服务器。
把预留槽计算在 max_connections 之外，而所有层级实际共享同一总上限。
应急响应预留过少，或预留过多以致饱和时普通应用容量骤降。
没有回滚计划及客户端或运维兼容测试，就全局修改 superuser_reserved_connections。

listen_addresses · port · max_connections · reserved_connections · unix_socket_directories

参考资料

38 - tcp_keepalives_count

tcp_keepalives_count 定义 TCP keepalive 的最大重传次数。

说明

Fact — 官方简述译文：设置 TCP keepalive 的最大重传次数。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值—: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / TCP Settings: 上游分类
最后 boot 值 , 值0: 0

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`0`	—	0

机制详解

tcp_keepalives_count：设置 TCP keepalive 的最大重传次数。它与 idle、interval 一起决定多少次未响应探测后判定故障；在支持的平台上，零选择操作系统默认值。

tcp_keepalives_count 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 tcp_keepalives_count 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP	长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格	除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_count。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

只在一个会话中修改 tcp_keepalives_count，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
误以为零表示不探测，而它实际选择操作系统默认值。

tcp_keepalives_idle · tcp_keepalives_interval · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

39 - tcp_keepalives_idle

tcp_keepalives_idle 定义开始发送 TCP keepalive 前的空闲时间。

说明

Fact — 官方简述译文：设置开始发送 TCP keepalive 前的空闲时间。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值s: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / TCP Settings: 上游分类
最后 boot 值 , 值0: 0 s

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`0`	`s`	0 s

机制详解

tcp_keepalives_idle：设置开始发送 TCP keepalive 前的空闲时间。它决定空闲 TCP 连接在首次 keepalive 探测前等待多久；零选择操作系统默认值。

tcp_keepalives_idle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 tcp_keepalives_idle 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP	长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格	除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_idle。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

只在一个会话中修改 tcp_keepalives_idle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
取值长于网络设备空闲超时，导致 keepalive 尚未探测连接就已被设备丢弃。

tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

40 - tcp_keepalives_interval

tcp_keepalives_interval 定义 TCP keepalive 重传之间的间隔。

说明

Fact — 官方简述译文：设置 TCP keepalive 重传之间的间隔。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值s: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / TCP Settings: 上游分类
最后 boot 值 , 值0: 0 s

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`0`	`s`	0 s

机制详解

tcp_keepalives_interval：设置 TCP keepalive 重传之间的间隔。探测开始后，它规定重传间隔，并与 tcp_keepalives_count 共同决定总故障发现时间。

tcp_keepalives_interval 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 tcp_keepalives_interval 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP	长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格	除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_interval。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

只在一个会话中修改 tcp_keepalives_interval，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
只调重传间隔，却未结合 tcp_keepalives_count 与总故障发现时间。

tcp_keepalives_idle · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

41 - tcp_user_timeout

tcp_user_timeout 定义 TCP 用户超时。

说明

Fact — 官方简述译文：设置 TCP 用户超时。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值user: 普通用户可在运行时修改
单位 , 值ms: 原始单位
范围 , 值0 – 2147483647: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / TCP Settings: 上游分类
最后 boot 值 , 值0: 0 ms

生命周期

Fact	值
首次观测	PG12
在档版本	PG12–19 Beta 3
移除版本	否
引入提交	`249d64999615` — Add support TCP user timeout in libpq and the backend server
提交日期	2019-04-06
Discussion	讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG12–19 Beta 3	`0`	`ms`	0 ms

机制详解

tcp_user_timeout：设置 TCP 用户超时。在操作系统支持时，它限制已发送数据保持未确认状态的时长；这不同于对空闲连接进行探测的 keepalive。

tcp_user_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	按可接受的未确认数据停滞上限设置 tcp_user_timeout，使其短于服务故障转移预算，并测试客户端重试行为。
OLAP	为大结果传输的暂时拥塞留出空间，但应短于不可达对端占用工作进程直至作业窗口结束的时长。
小规格	除非实测半开连接需要边界，否则使用操作系统默认值；依赖前先确认平台支持。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

只在一个会话中修改 tcp_user_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
忘记零通常表示禁用超时或把行为交给操作系统。
设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
把未确认数据超时与空闲套接字的 keepalive 探测混为一谈。

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · client_connection_check_interval · authentication_timeout

参考资料

42 - unix_socket_directories

unix_socket_directories 定义创建 Unix 域套接字的目录。

说明

Fact — 官方简述译文：设置创建 Unix 域套接字的目录。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值/var/run/postgresql: /var/run/postgresql

生命周期

Fact	值
首次观测	PG9.3
在档版本	PG9.3–19 Beta 3
移除版本	否
引入提交	`c9b0cbe98bd7` — Support having multiple Unix-domain sockets per postmaster.
提交日期	2012-08-10
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.3–19 Beta 3	`/var/run/postgresql`	—	/var/run/postgresql

机制详解

unix_socket_directories：设置创建 Unix 域套接字的目录。PostgreSQL 启动时在每个所列目录创建套接字与锁文件；在支持的系统上，以 @ 开头的值选择抽象命名空间。

unix_socket_directories 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Unix 套接字可达性由目录存在性与遍历权限、套接字组和模式、服务器账号及客户端搜索路径共同决定；pg_hba.conf 的 local 记录仍负责认证。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	把 unix_socket_directories 纳入同一套 Unix 套接字访问策略：选择可信目录、所有者、组成员与权限，并测试本地连接池、监控、备份和管理工具。
OLAP	分析工具采用同一套经评审本地访问边界；只有客户端与操作系统生命周期受管时才新增目录或组。
小规格	保持 unix_socket_directories 简单且最小权限。本地套接字只带来很小的 TCP 开销差异，不应为方便而开放给所有用户。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	`/var/run/postgresql, /tmp`	不同于 boot 值	`'/var/run/postgresql, /tmp'`
OLAP	`/var/run/postgresql, /tmp`	不同于 boot 值	`'/var/run/postgresql, /tmp'`
CRIT	`/var/run/postgresql, /tmp`	不同于 boot 值	`'/var/run/postgresql, /tmp'`
TINY	`/var/run/postgresql, /tmp`	不同于 boot 值	`'/var/run/postgresql, /tmp'`

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；OLAP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；CRIT: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；TINY: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)。建议（待人工复核）——编辑推断：同时提供发行版运行目录与 /tmp，可兼容本地工具，并保留常规托管套接字路径。

常见坑

期待重新加载或 SET 激活 unix_socket_directories，而它实际需要受控重启服务器。
放宽套接字模式，却忽略目录遍历、组成员与 pg_hba.conf local 认证。
加入易失或不存在目录，导致重启后服务器无法启动或本地客户端找错位置。
没有回滚计划及客户端或运维兼容测试，就全局修改 unix_socket_directories。

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections

参考资料

43 - unix_socket_directory

unix_socket_directory：设置创建 Unix 域套接字的目录。实测在档范围为 PG9.0–9.2；最后在档的 PG9.2 启动默认值为 empty string，context 为 postmaster。它在 PG9.3 被移除。

说明

Fact — 官方简述译文：设置创建 Unix 域套接字的目录。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–9.2
移除版本	PG9.3
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–9.2	`""`	—	empty string

机制详解

unix_socket_directory：设置创建 Unix 域套接字的目录。该值在服务器启动时固定，修改后必须安排受控重启。本站在 PG9.0–9.2 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个单数路径参数指定 Unix 域套接字目录。PG9.3 用 unix_socket_directories 取代它，新参数可用逗号分隔多个位置；套接字所属组与权限仍由其他参数控制。

应与 unix_socket_directories、unix_socket_group、unix_socket_permissions、listen_addresses 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP	升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格	记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.2 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.2 未修改；OLAP: PG9.0–9.2 未修改；CRIT: PG9.0–9.2 未修改；TINY: PG9.0–9.2 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

把 unix_socket_directory 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

unix_socket_directories · unix_socket_group · unix_socket_permissions · listen_addresses

参考资料

机器可读 GUC 全量导出

44 - unix_socket_group

unix_socket_group 定义 Unix 域套接字的所属组。

说明

Fact — 官方简述译文：设置 Unix 域套接字的所属组。

身份

类型 , 值string: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值—: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值"": empty string

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`""`	—	empty string

机制详解

unix_socket_group 设置文件系统 Unix 域套接字的所属组；所有者仍是 PostgreSQL 服务器账号。空字符串使用该账号默认组，unix_socket_permissions 决定哪些组访问位有效。

它属于 POSTMASTER 上下文，更改需要重启，并作用于启动时重建的套接字。目录所有权与遍历权限、组成员以及 pg_hba.conf local 记录仍是独立访问层。

Windows 不支持并会忽略该参数。对 unix_socket_directories 中以 @ 开头的 Linux 抽象命名空间套接字也会忽略，因为它们没有文件系统所有者或组。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有本地工具确需套接字可达时才选择专用操作系统组，审计组成员，并与 0770 类套接字及目录权限配合；另行测试 pg_hba.conf 认证。
OLAP	分析工具应加入同一经评审本地访问组或使用 TCP/TLS；不要为了方便创建宽泛组。
小规格	除非受管本地客户端需要其他组，否则使用服务器账号默认组。Windows 或抽象套接字会忽略本 GUC，应改为配置实际生效的访问边界。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

期待重载改变套接字所有权；只有服务器重启时才重建套接字。
在 Windows 或抽象命名空间套接字上依赖本参数，而它会被忽略。
授予套接字组成员资格，却未另行实施 pg_hba.conf 认证与数据库权限。
更改套接字组，但目录遍历权限仍阻止预期客户端访问。

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

45 - unix_socket_permissions

unix_socket_permissions 定义 Unix 域套接字的访问权限。

说明

Fact — 官方简述译文：设置 Unix 域套接字的访问权限。

身份

类型 , 值integer: 上游 pg_settings 类型
Context , 值postmaster: 修改后需要重启数据库
单位 , 值—: 原始单位
范围 , 值0 – 511: 最后在档版本的原始上下限
枚举值 , 值—: 非枚举类型记为 —
分类 , 值Connections and Authentication / Connection Settings: 上游分类
最后 boot 值 , 值511: 511

生命周期

Fact	值
首次观测	PG9.0（研究下界）
在档版本	PG9.0–19 Beta 3
移除版本	否
引入提交	不作断言：早于 PG9.0 研究边界
提交日期	—
Discussion	—

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本	原始 `boot_val`	单位	人类可读值
PG9.0–19 Beta 3	`511`	—	511

机制详解

unix_socket_permissions 设置文件系统 Unix 域套接字的 chmod 风格模式，八进制写法需要前导零。对套接字而言，只有写权限位控制能否连接；读与执行位不会提供有意义的额外套接字访问。

它属于 POSTMASTER 上下文，只有服务器重启重建套接字时模式才改变。目录遍历权限与 unix_socket_group 可形成额外本地边界，而 pg_hba.conf local 记录仍独立认证数据库用户。

抽象命名空间套接字没有文件系统权限，因此以 @ 开头的套接字条目会忽略本参数。某些操作系统也完全忽略套接字模式；不能把该模式描述成目录权限或 pg_hba.conf 的可移植替代。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景	建议
OLTP	只有本地操作系统成员资格是有意的第一道边界时才使用 0770 或 0700，并验证目录权限与 pg_hba.conf 仍实施预期策略。pg_hba.conf 为权威时，可移植默认 0777 也可能合理。
OLAP	分析工具采用同一本地策略。不要为解决缺失组或目录部署而放宽模式，应修复操作系统身份路径。
小规格	选择平台支持的最简单模式，并在重启后测试。对抽象套接字或忽略套接字模式的系统，应在适用时通过目录选择与 pg_hba.conf 实施访问。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板	有效值	与上游 boot 比较	源表达式
OLTP	未修改	—	—
OLAP	未修改	—	—
CRIT	未修改	—	—
TINY	未修改	—	—

注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

写成十进制 770 而非八进制 0770，得到意外的数字模式。
期待读或执行位控制套接字连接访问；只有写权限位有意义。
在抽象命名空间套接字或忽略套接字权限的操作系统上依赖该模式。
把严格套接字模式当作 pg_hba.conf 认证、角色权限或目录遍历控制的替代品。

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

连接与认证

1 - authentication_timeout

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

2 - bonjour

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

3 - bonjour_name

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

4 - client_connection_check_interval

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

5 - db_user_namespace

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

6 - gss_accept_delegation

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

7 - krb_caseins_users

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

8 - krb_server_keyfile

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数