Bỏ qua tới nội dung
Ông T.vn

Paperless-ngx: số hoá và tìm lại mọi giấy tờ trong vài giây — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật

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 →

Paperless-ngx: số hoá và tìm lại mọi giấy tờ trong vài giây — 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ờ in thành một kho lưu trữ số có thể tìm kiếm. Bạn tự chạy nó trên máy hoặc máy chủ của mình, nên dữ liệu nằm trong tay bạn. Cài đặt khá dễ nhờ Docker Compose và một script cài sẵn, nhưng bạn cần biết dùng terminal cơ bản.

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 có thể tìm kiếm được, để bạn giữ ít giấy hơn (đúng như tên gọi, "less paper"). Bạn tự chạy nó trên máy của mình, không phải gửi tài liệu cho dịch vụ nào bên ngoài.

Repo này hợp với ai? Chủ shop nhỏ phải giữ hoá đơn, hợp đồng, phiếu giao hàng. Nhân viên văn phòng có một đống file scan đặt tên lung tung. Cá nhân muốn gom giấy tờ gia đình, sổ bảo hiểm, giấy tờ thuế vào một chỗ. Lập trình viên mới muốn tự dựng một hệ thống thật để học cũng làm được.

Điểm đáng giá nhất là dự án đã rất đông người dùng: hiện có khoảng 48.000 sao và khoảng 3.383 fork trên GitHub, và vẫn được cập nhật trong 3 tháng gần đây. Đây là bản kế thừa chính thức của hai dự án Paperless và Paperless-ng trước đó, được một nhóm cộng đồng cùng duy trì. Bạn có thể xem video ngắn bên dưới để thấy nó chạy ra sao trước khi cài.

Ứng dụng

paperless-ngx/paperless-ngx

Hệ thống quản lý tài liệu mã nguồn mở: quét giấy tờ, nhận dạng chữ (OCR), lưu trữ và tìm kiếm lại như tìm trên Google.

★ 48kPythonGPL-3.0
Xem repo trên GitHub
Video giới thiệu paperless-ngxXem trên YouTube

I.Paperless-ngx làm được gì

Tư liệu README chỉ liệt kê ngắn gọn và dẫn sang trang tài liệu chính thức để xem danh sách đầy đủ. Dựa trên mô tả của tác giả và các chủ đề của repo (OCR, PDF, lưu trữ, tìm kiếm), đây là những điều chính bạn nhận được:

  • Quét, lập chỉ mục và lưu trữ tài liệu. Mô tả của tác giả nói rõ ba việc này: scan, index and archive. Tài liệu đưa vào được lưu thành kho chung thay vì nằm rải rác trong ngăn kéo hay thư mục máy tính.
  • Tìm kiếm trong nội dung. Repo gắn thẻ OCR (nhận dạng chữ trong ảnh) và PDF. Ý nghĩa thực tế là một tờ hoá đơn chụp bằng máy quét vẫn tìm lại được bằng từ khoá trong nội dung, không chỉ bằng tên file.
  • Giao diện web. Phần giao diện viết bằng Angular, còn phần lõi bằng Python và Django. Bạn dùng qua trình duyệt, không cần cài phần mềm riêng trên từng máy.
  • Nhiều ngôn ngữ giao diện. README cho biết bản dịch được cộng đồng điều phối trên Crowdin, nên bạn có thể tìm xem ngôn ngữ của mình đã có chưa.
  • Đổi từ Paperless-ng sang. Nếu bạn đang dùng Paperless-ng, README nói chuyển sang rất dễ: chỉ cần thay bằng image Docker mới. Chi tiết nằm ở phần hướng dẫn chuyển đổi trong tài liệu.
  • Có bản demo để thử. Bạn có thể dùng thử trước khi cài, ở địa chỉ demo.paperless-ngx.com, đăng nhập bằng demo / demo. Nhớ là nội dung demo bị xoá thường xuyên và README dặn rõ: đừng đưa thông tin nhạy cảm lên đó.

Mình khuyên bạn vào bản demo trước 10 phút. Nhìn giao diện thật sẽ giúp bạn quyết định có đáng cài hay không.

II.Cần chuẩn bị gì

