先说结论这个invalid value for parameter timeZone: Asia/Beijing的报错我在中标麒麟上处理过不止一次。头一回遇到时第一反应是去查系统时钟、查硬件时间、查NTP同步折腾了大半天最后发现跟系统时间一点关系都没有问题出在 PostgreSQL 的时区参数校验上——它压根不认 Asia/Beijing 这个写法。这篇文章把我完整的排查思路、原理和修复步骤整理出来给后面踩到同一个坑的人省点时间。1. 报错出现的三种典型现场以及我惯用的排查顺序1.1 最常见的三种触发现场同一个报错信息在真实环境里有三种完全不同的出现位置排错方向也完全不同。对号入座能省一半时间。现场APostgreSQL 服务启动失败实例初始化完执行systemctl start postgresql服务秒退。翻看日志第一屏就是FATAL: invalid value for parameter timeZone: Asia/Beijing这种情况十有八九是postgresql.conf里写死了timezone Asia/Beijing或者启动时通过-c timezoneAsia/Beijing传入了参数。配置文件是谁写的通常是初始化脚本、一键部署脚本、或者是从别的项目里拷过来的模板。模板里写 Asia/Beijing 很正常因为它符合人的直觉但 PostgreSQL 不需要直觉。现场B应用连接池启动时报错应用日志里不断刷Caused by: org.postgresql.util.PSQLException: FATAL: invalid value for parameter timeZone: Asia/Beijing at org.postgresql.core.v3.ConnectionFactoryImpl.doAuthentication...服务端本身是好的连接串也没问题。真正的原因是连接池或框架在新建连接时执行了初始化 SQL比如 HikariCP 的connectionInitSql配置了SET timezone Asia/BeijingDruid 的connectionInitSqls里写了同样的语句。连接池一创建连接就在会话级别执行这条 SQL直接报错。现场C手动执行 SQL 时立刻报错这种情况最少但最好排查。在 psql 里执行SET timezone Asia/Beijing;执行瞬间返回ERROR说明当前会话的客户端工具或环境变量把时区传成了这个值。常见来源是环境变量PGTZAsia/Beijing或者是某个.psqlrc文件里预设了 SET 命令。1.2 我排查这个报错的固定路线遇到这个报错我习惯按下面这个顺序排查建议直接照抄。第一步确定报错发生在哪个层面。先看是服务端日志、应用日志还是 psql 客户端返回。这一步能把问题范围缩小到服务端配置、连接层、会话层其中一处。第二步查服务端配置文件grep -n timezone $PGDATA/postgresql.conf grep -n timezone $PGDATA/postgresql.auto.conf重点看postgresql.conf里有没有被写入时区参数以及postgresql.auto.conf里有没有ALTER SYSTEM留下的痕迹。很多老项目的部署脚本习惯把时区显式写进配置文件这就是根因所在。第三步进入数据库看当前实际生效值SHOW timezone; SELECT current_setting(TimeZone);通过这个命令能确认实际跑起来的值是什么。如果配置文件里没有设置默认应该是GMT或者Asia/Shanghai取决于初始化数据库时的系统时区。观察报错上下文会看到一个细节PostgreSQL 的报错信息里参数名写成timeZone驼峰写法这是因为timezone参数在 PG 源码里属于类型为string的 GUC 参数对外展示名就是TimeZone。这里别被误导配置项本身就叫timezone。第四步查 tzdata 环境。这是很多人忽略的一步也是理解这个问题的关键。1.3 用一条SQL验证问题根因不管是哪种现场最终都要用这组SQL来判断根因-- 查看当前时区 SHOW timezone; -- 查看当前数据库能识别哪些 Asia 时区 SELECT name FROM pg_timezone_names WHERE name LIKE Asia/% ORDER BY name;执行第二条SQL看到的结果一般是Asia/Shanghai、Asia/Urumqi等列表但绝对不会有Asia/Beijing。到这里根因已经很清楚了PostgreSQL 的时区校验规则里没有这个字符串。我当时执行完这条SQL之后立刻去翻了系统时区文件ls /usr/share/zoneinfo/Asia/结果同样没有Beijing这个文件。这些线索指向同一个结论问题的核心不是服务器时间错乱而是时区名称的合法性问题。2. 时区参数校验机制PostgreSQL为什么对Asia/Beijing说不2.1 IANA 时区数据库里没有这个主条目PostgreSQL 校验时区名时参考的是 IANA 时区数据库也叫 tzdata而不是中国人都知道北京在东八区这种常识。在 IANA 数据库的标准目录中中国时区的主条目是Asia/Shanghai中国标准时间的代表时区覆盖东八区UTC8Asia/Urumqi新疆部分地区使用的时区UTC6Asia/Harbin、Asia/Chongqing等这些在早年间存在过后来被合并进Asia/Shanghai在新版 tzdata 中只剩历史记录Asia/Beijing在这套体系里非常尴尬。早期 tzdata 中确实有过这个名称但后来规范整合时没有被采用主数据目录里根本没有对应文件。现代 Linux 发行版自带的 tzdata 包里/usr/share/zoneinfo/Asia/目录下只会有Shanghai不会有Beijing。只看时区字符串本身在 tzdata 中合法在系统层可能也合法取决于安装的 tzdata 版本但到了 PostgreSQL 这里就分叉了。PostgreSQL 判断时区是否可用依据的是它自己的时区解析逻辑以及编译或运行时加载的 tzdata 数据。如果该版本 tzdata 中没有Asia/Beijing这个条目那它就是一个非法值不管服务器上实际时间对不对。2.2 PostgreSQL 内置的tzdata决定了合法值范围PostgreSQL 的时区支持有两套数据来源需要区分开来源说明常见场景编译内置时区数据PG 源码包自带 tzdata编译时被打进程序内部源码编译安装的 PG系统时区数据通过--with-system-tzdata编译运行时读取/usr/share/zoneinfo发行版打包的 PG不管是哪套来源主流版本对Asia/Beijing的态度基本一致不识别。区别只在于系统包里可能因为 tzdata 较老或发行版打了补丁恰好存在这个文件但如果你装的是当时最新稳定的 PostgreSQL它内置的 tzdata 也是当时的最新版自然不会包含Asia/Beijing这个非标准名。这里还有一个比较容易混淆的概念pg_timezone_abbrevs和pg_timezone_names是两张完全不同的表。pg_timezone_abbrevs时区缩写比如CST、UTC、GMT一个缩写可以对应多个时区偏移量有歧义。pg_timezone_names完整 IANA 时区名称如Asia/Shanghai、Asia/Urumqi一个名称对应一个确定的时区规则。想看完整合法值列表实际需要看的是pg_timezone_names。只做简单排查的话一条 SQL 就够了SELECT name, utc_offset, is_dst FROM pg_timezone_names WHERE name IN (Asia/Shanghai, Asia/Beijing, Asia/Urumqi);执行结果只会返回Asia/Shanghai和Asia/UrumqiAsia/Beijing直接缺席。这个结果能直接用来向别人证明不是系统时间问题是时区名不合法。2.3 这个报错的迷惑性在于看着太正常了为什么这个报错容易卡人很久因为 Asia/Beijing 这个写法太符合正常思维了。北京是中国首都东八区代表写 Beijing 有什么错但计算机系统讲的是标准和数据来源IANA 规则里中国标准时间的代表城市是上海不是北京。这个选择有历史原因也不只是中国如此很多国家的 IANA 命名都选了不一定是首都的城市。对于使用者来说唯一要做的是接受这个事实在 PostgreSQL 里要写Asia/Shanghai它能精确表达 UTC8 中国标准时间。另外很多系统自带的 Java 虚拟机对时区名的处理有自己一套逻辑某些 Java 版本或国产组件会生成Asia/Beijing或GMT08:00这样的字符串。这也是为什么同一个问题在 Java 技术栈项目里出现频率特别高的原因之一。JDK 层面的时区映射表和 tzdata 不完全一致导致 JDBC 连接层传过去的值就带着Asia/BeijingPG 服务端一看就拒了。还有一个相关的参数容易误伤log_timezone。在配置文件里如果写了log_timezone Asia/Beijing服务启动时同样报invalid value for parameter log_timezone。我在实际排障中遇到过有人把timezone改对了但忽略了log_timezone导致启动依然失败。改的时候两个参数一起改别漏。3. 修复实操改配置、改连接、改习惯3.1 服务端全局修复把配置文件中的时区改对修复的第一步是把Asia/Beijing全部替换成Asia/Shanghai。注意单引号不能省。对于postgresql.conf场景直接编辑文件找到下面这行#timezone GMT改成timezone Asia/Shanghai还有一种情况是用了ALTER SYSTEM的方式写入的它在文件系统中的体现是postgresql.auto.conf。执行以下命令会生成或覆盖该文件中的配置项ALTER SYSTEM SET timezone TO Asia/Shanghai;修改完成后需要让服务重新加载配置。如果只改了postgresql.conf可以执行SELECT pg_reload_conf();或者用系统命令pg_ctl reload如果改的是log_timezone或timezone这类参数PG 支持 reload不需要重启实例。但为了保险起见我在生产环境里一般会做一次完整重启因为如果连接池里已经有大量长连接reload 之后某些连接可能还持有旧值时区造成新老连接行为不一致。等业务低峰期重启一次最干净。修改完成后验证方法如下SHOW timezone; SHOW log_timezone;理想输出为TimeZone | Asia/Shanghai log_timezone | Asia/Shanghai3.2 连接层修复JDBC、连接池、环境变量一起收拾服务端修好只是完成了三分之一如果客户端连接层还带着错误值应用照样报错。JDBC URL里如果带了options参数正确写法是这样的jdbc:postgresql://192.168.10.20:5432/mydb?options-c%20timezone%3DAsia%2FShanghai说明一下这里的编码规则-c是要传给后端的命令参数%20是空格%3D是号。这是比较标准的 URL 编码方式手写容易错建议直接在代码或配置里用现成的常量管理。连接池配置建议用connectionInitSql做一次会话级兜底设置。HikariCP 的 YAML 配置spring: datasource: hikari: connection-init-sql: SET timezoneAsia/ShanghaiDruid 的配置spring: datasource: druid: connection-init-sqls: - SET timezoneAsia/Shanghai这个做法的好处是即使服务端手动改了其他时区连接池里的每个连接在创建时都会执行一次该 SQL确保应用侧拿到的时区一定正确。要说代价就是每次新建连接多一条往返对高频率创建连接的场景有一定影响。常规业务系统完全能接受。命令行客户端如果要用 psql通过环境变量控制export PGTZAsia/Shanghai psql -h 192.168.10.20 -U appuser -d mydb也可以在 psql 里直接执行SET time zone Asia/Shanghai;3.3 数据库级和用户级的时区设置别忘了一起查除了全局配置PostgreSQL 还支持数据库级别和用户级别的时区设置优先级从高到低依次是会话级 用户级 数据库级 全局级。如果之前有人执行过类似下面的 SQL它会针对特定数据库或用户固化时区值。因为它的目标更精确所以优先于postgresql.conf里的全局值。排错时要特别注意这一层因为很多人会改完全局配置就以为结束了结果某个库或某个用户下还有残留设置。ALTER DATABASE mydb SET timezone TO Asia/Shanghai; ALTER USER appuser SET timezone TO Asia/Shanghai;查看当前所有设置的有效来源可以用SELECT name, setting, source FROM pg_settings WHERE name IN (TimeZone, log_timezone);source字段会告诉你当前值来自哪个层级default、configuration file、database、user还是session。这个字段在排查多层级配置冲突时非常好用比拍脑袋猜来源靠谱得多。顺带提一个点如果应用用的是timestamp without time zone不带时区的 timestamp时区参数对存储数据没有影响只影响timestamp with time zone类型数据的展示转换。很多业务库习惯用不带时区的时间类型所以改完时区后不需要担心存量数据会变质。但如果是timestamptz类型改完时区后查询结果会按新时区转换显示业务里所有读取这个字段的地方都要重新验证一遍尤其是报表类查询。4. 中标麒麟部署PostgreSQL的四个相邻坑4.1 不联网环境下的离线安装挂载光盘或ISO找安装源中标麒麟服务器很多跑在内网无法直接在线拉取软件包。装 PostgreSQL 之前先把安装源准备好是第一步。最常见的方式就是挂载光盘或 ISO 镜像。以光盘为例# 查看光驱设备名 lsblk | grep rom # 挂载光盘到 /mnt/cdrom mkdir -p /mnt/cdrom mount /dev/cdrom /mnt/cdrom # 卸载 umount /mnt/cdromISO 镜像文件用 loop 设备挂载mount -o loop /data/os/neokylin.iso /mnt/cdrom挂载完成后配置本地 yum 源把baseurl指向/mnt/cdrom执行yum clean all yum makecache再安装 PostgreSQLyum install postgresql-server postgresql-contrib关于挂载有个很实在的经验挂载光盘时如果目录已存在且非空mount会成功但目录原有的内容会被隐藏卸载后才恢复显示。临时目录建议单独创建不要图方便直接用/mnt。另外如果 ISO 是从 Windows 机器拷过来的可能带了不规范的卷标挂载时报wrong fs type之类的信息加上-t iso9660强制指定文件系统类型就好了。4.2 Docker 方式部署时时区问题会换一种形式再现现在不少人用 Docker 装 PostgreSQL本以为能把环境差异全隔离掉但时区坑换个形式照样出现。我常用的命令是这样docker run -d \ --name postgres \ -e TZAsia/Shanghai \ -e POSTGRES_PASSWORDyourpassword \ -v pgdata:/var/lib/postgresql/data \ -p 5432:5432 \ postgres:15这里-e TZAsia/Shanghai设置的是容器操作系统的时区让date命令的输出正确。但是PostgreSQL 内部的timezone参数跟这个不是一回事。容器里的 PG 默认配置仍然使用GMT对普通业务来说这会导致数据库写入的timestamptz显示时间比北京时间少8小时。正确做法是在启动参数里直接传配置docker run -d \ --name postgres \ -e TZAsia/Shanghai \ -e POSTGRES_PASSWORDyourpassword \ -e PGDATA/var/lib/postgresql/data \ -v pgdata:/var/lib/postgresql/data \ -p 5432:5432 \ postgres:15 \ -c timezoneAsia/Shanghai \ -c log_timezoneAsia/Shanghai或者把配置文件的修改映射进去把含timezone Asia/Shanghai的postgresql.conf通过-v /path/postgresql.conf:/etc/postgresql/postgresql.conf注入容器。验证容器里时区是否生效docker exec -it postgres psql -U postgres -c SHOW timezone;一定要输出Asia/Shanghai而不是GMT才算真正配置到位。之前帮人排查过一个问题容器系统时区、PG参数全都显示正常但应用侧读出来还是 UTC 时间。最终发现是 Docker 宿主机的时间本身就是 UTC 时区业务通过 mounted volume 共享配置文件把宿主机的时区设置也带进去了。容器化环境里时区问题的排查必须把宿主机、容器系统、数据库三个层面分开验证缺一个都不行。4.3 用 pg_dump 导出 schema 下的视图注意权限和依赖解决了时区问题部署过程中另一个高频需求就是做数据导出这里聊聊导出 schema 下的视图。导出某个 schema 下的所有对象包括表、视图、序列、函数等结构定义用下面这个命令pg_dump -U postgres -d mydb -n myschema --sectionpre-data -f schema_struct.sql-n指定 schema--sectionpre-data表示只导出数据定义部分表、视图、函数这些不同时导出数据。数据量大的情况下这样导结构比全量导出快很多而且不会带上数据。如果明确只想导出某个特定视图pg_dump -U postgres -d mydb -t myschema.myview -f view.sql-t参数支持通配符例如-t myschema.*view*可以匹配多个视图。如果只想快速查询视图定义而不产生文件直接查系统视图也行SELECT viewname, definition FROM pg_views WHERE schemaname myschema ORDER BY viewname;有一条经验值得记住导出视图时经常遇到权限问题。视图涉及到底层表访问权限如果执行导出的用户不是 schema 所有者pg_dump可能会报权限不足或者导出出来的视图定义里包含了search_path警告。标准做法是导出前先确认为 schema 所有者执行或者用超级用户执行后再授权给业务账号。还有一个必须知道的细节视图和物化视图不一样。pg_views只包含普通视图物化视图定义存在pg_matviews里导出命令也不一样。物化视图在pg_dump中通常会同时导出定义和数据如果只需要结构不需要数据需要用--sectionpre-data加--no-data避免把物化视图数据也带出来。4.4 忘记密码时的两种救场路径部署过程中很多人会碰到上一任管理员留下的密码没人知道的情况这里说两条路径分别对应不同层面。场景数据库用户密码忘了常见做法是临时修改pg_hba.conf中的认证方式为trust重启或 reload 后免密登录然后重置密码再改回原来的认证方式。编辑pg_hba.conf通常在$PGDATA目录下把对应行的scram-sha-256或md5临时改成trusthost all all 127.0.0.1/32 trust然后 reload 配置pg_ctl reload再用 psql 本地免密登录重置密码ALTER USER postgres WITH PASSWORD 新密码;改完立刻把pg_hba.conf里的trust改回scram-sha-256再 reload 一次。这里要特别提醒trust 认证不能长期保留即使是内网环境也不建议因为这是无密码认证任何能连到该地址的用户都能直接操作数据库。改完密码后如果想预防再忘可以把密码记录到团队的密码管理工具里至少也要存到部署文档的加密字段里。场景系统 root 密码忘了思路也是进单用户模式重置。重启服务器在 GRUB 引导界面按e进入编辑模式找到内核启动行通常以linux或linux16开头在行尾追加single或init/bin/bash按CtrlX或F10引导进入单用户模式后执行passwd重置 root 密码。单用户模式下文件系统默认可能是只读挂载重置密码前先执行mount -o remount,rw /让根文件系统可写否则会提示权限不足。这个操作对物理机、虚拟机、云主机都适用差异只在 GRUB 界面风格和具体参数上。操作结束后直接重启进入正常模式用新密码登录即可。这套操作在生产环境上要谨慎。如果服务器上跑着数据库实例重启必然导致服务中断。正规做法是先在测试机上完整演练一遍确保自己能在 5 分钟内完成再找业务低峰期动手。另外如果你的系统里同时装了 PostgreSQL 和 Docker重启之后还要注意 Docker 服务是否自动启动。我遇到过多次系统重启后 Docker 引擎没起来依赖容器的数据库应用全都连不上的情况。检查命令很简单systemctl status docker systemctl enable docker确认docker服务是 enabled 状态再确认 PostgreSQL 容器已经自动启动docker ps | grep postgres如果容器没起来查看容器日志定位原因docker logs postgres --tail 100尤其要注意重启后如果容器自动启动了但容器内 PostgreSQL 服务因为时区配置或其他配置问题启动失败docker ps里看到的状态可能是Restarting或Exited。这时别急着重启容器先看日志把根因处理掉再启动否则陷入重启死循环。4.5 顺手把时间同步也一起做了时区问题修完还有一步容易被忽视的收尾时间同步。时区错了改完配置文件显示正确了但如果服务器本身时间漂移日志时间照样不可信。检查当前时间状态date timedatectl查看时间同步服务状态systemctl status chronyd如果chronyd没在运行或者显示同步状态是no需要编辑/etc/chrony.conf配置时间服务器然后systemctl enable chronyd systemctl start chronyd手动同步一次chronyc makestep时间同步对数据库场景尤其重要。一方面分布式环境中多个节点的日志时间必须统一否则排查问题的时候时间线对不上另一方面如果未来要做 PostgreSQL 主从复制或备份恢复主备机的时间差过大会引发各种诡异问题。所以时区问题和时间同步问题建议在同一次维护窗口内一起处理完。最后再分享一点个人经验这类跨系统、跨组件的时区问题最怕的就是看着没问题和以前都能用这两种心态。时区命名这种东西不同软件、不同版本、不同操作系统的处理方式都有差异遇到报错别硬刚先查它内部实际的数据来源。把时区相关的所有配置项timezone、log_timezone、JDBC 连接参数、容器环境变量统一成Asia/Shanghai以后能少踩很多坑。