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

🤖 Bản dịch này do máy tạo và đang chờ người kiểm duyệt. Trang tiếng Anh là bản chuẩn.

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:

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:

   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:

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

Chú ý

Đừ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 — những gì đã ship trong mỗi phiên bản.
• Khả năng quan sát & Cảnh báo — tình trạng runtime cùng với phiên bản.