Hướng dẫn cài đặt Stirling PDF với Docker từng bước một

Cập nhật lần cuối: 28/08/2026
Tác giả: Alberto Navarro

  • Stirling PDF là một công cụ miễn phí, chạy cục bộ, cho phép bạn thực hiện hơn 50 thao tác với các tệp PDF mà không cần phụ thuộc vào điện toán đám mây.
  • Việc cài đặt được thực hiện bằng cách sử dụng các container Docker và tương thích với Raspberry Pi, Synology NAS, và nhiều bản phân phối Linux khác nhau.
  • Nó cho phép bạn cấu hình các biến môi trường để tùy chỉnh ngôn ngữ, bảo mật thông qua đăng nhập và khả năng lưu trữ dữ liệu cho OCR.

Việc cài đặt Stirling PDF bằng Docker cho phép bạn biến ứng dụng này thành một... Máy chủ riêng để quản lý tài liệu PDFSau khi triển khai, bạn có thể truy cập nó từ bất kỳ máy tính, điện thoại di động hoặc máy tính bảng nào trên mạng bằng trình duyệt web, mà không cần cài đặt chương trình trên từng thiết bị.

Các tệp được gửi đến máy chủ do bạn cấu hình, chứ không phải đến máy chủ của Stirling PDF. Điều này giúp bạn kiểm soát tài liệu của mình tốt hơn, mặc dù quyền riêng tư tối thượng vẫn phụ thuộc vào bạn. Máy chủ được đặt ở đâu, ai có thể truy cập vào nó và kết nối được bảo vệ như thế nào..

Nếu bạn chỉ định sử dụng công cụ này trên một máy tính duy nhất, ứng dụng gốc có thể đơn giản hơn. Trong trường hợp đó, hãy xem cách thực hiện. Cài đặt Stirling PDF trên Windows mà không cần cấu hình Docker hoặc công bố dịch vụ mạng.

Bạn nên chọn hình ảnh PDF nào của Stirling?

Bạn nên chọn hình ảnh PDF nào của Stirling?

Stirling PDF phát hành ba phiên bản khác nhau của hình ảnh. Sự lựa chọn này ảnh hưởng đến các chức năng có sẵn, không gian chiếm dụng và tài nguyên cần thiết.

Phiên bản Nhãn Hướng dẫn sử dụng
Tiêu chuẩn latest Hầu hết người dùng gia đình và máy chủ
Mập latest-fat Khả năng tương thích tối đa, phông chữ và công cụ bổ sung
Siêu nhẹ latest-ultra-lite Raspberry Pi, máy chủ ảo VPS nhỏ và các thao tác cơ bản

Hình ảnh latest Đây là lựa chọn được khuyến nghị khi bạn không có yêu cầu đặc biệt nào. Nó bao gồm các tính năng quản lý, chuyển đổi, nhận dạng ký tự quang học (OCR) và bảo mật thông thường trong khi vẫn giữ kích thước hợp lý.

Biến thể latest-fat Nó bao gồm nhiều phông chữ và công cụ tùy chọn hơn, có thể cải thiện khả năng tương thích cho một số chuyển đổi nhất định. Đổi lại, nó yêu cầu nhiều dung lượng lưu trữ hơn.

latest-ultra-lite Nó giúp giảm kích thước và mức tiêu thụ điện năng cho các thiết bị có cấu hình hạn chế, nhưng lại lược bỏ một số tính năng. Nó phù hợp để hợp nhất, chia tách, xoay hoặc sắp xếp lại tài liệu trên các máy tính cấu hình thấp.

Sau khi máy chủ được cài đặt, bạn sẽ có thể Ghép nhiều tệp PDF với Stirling PDF, xóa trang, sắp xếp lại tài liệu hoặc Chuyển đổi nhiều hình ảnh thành một tệp PDF duy nhất..

Các yêu cầu để cài đặt Stirling PDF với Docker

Để triển khai cơ bản, bạn cần:

  • Docker Engine phiên bản 20.10 trở lên.
  • Docker Compose đã được cài đặt.
  • RAM tối thiểu 2 GB.
  • Cần ít nhất 5 GB dung lượng lưu trữ cho bài kiểm tra cơ bản.
  • Thư mục dùng để lưu trữ các cài đặt cố định.
  • Truy cập vào thiết bị đầu cuối hoặc giao diện tương thích với Compose.

Đối với máy chủ được sử dụng thường xuyên, các khuyến nghị sau đây được đưa ra: 2 lõi CPU, 4 GB RAM và 10 GB dung lượng trống.Việc chuyển đổi định dạng, hiển thị và nhận dạng ký tự quang học (OCR) có thể yêu cầu dung lượng bộ nhớ lớn gấp nhiều lần kích thước tài liệu gốc.

