Posted inHomeLab

Triển khai FileBrowser trên Docker: Trình quản lý file qua Web siêu nhẹ cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Khi SSH và SMB bất lực lúc 2 giờ sáng

Đó là 2:15 sáng Chủ nhật. Bạn đang dùng Wi-Fi khách sạn với độ trễ (ping) lên tới 200ms thì nhận được cảnh báo: một file sao lưu 45GB trên node lưu trữ cần được kiểm tra khẩn cấp.

Bạn thử mở ứng dụng SFTP, nhưng tính năng NAT traversal trên router du lịch hoạt động chập chờn. Tiếp theo, bạn mount ổ đĩa SMB qua WireGuard, nhưng độ trễ cao khiến việc tải danh sách thư mục chậm đến mức gần như tê liệt. Các nền tảng đám mây hoàn chỉnh như Nextcloud có thể giải quyết được, nhưng PHP-FPM pool và Redis cache của chúng dễ dàng ngốn tới 2GB RAM chỉ để xem trước một file cấu hình.

Bạn không cần một bộ công cụ làm việc nhóm cồng kềnh chỉ để kiểm tra hay tải về một file log khẩn cấp. Thứ bạn cần là một trình quản lý file trên nền web chuyên dụng: khởi động dưới hai giây, chiếm chưa tới 25MB RAM khi chạy nền và vận hành mượt mà bên trong một micro-container. Đó chính là nơi FileBrowser tỏa sáng.

Vì sao FileBrowser phù hợp với hệ thống tối ưu tài nguyên

FileBrowser được viết bằng Go và đóng gói gọn gàng trong một Docker image nền Alpine với dung lượng dưới 40MB. Hiểu rõ cách công cụ này xử lý trạng thái dữ liệu sẽ giúp bạn tránh được các rắc rối về phân quyền sau này.

Kiến trúc không phụ thuộc (Zero-Dependency)

Các bộ ứng dụng cloud self-hosted thường đòi hỏi database ngoài (PostgreSQL hoặc MariaDB), Redis cache chạy nền và các container cron theo lịch. Ngược lại, FileBrowser chỉ cần đúng hai thành phần:

  • File thực thi Web Server: Một file binary Go đã biên dịch, tích hợp sẵn giao diện frontend Vue.js hỗ trợ kéo-thả để upload, phát trực tiếp audio/video và trình chỉnh sửa code tích hợp sẵn tính năng highlight cú pháp.
  • Cơ sở dữ liệu SQLite (filebrowser.db): Một database nhúng duy nhất dùng để lưu thông tin đăng nhập người dùng, phạm vi thư mục được truy cập, giao diện tùy chỉnh và các token chia sẻ.

Truy xuất trực tiếp hệ thống file (Filesystem Passthrough)

FileBrowser bỏ qua các lớp lưu trữ ảo và định dạng object độc quyền. Các thư mục bạn mount vào container sẽ ánh xạ trực tiếp tới ổ cứng của máy host, bất kể đó là ZFS dataset, unRAID share hay một phân vùng mount ext4 cục bộ. Nếu bạn đẩy một file ISO 10GB lên server qua rsync, FileBrowser sẽ hiển thị ngay lập tức mà không yêu cầu quét lại chỉ mục (index rebuild).

Hãy lưu ý đến quyền sở hữu file (file ownership) trong Unix. Nếu container của bạn chạy dưới quyền root (UID 0) trong khi thư mục media lại thuộc về một user thông thường (UID 1000), bất kỳ file nào tải lên qua giao diện web sẽ bị gắn quyền root. Điều này khiến các dịch vụ phía sau như Jellyfin hoặc các script backup tự động không thể truy cập được. Việc chỉ định rõ quyền người dùng khi cấu hình sẽ xử lý triệt để vấn đề này.

Từng bước triển khai với Docker

Dưới đây là cách thiết lập FileBrowser với cấu hình lưu trữ bền vững và phân quyền chuẩn xác bằng Docker Compose.

Bước 1: Chuẩn bị thư mục và khởi tạo cơ sở dữ liệu

