# Lệch phiên bản frontend / backend

> Bảng About tô màu hổ phách cho sự lệch phiên bản giữa frontend và backend.

## Triệu chứng

Trong **Settings → About**, phiên bản frontend và phiên bản backend được hiển thị cạnh nhau và hàng được tô màu **hổ phách** vì chúng khác nhau, ví dụ:

- Frontend `v1.5.0` so với backend `v1.5.0-1-gabc1234`, hoặc
- Frontend `v1.5.0` so với backend `v1.4.0`.

Bảng tô sáng sự lệch một cách có chủ ý — đó là bộ phát hiện trôi (drift) tích hợp. Hai phiên bản được kỳ vọng khớp nhau trên một hộp được triển khai đúng.

## Xác nhận

Đọc trực tiếp phiên bản mà backend báo cáo và so với những gì bảng About hiển thị cho frontend:

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

Có hai nguyên nhân thường gặp:

1. **Một tab trình duyệt cũ.** Bundle frontend được nướng vào lúc build, nên một tab cũ vẫn hiển thị phiên bản nó được nạp với, ngay cả sau khi triển khai lại.
2. **Một container được triển khai lại mà không có cái kia.** Một image backend mới được triển khai nhưng image frontend (hoặc ngược lại) không được build lại — nên chúng thực sự chạy các phiên bản khác nhau.

Một chuỗi phiên bản chứa các commit thêm sau tag (`...-1-gabc1234`) nghĩa là container đó được build từ một commit *sau* tag phát hành — nó đi trước bản build có tag sạch.

## Sửa

1. **Trước tiên, loại trừ một tab cũ** — đó là nguyên nhân rẻ nhất. Hard-refresh trình duyệt (tải lại bỏ qua cache). Nếu frontend và backend giờ khớp nhau, bạn đã xong; không có gì thực sự sai với việc triển khai.

2. **Nếu chúng vẫn khác, hãy triển khai lại để cả hai image cùng phiên bản.** Build lại và đưa stack lên cùng nhau để frontend và backend được build từ cùng một bản phát hành:

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

3. **Xác minh chúng khớp nhau.** Tải lại **Settings → About** — phần tô màu hổ phách sẽ biến mất. Xác nhận phiên bản backend nữa:

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

Đừng ship một bản build mà phiên bản đọc là `0.0.0-dev...` hoặc kết thúc bằng `-dirty`. Cái đầu
nghĩa là không có bản phát hành nào được gắn tag cho build đó; cái thứ hai nghĩa là nó mang các chỉnh sửa
cục bộ chưa commit. Cả hai đều không tái lập được — hãy triển khai một bản phát hành được đánh phiên bản đúng cách.

## Phòng ngừa

- **Triển khai frontend và backend cùng nhau.** Cả hai image mang một phiên bản được nướng vào lúc build; triển khai chúng như một bộ khớp từ một bản phát hành giữ cho bảng About màu xanh.
- **Hard-refresh sau mỗi lần triển khai.** Các tab trình duyệt giữ bundle cũ cho đến khi tải lại. Một lần hard refresh nhanh sau mỗi lần triển khai tránh các báo cáo trôi sai.
- **Dùng bảng About làm kiểm tra sau-triển-khai.** Coi nó là bước nghiệm thu cuối cùng — nếu nó màu hổ phách, việc triển khai chưa hoàn tất.

## Liên quan

- [Release Notes](/vi/release-notes/) — những gì đã ship trong mỗi phiên bản.
- [Khả năng quan sát & Cảnh báo](/vi/operate/monitoring/) — tình trạng runtime cùng với phiên bản.