CHƯƠNG 3: HƯỚNG DẪN VẬN HÀNH & DEV

Chương này được thiết kế như một bản hướng dẫn từng bước (Step-by-step) để cài đặt, cấu hình và khởi chạy hệ thống trong môi trường phát triển và vận hành thực tế.

Trang 1: Chuẩn bị môi trường
Trang 2: Cấu hình hệ thống
Trang 3: Build & Deployment
Trang 4: Logging & Giám sát (Monitoring)

Trang 1: Chuẩn bị môi trường

Để chạy dự án service-proxy, hệ thống cần cài đặt sẵn các thành phần sau:

Java Development Kit (JDK) 17: Khuyến nghị sử dụng OpenJDK 17 hoặc Oracle JDK 17.
- Kiểm tra bằng lệnh: java -version
Apache Maven 3.8+: Dùng để build mã nguồn.
- Kiểm tra bằng lệnh: mvn -version
Kết nối mạng: Đảm bảo Server Proxy có quyền truy cập tới:
- Các cụm Signing Cluster (cổng mặc định: 6868).
- CRM/External API (cổng mặc định: 356).
- Callback Server (cổng mặc định: 8386).

Trang 2: Cấu hình hệ thống

Hệ thống hỗ trợ cấu hình linh hoạt thông qua file application.yml hoặc các biến môi trường (Environment Variables).

2.1 Các tham số cấu hình chính

Tham số	Biến môi trường (Env)	Giá trị mặc định	Mô tả
`server.port`	`SERVER_PORT`	`8080`	Port lắng nghe của Proxy
`external.api.base-url`	`EXTERNAL_API_BASE_URL`	`https://administrator.lifetex.vn:356`	URL dịch vụ CRM/BPMN
`signing-service.api.base-url`	`SIGNING_SERVICE_BASE_URL`	`http://192.168.0.51:6868`	URL dịch vụ ký số (Engine)
`callback.server.base-url`	`CALLBACK_SERVER_BASE_URL`	`http://192.168.0.185:8386`	URL nhận callback

2.2 Cấu hình Timeout (Quan trọng cho ký số)

Các yêu cầu ký file PDF lớn có thể mất nhiều thời gian, do đó cần chú ý cấu hình:

connect-timeout-ms: 60000 (60 giây).
read-timeout-ms: 60000 (60 giây).

Trang 3: Build & Deployment

Dự án đã tích hợp sẵn các script tự động hóa cho các hệ điều hành:

3.1 Triển khai trên Windows

Sử dụng file run-windows.bat.
Script sẽ tự động:
- Kiểm tra sự tồn tại của file JAR trong thư mục target/.
- Nếu chưa có, script sẽ tự chạy mvn clean package để build.
- Sau đó khởi chạy ứng dụng bằng Java và ghi log ra file app.log.

3.2 Triển khai trên Linux/macOS

Cấp quyền thực thi: chmod +x run-linux.sh
Chạy lệnh: ./run-linux.sh
Script sẽ build project (nếu cần) và khởi chạy ứng dụng dưới dạng tiến trình (Process).

Trang 4: Logging & Giám sát (Monitoring)

4.1 File Log

Windows: Log được ghi song song vào Console và file app.log tại thư mục gốc của dự án.
Linux: Log mặc định đẩy ra STDOUT (có thể chuyển hướng bằng > app.log 2>&1).

4.2 Mức độ Log (Log Levels)

Bạn có thể cấu hình mức độ chi tiết của log trong application.yml:

logging:
  level:
    org.springframework: INFO
    com.example: DEBUG # Bật DEBUG để xem các URL thực tế proxy đang gọi

Khi chạy trong môi trường Production, hãy chuyển com.example về mức INFO để tránh ghi log quá nhiều, gây đầy ổ cứng.