Vì sao nên self-host bộ công cụ PDF thay vì dùng thêm một converter web miễn phí

Converter PDF thuần trình duyệt tối ưu cho tải lên, bấm nút, tải về. Quảng cáo thường nuôi trang, và ngoài chiếc form gần như không có bề mặt lập trình ổn định. Hình dạng đó đúng cho một việc làm một lần của con người. Nó sai khi bạn cần tự động hóa, một chính sách lưu giữ, hoặc tệp buộc phải nằm trong mạng của bạn.

Converter trình duyệt tối ưu cho điều gì

Converter công khai bán sự tiện lợi: mở tab, thả tệp, nhận kết quả, rời đi. Giao diện chính là sản phẩm. Script thì hoặc cạo HTML, hoặc đánh vào những điểm cuối không tài liệu và đổi lúc nào không báo. Việc lưu giữ tùy thuộc ai vận hành kho tạm. Với một lần ghép hai PDF cá nhân, đánh đổi đó chấp nhận được.

Ngay khi cần cùng tác vụ đó từ CI, một agent, hay một mạng tách biệt, những mảnh còn thiếu lộ ra cùng lúc: xác thực, OpenAPI, thử lại idempotent, và một danh mục không âm thầm lệch khỏi chiếc form bạn bấm tuần trước.

Chạy danh mục này trên máy bạn thì được gì

Site hosted và một instance self-host dùng chung các thao tác. Compress và Merge là cùng một thao tác dù yêu cầu đến từ portal hay từ POST /api/v1/…. Self-host thêm quyền kiểm soát quanh danh mục chung đó:

• REST + OpenAPI tại /v1/openapi.json: mọi công cụ trong danh mục là điểm cuối ổn định, không chỉ một form.
• MCP tại /mcp: agent khám phá và gọi đúng các thao tác đó mà không phải tự viết scraper.
• CLI (pdfx): chạy pdf-core cục bộ, hoặc --cloud trỏ tới base URL kèm API key của bạn.
• Không có client desktop: Docker Compose là câu chuyện offline; plugin và bộ cài Windows bị loại ngoài phạm vi có chủ ý.
• Quảng cáo không nằm trong hệ thống của bạn: AdSense trên site công khai không thuộc bản self-host; tệp tải lên không rời máy bạn.

Compose dựng Rust pdfx-server và portal Next.js cùng nhau để người lẫn script dùng chung một danh mục. Chế độ dev native (task pdfx:dev cộng portal) đi qua cùng đường thao tác. Chi tiết ở Self-host.

OCR trên cả hai cách triển khai vẫn trả Markdown (text/markdown) từ /api/v1/misc/ocr-pdf, không phải một PDF tìm kiếm được gắn lại lớp chữ. Chuyển server chỉ đổi nơi byte hạ cánh, không tạo ra hợp đồng thao tác khác.

Những gì chúng tôi cố ý không sao chép

Các canvas “Edit PDF” online, so sánh trực quan, Create PDF trống, và giao diện Sign cho người dùng phổ thông đòi hỏi hướng sản phẩm khác. Chúng tôi giữ ma trận công cụ dạng form cùng API. Self-host không mở ra cây giao diện thứ hai; nó chuyển chính cây đó ra sau tường lửa.

Bỏ qua các bề mặt tiêu dùng đó là có chủ ý. Một trình soạn canvas sẽ là codebase thứ hai, với độ trễ tính năng riêng so với OpenAPI. Ràng buộc quan trọng cho dùng riêng là “byte ở lại đây”, không phải “có một tệp .exe”. Về lý do không có bản desktop, xem Vì sao chúng tôi bỏ qua ứng dụng desktop.

Khi nào bản hosted là đủ, khi nào không

Dùng site công khai khi muốn không cài đặt gì và chỉ làm một lần ẩn danh. Công cụ trong danh mục và các lệnh gọi /api/v1/ ẩn danh không cần tài khoản; phản hồi hosted công bố tiêu đề hạn mức, và các trần tồn tại để bề mặt miễn phí không thành nông trại batch của người khác (giới hạn tần suất ẩn danh).

Hãy self-host khi quy định lưu giữ, mạng riêng hoặc tự động hóa riêng buộc phải vậy. Khi đó bạn tự lo uptime, nâng cấp image, đĩa cho tệp tạm, TLS, và xoay key (SECURITY_CUSTOMGLOBALAPIKEY cho một cổng cố định trên máy bạn). Các thao tác vẫn giữ nguyên; nơi byte hạ cánh mới đổi.

Dùng thử

Bắt đầu từ Self-host và Nhà phát triển. Về bề mặt API hướng agent trên bất kỳ base URL nào, đọc Xây cho AI agent, không chỉ trình duyệt. Muốn phân tích chi phí/lợi ích dài hơn, xem Self-host thực sự mang lại gì.