Operations

@nx/search không có bản triển khai độc lập. Nó chạy bên trong container host (commerce) và chia sẻ vòng đời, replica, và tài nguyên 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 của commerce
Replicas	N/A - bằng số replica của commerce
Resources	Thêm bộ nhớ cho Kafka consumer + Typesense client vào host
Probes	Probe của host; TypesenseHelper.getHealth() quyết định việc đồng bộ collection + circuit breaker
Migration mode	Kiểm tra schema-drift khi khởi động (không tự áp dụng); script backfill thủ công cho thay đổi
Snowflake ID range	N/A

Phụ thuộc phải truy cập được

Phụ thuộc	Cần cho	Nếu mất kết nối
Typesense	search + indexing	Bootstrap bỏ qua việc đồng bộ collection (ghi log cảnh báo); circuit breaker tạm dừng CDC
Kafka + Debezium	đồng bộ CDC	Index ngừng cập nhật; consumer kết nối lại; offset không commit

Không có nhãn Traefik - route được gắn dưới base path của host service (/v1/api/commerce/...).

2. Observability

Tín hiệu	Nguồn	Nơi xem
Logs	stdout của host (key-value có cấu trúc)	log pod commerce - lọc theo scope component (ApplicationCdcComponent, TypesenseSearchEngineComponent)
CDC startup	dòng log Starting CDC consumer | Brokers… | DLQ… | CircuitBreaker…	xác nhận topic + trạng thái breaker
Schema sync	log Schema divergence detected | Collection: …	báo hiệu cần migration thủ công
Indexing throughput	chỉ số batch của SearchIndexingService	các trường log theo từng batch
Health	TypesenseHelper.getHealth()	probe của breaker + cổng kiểm tra lúc bootstrap

Chẩn đoán đồng bộ

Thao tác	Lệnh
Kiểm tra số dòng Typesense ↔ nguồn	So sánh số dòng Postgres với num_documents của collection Typesense
Chạy thử migration schema chỉ-thêm	bun run migrate
Chạy thử dựng lại collection (blue-green)	bun run migrate:rebuild

3. Security

Vấn đề	Biện pháp
AuthN	Route search kế thừa JWT/Basic của host (AuthenticateStrategy.JWT, .BASIC)
AuthZ	search:search / search:search-count; mixin yêu cầu config authorize của consumer
Tách biệt tenant	resolveSearchScope() gộp một scope where vào mọi query bằng and
Typesense API key	APP_ENV_TYPESENSE_API_KEY lấy từ secret của host; không bao giờ để trong code
Kafka SASL	APP_ENV_KAFKA_SASL_* khi broker yêu cầu xác thực
Không cho client ghi	Document chỉ thay đổi qua CDC - không có public write API

4. Runbook

4.1 Các loại Alert

Alert	Kích hoạt	Kiểm tra	Khắc phục	Báo cấp trên
searchSchemaDivergence	log Schema divergence detected khi khởi động	So sánh config với schema Typesense đang chạy	Chạy script backfill cho thay đổi chỉ-thêm; chỉ tạo lại collection khi an toàn không mất dữ liệu	backend on-call
searchCdcLag	CDC consumer tụt lại / circuit OPEN	Sức khoẻ Typesense, độ trễ consumer-group Kafka	Phục hồi Typesense; breaker đóng sau cửa sổ tĩnh	SRE on-call
searchDlqGrowth	message tích luỹ trong nx.seller.cdc.dlq	Xem payload DLQ + metadata lỗi	Sửa mapper/dữ liệu, replay từ DLQ	backend on-call
searchStale	kết quả thiếu các dòng vừa thay đổi	So sánh số dòng Postgres với num_documents của Typesense	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 / Hành động
Theo dõi log CDC	kubectl logs -f deploy/commerce | grep -E 'Cdc|Typesense'
Đối chiếu số liệu đồng bộ	So sánh số dòng Postgres với num_documents của collection Typesense
Áp dụng thay đổi schema chỉ-thêm	bun run migrate:apply (diff + PATCH lên collection đang chạy)
Dựng lại collection (thay đổi phá vỡ)	bun run migrate:rebuild:apply (copy blue-green + đổi alias nguyên tử)
Backfill các dòng DB sẵn có vào CDC	bun run backfill:apply (tín hiệu incremental snapshot của Debezium)
Reindex sau khi đổi schema	Tạo lại collection đã sai lệch (trong cửa sổ an toàn không mất dữ liệu) rồi backfill
Replay một CDC topic	Reset offset của Debezium connector / consumer-group (do infra sở hữu)

5. Trang liên quan

• Configuration
• /runbook/ - runbook trung tâm cho sự cố xuyên service
• Decisions