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

Xử lý sự cố

Bảng triệu chứng, nguyên nhân khả dĩ và cách kiểm tra. Mọi thông báo lỗi trích từ source. Các bước chưa chạy thử trên hệ thống thật được ghi rõ.

Khởi động​

Triệu chứngNguyên nhânCách xử lý
Missing required environment variables: ...Thiếu biến bắt buộc (env.validation.ts)Bổ sung MONGO_URL, JWT_*, OTP_SECRET; ở production thêm FE_URL, CORS_ORIGINS
Dịch vụ AI không khởi động / GeminiService báo thiếu khóaThiếu GEMINI_API_KEYĐặt khóa; xem ai-providers
Lỗi AI_GROQ_* khi khởi độngAIService kiểm tra nhóm biến ngân sách GroqĐặt các biến theo .env.example
Không kết nối MongoDBSai MONGO_URL; container chưa khỏe; mật khẩu có ký tự @ / :docker compose ps; dùng mật khẩu hex (deployment)
Không kết nối RedisSai REDIS_HOST, REDIS_PASSWORDKiểm tra Redis; compose prod bắt buộc REDIS_PASSWORD
npm run dev:services / dev:stop / migrate:locations lỗiScript trỏ tới file không tồn tạiDùng npm run docker:dev / docker:down; xem local-development
Container unhealthyGET /api/v1/health/live thất bại: process không còn phục vụ HTTP (Mongo hoặc Redis lỗi thì xem /health/ready và alert DependencyDown)docker compose logs backend; thử curl health trong container

Đăng nhập và phiên​

Triệu chứngNguyên nhânCách xử lý
401 "Token không hợp lệ hoặc đã hết hạn"Access token hết hạn hoặc saiGọi GET /auth/refresh
Làm mới token trả 400 "Session not found or already used"Refresh token đã dùng, đã đăng xuất, hoặc bị đẩy khỏi giới hạn 5 phiên; hai tab làm mới cùng lúcĐăng nhập lại; điều phối làm mới ở client
Cookie refresh_token không được gửiProduction dùng Secure + SameSite=Strict; frontend và API khác site hoặc dùng HTTPChạy cùng site qua HTTPS
401 "Tài khoản đã bị khóa" / "bị vô hiệu hóa"isLocked hoặc isActive = falseQuản trị viên mở khóa; tài khoản chưa xác thực quá 15 phút đã bị xóa tự động
403 "Tài khoản đang chờ bị xóa"Đã yêu cầu xóa tài khoảnHủy bằng link trong email (token có thể đã mất sau khi backend khởi động lại, xem Known Limitation của auth-and-sessions)
Link đặt lại mật khẩu báo hết hạn dù mới gửiBackend vừa khởi động lại; token nằm trong bộ nhớYêu cầu link mới
OTP "không chính xác" / 403Sai mã; từ 5 lần sai bị chặnChờ hết hạn (5 phút) rồi gửi lại; gửi lại có chờ 60 giây
429 Too Many RequestsVượt @Throttle hoặc throttler toàn cụcChờ; kiểm tra TRUST_PROXY nếu mọi người dùng chung bị chặn
Mọi người dùng bị 429 cùng lúcTRUST_PROXY chưa đặt nên mọi request mang IP của proxyĐặt TRUST_PROXY=1 (deployment)

Hồ sơ và CV​

Triệu chứngNguyên nhânCách xử lý
Hồ sơ kẹt processing / isParsed = falseHàng đợi chưa chạy; hết quota Gemini; văn bản CV không hợp lệXem parseError, analysisError của bản ghi; GET /resumes/queue/stats; log "Rescheduled parse"
parseError "Invalid CV text: Text too short"CV scan ảnh hoặc rỗng; dưới 100 ký tự, dưới 50 từYêu cầu file có chữ; giới hạn 100 đến 50.000 ký tự
analysisError "Resume must be parsed before analysis"Việc phân tích chạy trước khi đọc xongSẽ tự hết khi việc analyze do bước đọc sinh ra chạy; hoặc POST /resumes/:id/reanalyze
analysisError "Job is no longer active"Tin đã hết hoạt độngKhông phân tích được cho tới khi tin hoạt động trở lại
Điểm thấp hoặc cao bất thườngKhớp kỹ năng bằng chuỗi con; mức thành thạo mặc định 70cv-parsing-and-matching
Nộp CV trực tuyến báo "Your CV profile is inactive"CV bị tắtPOST /cv-profiles/me/activate
Upload 400 "Invalid folder_type"Thiếu hoặc sai header folder_typeDùng avatar, cv, resumes, company

Tin từ nguồn ngoài​

Triệu chứngNguyên nhânCách xử lý
Nguồn không đồng bộenabled = false; việc sync-<key> còn trong hàng đợi; lỗi liên tiếpGET /job-sources, GET /job-sources/:key/runs
Lần chạy SUSPECTDanh sách nguồn co dưới 50% mức nền hoặc rỗngKiểm tra nguồn; không tin nào bị đóng vì vắng mặt
Lần chạy PARTIALBị chặn 403, 429, captcha khi tải chi tiếtChờ lần sau; không tăng tốc độ (đã giới hạn 1 request mỗi giây)
Tin ngoài mất khỏi tìm kiếmNguồn bị HIDDEN; tin CLOSED; hết expiresAtXem trạng thái external-jobs
Mô tả tin ngoài trốngNguồn LINK_ONLYĐổi displayPolicy sang FULL rồi chờ đồng bộ (đổi sang LINK_ONLY xóa mô tả đã lưu)
POST /job-sources/:key/sync trả queued nhưng không có gì xảy raViệc cùng jobId đã tồn tại (đang chờ hoặc chạy)Chờ việc hiện tại; BullMQ bỏ qua việc trùng jobId

Chat AI​

Triệu chứngNguyên nhânCách xử lý
Sự kiện error kèm quota.nextResetTimeHết hạn mức ngày (30/100)Chờ đến thời điểm đặt lại, hoặc đổi dailyLimit trong chat_quota_policies
400 "Your message appears to contain instructions..."Guardrail chặn mẫu rủi ro caoDiễn đạt lại; kể cả câu hỏi nghề nghiệp có "write Python" có thể bị chặn nhầm
Câu trả lời là thông báo từ chối song ngữBộ lọc chủ đề cho là lạc đềHỏi lại trong phạm vi nghề nghiệp IT
Chat chậm hoặc lỗiGroq lỗi: tự chuyển sang Gemini nếu bật dự phòng và còn quotaXem fallbackUsed trong ai_usage_logs
Quota chat về 0 sau khi Redis mất dữ liệuBộ đếm nằm trong RedisChờ sang ngày; bộ đếm tự đặt lại

Dữ liệu​

Triệu chứngNguyên nhânCách xử lý
Danh sách tin/công ty cũ tối đa 60 giây / 3 phútCache danh sáchChờ hết TTL; cache tự xóa khi dữ liệu đổi qua API
Dashboard lệch giữa các lần tảiCache trong bộ nhớ, TTL 3 đến 15 phútChờ hoặc khởi động lại
Truy vấn bằng chuỗi không ra kết quả với cvprofiles/chat_*userId là Mixed; truy vấn phải dùng ObjectIddatabase-overview
Bản ghi đã xóa vẫn xuất hiện ở truy vấn mớiPlugin xóa mềm không lọc findOne, aggregate, update*Thêm isDeleted tường minh
Chỉ mục mong đợi (TTL, unique) không tồn tạiKhai báo index trùng key patterndb.<collection>.getIndexes() (database-overview)

Thu thập thông tin khi báo lỗi​

  1. X-Request-Id trong header phản hồi.
  2. Dòng log theo req.id.
  3. Sự kiện Sentry có tag request_id (nếu bật).
  4. Với hồ sơ: parseError, analysisError, isParsed, isAnalyzed.
  5. Với nguồn tin: bản ghi crawl_runs gần nhất.

Không dán token, OTP, nội dung CV hay .env vào ticket.