Vận hành

Không DB, không migration, không worker. Vận hành = triển khai proxy + portal, theo dõi metrics Traefik, và tinh chỉnh resilience.

1. Triển khai

Artifact	Image	Port	Build từ
Traefik	traefik:v3.6	:80 web, :8080 dashboard/metrics	config/traefik.yml + config/dynamic/ được mount
Portal	build tĩnh → nginxinc/nginx-unprivileged:1.27-alpine	:8080	portal/Dockerfile
Gateway dev cục bộ	nginx:1.27-alpine (local-nx-gateway)	:80 (host net)	local/docker-compose.yml + local/nginx.conf

Build & chạy Portal

cd packages/gateway/portal
bun install        # cây phụ thuộc riêng với gốc monorepo
bun run dev        # Astro dev server trên :3003
bun run rebuild    # clean + build tĩnh production
bun run lint       # scripts/lint.sh

Config Traefik và Nginx không cần bước build — chúng được mount trực tiếp. Dịch vụ backend tự đăng ký với Traefik qua Docker labels; không cần redeploy gateway khi thêm một dịch vụ (xem Routing).

Gateway dev native

# Chỉ Linux — host networking cho phép Nginx tiếp cận 127.0.0.1:31xx và bind :80
docker compose -f packages/gateway/local/docker-compose.yml up -d
curl http://localhost/__gateway_health   # → {"status":"ok","gateway":"local-nx-gateway"}

2. Observability

Tín hiệu	Nguồn	Xem ở đâu
Access logs	Traefik JSON access log (Authorization/Cookie bị bỏ)	container stdout / Loki
App logs	Traefik JSON log, level: INFO	container stdout
Metrics	Prometheus trên Traefik :8080	Prometheus + Grafana
Dashboard	Traefik dashboard :8080 (basic-auth)	/dashboard/
Sức khỏe theo dịch vụ	gateway-portal	trang Monitor của portal

Danh sách metric đầy đủ, config scrape Prometheus, và provisioning Grafana: xem Observability. Metric chính: traefik_service_requests_total, traefik_service_request_duration_seconds, traefik_service_server_up.

3. Bảo mật

Mối quan tâm	Giảm thiểu	Nguồn
TLS	Kết thúc tại edge Nginx — Traefik không có HTTPS entrypoint	config/traefik.yml
Rate limit (chung)	rate-limit 200/s, burst 400, theo IP	middlewares.yml
Rate limit (auth)	rate-limit-auth 30/min, burst 60, theo IP	middlewares.yml
Circuit breaker	NetworkErrorRatio() > 0.10 || LatencyAtQuantileMS(95.0) > 3000	middlewares.yml
Security headers	XSS filter, nosniff, frame deny; strip Server/X-Powered-By	middlewares.yml
Truy cập Dashboard / portal	basic auth (dashboard-auth)	middlewares.yml
Docker socket	mount read-only; exposedByDefault: false	config/traefik.yml
IP client thực	ipStrategy.depth=1 đọc X-Forwarded-For phía sau Nginx	middlewares.yml

Rate limiting theo IP chỉ hoạt động đúng vì ipStrategy.depth=1 trích IP client thực — nếu không, mọi request sẽ dùng chung bucket IP của Nginx. Xem Resilience.

4. Runbook

4.1 Phân loại cảnh báo (khuyến nghị — chưa triển khai)

Cảnh báo	Kích hoạt	Kiểm tra	Sửa
GatewayHighErrorRate	tỷ lệ 5xx > 5% trong 5m	Traefik access logs, sức khỏe dịch vụ đích	Kiểm tra backend lỗi; circuit breaker có thể đã mở
GatewayHighLatency	p99 > 2s trong 5m	histogram latency theo dịch vụ	Backend chậm; kiểm tra DB / downstream
BackendDown	traefik_service_server_up == 0	/health dịch vụ	Restart/scale backend; Traefik tự thêm lại khi hồi phục

Ví dụ PromQL + quy tắc cảnh báo: xem Observability §8.

4.2 Thao tác thường gặp

Thao tác	Lệnh / hành động
Tail log Traefik	docker logs -f <traefik-container>
Xác minh một route được đăng ký	Traefik dashboard /dashboard/ → HTTP Routers
Reload middleware dùng chung	sửa config/dynamic/middlewares.yml — file provider hot-reload (không restart)
Thêm một route backend (prod)	thêm Traefik labels vào compose dịch vụ; tự khám phá
Thêm một route backend (dev)	thêm upstream + location /v1/api/<svc>/ vào local/nginx.conf, restart local-nx-gateway
Thêm một dịch vụ vào portal	thêm một mục vào portal/src/constants/services.constant.ts, rebuild portal
Kiểm tra liveness gateway dev	curl http://localhost/__gateway_health
Kiểm tra một circuit đã trip	dashboard → middleware router; theo dõi NetworkErrorRatio / p95 latency

5. Trang liên quan

• Cấu hình
• Observability
• Resilience
• /runbook/ — runbook trung tâm cho sự cố cross-service
• Quyết định