Troubleshooting Hướng dẫn W5 & W6

Tài liệu hướng dẫn xử lý các sự cố thường gặp trong giai đoạn cấu hình Data Pipeline, Database, và Deployment (Sprint 3).

1. Lỗi kết nối MSSQL

Triệu chứng: Không thể kết nối DB từ FastAPI, lỗi Connection refused hoặc Login failed for user.
Nguyên nhân có thể: MSSQL Server chưa được start, cấu hình TCP/IP bị tắt trong SQL Server Configuration Manager, sai thông tin credentials.
Các bước khắc phục:
1. Kiểm tra services.msc xem dịch vụ SQL Server (MSSQLSERVER) đang chạy hay chưa.
2. Mở SQL Server Configuration Manager, bật (Enable) TCP/IP trong mục Network Configuration.
3. Restart dịch vụ SQL Server.
4. Kiểm tra lại thông tin username/password trong chuỗi kết nối (.env).

Triệu chứng: Lỗi khi chạy pip install chromadb, thường báo lỗi liên quan đến trình biên dịch C++ hoặc hnswlib.
Nguyên nhân có thể: Thiếu Build Tools for Visual Studio (do ChromaDB cần biên dịch C++ native extensions).
Các bước khắc phục:
1. Tải và cài đặt Microsoft C++ Build Tools.
2. Chọn workload "Desktop development with C++" khi cài đặt.
3. Khởi động lại terminal và chạy lại pip install chromadb.

Triệu chứng: Khi chạy trên IIS bị lỗi HTTP 500.19 hoặc 502.3 Bad Gateway.
Nguyên nhân có thể: HttpPlatformHandler chưa được cài, sai đường dẫn tới file chạy Python hoặc processPath không chính xác trong web.config.
Các bước khắc phục:
1. Đảm bảo đã cài đặt HttpPlatformHandler v1.2.
2. Kiểm tra web.config, đảm bảo processPath trỏ đúng thư mục Python (python.exe hoặc thư mục venv).
3. Kiểm tra các quyền đọc/thực thi của IIS_IUSRS trên thư mục mã nguồn.
4. Kiểm tra log của IIS để có thêm chi tiết (hoặc stdout log cấu hình trong web.config).

Triệu chứng: Gõ .\venv\Scripts\activate báo lỗi Execution of scripts is disabled on this system.
Nguyên nhân có thể: Chính sách thực thi (Execution Policy) của PowerShell hạn chế chạy script.
Các bước khắc phục:
1. Mở PowerShell dưới quyền Admin.
2. Chạy lệnh: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.
3. Kích hoạt lại .\venv\Scripts\activate.

Triệu chứng: Cài đặt thư viện bằng pip báo lỗi ReadTimeoutError hoặc Could not find a version that satisfies the requirement.
Nguyên nhân có thể: Mạng chậm, tường lửa/proxy chặn kết nối tới PyPI, hoặc dùng phiên bản Python không tương thích với package.
Các bước khắc phục:
1. Nâng cấp pip: python -m pip install --upgrade pip.
2. Thử tăng thời gian timeout bằng flag --default-timeout=100: pip install --default-timeout=100 <package_name>.
3. Kiểm tra lại phiên bản Python (ví dụ: một số package chưa hỗ trợ phiên bản Python mới nhất).