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

Soạn thảo OnlyOffice

govex-cloud-onlyoffice tích hợp OnlyOffice Document Server: trả cấu hình trình soạn thảo có JWT, phân phối file cho Document Server qua capability token và nhận callback để lưu bản chỉnh sửa vào storage. Dùng khi webapp cần cho người dùng soạn thảo DOCX trực tiếp trong trình duyệt.

Khi nào sử dụng​

  • Nhúng trình soạn thảo OnlyOffice vào webapp để người dùng chỉnh sửa văn bản DOCX.
  • Cho Document Server tải file từ backend mà không cần public storage.
  • Tự động lưu bản đã chỉnh sửa vào storage và đồng bộ lại hồ sơ nghiệp vụ sau khi kết thúc phiên soạn thảo.
  • Phục vụ plugin "Đặt vị trí cần điền" cho merge field trong trình soạn thảo.

Cài đặt​

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-onlyoffice</artifactId>
</dependency>

Version do BOM quản lý, xem Cài đặt.

Cấu hình​

govex:
  onlyoffice:
    enabled: true
    document-server-url: http://onlyoffice-server:80
    secret: ${ONLYOFFICE_JWT_SECRET}
    internal-base-url: http://backend:8080
PropertyMô tảMặc định
govex.onlyoffice.enabledBật tích hợp OnlyOffice; phải khai báo true tường minh, nếu thiếu property thì auto-configuration không đăng ký— (không bật)
govex.onlyoffice.document-server-urlURL OnlyOffice Document Server—
govex.onlyoffice.secretKhóa bí mật JWT dùng chung giữa backend và Document Server—
govex.onlyoffice.callback-token-requiredBắt buộc callback phải có JWT hợp lệtrue
govex.onlyoffice.callback-pathĐường dẫn callback để Document Server gọi/api/v1/onlyoffice/callback
govex.onlyoffice.internal-base-urlURL nội bộ gốc để Document Server tải file; nếu trống dùng URL gốc của request—
govex.onlyoffice.token-expirationThời hạn JWT cấu hình editor (giây)3600
govex.onlyoffice.callback-context-token-expirationTTL token ngữ cảnh callback (giây); phải lớn hơn hoặc bằng editor-absolute-lifetime và phần dư đủ callback-retry-window90000
govex.onlyoffice.editor-absolute-lifetimeVòng đời tuyệt đối tối đa của phiên editor (giây)86400
govex.onlyoffice.callback-retry-windowCửa sổ retry callback sau khi editor kết thúc (giây)3600
govex.onlyoffice.presigned-url-expirationThời hạn presigned URL truy cập file (giây)3600
govex.onlyoffice.plugin-api-base-urlURL API fallback để plugin lấy biến dữ liệu nghiệp vụ—

Sử dụng​

Host bắt buộc cung cấp đúng một bean OnlyOfficeEditorAuthorizationService để kiểm tra quyền mở tài liệu:

@Bean
OnlyOfficeEditorAuthorizationService onlyOfficeEditorAuthorizationService(QuyenTaiLieuService quyenService) {
    return (query, currentUserId) -> quyenService.kiemTraQuyenMo(query.getFileId(), currentUserId);
}

Luồng tích hợp:

  1. Frontend gọi GET /api/v1/onlyoffice/editor?fileId=<path>&fileName=<name>&templateType=TYPE_1&documentId=<id>&mode=edit để nhận EditorConfigResponse.
  2. Frontend truyền response vào new DocsAPI.DocEditor("placeholder", config) để khởi tạo trình soạn thảo.
  3. Document Server tải file qua GET /api/v1/onlyoffice/file/**?accessToken=... và gọi POST /api/v1/onlyoffice/callback mỗi khi có thay đổi.
  4. Dependency tải bản chỉnh sửa, chuẩn hóa merge field, lưu vào Storage và phát OnlyOfficeDocumentSavedEvent.

Lắng nghe sự kiện để đồng bộ hồ sơ nghiệp vụ:

@EventListener
public void onDocumentSaved(OnlyOfficeDocumentSavedEvent event) {
    if (event.isTerminal()) {
        hoSoService.capNhatBanChinhSua(event.getDocumentId(), event.getEditedFilePath());
    }
}

Lưu ý​

  • Cần OnlyOffice Document Server đang chạy và govex.onlyoffice.secret khớp cấu hình JWT của Document Server.
  • Cần govex-cloud-oss (bean Storage) để lưu/đọc file; hạ tầng storage (MinIO/S3) do ứng dụng cấu hình.
  • Nếu không có hoặc có nhiều hơn một bean OnlyOfficeEditorAuthorizationService, endpoint /editor trả HTTP 403.
  • /config và /editor đi qua policy host của govex-cloud-security; /callback, /file/**, /plugins/merge-field/** dùng capability token/asset công khai.
  • Khi Document Server chạy trong mạng container không truy cập được URL public của backend, phải cấu hình govex.onlyoffice.internal-base-url.