Chuyển tới nội dung chính

Biến môi trường

Tham chiếu mọi biến môi trường trong .env.example và các biến mà code đọc thêm. Không có giá trị thật nào trong tài liệu này; không đọc file .env. Cột "Mặc định" là giá trị trong code khi không đặt biến.

Cách nạp: ConfigModule.forRoot({ envFilePath: '.env', isGlobal: true, validate: validateEnv }) (app.module.ts). Biến đặt trong môi trường tiến trình được ưu tiên hơn file .env. Hàm kiểm tra env.validation.ts kiểm tra tồn tại; riêng METRICS_PORT được kiểm tra định dạng.

Ký hiệu cột "Bắt buộc": Boot = thiếu thì ứng dụng không khởi động; Prod = bắt buộc thêm ở NODE_ENV=production; Seed = bắt buộc khi chạy npm run seed; Compose = bắt buộc bởi docker-compose.prod.yml; Không = tùy chọn.

Ứng dụng​

BiếnBắt buộcMặc địnhDùng cho
PORTKhông8081Cổng HTTP
NODE_ENVKhôngdevelopmentproduction bật cookie Secure, tắt Swagger, log JSON, yêu cầu thêm biến
FE_URLProdhttp://localhost:3000Liên kết trong email; danh sách CORS khi không có CORS_ORIGINS
CORS_ORIGINSProdrơi về FE_URLDanh sách origin cho phép, cách nhau bằng dấu phẩy
TRUST_PROXYKhôngkhông đặtSố bước proxy tin cậy (số nguyên) hoặc giá trị Express; cần khi chạy sau nginx
SWAGGER_ENABLEDKhôngtắt ở productiontrue để mở Swagger ở production
IMAGE_TAGKhônglatestChỉ dùng bởi docker-compose.prod.yml (tag image backend); đặt trong .env.production, xem rollback

Log và giám sát​

BiếnBắt buộcMặc địnhDùng cho
LOG_LEVELKhônginfo (production), debugMức log pino
SENTRY_DSNKhôngtrống: tắt SentryĐích báo lỗi
SENTRY_TRACES_SAMPLE_RATEKhông0Tỷ lệ trace
METRICS_PORTKhôngtrống: tắtPort server /metrics nội bộ; phải là số nguyên 1–65535. Compose production đặt 9464

MongoDB​

BiếnBắt buộcMặc địnhDùng cho
MONGO_URLBootkhôngChuỗi kết nối. Compose prod ghi đè bằng URL dựng từ các biến MONGO_INITDB_*
MONGO_INITDB_ROOT_USERNAMEComposeroot (compose dev)Khởi tạo tài khoản root của container
MONGO_INITDB_ROOT_PASSWORDCompose123456 (compose dev)Mật khẩu root; production phải đặt mạnh, dạng hex để không phá URI
MONGO_INITDB_DATABASEKhôngmy-job-portalTên database

Ứng dụng không đọc ba biến MONGO_INITDB_*; chỉ Docker Compose dùng chúng.

Redis​

BiếnBắt buộcMặc địnhDùng cho
REDIS_HOSTKhônglocalhostMáy chủ Redis (compose prod ghi đè redis)
REDIS_PORTKhông6379Cổng
REDIS_PASSWORDComposekhôngMật khẩu; compose prod bắt buộc
REDIS_QUEUE_DBKhông0DB cho hàng đợi BullMQ
REDIS_CACHE_DBKhông1DB cho cache danh sách, OTP, quota, rate limit
REDIS_TTLKhông3600000TTL mặc định truyền cho CacheModule; lưu ý CACHE_MANAGER thực tế chạy trong bộ nhớ (data-flow)

Xác thực​

BiếnBắt buộcMặc địnhDùng cho
JWT_ACCESS_TOKEN_SECRETBootkhôngKý access token; cũng dùng xác minh token của Socket.IO. Production: tối thiểu 32 ký tự
JWT_ACCESS_EXPIRES_INBootkhôngThời hạn access token (.env.example mẫu 15m)
JWT_REFRESH_TOKEN_SECRETBootkhôngKý refresh token và tính HMAC lưu phiên. Production: tối thiểu 32 ký tự, phải khác JWT_ACCESS_TOKEN_SECRET
JWT_REFRESH_EXPIRES_INBootkhôngThời hạn refresh token và cookie (mẫu 7d)
OTP_SECRETBootkhôngKhóa HMAC cho OTP. Production: tối thiểu 32 ký tự
GOOGLE_CLIENT_IDKhôngkhôngaudience khi xác minh Google ID token
GOOGLE_CLIENT_SECRETKhôngkhôngKhông có chỗ nào trong src/ đọc biến này

Tạo secret bằng openssl rand -hex 32. Không đưa vào git.

Dữ liệu mẫu​

BiếnBắt buộcMặc địnhDùng cho
EMAIL_ADMINSeedkhôngEmail tài khoản quản trị tạo bởi seed
INIT_PASSWORDSeedkhôngMật khẩu của mọi tài khoản do seed tạo. Ngoài development/test chỉ tạo admin và yêu cầu tối thiểu 12 ký tự

Email​

