نصب FileBrowser Quantum روی VPS ایران: ساخت پنل مدیریت فایل تحت وب با Docker و HTTPS

اگر روی سرور مجازی ایران خود فایل‌های پروژه، بکاپ، ویدئو یا اسناد کاری نگهداری می‌کنید، مدیریت آن‌ها از طریق SSH و دستورات خط فرمان همیشه کارآمد نیست. FileBrowser Quantum یک فایل‌منیجر تحت وب است که به شما اجازه می‌دهد بدون نصب نرم‌افزار اضافی، فایل‌های VPS را از داخل مرورگر آپلود، دانلود، جابه‌جا و مدیریت کنید . در این راهنما، نصب و راه‌اندازی این پنل را با Docker روی Ubuntu بررسی می‌کنیم، یک فضای ذخیره‌سازی اختصاصی می‌سازیم و در ادامه اتصال دامنه، HTTPS و رفع خطاهای رایج را قدم‌به‌قدم پیش می‌بریم.

FileBrowser Quantum دقیقاً چیست و چه تفاوتی با نسخه قدیمی دارد؟

FileBrowser Quantum یک فورک (انشعاب) از پروژه شناخته‌شده FileBrowser است که با بازنویسی قابل‌توجه، امکانات پیشرفته‌تری را در قالبی سبک ارائه می‌کند . تفاوت اصلی در معماری نسخه 2.0.0 است: دیتابیس از حالت key/value به SQLite ساختاریافته تغییر کرده و لایه مدیریت state اضافه شده که سرعت و قابلیت گزارش‌گیری را بهبود می‌دهد .

از قابلیت‌های شاخص این نسخه می‌توان به جستجوی لحظه‌ای مبتنی بر ایندکس، پشتیبانی از چند منبع فایل (چند مسیر مختلف در یک پنل)، احراز هویت دو مرحله‌ای، پیش‌نمایش فایل‌های Office و ویدئو، و کنترل دسترسی در سطح دایرکتوری اشاره کرد . برخلاف نسخه قدیمی، دستورات Shell به‌طور کامل حذف شده‌اند تا سطح امنیت بالاتر برود .

چرا نصب FileBrowser Quantum روی VPS ایران منطقی است؟

فرض کنید یک سرور مجازی ایران دارید و می‌خواهید فایل‌های پروژه، بکاپ یا رسانه‌های خود را بدون SSH مدیریت کنید. ابزارهایی مثل SFTP و SCP برای انتقال‌های بزرگ عالی هستند، اما وقتی می‌خواهید یک فایل را سریع باز کنید، تغییر نام بدهید یا ببینید چه چیزی روی سرور هست، هر بار باز کردن یک کلاینت FTP اضافی است.

FileBrowser Quantum یک رابط گرافیکی سبک در اختیار شما قرار می‌دهد که از هر دستگاهی با مرورگر قابل دسترسی است. نیازی به نصب اپلیکیشن روی کامپیوتر یا موبایل نیست. داده‌ها هم روی دیسک خودتان می‌مانند و از سرویس‌های ابری شخص ثالث عبور نمی‌کنند.

پیش‌نیازهای نصب روی سرور مجازی

قبل از شروع، مطمئن شوید VPS شما شرایط زیر را دارد:

🔹 سیستم‌عامل: Ubuntu 22.04 یا 24.04 (سایر توزیع‌های لینوکس هم قابل استفاده‌اند اما دستورات ممکن است کمی متفاوت باشند)

🔹 CPU: 1 تا 2 هسته کافی است

🔹 RAM: حداقل 256 مگابایت برای کارکرد پایه؛ اگر ایندکس فایل‌های زیاد دارید، 512 مگابایت یا بیشتر توصیه می‌شود

🔹 فضای دیسک: حداقل 500 مگابایت برای ایمیج و دیتابیس، به‌علاوه فضایی که برای فایل‌های خودتان نیاز دارید

🔹 Docker و Docker Compose: اگر نصب نیستند، در ادامه روش نصب آمده است

مرحله اول: اتصال به VPS و به‌روزرسانی سیستم

با SSH به سرور خود متصل شوید:

ssh root@SERVER_IP

سپس پکیج‌های سیستم را به‌روز کنید:

apt update
apt upgrade -y

مرحله دوم: نصب Docker

اگر Docker روی سرور نصب نیست، با دستور رسمی آن را نصب کنید:

curl -fsSL https://get.docker.com | sh

وضعیت سرویس را بررسی کنید:

systemctl status docker
docker --version
docker compose version

مرحله سوم: ساخت ساختار پوشه‌ها

برای اینکه تنظیمات و دیتابیس FileBrowser بعد از حذف یا ری‌استارت کانتینر از بین نروند، باید از volume استفاده کنیم. یک ساختار پوشه در مسیر /opt/filebrowser بسازید:

mkdir -p /opt/filebrowser
cd /opt/filebrowser
mkdir -p data files

ساختار نهایی به این شکل خواهد بود:

/opt/filebrowser/
├── data/    ← تنظیمات، دیتابیس و کش
└── files/   ← فایل‌هایی که مدیریت می‌کنید

پوشه files فضایی است که می‌خواهید از طریق پنل مدیریت کنید. پوشه data هم اطلاعات داخلی FileBrowser را نگه می‌دارد. در مستندات رسمی نسخه 2.0.0 نیز mount کردن /home/filebrowser/data برای حفظ دیتابیس توصیه شده است .

مرحله چهارم: ساخت فایل Docker Compose

یک فایل compose.yaml در مسیر /opt/filebrowser بسازید:

nano compose.yaml

محتوای زیر را داخل فایل قرار دهید:

services:
  filebrowser:
    image: gtstef/filebrowser:beta
    container_name: filebrowser
    ports:
      - "8900:80"
    volumes:
      - ./files:/files
      - ./data:/home/filebrowser/data
    restart: unless-stopped

در این تنظیمات:

🔹 ./files:/files یعنی پوشه files روی VPS به مسیر /files داخل کانتینر وصل می‌شود.

🔹 ./data:/home/filebrowser/data باعث می‌شود دیتابیس و تنظیمات روی دیسک VPS باقی بمانند.

🔹 پورت 8900 روی هاست به پورت 80 کانتینر متصل می‌شود. می‌توانید عدد سمت چپ را تغییر دهید.

مرحله پنجم: اجرای FileBrowser Quantum

حالا کانتینر را اجرا کنید:

docker compose up -d

وضعیت را بررسی کنید:

docker compose ps

اگر همه‌چیز درست باشد، کانتینر در وضعیت Up خواهد بود. برای مشاهده لاگ‌ها:

docker compose logs -f

مرحله ششم: ورود به پنل و باز کردن پورت

مرورگر را باز کنید و آدرس زیر را وارد کنید:

http://SERVER_IP:8900

اگر پنل باز نشد، احتمالاً فایروال پورت را بسته است. اگر از UFW استفاده می‌کنید:

ufw status
ufw allow 8900/tcp
ufw reload

برای تست اتصال volume، یک فایل آزمایشی در پوشه files بسازید:

echo "FileBrowser Test" > /opt/filebrowser/files/test.txt

اگر فایل test.txt در پنل نمایش داده شد، volume به‌درستی متصل شده است.

مدیریت فایل‌ها و ساخت فضای اختصاصی برای کاربران

بعد از ورود به پنل، می‌توانید تمام عملیات فایل‌منیجر را از مرورگر انجام دهید:

🔹 آپلود فایل از کامپیوتر روی سرور

🔹 دانلود فایل‌های موجود روی VPS

🔹 ایجاد پوشه جدید برای دسته‌بندی فایل‌ها

🔹 تغییر نام، جابه‌جایی و حذف فایل‌ها

🔹 پیش‌نمایش فایل‌های تصویری، ویدئویی و Office

یکی از قابلیت‌های مهم Quantum، پشتیبانی از چند منبع است. می‌توانید در فایل config.yaml چندین مسیر مختلف را تعریف کنید تا همه در یک پنل نمایش داده شوند . برای مثال:

server:
  sources:
    - path: "/files"
      name: "Home"
      config:
        defaultEnabled: true
    - path: "/media"
      name: "Media Library"
      config:
        defaultEnabled: true

همچنین می‌توانید برای هر کاربر دایرکتوری اختصاصی بسازید. با تنظیم createUserDir: true، هر کاربر فقط فایل‌های پوشه خودش را می‌بیند .

اتصال دامنه و فعال‌سازی HTTPS

استفاده از IP و پورت برای تست مناسب است، اما برای دسترسی عمومی باید یک دامنه یا ساب‌دامین تنظیم کنید. در پنل DNS دامنه، یک رکورد A بسازید:

Type: A
Name: files
Value: SERVER_IP

سپس Nginx را نصب کنید:

apt update
apt install nginx -y

یک فایل تنظیمات برای Reverse Proxy بسازید:

nano /etc/nginx/sites-available/filebrowser

محتوای زیر را قرار دهید (به‌جای files.example.com دامنه خودتان را بنویسید):

server {
    listen 80;
    server_name files.example.com;
    client_max_body_size 5G;
    location / {
        proxy_pass http://127.0.0.1:8900;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

سایت را فعال کنید و تنظیمات را بررسی کنید:

ln -s /etc/nginx/sites-available/filebrowser /etc/nginx/sites-enabled/filebrowser
nginx -t
systemctl reload nginx

برای فعال‌سازی SSL با Let’s Encrypt:

apt install certbot python3-certbot-nginx -y
certbot --nginx -d files.example.com

بعد از موفقیت، آدرس پنل به این شکل خواهد بود:

https://files.example.com

نکته مهم: بعد از راه‌اندازی Nginx، بهتر است پورت 8900 را مستقیماً روی اینترنت باز نگذارید. در Docker Compose به‌جای “8900:80” از این تنظیم استفاده کنید تا فقط Nginx روی خود سرور به آن دسترسی داشته باشد:

ports:
  - "127.0.0.1:8900:80"

رفع خطاهای رایج FileBrowser Quantum

پنل باز نمی‌شود

ابتدا وضعیت کانتینر را بررسی کنید:

docker compose ps
docker compose logs --tail=100

و بررسی کنید پورت در حال Listen باشد:

ss -tulpn | grep 8900

خطای Permission هنگام آپلود

اگر کانتینر به فایل‌های Host دسترسی ندارد، مالکیت پوشه را بررسی کنید:

ls -la /opt/filebrowser/files

اگر مشکل Permission دیدید، مالکیت پوشه را متناسب با UID/GID مورد استفاده کانتینر تنظیم کنید. از دادن دسترسی باز مثل chmod -R 777 بدون بررسی خودداری کنید.

خطای 502 Bad Gateway در Nginx

اگر Nginx خطای 502 می‌دهد، بررسی کنید کانتینر فعال است و FileBrowser پاسخ می‌دهد:

docker compose ps
curl http://127.0.0.1:8900

اگر FileBrowser پاسخ داد اما Nginx همچنان 502 می‌دهد، تنظیمات Reverse Proxy را بررسی کنید.

از بین رفتن اطلاعات بعد از Restart

مطمئن شوید volume مربوط به /home/filebrowser/data در Compose به یک مسیر دائمی روی Host متصل است. در نمونه ما این کار با ./data:/home/filebrowser/data انجام شده است .

نکته مهم درباره ارتقا از نسخه قدیمی

اگر از نسخه‌های قدیمی FileBrowser استفاده می‌کردید، قبل از تغییر مستقیم به نسخه 2.0.0 حتماً مستندات Migration را بررسی کنید. دیتابیس قدیمی database.db با دیتابیس جدید filebrowser.sqlite جایگزین شده و تغییر مستقیم Image بدون مهاجرت می‌تواند باعث مشکل در اطلاعات قبلی شود .

نکات امنیتی برای استفاده عمومی

اگر FileBrowser را روی اینترنت عمومی قرار می‌دهید، این موارد را جدی بگیرید:

🔹 از HTTPS استفاده کنید — ارتباط کاربر و پنل باید رمزنگاری شود.

🔹 رمز عبور قوی انتخاب کنید — از رمزهای ساده مثل 123456 یا admin بپرهیزید.

🔹 دسترسی کاربران را محدود کنید — هر کاربر فقط به فایل‌هایی دسترسی داشته باشد که نیاز دارد.

🔹 پورت داخلی را عمومی نکنید — از Nginx به‌عنوان واسط استفاده کنید.

🔹 سیستم و Docker را به‌روز نگه دارید — نسخه‌های جدید شامل رفع باگ و بهبود امنیتی هستند.

به‌روزرسانی FileBrowser Quantum

قبل از هر به‌روزرسانی از اطلاعات مهم بکاپ بگیرید. سپس:

docker compose pull
docker compose down
docker compose up -d

اگر volume دائمی داشته باشید، دیتابیس و تنظیمات با حذف کانتینر از بین نمی‌روند .