Docker 컨테이너 시간이 실제 시간과 다를 때 TZ 설정을 확인해야 하는 이유

시놀로지 NAS에서 Docker 컨테이너를 사용하다 보면 NAS의 시간은 정확한데 컨테이너 내부의 시간만 다르게 표시되는 경우가 있습니다.

예를 들어 DSM에서는 현재 시간이 오전 10시로 표시되는데 Docker 컨테이너에서 확인하면 오전 1시로 표시되는 식입니다.

이런 상황에서는 시놀로지 NAS의 시간 자체에 문제가 있다고 생각하기 쉽습니다. 하지만 실제로는 Docker 컨테이너의 시간대(Time Zone)가 다르게 설정되어 발생하는 경우가 많습니다.

특히 컨테이너 로그의 시간이 실제 오류 발생 시간과 다르거나 예약 작업이 예상하지 않은 시간에 실행된다면 TZ 설정을 먼저 확인하는 것이 좋습니다.

Docker 컨테이너의 시간이 다른 이유

Docker 컨테이너는 시놀로지 NAS에서 실행되지만 컨테이너 내부에는 별도의 실행 환경이 존재합니다.

따라서 NAS의 시스템 시간과 컨테이너에서 애플리케이션이 사용하는 시간대가 서로 다를 수 있습니다.

특히 일부 Docker 이미지는 기본적으로 UTC를 기준으로 동작합니다.

한국의 시간대는 KST이며 UTC보다 9시간 빠릅니다.

따라서 컨테이너가 UTC를 기준으로 시간을 표시한다면 다음과 같은 차이가 발생할 수 있습니다.

시놀로지 NAS

오전 10시

Docker 컨테이너

오전 1시

정확하게 9시간 차이가 발생한다면 시간 자체가 틀렸다기보다 시간대 설정이 서로 다른 상황일 가능성이 높습니다.

UTC와 KST의 차이를 알아야 한다

Docker 시간 문제를 이해하려면 UTC와 KST의 차이를 알아야 합니다.

UTC는 세계 표준시이고 KST는 한국 표준시입니다.

한국은 UTC보다 9시간 빠릅니다.

따라서 UTC 01:00은 KST 10:00입니다.

Docker 컨테이너가 UTC로 설정되어 있다면 한국에서 사용하는 NAS의 시간보다 항상 9시간 느리게 보일 수 있습니다.

따라서 컨테이너 시간이 정확히 9시간 차이 난다면 NTP나 시놀로지 시스템 시간부터 의심하기보다는 TZ 설정을 확인하는 것이 먼저입니다.

TZ는 무엇을 의미할까?

Docker에서 자주 사용하는 TZ는 Time Zone, 즉 시간대를 지정하는 환경변수입니다.

한국 시간대를 사용해야 하는 컨테이너라면 다음과 같이 설정할 수 있습니다.

environment:
  TZ: Asia/Seoul

Docker Compose에서는 일반적으로 다음과 같은 형태로 작성합니다.

services:
  app:
    image: example/app
    environment:
      TZ: Asia/Seoul

이렇게 설정하면 해당 설정을 지원하는 애플리케이션에서 Asia/Seoul 시간대를 사용할 수 있습니다.

다만 중요한 점이 있습니다.

TZ 환경변수를 추가했다고 모든 Docker 애플리케이션의 시간이 자동으로 변경되는 것은 아닙니다.

Docker 이미지와 애플리케이션이 TZ 환경변수를 어떻게 처리하는지에 따라 실제 동작이 달라질 수 있습니다.

시놀로지 NAS 시간이 정상인데 Docker만 다를 수 있다

시간 문제가 발생하면 가장 먼저 DSM의 날짜와 시간을 확인하는 경우가 많습니다.

DSM에서 시간이 정확하다면 NAS 자체의 시스템 시간은 정상일 가능성이 높습니다.

이 상태에서 Docker 컨테이너의 시간만 다르다면 다음과 같은 항목을 확인해야 합니다.

컨테이너의 TZ 환경변수

Docker 이미지의 기본 시간대

애플리케이션의 시간대 설정

데이터베이스의 시간 처리 방식

즉, NAS의 시간이 정확하더라도 컨테이너가 다른 시간대를 사용할 수 있습니다.

Container Manager에서 TZ 설정을 확인한다

시놀로지 Container Manager를 이용해 컨테이너를 생성했다면 해당 컨테이너의 환경변수를 확인할 필요가 있습니다.

환경변수 목록에서 TZ가 있는지 확인하고 현재 사용해야 하는 시간대가 설정되어 있는지 확인합니다.

한국에서 사용할 서비스라면 일반적으로 다음과 같은 값을 사용할 수 있습니다.

TZ=Asia/Seoul

다른 시간대가 지정되어 있다면 컨테이너 내부의 시간이 실제 사용하는 지역 시간과 다르게 표시될 수 있습니다.

TZ를 설정했는데도 시간이 바뀌지 않는 이유

TZ=Asia/Seoul을 설정했는데도 애플리케이션의 시간이 그대로라면 몇 가지 가능성을 생각해 볼 수 있습니다.

가장 먼저 컨테이너가 변경된 환경변수를 실제로 적용했는지 확인해야 합니다.

Compose 파일이나 Container Manager의 설정만 변경하고 기존 컨테이너가 그대로 실행되고 있다면 변경 사항이 실제 컨테이너에 반영되지 않았을 수 있습니다.

이 경우 환경에 따라 컨테이너를 다시 생성하거나 재배포해야 할 수 있습니다.

또한 애플리케이션 자체에서 별도의 시간대를 설정하고 있을 수도 있습니다.

애플리케이션 자체의 시간대도 확인해야 한다

Docker 컨테이너 내부의 시간이 정상인데 애플리케이션 화면에서 표시되는 시간만 다르다면 TZ만의 문제가 아닐 수 있습니다.

예를 들어 컨테이너 자체는 한국 시간으로 설정되어 있지만 애플리케이션이 내부적으로 UTC를 사용하도록 설정되어 있을 수 있습니다.

이 경우에는 Docker의 시간대와 애플리케이션의 시간대를 각각 확인해야 합니다.

특히 서버 프로그램이나 데이터베이스를 사용하는 서비스에서는 이런 차이가 발생하기 쉽습니다.

데이터베이스 시간대도 확인해야 한다

Docker에서 데이터베이스를 사용하는 경우에는 시간 문제를 조금 더 복잡하게 확인해야 합니다.

예를 들어 다음과 같은 구조를 생각할 수 있습니다.

웹 애플리케이션

↓

데이터베이스

웹 애플리케이션은 KST를 사용하고 있는데 데이터베이스는 UTC를 기준으로 데이터를 처리할 수 있습니다.

그러면 사용자가 보는 시간과 데이터베이스에 저장된 시간이 서로 다르게 보일 수 있습니다.

따라서 Docker에서 데이터베이스를 운영한다면 애플리케이션의 TZ뿐만 아니라 데이터베이스의 시간대 처리 방식도 함께 확인해야 합니다.

로그 시간이 실제 시간과 다르게 표시되는 경우

Docker 컨테이너의 시간대가 잘못 설정됐을 때 가장 먼저 발견하기 쉬운 부분이 로그입니다.

예를 들어 실제 오류가 오전 10시에 발생했는데 로그에는 오전 1시로 기록될 수 있습니다.

한국 시간과 UTC의 차이가 9시간이기 때문입니다.

이런 상황에서 로그 시간만 보고 장애 발생 시간을 판단하면 문제의 원인을 찾는 과정에서 혼란이 생길 수 있습니다.

특히 장기간 운영하는 NAS에서는 로그의 시간 정보가 정확하게 기록되는 것이 중요합니다.

예약 작업이 잘못된 시간에 실행될 수 있다

시간대 설정은 단순히 화면에 표시되는 시간에만 영향을 주는 것이 아닙니다.

일부 Docker 애플리케이션은 특정 시간을 기준으로 자동 작업을 실행합니다.

예를 들어

매일 오전 3시 백업

매일 자정 데이터 정리

특정 시간 자동 다운로드

주기적인 작업 실행

등이 있습니다.

이런 프로그램이 UTC를 기준으로 동작하고 있는데 사용자는 KST 기준으로 시간을 설정했다고 생각한다면 작업이 예상하지 않은 시간에 실행될 수 있습니다.

따라서 자동 예약 기능을 사용하는 Docker 컨테이너라면 시간대 설정을 더욱 주의해야 합니다.

Cron 작업에서도 시간대가 중요하다

일부 컨테이너에서는 Cron이나 자체 스케줄러를 이용해 작업을 실행합니다.

