Loại bỏ tủ hồ sơ: Tự triển khai Paperless-ngx trên Docker

Table of Contents

Vấn đề mang tên “Núi giấy tờ”

Các hệ thống lưu trữ hồ sơ vật lý chính là nơi năng suất làm việc bị triệt tiêu. Hầu hết chúng ta dành nhiều năm để tích trữ giấy khai sinh, tờ khai thuế và giấy bảo hành thiết bị, để rồi nhận ra rằng việc tìm một tài liệu cụ thể từ năm 2019 giống như một cuộc khai quật khảo cổ kéo dài 30 phút trong những thư mục bụi bặm. Với những ai đang vận hành HomeLab, công việc thủ công như quét tệp PDF, đổi tên thành ‘Hoa_don_dien_March.pdf’ và kéo nó vào một thư mục là một quy trình sớm muộn gì cũng thất bại vì sự lười biếng của con người.

Tôi đã chạm ngưỡng chịu đựng vào năm ngoái khi thợ sửa máy rửa bát hỏi xin thẻ bảo hành mà tôi biết chắc mình có nhưng không thể tìm thấy. Một giờ tìm kiếm trong bực bội đó đã thôi thúc tôi tìm kiếm một giải pháp không chỉ để lưu trữ tệp mà còn thực sự hiểu được chúng. Paperless-ngx là phiên bản kế nhiệm của dự án Paperless gốc. Nó đóng vai trò như một bộ não kỹ thuật số cho tài liệu của bạn, sử dụng OCR (Nhận dạng ký tự quang học) để lập chỉ mục mọi từ ngữ và tự động gắn thẻ các tệp dựa trên nội dung của chúng.

Kể từ khi chuyển kho lưu trữ sang hệ thống này, tôi đã xử lý hơn 1.200 tài liệu. Đống giấy tờ vật lý của tôi giờ đây gần như không còn nữa. Mọi hồ sơ tôi sở hữu đều có thể tìm kiếm được thông qua một giao diện web đơn giản, mang lại cảm giác nhanh chóng như tìm kiếm trên Google.

Cách hệ thống xử lý dữ liệu của bạn

Paperless-ngx không phải là một ứng dụng nguyên khối duy nhất. Nó là một bộ dịch vụ phối hợp hoạt động cùng nhau trong Docker để xử lý các tác vụ nặng nề trong việc xử lý tài liệu.

Webserver: Phần lõi dựa trên Django phục vụ giao diện người dùng (UI) và quản lý logic.
Thư mục tiêu thụ (Consumption Folder): Đây là thư mục “ma thuật”. Chỉ cần thả một tệp vào đây, hệ thống sẽ ngay lập tức bắt đầu xử lý.
Redis: Đóng vai trò là trình quản lý tác vụ. Nếu bạn đổ 50 tệp PDF vào hệ thống cùng lúc, Redis đảm bảo chúng được xếp hàng và xử lý lần lượt mà không làm treo CPU.
PostgreSQL: Mặc dù ứng dụng hỗ trợ SQLite, tôi khuyên dùng Postgres để có sự ổn định lâu dài. Nó xử lý các chỉ mục lớn tốt hơn nhiều khi thư viện của bạn phát triển.
Tesseract OCR: Công cụ “đọc” hình ảnh của bạn. Nó có thể biến một bức ảnh chụp hóa đơn mờ nhạt từ điện thoại thành văn bản có thể tìm kiếm đầy đủ trong khoảng 5 đến 10 giây.

Chuẩn bị môi trường

Bạn sẽ cần một máy tính đã cài đặt Docker và Docker Compose. Tôi khuyên bạn nên tạo một thư mục riêng biệt để dữ liệu có tính di động và dễ dàng sao lưu. Tôi thường ánh xạ mọi thứ dưới ~/homelab/paperless để giữ nó tách biệt với phần còn lại của hệ thống.

Bắt đầu bằng cách tạo cấu trúc thư mục:

mkdir -p ~/homelab/paperless/{config,data,db,consume,export}

Thư mục consume là điểm đầu vào của bạn. Cho dù bạn sử dụng máy quét mạng hay ứng dụng điện thoại, đây là nơi các tệp thô sẽ nằm trước khi chúng được đưa vào cơ sở dữ liệu. Thư mục export sẽ để trống cho đến khi bạn chạy lệnh sao lưu.

Cấu hình Docker Compose

Triển khai qua docker-compose.yml là phương pháp tiêu chuẩn. Tệp này liên kết ứng dụng web, cơ sở dữ liệu và trình môi giới (broker) thành một đơn vị chức năng duy nhất. Tôi đã tối ưu hóa cấu hình này để ngăn xung đột cổng và đảm bảo công cụ OCR biết ngôn ngữ nào cần ưu tiên.

version: "3.9"
services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: docker.io/library/postgres:15
    restart: unless-stopped
    volumes:
      - ./db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: mat_khau_bao_mat_cua_ban

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8010:8000"
    volumes:
      - ./config:/usr/src/paperless/data
      - ./data:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: mat_khau_bao_mat_cua_ban
      PAPERLESS_OCR_LANGUAGES: eng vie
      PAPERLESS_TIME_ZONE: Asia/Ho_Chi_Minh
      USER_ID: 1000
      GROUP_ID: 1000

Lưu ý biến PAPERLESS_OCR_LANGUAGES. Nếu bạn có tài liệu bằng cả tiếng Anh và tiếng Việt, việc liệt kê cả hai sẽ đảm bảo công cụ Tesseract sử dụng đúng bộ ký tự. Tôi cũng đã ánh xạ cổng nội bộ 8000 sang 8010 trên máy chủ để tránh xung đột với các dịch vụ web khác mà bạn có thể đang chạy.

Khởi chạy Instance

Sau khi đã lưu cấu hình, hãy tải các hình ảnh (images) và khởi chạy các container ở chế độ chạy ngầm (detached mode):

docker compose up -d

Các container hiện đang chạy, nhưng bạn chưa thể đăng nhập ngay. Bạn cần tạo một tài khoản quản trị (admin) bằng cách thực thi một lệnh trực tiếp bên trong container webserver đang chạy:

docker compose exec webserver python3 manage.py createsuperuser

Khi bạn đã thiết lập thông tin đăng nhập, hãy mở trình duyệt và truy cập http://your-server-ip:8010. Bạn đã chính thức sẵn sàng để bắt đầu số hóa.

Tự động hóa quy trình làm việc

Thiết lập phần mềm chỉ là một nửa chặng đường. Phép màu thực sự xảy ra khi bạn loại bỏ được các rào cản thao tác. Sau sáu tháng sử dụng, tôi nhận thấy rằng Thuật toán khớp (Matching Algorithms) là bí mật để có một kho lưu trữ gọn gàng. Các quy tắc này hướng dẫn Paperless-ngx cách phân loại tệp mà không cần sự can thiệp của bạn.

Ví dụ: Tôi đã tạo một thẻ ‘Tiện ích’ (Utility) với quy tắc khớp tìm kiếm các từ ‘Công ty điện lực’ hoặc ‘Kilowatt’. Giờ đây, khi tôi thả một tệp PDF từ công ty điện lực vào thư mục, hệ thống sẽ tự động gắn thẻ, chỉ định nó vào loại tài liệu ‘Hóa đơn hàng tháng’ và đổi tên tệp bằng ngày tháng tìm thấy trong văn bản. Không cần nhập liệu thủ công.

Để quy trình này thực sự liền mạch, hãy sử dụng một ứng dụng di động như Microsoft Lens. Cấu hình ứng dụng để lưu các bản quét trực tiếp vào một thư mục trên điện thoại được đồng bộ hóa với máy chủ của bạn qua Syncthing. Điều này tạo ra một quy trình ‘một chạm’ từ hóa đơn vật lý đến một bản ghi kỹ thuật số được lập chỉ mục đầy đủ.

Sao lưu đáng tin cậy

Vì hệ thống này nắm giữ các giấy tờ quan trọng trong cuộc sống của bạn, việc mất dữ liệu là điều không thể chấp nhận. Đừng chỉ sao lưu các Docker volumes. Hãy sử dụng công cụ xuất tích hợp để tạo một bản sao “cứng” cho thư viện của bạn. Tôi chạy một tác vụ cron hàng tuần để thực thi lệnh sau:

docker compose exec webserver document_exporter ../export

Lệnh này xuất mọi tài liệu cùng với một tệp JSON chứa tất cả siêu dữ liệu (metadata). Nếu thiết lập Docker của bạn gặp sự cố, bạn vẫn có một thư mục các tệp PDF được sắp xếp hoàn hảo mà bất kỳ máy tính nào cũng có thể đọc được.

Lời kết

Chuyển từ một “núi giấy tờ” vật lý sang một kho lưu trữ kỹ thuật số có thể tìm kiếm được là một trong những dự án HomeLab xứng đáng nhất mà bạn có thể thực hiện. Nó chuyển đổi máy chủ của bạn từ một món đồ chơi sở thích thành một phần hạ tầng thiết yếu trong gia đình. Paperless-ngx cực kỳ ổn định và gần như không cần bảo trì sau khi các quy tắc khớp đã được thiết lập. Nếu bạn mệt mỏi với việc thất lạc các hồ sơ quan trọng, hãy triển khai nó ngay hôm nay và không bao giờ phải lục lọi trong những thư mục bụi bặm nữa.