容器里 date 少 8 小时:TZ 环境变量为什么有时候不生效
上周排查一个「日志时间对不上」的问题:同一个镜像在测试集群里 `date` 输出北京时间,迁到生产集群后变成 UTC,日志时间整体少 8 小时。运维同事已经把 `TZ=Asia/Shanghai` 加到了 Deployment 的 env 里,`/etc/localtime` 也挂载了,`date` 还是 UTC。这篇文章把这件事拆开讲清楚。
一、先确认「谁在决定时区」
Linux 里时间只有一个来源:内核维护的 UTC 时间戳。所有「本地时间」都是用户态转换出来的,转换依据是时区数据库,读取顺序大致是:
1. 环境变量 `TZ`(如果设置了,优先用它);
2. `/etc/localtime`(通常是 `/usr/share/zoneinfo/Asia/Shanghai` 的软链接或副本);
3. 都没有时,退化成 UTC。
看起来很简单,但容器里有三处容易出问题:
- **镜像里没有 tzdata**。glibc 有内置的时区解析,但 zoneinfo 文件是随 `tzdata` 包安装的。`TZ=Asia/Shanghai` 只是告诉运行时「用这个时区名」,名字查不到就直接退回 UTC,而且不报错。alpine 更明显,musl 的时区支持完全依赖 `/usr/share/zoneinfo` 目录,没有就是 UTC。
- **`/etc/localtime` 挂载的方式不对**。用 hostPath 把宿主机的 `/etc/localtime` 挂进来,看起来是「跟随宿主机」,实际上宿主机一换时区、或者节点本身是 UTC,容器就跟着变。而且它会把镜像里原本正常的时区文件覆盖成只读文件,后面想改都改不了。
- **应用自己有缓存**。JVM 在启动时读取一次 `TimeZone.getDefault()` 并缓存,之后改 `TZ` 或 `/etc/localtime` 都要重启进程才生效;这也是「改了配置没反应」最常见的原因。
二、四条排查命令
进容器按顺序跑:
```bash
date # 当前本地时间与 UTC 偏差
echo "$TZ" # TZ 到底设没设进去
ls -l /etc/localtime # 是软链接还是普通文件,指向哪
ls /usr/share/zoneinfo/Asia/Shanghai # 时区数据是否真的存在
```
如果第三条指向 `/usr/share/zoneinfo/Etc/UTC`,说明镜像被别的构建步骤写死了;如果第四条文件不存在,那 `TZ` 设了也是白设。
JVM 应用再加一条:
```bash
java -XshowSettings:properties -version 2>&1 | grep -i timezone
```
输出 `user.timezone = GMT` 或 `UTC` 就说明 JVM 没拿到正确时区。注意这个值不受容器内 `date` 影响——JVM 读的是 `/etc/localtime` 和环境变量,在启动那一刻定死。
三、正确的做法
推荐把时区写进镜像,而不是靠运行时挂载:
```dockerfile
FROM eclipse-temurin:17-jre
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
```
用 `ln -snf` 而不是 `cp`,是为了让 `/etc/localtime` 保持软链接;`/etc/timezone` 是 Debian 系工具读的,写上更一致。
只有运行时不方便改镜像时,才用挂载加环境变量的组合。两个注意点:一是 hostPath 的 `type: File` 必须写,否则节点上路径不存在时会自动建成目录,容器起来直接报错;二是 hostPath 依赖节点上有 zoneinfo,托管节点池的精简系统镜像不一定有,这时候老老实实改镜像。
四、几个容易被忽略的连带问题
- **CronJob 的时区**。Kubernetes 1.27 之后 `CronJob.spec.timeZone` 已经 GA,直接写 `Asia/Shanghai` 即可;老版本只能靠容器内 `TZ` 让 cron 自己解析,很容易出现「凌晨 2 点的任务下午 2 点跑」。
- **MySQL 的 TIMESTAMP 列**。它按连接时区做转换,`time_zone` 是 `SYSTEM` 时取的是 mysqld 进程的时区。容器化部署后 mysqld 从 CST 变 UTC,同一份数据读出来就少 8 小时,`DATETIME` 列反而不受影响。这也是「迁到容器后历史数据看着不对」的常见原因。
- **日志采集侧**。容器输出 UTC、采集端按本地时间加时间戳,两边拼出来的日志时间轴是错的。要么统一容器输出 UTC 并在展示层转换(推荐),要么全链路固定一个时区,别混着来。
五、结论
容器时区不是一个 `TZ` 环境变量能解决的事,它取决于「时区数据在不在」「转换发生在哪一层」「应用有没有缓存」。排查顺序固定为:`date` → `TZ` → `/etc/localtime` → zoneinfo 文件 → 应用自身时区。只要这五步走完,8 小时的问题基本一次定位。
- 点赞
- 收藏
- 关注作者
评论(0)