Đầu tiên, tạo các thư mục chuyên dụng trên máy host để chứa cấu hình FileBrowser và dữ liệu lưu trữ:

mkdir -p /opt/filebrowser/config
mkdir -p /srv/storage

# Tạo file database rỗng trước khi khởi chạy Docker
touch /opt/filebrowser/config/filebrowser.db

# Gán quyền sở hữu cho user non-root của bạn (ví dụ: UID/GID 1000)
sudo chown -R 1000:1000 /opt/filebrowser /srv/storage

Việc tạo trước file filebrowser.db trước khi khởi chạy container là cực kỳ quan trọng. Nếu Docker mount một đường dẫn file chưa tồn tại, nó sẽ tự động tạo ra một thư mục rỗng cùng tên. Điều này sẽ khiến file binary Go gặp lỗi khi khởi động do không thể mở file SQLite.

Bước 2: Cấu hình file Compose

Tạo file docker-compose.yml bên trong /opt/filebrowser/:

version: "3.8"

services:
  filebrowser:
    image: filebrowser/filebrowser:v2.30.0
    container_name: filebrowser
    restart: unless-stopped
    user: "1000:1000"
    ports:
      - "8080:80"
    volumes:
      # Thư mục lưu trữ gốc chứa các file bạn muốn quản lý
      - /srv/storage:/srv
      # Database cấu hình SQLite để lưu trữ dữ liệu bền vững
      - /opt/filebrowser/config/filebrowser.db:/database/filebrowser.db
      # Cấu hình tùy chỉnh đè lên mặc định (không bắt buộc)
      - /opt/filebrowser/config/settings.json:/.filebrowser.json
    security_opt:
      - no-new-privileges:true

Bước 3: Khởi chạy và kiểm tra

Khởi chạy container chạy ngầm trong background:

cd /opt/filebrowser
docker compose up -d

Kiểm tra log của container để xác nhận database đã khởi tạo thành công mà không gặp lỗi phân quyền:

docker logs -f filebrowser

Bạn sẽ thấy log xác nhận tương tự như sau chỉ trong vòng một giây:

Listening on [::]:80
Using database: /database/filebrowser.db

Bước 4: Đăng nhập lần đầu và thiết lập bảo mật

Truy cập vào http://<your-server-ip>:8080 trên trình duyệt của bạn.

  1. Thông tin đăng nhập mặc định: Đăng nhập với username admin và password admin.
  2. Đổi mật khẩu Admin: Vào mục Settings > Profile Settings và đổi ngay mật khẩu quản trị mạnh hơn.
  3. Vô hiệu hóa lệnh Shell: Trong Settings > Global Settings, hãy đảm bảo tính năng thực thi lệnh (command execution) vẫn bị tắt, trừ khi bạn thực sự cần kích hoạt lệnh shell phía server từ giao diện web.
  4. Tạo tài khoản phân quyền: Truy cập Settings > User Management để thêm các tài khoản bị giới hạn. Bạn có thể khóa một tài khoản chỉ được truy cập vào thư mục con như /srv/backups/work và thu hồi quyền xóa file của họ.

Bước 5: Reset mật khẩu khẩn cấp qua CLI

Nếu bạn lỡ mất quyền truy cập vào tài khoản admin, bạn không cần phải xóa database hay thiết lập lại từ đầu. Hãy đặt lại mật khẩu trực tiếp bên trong container đang chạy bằng chính công cụ dòng lệnh của FileBrowser:

docker exec -it filebrowser /filebrowser users update admin --password "NewStrongPass2026!" --database /database/filebrowser.db

Tổng kết

Khi sự cố lưu trữ xảy ra giữa đêm, những công cụ đơn giản chính là chìa khóa giúp việc khôi phục diễn ra nhanh chóng và đáng tin cậy. Chạy FileBrowser trên Docker mang đến một cổng quản lý file nền web gần như không tiêu tốn tài nguyên hệ thống, tránh phình to database và tương tác trực tiếp với các ổ đĩa lưu trữ gốc của bạn.

Share:
Tags: