Operations
@nx/searchkhông có deployment độc lập. Nó chạy bên trong container host (commerce) và chia sẻ vòng đời, replica, và resource của host. Vận hành nó nghĩa là vận hành Typesense, Debezium connector, và CDC consumer chạy trong commerce.
1. Deployment
| Thuộc tính | Giá trị |
|---|---|
| Image | N/A — đóng gói vào image commerce |
| Replicas | N/A — bằng replica commerce |
| Resources | Thêm memory Kafka consumer + Typesense client vào host |
| Probes | Probe host; TypesenseHelper.getHealth() gate collection sync + circuit breaker |
| Migration mode | Schema-drift check khi boot (không auto-apply); script backfill thủ công cho thay đổi |
| Snowflake ID range | N/A |
Dependency phải reachable
| Dependency | Cần cho | Nếu down |
|---|---|---|
| Typesense | search + indexing | Bootstrap skip collection sync (log warn); circuit breaker pause CDC |
| Kafka + Debezium | CDC sync | Index ngừng cập nhật; consumer reconnect; offset không commit |
Không có Traefik labels — route mount dưới base path của host service (
/v1/api/commerce/...).
2. Observability
| Signal | Nguồn | Nơi xem |
|---|---|---|
| Logs | Host stdout (key-value có cấu trúc) | log pod commerce — lọc scope component (ApplicationCdcComponent, TypesenseSearchEngineComponent) |
| CDC startup | dòng log Starting CDC consumer | Brokers… | DLQ… | CircuitBreaker… | xác nhận topic + state breaker |
| Schema sync | log Schema divergence detected | Collection: … | báo cần migration thủ công |
| Indexing throughput | metric batch SearchIndexingService | trường log theo từng batch |
| Health | TypesenseHelper.getHealth() | breaker probe + bootstrap gate |
Chẩn đoán Sync
| Thao tác | Lệnh |
|---|---|
| Check số dòng Typesense ↔ nguồn | scripts/check_sync_status.sh |
| Dry-run backfill reference | bun run migrate:references:dry |
| Dry-run backfill denorm | bun run migrate:denorm:dry |
3. Security
| Mối quan tâm | Biện pháp |
|---|---|
| AuthN | Route search kế thừa host JWT/Basic (AuthenticateStrategy.JWT, .BASIC) |
| AuthZ | search:search / search:search-count; mixin yêu cầu config authorize của consumer |
| Tenant isolation | resolveSearchScope() and-merge một scope where vào mọi query |
| Typesense API key | APP_ENV_TYPESENSE_API_KEY từ secret host; không bao giờ trong code |
| Kafka SASL | APP_ENV_KAFKA_SASL_* khi broker yêu cầu auth |
| Không client write | Document chỉ mutate qua CDC — không có public write API |
4. Runbook
4.1 Lớp Alert
| Alert | Trigger | Check | Fix | Escalate |
|---|---|---|---|---|
searchSchemaDivergence | log Schema divergence detected khi boot | So sánh config vs schema Typesense live | Chạy script backfill cho thay đổi additive; recreate collection chỉ khi an toàn về data-loss | backend on-call |
searchCdcLag | CDC consumer tụt lại / circuit OPEN | Typesense health, lag consumer-group Kafka | Phục hồi Typesense; breaker close sau quiet window | SRE on-call |
searchDlqGrowth | message tích lũy trong nx.seller.cdc.dlq | Inspect payload DLQ + metadata lỗi | Fix mapper/data, replay từ DLQ | backend on-call |
searchStale | kết quả thiếu dòng vừa thay đổi | scripts/check_sync_status.sh | Backfill hoặc replay topic bị ảnh hưởng | backend on-call |
4.2 Thao tác thường gặp
| Thao tác | Lệnh / Action |
|---|---|
| Tail log CDC | kubectl logs -f deploy/commerce | grep -E 'Cdc|Typesense' |
| Verify số sync | bun run check_sync_status (hoặc scripts/check_sync_status.sh) |
| Backfill references / denorm | bun run migrate:references / bun run migrate:denorm |
| Reindex sau khi đổi schema | Recreate collection đã phân kỳ (cửa sổ an toàn về data-loss) rồi backfill |
| Replay một CDC topic | Reset offset Debezium connector / consumer-group (do infra sở hữu) |
5. Trang liên quan
- Configuration
/runbook/— runbook trung tâm cho sự cố cross-service- Decisions