사용자가 한국 시간 기준으로 오전 9시에 작업하도록 설정했더라도 컨테이너 환경이 UTC로 구성되어 있다면 실제 실행 시간이 달라질 수 있습니다.

다만 Cron의 동작 방식은 사용하는 이미지와 환경에 따라 다를 수 있으므로 TZ 하나만 변경하면 모든 예약 작업이 해결된다고 판단해서는 안 됩니다.

실제로 작업을 담당하는 프로그램의 시간대 설정도 확인해야 합니다.

파일 생성 시간이 다르게 보이는 경우

Docker 컨테이너에서 생성한 파일의 시간 정보가 NAS에서 보는 시간과 다르게 나타나는 경우도 있습니다.

예를 들어 컨테이너에서 파일을 생성한 시간과 NAS의 파일 관리 화면에서 표시되는 시간이 서로 다르게 보일 수 있습니다.

이 경우에도 파일 시스템 자체의 문제라고 단정하기보다 시간대 변환이나 애플리케이션의 시간 처리 방식을 확인하는 것이 좋습니다.

특히 백업이나 자동 파일 생성 서비스를 Docker로 운영한다면 파일의 생성 시간과 수정 시간이 중요한 기준이 될 수 있습니다.

모든 Docker 컨테이너를 Asia/Seoul로 설정해야 할까?

반드시 그런 것은 아닙니다.

한국에서 사용하는 NAS라고 해서 모든 Docker 컨테이너가 무조건 Asia/Seoul을 사용해야 하는 것은 아닙니다.

서비스에 따라 UTC를 사용하는 것이 더 적합할 수도 있습니다.

특히 여러 서버나 여러 지역에서 사용하는 서비스에서는 데이터를 UTC 기준으로 저장하고 사용자에게 보여줄 때 지역 시간으로 변환하는 방식을 사용할 수 있습니다.

따라서 중요한 것은 무조건 한국 시간으로 변경하는 것이 아니라 해당 애플리케이션이 어떤 시간대를 기준으로 동작해야 하는지 결정하는 것입니다.

시간 동기화와 시간대 설정은 다르다

Docker 시간 문제에서 가장 많이 혼동하는 부분입니다.

시간 동기화

현재 시간이 실제 시간과 맞는지를 의미합니다.

시간대 설정

현재 시간을 어느 지역의 시간으로 표시할지를 의미합니다.

예를 들어 컨테이너 시간이 정확하게 9시간 느리다면 시간 자체가 틀린 것이 아니라 UTC와 KST의 차이일 가능성이 높습니다.

반면 몇 분 또는 몇 초 정도 시간이 어긋난다면 NTP와 같은 시간 동기화 문제를 확인할 필요가 있습니다.

NTP 문제와 TZ 문제를 구분해야 한다

시놀로지 NAS의 시간이 정확한데 Docker 컨테이너만 9시간 느리다면 NTP보다는 시간대 설정을 먼저 확인하는 것이 합리적입니다.

반대로 DSM 자체의 시간이 잘못되어 있다면 Docker 컨테이너뿐만 아니라 NAS의 다른 서비스에서도 시간 문제가 나타날 가능성이 있습니다.

따라서 다음 순서로 확인하면 원인을 구분하기 쉽습니다.

DSM 시간 확인

↓

Docker 컨테이너 시간 확인

↓

시간 차이 확인

↓

TZ 설정 확인

Docker Compose에서 TZ 설정할 때 주의할 점

Docker Compose를 사용하는 경우 다음과 같이 설정할 수 있습니다.

services:
  app:
    image: example/app
    environment:
      TZ: Asia/Seoul

여기서 TZ는 environment 아래에 들어가야 합니다.

YAML에서는 들여쓰기가 설정의 구조를 결정하기 때문에 위치가 잘못되면 원하는 환경변수가 서비스에 적용되지 않을 수 있습니다.

예를 들어 다음처럼 작성하면 구조가 달라집니다.

services:
  app:
    image: example/app
  environment:
    TZ: Asia/Seoul

따라서 Docker Compose 파일에 TZ를 추가할 때는 기존 환경변수의 들여쓰기와 동일한 수준에 맞춰 작성하는 것이 중요합니다.

TZ 변경 후 컨테이너를 다시 확인해야 한다

시간대 설정을 변경했다면 실제 실행 중인 컨테이너에 변경 사항이 적용됐는지 확인해야 합니다.

