Chương 8: Vận hành & Xử lý sự cố thường gặp (Troubleshooting)

Quá trình vận hành Signing Service Tân Cảng trải qua sự đóng góp của nhiều luồng kết nối phân tán. Chương này liệt kê các lỗi phổ biến mà quản trị viên, chuyên viên hỗ trợ (Support/IT) thường gặp và cách check log bắt bệnh chính xác.

8.1. Lỗi Không nhận USB Token trên Desktop App

Luồng chạy ứng dụng Desktop phụ thuộc sát sao vào độ ổn định phần cứng máy tính và Driver hãng.

Hiện tượng: Ứng dụng Desktop chạy, nhưng khi gọi lệnh ký thì pop-up báo "Không tìm thấy thiết bị Token" hoặc văng lỗi PKCS11Exception. Cách xử lý:

  1. Rút ra cắm lại USB Token, đảm bảo trên thanh System Tray Windows ở góc dưới màn hình đã hiển thị phần mềm ký của thiết bị (Ví dụ: Viettel-CA Manager).
  2. Kiểm tra tệp 

    token-config.json:
    • Mở file .json này tại thư mục chạy của Desktop App.
    • Kiểm tra đường dẫn chuỗi "libraryPath": "C:\\Windows\\System32\\eps2003csp11.dll" có đúng tới file .dll đang nằm sẵn trong Windows không. Đôi lúc bản Update của hãng đổi tên .dll gây hỏng tiến trình hook.
  3. Đóng ứng dụng Desktop (Quit ở System Tray) và chạy lại. Lỗi về session thẻ nhớ SmartCard thường sẽ hết.

8.2. Lỗi Chuyển đổi Khống Format (File Conversion Issues)

  1. Một trong những vấn đề đau đầu nhất là khi người dùng Upload một file không chính thống nhưng "vô tình hoặc cố ý" bị đổi sai định dạng đuôi file.

    Hiện tượng: Quăng lỗi UnsupportedFileFormatException khi đang thực thi bộ chuyển đổi Aspose.Words (ví dụ: Chuyển .docx sang .pdf). Nguyên nhân gốc rễ (Root Cause): File thực chất đã là chuẩn .pdf bên trong, nhưng người dùng (hoặc hệ thống tạo tự động) lại đang lưu tên nó với đuôi mở rộng là .docx. Bộ máy Aspose Words tiếp nhận file tưởng đây là Word, mở ra thấy sai logic binaire của Office thì quăng lỗi. Cách xử lý & Cách dự án giải quyết: Vấn đề này đã được Patch trong nhánh xử lý của 

    SigningController. Hệ thống sử dụng cơ chế đọc Magic Bytes để xem cấu trúc thật của Core File (Hex Header bắt đầu bằng %PDF- thì by-pass cơ chế converter của Word/Excel và coi thẳng đó là PDF). Đảm bảo File luôn lọt qua máy chủ ký tự động.

8.3. Lỗi Request OTP & Authentication (HTTP 400/401)

Dự án áp dụng logic ký bảo mật qua Session OTP sinh tự động. Lỗi thường phát sinh tại API /api/sign/request-otp và API ký.

Hiện tượng: Web/Portal trả về thông điệp lỗi HTTP status 400 Bad Request, hoặc "Phiên ký không hợp lệ". Cách khắc phục:

  1. Khi gọi /api/sign, Client bắt buộc phải có thông tin Token phiên làm việc ở Header Token-Signing.
  2. Dữ liệu Request OTP yêu cầu người dùng (username) và email được cấp từ SecurityUtils phải đúng cấu trúc. IT cần kiểm tra hệ thống tài khoản E-Office đã gửi User Context hợp lệ sang khối Ký số chưa (Nếu Header OAuth/JWT truyền qua sai username, Service sẽ ngắt lệnh).

8.4. Lỗi độ trễ Redis Cache (EJBCA Lookup Error)

Hiện tượng: Tài liệu ký bị pending quá lâu, timeout, hoặc hệ thống báo "Người dùng không tồn tại". Cách xử lý:

  1. Hệ thống dùng Redis để quản lý cache hàm endEntityExists().
  2. IT cần kiểm tra xem Container kyso-redis có đang sống và đáp trả lệnh ping không (docker logs kyso-redis).
  3. Trong trường hợp người dùng trên CA vừa mới bị vô hiệu hóa hoặc thu hồi chứng chỉ .p12, việc kiểm tra cache bị "lỗi nhịp" với thực tế. Hệ thống signing-web-service đã xử lý bằng lệnh signingService.revokeCache(username) xóa ngay luồng cache chết trên Redis.
  4. Môi trường Dev có thể thử lệnh redis-cli flushall để xóa sạch Redis phục vụ Test Fresh Data với máy chủ EJBCA.

(Bản tài liệu "Signing Service Tân Cảng" được hoàn thành phục vụ công tác đào tạo và bàn giao Source Code. Mọi vấn đề về Security Endpoint hay Keys vui lòng liên hệ Admin System Tân Cảng).