Theo README, cách dễ nhất để chạy Paperless-ngx là docker compose. Các file cấu hình trong thư mục docker/compose của repo đã được chỉnh sẵn để kéo image từ GitHub container registry. Vậy bạn cần:

  • Một máy hoặc máy chủ chạy được Docker và Docker Compose. README chưa ghi chi tiết phiên bản hay hệ điều hành cụ thể ở phần này; bạn xem phần Installation trong tài liệu chính thức.
  • Một cửa sổ terminal có shell bash, vì script cài đặt trong README là lệnh bash. README không nói gì về chạy trên Windows, nên nếu bạn dùng Windows, hãy đọc kỹ tài liệu cài đặt trước khi làm.
  • Python từ 3.11 trở lên chỉ cần khi bạn cài kiểu chạy trực tiếp mã nguồn (không qua Docker). File pyproject.toml của repo yêu cầu >=3.11. Nếu bạn dùng Docker thì không cần quan tâm.
  • Tài khoản, API key, GPU: tư liệu không yêu cầu gì trong số này để cài và chạy. Chưa có thông tin về yêu cầu RAM hay ổ đĩa, bạn nên xem trang tài liệu.

README cảnh báo rõ: Paperless-ngx lưu thông tin ở dạng văn bản thường, không mã hoá. Đừng chạy nó 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ộ trong nhà hoặc văn phòng của bạn, và luôn có bản sao lưu.

III.Cài đặt từng bước

Có nhiều cách cài, nhưng mình hướng dẫn cách README gọi là dễ nhất: dùng script cài đặt để tạo sẵn môi trường docker compose.

  1. Chuẩn bị DockerCài Docker và Docker Compose trên máy hoặc máy chủ của bạn
  2. Mở terminalMở cửa sổ dòng lệnh có shell bash
  3. Chạy script càiDán một lệnh duy nhất, trả lời các câu hỏi trên màn hình
  4. Mở trình duyệtVào giao diện web để đăng nhập và thử tải tài liệu
  5. Cân nhắc cách khácXem tài liệu nếu muốn cài theo cách không dùng script

A.Chuẩn bị Docker

README không hướng dẫn cài Docker, vì đó là việc chung của mọi ứng dụng chạy bằng container. Bạn cần Docker và Docker Compose đã hoạt động. Nếu chưa có, hãy cài theo hướng dẫn chính thức của Docker cho hệ điều hành của bạn rồi quay lại.

B.Mở terminal và chạy script cài đặt

Mở terminal ở máy hoặc máy chủ sẽ chạy Paperless-ngx. Chỗ người mới hay vấp: nếu bạn dùng máy chủ ở xa, hãy mở terminal đã kết nối vào máy chủ đó, không phải terminal trên máy cá nhân.

Sau đó dán lệnh sau (chép đúng từ README):

Terminal
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Lệnh này làm gì? curl -L tải file script install-paperless-ngx.sh từ repo về, rồi bash -c chạy luôn script đó. README nói script sẽ giúp bạn cấu hình một môi trường docker compose. Các câu hỏi cụ thể mà script đặt ra, README không liệt kê, nên bạn cứ đọc từng câu trên màn hình và trả lời theo nhu cầu của mình.

Một thói quen tốt: trước khi chạy bất kỳ script tải từ mạng nào, hãy mở file đó ra đọc. Bạn có thể xem file install-paperless-ngx.sh ngay trong repo trên GitHub.

C.Cách khác: tự lấy mã nguồn về

Nếu bạn muốn xem file cấu hình trước khi chạy, hãy tải cả repo về:

Terminal
git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngx

Lệnh đầu tải mã nguồn về máy, lệnh thứ hai đi vào thư mục vừa tải. Trong đó có thư mục docker/compose chứa các file cấu hình mà README nhắc tới. README không ghi cụ thể bạn phải chạy lệnh nào tiếp theo từ các file này, nên hãy làm theo phần Installation trong tài liệu chính thức: https://docs.paperless-ngx.com/setup/#installation.

D.Mở giao diện web

Sau khi script chạy xong, bạn truy cập giao diện bằng trình duyệt. Địa chỉ và cổng cụ thể phụ thuộc vào những gì bạn chọn khi trả lời script, và README không ghi con số nào, nên hãy xem thông báo cuối cùng của script hoặc tài liệu.

E.Chuyển từ Paperless-ng

Nếu bạn đang chạy Paperless-ng, không cần cài mới. README nói bạn chỉ cần thay bằng image Docker mới và dẫn tới mục hướng dẫn chuyển đổi (migrating) trong tài liệu. Hãy sao lưu dữ liệu trước khi làm.

IV.Kiểm tra đã chạy được chưa

README không đưa ra lệnh kiểm tra riêng. Cách đơn giản và thực tế là:

  1. Mở trình duyệt, vào địa chỉ mà script cài đặt báo ở cuối.
  2. Nếu thấy trang đăng nhập của Paperless-ngx, phần chính đã chạy.
  3. Đăng nhập, rồi thử tải lên một file PDF hoặc ảnh có chữ.
  4. Đợi một lúc cho hệ thống xử lý, rồi gõ một từ có trong tài liệu vào ô tìm kiếm. Nếu tài liệu hiện ra, nghĩa là quét và lập chỉ mục đã hoạt động.

