ADR-0002. Bảng route Nginx cục bộ cho parity dev native
| Trường | Giá trị |
|---|---|
| Status | Accepted |
| Ngày | 2025-01-20 |
| Người quyết định | @platform |
| Thay thế | — |
Bối cảnh
- Trong development native, dịch vụ chạy trực tiếp trên host (
127.0.0.1:31xx), không phải trong Docker — nên Docker-label discovery của Traefik không áp dụng. - Frontend muốn một base URL duy nhất (
http://sgw.local.bana.com.vn/v1/api) bất kể nó gọi dịch vụ nào, phản chiếu edge production. - Chạy toàn bộ stack Docker/Traefik cục bộ là nặng và làm chậm vòng lặp dev nội bộ.
- Prefix dịch vụ đã khớp
APP_ENV_SERVER_BASE_PATH, nên không cần rewrite path.
Quyết định
Chúng tôi sẽ đặt trước các dịch vụ native một container Nginx duy nhất (local-nx-gateway) dùng host networking, được điều khiển bởi một bảng route trung tâm tường minh trong local/nginx.conf (block upstream + location /v1/api/<svc>/ theo từng dịch vụ, cộng /stream và /__gateway_health).
Hệ quả
| Ưu | Nhược |
|---|---|
| Một base URL ổn định cho FE — khớp hành vi edge prod | Host networking chỉ Linux |
| Nhẹ — một container, không stack Traefik/Docker | Bảng route thủ công: mỗi dịch vụ mới cần chỉnh sửa upstream + location |
Path không khớp fail nhanh với JSON 404 rõ ràng | Hai định nghĩa route phải giữ đồng bộ (labels prod vs nginx.conf dev) |
WebSocket /stream và một health probe hoạt động cục bộ | Không middleware resilience trong dev (cố ý — gần với hành vi dịch vụ thô hơn) |
Phương án đã cân nhắc
| Tùy chọn | Ưu | Nhược | Vì sao bị từ chối |
|---|---|---|---|
| Chạy Traefik cục bộ luôn | Proxy giống hệt prod | Yêu cầu Docker-hóa mọi dịch vụ dev; nặng | Phá vỡ vòng lặp dev native nhanh |
FE trỏ trực tiếp tới mỗi 127.0.0.1:31xx | Không gateway nào cả | Nhiều base URL; không parity prod; đau đầu CORS | DX kém, lệch khỏi prod |
| Stack dev Docker Compose với Traefik | Parity đầy đủ | Rebuild chậm, nặng tài nguyên | Ma sát vòng lặp nội bộ |
Tham khảo
- Cấu hình — Bảng route Nginx cục bộ
packages/gateway/local/nginx.conf