Posted inHomeLab

Triển khai Stirling-PDF trên Docker: Tự host bộ công cụ PDF riêng tư cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Rủi ro bảo mật tiềm ẩn từ các công cụ chuyển đổi PDF trực tuyến

Hầu hết chúng ta đều từng làm điều này: bạn cần ghép hợp đồng ký quỹ đã ký, bôi đen thông tin trên bản quét hộ chiếu, hay nén bản khai thuế dài 60 trang, thế là bạn tải chúng lên các dịch vụ miễn phí như iLovePDF hoặc SmallPDF. Vào thời điểm đó, hành động này có vẻ vô hại. Tuy nhiên, việc giao hồ sơ tài chính chưa mã hóa, hợp đồng bảo mật (NDA) của khách hàng hay giấy tờ tùy thân cho các máy chủ đám mây bên thứ ba là một canh bạc không đáng có.

Các gói miễn phí thường giới hạn dung lượng file ở mức 15 MB, bắt bạn xếp hàng chờ chuyển đổi với tốc độ bị bóp nghẹt, và thường lưu cache file trên máy chủ từ xa trong nhiều giờ. Hệ thống HomeLab của bạn có thể giải quyết triệt để vấn đề này chỉ trong năm phút. Việc dựng một công cụ xử lý tài liệu cục bộ mang lại cho gia đình bạn toàn bộ sức mạnh xử lý, không bị thu thập dữ liệu (telemetry) và làm chủ dữ liệu của mình 100%.

Tìm hiểu kiến trúc của Stirling-PDF

Stirling-PDF đóng gói các tác vụ tách, ghép, xoay, bôi đen thông tin nhạy cảm (redact), đóng dấu bản quyền (watermark) và OCR vào một bộ ứng dụng web tự host duy nhất. Thay vì phải chắp vá từng script CLI riêng lẻ, bạn sẽ có một giao diện web trực quan, gọn gàng được hỗ trợ bởi một tech stack đã qua kiểm chứng: Spring Boot, Apache PDFBox, LibreOffice và Tesseract OCR.

Các phiên bản Image: Full so với Ultra-Lite

Việc chọn container image phù hợp phụ thuộc vào phần cứng và khối lượng công việc của bạn:

  • Full (Fat) Image: Tích hợp sẵn LibreOffice, OpenCV và các gói ngôn ngữ Tesseract. Hãy chọn bản này nếu bạn cần chuyển đổi hai chiều (chẳng hạn như từ .docx hoặc .xlsx sang PDF) cùng với quét OCR đa ngôn ngữ. Bộ nhớ RAM có thể tăng vọt trong khoảng từ 2 GB đến 3.5 GB khi thực hiện các tác vụ nhận dạng ký tự quang học nặng.
  • Ultra-Lite Image: Loại bỏ LibreOffice và các engine OCR nặng nề. Nếu bạn chỉ cần các thao tác cơ bản trên trang—như ghép, tách, xoay hoặc đặt mật khẩu khóa file—phiên bản này chỉ tiêu tốn dưới 120 MB RAM khi ở chế độ chờ và đạt đỉnh dưới 300 MB. Nó hoạt động mượt mà trên Raspberry Pi 4 (2 GB) hoặc một gói VPS giá rẻ chỉ $4/tháng.

Với hầu hết các mini PC chạy x86 (như Intel N100 hoặc một node Lenovo ThinkCentre tiny đời cũ), bạn nên dùng bản full image. Nó cung cấp trọn vẹn bộ tính năng mà không cần dựng thêm các microservice sidecar bên ngoài.

Từng bước triển khai Stirling-PDF với Docker Compose

Sử dụng Docker Compose giúp quá trình triển khai có thể tái lập dễ dàng, quản lý phiên bản hiệu quả và thuận tiện di chuyển giữa các host.

1. Thiết lập thư mục dự án

Tạo một thư mục riêng để lưu trữ trạng thái ứng dụng, dữ liệu Tesseract tùy chỉnh và các quy trình tự động hóa:

mkdir -p ~/homelab/stirling-pdf/{trainingData,extraConfigs,logs,pipeline}
cd ~/homelab/stirling-pdf

2. Tạo file Docker Compose

