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

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

11 phút đọcCập nhật
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ữ số có thể tìm kiếm. Cách dễ nhất để chạy là docker compose, kèm một script cài đặt chỉ cần một dòng lệnh. Với người đã quen dùng Docker thì cài không khó, còn người mới nên đọc kỹ phần chuẩn bị bên dưới.

Paperless-ngx là một hệ thống quản lý tài liệu (DMS) mã nguồn mở, chạy trên máy chủ của bạn. Nó biến giấy tờ thật thành một kho lưu trữ số có thể tìm kiếm, để bạn giữ ít giấy hơn. Chủ dự án mô tả nó là hệ thống quản lý tài liệu "được cộng đồng hỗ trợ", dùng để scan, lập chỉ mục và lưu trữ toàn bộ tài liệu.

Bạn nên xem repo này nếu nhà hoặc văn phòng bạn có một đống hoá đơn, hợp đồng, giấy tờ thuế, thư từ cần giữ lại mà mỗi lần cần là lục cả buổi. Người làm kinh doanh nhỏ, nhân viên văn phòng, hay lập trình viên muốn tự dựng kho tài liệu riêng đều hợp. Điểm đáng giá nhất là dữ liệu nằm trên máy của bạn, không phải gửi lên một dịch vụ lưu trữ của bên thứ ba.

Dự án này là bản kế nhiệm chính thức của Paperless và Paperless-ng, hiện có khoảng 48 nghìn sao và hơn 3.300 fork trên GitHub, giấy phép GPL-3.0. Repo vẫn được cập nhật trong vài tháng gần đây. Bạn có thể xem video ngắn bên dưới để thấy nó chạy ra sao, rồi quay lại đọc phần cài đặt.

Ứng dụng

paperless-ngx/paperless-ngx

Paperless-ngx là hệ thống quản lý tài liệu tự host: scan giấy tờ, lập chỉ mục để tìm kiếm và lưu trữ gọn gàng trên máy chủ của chính bạn.

★ 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 khá ngắn và trỏ sang trang tài liệu chính thức để xem danh sách tính năng đầy đủ. Dưới đây là những gì mình đọc được từ mô tả và chủ đề của repo. Danh sách chi tiết và ảnh chụp màn hình bạn xem ở trang docs.paperless-ngx.com.

  • Số hoá giấy tờ thành kho lưu trữ có thể tìm kiếm. Đây là mục tiêu cốt lõi của dự án. Thay vì mở từng tập giấy, bạn tìm trong một kho số. Chủ đề của repo có nhắc đến OCR (nhận dạng chữ từ ảnh) và PDF, nên ý tưởng là tài liệu scan được đọc chữ để tra cứu.
  • Lập chỉ mục và lưu trữ. Mô tả của tác giả dùng đúng ba động từ: scan, index và archive. Lợi ích thực tế là bạn không phải nhớ file nằm ở thư mục nào, chỉ cần tìm.
  • Giao diện web. Repo có thư mục src-ui (giao diện viết bằng Angular) và src (phần xử lý viết bằng Django/Python). 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ữ. README cho biết Paperless-ngx có nhiều ngôn ngữ, việc dịch được điều phối qua Crowdin. README không liệt kê cụ thể có tiếng Việt hay không, nên bạn thử trong ứng dụng hoặc xem trang Crowdin của dự án.
  • Có bản demo để thử trước. Bạn vào demo.paperless-ngx.com, đăng nhập bằng demo / demo. Nội dung demo bị xoá thường xuyên và README dặn rõ là không được tải tài liệu bí mật lên đó.
  • Chuyển từ Paperless-ng dễ. Nếu bạn đang dùng Paperless-ng, README nói chỉ cần thay bằng image Docker mới. Chi tiết ở phần migrating trong tài liệu.
  • Cộng đồng hỗ trợ. Dự án có đội nhóm (frontend, CI/CD…), phòng Matrix, GitHub Discussions để đề xuất tính năng. Nếu bạn gặp khó, có chỗ để hỏi.

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

