一、这些症状，中一条就是时区问题
-
Navicat 里看 `create_time` 差 8 小时，但接口返回的时间是对的；
-
同一张表，有的行时间对、有的行差 8 小时；
-
第三方推送（ETL/消息队列）写入的数据时间"看起来正常"，自己系统写入的反而差 8 小时；
-
前端凌晨提交的数据，业务日期莫名其妙变成了前一天；
-
有人往代码里写 `±8 hour` 的补丁，越补越乱。
这些现象的根子是同一回事。先说结论：**最根本的问题在环境------Linux 宿主机、Docker 容器、数据库实例的时区没有统一。如果这几层全都设置为 Asia/Shanghai（UTC+8），时区问题压根不会发生。** 应用层的各种转换和补丁，都是在为环境的不统一买单。
二、根因分层：环境是根，字面值是放大器
2.1 最根本的一层：环境时区不一致
一个典型的翻车现场长这样：
| 层 | 实际时区 | 说明 |
|----|----------|------|
| Linux 宿主机 | Asia/Shanghai | 麒麟 v10，装系统时设过 |
| **Docker 容器** | **UTC（默认）** | 镜像没设 `TZ`，也没挂 `/etc/localtime`，**这是最常见的病根** |
| 数据库实例 | 跟容器走 = UTC | `CURRENT_TIMESTAMP` 按 UTC 算 |
| 应用 JVM | Asia/Shanghai | 启动参数或代码里设过 |
于是同一个"现在"，数据库算出来比 Java 算出来慢 8 小时。谁写入用 `CURRENT_TIMESTAMP`、谁写入用 Java 时间，决定了这一行差不离 8 小时。
2.2 第二层：`timestamp` 是无时区字面值
PG 系的 `timestamp`（即 `timestamp without time zone`）存的是**无时区字面值**------数据库列本身只记"2026-10-22 12:30:00"这串数字，不负责任何时区换算。环境不一致时，各条链路就各自做时区解释，互相打架：
```text
链路 A：DEFAULT CURRENT_TIMESTAMP → 跟 DB 会话时区（容器常为 UTC）
链路 B：Java Date + 自动填充 → 跟 JVM 时区 + JDBC 会话时区
链路 C：ETL / 消息队列字面量直写 → 上游给几点存几点（所以常"看起来正常"）
显示 D：Navicat / 客户端 → 用自己的会话时区再"解释"一次
```
同表不同行差 8 小时，就是 A、B 两条写入链路混用的结果；Navicat 再按自己的会话时区显示一遍，偏差又被放大或"修复"，让人彻底晕头转向。
2.3 叠加因素：模式切换会放大问题
如果现场同时在做 **MySQL 兼容模式 → PG 模式** 的切换，时间语义与对象模型一起变化，导入脚本反复失败重跑，"时区问题"会显得越来越严重------这时要先收口模式转换报错，再处理时区，顺序不能反（详见姊妹篇）。
三、根治方案（首选）：把环境全部设为 Asia/Shanghai
**这是最便宜、最彻底、最该先做的一步。** 环境统一后，`CURRENT_TIMESTAMP` 和 Java 时间天然同口径，§2.2 的四条链路全部自动对齐，什么都不用改。
3.1 Linux 宿主机
```bash
timedatectl set-timezone Asia/Shanghai
date # 验证：应显示 CST 北京时间
```
3.2 Docker 容器（最关键的一层）
容器**不继承**宿主机时区，必须显式设置。先分清两件事：容器与宿主机**共享同一个内核 UTC 时钟**------宿主机 NTP / chronyd 校时后，容器时间数值自动就是准的，容器内**禁止**再装 ntpd / chronyd（默认无 `CAP_SYS_TIME` 权限，必然报错且与宿主机冲突）；但"时间数值一致"不等于"时区一致"------内核只维护 UTC，时区是各进程基于 tzdata / `TZ` 的**本地展示翻译规则**，容器需要自己的规则。一句话分工：**校时归宿主机，时区归容器与数据库各自配置。**
宿主机若用 `ntpdate` 每日跳变式校准，建议升级为 `chronyd` 常驻平滑校时（slew），避免时钟回拨导致数据库日志/时间戳"时间倒流"。
时区两种配置方式（二选一，推荐方案 A）：
**方案 A（通用稳妥，适配所有镜像含 alpine）**：挂载宿主机**真实时区文件**（不要挂 `/etc/localtime` 软链接本身），并同时设 `TZ`：
```bash
docker run -e TZ=Asia/Shanghai \
-v /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime:ro \
...
```
docker-compose 写法：
```yaml
services:
kingbase:
image: <kingbase-image>
environment:
TZ: Asia/Shanghai
volumes:
- /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime:ro
```
**方案 B（简洁无挂载，仅限自带 tzdata 的镜像）**：只设 `TZ=Asia/Shanghai`。Kingbase / PostgreSQL / MySQL 官方镜像均内置 tzdata，进程时区遵循 `TZ`（glibc 读取顺序：`TZ` 环境变量 > `/etc/localtime` 文件），干净无挂载依赖。
**避坑要点**：
-
**不要直接挂 `/etc/localtime`**：麒麟 v10 / CentOS 7+ / Ubuntu / openEuler 上它是**软链接**（指向 `../usr/share/zoneinfo/...`），`-v /etc/localtime:/etc/localtime:ro` 在部分 Docker 版本、Docker Desktop 等环境会把**链接本身**挂进容器，链接目标在容器内不存在 → 时区静默失效。统一改挂真实文件最稳妥；
-
alpine 类精简镜像没有内置 tzdata，只设 `TZ` 不生效：要么镜像内 `apk add --no-cache tzdata`，要么按方案 A 挂载真实时区文件；
-
**存量数据卷特别注意**：Kingbase / PG 系数据库在 initdb（初始化数据目录）时已把探测到的时区**固化进配置文件**（`kingbase.conf` 里 `timezone = 'UTC'`）。已有 UTC 数据卷的容器，就算重建时设了 `TZ`、挂了时区文件，`SHOW timezone` 仍读配置里的旧值------必须再执行 §3.3 的 `ALTER DATABASE ... SET timezone`（或改配置 + reload）才会变；`TZ` 只在**全新数据卷首次 initdb** 时被采纳。
验证：
```bash
docker exec <容器名> date # 应显示 CST 北京时间，与宿主机一致
```
已运行的容器改挂载/环境变量需要重建（`docker compose up -d` 重建）------**这只是容器重建，不是数据库重建，数据卷不受影响**。
3.3 数据库实例
```sql
-- 库级设置（新会话生效）
ALTER DATABASE your_db SET timezone TO 'Asia/Shanghai';
-- 或实例级：kingbase.conf / postgresql.conf 中
-- timezone = 'Asia/Shanghai'
```
3.4 JVM
```bash
java -Duser.timezone=Asia/Shanghai -jar app.jar
```
3.5 验证四连（每层都对才算完）
```bash
date # 宿主机：CST 北京时间
docker exec <容器名> date # 容器：CST 北京时间
```
```sql
SHOW timezone; -- 数据库会话：Asia/Shanghai
SELECT now(); -- 当前北京时间
```
3.6 环境统一后的直接收益：看数据不再猜口径
环境统一最直观的好处，往往被低估：
-
**Navicat / DBeaver / 任何客户端打开，看到的就是北京时间**------库里存的字面值就是东八区墙上时钟，不再需要在脑子里做 +8 换算；
-
**新人接手零困惑**：查一条数据，`create_time` 就是这条记录真实的创建时刻，不用先问"这列是 UTC 还是东八区？"，也不会看着"差 8 小时"的时间误以为数据错了去乱修；
-
**排查问题不用三方对照**：接口、SQL 结果、客户端显示天然一致，§六 P1 那套诊断方法基本用不上；
-
**写 SQL 做统计、导数据给别组**：`DATE(create_time)` 就是业务日，不用先搞清楚会话时区再解释结果。
一句话：**时间列自解释，是全系统最便宜的可维护性投资。**
3.7 环境统一后还要做什么
环境统一后，`DEFAULT CURRENT_TIMESTAMP` 与 Java 填充在数值上一致了，但**双源写入仍是隐患**------容器换个基础镜像、迁移到新环境、换个部署方式，UTC 默认值就可能悄悄回来。所以新建表仍建议遵守 §五 的规范：时间字段单一写入来源，DDL 不写 `DEFAULT CURRENT_TIMESTAMP`。
四、总原则（两条铁律）
-
**环境先行**：Linux / Docker / 数据库实例 / JVM 全部 Asia/Shanghai，这是根。
-
**每个时间字段只保留一个写入来源**：推荐统一由应用层（MyBatis-Plus `MetaObjectHandler`）填充，消灭双源。
以及一条禁令：**禁止在业务代码里写 `±8 hour` 补丁**。那是治标不治本，还会让后来人无法判断某列到底是什么口径。
五、新建项目：强制规范（环境统一 + 链路一致）
5.0 环境先行
按 §三 把宿主机、容器、数据库实例、JVM 全部设为 Asia/Shanghai，验证四连通过后再谈代码。
5.1 JDBC URL（每个数据源都要）
```yaml
url: jdbc:postgresql://<host>:54321/<db>?currentSchema=public&options=-c%20TimeZone%3DAsia/Shanghai
```
`options=-c TimeZone=Asia/Shanghai`（URL 编码形式）把数据库会话时区锁死，是环境之外的第二道保险。多数据源（dynamic-datasource）场景下**每一个 url 都要追加**。
5.2 JVM
```bash
java -Duser.timezone=Asia/Shanghai -jar app.jar
```
或在启动类 `main` 方法最前面：
```java
TimeZone.setDefault(TimeZone.getTimeZone("Asia/Shanghai"));
```
5.3 Jackson
```yaml
spring:
jackson:
time-zone: GMT+8
date-format: yyyy-MM-dd HH:mm:ss
```
BO/VO 的日期字段同时加注解（前后端 JSON 进出统一东八区）：
```java
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Shanghai")
private LocalDateTime createTime;
```
5.4 DDL
```sql
-- 正确：无 DEFAULT，应用层填充
"create_time" timestamp(0) NOT NULL,
"update_time" timestamp(0) NOT NULL
-- 错误：与 Java 填充形成双源写入，环境一变就分叉
"create_time" timestamp(0) DEFAULT CURRENT_TIMESTAMP
```
5.5 Java 类型
-
新代码一律 `LocalDateTime`，不要再用 `java.util.Date` 做时间计算；
-
`LocalDate` / `LocalDateTime` 必须转 `Date` 的场景，显式指定时区，不要依赖 `ZoneId.systemDefault()`（生产容器经常是 UTC）：
```java
// 推荐
Date date = Date.from(localDateTime.atZone(ZoneId.of("Asia/Shanghai")).toInstant());
// 避免
Date date = Date.from(localDateTime.atZone(ZoneId.systemDefault()).toInstant());
```
5.6 前端
-
**禁止**用 `toISOString().split('T')0` 当业务日期------那是 UTC 日期，东八区凌晨会差一天；
-
日期范围选择器用 `value-format="YYYY-MM-DD"`，业务日按本地日历日格式化后传参；
-
`toISOString()` 只留给与"业务日历日"无关的绝对时刻（如日志时间戳）。
六、老项目整改：P0 → P4，按顺序来
| 阶段 | 内容 | 风险 | 动历史数据？ |
|------|------|------|--------------|
| **P0** | **环境统一（§三）** + JDBC URL + Navicat 统一东八区 | 低 | 否 |
| **P1** | 诊断：接口 vs `::text` vs Navicat 三方对照 | 无 | 否 |
| **P2** | 止血：新需求禁写 `±8h`；新表去掉 `DEFAULT CURRENT_TIMESTAMP` | 低 | 否 |
| **P3** | 存量表 `DROP DEFAULT`；实体逐步 `Date` → `LocalDateTime` | 中 | 否（仅结构/代码） |
| **P4** | 历史数据修正（仅接口也错且业务书面确认） | 高 | **是（须审批）** |
P0：环境与配置统一（第一步，必做）
先做 §三 的环境四件套（宿主机 / 容器 / 实例 / JVM），再按 §5.1 补齐 JDBC `options`，重启应用；Navicat 连接属性的时区设为 `Asia/Shanghai`。验证：
```sql
SHOW timezone;
SELECT current_setting('TimeZone');
SELECT now(); -- 应为当前北京时间
```
**很多现场走完这一步，"差 8 小时"就消失了大半**------因为病根本来就在容器 UTC。
P1：诊断（不动数据）
三方对照法：
```sql
SELECT id, create_time, create_time::text
FROM your_table
ORDER BY id DESC
LIMIT 5;
```
-
**接口返回值**（应用实际读写结果）；
-
**`create_time::text`**（数据库存的字面值，绕开客户端时区解释）；
-
**Navicat 显示**（客户端解释后的值）。
三者一对照，问题在哪一层立刻现形：**只看 Navicat 就做结论，是这个领域翻车率最高的动作**。双源写入的表要单独抽样，看是不是"一部分行 UTC、一部分行东八区"。
应用侧验证（每条必做）：新增一条记录，记下操作时刻 → 接口返回的时间与操作时刻一致 → 库中 `::text` 与接口一致 → Navicat 显示与 `::text` 一致。
P2：止血
-
新需求代码评审加一条：出现 `±8`、`-8 hour`、`+ interval '8 hours'` 一律打回；
-
新建表 DDL 评审：`create_time`/`update_time` 不得带 `DEFAULT CURRENT_TIMESTAMP`。
P3：存量结构与代码
```sql
ALTER TABLE your_table ALTER COLUMN create_time DROP DEFAULT;
ALTER TABLE your_table ALTER COLUMN update_time DROP DEFAULT;
```
实体逐步 `Date` → `LocalDateTime`（随需求迭代顺带改，不搞大爆炸式重构）；`MetaObjectHandler` 确认用 `LocalDateTime.now()` 填充，且对所有实体生效（包括不继承公共基类的那些）。
P4：历史数据修正（最后的手段，须审批）
**大多数现场走完 P0~P3 就不需要改历史数据了**------链路一致后，"差 8 小时"往往只是显示层的误会。确需修正时，纪律如下：
-
触发条件：**接口/报表也固定差 8h** 且业务书面确认"应以东八区墙上时钟为准"；
-
修正前：备份 + 抽样 20 条人工核对 + 写好对账记录；
-
SQL 按主键范围分批、可回滚，禁止全表一把梭 `UPDATE ... + interval '8 hours'`；
-
**第三方同步表/字段单独评审**，不得与本系统字段同一脚本批量 +8h------上游给的可能本来就是东八区墙上时钟，加 8 小时就毁了。
七、环境动不了时的退路：应用层全链路转换
7.1 适用场景
只有一种情况该走这条路：**环境/数据库配置确实改不了**------多方共用实例、DBA 不配合、老系统已上线且生产数据量大、容器重建窗口批不下来。典型约束现场：Docker 装的 KingbaseES 固定在 UTC，宿主机和应用都是东八区，数据库配置不允许动，只能在应用层硬扛。
7.2 核心思路
在应用层统一做双向转换：
-
**存储**：Asia/Shanghai → UTC，写入数据库；
-
**读取**：UTC → Asia/Shanghai，返回前端；
-
**查询**：查询条件同样先转 UTC 再比较。
7.3 工具类方法表
封装一个 `TimeZoneUtils`，核心方法：
| 方法 | 功能 | 使用场景 |
|------|------|----------|
| `toDbTime(Date)` | 东八区 Date → UTC Date | 存储前 |
| `toAppTime(Date)` | UTC Date → 东八区 Date | 读取后 |
| `parseAppDateToDbTime(String)` | 东八区日期字符串 → UTC Date | 前端传日期字符串需存储 |
| `formatDbTimeToAppDate(Date)` | UTC Date → 东八区日期字符串 | 读取日期返回前端 |
| `parseAppDateTimeToDbTime(String)` | 东八区日期时间字符串 → UTC Date | 前端传日期时间需存储 |
| `formatDbTimeToAppDateTime(Date)` | UTC Date → 东八区日期时间字符串 | 读取日期时间返回前端 |
| `formatAppDateToDbDateStr(Date)` | 东八区 Date → UTC 日期字符串 | Mapper XML 查询条件 |
| `getNowAppTime()` | 当前东八区时间 | 需要"现在"时 |
7.4 三个典型场景
**场景 1：存储**
```java
// Service 层 insertByBo
if (bo.getCommissioningDate() != null) {
// 东八区 → UTC，再入库
entity.setCommissioningDate(TimeZoneUtils.toDbTime(bo.getCommissioningDate()));
}
// create_time 同理：getNowAppTime() 再 toDbTime
```
**场景 2：读取**
```java
// Service 层 queryById
if (vo.getCommissioningDate() != null) {
// UTC → 东八区，再返回前端
vo.setCommissioningDate(TimeZoneUtils.toAppTime(vo.getCommissioningDate()));
}
```
**场景 3：查询条件**
```java
// Service 层：查询条件先转 UTC
if (bo.getCommissioningDate() != null) {
bo.setCommissioningDate(TimeZoneUtils.toDbTime(bo.getCommissioningDate()));
}
// 结果集中的日期再逐条 toAppTime 转回
```
查询转换优先放在 Service 层（性能好、逻辑集中、便于单测）；确需在 SQL 层处理时，可用 `AT TIME ZONE`（金仓兼容 PostgreSQL 语法）：
```xml
AND t.commissioning_date = DATE(
(#{bo.commissioningDate} AT TIME ZONE 'Asia/Shanghai') AT TIME ZONE 'UTC'
)
```
**场景 4：日期字符串与创建时间**
```java
// 前端传日期字符串 "2026-02-01"：先转 UTC Date 再入库
Date dbDate = TimeZoneUtils.parseAppDateToDbTime(dateStr);
entity.setCommissioningDate(dbDate);
// create_time / update_time：取东八区"现在"，再转 UTC 存储
Date nowDbTime = TimeZoneUtils.toDbTime(TimeZoneUtils.getNowAppTime());
entity.setCreateTime(nowDbTime);
```
**配套约定**（与 §五 不冲突，仅适用于这条退路）：
-
BO/VO 的日期字段仍加 `@JsonFormat(timezone = "Asia/Shanghai")`，保证 JSON 进出按东八区解析/格式化；
-
Entity 不加时区注解，保持简洁，转换全部集中在 Service 层；
-
日期范围查询：开始日期和结束日期**都要**转 UTC 再比较，漏转一端结果就错。
7.5 日期边界问题（最容易漏）
`2026-02-01 00:00:00`（东八区）= `2026-01-31 16:00:00`（UTC）------**日期部分变了**。按日期查询/统计时如果直接拿转换后的值等值比较，边界记录会错位。处理：日期字段用 `DATE()` 函数只比较日期部分，或转换时保持日期部分不变、只调整时间部分，并在单元测试里专门覆盖 `00:00:00` 边界。
7.6 测试要求
-
**单元测试**：`TimeZoneUtils` 各方法 + 日期边界（`00:00:00`、`23:59:59`）；
-
**集成测试**：存一条、读一条、查一条，三方核对；
-
**回归测试**：确保转换改造不影响未改造的老功能。
7.7 为什么说它只是退路
这套方案能跑，但代价是真实的：
-
**转换逻辑散落在每个 Service 方法里，漏一处就是一个 bug**；新人不知道这个约定，新功能直接写错；
-
**库里存的永远是 UTC**------这是最容易被忽视的隐性代价：Navicat 里看数据永远"差 8 小时"，每次查库都要心算换算；新人接手看到时间以为数据错了，照着"修"反而制造新问题；给其他组导数、写临时 SQL 统计，每个人都得先被科普一遍口径；
-
一旦将来环境放开了（容器重建、DBA 同意改配置），这套代码又变成**必须拆除的技术债**，而且拆除时还要处理"库里既有 UTC 又有东八区"的混合数据。
与 §3.6 对照着看就很清楚：环境统一是"一次配置，处处自解释"；应用层转换是"处处写代码，还换不来一个能直接看懂的库"。能用 §三 + §六 的环境统一方案，就不要选这条路。
八、外部接口字段：单独的纪律
第三方推送、消息队列、总部接口写入的时间字段，是另一个翻车高发区：
-
**单独命名**（如 `xxx_collect_time`），不要与 `create_time` 混用同一套自动填充；
-
**DDL 注释写明上游口径**："上游为东八区墙上时钟"还是"UTC"，以官方接口文档为唯一依据；
-
**禁止无依据的 ±8h 换算**：对接前先留存最底层原始报文（日志/抽样/临时表），对照"原始值 → 解析值 → 落库值"三者后再写转换逻辑；
-
排错时同样原始报文优先，不要只凭加工后的界面或库内结果推断接口语义。
九、上线前检查清单
**环境（根）**：
-
Linux 宿主机 `date` 显示 CST 北京时间
-
Docker 容器 `docker exec <容器> date` 显示 CST 北京时间（方案 A：挂真实文件 `/usr/share/zoneinfo/Asia/Shanghai:/etc/localtime:ro`；或方案 B：镜像含 `tzdata` 时只设 `TZ`；**未**直接挂 `/etc/localtime` 软链接）
-
`SHOW timezone` 返回 Asia/Shanghai，`SELECT now()` 为北京时间
-
JVM 含 `-Duser.timezone=Asia/Shanghai`
**链路（本）**：
-
每个数据源 JDBC URL 含 `options=-c TimeZone=Asia/Shanghai`
-
Jackson 时区 `GMT+8`，BO/VO 日期字段有 `@JsonFormat(timezone = "Asia/Shanghai")`
-
全库无 `DEFAULT CURRENT_TIMESTAMP`（或已有下线计划），时间字段单一写入来源
-
新代码用 `LocalDateTime`，`LocalDateTime`→`Date` 显式 `ZoneId.of("Asia/Shanghai")`
-
代码扫描无 `±8 hour` 补丁；前端无 `toISOString()` 截取业务日
-
外部接口时间字段单独命名、DDL 注释写明上游口径
-
三方对照法验证：接口 = `::text` = Navicat
-
历史数据修正（如有）已过审批、有备份、可回滚
十、写在最后
时区问题最讨厌的地方在于：**它平时不报错，只在展示和跨天统计时悄悄出错**。绝大多数"差 8 小时"的病根不是代码，而是环境------一个没设 `TZ` 的 Docker 容器就够了。所以行动顺序永远是：**先把 Linux、容器、数据库、JVM 全部拨到 Asia/Shanghai，再谈代码规范；环境统一了，剩下的大多数问题会自然消失。** 而且这份投入会直接回馈到日常：Navicat 打开就是北京时间，新人接手看数据一眼就懂，不用再猜口径、不用心算换算。应用层转换留给真正动不了环境的场景，历史数据能不碰就不碰。
十一、参考资料
-
PostgreSQL 12 官方文档：Date/Time Types(https://www.postgresql.org/docs/12/datatype-datetime.html)
-
PostgreSQL 12 官方文档：AT TIME ZONE 与时区函数(https://www.postgresql.org/docs/12/functions-datetime.html)
-
Docker 官方文档：容器时区与 TZ 环境变量(https://docs.docker.com/)
-
KES V9R1 官方文档站（人大金仓）(https://docs.kingbase.com.cn/cn/KES-V9R1C10)
-
姊妹篇：金仓 KingbaseES 兼容模式（DB_MODE）实战指南(./kingbase-dbmode-guide-blog.md)------模式切换与时区问题互相放大时的处理顺序