Soạn thảo file docker-compose.yml của bạn:

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./trainingData:/usr/share/tessdata:rw
      - ./extraConfigs:/configs:rw
      - ./logs:/logs:rw
      - ./pipeline:/pipeline:rw
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false
      - LANGS=en_GB,en_US,de_DE,fr_FR
      - SYSTEM_DEFAULTLOCALE=en_US
      - UI_APPNAME=HomeLab PDF Suite
    deploy:
      resources:
        limits:
          memory: 4G

Các điểm cấu hình quan trọng cần lưu ý:

  • ./trainingData: Mount các model .traineddata tùy chỉnh vào Tesseract. Dùng mục này nếu bạn cần xử lý các bảng chữ cái không phải Latin hoặc các font chữ đặc thù.
  • DOCKER_ENABLE_SECURITY: Mở quyền truy cập dashboard tự do trong mạng LAN khi đặt là false. Hãy chuyển thành true nếu bạn publish instance này ra ngoài Internet hoặc dùng chung mạng gia đình với khách.
  • LANGS: Định nghĩa các từ điển OCR được tải về trong lần khởi tạo đầu tiên. Hãy rút gọn danh sách này chỉ gồm các ngôn ngữ bạn thực sự sử dụng để tăng tốc quá trình build container ban đầu.
  • memory: 4G: Việc chuyển đổi một tài liệu scan dài 300 trang có thể khiến mức sử dụng RAM tăng vọt trong chốc lát. Đặt một giới hạn cứng rõ ràng sẽ giúp Java không chiếm dụng tài nguyên của các container Docker lân cận.

3. Khởi chạy và kiểm tra Container

Khởi chạy container ở chế độ chạy ngầm (detached mode):

docker compose up -d

Theo dõi log của container để xem Java runtime và các dependency được kích hoạt:

docker compose logs -f stirling-pdf

Khi bạn nhìn thấy banner Spring Boot và thông báo khởi tạo thành công trên terminal, hãy mở trình duyệt và truy cập vào http://<your-server-ip>:8080. Giao diện được phân loại các công cụ rất rõ ràng theo từng tab: Merge & Split (Ghép & Tách), Convert (Chuyển đổi), Security (Bảo mật) và Page Ops (Thao tác trang).

4. Tăng cường bảo mật và tài khoản người dùng cho môi trường Production

Nếu bạn định tuyến traffic qua một reverse proxy bên ngoài như Caddy, Traefik hoặc Cloudflare Tunnels, việc siết chặt quyền truy cập là bắt buộc. Hãy cập nhật các biến môi trường trong file Compose:

    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - SECURITY_CSRFDISABLED=false

Khởi động lại container. Thông tin đăng nhập quản trị mặc định là:

  • Username: admin
  • Password: stirling

Hãy đổi mật khẩu này ngay lập tức trong mục Account Settings (Cài đặt tài khoản). Tại đây, bạn cũng có thể phân quyền tài khoản theo vai trò (RBAC) hoặc tạo API token phục vụ các script CLI tự động hóa.

Trong môi trường lab của chúng tôi, một máy ảo 4 core với 4 GB RAM được gán có thể xử lý trơn tru các bản vẽ kiến trúc 250 MB và sao kê ngân hàng 400 trang mà không hề bị tràn bộ nhớ hay khóa luồng (thread lock).

5. Thiết lập quy trình tự động hóa với Watched Folder (Pipeline)

Mount ./pipeline mở khóa khả năng xử lý hàng loạt tự động. Bạn chỉ cần trỏ máy scan hoặc thư mục mạng vào một thư mục con được giám sát chỉ định. Stirling-PDF sẽ tự động nhận diện file mới, tự nắn thẳng các trang bị nghiêng, chạy OCR, nén giảm dung lượng và lưu trữ các file chuẩn PDF/A sạch đẹp trực tiếp vào thư mục lưu trữ trên NAS của bạn.

Lời kết và các bước tiếp theo

Thay thế các tiện ích SaaS bằng các giải pháp tự host là một nước đi rất đáng giá cho bất kỳ home server nào. Stirling-PDF đánh đổi các trình theo dõi độc quyền cùng phí thuê bao định kỳ để mang lại cho bạn một trạm làm việc xử lý tài liệu tốc độ cao và hoàn toàn độc lập.

Để hệ thống vận hành ổn định lâu dài, hãy đặt service phía sau một reverse proxy hỗ trợ SSL, thiết lập cơ chế tự động gia hạn chứng chỉ qua Let’s Encrypt và sao lưu thư mục extraConfigs song song với lịch trình snapshot định kỳ bằng Borg hoặc Restic.

Share:
Tags: