# 프런트엔드 / 백엔드 버전 불일치

> 정보 패널이 프런트엔드와 백엔드 간 버전 불일치를 호박색으로 강조합니다.

## 증상

**설정 → 정보**에서 프런트엔드 버전과 백엔드 버전이 나란히 표시되며, 서로 다르기 때문에
해당 행이 **호박색**으로 강조됩니다. 예를 들어:

- 프런트엔드 `v1.5.0` 대 백엔드 `v1.5.0-1-gabc1234`, 또는
- 프런트엔드 `v1.5.0` 대 백엔드 `v1.4.0`.

패널은 의도적으로 불일치를 강조합니다 — 내장된 드리프트 탐지기입니다. 올바르게 배포된
박스에서는 두 버전이 일치해야 합니다.

## 확인

백엔드가 보고하는 버전을 직접 읽어 정보 패널이 프런트엔드에 대해 표시하는 것과
비교하세요:

```bash
curl -s http://localhost:5000/api/system/health | jq '{version, commit, buildTime}'
```

흔한 원인은 두 가지입니다:

1. **오래된 브라우저 탭.** 프런트엔드 번들은 빌드 시점에 구워지므로, 재배포 후에도 오래된
   탭은 로드된 버전을 계속 표시합니다.
2. **한 컨테이너만 다른 것 없이 재배포됨.** 새 백엔드 이미지는 배포되었으나 프런트엔드
   이미지(또는 그 반대)는 다시 빌드되지 않아 — 실제로 서로 다른 버전을 실행합니다.

태그 뒤에 추가 커밋이 붙은 버전 문자열(`...-1-gabc1234`)은 그 컨테이너가 릴리스 태그를
*지난* 커밋에서 빌드되었음을 의미합니다 — 깨끗한 태그 빌드보다 앞서 있습니다.

## 해결

1. **먼저 오래된 탭을 배제하세요** — 가장 비용이 적은 원인입니다. 브라우저를 하드
   새로고침하세요(캐시 무시 다시 로드). 이제 프런트엔드와 백엔드가 일치하면 끝입니다.
   배포에는 실제로 문제가 없었던 것입니다.

2. **여전히 다르면, 두 이미지가 같은 버전이 되도록 재배포하세요.** 프런트엔드와 백엔드가
   같은 릴리스에서 빌드되도록 다시 빌드하고 함께 스택을 기동합니다:

   ```bash
   docker compose -f docker-compose.release.yml up -d
   ```

3. **일치하는지 검증하세요.** **설정 → 정보**를 다시 로드하면 호박색 강조가 사라져야
   합니다. 백엔드 버전도 확인하세요:

   ```bash
   curl -s http://localhost:5000/api/system/health | jq .version
   ```

버전이 `0.0.0-dev...`로 표시되거나 `-dirty`로 끝나는 빌드는 배포하지 마세요. 전자는 그
빌드에 릴리스가 태그되지 않았음을 의미하고, 후자는 커밋되지 않은 로컬 편집을 담고 있음을
의미합니다. 둘 다 재현 불가능합니다 — 제대로 버전이 매겨진 릴리스를 배포하세요.

## 예방

- **프런트엔드와 백엔드를 함께 배포하세요.** 두 이미지 모두 빌드 시점에 구워진 버전을
  지닙니다. 하나의 릴리스에서 짝을 이룬 세트로 배포하면 정보 패널이 녹색을 유지합니다.
- **배포할 때마다 하드 새로고침하세요.** 브라우저 탭은 다시 로드하기 전까지 오래된 번들을
  유지합니다. 배포 후 빠른 하드 새로고침은 잘못된 드리프트 보고를 방지합니다.
- **정보 패널을 배포 후 점검으로 사용하세요.** 이를 최종 합격 단계로 취급하세요 —
  호박색이면 배포가 끝나지 않은 것입니다.

## 관련 항목

- [릴리스 노트](/release-notes/) — 각 버전에 포함된 내용.
- [관측성 및 알림](/operate/monitoring/) — 버전과 함께 보는 런타임 헬스.