Hướng dẫn: Nhúng Doconut Viewer một cách an toàn với React – Từ đầu đến cuối
Việc nhúng một trình xem tài liệu một cách an toàn đòi hỏi hơn việc sao chép một đoạn mã middleware vào ứng dụng ASP.NET Core. Việc tích hợp phải xác định các ranh giới rõ ràng cho xác thực, truy cập tài liệu, quản lý phiên, hiển thị, chú thích, tìm kiếm, in ấn và ghi nhật ký kiểm toán.
Các doanh nghiệp xây dựng các cổng thông tin tập trung vào tài liệu — như DMS, CRM, đánh giá pháp lý, hoặc ứng dụng bản vẽ kỹ thuật — cũng cần giữ các tệp gốc phía sau ranh giới ứng dụng. Doconut hỗ trợ mô hình xem phía máy chủ cho các tài liệu PDF, Office, CAD và hình ảnh, trong khi giao diện React có thể cung cấp giao diện người dùng.
Bài hướng dẫn này tập trung vào một kiến trúc đáng tin cậy và cố ý tránh các tên gói, thuộc tính tùy chọn, chữ ký phương thức và đường dẫn endpoint có thể thay đổi giữa các phiên bản SDK. Hãy sử dụng tài liệu chính thức phù hợp với phiên bản có giấy phép của bạn để biết chi tiết đăng ký và API chính xác.
1️⃣ Bước 1 – Chuẩn bị dự án ASP.NET Core và React
Trước khi viết bất kỳ mã nào, hãy đảm bảo môi trường phát triển của bạn đáp ứng các yêu cầu cơ bản:
| Yêu cầu | Phiên bản đề xuất |
|---|---|
| .NET runtime | .NET 6 trở lên |
| ASP.NET Core | 6.0+ |
| IDE | Môi trường phát triển .NET được hỗ trợ |
| Front‑end (optional) | Ứng dụng React tương thích với dự án của bạn |
- Tạo một dự án ASP.NET Core Web API mới
dotnet new webapi -n DocPortal
cd DocPortal
-
Thêm các phụ thuộc Doconut có giấy phép – Lấy tên gói, phiên bản, phụ thuộc gốc và hướng dẫn tải giấy phép chính xác từ tài liệu chính thức cho phiên bản Doconut của bạn. Đừng giả định rằng một gói hoặc wrapper được hiển thị trong một hướng dẫn không liên quan áp dụng cho phiên bản của bạn.
-
Chuẩn bị ứng dụng React – Nếu trình xem sẽ được trình bày qua React, hãy sử dụng cấu hình front‑end đã được đội ngũ của bạn phê duyệt. Giữ cho ứng dụng React phụ thuộc vào API đã xác thực của bạn thay vì các wrapper bên thứ ba không được tài liệu.
-
Cam kết (commit) trạng thái ban đầu – Hầu hết các đội doanh nghiệp áp dụng chính sách Git yêu cầu một commit có chữ ký cho bất kỳ thay đổi nào liên quan đến giấy phép hoặc cài đặt bảo mật.
Bây giờ bạn đã có một giải pháp sạch sàng, sẵn sàng cho việc tích hợp máy chủ Doconut được tài liệu hoá.
2️⃣ Bước 2 – Cấu hình tích hợp máy chủ một cách an toàn
Đăng ký trình xem bằng cách sử dụng hướng dẫn cung cấp cho phiên bản Doconut chính xác trong dự án của bạn. Thứ tự middleware, đăng ký dịch vụ, khởi tạo giấy phép và tên thuộc tính cấu hình là các chi tiết riêng cho từng phiên bản và không nên sao chép từ các ví dụ chưa được xác minh.
Bất kể phiên bản SDK nào, ứng dụng ASP.NET Core xung quanh nên thực thi các kiểm soát sau:
- Xác thực trước khi mở tài liệu – Phiên trình xem không bao giờ được bỏ qua lớp nhận dạng của ứng dụng.
- Giải quyết định danh tài liệu trên máy chủ – Chấp nhận ID tài liệu cấp ứng dụng, không phải đường dẫn tệp vật lý tùy ý do trình duyệt cung cấp.
- Ủy quyền cho mọi thao tác – Xem, chú thích, tìm kiếm, tải xuống và in ấn có thể yêu cầu các quyền khác nhau.
- Giữ bí mật ngoài hệ thống kiểm soát nguồn – Lưu giấy phép, chuỗi kết nối và vật liệu mã hoá trong cơ chế quản lý bí mật đã được phê duyệt.
- Áp dụng giới hạn yêu cầu – Đặt giới hạn tải lên, kích thước tài liệu, thời gian chờ và tốc độ phù hợp cho quy trình làm việc của trình xem.
- Ghi lại các sự kiện bảo mật – Ghi nhật ký quyết định truy cập và hành động tài liệu mà không ghi nội dung tài liệu hoặc token nhạy cảm vào log.
Xem tất cả cài đặt SDK như cấu hình có phiên bản. Xác nhận ý nghĩa của chúng trong tài liệu tham khảo chính thức trước khi kích hoạt trong môi trường sản xuất.
3️⃣ Bước 3 – Cô lập các phiên tài liệu phía sau một dịch vụ ứng dụng
Giữ các tương tác đặc thù Doconut trong một dịch vụ ứng dụng riêng biệt. Tham chiếu đến lớp Viewer hữu ích ở mức kiến trúc, nhưng chữ ký constructor, phương thức mở tài liệu, yêu cầu bộ nhớ đệm và hành vi khám phá giấy phép phải dựa trên tài liệu cho phiên bản đã cài đặt của bạn.
Một ranh giới dịch vụ an toàn nên:
- Nhận một người dùng đã xác thực và một định danh tài liệu cấp ứng dụng.
- Kiểm tra quyền của người dùng đối với hành động yêu cầu.
- Giải quyết tài liệu từ kho lưu trữ phía máy chủ đã được phê duyệt.
- Yêu cầu API trình xem được tài liệu để thiết lập một phiên tài liệu.
- Trả về chỉ thông tin phiên tối thiểu, không rõ ràng, mà client cần.
- Giải phóng hoặc hết hạn các phiên theo chính sách lưu trữ và bộ nhớ đệm của bạn.
Trình duyệt không bao giờ nên nhận đường dẫn lưu trữ vật lý, dữ liệu giấy phép, khóa bộ nhớ đệm nội bộ, hoặc tham chiếu không giới hạn tới tài liệu gốc.
4️⃣ Bước 4 – Kích hoạt chú thích, tìm kiếm và in ấn kiểm soát
Chú thích, tìm kiếm, OCR và in ấn kiểm soát chỉ nên được kích hoạt khi chúng được bao gồm trong cấu hình Doconut có giấy phép của bạn và được hỗ trợ bởi phiên bản đã cài đặt. Tránh giả định tên phương thức, định dạng lưu trữ hoặc lớp tùy chọn.
- Chú thích – Xác định vai trò nào có thể tạo, chỉnh sửa, xem hoặc xóa đánh dấu. Lưu trạng thái chú thích theo hướng dẫn lưu trữ cho phiên bản SDK của bạn và yêu cầu kiểm toán của riêng bạn.
- Tìm kiếm và OCR – Xác định loại tài liệu nào cần OCR, nơi lưu trữ văn bản đã trích xuất và thời gian chỉ mục còn khả dụng. Xem kết quả tìm kiếm như dữ liệu tài liệu và ủy quyền chúng một cách phù hợp.
- In ấn kiểm soát – Định nghĩa giới hạn trang, chính sách watermark, quy tắc phê duyệt và sự kiện kiểm toán ở mức ứng dụng, sau đó ánh xạ các yêu cầu đó tới khả năng in được tài liệu mô tả.
Giữ các thao tác này phía sau cùng dịch vụ ứng dụng được sử dụng cho các phiên tài liệu để các controller vẫn gọn nhẹ và các quy tắc nghiệp vụ dễ kiểm thử.
5️⃣ Bước 5 – Kết nối giao diện React
Ứng dụng React nên gọi API ASP.NET Core đã xác thực của bạn thay vì chấp nhận đường dẫn lưu trữ hoặc kết nối trực tiếp tới các dịch vụ tài liệu nội bộ. Định nghĩa hợp đồng API hướng tài nguyên của riêng bạn quanh các hành động nghiệp vụ và tránh công bố các tên endpoint đặc thù SDK như một phần của hợp đồng client công cộng.
Một chuỗi tương tác điển hình là:
- Người dùng chọn một tài liệu đã hiển thị trong ứng dụng.
- React yêu cầu một phiên xem bằng cách sử dụng ID tài liệu cấp ứng dụng.
- ASP.NET Core xác thực yêu cầu, ủy quyền tài liệu và điều phối phiên trình xem.
- React nhận chỉ thông tin cần thiết để hiển thị trình xem.
- Các yêu cầu chú thích, tìm kiếm và in ấn trả về qua API ứng dụng đã xác thực.
- Máy chủ ghi lại các sự kiện kiểm toán và hết hạn phiên khi thích hợp.
Trong UI React, giữ trạng thái phiên ngắn hạn, xử lý lỗi ủy quyền một cách rõ ràng, tránh lưu các giá trị nhạy cảm trong bộ nhớ lưu trữ trình duyệt lâu dài, và cung cấp trạng thái tải và lỗi mà không tiết lộ đường dẫn nội bộ hoặc chi tiết ngoại lệ.
Sự tách biệt này giữ việc render và điều khiển tài liệu trên máy chủ trong khi React vẫn chịu trách nhiệm về giao diện và tương tác.
Kết luận
Bằng cách đặt tích hợp Doconut phía sau một dịch vụ ứng dụng ASP.NET Core an toàn, bạn có thể xây dựng một cổng tài liệu cho quy trình PDF, Office, CAD và hình ảnh mà không gắn kết giao diện React với các chi tiết SDK chưa được tài liệu hoá. Xác thực, ủy quyền, vòng đời phiên, tìm kiếm, chú thích, in ấn và chính sách kiểm toán vẫn là các phần rõ ràng trong thiết kế ứng dụng của bạn.
Bạn đã sẵn sàng đánh giá Doconut cho dự án .NET của mình? Sử dụng gói, giấy phép và tài liệu API chính thức cho phiên bản đã chọn, sau đó áp dụng kiến trúc và danh sách kiểm tra bảo mật ở trên vào triển khai của bạn.