Kiểm tra cài đặt:

docker --version
docker compose version

Trong các hệ thống hiện tại, việc sử dụng là phương pháp được ưu tiên hơn. docker composecó dấu cách. Một số giao diện và phiên bản cũ hơn vẫn tiếp tục hiển thị docker-composeTuy nhiên, cả hai lệnh không phải lúc nào cũng khả dụng cùng lúc.

Cài đặt nhanh bằng Docker Run

Để thử Stirling PDF mà chưa tạo tệp Compose, hãy chạy lệnh sau:

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data:/configs \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

Sau đó mở:

http://localhost:8080

Nếu Docker đang chạy trên một máy khác, hãy thay thế localhost theo địa chỉ IP của họ:

http://192.168.1.50:8080

Khối lượng ./stirling-data:/configs Nó giữ nguyên các cài đặt và cơ sở dữ liệu khi vùng chứa bị xóa hoặc cập nhật.

Phương pháp này phù hợp cho việc kiểm tra nhanh. Đối với cài đặt lâu dài, Docker Compose thuận tiện hơn vì nó ghi lại các cổng, volume, biến và chính sách khởi động lại.

Nội dung độc quyền - Bấm vào đây  Các ứng dụng được phát triển bằng ứng dụng Swift Playgrounds như thế nào?

Cách chuẩn bị thư mục lưu trữ lâu dài

Tạo một thư mục cho dự án và một vài thư mục lưu trữ cố định:

mkdir -p ~/stirling-pdf/stirling-data/{configs,logs,pipeline,tessdata}
cd ~/stirling-pdf

Mỗi thư mục có một chức năng khác nhau:

  • configs: cài đặt và cơ sở dữ liệu nội bộ.
  • logs: nhật ký hoạt động và lỗi.
  • pipelineCác cấu hình cho quá trình xử lý tự động.
  • tessdataCác mô hình ngôn ngữ được Tesseract sử dụng.

Bạn cũng có thể tạo một ổ đĩa cho /customFiles Nếu bạn cần phông chữ, giao diện, chữ ký hoặc các tệp tùy chỉnh khác.

Không cần cấu hình gì cả. PUID y PGID trong tất cả các cài đặt. Một số mẫu cộng đồng dành cho NAS hoặc Unraid sử dụng các biến này, nhưng cấu hình chính thức cơ bản dựa trên quyền truy cập của các thư mục được gắn kết.

Hướng dẫn cài đặt Stirling PDF bằng Docker Compose

Hướng dẫn cài đặt Stirling PDF bằng Docker Compose

Ở trong ~/stirling-pdf, tạo ra một tệp có tên là docker-compose.yml Với nội dung này:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/tessdata:/usr/share/tessdata
    environment:
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "admin"
      SECURITY_INITIALLOGIN_PASSWORD: "${STIRLING_ADMIN_PASSWORD}"
      SYSTEM_DEFAULTLOCALE: "es-ES"
    restart: unless-stopped

Nó cũng tạo ra một tệp .env trong cùng thư mục:

STIRLING_ADMIN_PASSWORD=INTRODUCE_UNA_CONTRASEÑA_SEGURA

Hãy bảo vệ tập tin sao cho chỉ người dùng của bạn mới có thể đọc được:

chmod 600 .env

Sau đó, dịch vụ bắt đầu:

docker compose up -d

Kiểm tra trạng thái của nó:

docker compose ps

Container sẽ hiển thị trạng thái đã khởi động. Trong lần khởi động đầu tiên, có thể mất vài giây để chuẩn bị cơ sở dữ liệu và các thành phần nội bộ.

Cách bảo vệ và quản lý các tệp PDF được bảo vệ bằng mật khẩu bằng Stirling PDF
Bài viết liên quan:
Cách bảo vệ và quản lý các tệp PDF được bảo vệ bằng mật khẩu bằng Stirling PDF

Hướng dẫn cấu hình ngôn ngữ và xác thực

Các ảnh Docker hiện tại có Đăng nhập được bật theo mặc địnhNếu bạn không thiết lập thông tin đăng nhập ban đầu, một tài khoản sẽ được tạo với:

  • Người dùng: admin
  • Mật khẩu: stirling

Bạn phải thay đổi mật khẩu này ngay lập tức. Cấu hình trước đó ngăn cản việc sử dụng mật khẩu này bằng cách yêu cầu bạn phải tự đặt mật khẩu từ lần triển khai đầu tiên.

Các biến số SECURITY_INITIALLOGIN_USERNAME y SECURITY_INITIALLOGIN_PASSWORD Những mật khẩu này được sử dụng khi tạo tài khoản ban đầu. Chúng không thể được sử dụng để thay đổi mật khẩu của người dùng hiện có sau này; việc thay đổi đó phải được thực hiện từ giao diện.

Nếu máy chủ hoàn toàn biệt lập và bạn muốn sử dụng nó mà không cần xác thực, bạn có thể chỉ định:

SECURITY_ENABLELOGIN: "false"

Không nên tắt xác thực nếu người dùng khác có thể truy cập cổng, nếu bạn đang sử dụng mạng dùng chung hoặc nếu bạn định công bố dịch vụ trên Internet.

Để sử dụng tiếng Tây Ban Nha làm ngôn ngữ mặc định, biến hiện tại là:

SYSTEM_DEFAULTLOCALE: "es-ES"

Nếu không được thiết lập, Stirling PDF sẽ cố gắng tự động phát hiện ngôn ngữ trình duyệt. Để giới hạn các ngôn ngữ có sẵn trong bộ chọn, bạn có thể sử dụng... UI_LANGUAGES, trong đó mã sử dụng dấu gạch dưới:

UI_LANGUAGES: "es_ES,en_US"

Cách thêm tính năng nhận dạng ký tự quang học (OCR) vào tiếng Tây Ban Nha

Stirling PDF sử dụng Tesseract để nhận dạng văn bản trong các tài liệu được quét. OCR trích xuất văn bản, nhưng... Nó không tự động xây dựng lại các bảng, công thức hoặc cấu trúc phức tạp..

Để nhận diện tài liệu bằng tiếng Tây Ban Nha, hãy tải xuống tệp. spa.traineddata Tải xuống từ kho lưu trữ chính thức của Tesseract và lưu vào:

~/stirling-pdf/stirling-data/tessdata

Thư mục này được kết nối với /usr/share/tessdata bên trong container bằng cách sử dụng tệp Compose.

Không xóa eng.traineddataStirling PDF cần giữ nguyên mẫu tiếng Anh ngay cả khi bạn thêm các ngôn ngữ khác.

Bạn có thể lựa chọn giữa:

  • tessdata_fast: Các tập tin nhỏ hơn, nhanh hơn, nhưng độ chính xác có thể thấp hơn.
  • tessdata: Các mẫu máy nặng hơn có thể cho kết quả tốt hơn.

Sau khi thêm tệp, hãy khởi động lại container:

docker compose restart stirling-pdf

OCR cho phép bạn chuyển đổi bản quét thành tệp PDF có thể tìm kiếm. Nếu sau này bạn cần chỉnh sửa nội dung, bạn có thể Chuyển đổi PDF sang Word bằng Stirling PDFCần lưu ý rằng độ chính xác sẽ phụ thuộc vào thiết kế gốc.

Cách truy cập từ các thiết bị khác trên mạng

Cách truy cập từ các thiết bị khác trên mạng

Tìm địa chỉ IP của máy đang chạy Docker và mở nó từ một thiết bị khác:

http://DIRECCION_IP:8080

Ví dụ:

http://192.168.1.50:8080

Nếu trang không tải được, hãy kiểm tra xem tường lửa có cho phép kết nối TCP đến cổng 8080 từ mạng cục bộ hay không.

Nội dung độc quyền - Bấm vào đây  Làm thế nào để sử dụng PyCharm để tạo ứng dụng cho điện thoại di động?

Bạn không cần phải quảng cáo cổng trên bộ định tuyến để sử dụng nó trong mạng gia đình hoặc văn phòng. Việc giới hạn nó trong mạng LAN sẽ giảm thiểu nguy cơ bị tấn công.

Từ giao diện, bạn có thể thực hiện các thao tác như sau: xóa các trang trống và chỉnh sửa tài liệu, thêm chú thích hoặc Thêm hình mờ vào tệp PDF.

Cách truy cập từ xa và an toàn

Không nên trực tiếp mở cổng 8080 ra internet bằng cách sử dụng tính năng chuyển tiếp cổng của bộ định tuyến. Kết nối sẽ sử dụng giao thức HTTP và có thể bị các phần mềm theo dõi hoặc kẻ tấn công truy cập.

Các phương án thay thế an toàn nhất là:

  • Truy cập thông qua VPN riêng tư Ví dụ như WireGuard hoặc Tailscale.
  • Hãy sử dụng máy chủ proxy ngược có tên miền và chứng chỉ HTTPS.
  • Cấu hình đường hầm xác thực dưới dạng Đường hầm Cloudflare.

