ADR-0002. Bảng route Nginx cục bộ để đồng nhất với môi trường dev native

Trường	Giá trị
Trạng thái	Accepted
Ngày	2025-01-20
Người quyết định	Phat Nguyen
Thay thế	-

Bối cảnh

• Khi phát triển ở chế độ native, các service chạy thẳng trên host (127.0.0.1:31xx) chứ không nằm trong Docker - nên cơ chế tự khám phá theo Docker label của Traefik không áp dụng được.
• Frontend muốn một base URL duy nhất (http://sgw.local.bana.com.vn/v1/api) bất kể gọi tới service nào, giống hệt như edge production.
• Chạy toàn bộ stack Docker/Traefik trên máy cục bộ rất nặng và làm chậm vòng lặp phát triển.
• Prefix của các service vốn đã khớp với APP_ENV_SERVER_BASE_PATH, nên không cần viết lại path.

Quyết định

Chúng tôi sẽ đặt phía trước các service native một container Nginx duy nhất (local-nx-gateway) dùng host networking, điều khiển bằng một bảng route trung tâm tường minh trong local/nginx.conf (các block upstream + location /v1/api/<svc>/ cho từng service, cùng với /stream và /__gateway_health).

Hệ quả

Ưu điểm	Nhược điểm
Một base URL ổn định cho FE - khớp hành vi edge production	Host networking chỉ chạy trên Linux
Nhẹ - một container, không cần stack Traefik/Docker	Bảng route phải sửa tay: mỗi service mới cần thêm upstream + location
Path không khớp sẽ trả lỗi ngay với JSON 404 rõ ràng	Hai định nghĩa route phải giữ đồng bộ (label prod và nginx.conf dev)
WebSocket /stream và health probe hoạt động được cục bộ	Không có middleware chịu lỗi trong dev (cố ý - gần với hành vi service thô hơn)

Phương án đã cân nhắc

Phương án	Ưu điểm	Nhược điểm	Vì sao bị loại
Chạy luôn Traefik ở cục bộ	Proxy giống hệt prod	Phải Docker hoá mọi service dev; nặng	Triệt tiêu vòng lặp dev native nhanh
FE trỏ thẳng tới từng 127.0.0.1:31xx	Không cần gateway nào cả	Nhiều base URL; không giống prod; khổ vì CORS	DX kém, lệch khỏi prod
Stack dev Docker Compose kèm Traefik	Đồng nhất hoàn toàn	Build lại chậm, ngốn tài nguyên	Gây ma sát cho vòng lặp phát triển

Tham khảo

• Cấu hình - Bảng route Nginx cục bộ
• packages/gateway/local/nginx.conf