Nếu bạn muốn biết "đúng thì trông như thế nào" trước khi cài, hãy mở bản demo ở demo.paperless-ngx.com và so sánh với bản của mình.

V.Dùng vào việc thật

Tư liệu chỉ nói về khả năng quét, lập chỉ mục, lưu trữ và tìm kiếm tài liệu. Các tình huống dưới đây bám đúng phạm vi đó. Mình không hứa những tính năng README không nhắc.

A.Chủ shop nhỏ gom hoá đơn và hợp đồng

Chị Lan bán đồ gia dụng, cuối tháng phải lục lại hoá đơn nhập hàng để đối chiếu với kế toán. Chị quét hoặc chụp hoá đơn thành PDF rồi tải vào Paperless-ngx. Đến lúc cần, chị gõ tên nhà cung cấp hoặc số hoá đơn vào ô tìm kiếm thay vì lật từng tập giấy.

Kết quả: tìm một tờ hoá đơn mất vài giây thay vì cả buổi. Đây là điểm khác biệt lớn nhất so với việc để file trong thư mục, vì tìm được cả nội dung bên trong ảnh quét nhờ OCR.

B.Nhân viên hành chính văn phòng bỏ thói quen đặt tên file

Anh Hùng phụ trách hành chính, hay nhận công văn, hợp đồng bản cứng. Trước đây anh đặt tên file theo ý mỗi người nên không ai tìm ra. Giờ cả phòng quét tài liệu vào cùng một hệ thống, và khi cần tìm "hợp đồng thuê văn phòng", anh chỉ gõ cụm từ đó.

Lưu ý: README không nói về phân quyền người dùng hay quy trình duyệt tài liệu, nên nếu phòng bạn cần các thứ đó, hãy đọc danh sách tính năng đầy đủ trong tài liệu trước khi quyết định.

Giấy tờ không đáng sợ khi bạn tìm lại được nó trong vài giây.

Ông T

C.Gia đình lưu giấy tờ cá nhân

Một gia đình có nhiều loại giấy: sổ bảo hiểm, hoá đơn bảo hành, hồ sơ thuế, giấy tờ học tập của con. Họ dựng Paperless-ngx trên một máy chủ nhỏ đặt trong nhà, đúng khuyến nghị của README là chạy ở máy chủ cục bộ có sao lưu. Mỗi khi cần bảo hành đồ điện, chỉ cần tìm tên sản phẩm là ra hoá đơn mua.

Vì đây là giấy tờ nhạy cảm, hãy làm đúng lời dặn: không đưa lên máy chủ bạn không tin tưởng, và luôn sao lưu.

D.Lập trình viên mới học dựng hệ thống thật

Nếu bạn đang tập Docker hoặc muốn xem một dự án Django kết hợp Angular lớn trông ra sao, repo là tài liệu học rất tốt. Bạn cài bằng script, thử dùng, rồi tải mã nguồn về đọc:

Terminal
git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngx

Trong repo có src/ (phần Python), src-ui/ (giao diện Angular), docker/ và docs/. Muốn đóng góp, README dẫn tới trang hướng dẫn phát triển ở docs.paperless-ngx.com/development. Với thay đổi lớn, họ đề nghị bạn mở một thảo luận trước.

VI.Lỗi hay gặp và cách xử lý

README không có mục xử lý lỗi, nên dưới đây là những chỗ rất dễ vấp với loại ứng dụng chạy bằng Docker. Mình nói rõ chúng là suy luận từ kinh nghiệm chung, không phải trích từ tư liệu.

  • Lệnh curl hoặc bash báo không tìm thấy. Máy chưa có curl hoặc bạn không đứng trong shell bash (ví dụ mở nhầm cửa sổ lệnh khác). Hãy mở terminal có bash, hoặc đọc phần Installation trong tài liệu để chọn cách cài khác.
  • Docker chưa chạy hoặc thiếu quyền. Script cấu hình docker compose cần Docker đang hoạt động. Hãy kiểm tra Docker đã khởi động chưa, đừng vội dùng quyền quản trị cao nhất cho mọi thứ nếu chưa hiểu lệnh làm gì.
  • Không vào được trang web sau khi cài. Thường do nhập sai địa chỉ hoặc cổng, hoặc tường lửa chặn. Xem lại thông báo cuối của script và cấu hình bạn đã chọn.
  • Tải tài liệu lên nhưng không tìm thấy bằng từ khoá. Hệ thống cần thời gian xử lý và nhận dạng chữ. Đợi một lúc rồi thử lại. Nếu file là ảnh chất lượng quá thấp thì kết quả nhận dạng sẽ kém.
  • Mất dữ liệu sau khi cập nhật hoặc chuyển đổi. Luôn sao lưu trước khi nâng cấp, đặc biệt khi chuyển từ Paperless-ng. README nhấn mạnh việc có sao lưu.

