Skip to main content
Version: 1.1.0

Hướng Dẫn Xử Lý Sự Cố Thường Gặp (Troubleshooting)

Tài liệu này tổng hợp các sự cố thường gặp trong quá trình cài đặt, vận hành môi trường ERPNext bằng sPhoton ERP CLI (erp) và cách giải quyết chúng.

1. Sự cố Ngôn ngữ mặc định của Setup Wizard vẫn hiện tiếng Anh​

1.1. Hiện tượng​

Dù đã cấu hình mặc định tiếng Việt trong database và site_config.json, khi bạn truy cập trang web lần đầu tiên (Setup Wizard), ô chọn ngôn ngữ (Your Language) vẫn hiển thị mặc định là English thay vì Tiếng Việt.

1.2. Nguyên nhân​

Trong mã nguồn client-side JS của Frappe framework (setup_wizard.js), trường language được định nghĩa cứng giá trị mặc định là "English" (default: "English"). Khi trang Setup Wizard load lên, trường này nhận giá trị "English", khiến điều kiện kiểm tra trường rỗng if (!slide.get_value("language")) luôn trả về false. Do đó, logic tự động điền ngôn ngữ hệ thống (vi) hoặc ngôn ngữ trình duyệt (Accept-Language) bị bỏ qua hoàn toàn, dẫn đến ô chọn ngôn ngữ luôn bị kẹt hiển thị "English".

1.3. Giải pháp tự động của CLI​

CLI của chúng ta đã được tích hợp cơ chế tự động vá lỗi (auto-patch):

  1. Vá file JS: CLI tự động đọc và chỉnh sửa file /apps/frappe/frappe/desk/page/setup_wizard/setup_wizard.js ở host ngay khi container khởi chạy lần đầu. Nó xoá dòng default: "English", và bọc logic gán session_language bằng hàm dịch tên mã ngôn ngữ get_language_name_from_code để tự động điền sẵn chữ "Tiếng Việt" lên ô chọn ngôn ngữ.
  2. Tắt tạm thời ngôn ngữ tiếng Anh: CLI tạm thời tắt kích hoạt (disable) ngôn ngữ en trong tabLanguage khi cài đặt site mới để đảm bảo Setup Wizard nhận diện tiếng Việt là ngôn ngữ mặc định duy nhất.
  3. Kích hoạt lại tiếng Anh (nếu cần): Sau khi hoàn thành xong Setup Wizard, nếu bạn cần sử dụng thêm tiếng Anh, bạn chỉ cần vào màn hình Danh sách ngôn ngữ (Language List) trên thanh tìm kiếm ERPNext, tìm bản ghi en và tích chọn Kích hoạt (Enabled) là xong.

2. Lỗi Quyền truy cập Docker Image (Image Access Denied)​

2.1. Hiện tượng​

Khi chạy erp run, lệnh kéo image từ registry thất bại với lỗi dạng pull access denied, does not exist, hoặc unauthorized. Điều này xảy ra do lỗi mạng hoặc không có quyền truy cập vào private registry chứa base image.

2.2. Giải pháp tự động của CLI​

CLI sẽ tự động bắt lỗi này và hiển thị câu hỏi trên terminal:

Image access denied or not found. Would you like to build the image instead? (y/n)

Nếu bạn chọn y, CLI sẽ tự động kích hoạt tiến trình build image trực tiếp từ Dockerfile và các tài nguyên cục bộ (docker compose build), sau đó chạy lại lệnh up. Quá trình này giúp bạn tiếp tục cài đặt mà không cần kết nối tới registry bên ngoài.

3. Lỗi Quyền truy cập Database root (Database Root Access Denied)​

3.1. Hiện tượng​

Khi chạy erp run, lệnh ping kiểm tra MariaDB container trả về lỗi Access denied. Điều này thường xảy ra khi thư mục volume db-data từ lần chạy cũ của dự án khác vẫn tồn tại nhưng mật khẩu root cấu hình lần này lại khác, dẫn đến xung đột thông tin xác thực của database.

3.2. Giải pháp tự động của CLI​

CLI sẽ phát hiện lỗi xác thực root này và hiển thị cảnh báo kèm câu hỏi:

Database root access denied. ... Would you like to recreate the database volume? (y/n)

Nếu bạn chọn y, CLI sẽ tự động dừng dự án, xóa hoàn toàn volume cũ bị xung đột bằng lệnh docker compose down -v, khởi động lại container mới tinh và tiếp tục quy trình cài đặt sạch sẽ từ đầu.

4. Giao diện Desk hoặc Setup Wizard không nhận thay đổi cấu hình mới​

4.1. Hiện tượng​

Bạn vừa chỉnh sửa file cấu hình hoặc mã nguồn Python/JS nhưng khi F5 trình duyệt vẫn thấy dữ liệu cũ hoặc giao diện cũ hiển thị.

4.2. Giải pháp​

  1. Xoá cache trình duyệt: Trình duyệt có thể cache rất mạnh file JS tĩnh của Desk hoặc Setup Wizard. Hãy ấn tổ hợp phím Ctrl + F5 (hoặc Cmd + Shift + R trên macOS) để buộc trình duyệt tải lại hoàn toàn tài nguyên mới từ server.
  2. Xoá cache hệ thống Frappe: Chạy lệnh xoá cache trên site: 
    docker compose exec -T backend bench --site localhost execute "frappe.clear_cache()"
  3. Khởi động lại các containers: 
    erp dev reload

5. Lỗi clone các ứng dụng tùy chỉnh (Failed to clone custom apps / private repos)​

5.1. Hiện tượng​

Khi chạy erp run hoặc cài app qua erp app install, tiến trình gặp lỗi không có quyền truy cập hoặc không thể clone repository private từ GitHub (lỗi dạng Repository not found hoặc Permission denied (publickey)).

5.2. Nguyên nhân​

Môi trường Docker container mặc định không có sẵn thông tin xác thực để clone các mã nguồn từ các kho lưu trữ riêng tư (private repo) trên GitHub của bạn hoặc của tổ chức.

5.3. Cách giải quyết​

Hệ thống cung cấp cho bạn 2 cách giải quyết cực kỳ đơn giản và nhanh chóng:

  1. Sử dụng GitHub Personal Access Token (PAT):

    • Tạo một token có quyền đọc repo trên tài khoản GitHub của bạn.
    • Đăng nhập token vào hệ thống bằng lệnh: 
      erp github login --token <access_token>
    • CLI sẽ tự động kiểm tra, mã hóa an toàn và áp dụng token này để chuyển đổi tự động các URL clone dạng SSH/HTTPS sang dạng HTTPS OAuth2 có chứa token ở thời điểm runtime.

  2. Sử dụng Khóa SSH của máy host:

    • Nếu máy của bạn đã liên kết SSH Key thành công với GitHub, hãy import nó vào hệ thống: 
      erp ssh-key import --path ~/.ssh
    • CLI sẽ ghi nhận và tự động mount thư mục khóa SSH này vào container backend dưới dạng chỉ đọc (:ro) khi khởi dựng. Container sẽ tự động thừa hưởng toàn bộ thông tin xác thực SSH Key và known_hosts từ máy host để clone mã nguồn dạng SSH (git@github.com:...).