프런트엔드 / 백엔드 버전 불일치
설정 → 정보에서 프런트엔드 버전과 백엔드 버전이 나란히 표시되며, 서로 다르기 때문에 해당 행이 호박색으로 강조됩니다. 예를 들어:
- 프런트엔드
v1.5.0대 백엔드v1.5.0-1-gabc1234, 또는 - 프런트엔드
v1.5.0대 백엔드v1.4.0.
패널은 의도적으로 불일치를 강조합니다 — 내장된 드리프트 탐지기입니다. 올바르게 배포된 박스에서는 두 버전이 일치해야 합니다.
백엔드가 보고하는 버전을 직접 읽어 정보 패널이 프런트엔드에 대해 표시하는 것과 비교하세요:
curl -s http://localhost:5000/api/system/health | jq '{version, commit, buildTime}'흔한 원인은 두 가지입니다:
- 오래된 브라우저 탭. 프런트엔드 번들은 빌드 시점에 구워지므로, 재배포 후에도 오래된 탭은 로드된 버전을 계속 표시합니다.
- 한 컨테이너만 다른 것 없이 재배포됨. 새 백엔드 이미지는 배포되었으나 프런트엔드 이미지(또는 그 반대)는 다시 빌드되지 않아 — 실제로 서로 다른 버전을 실행합니다.
태그 뒤에 추가 커밋이 붙은 버전 문자열(...-1-gabc1234)은 그 컨테이너가 릴리스 태그를
지난 커밋에서 빌드되었음을 의미합니다 — 깨끗한 태그 빌드보다 앞서 있습니다.
-
먼저 오래된 탭을 배제하세요 — 가장 비용이 적은 원인입니다. 브라우저를 하드 새로고침하세요(캐시 무시 다시 로드). 이제 프런트엔드와 백엔드가 일치하면 끝입니다. 배포에는 실제로 문제가 없었던 것입니다.
-
여전히 다르면, 두 이미지가 같은 버전이 되도록 재배포하세요. 프런트엔드와 백엔드가 같은 릴리스에서 빌드되도록 다시 빌드하고 함께 스택을 기동합니다:
Terminal window docker compose -f docker-compose.release.yml up -d -
일치하는지 검증하세요. 설정 → 정보를 다시 로드하면 호박색 강조가 사라져야 합니다. 백엔드 버전도 확인하세요:
Terminal window curl -s http://localhost:5000/api/system/health | jq .version
- 프런트엔드와 백엔드를 함께 배포하세요. 두 이미지 모두 빌드 시점에 구워진 버전을 지닙니다. 하나의 릴리스에서 짝을 이룬 세트로 배포하면 정보 패널이 녹색을 유지합니다.
- 배포할 때마다 하드 새로고침하세요. 브라우저 탭은 다시 로드하기 전까지 오래된 번들을 유지합니다. 배포 후 빠른 하드 새로고침은 잘못된 드리프트 보고를 방지합니다.
- 정보 패널을 배포 후 점검으로 사용하세요. 이를 최종 합격 단계로 취급하세요 — 호박색이면 배포가 끝나지 않은 것입니다.