YOURLS в Docker Compose: готовый файл

MAATRIX

Публичные сокращатели ссылок вроде bit.ly или clck.ru удобны, пока вы не начинаете считать переходы всерьёз: аналитика урезана, домен чужой, а в один день сервис может просто заблокировать вашу учётку без объяснений. Если вы гоняете трафик на рекламу, партнёрские ссылки или QR-коды на упаковке, короткие ссылки — это инфраструктура, а не мелочь, и держать их на своём сервере разумнее, чем на чужом. YOURLS закрывает эту задачу: свой домен, полная статистика по каждому клику, API для автоматизации и никакой зависимости от чужой политики модерации. Ниже — рабочий docker-compose.yml, который поднимает YOURLS с MySQL и Caddy за один docker compose up -d.

Что такое YOURLS и зачем свой сокращатель

YOURLS (Your Own URL Shortener) — open-source PHP-приложение для сокращения ссылок, живёт с 2009 года, стабильно развивается и имеет большую библиотеку плагинов. В базовой поставке вы получаете:

• короткие ссылки вида vash-domen.ru/abc123 с настраиваемым алфавитом и длиной кода;
• статистику по каждой ссылке: количество переходов, referrer, страна (по IP), браузер и ОС посетителя, график по дням;
• собственные (кастомные) короткие коды — например /promo вместо случайного набора символов;
• REST/HTTP API для создания ссылок из скриптов, ботов или CRM;
• панель администратора с поиском, сортировкой и массовыми действиями.

Отличие от Bitly и подобных сервисов принципиальное: домен ваш, данные ваши, лимитов на количество ссылок и кликов нет — только то, что выдержит сервер. Для маркетинга это ещё и вопрос доверия: короткая ссылка на вашем собственном домене выглядит солиднее и реже режется спам-фильтрами почтовых провайдеров, чем ссылка с публичного сокращателя.

Из ограничений — честно: интерфейс YOURLS минималистичный и слегка старомодный (это PHP-проект без модного SPA-фронтенда), геолокация по IP не идеальна на VPN-трафике, а под очень большую нагрузку (десятки тысяч кликов в минуту) стандартную установку придётся дополнительно тюнить — кешированием и репликой БД. Для типичного проекта — блог, магазин, рекламная кампания, рассылка — из коробки более чем достаточно.

Требования к серверу

YOURLS — лёгкое приложение, ест немного:

Для проекта с несколькими сотнями тысяч ссылок и активной статистикой закладывайте 2 ГБ RAM — под MySQL с индексами по таблице кликов. Если на том же сервере крутится ещё что-то (например, Matomo для веб-аналитики), берите план с запасом.

Структура проекта и docker-compose.yml

Создаём рабочую директорию и файл с переменными окружения:

mkdir -p ~/yourls && cd ~/yourls
mkdir -p data/db data/yourls caddy_data caddy_config

Файл .env:

# MySQL
MYSQL_ROOT_PASSWORD=замените_на_сложный_пароль
MYSQL_DATABASE=yourls
MYSQL_USER=yourls
MYSQL_PASSWORD=замените_на_другой_сложный_пароль

# YOURLS
YOURLS_SITE=https://short.vash-domen.ru
YOURLS_USER=admin
YOURLS_PASS=замените_на_надежный_пароль_админки

# Домен для Caddy
DOMAIN=short.vash-domen.ru

Пароли генерируйте командой openssl rand -base64 24 — не оставляйте плейсхолдеры, это первое, что перебирают боты по открытым портам.

Теперь сам docker-compose.yml:

services:
  db:
    image: mysql:8.4
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - ./data/db:/var/lib/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - yourls_net

  yourls:
    image: yourls:1.9-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      YOURLS_DB_HOST: db
      YOURLS_DB_USER: ${MYSQL_USER}
      YOURLS_DB_PASS: ${MYSQL_PASSWORD}
      YOURLS_DB_NAME: ${MYSQL_DATABASE}
      YOURLS_SITE: ${YOURLS_SITE}
      YOURLS_USER: ${YOURLS_USER}
      YOURLS_PASS: ${YOURLS_PASS}
    volumes:
      - ./data/yourls:/var/www/html/user
    networks:
      - yourls_net

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    depends_on:
      - yourls
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config
    networks:
      - yourls_net

networks:
  yourls_net:
    driver: bridge

Обратите внимание на condition: service_healthy — YOURLS не запустится, пока MySQL реально не готов принимать соединения, а не просто пока контейнер стартовал. Это частая причина сбоев при первом поднятии стека без healthcheck.

Файл Caddyfile рядом:

{$DOMAIN} {
    reverse_proxy yourls:80
    encode gzip zstd
}

