Configuration
@nx/searchđọc env từ process host (commerce). Nó định nghĩa các key riêng (src/common/environments.ts) trên nền các Kafka key của@nx/core, cộng config embedding + pipeline lưu trong bảngConfigurationở DB.
1. Biến môi trường
Riêng cho search (EnvironmentKeys mở rộng core)
| Tên | Kiểu | Mặc định | Bắt buộc | Mô tả |
|---|---|---|---|---|
APP_ENV_TYPESENSE_NODES | string (CSV) | http:localhost:8108 | Nodes dạng protocol:host:port, phân tách bằng dấu phẩy. Không phải URL | |
APP_ENV_TYPESENSE_API_KEY | string | xyz | Typesense API key | |
APP_ENV_CDC_DLQ_TOPIC | string | nx.seller.cdc.dlq | Dead-letter topic cho message CDC lỗi | |
APP_ENV_CDC_CIRCUIT_BREAKER_ENABLED | boolean (string) | false | Bật probe sức khoẻ Typesense + tạm dừng consumer |
Kafka / CDC consumer (kế thừa từ @nx/core)
| Tên | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
APP_ENV_KAFKA_BROKERS | string (CSV) | localhost:19092 | Bootstrap brokers |
APP_ENV_KAFKA_CLIENT_ID | string | commerce-cdc-consumer | Client id của CDC consumer |
APP_ENV_KAFKA_GROUP_ID | string | commerce-cdc-group | Consumer group của CDC |
APP_ENV_KAFKA_SASL_ENABLE | boolean (string) | false | Bật SASL |
APP_ENV_KAFKA_SASL_MECHANISM | string | SCRAM-SHA-512 | Cơ chế SASL (khi bật) |
APP_ENV_KAFKA_SASL_USERNAME | string | - | SASL user (khi bật) |
APP_ENV_KAFKA_SASL_PASSWORD | string | - | SASL password (khi bật) |
Các giá trị mặc định
commerce-cdc-*phản ánh host hiện tại; chúng không bị gắn cứng cho một service "search".
2. Feature Flags
| Flag | Mặc định | Mô tả |
|---|---|---|
APP_ENV_CDC_CIRCUIT_BREAKER_ENABLED | false | Kiểm soát CDC circuit breaker (probe sức khoẻ + tạm dừng) |
ISearchParams.disableSemanticSearch | false (theo từng query) | Bỏ trường embedding khỏi query_by → thuần từ khoá |
Auto-embedding (embed.from) | tắt trừ khi có config trong DB | Chỉ bật khi có config model embedding + collection có embeddingField/embeddingFields |
3. Dữ liệu Seed
Không có PostgreSQL migration riêng. "Seeding" thực hiện qua các script developer dùng để nạp/backfill dữ liệu:
| Script | Lệnh | Hành động | Idempotent |
|---|---|---|---|
scripts/migrate.ts | bun run migrate[:apply] | So sánh config collection đã đăng ký với Typesense đang chạy, PATCH các thay đổi trường chỉ-thêm | có |
scripts/rebuild-collection.ts | bun run migrate:rebuild[:apply] | Dựng lại kiểu blue-green: tạo collection mới từ config, copy document, đổi alias nguyên tử | có |
scripts/backfill-search.ts | bun run backfill[:apply] | Gửi tín hiệu incremental snapshot của Debezium để bù các dòng DB sẵn có vào CDC | có |
4. Lưu trữ Configuration (bảng Configuration)
Được SearchConfigurationService đọc khi bootstrap; nếu thiếu thì dùng DEFAULT_SEARCH_PIPELINE_CONFIG.
| Loại configuration | Đọc bởi | Bind tới | Ghi chú |
|---|---|---|---|
TYPESENSE_EMBEDDING_CONFIG (SystemConfigurations) | ApplicationEmbeddingConfigurationComponent | EMBEDDING_MODEL_CONFIG | Tuỳ chọn; nếu thiếu → chỉ tìm theo từ khoá |
| Config pipeline search | ApplicationEmbeddingConfigurationComponent | SEARCH_PIPELINE_CONFIG | Ghi đè một phần, gộp lên giá trị mặc định |
Giá trị mặc định của config pipeline (DEFAULT_SEARCH_PIPELINE_CONFIG)
| Nhóm | Trường | Mặc định |
|---|---|---|
cdc.kafkaConsumer | maxWaitTimeMs / maxBytes | 500 / 5 MB |
cdc.batching | maxBatchSize / flushIntervalMs | 200 / 2000 |
cdc.processing | typesenseBatchSize | 100 |
circuitBreaker | probeIntervalMs | 30 000 |
circuitBreaker | quietWindowMsTypesense / quietWindowMsGoogle | 30 000 / 90 000 |
circuitBreaker | maxOpenMs | 1 800 000 (30 phút) |
lsnLookup | pageSize | 250 |
search | cacheTtlSeconds | 5 |
search | paginationDefaultLimit / paginationMaxLimit | 10 / 250 |