FreshRSS

Обзор

FreshRSS — лёгкий агрегатор RSS и Atom для личной ленты или небольшой доверенной группы. Он группирует источники, фильтрует и помечает статьи, поддерживает поиск, OPML и WebSub, а Google Reader/Fever API позволяет читать ленты в сторонних Android, iOS и desktop-клиентах.

Рецепт запускает закреплённый FreshRSS 1.29.1 с PostgreSQL 18. Первый запуск детерминирован: создаётся отдельный администратор с form auth, включается API с другим паролем, выбираются английский интерфейс, production environment и cron дважды в час. Data, extensions и PostgreSQL сохраняются в отдельных volumes.

Безопасность и границы рецепта

Полный HTTP smoke-тест прошёл на amd64, arm64 и armv7; backup и restore практически не проверялись. Получение feed URL выполняется сервером и может достигать внутренних адресов, поэтому рецепт предназначен только для доверенных пользователей. В FreshRSS 1.29.1 нет параметра INTERNAL_HOST_ALLOWLIST; рецепт не задаёт его и тем более не разрешает *. Для недоверенных пользователей нужна отдельная сетевая политика исходящего трафика. Web привязан к localhost, PostgreSQL наружу не опубликован, а доверие proxy-заголовкам по умолчанию выключено.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Нужны Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Выделите минимум 1 CPU, 512 МБ RAM и 2 ГБ диска; рекомендуется 1 ГБ RAM и запас диска под историю статей и backup. Официальный образ заявляет amd64, arm64 и armv7.

docker --version
docker compose version

2. Подготовьте рецепт и независимые секреты

mkdir -p ~/services/freshrss
cd ~/services/freshrss
cp .env.example .env
chmod 600 .env
login_password="$(openssl rand -hex 24)"
api_password="$(openssl rand -hex 24)"
db_password="$(openssl rand -hex 24)"
sed -i "s|^FRESHRSS_ADMIN_PASSWORD=.*|FRESHRSS_ADMIN_PASSWORD=$login_password|" .env
sed -i "s|^FRESHRSS_ADMIN_API_PASSWORD=.*|FRESHRSS_ADMIN_API_PASSWORD=$api_password|" .env
sed -i "s|^FRESHRSS_DB_PASSWORD=.*|FRESHRSS_DB_PASSWORD=$db_password|" .env
unset login_password api_password db_password

Секреты состоят только из букв и цифр: entrypoint 1.29.1 выполняет first-run option strings через shell eval, поэтому пробелы и shell-метасимволы здесь недопустимы. Все три значения должны отличаться. Сохраните их в менеджере паролей: API-клиент использует не пароль web-входа, а отдельный API password.

Все переменные .env:

• FRESHRSS_PORT — локальный web-порт, по умолчанию 8080;
• FRESHRSS_BASE_URL — точный внешний URL с https, без завершающего /; отдельный поддомен надёжнее subpath;
• FRESHRSS_ADMIN_USER — ASCII-alphanumeric логин первого администратора, отличный от секретов и меняемый только до первой инициализации;
• FRESHRSS_ADMIN_PASSWORD и FRESHRSS_ADMIN_API_PASSWORD — независимые alphanumeric пароли form auth и Google Reader/Fever API;
• FRESHRSS_ADMIN_EMAIL — email первого администратора;
• FRESHRSS_DB_PASSWORD — отдельный обязательный пароль PostgreSQL;
• FRESHRSS_DB_NAME и FRESHRSS_DB_USER — имя базы и роли, меняются только до первого запуска;
• FRESHRSS_TIME_ZONE — часовой пояс IANA;
• FRESHRSS_CRON_MIN — минуты встроенного cron; безопасное значение 13,43 обновляет ленты дважды в час без синхронного запуска в нулевую минуту;
• FRESHRSS_TRUSTED_PROXY — доверие forwarded client-IP и external-auth headers; безопасный default 0, не меняйте на широкую сеть;
• FRESHRSS_DATA_VOLUME, FRESHRSS_EXTENSIONS_VOLUME и FRESHRSS_DB_VOLUME — имена постоянных volumes;
• FRESHRSS_BACKUP_DIR — каталог итоговых архивов на хосте.