Caddy сам получит и продлит SSL-сертификат Let's Encrypt — руками ничего настраивать не нужно, кроме A-записи домена на IP сервера. Если вы предпочитаете держать SSL отдельным слоем или у вас уже есть свой reverse-proxy, посмотрите пошаговую установку Caddy на Ubuntu 24.04 — принцип тот же.

Запуск и первичная настройка

Перед запуском убедитесь, что DNS A-запись домена short.vash-domen.ru уже указывает на IP вашего сервера — иначе Caddy не сможет выпустить сертификат и уйдёт в цикл ретраев.

docker compose up -d
docker compose logs -f caddy

В логах Caddy должно появиться что-то вроде certificate obtained successfully. После этого открывайте https://short.vash-domen.ru/admin/ и заходите с логином/паролем из .env (переменные YOURLS_USER/YOURLS_PASS). При первом запуске YOURLS сам создаёт таблицы в базе — если вместо формы входа видите ошибку подключения к БД, проверьте, что контейнер db действительно поднялся:

docker compose ps
docker compose logs db --tail=50

Дальше — базовая настройка в админке: Tools → Options для алфавита коротких кодов, Plugins для установки дополнений (статистика по странам работает из коробки через GeoIP-плагин, который можно включить в разделе плагинов).

Настройка статистики переходов

Ключевая причина ставить YOURLS вместо обычного редиректа nginx — именно статистика. По умолчанию для каждой ссылки доступны:

• общее число кликов и график по дням/неделям/месяцам;
• топ referrer'ов (откуда пришли);
• разбивка по браузерам и операционным системам;
• геолокация по IP (страна, иногда город — зависит от точности GeoIP-базы).

Открыть статистику конкретной ссылки: short.vash-domen.ru/abc123+ — плюс в конце короткого кода открывает страницу со всей аналитикой по этой ссылке. Это удобно для быстрой проверки без захода в админку.

Для автоматизации — например, если вы генерируете сотни ссылок из CRM или рекламного кабинета — используйте API. Он включён по умолчанию, ключ доступен в Tools вашей админки:

curl "https://short.vash-domen.ru/yourls-api.php?signature=ВАШ_КЛЮЧ&action=shorturl&url=https://vash-domen.ru/promo-page&format=json"

В ответ придёт JSON с готовой короткой ссылкой. Тем же API можно запрашивать статистику по кликам (action=url-stats) — удобно, если хотите вывести цифры на свой дашборд, а не смотреть их только в админке YOURLS.

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

YOURLS хранит всё в MySQL — бэкапить нужно именно базу, плюс директорию user с кастомными плагинами и конфигом.

# Дамп базы
docker compose exec db mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" ${MYSQL_DATABASE} > backup_$(date +%F).sql

# Архив данных приложения
tar -czf yourls_user_$(date +%F).tar.gz ./data/yourls

Для регулярного автоматического бэкапа вынесите это в cron-задачу с ротацией и, желательно, выгрузкой копии за пределы сервера (в S3-совместимое хранилище или на другой VPS) — если база и бэкап живут на одном диске, при отказе диска вы теряете и то, и другое. Подробный разбор автоматизации бэкапов БД — в статье про резервное копирование баз данных; там же — про восстановление и проверку целостности дампов, что не менее важно, чем сам бэкап.

Восстановление из дампа:

cat backup_2026-08-20.sql | docker compose exec -T db mysql -u root -p"${MYSQL_ROOT_PASSWORD}" ${MYSQL_DATABASE}

Обслуживание и обновления

Обновление стека — стандартная процедура для Docker Compose:

docker compose pull
docker compose up -d

Перед обновлением на новую мажорную версию YOURLS всегда снимайте свежий дамп базы — changelog проекта иногда включает изменения схемы таблиц, и откат назад после неудачного апгрейда без бэкапа будет болезненным.

Если вы держите MySQL не в контейнере, а как отдельный управляемый сервис на том же сервере, обратите внимание на связку прав доступа и версий — она подробно разобрана в статье про установку MariaDB на Ubuntu 24.04 (YOURLS одинаково хорошо работает и с MySQL, и с MariaDB, разница в основном в деталях обслуживания).

Проверяйте место на диске — таблица кликов (yourls_log) растёт пропорционально трафику и со временем может стать самой тяжёлой в базе:

docker compose exec db mysql -u root -p"${MYSQL_ROOT_PASSWORD}" -e \
  "SELECT table_name, ROUND(data_length/1024/1024,1) AS mb FROM information_schema.tables WHERE table_schema='yourls' ORDER BY data_length DESC;"

Если таблица кликов разрослась сильно, а старая детальная статистика уже не нужна, можно периодически архивировать и чистить записи старше N месяцев — штатного инструмента для этого в YOURLS нет, чистка делается прямым SQL-запросом по полю click_time с предварительным бэкапом.

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