블로그 목록으로
소프트웨어

서버는 UTC, 업무는 한국 시간: 업무 시스템 날짜·시간대 설계와 9시간 밀림 버그 막는 법

클라우드 서버는 UTC, 업무는 KST로 돌아가면서 생기는 '9시간 밀림' 버그의 원인과, 시각·날짜 구분부터 집계·크론·테스트까지 시간대 설계 원칙을 정리합니다.

POLYGLOTSOFT 기술팀2026-11-097분 소요8
시간대UTC날짜처리클라우드업무시스템

클라우드로 옮기자 마감일이 하루 밀렸다

온프레미스에서 클라우드로 업무 시스템을 옮긴 뒤 가장 흔하게 나오는 문의는 "날짜가 하루씩 틀려요"입니다. 사내 서버는 대부분 한국 시간(KST, UTC+9)으로 설정돼 있지만 AWS·Vercel 같은 클라우드의 서버와 컨테이너는 기본이 UTC입니다. 같은 코드가 실행 환경만 바뀌어도 9시간 어긋난 결과를 냅니다.

대표 증상은 다음과 같습니다.

  • 자정 전후 데이터가 다른 날로 집계됨: KST 00:00~08:59 사이의 주문은 UTC로 보면 아직 전날입니다. 서버 시간대로 날짜를 자르면 매일 새벽 9시간 치 데이터가 전날 매출로 들어갑니다
  • 마감일이 하루 앞당겨짐: 11월 30일 마감을 `2026-11-30T00:00+09:00`으로 저장하면 UTC로는 11월 29일 15:00이고, UTC 서버에서 날짜만 꺼내면 29일이 됩니다
  • 배치 실행 시각 혼동: "매일 7시"라고 생각하고 적은 크론이 실제로는 오후 4시(UTC 07:00)에 실행됩니다
  • 이 버그가 늦게 발견되는 이유는 개발 PC가 KST이기 때문입니다. 로컬과 사내 테스트 서버에서는 모든 테스트가 통과하고, 운영에 올라간 뒤에야 월말 정산에서 숫자가 맞지 않아 드러납니다.

    '시각'과 '날짜'는 다른 데이터다

    먼저 두 종류의 값을 구분해야 합니다.

  • 시각(타임스탬프): 지구상 어디서나 같은 한 순간입니다. 주문 시각, 로그인 시각, 결재 승인 시각이 여기에 해당합니다
  • 달력상의 날짜: 시간대와 무관한 "그 날"입니다. 생일, 계약 마감일, 영업일, 휴가일이 해당합니다
  • DB와 언어는 이 차이를 타입으로 구분합니다. PostgreSQL의 `timestamptz`는 UTC로 저장하고 세션 시간대로 변환해 보여 주며, `timestamp`(without time zone)와 `date`는 시간대 정보가 없습니다. Java는 `Instant`·`ZonedDateTime`과 `LocalDate`를, Python은 aware·naive `datetime`과 `date`를 구분합니다. 반면 JavaScript의 `Date`는 항상 타임스탬프이므로 날짜만 담는 용도로 쓰면 위험합니다.

    가장 흔한 함정은 날짜만 필요한 값을 자정 타임스탬프로 저장하는 것입니다. 마감일 11월 30일은 `date` 타입이나 `"2026-11-30"` 문자열로 저장해야 어느 서버에서 읽어도 30일로 남습니다.

    저장·처리·표시 원칙

  • 저장: 시각은 UTC 또는 오프셋을 포함한 형식(`timestamptz`, ISO 8601 `+09:00`)으로, 날짜는 날짜 타입으로 저장합니다
  • 표시: 화면에 보여 줄 때만 사용자 시간대로 변환합니다
  • 업무 기준 시간대를 코드에 명시: `Asia/Seoul`을 설정 상수로 두고 날짜 계산에 명시적으로 넘깁니다. `new Date(y, m, d)`나 `getDate()`처럼 실행 환경 시간대를 따르는 API는 서버 코드에서 쓰지 않습니다
  • 외부 API의 날짜 해석 규칙 정의: 공공 API는 `20261109143000`처럼 구분자 없는 문자열을 자주 돌려줍니다. 여기에는 시간대 정보가 없으므로 "KST로 해석한다"는 규칙을 정하고, 예를 들어 `Date.UTC(y, m - 1, d, h - 9, min)`처럼 명시적으로 변환해야 합니다
  • 집계와 배치에서 주의할 것

    '오늘'과 '이번 달'의 경계는 업무 시간대로 계산합니다. KST 기준 11월은 `2026-10-31T15:00Z` 이상, `2026-11-30T15:00Z` 미만입니다. SQL에서도 `date_trunc('month', created_at AT TIME ZONE 'Asia/Seoul')`처럼 변환 후 자르는 것이 원칙입니다.

    크론 표기 시간대를 확인합니다. 대부분의 클라우드 스케줄러는 UTC 기준이라 KST 07:00 실행은 `0 22 * * *`(전날 22:00 UTC)로 적어야 합니다. 설정 파일에 KST 실행 시각을 주석으로 함께 적어 두고, 배포 후에는 실행 기록으로 실제 시각을 확인합니다.

    해외 사용자·법인이 있다면 정책을 문서로 정합니다. 정산은 본사 KST로 할지, 법인별 현지 시간대로 할지를 먼저 정해야 합니다. 한국은 서머타임이 없지만 미국·유럽 법인은 연 2회 오프셋이 바뀌므로 고정 오프셋(`+09:00`, `-05:00`) 대신 IANA 시간대 이름(`America/New_York`)을 사용합니다.

    테스트로 잡는 방법

  • 실행 환경 시간대를 바꿔 테스트: CI에서 `TZ=UTC`와 `TZ=Asia/Seoul` 두 번 실행하면 환경 의존 코드가 바로 드러납니다
  • 경계 테스트 케이스: KST 23:59와 00:00, 08:59와 09:00(UTC 날짜가 바뀌는 시점), 월말·연말, 윤년 2월 29일을 고정 케이스로 둡니다
  • 운영 로그 시각 통일: 로그는 UTC ISO 8601(`Z` 포함)로 남기거나 KST라면 `+09:00`을 반드시 붙입니다. 오프셋 없는 로그는 장애 분석 때 9시간 어긋난 시각을 읽게 만듭니다
  • POLYGLOTSOFT의 접근

    POLYGLOTSOFT는 클라우드 이전과 구독형 개발 프로젝트에서 시간대 정책을 설계 초기 산출물로 정의합니다. 시각·날짜 필드 분류, 업무 기준 시간대, 외부 연동 날짜 해석 규칙, 크론 표기 기준을 요구사항 단계에서 확정하고, CI에 시간대 교차 테스트를 기본으로 포함합니다. 클라우드 이전 후 집계가 맞지 않거나 새 시스템의 날짜 설계를 점검하고 싶으시다면 POLYGLOTSOFT에 문의해 주십시오. 현재 구조를 진단하고 이전 전에 막아야 할 지점을 함께 정리해 드립니다.