freshrss-data хранит конфигурацию, пользователей и служебные файлы; freshrss-extensions — сторонние расширения; freshrss-database — PostgreSQL.

3. Запустите детерминированную установку

docker compose config
docker compose pull
docker compose up -d --wait
docker compose exec freshrss cli/health.php
docker compose exec freshrss cli/list-users.php

FRESHRSS_INSTALL только при пустом data volume создаёт production-конфигурацию с PostgreSQL, form auth, выключенным anonymous access, включённым API, английским языком и точным base URL. FRESHRSS_USER создаёт администратора. Изменение этих переменных после первой инициализации не меняет существующую учётную запись.

Запуск на VPS

Оставьте bind 127.0.0.1:${FRESHRSS_PORT}:80: web доступен только HTTPS proxy на этом хосте. PostgreSQL не имеет published port. В firewall откройте только SSH, HTTP и HTTPS. До старта настройте DNS, замените FRESHRSS_BASE_URL и домен в одном proxy-примере. Не приглашайте недоверенных пользователей: они могут заставить сервер получать URL из внутренней сети.

Доступ в доверенной локальной сети

Предпочтителен SSH-туннель ssh -L 8080:127.0.0.1:8080 user@server; для него до первого старта задайте FRESHRSS_BASE_URL=http://localhost:8080. Для постоянного LAN-доступа замените localhost bind в Compose на конкретный private IP, задайте совпадающий base URL и ограничьте порт firewall. Не используйте 0.0.0.0 без сетевых ограничений.

Домен, HTTPS и API-клиенты

Используйте отдельный host вроде https://rss.example.com без завершающего / и укажите его в .env и Caddy, Nginx или Traefik. Caddy получает сертификат автоматически, Nginx ожидает Certbot, Traefik использует resolver letsencrypt. Proxy сохраняет Host, передаёт X-Forwarded-Proto и Authorization, который нужен некоторым Google Reader API-клиентам. FreshRSS не требует WebSocket, поэтому upgrade-заголовки намеренно отсутствуют. Не заменяйте и не удаляйте CSP, которую выдаёт FreshRSS; upstream прямо предупреждает не переопределять её в proxy.

FRESHRSS_TRUSTED_PROXY=0 не доверяет forwarded client IP и заголовкам external auth. Обычный form auth и API при точном base_url работают без широкого trusted range. Если external auth действительно нужен, укажите только точный IP/CIDR последнего защищённого proxy: лишний адрес позволяет подделать пользователя.

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает FreshRSS вместе со встроенным cron, оставляет PostgreSQL работающим для native pg_dump, архивирует полные data и extensions, .env и Compose, затем запускает приложение. Это согласованный полный backup. OPML недостаточно: он не содержит статьи, пользователей, пароли feed, частоту обновления, user agent и XPath scraping rules. Зашифруйте архив, скопируйте его за пределы сервера и регулярно проверяйте restore.

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

Restore необратимо заменяет data, extensions и PostgreSQL. Используйте ту же версию FreshRSS и активный .env, затем:

./restore.sh ./backups/freshrss-YYYYMMDDTHHMMSSZ.tar
docker compose exec freshrss cli/health.php

Скрипт сначала делает страховочный backup текущего состояния, пересоздаёт три volumes, восстанавливает native dump и запускает FreshRSS. Сохранённый configuration.env оставляется только для сравнения. Процедура ещё не прошла практический restore-тест; сначала испытайте копию на отдельном сервере.

Обновление FreshRSS

Сделайте backup и прочитайте release notes. Замените точный тег freshrss/freshrss:1.29.1 на проверенную версию, не используйте latest, затем:

docker compose pull
docker compose up -d --wait
docker compose exec freshrss cli/health.php
docker compose logs --tail=200 freshrss