Nginx, Caddy hoặc Traefik có thể hoạt động như một máy chủ proxy ngược và gửi các yêu cầu HTTPS đến container bằng cách sử dụng http://localhost:8080Chứng chỉ có thể được quản lý bởi Let's Encrypt hoặc bởi nhà cung cấp tên miền.

Chức năng xác thực PDF của Stirling phải luôn được bật ngay cả khi máy chủ proxy đã bảo vệ kết nối. Mã hóa HTTPS bảo mật quá trình truyền tải, trong khi thông tin đăng nhập kiểm soát ai có thể sử dụng ứng dụng.

Hướng dẫn cài đặt Stirling PDF trên Raspberry Pi hoặc NAS

Trên một chiếc Raspberry Pi có tài nguyên hạn chế, bạn có thể thay đổi hình ảnh thành:

docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest-ultra-lite

Các thao tác đơn giản sẽ hoạt động chính xác, nhưng nhận dạng ký tự quang học (OCR), chuyển đổi tài liệu Office và xử lý tài liệu dung lượng lớn có thể chậm hoặc vượt quá dung lượng bộ nhớ hiện có.

Trên Synology, QNAP và các thiết bị NAS tương thích khác, bạn có thể triển khai cùng một tệp bằng Docker Compose, Container Manager hoặc Portainer. Trong Portainer, hãy mở tệp đó. Ngăn xếp > Thêm ngăn xếpSao chép cấu hình và điều chỉnh đường dẫn để trỏ đến các thư mục chia sẻ cố định.

Kiểm tra quyền ghi trên configs, logs, pipeline y tessdataSử dụng PUID y PGID Chỉ khi mẫu NAS cụ thể cho phép điều đó.

Cách điều chỉnh hiệu suất

Việc lắp đặt thiết bị quy mô nhỏ có thể bắt đầu bằng... 2 nhân xử lý, 4 GB RAM và 10 GB dung lượng trống.Các tài liệu có nhiều trang, chứa phông chữ nhúng hoặc đồ họa vector có thể tăng kích thước đáng kể trong quá trình xử lý.

Các hoạt động đòi hỏi nhiều nỗ lực nhất thường là:

  • Nhận dạng ký tự quang học (OCR) bằng Tesseract hoặc OCRmyPDF.
  • Chuyển đổi tài liệu bằng LibreOffice.
  • Chuyển đổi PDF sang hình ảnh.
  • Nén và sửa chữa các tập tin dung lượng lớn.

Không nên tăng giới hạn cho các tiến trình đồng thời mà không giám sát bộ nhớ. Trên các máy chủ có cấu hình khiêm tốn, tốt hơn hết là xử lý tài liệu trong hàng đợi thay vì gây ra lỗi do thiếu RAM.

Nếu máy chủ phục vụ nhiều người dùng, hãy kiểm tra mức sử dụng bằng cách sử dụng:

docker stats stirling-pdf

Cách cập nhật Stirling PDF mà không làm mất dữ liệu

Trước khi cập nhật, hãy tạo bản sao của các thư mục lưu trữ dữ liệu, tệp Compose và tệp tin đó. .env:

tar -czf stirling-backup.tar.gz \
  stirling-data docker-compose.yml .env

Lưu bản sao vào thiết bị hoặc hệ thống lưu trữ khác. Tệp tin .env Tệp này chứa mật khẩu ban đầu và phải được bảo vệ.

Sau đó cập nhật hình ảnh:

docker compose down
docker compose pull
docker compose up -d

Dữ liệu vẫn còn trong các thư mục đã được gắn kết. Trên máy chủ quan trọng, nên thay thế chúng. latest bằng cách sử dụng một phiên bản cụ thể để kiểm soát thời điểm áp dụng các thay đổi.

Những lỗi thường gặp khi cài đặt Stirling PDF với Docker

Những lỗi thường gặp khi cài đặt Stirling PDF với Docker

Docker không thể tìm thấy ảnh frooodle/s-pdf.

Các hướng dẫn cũ đã sử dụng frooodle/s-pdfHãy thay thế đoạn tham chiếu đó bằng:

docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

Nếu máy chủ đăng ký chính không phản hồi, bạn cũng có thể sử dụng:

ghcr.io/stirling-tools/stirling-pdf:latest

Cảng 8080 đã có người sử dụng.

Chỉ cần thay đổi cổng trên máy chủ:

ports:
  - "9000:8080"

Sau đó truy cập qua http://localhost:9000.

Container liên tục khởi động lại.

Kiểm tra hồ sơ:

docker logs stirling-pdf

