Spring Boot Docker容器未同步宿主机时区问题排查

我尝试将Docker容器的本地时间设置为与宿主机一致，以便Spring Boot应用存储数据时使用。

Spring Boot代码片段 #

...
cpoWorkflowExecution.setStartDate(LocalDateTime.now());
...

宿主机配置 #

• 本地时间链接：

  [ainacio@brsp1nf01 cpo-dockers]$ ls -l /etc/localtime
  lrwxrwxrwx. 1 root root 39 Oct  6 07:42 /etc/localtime -> ../usr/share/zoneinfo/America/Sao_Paulo
  

• 时区文件内容：

  [ainacio@brsp1nf01 cpo-dockers]$ cat /etc/timezone 
  America/Sao_Paulo
  

容器状态 #

• 容器本地时间链接未生效：

  root@ffbd68eeaccd:/# ls -l /etc/localtime
  lrwxrwxrwx. 1 root root 27 Nov 17 13:37 /etc/localtime -> /usr/share/zoneinfo/Etc/UTC
  

• 容器时区文件已同步：

  root@ffbd68eeaccd:/# cat /etc/timezone 
  America/Sao_Paulo
  

Docker Compose配置 #

version: '3'
services:
    cpo-executor:
        container_name: cpo-executor
        image: .../cpo-executor:1.103.3.1
        ports:
          - 8879:8879
        environment:
          - TZ=America/Sao_Paulo
        volumes:
          - /etc/timezone:/etc/timezone:ro
          - /etc/localtime:/etc/localtime:ro
        networks:
          - cpo-network
        depends_on:
          - cpo-config-server

我使用Spring Boot Maven插件生成Docker镜像：

mvn spring-boot:build-image -DskipTests -Dspring-boot.build-image.imageName=.../cpo-executor:1.103.3.1

设置了TZ环境变量和挂载时区文件后仍无效，请问遗漏了什么配置？

1. 给JVM指定时区参数 #

Spring Boot应用的LocalDateTime.now()依赖JVM时区设置，即使系统时区正确，JVM可能仍默认使用UTC。在Docker Compose中添加JVM启动参数：

environment:
  - TZ=America/Sao_Paulo
  - JAVA_OPTS=-Duser.timezone=America/Sao_Paulo

或者在Spring Boot的application.properties/application.yml中补充配置：

spring.jackson.time-zone=America/Sao_Paulo

（注：后者主要影响JSON序列化，若要确保LocalDateTime.now()使用目标时区，优先设置JVM参数）

2. 直接挂载宿主机时区文件而非软链接 #

宿主机的/etc/localtime是软链接，部分容器镜像可能无法正确解析该链接。改为直接挂载宿主机的时区文件到容器：

volumes:
  - /usr/share/zoneinfo/America/Sao_Paulo:/etc/localtime:ro
  - /etc/timezone:/etc/timezone:ro

3. 构建镜像时指定时区（针对Spring Boot Maven插件） #

Spring Boot Maven插件基于Paketo Buildpacks，可通过构建参数在镜像阶段设置时区：

mvn spring-boot:build-image -DskipTests \
  -Dspring-boot.build-image.imageName=.../cpo-executor:1.103.3.1 \
  -DBP_ENVIRONMENT_VARIABLES=TZ=America/Sao_Paulo

或者在pom.xml中配置插件参数：

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <image>
      <env>
        <TZ>America/Sao_Paulo</TZ>
      </env>
    </image>
  </configuration>
</plugin>

4. 验证容器时间是否生效 #

进入容器执行以下命令，确认实际时间和时区：

# 查看系统时间
date
# 查看JVM时区
java -XshowSettings:properties -version 2>&1 | grep user.timezone

内容的提问来源于stack exchange，提问作者Aldo Inácio da Silva