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

MAATRIX

YOURLS (Your Own URL Shortener) — самый популярный self-hosted сервис коротких ссылок: PHP + MySQL, свой домен, полная статистика переходов без чужих аналитик и лимитов bit.ly. Ставится за пять минут, но именно из-за простоты первого запуска большинство проблем всплывает позже — на проде, под нагрузкой или после обновления PHP. Ниже — конкретные ошибки, с которыми сталкиваются при развёртывании и эксплуатации YOURLS на своём VPS, и рабочие решения без гаданий.

Белый экран или 500-я после установки

Классика: скачали архив, настроили config.php, зашли на /admin/ — и получили пустую страницу или Internal Server Error без единой подсказки.

Первым делом включите вывод ошибок PHP на время диагностики. В config.php рядом с настройками БД временно добавьте:

error_reporting(E_ALL);
ini_set('display_errors', '1');

Дальше смотрите реальный лог, а не догадки:

tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/log/php8.2-fpm.log

Топ причин белого экрана:

• Не хватает PHP-расширений. YOURLS требует php-mysqli (или php-mysqlnd), php-curl, php-mbstring, php-gd (для QR-кодов), php-xml. Проверка одной командой:

php -m | grep -Ei 'mysqli|curl|mbstring|gd|xml'

Если чего-то нет:

apt install php8.2-mysqli php8.2-curl php8.2-mbstring php8.2-gd php8.2-xml
systemctl restart php8.2-fpm

• Права на файлы. YOURLS не пишет в /var/www, если владелец — root, а веб-сервер работает от www-data:

chown -R www-data:www-data /var/www/yourls
find /var/www/yourls -type d -exec chmod 755 {} \;
find /var/www/yourls -type f -exec chmod 644 {} \;

• Неверные данные в config.php. Особенно частая опечатка — YOURLS_DB_HOST с портом через двоеточие вместо отдельного параметра, или хост localhost вместо 127.0.0.1 (при localhost PHP пытается идти через unix-сокет, которого может не быть, если MySQL слушает только TCP).

Если проблема глубже — стоит свериться с общими причинами падения PHP-приложений на связке nginx/Apache, разобранными в статье про Apache с mod_php — многие грабли (права, php-fpm сокет, лимиты памяти) общие для любого self-hosted PHP-сервиса.

Короткие ссылки отдают 404 вместо редиректа

Установка прошла, /admin/ открывается, но переход по https://ваш-домен/abc123 выдаёт 404 от веб-сервера, а не от YOURLS. Причина всегда одна: запрос не долетает до index.php, потому что не настроен rewrite.

Для Apache проверьте, что mod_rewrite включён и .htaccess в корне YOURLS реально читается (AllowOverride All в конфиге сайта):

<Directory /var/www/yourls>
    AllowOverride All
</Directory>

a2enmod rewrite
systemctl restart apache2

Содержимое .htaccess (YOURLS кладёт его сам при установке, но если файл потерялся):

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ ./yourls-loader.php [L]
</IfModule>

Для nginx .htaccess не работает вообще — правило нужно прописать прямо в конфиге сервера:

server {
    listen 443 ssl http2;
    server_name go.ваш-домен.ru;
    root /var/www/yourls;
    index index.php;

    location / {
        try_files $uri $uri/ /yourls-loader.php$is_args$args;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Ключевая строка — try_files ... /yourls-loader.php$is_args$args: без неё nginx честно вернёт 404 на любой несуществующий файл вроде /abc123, вместо того чтобы передать управление YOURLS. Забытый $is_args$args — вторая по частоте ошибка: без него теряются GET-параметры, и часть плагинов (например, для UTM-меток) перестаёт работать.

Ошибка подключения к базе данных

Error establishing a database connection или Access denied for user — почти всегда про несовпадение того, что в config.php, и того, что реально создано в MySQL.

Проверка вручную теми же учётными данными:

mysql -u yourls_user -p -h 127.0.0.1 yourls_db

Если не заходит — пересоздайте пользователя с нуля, явно указав хост:

CREATE DATABASE yourls_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yourls_user'@'127.0.0.1' IDENTIFIED BY 'СЛОЖНЫЙ_ПАРОЛЬ';
GRANT ALL PRIVILEGES ON yourls_db.* TO 'yourls_user'@'127.0.0.1';
FLUSH PRIVILEGES;

Частый нюанс с MySQL 8: по умолчанию используется плагин аутентификации caching_sha2_password, с которым старые версии php-mysqli иногда конфликтуют. Если после верного пароля всё равно Access denied, пересоздайте пользователя с явным mysql_native_password:

ALTER USER 'yourls_user'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'СЛОЖНЫЙ_ПАРОЛЬ';

Общие подходы к диагностике MySQL на сервере — с проверкой max_connections, кодировок и логов — подробно разбирались в статье MySQL на сервере: частые ошибки и решения.

Отдельно: если после успешной установки в какой-то момент база "теряется" (переезд, обновление MySQL, случайный DROP) — заранее настроенный бэкап экономит часы. Как автоматизировать дампы, описано в статье про бэкап MySQL на сервере.

Не работает генерация коротких ссылок или API

Ссылка создаётся в админке, но при попытке создать её через API (/yourls-api.php) — тишина, 403 или signature error.

Проверьте, что в config.php включён нужный способ авторизации API:

define( 'YOURLS_UNIQUE_URLS', true );

Для API есть два режима — по логину/паролю или по signature-токену (он показывается в /admin/tools.php). Частая ошибка — путают timestamp-подпись (действует ограниченное время) со статичным signature: если между генерацией подписи на клиенте и запросом на сервер прошло больше окна валидности, а вы используете именно timestamp-вариант, получите error: bad signature timestamp. Для скриптов и cron-заданий проще и надёжнее взять статичный токен из настроек — он не истекает.

Проверка API curl'ом напрямую, в обход вашего клиента, сразу показывает, где проблема — на стороне YOURLS или в вызывающем коде:

curl "https://go.ваш-домен.ru/yourls-api.php?signature=ВАШ_ТОКЕН&action=shorturl&url=https://example.com&format=json"

Если получаете {"errorCode":403,"message":"Please log in"} — токен неверный или его вообще не подхватил config.php (проверьте, что файл не кэшируется opcache со старой версией — после правки конфига стоит выполнить systemctl reload php8.2-fpm).

Статистика переходов не считается или считается неверно

YOURLS хранит клики в таблице yourls_url (счётчик) и, если включено, в yourls_log (детальные записи по каждому переходу — IP, referrer, user agent, страна). Если счётчик кликов на странице + не растёт:

1. Проверьте, что плагин Stats for YOURLS или встроенный трекинг не отключён в /admin/plugins.php.
2. Убедитесь, что запросы реально доходят до yourls-loader.php, а не отдаются напрямую из кэша nginx/Cloudflare. Если перед сервером стоит CDN или reverse-proxy с агрессивным кэшированием статики, короткие ссылки нужно явно исключить из кэша — иначе повторные переходы будут отдаваться из кэша proxy, минуя YOURLS и его логирование.
3. Проверьте таблицу напрямую:

SELECT keyword, url, clicks FROM yourls_url ORDER BY timestamp DESC LIMIT 10;

Если clicks растёт в базе, но не отображается в интерфейсе — обычно проблема в JS-виджете статистики (устаревший плагин, конфликт версий после обновления YOURLS) — временно отключите сторонние плагины по одному через /admin/plugins.php и проверьте, какой конфликтует.

Для гео-статистики (страна перехода) YOURLS по умолчанию использует внешний сервис определения IP — если сервер не имеет исходящего доступа в интернет (что бывает при жёстких firewall-правилах на выделенных серверах), геолокация будет пустой при полностью рабочих остальных счётчиках. Проверка исходящего доступа:

curl -sI https://api.ipapi.com | head -1

Медленная загрузка коротких ссылок под нагрузкой

Отдельная ссылка открывается мгновенно, но при заметном потоке переходов (рассылка, реклама, вирусный пост) сервер начинает тормозить или отдавать 502/504.

Основные точки, которые стоит проверить по порядку:

• PHP-FPM пул. Дефолтные pm.max_children в 5 штук хватает на тестовый стенд, но не на всплеск трафика. Смотрите текущую загрузку:

systemctl status php8.2-fpm
tail -f /var/log/php8.2-fpm.log | grep -i "server reached"

Если в логе есть server reached pm.max_children, увеличивайте лимит в /etc/php/8.2/fpm/pool.d/www.conf пропорционально доступной RAM (каждый php-fpm воркер под YOURLS обычно занимает 20-40 МБ):

pm = dynamic
pm.max_children = 30
pm.start_servers = 6
pm.min_spare_servers = 4
pm.max_spare_servers = 12

• Отсутствие индексов на большой таблице yourls_url. На проектах с сотнями тысяч ссылок редиректы по keyword могут упираться в полное сканирование, если индекс повреждён после ручных манипуляций с БД. Проверка:

SHOW INDEX FROM yourls_url;

Поле keyword должно быть PRIMARY или UNIQUE — по умолчанию YOURLS создаёт его так сам, трогать вручную не нужно.

• MySQL слушает без кэша соединений. Если PHP на каждый редирект открывает новое TCP-соединение к MySQL, а max_connections в MySQL занижен, под нагрузкой начнутся отказы. Разумный кэш через persistent-соединения или пул (например, ProxySQL) для высоконагруженного шортенера снимает эту проблему, но для среднего проекта достаточно просто адекватно выставленного max_connections (250-500 для отдельного VPS под этот сервис).

Здесь общий принцип тот же, что и с любым PHP-сервисом на cron или под нагрузкой: если параллельно с YOURLS крутятся ещё и фоновые задачи (например, периодическая чистка старых логов кликов), стоит свериться с материалом про настройку cron-задач на сервере, чтобы не столкнуть их с пиковой нагрузкой на редиректы.

SSL и корректная работа коротких ссылок в браузерах и мессенджерах

Короткие ссылки часто расшариваются в Telegram, WhatsApp и соцсетях — эти платформы делают собственный HEAD/GET запрос на превью ссылки ещё до того, как перейдёт человек. Если у сервера истёк или неправильно настроен сертификат, превью не подгрузится, а сама ссылка в некоторых клиентах будет помечена как небезопасная.

Быстрая проверка сертификата снаружи:

curl -vI https://go.ваш-домен.ru 2>&1 | grep -E "SSL certificate|expire"

Если сертификат просрочен или не продлился автоматически — причины и починка разобраны в статье SSL-сертификат не обновился. А для выбора и настройки инструмента автопродления с нуля пригодится сравнение Certbot или acme.sh — что выбрать для сервера.

Отдельно стоит убедиться, что редирект с http:// на https:// настроен именно на уровне веб-сервера, а не полагается только на HSTS — часть мессенджеров и старых ботов-краулеров не следует HSTS-заголовку с первого запроса и может зафиксировать ссылку как небезопасную при однократном обращении по HTTP.

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