Nếu vẫn không giải quyết được, README chỉ ra hai nơi: mở issue trên GitHub nếu là lỗi, hoặc mở một thảo luận (discussion) nếu là câu hỏi.

VII.Có nên dùng không

Điểm mạnh:

  • Miễn phí, mã nguồn mở theo giấy phép GPL-3.0.
  • Dữ liệu nằm trên máy của bạn, không phụ thuộc dịch vụ đám mây nào.
  • Cộng đồng rất lớn (khoảng 48.000 sao) và vẫn được cập nhật đều.
  • Có bản demo để thử trước, và có tài liệu chính thức đầy đủ.
  • Có đường chuyển đổi từ Paperless-ng.

Giới hạn:

  • README nói rõ tài liệu được lưu dạng văn bản thường, không mã hoá, và không đảm bảo về bảo mật. Bạn dùng với trách nhiệm của mình.
  • Bạn phải tự vận hành: cài Docker, tự sao lưu, tự nâng cấp. Nếu bạn không muốn đụng vào terminal thì đây không phải lựa chọn nhẹ nhàng.
  • README không nói về hỗ trợ Windows, về yêu cầu phần cứng hay về tiếng Việt khi nhận dạng chữ. Bạn cần kiểm tra trong tài liệu.

Khi nào nên chọn cách khác: nếu bạn chỉ có vài chục file và không ngại để trong thư mục, một thư mục có tên file rõ ràng là đủ. Nếu cần một dịch vụ có người vận hành sẵn, có cam kết bảo mật, hãy cân nhắc dịch vụ trả phí. Còn nếu bạn muốn tự giữ giấy tờ trong tay, tìm lại nhanh và không ngại cài đặt một lần cho xong, Paperless-ngx rất đáng thử. Hãy bắt đầu bằng bản demo, rồi mới quyết định cài.

4.3/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

Câu hỏi thường gặp

Paperless-ngx có miễn phí không?

Có. Đây là phần mềm mã nguồn mở theo giấy phép GPL-3.0, bạn tải và dùng không mất phí bản quyền. Tư liệu không nói về chi phí máy chủ hay điện, những khoản đó bạn tự chịu nếu tự vận hành.

Cài Paperless-ngx có khó không?

README gọi `docker compose` là cách dễ nhất và cung cấp một script cài đặt chỉ cần dán một lệnh. Bạn cần biết mở terminal và đã có Docker. Nếu muốn cài theo cách khác, README dẫn sang tài liệu chính thức.

Có cần GPU hay API key không?

Tư liệu README không yêu cầu GPU, tài khoản hay API key để cài và chạy. Chưa có thông tin về yêu cầu RAM hoặc ổ đĩa, bạn xem thêm trong tài liệu chính thức.

Chạy trên Windows được không?

README chưa nói rõ về Windows. Script cài đặt là lệnh bash và cách dễ nhất là dùng Docker Compose. Nếu bạn dùng Windows, hãy đọc phần Installation trong tài liệu chính thức trước khi cài.

Dữ liệu của tôi có an toàn không?

README cảnh báo thông tin được lưu dạng văn bản thường, không mã hoá, và không đảm bảo về bảo mật. Họ khuyên không chạy trên máy chủ không đáng tin, và an toàn nhất là máy chủ cục bộ trong nhà có sao lưu. Đừng đưa tài liệu nhạy cảm lên bản demo công khai.

Có thể thử trước khi cài không?

Có. README cung cấp bản demo ở demo.paperless-ngx.com, đăng nhập bằng `demo` / `demo`. Nội dung demo bị xoá thường xuyên nên chỉ dùng để xem thử, không tải tài liệu quan trọng lên.

Tôi đang dùng Paperless-ng thì chuyển sang thế nào?

README nói việc chuyển rất dễ: chỉ cần thay bằng image Docker mới. Chi tiết nằm ở mục hướng dẫn migrating trong tài liệu chính thức. Bạn nên sao lưu dữ liệu trước khi làm.

Chuyển nhanh tới mục

  1. I.Paperless-ngx làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chuẩn bị Docker
    2. B.Mở terminal và chạy script cài đặt
    3. C.Cách khác: tự lấy mã nguồn về
    4. D.Mở giao diện web
    5. E.Chuyển từ Paperless-ng
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop nhỏ gom hoá đơn và hợp đồng
    2. B.Nhân viên hành chính văn phòng bỏ thói quen đặt tên file
    3. C.Gia đình lưu giấy tờ cá nhân
    4. D.Lập trình viên mới học dựng hệ thống thật
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.