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

MAATRIX

Piwigo ставится за десять минут мастером установки, а дальше начинается: фото весом больше пары мегабайт не грузятся, миниатюры не строятся, при синхронизации тысяч файлов сервер зависает, а после переезда на новый хостинг альбомы вообще не открываются. Ниже — конкретные причины этих ошибок и то, как их закрыть без переустановки галереи с нуля.

Что реально нужно на сервере для Piwigo

Piwigo — классическое PHP-приложение с MySQL/MariaDB, без Node.js и без обязательного Docker, поэтому большинство проблем приходят не из «экзотики», а из типовых мест: версия PHP, расширения, права и лимиты веб-сервера.

Минимальный набор, который стоит проверить перед тем, как копать глубже:

• PHP 7.4+ (для актуальных веток Piwigo 14–15 комфортнее 8.1–8.3, но проверяйте требования конкретной версии в release notes — они меняются);
• расширения: gd или imagick, mysqli, mbstring, curl, zip, exif, gettext;
• MySQL 5.7+/MariaDB 10.3+ с кодировкой utf8mb4;
• веб-сервер nginx или Apache с PHP через php-fpm.

Проверить набор расширений на Debian/Ubuntu:

php -v
php -m | grep -Ei 'gd|imagick|mysqli|mbstring|curl|zip|exif'

Если чего-то не хватает — доустановите пакеты (php-gd, php-mysqli, php-mbstring и так далее) и перезапустите php-fpm, иначе мастер установки будет молча выключать пункты меню или падать на шаге проверки окружения.

Права доступа — причина №1 «белого экрана» после установки

Piwigo пишет на диск больше, чем кажется на первый взгляд: каталог с самими фото (galleries/ или upload/ в зависимости от версии и режима), кэш и превью (_data/), а также загруженные плагины и темы. Если владелец файлов — не тот пользователь, от имени которого работает php-fpm, вы получите пустую страницу, ошибку 500 или «Невозможно записать файл» при загрузке.

Правильно выставить владельца и права на Ubuntu/Debian с nginx + php-fpm (пользователь www-data):

cd /var/www/piwigo
sudo chown -R www-data:www-data _data galleries upload plugins themes local
sudo find _data galleries upload -type d -exec chmod 755 {} \;
sudo find _data galleries upload -type f -exec chmod 644 {} \;

Если сервер на другом дистрибутиве и пользователь PHP-FPM другой (например, nginx или ваш собственный аккаунт), уточните его в ps aux | grep php-fpm и подставьте вместо www-data. Отдельно проверьте, не мешает ли SELinux (CentOS/AlmaLinux) — если после верных прав всё равно 403/500, временно переключите режим в permissive (setenforce 0) и посмотрите, исчезнет ли проблема; если да, донастраивайте контексты через semanage fcontext, а не оставляйте SELinux выключенным насовсем.

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

Ошибка «файл не загружен» или обрыв на середине прогресс-бара почти всегда означает, что где-то в цепочке PHP → PHP-FPM → nginx стоит лимит меньше, чем размер ваших RAW или полноразмерных JPEG.

Проверьте в php.ini (обычно /etc/php/8.2/fpm/php.ini, путь зависит от версии):

upload_max_filesize = 64M
post_max_size = 72M
memory_limit = 256M
max_execution_time = 300
max_input_time = 300

post_max_size должен быть строго больше upload_max_filesize — вы можете грузить сразу несколько фото за раз, и суммарный размер запроса выйдет за пределы одного файла.

На стороне nginx лимит стоит отдельно и по умолчанию всего 1 МБ:

server {
    client_max_body_size 64m;

    location ~ \.php$ {
        fastcgi_read_timeout 300;
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

После правки — обязательно systemctl restart php8.2-fpm и systemctl reload nginx, иначе изменения не подхватятся. Если после этого загрузка всё равно рвётся именно на больших файлах — проверьте таймаут прокси, если Piwigo стоит за реверс-прокси или CDN; там свой лимит на размер тела запроса и время ответа. О похожей механике на примере обратного прокси есть отдельный разбор — nginx как reverse proxy: частые ошибки и решения.

Ошибки базы данных и кракозябры в названиях альбомов

Мастер установки Piwigo падает с «Access denied for user» — почти всегда неверные права у пользователя MySQL или он не может подключаться с localhost при работе через сокет. Создать пользователя и базу под Piwigo:

CREATE DATABASE piwigo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'piwigo_user'@'localhost' IDENTIFIED BY 'СложныйПароль123';
GRANT ALL PRIVILEGES ON piwigo.* TO 'piwigo_user'@'localhost';
FLUSH PRIVILEGES;

Если база уже создана с кодировкой latin1 или utf8 (без mb4), кириллица в названиях альбомов и подписях превращается в вопросики или квадратики после сохранения. Проверить и поправить кодировку существующей базы:

ALTER DATABASE piwigo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE piwigo_categories CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Учтите, что конвертация таблиц, где уже есть кракозябры, кодировку не восстановит — она чинит только новые записи. Старые названия придётся переименовывать руками или восстанавливать из бэкапа, снятого до порчи данных. Общие принципы диагностики MySQL на сервере разобраны в статье MySQL на сервере: частые ошибки и решения.

Миниатюры не строятся: GD против ImageMagick

Piwigo умеет строить превью двумя способами — встроенным GD или внешним ImageMagick (бинарник convert/magick). В админке (Настройки → Основные → библиотека изображений) это переключается явно, и от выбора зависит, какая ошибка вас встретит.

GD идёт «из коробки» почти на любом хостинге и достаточно для стандартных JPEG/PNG. ImageMagick даёт лучшее качество и HEIC-совместимость, но требует отдельной установки пакета и иногда — прав на выполнение внешнего процесса, если хостинг это ограничивает. На своём VPS такого ограничения нет, поэтому если вы часто заливаете фото с айфонов — сразу ставьте ImageMagick.

Синхронизация большой коллекции: что при этом делает диск

Здесь начинается «железная» часть проблемы. Функция «Синхронизация» в Piwigo сканирует каталог с фото, читает EXIF каждого файла и пишет превью в _data/ — на коллекции в десятки тысяч снимков это тысячи операций чтения и записи мелких файлов подряд. На медленном сетевом диске или переполненном HDD именно здесь синхронизация зависает или обрывается по таймауту браузера.

Что реально помогает:

• Диск под _data/ и galleries/ — SSD, а не сетевое хранилище с высокой задержкой. Превью — это множество мелких файлов, и на них важнее IOPS, чем последовательная скорость чтения.
• Синхронизацию больших коллекций запускайте не за один проход, а по подкаталогам — так меньше риска упереться в max_execution_time веб-сервера. Для регулярных догрузок удобнее CLI-обёртка вокруг sync-запроса через wget/curl из cron в тихие часы, чем ручной клик в браузере на пиковой нагрузке.
• RAM важна для обработки EXIF и построения превью пачками — на сервере с 1 ГБ и активной синхронизацией процесс php-fpm может упираться в memory_limit или своп; для регулярной работы с большими фотоархивами комфортнее 2–4 ГБ.
• Если превью уже строились и вы просто перенесли фото, не трогая структуру — используйте «пересканирование» точечно по альбому, а не полную синхронизацию с нуля.

Если галерея растёт быстрее, чем вы рассчитывали, и диск начал заканчиваться — сначала проверьте, что именно съедает место (_data/ с несколькими размерами превью на каждое фото часто весит сравнимо с оригиналами). Практические шаги разобраны в статье закончилось место на диске VPS. Если хочется контейнеризированную альтернативу с автоматическим ML-тегированием и другой моделью хранения — присмотритесь к Immich в Docker Compose, это другой подход к тем же задачам, местами удобнее для личного архива, местами беднее по управлению правами и альбомами, чем у Piwigo.

HTTPS и человекопонятные ссылки (Friendly URLs)

После переноса на HTTPS или включения ЧПУ-адресов в настройках Piwigo часто ломается — то смешанный контент (часть ресурсов грузится по http), то 404 на всех страницах кроме главной.

Для смешанного контента убедитесь, что в local/config/config.inc.php не прописан жёстко http:// в путях, и что за прокси Piwigo корректно видит схему запроса — если сервер стоит за nginx-прокси или CDN, добавьте заголовок:

proxy_set_header X-Forwarded-Proto $scheme;

Для «дружественных» URL (/picture/123-nazvanie вместо index.php?/picture/123) на Apache должен быть включён mod_rewrite и разрешён .htaccess в конфиге виртуального хоста (AllowOverride All). На nginx .htaccess не читается вообще — правила нужно перенести в конфиг явно:

location / {
    try_files $uri $uri/ /index.php?$args;
}

Если после включения Friendly URLs в админке Piwigo вы получаете 404 на все страницы, кроме главной, — почти наверняка не хватает именно этого try_files, а не проблема самого Piwigo. Разбор похожих ситуаций с nginx и SSL — в статье nginx не применяет SSL: причины и решение.

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