Обновление версии, бэкап и восстановление

Большая часть того, что занимает место в Flibusta-at-home, — это копии данных Флибусты, которые можно скачать заново. Ценного и невосполнимого немного, и оно компактное. Эта статья про то, что именно, как это сохранять, и как обновлять библиотеку, не рискуя этим.

Что где лежит

Итого обязательный бэкап — это несколько таблиц Postgres, директория /cache/local (хотя бы одно-книжные zip) и конфигурационные файлы. Всё вместе — мегабайты, если не считать локальных книг.

Снимаем дамп Postgres

В образе библиотеки есть клиент Postgres, а dbinit.sh собирает строку подключения из переменных окружения и секрета, так что ничего ставить на хост не нужно (подробнее о docker exec — в статье о скриптах).

Только пользовательские данные (быстро, компактно):

docker exec -u www-data flibusta-fpm sh -c '. /tools/dbinit.sh; \
  pg_dump -h "$FLIBUSTA_DBHOST" -U "$FLIBUSTA_DBUSER" -d "$FLIBUSTA_DBNAME" \
    --data-only --column-inserts \
    -t users -t user_settings -t user_excluded_genres \
    -t fav -t fav_lists -t progress -t epub_progress -t djvu_progress \
    -t local_books -t local_authors -t local_book_authors -t local_book_genres \
    -t local_book_id_seq -t local_author_id_seq' \
  > flibusta-userdata-$(date +%F).sql

--data-only потому, что схему создаёт сама библиотека при первом старте; --column-inserts делает дамп устойчивым к появлению новых колонок в будущих версиях (строки вставляются по именам полей, а не по позиции). Две последовательности нужны, чтобы после восстановления новые локальные книги не получили уже занятые id.

Вся база (проще, но включает каталог Флибусты — гигабайты):

docker exec -u www-data flibusta-fpm sh -c '. /tools/dbinit.sh; \
  pg_dump -h "$FLIBUSTA_DBHOST" -U "$FLIBUSTA_DBUSER" -d "$FLIBUSTA_DBNAME" -Fc' \
  > flibusta-full-$(date +%F).dump

Полный дамп имеет смысл, если хочется восстановиться быстро, не дожидаясь скачивания и импорта дампа Флибусты (импорт занимает от минут до часа).

Файлы к дампу:

tar czf flibusta-local-$(date +%F).tgz -C /opt/flibusta/cache local
cp -a /opt/flibusta/docker-compose.yml /opt/flibusta/secrets /backup/

Всё это удобно повесить на тот же cron, что и обновления, и класть туда, куда уходят остальные бэкапы хоста. Дамп снимается без остановки библиотеки; если он совпадёт по времени с «Обновить базу данных», pg_dump просто подождёт или снимет согласованный снимок — Postgres это умеет.

Восстановление на чистой установке

Сценарий: новый сервер (или новая база) и бэкап пользовательских данных.

1. Разверните библиотеку по чеклисту установки с теми же docker-compose.yml и секретами, дайте контейнеру стартовать один раз — он создаст схему.

2. Остановите контейнер (docker compose stop flibusta-fpm) или хотя бы убедитесь, что никто не входит: при старте контейнер создал администратора из FLIBUSTA_APP_ADMIN, и если в бэкапе есть пользователь с тем же именем, вставка упрётся в уникальность имени. Проще всего удалить свежесозданного администратора перед восстановлением — в бэкапе есть свой:

   docker exec -u www-data flibusta-fpm sh -c '. /tools/dbinit.sh; \
     $SQL_CMD -c "DELETE FROM users"'
   

3. Залейте дамп:

   docker exec -i -u www-data flibusta-fpm sh -c '. /tools/dbinit.sh; $SQL_CMD -v ON_ERROR_STOP=1' \
     < flibusta-userdata-2026-09-17.sql
   

4. Распакуйте /cache/local на место, проверьте владельца (chown -R 82:82).

5. Запустите контейнер, в «Сервисе» выполните «Скачать базу» → «Обновить базу» (восстановление локальных книг произойдёт автоматически на шаге импорта) → «Скачать обложки» → «Сканирование ZIP».

Для полного дампа (-Fc) вместо шагов 2–3 и 5: создайте роль и базу вручную (или дайте контейнеру стартовать и затем очистите базу), восстановите через pg_restore --clean --if-exists, и потом запускайте контейнер — увидев существующую роль, он пропустит инициализацию, прогонит миграции (они идемпотентны) и убедится, что администратор есть.