특히 Docker Compose나 Container Manager에서 환경변수를 수정한 경우 구성에 따라 기존 컨테이너를 재생성하거나 다시 배포해야 할 수 있습니다.

설정 파일만 수정하고 컨테이너를 그대로 실행하고 있다면 변경된 TZ가 적용되지 않을 수 있습니다.

따라서 설정 변경 후에는 실제 컨테이너에서 시간이 제대로 변경됐는지 확인하는 것이 좋습니다.

컨테이너 시간 문제 확인 순서

Docker 컨테이너의 시간이 실제 시간과 다르다면 다음 순서로 확인하면 됩니다.

1. DSM의 시간이 정확한지 확인합니다.

먼저 시놀로지 NAS 자체의 시스템 시간이 정상인지 확인합니다.

2. 컨테이너의 시간을 확인합니다.

Docker 컨테이너 내부에서 표시되는 시간이 실제 시간과 얼마나 차이 나는지 확인합니다.

3. 시간 차이를 확인합니다.

정확하게 9시간 차이가 난다면 UTC와 KST의 차이를 의심할 수 있습니다.

4. TZ 환경변수를 확인합니다.

TZ=Asia/Seoul 등 현재 필요한 시간대가 설정되어 있는지 확인합니다.

5. 애플리케이션의 시간대 설정을 확인합니다.

애플리케이션 자체에서 별도의 시간대를 사용하는지 확인합니다.

6. 데이터베이스의 시간 처리 방식을 확인합니다.

DB를 사용하는 서비스라면 데이터베이스의 시간대도 확인합니다.

7. 예약 작업을 확인합니다.

Cron이나 스케줄러가 예상한 시간에 실행되는지 확인합니다.

8. 변경된 설정이 실제 컨테이너에 적용됐는지 확인합니다.

필요한 경우 컨테이너를 재생성하거나 재배포합니다.

무조건 TZ를 변경하면 안 되는 이유

컨테이너 시간이 다르다고 해서 무조건 Asia/Seoul로 변경하는 것도 주의해야 합니다.

일부 애플리케이션은 UTC를 기준으로 동작하도록 설계되어 있습니다.

이런 서비스의 시간대를 임의로 변경하면 로그뿐만 아니라 예약 작업이나 데이터 처리 방식에 영향을 줄 수 있습니다.

따라서 먼저 현재 애플리케이션이 어떤 시간대를 기준으로 동작하도록 설계되어 있는지 확인한 다음 변경하는 것이 좋습니다.

마무리

시놀로지 NAS에서 Docker 컨테이너의 시간이 실제 시간과 다르게 표시된다면 가장 먼저 TZ(Time Zone) 설정을 확인하는 것이 좋습니다.

특히 NAS의 시간은 정확한데 Docker 컨테이너만 정확히 9시간 느리다면 UTC와 KST의 시간대 차이를 의심할 수 있습니다.

Docker Compose에서는 다음과 같이 시간대를 지정할 수 있습니다.

environment:
  TZ: Asia/Seoul

하지만 TZ 설정만으로 모든 시간 문제가 해결되는 것은 아닙니다.

Docker 컨테이너 자체의 시간대와 애플리케이션의 시간대가 다를 수 있고, 데이터베이스나 예약 작업이 별도의 시간 기준을 사용할 수도 있기 때문입니다.

따라서 시간 문제가 발생했다면

DSM 시간 확인

컨테이너 시간 확인

UTC와 KST 차이 확인

TZ 환경변수 확인

애플리케이션 시간대 확인

데이터베이스 시간대 확인

예약 작업 확인

순서로 원인을 좁혀가는 것이 좋습니다.

특히 Docker Compose를 사용하는 경우 TZ 환경변수를 추가할 때 YAML의 들여쓰기까지 정확하게 확인해야 합니다.

결국 Docker 컨테이너 시간 문제의 핵심은 단순히 “Docker 시간이 틀렸다”고 생각하는 것이 아니라 시스템 시간과 시간대 설정을 구분해서 확인하는 것입니다.

시놀로지 NAS에서 Docker를 장기간 운영한다면 로그 시간, 파일 생성 시간, 예약 작업, 데이터베이스 기록 등이 서로 어긋나지 않도록 처음부터 시간대 설정을 명확하게 관리하는 것이 중요합니다.