Миграции приложения применяются при старте. Не обновляйте FreshRSS и PostgreSQL одновременно: это сохраняет однозначный путь отката.

PostgreSQL major update

Тег postgres:18-alpine закреплён отдельно. Смена major требует нового data volume: старый сервер не должен читать каталог новой major и наоборот. Остановите FreshRSS, сохраните native pg_dump и полный data/extensions backup, создайте новый volume с новым образом и восстановите dump. Upstream также предлагает cli/db-backup.php и cli/db-restore.php для переносимого SQLite export каждого пользователя. Не удаляйте старый volume до проверки новой базы.

Откат

Не запускайте старый FreshRSS поверх данных после миграций. Верните прежние точные теги FreshRSS и PostgreSQL и восстановите полный pre-update архив через restore.sh. После неудачной смены PostgreSQL major подключите прежний образ только к сохранённому старому volume либо восстановите его dump в пустой кластер той же major.

Остановка и полное удаление

docker compose down сохраняет данные. После проверки внешнего backup удалить всё безвозвратно:

docker compose down
docker volume rm freshrss-data freshrss-extensions freshrss-database
rm -rf ~/services/freshrss

Если имена volumes изменены в .env, подставьте фактические значения.

Источники: Docker и first run, backup и OPML, access control и SSRF, server CSP и PostgreSQL upgrades.

Диагностика

FreshRSS не становится healthy

docker compose ps
docker compose logs --tail=200 freshrss database
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q freshrss)"
docker compose exec freshrss cli/health.php

Проверьте три обязательных разных секрета, состояние PostgreSQL, свободный диск и first-run ошибки. Пароли должны быть alphanumeric без пробелов и shell-символов. Если пустая установка оборвалась до завершения, изучите логи и только затем удалите пустые volumes и повторите старт; никогда не удаляйте рабочие данные.

Неверный redirect, URL или WebSub callback

FRESHRSS_BASE_URL должен точно совпадать с внешним URL: схема, host, необязательный порт и путь, без завершающего /. Значение применяется только при первой установке; для существующего instance измените base_url в data config.php по официальной инструкции, затем пересоздайте контейнер. Проще и надёжнее использовать отдельный поддомен, а не subpath.

API-клиент не входит

Убедитесь, что клиент использует FRESHRSS_ADMIN_API_PASSWORD, а не пароль web form, и endpoint Google Reader API на том же HTTPS host. Проверьте, что Nginx передаёт Authorization; Caddy и Traefik делают это по умолчанию. WebSocket FreshRSS не нужен.

Ленты с внутренних адресов доступны

Это поведение FreshRSS 1.29.1, а не ошибка рецепта. Не добавляйте wildcard internal-host allowlist: такой поддерживаемой переменной в этой версии нет, а разрешение всех адресов создало бы ложное ощущение защиты. Для недоверенных пользователей запретите container egress к loopback, RFC1918, link-local и cloud metadata средствами firewall/сети либо разместите FreshRSS в отдельной сети.

После настройки proxy неверен IP клиента

Безопасный FRESHRSS_TRUSTED_PROXY=0 отключает обработку forwarded client IP. Если точный IP нужен, доверяйте только последнему proxy IP/CIDR и защитите соединение до FreshRSS. Широкая сеть позволяет подделать IP и заголовки Remote-User/X-WebAuth-User, вплоть до входа администратором.

Расширение ломает страницу или CSP

Отключите стороннее расширение через UI либо восстановите extensions из backup. Не маскируйте ошибку отключением предупреждения и не переопределяйте Content-Security-Policy в reverse proxy: FreshRSS выдаёт собственную CSP.

Ошибка 502 от reverse proxy

С хоста выполните curl -I http://127.0.0.1:8080/. Проверьте upstream, firewall и namespace proxy. Из контейнера 127.0.0.1 указывает на сам proxy-контейнер, а не на FreshRSS на хосте; используйте host gateway или общую закрытую сеть.