Tham khảo Biến Môi trường

Cách thức file môi trường hoạt động

Mỗi package backend dùng dotenv-flow. Giá trị NODE_ENV quyết định file nào được nạp:

File	Mục đích	Bị gitignore
.env.development	Dev server (bun run server:dev)	Thường là không
.env.local	Override cá nhân	Có
.env.test	Test suite (bun run test)	Thường là có

Để cài đặt một package mới, hãy sao chép từ một package đã hoạt động và điều chỉnh cổng / tên dịch vụ / Snowflake ID.

Các script npm của mỗi package truyền file env một cách tường minh:

"server:dev": "NODE_ENV=development bun run start --env-file=.env.development"

Biến chung (Tất cả dịch vụ)

Các biến này được dùng chung cho mọi dịch vụ backend.

Application

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_APPLICATION_NAME	Có	Tên dịch vụ (dùng trong logging, service discovery)	identity
APP_ENV_APPLICATION_CODE	Có	Mã dịch vụ duy nhất	SVC-00010-IDENTITY
APP_ENV_APPLICATION_ROLES	Có	Tag vai trò dịch vụ	identity
APP_ENV_APPLICATION_TIMEZONE	Có	Múi giờ	Asia/Ho_Chi_Minh
APP_ENV_APPLICATION_SECRET	Có	Secret dùng chung cho mã hóa payload AES-256-GCM (hệ thống chứng chỉ, mã hóa thông tin xác thực). Phải giống hệt nhau giữa tất cả các dịch vụ.	-
APP_ENV_APPLICATION_DS_MIGRATION	Không	Tên datasource migration	pg_core
APP_ENV_APPLICATION_DS_AUTHORIZE	Không	Tên datasource authorization	pg_core

Server

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_SERVER_HOST	Có	Host bind	localhost
APP_ENV_SERVER_PORT	Có	Cổng bind (duy nhất theo từng dịch vụ)	31010
APP_ENV_SERVER_BASE_PATH	Có	Base path API	/v1/api/identity

Snowflake ID

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_SNOWFLAKE_WORKER_ID	Có	Worker ID duy nhất (0-1023). Phải duy nhất theo từng instance đang chạy - trùng lặp sẽ gây ID trùng.	1
APP_ENV_SNOWFLAKE_EPOCH_CHECKPOINT	Có	Mốc bắt đầu epoch (ms tính từ Unix epoch)	1735689600000

PostgreSQL

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_POSTGRES_HOST	Có	Host database	localhost
APP_ENV_POSTGRES_PORT	Có	Cổng database	5432
APP_ENV_POSTGRES_DATABASE	Có	Tên database	nx_seller
APP_ENV_POSTGRES_USERNAME	Có	User DB	postgres
APP_ENV_POSTGRES_PASSWORD	Có	Mật khẩu DB	-

Redis (Cache)

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_CACHE_REDIS_MODE	Có	single hoặc cluster	cluster
APP_ENV_CACHE_REDIS_IDENTIFIER	Có	Tên logic	cache
APP_ENV_CACHE_REDIS_PASSWORD	Không	Mật khẩu Redis	-
APP_ENV_CACHE_REDIS_HOST	Chế độ single	Host Redis	localhost
APP_ENV_CACHE_REDIS_PORT	Chế độ single	Cổng Redis	6379
APP_ENV_CACHE_REDIS_CLUSTER_NODES	Chế độ cluster	host:port cách nhau bằng dấu phẩy	node1:6379,node2:6380

Redis (BullMQ / Queue)

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_BULLMQ_REDIS_HOST	Nếu dùng queue	Host Redis cho BullMQ	localhost
APP_ENV_BULLMQ_REDIS_PORT	Nếu dùng queue	Cổng Redis	6379
APP_ENV_BULLMQ_REDIS_PASSWORD	Không	Mật khẩu Redis	-

Dịch vụ Bên ngoài

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_IDENTITY_SERVICE_BASE_URL	Có (tất cả verifier)	URL dịch vụ identity cho JWKS	http://localhost:31010/v1/api/identity
APP_ENV_JWKS_REST_PATH	Không	Đường dẫn endpoint JWKS	/jw-certs (mặc định)
APP_ENV_BASIC_AUTH_USERNAME	Không	User HTTP Basic auth	superadmin
APP_ENV_BASIC_AUTH_PASSWORD	Không	Mật khẩu HTTP Basic auth	-

Logging

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_LOGGER_FOLDER_PATH	Không	Thư mục output file log	./app_data/logs
APP_ENV_PARSE_RESULT_FOLDER_PATH	Không	Output kết quả parse	./app_data/parse_result

Khác

Biến	Mô tả	Ví dụ
DEBUG	Bật output debug	true
NODE_ENV	Môi trường runtime	development
RUN_MODE	startup hoặc migrate	startup
TZ	Múi giờ hệ thống	Asia/Ho_Chi_Minh

Chỉ Dịch vụ Identity (JWKS Issuer)

Các biến này chỉ cần cho @nx/identity - JWKS issuer.

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_JWT_EXPIRES_IN	Có	Thời gian sống của JWT tính bằng giây	86400 (1 ngày)
APP_ENV_JWKS_ALGORITHM	Có	Thuật toán ký	ES256
APP_ENV_JWKS_PRIVATE_KEY	Có	Private key ECDSA (PEM, định dạng PKCS#8)	-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
APP_ENV_JWKS_PUBLIC_KEY	Có	Public key ECDSA (PEM)	-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----

Bắt buộc PKCS#8

Private key phải dùng định dạng PKCS#8 (-----BEGIN PRIVATE KEY-----), không phải SEC1 (-----BEGIN EC PRIVATE KEY-----). Tạo bằng:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
  | tee private.pem | openssl pkey -pubout > public.pem

Dịch vụ Licensing

Biến	Bắt buộc	Mô tả	Mặc định
APP_ENV_LICENSING_ED25519_PRIVATE_KEY	Không*	Private key Ed25519 PEM để ký chứng chỉ	-
APP_ENV_LICENSING_ED25519_PUBLIC_KEY	Không*	Public key Ed25519 PEM để xác thực	-
APP_ENV_LICENSING_CERT_TTL_SECONDS	Không	TTL chứng chỉ (ghi vào Redis + payload)	86400

* Nếu thiếu, publishCertificate() sẽ bỏ qua một cách im lặng - license vẫn được phát hành nhưng không có chứng chỉ.

Dịch vụ Signal (WebSocket)

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_WEBSOCKET_REDIS_MODE	Có	single hoặc cluster	single
APP_ENV_WEBSOCKET_REDIS_HOST	Chế độ single	Host Redis WebSocket	localhost
APP_ENV_WEBSOCKET_REDIS_PORT	Chế độ single	Cổng Redis WebSocket	6379
APP_ENV_WEBSOCKET_ECDH_INFO	Có	Chuỗi info HKDF cho mã hóa E2E	-

Dịch vụ Asset (S3 / MinIO)

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_MINIO_HOST	Có	Host lưu trữ tương thích S3	localhost
APP_ENV_MINIO_API_PORT	Có	Cổng API S3	9000
APP_ENV_MINIO_ACCESS_KEY	Có	Access key S3	-
APP_ENV_MINIO_SECRET_KEY	Có	Secret key S3	-

Dịch vụ Search (Typesense)

Biến	Bắt buộc	Mô tả	Ví dụ
APP_ENV_TYPESENSE_API_KEY	Có	API key Typesense	-
APP_ENV_TYPESENSE_NODES	Có	Danh sách node (protocol:host:port)	http:localhost:8108

Commerce / URL Liên dịch vụ

Biến	Mục đích	Ví dụ
APP_ENV_COMMERCE_SERVICE_BASE_URL	Base API Commerce cho các cuộc gọi liên dịch vụ	http://localhost:31020/v1/api/commerce

Dịch vụ Payment

Biến	Mô tả
APP_ENV_MQ_PAY_MODE	Chế độ triển khai: full (mặc định), api (chỉ REST), worker (chỉ BullMQ)

Tham khảo Nhanh Danh mục Dịch vụ

Giá trị từng service của các biến này được tự sinh từ source - xem Platform Facts, nguồn-sự-thật-duy-nhất. Ánh xạ cột: APPLICATION_NAME = tên service, APPLICATION_CODE = mã service, SERVER_PORT = cổng, SNOWFLAKE_WORKER_ID = Snowflake worker, SERVER_BASE_PATH = base path.

Trang Liên quan

Trang	Mô tả
Bắt đầu	Hướng dẫn cài đặt
Hệ thống Build	Target Make
IGNIS Patterns	Pattern cấu hình framework
Licensing - Chứng chỉ	Cách APP_ENV_APPLICATION_SECRET được dùng cho mã hóa chứng chỉ