File Browser на сервере: частые ошибки и решения

MAATRIX

File Browser — удобная штука: лёгкий веб-интерфейс, через который можно загружать, редактировать и шарить файлы на сервере без FTP-клиента и без SSH-сессии для каждой мелочи. Но именно из-за этой лёгкости с ним чаще всего возникают одни и те же проблемы: то интерфейс не открывается, то файлы «зависают» на загрузке, то права доступа путаются между контейнером и хостом. Разберём эти ошибки по порядку — с командами и конфигами, которые реально помогают.

Контейнер запущен, а интерфейс не открывается

Самая частая жалоба: docker ps показывает контейнер как Up, но браузер отдаёт «не удаётся подключиться» или ERR_CONNECTION_REFUSED. Причины почти всегда сводятся к трём вещам.

Во-первых, порт. File Browser по умолчанию слушает 80-й порт *внутри* контейнера, а наружу вы должны пробросить его сами:

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - /srv/files:/srv
      - ./filebrowser.db:/database/filebrowser.db
      - ./settings.json:/.filebrowser.json

Если в ports стоит 80:80, а на сервере уже занят 80-й порт (nginx, Apache, другой контейнер) — File Browser либо не стартует, либо стартует, но конфликтует, и docker молча биндит не то, что вы ожидаете. Проверить занятость порта:

sudo ss -tulpn | grep :80

Во-вторых, firewall. Если на сервере включён ufw, порт нужно открыть явно:

sudo ufw allow 8080/tcp
sudo ufw status

Про настройку самого файрвола и типичные грабли с ним есть отдельный разбор — фаервол UFW на сервере: частые ошибки и решения. Если сервер арендован в облаке — не забудьте, что кроме UFW на хосте может быть ещё Security Group на уровне провайдера, и правило нужно продублировать там.

В-третьих, сам процесс мог упасть сразу после старта — это частая ситуация, если конфиг settings.json битый или база данных повреждена. Смотрим логи:

docker logs filebrowser --tail 50

Если там panic: database is locked или unexpected EOF — база filebrowser.db повреждена, проще всего пересоздать её (с потерей пользователей и настроек, но не файлов):

docker compose down
rm ./filebrowser.db
docker compose up -d
docker exec filebrowser filebrowser users add admin ВАШ_ПАРОЛЬ --perm.admin

502 Bad Gateway за reverse-proxy

Если File Browser стоит не напрямую, а за nginx или Traefik (обычный вариант, когда нужен нормальный домен и SSL), самая частая ошибка — 502.

Для nginx проверьте, что proxy_pass указывает на правильный порт контейнера и что заголовки для WebSocket проброшены — File Browser использует WebSocket для живого обновления списка файлов при загрузке:

server {
    listen 443 ssl;
    server_name files.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Без строк proxy_http_version 1.1 и Upgrade/Connection интерфейс откроется, но список файлов не будет обновляться живьём, а иногда и загрузка файлов будет обрываться на середине с невнятной ошибкой в консоли браузера.

Если используете Traefik, аналогичная грабля — не хватает провайдера для WebSocket в самом Traefik по умолчанию нет проблем, но нужно убедиться, что лейблы контейнера правильно указывают порт:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.filebrowser.rule=Host(`files.example.com`)"
  - "traefik.http.routers.filebrowser.tls.certresolver=letsencrypt"
  - "traefik.http.services.filebrowser.loadbalancer.server.port=80"

Если у вас чаще возникают проблемы именно с Traefik как таковым — есть отдельная статья про Traefik на сервере: частые ошибки и решения.

Файлы загружаются, но недоступны для редактирования — путаница с правами

Это, пожалуй, самая коварная категория ошибок, потому что интерфейс не показывает явной причины — просто при попытке сохранить файл вылетает «Failed to save» или файл появляется, но открыть его на редактирование нельзя.

Корень проблемы — несовпадение UID/GID между процессом внутри контейнера и владельцем директории на хосте. По умолчанию образ filebrowser/filebrowser запускает процесс от root (UID 0), и если смонтированная директория /srv/files на хосте принадлежит другому пользователю с ограниченными правами, могут возникать неожиданные конфликты — особенно если вы параллельно редактируете эти же файлы по SSH от имени обычного пользователя.

Проверить текущего владельца:

ls -la /srv/files
stat -c '%U:%G %a' /srv/files

Если директория принадлежит, например, www-data:www-data с правами 750, а контейнер пишет от root, — по факту всё будет работать (root может всё), но новые файлы будут создаваться с владельцем root, и тогда уже другие сервисы (тот же nginx, если он раздаёт эти файлы статикой) не смогут их прочитать. Практичное решение — явно выставить PUID/PGID через переменные окружения, если используете образ на базе LinuxServer.io (lscr.io/linuxserver/filebrowser), либо просто привести владельца директории в соответствие с тем, кто реально должен её читать:

sudo chown -R www-data:www-data /srv/files
sudo chmod -R 750 /srv/files

После смены владельца контейнер стоит перезапустить:

docker compose restart filebrowser

Если вы только разворачиваете сервер с нуля и права ещё не устаканились — полезно заранее понимать логику chmod/chown, прежде чем городить костыли в самом File Browser.

Пароль администратора потерян или не подходит

Бывает, что после переустановки контейнера или переноса на новый сервер логин-пароль, которые вы помните, перестают работать. Проверьте сначала, что база данных вообще та же самая, а не пересозданная заново (см. первый раздел) — при новой базе всегда генерируется дефолтный пользователь admin/admin, о чём часто забывают.

Если база на месте, а пароль просто забыт — сбросить его можно прямо из контейнера, без веб-интерфейса:

docker exec -it filebrowser filebrowser users ls
docker exec -it filebrowser filebrowser users update admin --password НовыйПароль

Если пользователя с именем admin не существует вовсе (иногда при первой инициализации создаётся пользователь с другим логином из settings.json), сначала посмотрите список:

docker exec -it filebrowser filebrowser users ls

и обновляйте именно то имя, которое там реально есть. Отдельно стоит сразу сменить дефолтный пароль на этапе первого запуска — оставленный admin/admin на публично доступном порту находят автоматизированные сканеры за считаные часы.

Загрузка больших файлов обрывается или зависает

File Browser сам по себе не имеет жёсткого лимита размера файла, но обрыв загрузки почти всегда происходит на уровне reverse-proxy или самого docker-хранилища.

Для nginx частая причина — дефолтный client_max_body_size в 1 МБ:

http {
    client_max_body_size 2048M;
}

Значение указывайте с запасом под ваши реальные файлы — если планируете загружать бэкапы по 10-20 ГБ через веб-интерфейс, это в принципе не лучший сценарий (лучше rsync или scp напрямую), но для файлов в пределах пары гигабайт правки лимита обычно достаточно.

Второй момент — таймауты. Если загрузка медленного файла (большой объём + не самый быстрый канал) превышает proxy_read_timeout и proxy_send_timeout, соединение разрывается на середине:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

И третье — банально место на диске. docker exec filebrowser df -h покажет, видит ли контейнер реальный объём свободного места на смонтированном томе; если используете overlay-хранилище без выделенного тома, легко упереться в лимиты самого диска ноды, особенно на бюджетных тарифах с небольшим SSD.

Медленная работа интерфейса при большом количестве файлов

Если в одной директории лежат десятки тысяч файлов (частый случай для медиатек или архивов логов), File Browser начинает заметно тормозить при построении списка — это не баг, а особенность того, как он индексирует содержимое директории при каждом обращении.

Практические варианты: разбить одну огромную папку на подпапки по датам или категориям — уже само по себе снижает время рендера списка в разы; для чисто «раздаточных» сценариев (когда файлы нужно только скачивать, без интерактивного управления) вынести их на отдельный statics-сервер на nginx, а File Browser оставить только для директорий, с которыми реально идёт активная работа.

Если ресурсов сервера в принципе не хватает — стоит проверить нагрузку в целом:

docker stats filebrowser
htop

Если узкое место — процессор или память самого VPS, а не логика File Browser, дальнейшая оптимизация конфига мало что даст: разумнее увеличить тариф.

File Browser доступен из интернета без пароля — риск, который легко пропустить

Отдельная категория «ошибок» — не техническая, а про безопасность. Если вы тестировали контейнер и временно отключали авторизацию (--noauth в CLI-аргументах или через settings.json), а потом забыли включить обратно, публично доступный File Browser с полным доступом к файловой системе — это открытая дверь на сервер.

Проверить, включена ли авторизация, проще всего просто открыв URL из приватного окна браузера без сохранённых кук — если сразу видна файловая структура без формы логина, авторизация выключена.

Если File Browser торчит наружу, есть смысл добавить Basic Auth на уровне nginx поверх встроенной авторизации (двойной барьер не помешает для чувствительных директорий) и ограничить доступ по IP через allow/deny, если сервисом пользуется только команда с известных адресов. Против перебора пароля помогает fail2ban с правилом на форму логина — общий подход к его настройке под конкретные сервисы описан в статье про fail2ban на сервере: частые ошибки и решения.

Если сервис нужен только вам лично, а не команде — иногда проще вообще не выставлять порт наружу и заходить через SSH-туннель:

ssh -L 8080:localhost:8080 user@your-server-ip

Тогда интерфейс будет доступен только на localhost:8080 вашей локальной машины, без единой открытой точки входа на сервере.

Частые вопросы