Bài 4: Reverse Proxy & API Gateway

Bài 3 đặt nginx lên trước ba replica và dùng nó cho đúng một việc: chia tải. Nhưng thành phần đứng ở vị trí đó — nơi mọi request đều phải đi qua — có thể làm nhiều hơn thế rất nhiều: kết thúc TLS, định tuyến theo đường dẫn, phục vụ file tĩnh, chặn request thiếu token, giới hạn tần suất. Bài này giữ nguyên nginx nhưng giao cho nó những việc đó, rồi đo xem mỗi việc đáng giá bao nhiêu.

Hai phép đo trong bài đi ngược lại điều mình dự đoán khi viết đề cương. Thứ nhất: câu "cho gateway phục vụ file tĩnh để app đỡ việc" hoá ra khiến gateway chậm hơn 2,6 lần so với việc chuyển tiếp request về app — cho tới khi thêm đúng một chỉ thị cấu hình. Thứ hai: "TLS tốn khoảng 10%" là con số mình đo được và cũng là con số hay được trích dẫn, nhưng nó chỉ đúng trong một điều kiện rất cụ thể; bỏ điều kiện đó ra thì chi phí thành gần 16 lần.

4.1 Ba cái tên cho cùng một vị trí

"Reverse proxy", "load balancer", "API gateway" thường được nói như ba sản phẩm khác nhau. Thực tế chúng là ba mức trách nhiệm gán cho cùng một vị trí trong hệ thống: chặng đứng giữa client và các service. Cùng một tiến trình nginx trong lab của series này lần lượt đóng cả ba vai.

Phân biệt thêm một cặp dễ lẫn: forward proxy và reverse proxy. Forward proxy đứng cạnh client và đại diện cho client (ví dụ proxy của công ty đi ra Internet); reverse proxy đứng cạnh server và đại diện cho server. Cùng công nghệ, ngược hướng, và bên nào cấu hình nó cũng khác nhau.

Lab của bài này

Lab dùng chung của series được mở thêm profile gw. Điểm quan trọng trong thiết kế lab: cổng HTTP (8081) và cổng HTTPS (8443) include cùng một file route, nên chênh lệch đo được giữa hai cổng chỉ đến từ TLS, không lẫn khác biệt cấu hình:

cd blog/sysdesign/sysdesign-lab

# 1. Generate a SELF-SIGNED cert for the gateway (lab only, never use it anywhere else)
mkdir -p nginx/certs
openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout nginx/certs/lab.key -out nginx/certs/lab.crt \
  -subj "/CN=localhost"

# 2. Start the gateway + 3 app replicas
docker compose --profile gw up -d

# 3. Check that both ports are alive
curl -s  http://localhost:8081/gw-health      # -> gateway ok
curl -sk https://localhost:8443/gw-health     # -> gateway ok  (-k: skip cert verification)

# 4. Gateway strips the /api/ prefix before forwarding
curl -s http://localhost:8081/api/whoami
# -> {"instance":"app1", ...}   the app has NO idea the /api/ prefix even exists

Nếu cả hai lệnh curl ở bước 3 đều trả về gateway ok, gateway đang chạy đúng và sẵn sàng cho phần đo tiếp theo. Bước 4 xác nhận điều quan trọng nhất của bài: gateway và app nói hai đường dẫn khác nhau — client gọi /api/whoami, app chỉ thấy /whoami.

4.2 TLS termination và sự thật về X-Forwarded-For

TLS termination nghĩa là gateway giải mã HTTPS rồi nói HTTP thuần với các service phía sau. Lý do làm vậy rất thực dụng: chứng chỉ chỉ nằm ở một chỗ (gia hạn một lần thay vì N lần), service không cần biết gì về TLS, và gateway đọc được nội dung nên mới định tuyến theo path được.

TLS tốn bao nhiêu?

Cùng route /api/fast, 8 kết nối đồng thời, 8 giây đo, ba lần lặp — chỉ khác cổng vào là HTTP hay HTTPS:

Khoảng 10% throughput, và độ trễ tăng thêm nhỏ hơn nhiều so với thời gian một truy vấn database tầm thường nhất. Kết luận có vẻ rõ ràng: TLS rẻ, bật đi. Nhưng con số này che một điều kiện.

Con số 10% chỉ đúng khi có keep-alive

Bộ đo tải của lab mặc định dùng kết nối bền (keep-alive): mở 8 kết nối rồi gửi hàng trăm nghìn request qua chúng. Cái đắt của TLS là bắt tay — trao đổi khoá bất đối xứng, một hoặc hai vòng mạng — còn phần mã hoá đối xứng sau đó thì rất rẻ. Với keep-alive, chi phí bắt tay được chia cho hàng chục nghìn request nên gần như tan biến.

Bộ đo tải có cờ --no-keepalive để buộc mỗi request mở một kết nối mới. Cùng route, cùng số kết nối đồng thời:

Bỏ keep-alive đi, HTTP mất 3 lần throughput vì phải bắt tay TCP mỗi lần. Nhưng HTTPS mất gần 16 lần so với chính nó khi có keep-alive (20.400 req/s xuống còn khoảng 1.260 req/s), và p50 tăng từ 0,36 ms lên hơn 6 ms — gấp 17 lần. Đó là hình dạng thật của chi phí TLS: nó không nằm ở mỗi request, nó nằm ở mỗi kết nối.

Sau khi giải mã, app mất thông tin gì?

Kết nối TCP mà app nhìn thấy là kết nối từ gateway, không phải từ client. Nên socket.remoteAddress của app luôn là IP của gateway, và app cũng không còn biết client vào bằng HTTP hay HTTPS. Thông tin đó phải được chuyển tiếp bằng header — và đây là chỗ sinh ra một lỗ hổng rất phổ biến.

Lab có endpoint /client-ip tồn tại chỉ để chứng minh chuyện này. Chạy thật, gửi kèm một header bịa:

curl -s -H 'X-Forwarded-For: 1.2.3.4' http://localhost:8081/api/client-ip

# {"instance":"app1",
#  "remoteAddress":"::ffff:172.21.0.5",              ← the GATEWAY's IP, not the client's
#  "xForwardedForRaw":"1.2.3.4, 192.168.65.1",       ← spoofed value + real IP
#  "trustProxyHops":0,
#  "trustedClientIp":"::ffff:172.21.0.5",
#  "naiveClientIp":"1.2.3.4"}                  ← WRONG: took spoofed value verbatim

# ---- Fix 1: gateway OVERWRITES the header (route /safe-api/) ----
curl -s -H 'X-Forwarded-For: 1.2.3.4' http://localhost:8081/safe-api/client-ip

# "xForwardedForRaw":"192.168.65.1"                  ← spoofed value wiped out
# "naiveClientIp":"192.168.65.1"                     ← correct no matter how you read it

# ---- Fix 2: app counts from the right ----
# Set TRUST_PROXY_HOPS='1' for all three apps in docker-compose.yml (default is '0'),
# then RECREATE the containers - `restart` does not reload environment variables:
#   docker compose --profile gw up -d --force-recreate app1 app2 app3
curl -s -H 'X-Forwarded-For: 1.2.3.4' http://localhost:8081/api/client-ip

# "xForwardedForRaw":"1.2.3.4, 192.168.65.1",
# "trustProxyHops":1,
# "trustedClientIp":"192.168.65.1"                   ← CORRECT
# "naiveClientIp":"1.2.3.4"                          ← still wrong, kept for comparison

Cấu hình nginx tạo ra hai hành vi đó chỉ khác nhau một dòng:

location /api/ {
    proxy_pass http://api_pool/;
    # APPEND: keep what the client sent, add the real IP at the end.
    # Use this when there is ANOTHER trusted proxy in front of the gateway (a CDN,
    # say) and the app needs the whole chain. The app MUST read from the right.
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP       $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location /safe-api/ {
    proxy_pass http://api_pool/;
    # OVERWRITE: wipe out everything the client sent. Use this when the gateway is
    # the FIRST hop touching the Internet. This is the safest default.
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP       $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

4.3 Định tuyến theo đường dẫn — và một phép đo đi ngược dự đoán

Việc dễ thấy nhất của gateway: xem đường dẫn rồi quyết định gửi đi đâu. /api/orders/* về service đơn hàng, /api/users/* về service người dùng, /static/* thì gateway tự trả. Client thấy một domain duy nhất và không biết phía sau có bao nhiêu service.

"Cho gateway phục vụ file tĩnh" — đo trước khi tin

Lời khuyên kinh điển: để gateway tự trả file tĩnh, mỗi file nó trả là một request app không phải xử lý. nginx đọc file nhanh hơn Node rất nhiều, nên chuyện này nghe như không cần kiểm tra. Mình đo thử, 16 kết nối, 8 giây, ba lần lặp, so /static/hello.json (nginx tự trả) với /api/fast (chuyển tiếp về app):

File tĩnh chậm hơn 2,6 lần so với đi qua proxy tới một tiến trình Node. Điều này ngược hoàn toàn với dự đoán, nên nó là một trong hai khả năng: hoặc lời khuyên sai, hoặc mình đang đo một thứ khác với thứ mình nghĩ.

Giả thuyết: thư mục static được bind-mount từ máy host vào container. Trên Docker Desktop (macOS/Windows), bind-mount đi qua ranh giới máy ảo, nên mỗi lời gọi hệ thống lên file đó đắt hơn hẳn. Và nginx mặc định mở lại file mỗi request: stat(), open(), read(). Nếu giả thuyết đúng thì việc cache metadata và file descriptor phải xoá được gần hết khoảng cách. Thêm bốn dòng:

location /static/ {
    alias /usr/share/nginx/static/;
    expires 1h;

    # Cache metadata + file descriptor instead of stat()+open()+read() every request.
    open_file_cache          max=1000 inactive=60s;
    open_file_cache_valid    60s;
    open_file_cache_min_uses 1;
    open_file_cache_errors   on;
}

Nhanh lên 2,4 lần, p50 giảm từ 1,6 ms xuống 0,68 ms. Giả thuyết đúng: nút cổ chai không phải nginx mà là hệ thống file phía dưới nó. Sau khi sửa, file tĩnh gần bằng route proxy — vẫn thấp hơn chút, và với file lớn hơn static/hello.json (94 byte) của lab thì lợi thế sẽ nghiêng hẳn về nginx: chi phí cố định của mỗi request (bắt tay TCP nội bộ, event loop) chiếm phần lớn hơn khi file nhỏ, còn nginx đọc file lớn thẳng từ cache mà không tốn CPU cho JavaScript.

Đánh version API

Khi API phải thay đổi theo cách không tương thích ngược, gateway là nơi tự nhiên để hai phiên bản cùng tồn tại. Ba cách thường gặp:

Trong thực tế, version trong đường dẫn thắng ở phần lớn hệ thống vì lý do rất thực dụng: khi có sự cố lúc 2 giờ sáng, bạn đọc được version ngay trên dòng log mà không phải mở thêm gì.

Gateway cũng là chỗ để canary: đẩy một phần nhỏ lưu lượng sang phiên bản mới trước khi chuyển hết. nginx làm được bằng split_clients, và điểm quan trọng là nó băm theo một khoá ổn định để một client luôn thấy cùng một phiên bản:

# Hash on IP (or better: on the user id in a cookie) => ONE client always sees
# the SAME version. Hashing on $request_id instead makes the same person bounce
# between v1 and v2 across requests — a bug that's very hard to reproduce.
split_clients "${remote_addr}canary" $api_backend {
    5%      api_v2;
    *       api_v1;
}

location /api/ {
    proxy_pass http://$api_backend/;
}

5% ở đây là điểm khởi đầu thận trọng, không phải con số cố định — tăng dần (5% → 25% → 100%) khi tỉ lệ lỗi và độ trễ của api_v2 đo riêng vẫn ổn, và có đường lùi ngay lập tức về 0% nếu không.

4.4 Việc xuyên suốt: cái gì nên đặt ở gateway

Có một nhóm việc mà mọi service đều cần: xác thực, giới hạn tần suất, ghi log, nén, CORS. Nếu mỗi service tự làm, bạn có N bản cài đặt và N cơ hội để một bản làm sai. Gateway là nơi làm một lần. Nhưng không phải việc gì cũng nên chuyển lên đó.

Ranh giới nằm ở một câu hỏi: việc này có cần biết nghiệp vụ không? Không cần thì gateway. Cần thì service. Áp dụng câu hỏi đó cho từng việc là cách duy nhất mình biết để gateway không dần biến thành nơi chứa logic.

Gộp nhiều service: độ trễ bằng nhánh chậm nhất

Một màn hình thường cần dữ liệu từ nhiều service. Nếu client tự gọi từng cái, nó phải chịu toàn bộ độ trễ mạng của mình — với mạng di động thì đắt. Cho gateway (hoặc một service BFF — backend for frontend) gọi hộ trong mạng nội bộ rồi trả về một lần là kiểu thiết kế phổ biến. Điều then chốt là gọi song song:

Endpoint /aggregate của lab gọi thật ba nhánh qua HTTP nên chi phí socket và event loop đều là chi phí thật, không phải setTimeout giả:

curl -sk "https://localhost:8443/api/aggregate?branches=50,120,200&mode=parallel"
# "maxBranchMs":200, "sumBranchMs":370, "totalMs":208.36

curl -sk "https://localhost:8443/api/aggregate?branches=50,120,200&mode=sequential"
# "maxBranchMs":200, "sumBranchMs":370, "totalMs":386.00

# Same three branches. Parallel: ~MAX. Sequential: ~SUM.

Về giới hạn tần suất, nginx làm sẵn — nhưng cần hiểu nó cho phép bùng tới mức nào, vì đó là chỗ hay gây bất ngờ:

# Shared bucket, keyed by the real IP (do NOT use raw XFF - see section 4.2).
# 10r/s is the REFILL rate, not "10 requests per second, max".
limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

location /api/ {
    # burst=20: let up to 20 requests queue up, then drain them at 10r/s.
    # nodelay:  serve those 20 queued requests IMMEDIATELY instead of pacing them.
    # => with nodelay, a client can burst 20 requests in a fraction of a second.
    #    Without nodelay it is smoother, but the client sees the delay stretched out.
    limit_req zone=perip burst=20 nodelay;
    limit_req_status 429;          # default is 503 — 429 is more meaningful
    proxy_pass http://api_pool/;
}

4.5 Gateway là điểm chết duy nhất — và ngân sách timeout

Mọi thứ trong bài này đều dồn về một chỗ, và chỗ đó nằm trên đường đi của 100% lưu lượng. Gateway chết là cả hệ thống chết, dù mọi service phía sau vẫn khoẻ mạnh. Nghịch lý: thành phần được thêm vào để tăng độ tin cậy lại là thành phần nguy hiểm nhất.

Ngân sách timeout

Mỗi chặng trên đường đi có timeout riêng, và chúng phải giảm dần khi đi vào trong. Nếu chặng trong chờ lâu hơn chặng ngoài, phần chờ vượt quá là công việc chắc chắn bị bỏ: client đã đi từ lâu mà service vẫn còn chiếm kết nối và CPU để tính một kết quả không ai nhận.

Tóm lại

Reverse proxy, load balancer và API gateway là ba mức trách nhiệm ở cùng một vị trí, và mỗi mức thêm quyền năng bằng cách thêm trạng thái phải quản lý. TLS termination rẻ khi có kết nối bền và đắt gấp nhiều lần khi không — chi phí nằm ở mỗi kết nối, không phải mỗi request. X-Forwarded-For phải đọc từ bên phải, hoặc tốt hơn là để gateway ghi đè. Việc gì không cần biết nghiệp vụ thì đặt ở gateway, việc cần biết nghiệp vụ thì để service. Và mọi thứ dồn về gateway nghĩa là ngân sách timeout cùng chính sách thử lại phải được thiết kế có chủ ý, không để mặc định.

Phép đo file tĩnh trong bài này để lại bài học rộng hơn cả kiến trúc: một con số ngược dự đoán không phải kết luận, nó là câu hỏi. Nếu mình dừng ở lần đo đầu, bài này đã khẳng định "nginx phục vụ file tĩnh chậm hơn Node" — sai, nhưng có số liệu kèm theo nên nghe rất thuyết phục.

Bài 5 đi vào tầng ngay sau gateway: caching. Lab đã có Redis chờ ở profile cache, và câu hỏi trung tâm là cái mà mọi tầng cache đều phải trả lời — dữ liệu cũ tới mức nào thì vẫn dùng được, và ai chịu trách nhiệm xoá nó.