Vận hành
1. Triển khai
| Thuộc tính | Giá trị |
|---|---|
| Image | registry/nx-seller-commerce:<tag> |
| Container Port | 3000 |
| External Port | 31020 |
| Snowflake ID | 2 |
| Roles | api (HTTP) + worker (CDC consumer + SyncProductWorker) qua APP_ENV_WORKERS |
| Replicas (mặc định) | 1 (dev) / 2+ (staging+) |
| Chế độ migration | job RUN_MODE=migrate trước rollout; on-boot cho dev |
| Live probe | GET /v1/api/commerce/healthz |
| Ready probe | GET /v1/api/commerce/readyz |
Nhãn routing Traefik
yaml
labels:
- "traefik.enable=true"
- "traefik.http.routers.commerce.rule=PathPrefix(`/v1/api/commerce`)"
- "traefik.http.services.commerce.loadbalancer.server.port=3000"Hạ tầng bắt buộc
| Phụ thuộc | Lý do |
|---|---|
| PostgreSQL | Datastore chính (schema public + allocation) |
| Cache Redis | Cache authorization + cache footer-summary |
| BullMQ Redis | SYNC_PRODUCT_QUEUE (kết nối riêng) |
| WebSocket Redis | Fanout WebSocketEmitter |
| Debezium / Kafka Connect | Đọc WAL commerce → CDC topics (seam tích hợp) |
| Typesense | Engine tìm kiếm (qua @nx/search) |
| Minio | Lưu trữ media (qua @nx/asset) |
@nx/identity truy cập được | Xác thực JWKS trên mỗi JWT |
Vai trò API có thể phục vụ traffic mà không cần vai trò worker; đồng bộ CDC tới search chỉ chạy nơi
APP_ENV_WORKERSbật nó.
2. Observability
| Tín hiệu | Nguồn | Xem ở đâu |
|---|---|---|
| Logs | stdout (logger có cấu trúc IGNIS, key: %s) | kubectl logs deploy/commerce / Loki |
| Health | GET /v1/api/commerce/healthz, /readyz | Cổng gateway |
| OpenAPI live spec | GET /v1/api/commerce/doc/openapi.json | Trình khám phá cổng gateway |
| Metrics | Traefik gateway (Prometheus scrape) | Grafana — dashboard gateway |
| CDC lag | Metrics Debezium / Kafka Connect | Connect REST + lag consumer-group Kafka |
Trường log chính
| Trường | Nguồn | Ghi chú |
|---|---|---|
requestId | header X-Request-Id | lan truyền cross-service |
userId | subject JWT | — |
merchantId | phạm vi request | lọc theo vai trò |
productId / primaryProductId | luồng aggregate + sync | quan trọng để trace sync |
queueName / job id | log BullMQ | SYNC_PRODUCT_QUEUE |
Truy vấn log hữu ích
| Câu hỏi | Truy vấn |
|---|---|
| Lỗi worker đồng bộ sản phẩm | level=error AND SyncProductWorker |
| Rollback transaction aggregate | level=error AND (ProductCreateService OR ProductUpdateService) |
| Vấn đề kết nối Kafka producer | Disconnected from broker |
| Lỗi mã hóa | level=error AND EncryptService |
3. Bảo mật
| Mối quan tâm | Giảm thiểu |
|---|---|
| AuthN | JWT (ES256, JWKS từ identity); BASIC cho service-to-service |
| AuthZ | Lọc theo vai trò (SUPER_ADMIN/ADMIN đầy đủ, OWNER theo createdBy, EMPLOYEE qua PolicyDefinition, mặc định rỗng); cache trong authorization Redis |
| Mã hóa credential | AES-256-GCM (EncryptService, APP_ENV_APPLICATION_SECRET); hiển thị che; giải mã chỉ nội bộ |
| Secrets | K8s Secret gắn dưới dạng env (APP_ENV_DB_URL, APP_ENV_APPLICATION_SECRET, SASL, Redis) |
| Soft-delete | deletedAt trên tất cả thực thể; xóa được bảo vệ bởi DeletionPolicyService |
| Tin cậy CDC | Debezium đọc WAL với vai trò replication riêng; topic chỉ nội bộ |
| Network policy | Cilium — chỉ cho phép gateway + Postgres + Redis(×3) + identity + Minio + Typesense + Kafka |
4. Runbook
4.1 Phân loại cảnh báo
| Cảnh báo | Kích hoạt | Kiểm tra | Sửa | Leo thang |
|---|---|---|---|---|
CommerceHighErrorRate | 5xx >5% trong 5m | kubectl logs deploy/commerce | grep level=error | xác định endpoint lỗi; rollback deploy gần đây | on-call backend |
CommerceSyncWorkerBacklog | độ sâu SYNC_PRODUCT_QUEUE tăng | độ sâu hàng đợi BullMQ | kiểm tra sức khỏe BullMQ Redis; tăng concurrency | on-call backend |
CommerceCdcLag | lag consumer Debezium tăng | trạng thái Kafka Connect + lag consumer-group | restart connector; kiểm tra WAL slot | on-call SRE |
CommerceAggregateRollbacks | lỗi TX aggregate tăng | grep ProductCreateService/MerchantService | kiểm tra payload request; kiểm tra xung đột FK/slug | on-call backend |
CommerceKafkaProducerDown | lỗi kết nối producer | sức khỏe broker, credential SASL | (tác động thấp — producer nhàn rỗi; sửa broker) | on-call SRE |
CommerceTaxInfoStale | TaxInfo không cập nhật sau khi sửa thuế merchant | kiểm tra Merchant CDC → consumer invoice | replay offset Debezium; xác minh consumer invoice | on-call backend + nhóm invoice |
4.2 Thao tác thường gặp
| Thao tác | Lệnh |
|---|---|
| Tail logs | kubectl logs -n <ns> -f deploy/commerce |
| Chạy migration thủ công | kubectl exec -it deploy/commerce -- bun run migrate |
| Kiểm tra sync queue | BullMQ admin / Redis LLEN/KEYS trên SYNC_PRODUCT_QUEUE |
| Kích hoạt lại CDC snapshot | Kafka Connect connector restart / incremental snapshot |
| Audit tích hợp provider | SELECT code, status FROM "Configuration" WHERE group='...' (ciphertext credential, không bao giờ plaintext) |
4.3 Kịch bản phục hồi
| Kịch bản | Phục hồi |
|---|---|
| Worker crash trước khi đưa sync vào hàng đợi | aggregate đã commit; chạy lại sync bằng cách phát lại update aggregate hoặc enqueue thủ công |
| CDC consumer ngừng | Debezium giữ offset; restart connector — sự kiện replay từ WAL slot |
| Drift chỉ mục tìm kiếm | kích hoạt Debezium incremental snapshot để seed lại Typesense |
| Thiếu location mặc định inventory | replay CDC merchant; xác nhận consumer inventory khỏe mạnh |
| Sai credential được che | tạo lại tích hợp provider (không thể giải mã-và-hiển thị; xoay APP_ENV_APPLICATION_SECRET làm mất hiệu lực tất cả) |
5. Runbook Cross-Service
Với sự cố trải dài nhiều dịch vụ, xem runbook/ trung tâm:
6. Trang liên quan
- Cấu hình
- API Events — danh sách CDC topic để replay
- Tích hợp — mạng dịch vụ chị em
- Quyết định