Theo README, cách triển khai dễ nhất là docker compose. Các file cấu hình mẫu nằm trong thư mục docker/compose của repo và được cấu hình để kéo image từ GitHub container registry. Vì vậy thứ bạn cần trước tiên là một máy đã có Docker và docker compose.

  • Máy chủ. README khuyên chạy trên một máy chủ cục bộ trong nhà bạn, có sao lưu. Tư liệu không nêu cấu hình phần cứng tối thiểu (RAM, ổ đĩa), nên mình không đưa con số nào. Bạn xem mục cài đặt trong docs.
  • Hệ điều hành. Tư liệu không nói rõ hệ điều hành nào được hỗ trợ cho cách cài bằng Docker. Script cài đặt là file install-paperless-ngx.sh chạy bằng bash, nên bạn cần một môi trường có bash và curl. Với Windows, README chưa ghi hướng dẫn riêng, bạn nên xem trang setup trong docs trước khi làm.
  • Python. Nếu chạy bằng Docker, bạn không cần tự cài Python. Chỉ khi cài thủ công (không dùng Docker) mới cần Python, vì pyproject.toml yêu cầu Python từ 3.11 trở lên.
  • Tài khoản và API key. README không yêu cầu API key hay tài khoản dịch vụ ngoài để chạy. Bạn sẽ tạo tài khoản quản trị ngay trong ứng dụng của mình.
  • GPU. Tư liệu không nhắc đến yêu cầu GPU.

Giấy tờ scan thường chứa thông tin nhạy cảm như số bảo hiểm, hồ sơ thuế, hoá đơn. README cảnh báo: dữ liệu được lưu dạng chữ rõ, không mã hoá. Đừng chạy Paperless-ngx trên máy chủ bạn không tin tưởng, và hãy có bản sao lưu.

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

README đưa ra cách nhanh nhất là một dòng lệnh với script cài đặt, tạo sẵn môi trường docker compose cho bạn. Các bước dưới đây bám theo đó.

  1. Chuẩn bị DockerCài Docker và docker compose lên máy chủ của bạn
  2. Mở terminalMở cửa sổ dòng lệnh có bash trên máy sẽ chạy Paperless-ngx
  3. Chạy script càiDán một dòng lệnh để tải và chạy install-paperless-ngx.sh
  4. Trả lời câu hỏi của scriptĐiền các lựa chọn cấu hình khi script hỏi
  5. Mở giao diện webVào trình duyệt, tạo tài khoản và thử đưa tài liệu vào

A.Cài Docker và docker compose

README không hướng dẫn cài Docker, vì đó là công cụ độc lập. Bạn cài Docker theo hướng dẫn trên trang chính thức của Docker cho hệ điều hành của mình. Xong, bạn có thể kiểm tra Docker có chạy không bằng lệnh phổ thông sau:

Terminal
docker --version

Nếu lệnh in ra phiên bản, Docker đã có trên máy. Nếu báo "command not found" hoặc tương tự, bạn chưa cài xong.

B.Chạy script cài đặt

Mở terminal trên máy chủ (người mới hay quên: lệnh này phải chạy trên máy sẽ chứa Paperless-ngx, không phải máy khác). Dán đúng dòng lệnh trong 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 hai việc. curl -L tải file script install-paperless-ngx.sh từ repo chính thức về. bash -c chạy nội dung script đó. Script sẽ cấu hình một môi trường docker compose cho bạn.

Vì lệnh chạy thẳng một script tải từ mạng, bạn nên mở đường link install-paperless-ngx.sh trong repo để đọc qua trước khi chạy. Đó là thói quen tốt với mọi script kiểu này.

C.Trả lời các câu hỏi của script

README không liệt kê script sẽ hỏi những gì. Khi chạy, bạn đọc kỹ từng câu hỏi trên màn hình rồi trả lời. Nếu chưa chắc câu nào, hãy dừng lại và đọc phần Installation trong trang docs.paperless-ngx.com/setup trước khi chọn, vì một số lựa chọn ảnh hưởng đến chỗ lưu dữ liệu của bạn.

D.Cách cài khác (không dùng script)

Nếu bạn muốn tự làm, README chỉ cho hai hướng. Một là dùng các file trong thư mục docker/compose của repo. Hai là xem hướng dẫn từng bước cho các cách cài khác ở trang docs.paperless-ngx.com/setup/#installation. Bạn có thể tải mã nguồn về xem bằng lệnh phổ thông sau:

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

README chưa ghi chi tiết lệnh chạy sau bước này, nên bạn xem file hướng dẫn trong thư mục docker/compose và trang docs để làm đúng.

E.Mở giao diện web

Sau khi script chạy xong, bạn mở trình duyệt để vào giao diện. README không nêu địa chỉ hay cổng cụ thể. Hãy xem thông báo script in ra ở cuối, hoặc phần cấu hình trong docs. Lần đầu vào, bạn sẽ cần tạo tài khoản quản trị theo hướng dẫn của docs.

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

Cách đơn giản nhất: bạn mở được trang web Paperless-ngx trong trình duyệt và đăng nhập được. Nếu thấy giao diện quản lý tài liệu, bạn đã cài thành công.

Trước khi cài, nếu muốn biết giao diện trông thế nào, bạn thử demo ở demo.paperless-ngx.com với tài khoản demo / demo. Nhớ là không tải tài liệu thật lên đó.

Bước thử tiếp theo là đưa một tài liệu mẫu vào hệ thống (ví dụ một hoá đơn không quan trọng) và tìm lại bằng một từ có trong tài liệu. Nếu tìm ra, chuỗi scan, lập chỉ mục và tìm kiếm đã hoạt động. README không mô tả chi tiết thao tác tải lên hay thư mục nhận file, bạn xem phần sử dụng trong docs.

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

Các tình huống dưới đây bám vào mục tiêu chính của repo là scan, lập chỉ mục, lưu trữ và tìm kiếm. Các thao tác chi tiết trong giao diện bạn xem thêm trong docs.

A.Chủ cửa hàng nhỏ gom hoá đơn và chứng từ

Chị Lan bán đồ gia dụng, mỗi tháng nhận hàng chục hoá đơn giấy từ nhà cung cấp. Trước đây chị nhét vào một cái hộp, cuối quý kế toán hỏi là cả nhà lục tung. Giờ chị scan hoá đơn bằng máy scan hoặc điện thoại, đưa vào Paperless-ngx chạy trên một máy nhỏ ở cửa hàng.

Khi kế toán cần hoá đơn của một nhà cung cấp, chị gõ tên nhà cung cấp hoặc một số hoá đơn vào ô tìm kiếm thay vì mở từng tập giấy. Kết quả là chị tìm được chứng từ trong vài giây, và giấy gốc có thể cất gọn một chỗ.

Giữ giấy tờ không khó, khó là lúc cần thì không tìm ra. Một kho tài liệu tìm được mới là kho có ích.

Ông T

B.Nhân viên hành chính văn phòng lưu hợp đồng

Anh Minh làm hành chính ở một công ty nhỏ, phụ trách hợp đồng lao động, hợp đồng thuê và biên bản. Mỗi lần sếp hỏi "hợp đồng thuê kho còn hạn đến khi nào", anh phải mở nhiều thư mục. Anh dựng Paperless-ngx trên một máy chủ nội bộ của công ty và scan toàn bộ hợp đồng vào.

Khi cần, anh tìm theo tên đối tác hoặc cụm từ trong nội dung hợp đồng. Vì kho là chỉ mục toàn văn do OCR tạo ra, anh không phải nhớ tên file do ai đặt. Lưu ý đây là điểm anh nên tự thử trước với tài liệu của mình, vì chất lượng nhận dạng phụ thuộc vào bản scan.

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

Nhà bạn Hà có giấy tờ nhà đất, hồ sơ bảo hiểm, hồ sơ học bạ của con, hoá đơn điện nước. Bạn chọn cách an toàn mà README khuyên: chạy Paperless-ngx trên một máy chủ nhỏ ngay trong nhà, có sao lưu định kỳ.

Bạn scan từng loại giấy và đưa vào hệ thống. Khi cần nộp hồ sơ cho trường hoặc ngân hàng, bạn tìm lại bản scan trong vài giây. Đây là kiểu dùng mà dự án nhắm tới, và là lý do README nhấn mạnh việc chạy trong mạng nhà riêng.

D.Lập trình viên thử nghiệm và đóng góp

Bạn là dev mới, muốn xem một ứng dụng Django kết hợp Angular lớn thì tổ chức ra sao. Bạn tải repo về, xem src (Python/Django), src-ui (Angular) và docs. File pyproject.toml khai báo gói paperless-ngx và yêu cầu Python từ 3.11. Nếu muốn đóng góp, README gợi ý đọc phần development trong docs và mở một thảo luận trước khi làm việc lớn. Bạn cũng có thể giúp dịch qua Crowdin hoặc báo lỗi qua GitHub Issues.

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

README không có mục xử lý lỗi, nên các mục dưới đây là những tình huống rất dễ gặp với loại công cụ chạy bằng Docker. Khi gặp, bạn đối chiếu thêm với docs và GitHub Discussions.

  • Lệnh docker hoặc curl báo không tìm thấy. Máy bạn chưa cài Docker hoặc curl. Cài Docker theo trang chính thức, rồi chạy lại. Đừng thử chạy script khi chưa kiểm tra được docker --version.
  • Chạy script báo thiếu quyền với Docker. Đây là lỗi hay gặp khi tài khoản của bạn chưa được phép dùng Docker. Hãy xem hướng dẫn quyền của Docker trên hệ điều hành của bạn, thay vì cố chạy mọi thứ với quyền quản trị cao nhất.
  • Không mở được trang web sau khi cài. Có thể ứng dụng chưa khởi động xong, hoặc bạn đang gõ sai địa chỉ hay cổng. Đọc thông báo cuối của script và kiểm tra các container có đang chạy không bằng docker ps. Nếu vẫn không được, xem mục cài đặt trong docs.
  • Tìm kiếm không ra chữ trong tài liệu. Bản scan mờ, nghiêng hoặc độ phân giải thấp thì nhận dạng chữ sẽ kém. Scan lại rõ hơn. Tài liệu viết tay thường khó nhận dạng hơn chữ in.
  • Sợ mất dữ liệu. README nói Paperless-ngx lưu dữ liệu không mã hoá và không đảm bảo an toàn tuyệt đối. Bạn nên sao lưu định kỳ ra nơi khác, và đừng để máy chủ lộ ra internet nếu chưa hiểu rõ về bảo mật.

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

