Gateway Middlewares

1. Tổng quan

Middleware trong Traefik xử lý request trước khi chúng tới dịch vụ backend. BANA định nghĩa middleware dùng chung trong packages/gateway/config/dynamic/middlewares.yml (file provider) và tham chiếu chúng qua Docker labels trên mỗi dịch vụ với hậu tố @file.

Nguồn: packages/gateway/config/dynamic/middlewares.yml

2. Pipeline Middleware

3. Namespace Provider

Traefik dùng namespace provider để phân biệt nơi middleware được định nghĩa:

Hậu tố	Provider	Định nghĩa trong
@file	File provider	packages/gateway/config/dynamic/middlewares.yml
@docker	Docker provider	Docker labels trên container dịch vụ
(không)	Cùng provider	Chỉ hoạt động trong cùng phạm vi provider

Vì middleware dùng chung nằm trong file provider, Docker labels phải dùng hậu tố @file:

# Đúng
- "traefik.http.routers.commerce.middlewares=rate-limit@file,circuit-breaker@file,security-headers@file"

# Sai — Traefik tìm "rate-limit" trong Docker provider (không tồn tại)
- "traefik.http.routers.commerce.middlewares=rate-limit,circuit-breaker,security-headers"

4. Định nghĩa Middleware Dùng chung

Tất cả middleware dùng chung được định nghĩa trong packages/gateway/config/dynamic/middlewares.yml.

Circuit Breaker

Trip khi tỷ lệ network error vượt 10% hoặc P95 latency vượt 3 giây. Sau khi trip, circuit ở trạng thái mở trong 15 giây, rồi dần hồi phục trong 30 giây. Vế tỷ lệ 5xx-response có trong source nhưng bị comment out.

Nguồn: packages/gateway/config/dynamic/middlewares.yml

http:
  middlewares:
    circuit-breaker:
      circuitBreaker:
        # vế tỷ lệ 5xx bị comment out trong source:
        # expression: "ResponseCodeRatio(500, 600, 0, 600) > 0.30 || NetworkErrorRatio() > 0.10 || LatencyAtQuantileMS(95.0) > 3000"
        expression: "NetworkErrorRatio() > 0.10 || LatencyAtQuantileMS(95.0) > 3000"
        checkPeriod: 5s
        fallbackDuration: 15s
        recoveryDuration: 30s

Trạng thái:

• Closed — vận hành bình thường, request đi qua
• Open — mọi request fail nhanh với 503 (kích hoạt bởi expression). Kéo dài fallbackDuration (15s).
• Recovering — request giới hạn được phép để test hồi phục. Kéo dài tới recoveryDuration (30s). Trở về Closed nếu khỏe, mở lại nếu expression vẫn kích hoạt.

Rate Limiting (Chung)

Nguồn: middlewares.yml (dòng 53–59)

Áp dụng cho hầu hết dịch vụ — 200 request/giây theo IP client:

    rate-limit:
      rateLimit:
        average: 200
        burst: 400
        sourceCriterion:
          ipStrategy:
            depth: 1

Rate Limiting (Auth)

Nguồn: middlewares.yml (dòng 62–69)

Giới hạn nghiêm hơn cho endpoint xác thực — 30 request/phút theo IP client:

    rate-limit-auth:
      rateLimit:
        average: 30
        burst: 60
        period: 1m
        sourceCriterion:
          ipStrategy:
            depth: 1

sourceCriterion.ipStrategy.depth: 1 trích IP client thực từ header X-Forwarded-For (cần thiết vì Traefik nằm sau Nginx).

Security Headers

Nguồn: middlewares.yml (dòng 72–79)

Ẩn thông tin server và ngăn các tấn công phổ biến:

    security-headers:
      headers:
        browserXssFilter: true
        contentTypeNosniff: true
        frameDeny: true
        customResponseHeaders:
          Server: ""
          X-Powered-By: ""

Header	Hiệu ứng
browserXssFilter: true	Thêm X-XSS-Protection: 1; mode=block
contentTypeNosniff: true	Thêm X-Content-Type-Options: nosniff
frameDeny: true	Thêm X-Frame-Options: DENY
Server: ""	Strip header response Server
X-Powered-By: ""	Strip header response X-Powered-By

Xác thực Dashboard

Nguồn: middlewares.yml (dòng 36–39)

Traefik dashboard được bảo vệ bởi HTTP Basic Auth (không phơi bày với api.insecure):

    dashboard-auth:
      basicAuth:
        users:
          - "nx.eventry:$apr1$V3YHNLtR$x1jWCQ8.AiEfXoEc4ko7M0"

Redirect tới Dashboard

Nguồn: middlewares.yml (dòng 30–34)

Redirect path gốc / tới /dashboard/ trên entrypoint traefik:

    redirect-to-dashboard:
      redirectRegex:
        regex: "^/$"
        replacement: "/dashboard/"
        permanent: false

5. Router Dashboard

Nguồn: middlewares.yml (dòng 8–23)

Dashboard được phơi bày qua router file provider trên entrypoint traefik (:8080 → host port 30100):

http:
  routers:
    dashboard:
      rule: "PathPrefix(`/api`) || PathPrefix(`/dashboard`)"
      entryPoints:
        - traefik
      service: api@internal
      middlewares:
        - dashboard-auth
    dashboard-redirect:
      rule: "Path(`/`)"
      entryPoints:
        - traefik
      service: api@internal
      middlewares:
        - redirect-to-dashboard
        - dashboard-auth

Router	Rule	Middlewares	Ghi chú
dashboard	PathPrefix(/api) || PathPrefix(/dashboard)	dashboard-auth	Dashboard chính + route API
dashboard-redirect	Path(/)	redirect-to-dashboard, dashboard-auth	Redirect gốc tới /dashboard/

6. Áp dụng Middleware cho Dịch vụ

Middleware được áp dụng qua Docker labels trên mỗi dịch vụ. Hậu tố @file là bắt buộc:

# Dịch vụ chuẩn (commerce, sale, finance, v.v.)
labels:
  - "traefik.http.routers.commerce.middlewares=rate-limit@file,circuit-breaker@file,security-headers@file"

# Dịch vụ auth (rate limiting nghiêm hơn)
labels:
  - "traefik.http.routers.identity.middlewares=rate-limit-auth@file,circuit-breaker@file,security-headers@file"

7. Gán Middleware theo Dịch vụ

Dịch vụ	Rate Limit	Circuit Breaker	Security Headers
identity	rate-limit-auth@file (30/min theo IP)	Có	Có
commerce	rate-limit@file (200/s theo IP)	Có	Có
sale	rate-limit@file (200/s theo IP)	Có	Có
finance	rate-limit@file (200/s theo IP)	Có	Có
inventory	rate-limit@file (200/s theo IP)	Có	Có
payment	rate-limit@file (200/s theo IP)	Có	Có
payment-webhook	—	—	security-headers@file
signal (REST)	rate-limit@file (200/s theo IP)	Có	Có
signal (WS)	—	—	—
portal	—	—	— (dùng dashboard-auth@file cho basic auth)

8. Thêm Middleware Tùy biến

Tùy chọn A: File provider (dùng chung giữa các dịch vụ)

1. Định nghĩa middleware trong packages/gateway/config/dynamic/middlewares.yml
2. Tham chiếu nó trong Docker labels với hậu tố @file:

   - "traefik.http.routers.<service>.middlewares=<middleware-name>@file,..."

3. Traefik tự reload config động dựa-trên-file (không cần restart)

Tùy chọn B: Docker provider (theo từng dịch vụ)

1. Định nghĩa middleware trực tiếp trong Docker labels của dịch vụ:

   - "traefik.http.middlewares.<middleware-name>.<type>.<setting>=<value>"

2. Tham chiếu nó với hậu tố @docker (hoặc không hậu tố từ trong Docker labels):

   - "traefik.http.routers.<service>.middlewares=<middleware-name>@docker,..."

Middleware replacepathregex của webhook payment dùng Tùy chọn B vì nó riêng cho dịch vụ đó.

9. Trang liên quan

Tài liệu	Mô tả
Tổng quan Gateway	Thẻ định danh + service catalog
Kiến trúc	Góc nhìn C4, luồng request-routing
Routing	Docker label routing, 3 mẫu routing
Resilience	Trạng thái circuit breaker, health check, retry
Cấu hình	Config Traefik/Nginx, hằng số
Quyết định	ADRs