ADR-0001. Routing động dựa-trên-label Traefik thay vì bảng route tĩnh

Trường	Giá trị
Status	Accepted
Ngày	2025-01-20
Người quyết định	@platform
Thay thế	—

Bối cảnh

• Nền tảng chạy ~13 dịch vụ backend trong Docker Compose, mỗi dịch vụ sở hữu prefix /v1/api/<svc> riêng; tập này tăng theo thời gian.
• Một bảng route trung tâm duy trì thủ công bị drift: mỗi dịch vụ mới hay thay đổi port cần một chỉnh sửa phối hợp + reload gateway.
• Chúng tôi muốn không redeploy gateway khi thêm một dịch vụ, và một lộ trình migration cơ học sang Kubernetes.
• Mỗi dịch vụ đã đặt APP_ENV_SERVER_BASE_PATH=/v1/api/<svc> — routing hoàn toàn suy ra được từ chính dịch vụ.

Quyết định

Chúng tôi sẽ dùng Traefik v3.6 với Docker provider: mỗi dịch vụ tự đăng ký router, port load-balancer, health check, và tham chiếu middleware qua Docker labels. Không có bảng route trung tâm trong lớp proxy production.

Hệ quả

Ưu	Nhược
Route dịch vụ mới xuất hiện tự động — không đổi config gateway	Routing phi tập trung; bản đồ route đầy đủ nằm rải qua nhiều file compose
Labels chuyển đổi cơ học sang Traefik IngressRoute CRDs cho K8s	PathPrefix là khớp prefix thuần — trùng lặp cần priority tường minh (xem Routing)
Resilience tích hợp (circuit breaker, rate limit, health check) không cần plugin	Traefik thêm phụ thuộc vào Docker socket
Hot-reload middleware dùng chung qua file provider	Middleware dùng chung phải dùng hậu tố @file hoặc fail âm thầm

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

Tùy chọn	Ưu	Nhược	Vì sao bị từ chối
Bảng route trung tâm tĩnh (file Nginx/HAProxy)	Một file để đọc; dễ đoán	Chỉnh sửa + reload thủ công mỗi thay đổi; bị drift	Vất vả vận hành; không tự khám phá
Kong / APISIX (route nền DB/etcd)	Hệ sinh thái plugin phong phú	Yêu cầu PostgreSQL/etcd; dấu chân nặng hơn	Overhead vận hành cho nhu cầu chỉ-gateway
Envoy (xDS)	Mạnh nhất, sẵn sàng mesh	Config phức tạp nhất; không Docker label discovery	Quá mức khi không có service mesh

Tham khảo

• Gateway Selection Report — Traefik chấm điểm 4.60/5
• Routing