Điểm mạnh. Đây là một dự án lớn, có cộng đồng đông, được cập nhật gần đây, và có đội ngũ chia nhau trách nhiệm chứ không phụ thuộc một người. Dữ liệu nằm trên máy của bạn. Có script cài một dòng lệnh, có tài liệu riêng, có demo để thử trước. Giấy phép GPL-3.0 nên bạn dùng miễn phí.

Giới hạn. Bạn phải tự chạy và tự bảo trì máy chủ, gồm cả sao lưu. README thẳng thắn nói dữ liệu lưu dạng chữ rõ, không mã hoá, và không cam kết về bảo mật, bạn dùng tự chịu rủi ro. Với người chưa từng dùng Docker, bước cài đầu tiên có thể hơi khó. Tư liệu cũng không nói rõ về hỗ trợ Windows hay cấu hình phần cứng tối thiểu.

Khi nào chọn cách khác. Nếu bạn chỉ có vài chục giấy tờ và không muốn quản trị máy chủ, một thư mục có đặt tên gọn hoặc dịch vụ lưu trữ đám mây có sẵn sẽ đơn giản hơn. Nếu tài liệu của bạn đặc biệt nhạy cảm mà bạn không có máy chủ đáng tin cậy, đừng cài. Còn nếu bạn muốn một kho giấy tờ riêng, tìm được nhanh và tự chủ dữ liệu, Paperless-ngx là lựa chọn đáng thử, hãy bắt đầu từ bản demo rồi cài thử trên một máy trong nhà.

4.6/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?

Repo dùng giấy phép GPL-3.0 và là mã nguồn mở. Bạn tải về và tự chạy trên máy chủ của mình. Tư liệu không nói đến chi phí nào khác, còn chi phí máy chủ hay điện thì tuỳ bạn.

Cài Paperless-ngx dễ nhất bằng cách nào?

README nói cách dễ nhất là docker compose. Bạn có thể chạy script cài đặt bằng một dòng lệnh bash để tạo sẵn môi trường docker compose. Các cách cài khác có trong phần Installation của docs.paperless-ngx.com.

Có chạy được trên Windows không?

Tư liệu không nói rõ về Windows. Script cài đặt là file bash, nên bạn cần môi trường có bash. Bạn nên xem trang setup trong docs chính thức để biết cách làm phù hợp với máy của mình.

Có cần GPU hoặc cấu hình mạnh không?

Tư liệu không nhắc đến yêu cầu GPU và cũng không nêu cấu hình phần cứng tối thiểu. README khuyên chạy trên một máy chủ cục bộ trong nhà. Muốn biết chi tiết hơn, bạn xem trang docs.

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 chữ rõ, không mã hoá, và không cam kết về bảo mật. Cách an toàn nhất theo README là chạy trên máy chủ cục bộ trong nhà bạn và có sao lưu. Không nên chạy trên máy chủ không đáng tin cậy.

Tôi muốn thử trước khi cài thì làm sao?

Có bản demo tại demo.paperless-ngx.com, đăng nhập bằng demo / demo. Nội dung demo bị xoá thường xuyên và README dặn không tải thông tin bí mật lên đó.

Tôi đang dùng Paperless-ng thì chuyển sang có khó không?

README nói việc chuyển từ Paperless-ng rất dễ, chỉ cần thay bằng image Docker mới. Chi tiết nằm ở phần migrating to Paperless-ngx trong tài liệu chính thức.

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.Cài Docker và docker compose
    2. B.Chạy script cài đặt
    3. C.Trả lời các câu hỏi của script
    4. D.Cách cài khác (không dùng script)
    5. E.Mở giao diện web
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ cửa hàng nhỏ gom hoá đơn và chứng từ
    2. B.Nhân viên hành chính văn phòng lưu hợp đồng
    3. C.Một gia đình lưu giấy tờ cá nhân
    4. D.Lập trình viên thử nghiệm và đóng góp
  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ỏ.