Kiểm tra dung lượng trống, bộ nhớ và quyền ghi trên các phân vùng. Trên các hệ thống có tài nguyên hạn chế, hãy kiểm tra ảnh đĩa. latest-ultra-lite.

Các thiết lập sẽ biến mất sau khi cập nhật.

Khối lượng /configs Nó chưa được gắn kết đúng cách hoặc nó trỏ đến một thư mục khác. Hãy kiểm tra đường dẫn bên trong. docker-compose.yml và người dùng vùng chứa có thể ghi vào đó.

Nội dung độc quyền - Bấm vào đây  Apple dựa vào trí tuệ nhân tạo để tăng thời lượng pin trên iPhone với iOS 19.

Giao diện này hiện không có sẵn bằng tiếng Tây Ban Nha.

Sử dụng SYSTEM_DEFAULTLOCALE=es-ESBiến số cũ LANGS=es_ES Nó không thiết lập ngôn ngữ mặc định trong cấu hình hiện tại.

OCR không hiển thị tiếng Tây Ban Nha

Kiểm tra điều đó spa.traineddata tồn tại bên trong thư mục đã được gắn kết và ổ đĩa đó trỏ đến /usr/share/tessdataNó cũng bảo tồn eng.traineddata.

Tôi không thể đăng nhập

Trên một bản cài đặt mới không có thông tin đăng nhập tùy chỉnh, hãy kiểm tra admin y stirling và lập tức thay đổi mật khẩu. Nếu cơ sở dữ liệu đã tồn tại, các biến khởi động ban đầu sẽ không thay thế thông tin đăng nhập đã lưu.

Quyền truy cập bị từ chối khi sử dụng ổ đĩa.

Hãy tạo các thư mục trước khi khởi động container và kiểm tra chủ sở hữu cũng như quyền truy cập của chúng. Không nên áp dụng quyền ghi toàn cục một cách bừa bãi hoặc cấu hình quyền đó. 777 như một giải pháp lâu dài.

Ứng dụng hoạt động trên máy tính cục bộ, nhưng không hoạt động khi truy cập từ máy tính khác.

Hãy kiểm tra xem bạn có đang sử dụng địa chỉ IP của máy chủ không, cổng có được mở không và tường lửa có cho phép kết nối từ mạng cục bộ không. localhost Nó luôn đề cập đến thiết bị mà bạn dùng để mở trình duyệt.

Máy chủ hết bộ nhớ khi xử lý các tập tin lớn.

Giảm số lượng thao tác đồng thời; sử dụng phiên bản Ultra-Lite nếu bạn không cần các công cụ nâng cao, hoặc tăng dung lượng RAM. Quá trình nhận dạng ký tự quang học (OCR) và xử lý hình ảnh có thể tiêu tốn dung lượng gấp nhiều lần kích thước tệp gốc.

Việc cài đặt Stirling PDF bằng Docker cho phép bạn cung cấp một nền tảng quản lý tài liệu tập trung cho tất cả các thiết bị trên mạng. Hình ảnh tiêu chuẩn phù hợp với hầu hết người dùng, trong khi các phiên bản Fat và Ultra-Lite cho phép bạn ưu tiên khả năng tương thích hoặc giảm mức tiêu thụ tài nguyên.

Phần quan trọng nhất là gắn kết các ổ đĩa đúng cách, duy trì xác thực, cấu hình OCR chỉ khi cần thiết và bảo vệ mọi truy cập từ xa bằng VPN hoặc HTTPS. Bạn cũng nên sao lưu dữ liệu của mình. /configs trước khi cập nhật, vì nó chứa các thiết lập cài đặt và cơ sở dữ liệu.

Alberto Navarro

Alberto Navarro

Tôi là một người đam mê công nghệ và đã biến sở thích "mọt sách" của mình thành nghề nghiệp. Tôi đã dành hơn 10 năm sử dụng các công nghệ tiên tiến và mày mò với đủ loại chương trình chỉ vì tò mò. Hiện tại, tôi chuyên về công nghệ máy tính và trò chơi điện tử. Hơn 5 năm nay, tôi đã viết bài cho nhiều trang web về công nghệ và trò chơi điện tử, tạo ra các bài viết nhằm cung cấp cho bạn những thông tin cần thiết bằng ngôn ngữ dễ hiểu đối với mọi người.

Nếu bạn có bất kỳ câu hỏi nào, kiến ​​thức của tôi bao gồm mọi thứ liên quan đến hệ điều hành Windows cũng như Android dành cho điện thoại di động. Và cam kết của tôi là với bạn, tôi luôn sẵn sàng dành một vài phút và giúp bạn giải quyết mọi thắc mắc mà bạn có thể có trong thế giới internet này.