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

MAATRIX

Miniflux — один из немногих RSS-ридеров, который честно делает одну вещь и делает её хорошо: собирает фиды и отдаёт их в чистом, быстром интерфейсе без обвеса. Но именно из-за минимализма первая установка на свой сервер часто превращается в серию непонятных ошибок — сервис не стартует, база не подключается, за reverse proxy всё редиректит не туда. Разберём, что на самом деле происходит в каждом из типичных случаев и как это чинить, а не гадать.

Установка: бинарник или Docker, и на чём спотыкаются чаще всего

Miniflux написан на Go и распространяется как один статический бинарник, плюс официальный образ miniflux/miniflux для Docker. Никаких PHP, Node.js или отдельного веб-сервера ему не нужно — только PostgreSQL. Это плюс для стабильности, но и источник первой путаницы: люди по привычке ищут www-каталог, конфиг .env рядом с исходниками или права на запись в директорию установки — а всё это здесь не нужно.

Установка бинарником на Ubuntu 24.04 выглядит так:

curl -L https://github.com/miniflux/v2/releases/latest/download/miniflux-linux-amd64 -o /usr/bin/miniflux
chmod +x /usr/bin/miniflux
useradd -r -s /usr/sbin/nologin miniflux

Конфигурация — либо через переменные окружения, либо через файл /etc/miniflux.conf, который бинарник читает флагом -c. Смешивать оба способа можно, но если один и тот же параметр задан и в файле, и в окружении systemd-юнита — побеждает окружение, и это частая причина «я поменял конфиг, а поведение не изменилось»: правили не тот источник.

Юнит systemd:

[Unit]
Description=Miniflux
After=postgresql.service

[Service]
User=miniflux
EnvironmentFile=/etc/miniflux.conf
ExecStart=/usr/bin/miniflux -c /etc/miniflux.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

Типичная ошибка на этом шаге — сервис падает сразу после старта без внятного сообщения в systemctl status. Смотрите полный лог, а не сокращённый вывод статуса:

journalctl -u miniflux -n 100 --no-pager

В девяти случаях из десяти там будет либо отказ подключения к базе, либо запрет на бинд порта (Miniflux по умолчанию слушает 0.0.0.0:8080, и если порт занят другим сервисом, процесс просто завершится с exit-кодом).

PostgreSQL: миграции, права и SSL-режим

Miniflux работает только с PostgreSQL, версии MySQL или SQLite не поддерживаются — и это осознанный выбор разработчика ради простоты кода, а не недоработка. Минимальная подготовка базы:

CREATE USER miniflux WITH PASSWORD 'сложный_пароль';
CREATE DATABASE miniflux OWNER miniflux;

Строка подключения задаётся через DATABASE_URL:

DATABASE_URL=postgres://miniflux:сложный_пароль@localhost/miniflux?sslmode=disable

Ошибка unable to connect to database почти всегда сводится к одному из трёх:

• PostgreSQL слушает только localhost, а вы указали IP контейнера или другого хоста — проверьте listen_addresses в postgresql.conf.
• В pg_hba.conf для пользователя miniflux не прописан метод md5/scram-sha-256, стоит peer — он работает только для локальных unix-сокетов и системных пользователей с тем же именем.
• Если PostgreSQL требует SSL, а в строке подключения sslmode=disable — соединение отклоняется. В Docker-связке через отдельную сеть compose SSL обычно не нужен, disable подходит; для внешней базы правильнее require или verify-full.

Отдельная ошибка первого запуска — миграции не применились, и приложение падает на relation "users" does not exist. Миграции не выполняются автоматически при каждом старте, их нужно явно запустить один раз:

miniflux -c /etc/miniflux.conf -migrate

Или через переменную RUN_MIGRATIONS=1 при первом старте контейнера. Частая накладка — запускать -migrate при каждом деплое из CI: это безопасно (миграции идемпотентны), но если параллельно с этим кто-то руками правил схему базы, можно словить duplicate key value violates unique constraint — тогда придётся смотреть, какая миграция уже была применена вручную, и либо откатывать правки, либо помечать миграцию как выполненную в таблице schema_version.

Reverse proxy: nginx и Caddy перед Miniflux

Сам Miniflux не занимается TLS-терминацией — это задача nginx или Caddy перед ним. Рабочий конфиг nginx:

server {
    listen 443 ssl http2;
    server_name rss.example.com;

    ssl_certificate /etc/letsencrypt/live/rss.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/rss.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Самая частая жалоба на этом этапе — «после логина бросает на страницу с ошибкой» или ссылки в интерфейсе ведут на http:// вместо https://. Причина — Miniflux формирует абсолютные URL на основе заголовка X-Forwarded-Proto, и если nginx его не передаёт (или передаёт статически http вместо $scheme), приложение считает, что работает по HTTP, и генерирует смешанный контент. Проверяется быстро:

curl -I -H "X-Forwarded-Proto: https" http://127.0.0.1:8080/

Если базовый путь установки не корень домена (например, /rss/), обязательно задайте BASE_URL:

BASE_URL=https://example.com/rss/

Без этого статические файлы (CSS, иконки) будут запрашиваться от корня и не найдутся — визуально это выглядит как «интерфейс без стилей».

Для Caddy всё проще из коробки, он сам подставляет заголовки:

rss.example.com {
    reverse_proxy 127.0.0.1:8080
}

Если у вас уже есть Caddy на сервере для других сайтов и вы выбираете между ним и nginx для новых проектов — сравнение есть в статье Caddy или nginx: что выбрать для сервера.

Загрузка фидов: 403, таймауты и «feed not found»

Это категория ошибок, которая пугает новичков больше всего, потому что кажется, будто сломан сам Miniflux — а на самом деле проблема почти всегда на стороне источника фида или сети.

• 403 Forbidden при обновлении фида. Некоторые сайты блокируют дефолтный User-Agent Miniflux или любые запросы без cookie-сессии. Можно задать свой User-Agent глобально через HTTP_CLIENT_USER_AGENT или индивидуально для фида в его настройках в интерфейсе.
• Таймаут на медленных источниках. По умолчанию HTTP_CLIENT_TIMEOUT невелик (несколько секунд), и тяжёлые фиды с большим числом изображений в описании не успевают отдаться. Поднимите таймаут в конфиге, но не делайте его чрезмерным — иначе один зависший источник будет держать воркер и замедлять обновление остальных фидов.
• Сервер не может достучаться до внешнего сайта вовсе. Проверьте DNS и исходящий трафик с самого хоста:

  curl -A "Miniflux/2" -sI https://example.com/feed.xml

Если сервер географически удалён и целевой ресурс режет по региону — здесь помогает только смена локации сервера или прокси на уровне HTTP_CLIENT_PROXY.

• OPML-импорт зависает или обрывается на большом файле. Импорт идёт синхронно через веб-интерфейс, и на списке из нескольких сотен фидов запрос может упереться в таймаут самого reverse proxy (nginx по умолчанию рвёт долгие запросы через 60 секунд). Увеличьте proxy_read_timeout в nginx на время импорта или разбейте OPML на части.

Число одновременных воркеров и частоту опроса регулируют WORKER_POOL_SIZE и POLLING_FREQUENCY — на слабом VPS с сотнями фидов стоит не задирать пул воркеров, иначе PostgreSQL и сеть будут упираться в одновременные запросы, а не в реальную нехватку CPU.

Учётные записи, вход и Fever/Google Reader API

Первый администратор создаётся флагом при старте или переменными окружения:

miniflux -c /etc/miniflux.conf -create-admin

Либо в Docker — CREATE_ADMIN=1, ADMIN_USERNAME, ADMIN_PASSWORD при первом запуске контейнера. Если забыли пароль и веб-интерфейс недоступен, сбросить его можно тем же бинарником напрямую в базу, без обращения к API:

miniflux -c /etc/miniflux.conf -reset-password

Отдельно стоит сказать про мобильные клиенты — Miniflux совместим с Fever API и Google Reader API, поэтому его можно подключить к Reeder, Fiery Feeds, NetNewsWire и подобным приложениям. Проблема, с которой сталкиваются почти все: клиент пишет «неверный логин или пароль», хотя в вебе всё работает. Для Fever API нужен отдельный ключ доступа (API key), который включается и генерируется в настройках профиля пользователя внутри Miniflux — обычным паролем от веб-интерфейса эти API не пользуются. Для Google Reader API совместимости логин и пароль совпадают с учёткой в Miniflux, но нужно явно включить эту опцию в настройках профиля, она выключена по умолчанию.

Если вы заводите вход через внешний OAuth2/OIDC-провайдер (OAUTH2_PROVIDER, OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, OAUTH2_REDIRECT_URL), самая частая накладка — redirect URL в настройках провайдера не совпадает буквально с тем, что укажет Miniflux (включая завершающий слэш и протокол). Сверяйте строка в строку, а не «на глаз».

Резервное копирование и обновление версии

Всё состояние Miniflux — это база PostgreSQL, сам бинарник состояния не хранит. Значит, бэкап сводится к дампу базы:

pg_dump -U miniflux -Fc miniflux > miniflux_$(date +%F).dump

Восстановление:

pg_restore -U miniflux -d miniflux --clean miniflux_2026-08-20.dump

Обновление до новой версии — это замена бинарника (или образа в Docker) и повторный запуск -migrate. Проблема, с которой сталкиваются на мажорных апдейтах: миграция схемы может занять заметное время на базе с историей в сотни тысяч записей — сервис в этот момент недоступен, и если systemd настроен с коротким TimeoutStartSec, он может убить процесс посреди миграции, решив, что тот завис. Перед крупным обновлением увеличьте таймаут старта юнита и обязательно снимите свежий дамп — миграции Miniflux хорошо протестированы, но откатывать их назад штатных средств нет, только restore из бэкапа.

Общий подход к автоматизации бэкапов баз данных на сервере — со скриптами и планировщиком — разобран в статье Резервное копирование БД на сервере: частые ошибки и решения. Если сравниваете, ставить ли себе Miniflux или более функциональный FreshRSS с расширениями и правилами фильтрации, посмотрите на пошаговую установку FreshRSS на VPS — разница в философии (минимализм против гибкости) там видна сразу.

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