Paperless-ngx: số hóa và tìm lại giấy tờ trong vài giây — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về paperless-ngx/paperless-ngx — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Paperless-ngx: số hoá, tìm kiếm và lưu trữ giấy tờ — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Paperless-ngx là hệ thống quản lý tài liệu mã nguồn mở, biến giấy tờ vật lý thành kho lưu trữ trực tuyến có thể tìm kiếm. Bạn tự chạy nó trên máy của mình, không phụ thuộc dịch vụ đám mây. Cách cài dễ nhất là docker compose, có sẵn một script cài đặt chạy bằng một lệnh.
Paperless-ngx là một hệ thống quản lý tài liệu (DMS) mã nguồn mở. Nó biến giấy tờ vật lý thành một kho lưu trữ trực tuyến mà bạn tìm kiếm được, để bạn giữ ít giấy hơn. Đúng như tên gọi: less paper.
Nếu bạn có một tủ hồ sơ đầy hóa đơn, hợp đồng, giấy tờ thuế, hoặc một thư mục PDF đặt tên lộn xộn, repo này dành cho bạn. Chủ shop nhỏ, nhân viên kế toán, người làm giấy tờ gia đình, hay lập trình viên muốn tự dựng kho tài liệu riêng đều dùng được. Dự án hiện có khoảng 48.000 sao và 3.300 fork trên GitHub, nên cộng đồng đủ lớn để bạn tìm được câu trả lời khi gặp vướng.
Điểm đáng giá nhất: bạn tự chạy nó trên máy của mình và giữ toàn quyền với dữ liệu. Paperless-ngx là bản kế nhiệm chính thức của hai dự án Paperless và Paperless-ng, và được cộng đồng duy trì. Xem video ngắn bên dưới để thấy nó hoạt động, rồi quay lại làm theo các bước.
paperless-ngx/paperless-ngx
Hệ thống quản lý tài liệu mã nguồn mở: quét, đánh chỉ mục và lưu trữ giấy tờ thành kho lưu trữ tìm kiếm được, chạy trên máy chủ của chính bạn.
I.Paperless-ngx làm được gì
README không liệt kê hết tính năng mà dẫn sang trang tài liệu chính thức. Dưới đây là những gì rút ra được từ README và thông tin repo. Danh sách đầy đủ và ảnh chụp màn hình bạn xem ở trang docs của dự án.
- Số hóa giấy tờ thành kho lưu trữ tìm kiếm được. Thay vì lục tủ hồ sơ, bạn gõ từ khóa và tìm ra tài liệu. Repo gắn các chủ đề OCR (nhận dạng chữ trong ảnh) và PDF, nên nội dung các bản scan được đọc ra để tìm kiếm.
- Quét, đánh chỉ mục và lưu trữ. Mô tả của tác giả nói rõ ba việc này: scan, index, archive. Bạn chỉ cần đưa tài liệu vào, phần còn lại hệ thống lo.
- Giao diện web. Repo có thư mục
src-ui(viết bằng Angular) và phần máy chủ viết bằng Django (Python). Bạn dùng qua trình duyệt, không phải gõ lệnh hằng ngày. - Nhiều ngôn ngữ giao diện. Bản dịch được điều phối trên Crowdin, nên có nhiều ngôn ngữ để chọn.
- Có bản demo để thử. Bạn xem trước giao diện mà chưa phải cài gì (hướng dẫn ở phần dưới).
- Chuyển từ Paperless-ng dễ dàng. README cho biết chỉ cần thay bằng docker image mới. Chi tiết nằm ở mục di chuyển (migrating) trong tài liệu.
Trang chủ của repo còn gắn các chủ đề ai, llm và machine-learning. README không giải thích cụ thể các tính năng này, nên bạn cần đọc docs nếu muốn dùng.
II.Cần chuẩn bị gì
Theo README, cách triển khai dễ nhất là docker compose. Vì vậy bạn cần:
- Một máy chủ hoặc máy tính để chạy Paperless-ngx, cài sẵn Docker và docker compose. README không ghi phiên bản cụ thể, bạn xem mục cài đặt trong docs.
- Một cửa sổ terminal. Script cài đặt là lệnh bash, nên trên Windows bạn cần môi trường có bash (ví dụ WSL hoặc Git Bash). README không nói rõ về Windows, mục Hỏi đáp bên dưới có nói thêm.
- Chút thời gian đọc phần cảnh báo bảo mật ở cuối bài.
README không nhắc đến tài khoản trả phí, API key hay card đồ họa (GPU). Nếu bạn cài thủ công không dùng Docker, tệp pyproject.toml yêu cầu Python từ 3.11 trở lên. Nhưng README khuyên dùng docker compose, và đó cũng là cách mình hướng dẫn dưới đây.
README cảnh báo rõ: tài liệu được lưu ở dạng văn bản thường, không mã hóa. Đừng chạy Paperless-ngx trên máy chủ bạn không tin tưởng. Cách an toàn nhất là chạy trên một máy chủ cục bộ tại nhà và có sao lưu.
III.Cài đặt từng bước
Cách nhanh nhất là dùng script cài đặt của dự án. Nó cấu hình sẵn môi trường docker compose cho bạn.
- Kiểm tra DockerChắc chắn máy đã có Docker và docker compose
- Mở terminalDùng terminal có bash
- Chạy script cài đặtDán một lệnh để cấu hình docker compose
- Làm theo hướng dẫnĐọc docs nếu cần cách cài khác
- Sao lưuChuẩn bị bản sao lưu cho dữ liệu
A.Kiểm tra Docker
README không đưa lệnh kiểm tra, nên bạn tự đảm bảo Docker và docker compose đã được cài trên máy. Nếu chưa, hãy cài trước rồi mới tiếp tục. Đây là chỗ người mới hay quên: script chỉ cấu hình môi trường chứ không cài Docker thay bạn (README không nói script làm việc này).
B.Mở terminal đúng chỗ
Mở terminal trên máy sẽ chạy Paperless-ngx. Trên Linux hoặc macOS, mở ứng dụng Terminal là đủ. Trên Windows, dùng WSL hoặc Git Bash vì lệnh bên dưới là lệnh bash.
C.Chạy script cài đặt
Dán đúng lệnh sau, lấy từ README:
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"Lệnh này dùng curl tải script install-paperless-ngx.sh từ repo, rồi đưa cho bash chạy. Script sẽ cấu hình một môi trường docker compose cho bạn. Hãy đọc kỹ các câu hỏi hiện ra trong terminal và trả lời theo nhu cầu của mình.
Nếu bạn thích tự kiểm soát, có thể tải repo về và xem các tệp mẫu:
git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngxCác tệp compose được cấu hình sẵn nằm trong thư mục docker/compose của repo, và chúng kéo image từ GitHub container registry. Cách chạy chi tiết từng tệp README không ghi, bạn xem trong docs.
D.Cách cài khác và nâng cấp
README chưa liệt kê lệnh cho các cách cài khác ngoài script. Hướng dẫn từng bước cho các phương án đó nằm trong mục installation của docs. Còn nếu bạn đang dùng Paperless-ng, hãy đọc mục migrating trong cùng tài liệu trước khi thay image.
E.Chuẩn bị sao lưu
README nhấn mạnh việc chạy cùng bản sao lưu. Hãy quyết định nơi lưu và cách sao lưu dữ liệu ngay từ đầu, đừng để đến khi có sự cố mới nghĩ.
IV.Kiểm tra đã chạy được chưa
README không mô tả màn hình sau khi cài. Cách kiểm tra chắc chắn nhất là:
- Chạy
docker compose pstrong thư mục chứa tệp compose của bạn và xem các container đã ở trạng thái đang chạy chưa. Đây là lệnh docker phổ thông, không riêng của dự án. - Mở địa chỉ mà script cài đặt báo ở cuối quá trình, bằng trình duyệt. Nếu bạn thấy trang đăng nhập Paperless-ngx thì cài đặt thành công.
- Muốn biết giao diện trông thế nào trước khi cài, hãy vào trang demo của dự án (demo.paperless-ngx.com) và đăng nhập bằng
demo/demo. Nội dung demo bị đặt lại thường xuyên, nên tuyệt đối không tải tài liệu nhạy cảm lên đó.
V.Dùng vào việc thật
README không có ví dụ lệnh dùng hằng ngày, nên các tình huống dưới đây bám theo mục đích chính của repo: số hóa, tìm kiếm, lưu trữ. Cách nạp tài liệu và các tính năng nâng cao bạn xem thêm trong docs.
A.Chủ shop nhỏ gom hóa đơn nhà cung cấp
Chị Lan bán hàng online, mỗi tháng nhận hàng chục hóa đơn giấy. Chị scan hóa đơn thành PDF rồi đưa vào Paperless-ngx. Khi nhà cung cấp hỏi lại một khoản thanh toán, chị gõ tên nhà cung cấp vào ô tìm kiếm thay vì lục từng tập giấy. Kết quả là chị tìm lại đúng hóa đơn trong vài giây.
B.Nhân viên văn phòng lưu hợp đồng
Anh Minh làm hành chính, giữ hợp đồng lao động và hợp đồng thuê. Anh scan hết và để hệ thống lưu trữ trong một chỗ duy nhất. Khi sếp hỏi điều khoản gia hạn, anh tìm theo cụm từ trong nội dung hợp đồng. Nhờ OCR, kể cả bản scan cũng có thể tìm theo chữ bên trong.
Giấy tờ không mất đi, nó chỉ chuyển từ tủ hồ sơ sang một ô tìm kiếm.
Ông T
C.Gia đình lưu giấy tờ thuế và bảo hiểm
Một gia đình muốn giữ hồ sơ thuế, bảo hiểm, giấy khám bệnh gọn gàng. Họ chạy Paperless-ngx trên một máy chủ nhỏ trong nhà đúng như khuyến cáo của README, và sao lưu định kỳ. Đến mùa kê khai, mọi giấy tờ nằm ở một nơi, tìm lại không mất cả buổi.
D.Lập trình viên thử nghiệm và đóng góp
Bạn là dev mới và muốn học một dự án Django kết hợp Angular lớn. Bạn clone repo, đọc CONTRIBUTING.md và tài liệu phát triển. Dự án có các nhóm (frontend, CI/CD…) và chào đón đóng góp, từ sửa lỗi, cải thiện giao diện đến dịch thuật.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý sự cố, nên đây là những lỗi rất dễ gặp với loại công cụ này. Với từng lỗi cụ thể, hãy xem docs hoặc mục Discussions trên GitHub.
- Lệnh
dockerhoặcdocker composekhông nhận. Docker chưa được cài hoặc chưa chạy. Cài Docker, khởi động lại terminal rồi thử lại. - Chạy lệnh cài đặt trên Windows báo lỗi. Lệnh dùng
bashvàcurl, nên PowerShell thuần có thể không chạy được. Hãy mở WSL hoặc Git Bash rồi dán lại. - Không mở được trang web sau khi cài. Kiểm tra container có đang chạy không bằng
docker compose ps, và xem lại địa chỉ mà script cài đặt đã báo. Nếu vẫn lỗi, mở một Issue hoặc Discussion trên GitHub như README gợi ý. - Lỡ tải tài liệu nhạy cảm lên bản demo. Bản demo bị đặt lại thường xuyên và không dành cho dữ liệu bí mật. Chỉ thử bằng tài liệu giả.
- Lo lắng về dữ liệu không mã hóa. README thừa nhận dữ liệu lưu dạng văn bản thường. Hãy chạy trên máy chủ bạn tin tưởng, ưu tiên mạng nội bộ, và luôn có bản sao lưu.
VII.Có nên dùng không
Điểm mạnh. Mã nguồn mở theo giấy phép GPL-3.0, dữ liệu nằm ở máy của bạn, cộng đồng lớn và repo vẫn được cập nhật trong vài tháng gần đây. Cách cài bằng docker compose có script hỗ trợ, nên người mới cũng làm được. Tài liệu chính thức đầy đủ, và có demo để thử trước.
Giới hạn. Bạn phải tự vận hành: cài Docker, tự sao lưu, tự bảo vệ máy chủ. README nói thẳng là không đảm bảo về bảo mật và bạn dùng với rủi ro của mình. Dữ liệu không được mã hóa, nên không hợp để đặt lên máy chủ không đáng tin. README cũng không nhắc đến ứng dụng di động chính thức hay hỗ trợ trả phí.
Khi nào chọn cách khác. Nếu bạn chỉ có vài chục tệp PDF, một thư mục đặt tên cẩn thận có thể là đủ. Nếu bạn không muốn tự quản lý máy chủ, hãy cân nhắc dịch vụ lưu trữ tài liệu có sẵn. Còn nếu bạn muốn kiểm soát dữ liệu và chịu khó bỏ chút công cài đặt, Paperless-ngx là lựa chọn rất đáng thử.
Câu hỏi thường gặp
Paperless-ngx có miễn phí không?
Repo là mã nguồn mở theo giấy phép GPL-3.0. README không nhắc đến phí sử dụng. Bạn chỉ phải lo chi phí máy chủ hoặc máy tính chạy nó.
Cần GPU hay máy mạnh để chạy không?
README không nêu yêu cầu phần cứng, kể cả GPU. Hiện chưa có thông tin cụ thể, bạn xem mục cài đặt trong tài liệu chính thức.
Chạy trên Windows được không?
README không nói riêng về Windows. Cách cài chính là docker compose và script bash, nên bạn cần Docker và một môi trường có bash như WSL hoặc Git Bash. Chi tiết xem ở mục installation trong docs.
Dữ liệu của tôi có an toàn không?
README cảnh báo tài liệu được lưu dạng văn bản thường, không mã hóa, và không có bảo đảm về bảo mật. Bạn không nên chạy nó trên máy chủ không đáng tin. Cách an toàn nhất theo README là chạy trên máy chủ cục bộ tại nhà và có sao lưu.
Cài đặt nhanh nhất bằng cách nào?
Dùng script cài đặt trong README, chạy bằng bash và curl để cấu hình môi trường docker compose. Các tệp compose cấu hình sẵn cũng nằm trong thư mục docker/compose của repo. Muốn cách cài khác, hãy xem docs ở mục installation.
Tôi đang dùng Paperless-ng, chuyển sang được không?
Được. README nói việc chuyển từ Paperless-ng khá dễ, chỉ cần thay bằng docker image mới. Hãy đọc mục migrating trong tài liệu trước khi làm.
Làm sao thử mà không cần cài?
Dự án có bản demo ở demo.paperless-ngx.com, đăng nhập bằng demo / demo. Nội dung demo bị đặt lại thường xuyên, nên đừng tải lên thông tin nhạy cảm.