BiếnBắt buộcMặc địnhDùng cho
SMTP_HOSTKhôngkhôngMáy chủ SMTP
SMTP_EMAILKhôngkhôngTên đăng nhập SMTP
SMTP_PASSWORDKhôngkhôngMật khẩu SMTP

Thiếu cấu hình SMTP không làm ứng dụng từ chối khởi động nhưng gửi email sẽ lỗi.

Nhà cung cấp AI​

BiếnBắt buộcMặc địnhDùng cho
GEMINI_API_KEYKhông (thực tế có)khôngKhóa Gemini; GeminiService không khởi động nếu thiếu theo .env.example
GEMINI_MODELKhônggemini-3.1-flash-liteMô hình Gemini
GROQ_API_KEYKhôngkhôngKhóa Groq; thiếu thì Groq không khả dụng
GROQ_CHAT_MODELKhôngopenai/gpt-oss-20bMô hình chat
GROQ_SUMMARY_MODELKhôngnhư mô hình chatMô hình tóm tắt
GROQ_TIMEOUT_MSKhông30000Thời gian chờ của SDK
GROQ_MAX_RETRIESKhông2Số lần SDK thử lại
AI_CHAT_PRIMARY_PROVIDERKhônggroqNhà cung cấp chính cho chat (gemini hoặc groq)
AI_CHAT_GEMINI_FALLBACK_ENABLEDKhôngbậtCho phép dự phòng Gemini khi chat
AI_SUMMARY_PRIMARY_PROVIDERKhônggroqNhà cung cấp chính cho tóm tắt
AI_SUMMARY_GEMINI_FALLBACK_ENABLEDKhôngbậtCho phép dự phòng Gemini khi tóm tắt
AI_COST_GROQ_PROMPT_USD_PER_1KKhông0Đơn giá token đầu vào để ước tính chi phí (mẫu khác: AI_COST_PROMPT_USD_PER_1K)
AI_COST_GROQ_COMPLETION_USD_PER_1KKhông0Đơn giá token đầu ra

Ngân sách ngữ cảnh gửi Groq​

.env.example ghi nhóm này là bắt buộc và AIService kiểm tra; trong code có giá trị mặc định (ai.constants.ts).

BiếnMặc địnhÝ nghĩa
AI_GROQ_HISTORY_LIMIT6Số tin lịch sử
AI_GROQ_MAX_INPUT_TOKENS6000Trần token đầu vào
AI_GROQ_MAX_MATCHING_JOBS3Số tin phù hợp đưa vào prompt
AI_GROQ_MAX_SEARCH_RESULTS3Số kết quả tìm kiếm
AI_GROQ_MAX_COMPANY_ITEMS2Số công ty
AI_GROQ_MAX_TOP_SKILLS5Số kỹ năng hàng đầu
AI_GROQ_MAX_TOP_COMPANIES5Số công ty hàng đầu
AI_GROQ_MAX_SUMMARY_CHARS400Độ dài tóm tắt

Quota Gemini​

Mọi biến tùy chọn; mặc định ở gemini-quota.constants.ts và gemini-quota.service.ts. Cơ chế: cv-parsing-and-matching.

BiếnMặc địnhÝ nghĩa
GEMINI_RPM15Giới hạn mỗi phút
GEMINI_DAILY_BUDGET450Ngân sách mỗi ngày
GEMINI_DAILY_ALERT_THRESHOLDS70,85,95Ngưỡng cảnh báo (phần trăm)
GEMINI_PARSE_MINUTE_RESERVE, GEMINI_PARSE_DAILY_RESERVE0, 0Phần chừa của việc đọc CV
GEMINI_SUMMARY_MINUTE_RESERVE, GEMINI_SUMMARY_DAILY_RESERVE4, 50Phần chừa của tóm tắt
GEMINI_CHAT_FALLBACK_MINUTE_RESERVE, GEMINI_CHAT_FALLBACK_DAILY_RESERVE2, 25Phần chừa của chat dự phòng
GEMINI_QUOTA_RETRY_JITTER_MS1000Nhiễu ngẫu nhiên khi lên lịch lại việc đọc CV

Chat​

BiếnMặc địnhÝ nghĩa
CHAT_QUOTA_NORMAL_USER_DAILY_LIMIT30Lượt mỗi ngày cho NORMAL USER khi không có bản ghi chính sách
CHAT_QUOTA_HR_DAILY_LIMIT100Lượt mỗi ngày cho HR
CHAT_CONTEXT_CACHE_TTL_MS10 phútTTL cache ngữ cảnh chat
CHAT_FAQ_CACHE_TTL_MS24 giờTTL cache FAQ
CHAT_TOOL_ACTION_EXPIRY_MS15 phútThời hạn xác nhận hành động

Bí mật cần bảo vệ​

JWT_ACCESS_TOKEN_SECRET, JWT_REFRESH_TOKEN_SECRET, OTP_SECRET, MONGO_INITDB_ROOT_PASSWORD, REDIS_PASSWORD, SMTP_PASSWORD, GOOGLE_CLIENT_SECRET, GEMINI_API_KEY, GROQ_API_KEY, INIT_PASSWORD, SENTRY_DSN. Danh sách trước khi mở production: production-security-checklist.