Обновление версии образа

Образ публикуется на Docker Hub как blitvin/flibusta-at-home с тегами latest и vX.Y.Z (собирается автоматически из тегов репозитория, для amd64 и arm64). Обновление — стандартное для Docker:

cd /opt/flibusta
docker compose pull
docker compose up -d
docker compose logs -f flibusta-fpm

Что делает новая версия при старте — то же, что и при любом старте: синхронизирует статику в том (reverse proxy сразу видит новые JS-читалки и стили), прогоняет postgres_migration.sql (все операции вида CREATE TABLE IF NOT EXISTS / ADD COLUMN IF NOT EXISTS, лог в /cache/log/postgres_migration.log), проверяет администратора. Отдельных действий от вас не требуется; убедитесь только, что в логе есть Migration proceeded и нет ошибок Postgres.

Правила хорошего тона:

• Снимите дамп перед обновлением. Миграции добавляют, а не удаляют, но бэкап за минуту до pull — дешёвая страховка.
• Прочитайте описание релиза на GitHub: там будет сказано, если версия требует полного переимпорта дампа (новые полнотекстовые индексы, новые таблицы из дампа) или изменений в docker-compose (новая переменная, новый том).
• Приколите тег, если библиотекой пользуются другие люди и внезапные изменения нежелательны: image: blitvin/flibusta-at-home:v1.2.6 вместо latest. Тогда pull ничего не поменяет, пока вы сами не смените тег.

Откат. Укажите предыдущий тег в image: и снова up -d. Поскольку миграции только добавляют объекты, старая версия обычно работает на «новой» схеме, но это не гарантируется — если откатываетесь из-за проблем, восстановите заодно дамп, снятый перед обновлением.

Обновление на версию с поддержкой Redis

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

Обновление образа ничего не требует. Изменений схемы в этом выпуске нет, конфигурацию править не нужно, никто не разлогинивается. Библиотека просто перестаёт обращаться к базе там, где ей нечего там делать, и при старте строит индекс архивов /cache/zip_index.php из существующей таблицы book_zip.

Redis — отдельный, необязательный шаг, который можно сделать когда угодно позже или не делать совсем. Если решите включать, учтите две вещи. Первая: в момент включения все читатели разлогиниваются один раз — кроме тех, кто заходит из доверенной сети, и тех, у кого стоит галочка «Запомнить меня» (эти токены живут в Postgres и переезд их не касается). Вторая: после переезда таблица php_sessions больше не используется, и оставшиеся в ней строки стоит один раз удалить:

docker exec -u www-data flibusta-fpm sh -c '. /tools/dbinit.sh; \
  $SQL_CMD -c "TRUNCATE php_sessions"'

Откатить включение Redis так же просто, как включить: уберите FLIBUSTA_REDIS_HOST, пересоздайте контейнер, сессии снова окажутся в Postgres. Подробный разбор — в статье о кэше и производительности.

Обновление Postgres (мажорной версии) — это не про библиотеку, а про ваш контейнер Postgres; делается штатно для Postgres (pg_dumpall / pg_upgrade) и не отличается от обновления любой другой базы на хосте. Библиотеке всё равно, какая версия, лишь бы работало расширение pg_trgm.

Переезд на другой сервер

Ровно «бэкап + восстановление», плюс большие данные:

1. Скопируйте /flibusta (rsync, диск целиком, или скачайте торренты заново на новом месте).
2. Скопируйте /cache/local — это одновременно и локальные книги, и всё, что скачано на лету; терять не обязательно, но и не жалко.
3. Перенесите docker-compose.yml, секреты, конфиг reverse proxy, jail fail2ban. Если используется Redis — поднимите его на новом месте; переносить его данные не нужно, они одноразовые.
4. Восстановите пользовательские данные как описано выше.
5. Проверьте права: uid 82 на /sql, /cache, секретах; чтение на /flibusta.

Если на новом сервере другая подсеть, не забудьте FLIBUSTA_TRUSTED_NET; если другой домен — FLIBUSTA_WEBROOT, DNS и сертификат. Читателям после переезда придётся войти заново (сессии и токены в бэкап не входят), всё остальное — полка, позиции, настройки — окажется на месте.