Настройка собственного URL-сокращателя Shlink на VPS с Docker

Что мы настраиваем и зачем

В эпоху, когда каждый символ имеет значение, а длинные, неуклюжие URL-адреса могут оттолкнуть пользователей и испортить внешний вид сообщения, сервисы для сокращения ссылок стали незаменимым инструментом. Shlink – это саморазмещаемое (self-hosted) решение с открытым исходным кодом, которое позволяет вам создать собственный, полностью контролируемый сервис для сокращения URL-адресов. В отличие от популярных коммерческих аналогов, таких как Bitly или Rebrandly, Shlink предоставляет вам полную свободу и владение данными, а также возможность использовать собственные домены для брендирования ссылок.

В итоге этого руководства вы получите полностью функционирующий URL-сокращатель Shlink, развернутый на вашем собственном VPS. Это означает, что вы сможете создавать короткие, запоминающиеся ссылки, которые будут указывать на ваш домен (например, my.link/abc вместо long-and-ugly-url.com/some/path/to/resource). Помимо базового сокращения, Shlink предлагает богатый набор функций: подробную аналитику переходов (количество кликов, география, браузеры, ОС), создание QR-кодов для каждой ссылки, возможность установки паролей на ссылки, лимитов переходов и сроков действия, а также мощный API для интеграции с другими вашими сервисами. Вы сможете управлять всеми этими функциями через удобный веб-интерфейс или командную строку.

Почему self-hosted на VPS, а не облачные управляемые сервисы? Выбор в пользу собственного VPS обусловлен несколькими ключевыми преимуществами. Во-первых, это полный контроль над данными. Вся информация о ваших ссылках и их аналитике хранится на вашем сервере, а не на серверах стороннего провайдера. Это критично для проектов, требующих повышенной конфиденциальности или соответствия строгим регуляторным требованиям. Во-вторых, это кастомизация. Вы можете настроить Shlink под свои нужды, интегрировать его с другими инструментами, использовать собственный брендированный домен без ограничений, которые часто накладывают бесплатные тарифы облачных сервисов. В-третьих, это экономия в долгосрочной перспективе. Хотя аренда VPS требует некоторых начальных вложений и времени на настройку, для высоконагруженных или долгосрочных проектов это часто оказывается значительно дешевле, чем ежемесячные подписки на коммерческие сервисы, особенно при большом объеме ссылок или аналитики. Наконец, это отличный способ углубить свои знания в области администрирования серверов и работы с Docker, что является ценным навыком для любого разработчика или технического специалиста.

Альтернативы Shlink включают множество коммерческих решений, таких как Bitly, Rebrandly, Short.io, TinyURL, а также другие self-hosted варианты, например, Kutt или Polr. Однако Shlink выделяется своей зрелостью, активным развитием, богатым функционалом и поддержкой Docker, что делает его идеальным выбором для развертывания на VPS.

Какой VPS-конфиг нужен под эту задачу

Для развертывания Shlink с Docker и базой данных на VPS, важно выбрать подходящие аппаратные ресурсы. Shlink сам по себе достаточно легковесный, но Docker, база данных (например, MariaDB или PostgreSQL) и веб-сервер (Caddy) требуют определенного минимума.

Минимальные требования:

• CPU: 1 vCPU (виртуальное ядро). Для небольших проектов и тестирования этого будет достаточно.
• RAM: 1 GB. Это абсолютный минимум. Docker Engine, ОС и база данных потребляют значительную часть этой памяти, оставляя мало для самого Shlink. Могут возникать проблемы при пиковых нагрузках или во время обновлений.
• Диск: 20 GB NVMe/SSD. NVMe или SSD крайне желательны для производительности базы данных. 20 GB хватит для ОС, Docker-образов, данных Shlink и логов.
• Сеть: 100 Mbps с неограниченным трафиком или с большим запасом (от 1 TB в месяц). Shlink не является сильно сетезависимым сервисом, если только вы не ожидаете миллионы кликов в день.

Рекомендуемый VPS-план для большинства случаев (актуально на 2026 год):

Для комфортной работы и возможности масштабирования в будущем, а также для обеспечения стабильности, рекомендуется следующий конфиг:

• CPU: 2 vCPU. Обеспечит плавную работу всех компонентов и позволит обрабатывать больше запросов одновременно.
• RAM: 2-4 GB. 2 GB будет достаточно для большинства средних проектов, 4 GB даст большой запас прочности и позволит запускать дополнительные сервисы при необходимости.
• Диск: 40-80 GB NVMe/SSD. Больший объем диска обеспечит место для расширения базы данных, логов и потенциальных бэкапов. NVMe значительно ускорит дисковые операции.
• Сеть: 1 Gbps с трафиком от 5 TB в месяц. Гигабитный порт и достаточный объем трафика обеспечат высокую скорость загрузки и обработки запросов, даже если ваш URL-сокращатель станет очень популярным.

Найти VPS с указанными характеристиками не составит труда у большинства провайдеров. Например, можно взять VPS с 2 vCPU, 4 GB RAM и 80 GB NVMe диском, что обеспечит отличную производительность и запас на будущее.

Когда нужен dedicated, а не VPS:

Dedicated сервер (выделенный сервер) становится необходимым, когда ваш URL-сокращатель начинает обрабатывать очень большие объемы трафика (десятки или сотни миллионов кликов в месяц), когда требуется максимальная производительность базы данных, или если вы планируете размещать на этом же сервере множество других ресурсоемких приложений. Также dedicated серверы предлагают более высокий уровень изоляции и часто более широкие возможности по кастомизации аппаратной части. Для Shlink это обычно не требуется, если только вы не строите глобальный сервис с миллиардами переходов.

Локация: на что влияет

Выбор локации VPS имеет значение по нескольким причинам:

• Задержка (latency): Чем ближе сервер к вашей основной аудитории или к серверам, на которые будут указывать сокращенные ссылки, тем меньше будет задержка при переходе. Для URL-сокращателя это не критично, так как сам редирект происходит очень быстро, но для общей отзывчивости админ-панели и API это может быть заметно.
• Законодательство: В зависимости от того, где физически расположен сервер, на него распространяются законы этой страны относительно хранения данных, конфиденциальности и т.д. Убедитесь, что выбранная юрисдикция соответствует вашим требованиям.
• Доступность: Некоторые регионы могут предлагать более стабильное и быстрое сетевое соединение, а также лучшую связность с различными частями света.

Обычно рекомендуется выбирать локацию, которая географически близка к вашей целевой аудитории или к вам самим, чтобы упростить управление.

Подготовка сервера

После получения доступа к вашему новому VPS, первым делом необходимо провести минимальную настройку для обеспечения безопасности и удобства работы. Мы будем использовать дистрибутив Ubuntu Server 24.04 LTS (актуальная версия на 2026 год) как наиболее распространенный и хорошо документированный выбор.

1. Подключение по SSH

Подключитесь к серверу как пользователь root (или тот пользователь, которого предоставил хостинг-провайдер) по SSH. Замените на IP-адрес вашего сервера.

ssh root@

Если вы используете пароль, система запросит его. Если вы используете SSH-ключи, убедитесь, что ваш публичный ключ добавлен на сервер.

2. Обновление системы

Всегда начинайте с обновления списка пакетов и их установки до последней версии. Это обеспечит наличие всех последних исправлений безопасности и стабильности.

sudo apt update          # Обновляем список доступных пакетов
sudo apt upgrade -y      # Устанавливаем все доступные обновления без подтверждения
sudo apt autoremove -y   # Удаляем ненужные пакеты

3. Создание нового пользователя с правами sudo

Работать под пользователем root небезопасно. Создайте нового пользователя и предоставьте ему права sudo.

sudo adduser shlinkuser                  # Создаем нового пользователя с именем shlinkuser
sudo usermod -aG sudo shlinkuser         # Добавляем пользователя shlinkuser в группу sudo

После создания пользователя, задайте ему надежный пароль. Теперь вы можете выйти из root и войти под новым пользователем:

exit                                     # Выходим из root
ssh shlinkuser@             # Входим под новым пользователем

4. Настройка SSH-ключей для нового пользователя (рекомендуется)

Для повышения безопасности и удобства, настройте вход по SSH-ключам для shlinkuser. Если у вас еще нет SSH-ключа на локальной машине, создайте его:

ssh-keygen -t rsa -b 4096 -C "[email protected]" # Создаем новый SSH-ключ (на вашей локальной машине)

Затем скопируйте публичный ключ на сервер:

ssh-copy-id shlinkuser@     # Копируем публичный ключ на сервер

Или вручную добавьте содержимое файла ~/.ssh/id_rsa.pub (на локальной машине) в файл ~/.ssh/authorized_keys на сервере (для пользователя shlinkuser).

После этого можно отключить вход по паролю для SSH, отредактировав файл /etc/ssh/sshd_config. Найдите строки:

PasswordAuthentication yes

И измените ее на:

PasswordAuthentication no

Также рекомендуется отключить вход для root пользователя по SSH, изменив:

PermitRootLogin yes

на:

PermitRootLogin no

После изменений перезапустите SSH-сервис:

sudo systemctl restart sshd

Важно: Убедитесь, что вы можете войти по SSH-ключу, прежде чем отключать вход по паролю! Иначе вы можете потерять доступ к серверу.

5. Установка и настройка брандмауэра UFW

Брандмауэр Uncomplicated Firewall (UFW) прост в настройке и значительно повышает безопасность сервера, блокируя нежелательные входящие соединения.

sudo apt install ufw -y                 # Устанавливаем UFW
sudo ufw allow OpenSSH                  # Разрешаем SSH-соединения (порт 22)
sudo ufw allow http                     # Разрешаем HTTP-соединения (порт 80)
sudo ufw allow https                    # Разрешаем HTTPS-соединения (порт 443)
sudo ufw enable                         # Включаем UFW
sudo ufw status                         # Проверяем статус UFW

Вывод sudo ufw status должен показать, что SSH, HTTP и HTTPS разрешены.

6. Установка Fail2Ban

Fail2Ban сканирует логи сервера (например, SSH, веб-сервера) на предмет подозрительной активности (многочисленные неудачные попытки входа) и временно или навсегда блокирует IP-адреса злоумышленников.

sudo apt install fail2ban -y            # Устанавливаем Fail2Ban
sudo systemctl enable fail2ban          # Включаем автозапуск Fail2Ban при старте системы
sudo systemctl start fail2ban           # Запускаем сервис Fail2Ban
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local # Копируем конфиг для локальных изменений

Вы можете отредактировать /etc/fail2ban/jail.local для тонкой настройки, например, изменить bantime (время блокировки) или findtime (период, за который считаются неудачные попытки). По умолчанию, SSH уже защищен.

Установка ПО — пошагово

Теперь, когда сервер подготовлен, перейдем к установке необходимого программного обеспечения: Docker Engine и Docker Compose. Мы будем использовать актуальные версии, доступные в 2026 году.

1. Установка Docker Engine

Docker Engine – это основная платформа для запуска контейнеров. Мы будем устанавливать его из официального репозитория Docker, чтобы всегда иметь самые свежие версии.

# Обновляем список пакетов и устанавливаем зависимости для apt
sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y

# Добавляем официальный GPG-ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий Docker в sources.list
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновляем список пакетов apt после добавления репозитория Docker
sudo apt update

# Устанавливаем Docker Engine, Docker CLI и containerd.io
# Актуальные версии на 2026 год: Docker Engine 26.x, Docker CLI 26.x
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Проверяем, что Docker установлен и запущен
sudo systemctl status docker

Вывод sudo systemctl status docker должен показать, что Docker активен (active (running)).

2. Добавление пользователя в группу Docker

Чтобы избежать постоянного использования sudo при работе с Docker, добавьте вашего пользователя в группу docker.

sudo usermod -aG docker shlinkuser       # Добавляем shlinkuser в группу docker
newgrp docker                            # Активируем изменения для текущей сессии

Теперь вы можете проверить установку Docker без sudo:

docker run hello-world                   # Запускаем тестовый контейнер 'hello-world'

Если вы видите приветственное сообщение от Docker, значит, все настроено правильно.

3. Создание каталога для проекта Shlink

Создадим директорию, где будут храниться все файлы проекта Shlink.

mkdir ~/shlink-docker                    # Создаем директорию shlink-docker в домашнем каталоге пользователя
cd ~/shlink-docker                       # Переходим в созданную директорию

4. Загрузка файла Docker Compose для Shlink

Shlink предоставляет официальный файл docker-compose.yml, который включает в себя все необходимые сервисы: сам Shlink, базу данных (MariaDB по умолчанию) и веб-сервер Caddy для обратного прокси и HTTPS. Мы будем использовать его как основу.

На 2026 год, официальные образы Shlink и Caddy активно поддерживаются. Shlink версии 4.x и Caddy версии 2.x.

# Загружаем официальный docker-compose.yml файл
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/docker-compose.yml -o docker-compose.yml

# Загружаем пример файла .env
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/.env.example -o .env

# Загружаем пример Caddyfile
curl -sL https://raw.githubusercontent.com/shlinkio/shlink-web-client/master/docker/Caddyfile -o Caddyfile

Теперь у вас есть три ключевых файла в директории ~/shlink-docker: docker-compose.yml, .env и Caddyfile. Мы будем их редактировать на следующем этапе.

Конфигурация

После загрузки базовых файлов, необходимо их настроить под вашу среду. Это включает в себя переменные окружения, настройки базы данных, конфигурацию веб-сервера Caddy и DNS-записи.

1. Настройка файла .env

Файл .env содержит переменные окружения, которые используются Docker Compose для настройки сервисов. Отредактируйте его, заменив заполнители на ваши значения. Откройте файл для редактирования:

nano .env

Пример содержимого .env (обязательно измените DB_ROOT_PASSWORD, DB_PASSWORD, DEFAULT_DOMAIN и API_KEY):

# Database configuration
DB_DRIVER=mariadb
DB_HOST=db
DB_PORT=3306
DB_NAME=shlink
DB_USER=shlink
DB_PASSWORD=your_strong_db_password_here # Обязательно измените!
DB_ROOT_PASSWORD=your_strong_db_root_password_here # Обязательно измените!

# Shlink configuration
DEFAULT_DOMAIN=your-shlink-domain.com # Замените на ваш домен (например, s.example.com)
DEFAULT_BASE_URL=https://your-shlink-domain.com # Замените на ваш домен
DEFAULT_TITLE=My Custom Shlink
GEOLITE_LICENSE_KEY=your_geolite_license_key # Необязательно, для гео-аналитики. Получить на MaxMind.
API_KEY=your_shlink_api_key_here # Обязательно сгенерируйте и измените!
INITIAL_API_KEY=your_initial_api_key_for_first_login # Необязательно, для первого входа в админку
SHLINK_WEB_CLIENT_URL=https://shlink-web.your-shlink-domain.com # URL для веб-клиента, если разворачиваете его отдельно

Пояснения:

• DB_PASSWORD и DB_ROOT_PASSWORD: Очень важно использовать уникальные и надежные пароли.
• DEFAULT_DOMAIN: Это домен, который будет использоваться для сокращенных ссылок. Например, если вы хотите, чтобы ссылки выглядели как s.example.com/xyz, то здесь должно быть s.example.com. Убедитесь, что этот домен (или поддомен) указывает на IP-адрес вашего VPS.
• API_KEY: Сгенерируйте длинный, случайный ключ. Он будет использоваться для аутентификации при доступе к API Shlink и в веб-клиенте.
• GEOLITE_LICENSE_KEY: Если вы хотите использовать геоаналитику, вам нужно получить бесплатный ключ лицензии GeoLite2 от MaxMind (требуется регистрация). Без него геоаналитика не будет работать.

2. Настройка файла Caddyfile

Caddy будет выступать в роли обратного прокси, перенаправляя запросы к Shlink и автоматически управляя HTTPS-сертификатами через Let's Encrypt. Откройте файл для редактирования:

nano Caddyfile

Замените your-shlink-domain.com на ваш домен (тот же, что и в .env).

{
  email [email protected] # Замените на ваш email для Let's Encrypt уведомлений
}

your-shlink-domain.com { # Замените на ваш домен (например, s.example.com)
  reverse_proxy shlink:8080
}

# Если вы разворачиваете веб-клиент Shlink отдельно, добавьте секцию для него:
# shlink-web.your-shlink-domain.com { # Замените на ваш домен для веб-клиента
#   root  /app/dist
#   file_server
#   try_files {path} {path}/ /index.html
# }

# Пример docker-compose.yml (сокращенно)
version: '3.8'

services:
  db:
    image: mariadb:11.3 # Актуальная версия MariaDB на 2026 год
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - shlink_db_data:/var/lib/mysql
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}

  shlink:
    image: shlinkio/shlink:4.0.0 # Актуальная версия Shlink на 2026 год
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "8080:8080" # Внутренний порт Shlink
    depends_on:
      - db
    environment:
      DB_DRIVER: ${DB_DRIVER}
      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      DB_NAME: ${DB_NAME}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      DEFAULT_DOMAIN: ${DEFAULT_DOMAIN}
      DEFAULT_BASE_URL: ${DEFAULT_BASE_URL}
      DEFAULT_TITLE: ${DEFAULT_TITLE}
      GEOLITE_LICENSE_KEY: ${GEOLITE_LICENSE_KEY}
      API_KEY: ${API_KEY}
      INITIAL_API_KEY: ${INITIAL_API_KEY}

  caddy:
    image: caddy:2.7-alpine # Актуальная версия Caddy на 2026 год
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - shlink_caddy_data:/data
    depends_on:
      - shlink

volumes:
  shlink_db_data:
  shlink_caddy_data:

dig +short your-shlink-domain.com

docker compose up -d                     # Запускаем контейнеры в фоновом режиме

docker compose ps                        # Показывает статус запущенных контейнеров

curl -I https://your-shlink-domain.com/rest/v4/health

Бэкапы и обслуживание

Настройка Shlink – это только первый шаг. Для обеспечения долгосрочной стабильности и безопасности вашего URL-сокращателя крайне важны регулярные бэкапы и правильное обслуживание.

1. Что бэкапить

Для Shlink критически важны следующие компоненты:

• База данных: Содержит все сокращенные ссылки, статистику переходов, домены и настройки Shlink. Это самый важный компонент.
• Конфигурационные файлы: В первую очередь это .env и Caddyfile. Они определяют, как работают ваши сервисы.
• Данные Caddy: Каталог shlink_caddy_data (из docker-compose.yml) содержит TLS-сертификаты Let's Encrypt и другие данные Caddy. Важно сохранять его, чтобы избежать проблем с повторным получением сертификатов после восстановления.

2. Простой скрипт автобэкапа

Мы создадим простой скрипт, который будет выполнять дамп базы данных и архивировать важные файлы. Этот скрипт можно запускать по расписанию с помощью cron.

Создайте файл backup_shlink.sh в директории ~/shlink-docker:

nano ~/shlink-docker/backup_shlink.sh

Добавьте следующее содержимое (замените your_strong_db_root_password_here на ваш реальный пароль из .env):

#!/bin/bash

# Каталог для бэкапов
BACKUP_DIR="/var/backups/shlink"
DATE=$(date +%Y-%m-%d_%H-%M-%S)
DB_CONTAINER_NAME="shlink-docker-db-1" # Имя контейнера базы данных (проверьте через docker ps)
DB_NAME="shlink"
DB_USER="root"
DB_ROOT_PASSWORD="your_strong_db_root_password_here" # Используйте DB_ROOT_PASSWORD из .env

# Создаем директорию для бэкапов, если ее нет
mkdir -p "$BACKUP_DIR"

echo "Начинаем бэкап Shlink в $DATE..."

# 1. Бэкап базы данных
echo "Дамп базы данных..."
docker exec "$DB_CONTAINER_NAME" mariadb-dump -u "$DB_USER" -p"$DB_ROOT_PASSWORD" "$DB_NAME" > "$BACKUP_DIR/$DB_NAME-$DATE.sql"
if [ $? -eq 0 ]; then
    echo "Дамп базы данных успешно создан: $BACKUP_DIR/$DB_NAME-$DATE.sql"
else
    echo "Ошибка при создании дампа базы данных!"
fi

# 2. Архивирование конфигурационных файлов и данных Caddy
echo "Архивирование конфигурационных файлов и данных Caddy..."
tar -czvf "$BACKUP_DIR/shlink-config-caddy-data-$DATE.tar.gz" -C ~/shlink-docker .env Caddyfile shlink_caddy_data
if [ $? -eq 0 ]; then
    echo "Архив конфигурации и данных Caddy успешно создан: $BACKUP_DIR/shlink-config-caddy-data-$DATE.tar.gz"
else
    echo "Ошибка при создании архива конфигурации и данных Caddy!"
fi

# 3. Удаление старых бэкапов (старше 7 дней)
echo "Удаление старых бэкапов..."
find "$BACKUP_DIR" -type f -name ".sql" -mtime +7 -delete
find "$BACKUP_DIR" -type f -name ".tar.gz" -mtime +7 -delete
echo "Старые бэкапы удалены."

echo "Бэкап Shlink завершен."

chmod +x ~/shlink-docker/backup_shlink.sh

crontab -e

0 3    /home/shlinkuser/shlink-docker/backup_shlink.sh >> /var/log/shlink_backup.log 2>&1

Эта строка запускает скрипт каждый день в 3 часа ночи и перенаправляет его вывод в лог-файл /var/log/shlink_backup.log.

4. Куда складывать бэкапы (внешнее хранилище)

Хранение бэкапов на том же сервере, что и основной сервис, является рискованным. В случае выхода из строя диска VPS, вы потеряете и сервис, и бэкапы. Рекомендуется использовать внешнее хранилище:

• Облачное хранилище объектов (S3-совместимое): AWS S3, Backblaze B2, DigitalOcean Spaces, MinIO. Это надежные и масштабируемые решения. Вы можете использовать утилиты вроде s3cmd или rclone для автоматической синхронизации локальных бэкапов с облаком.
• Отдельный VPS: Если у вас есть второй VPS, вы можете настроить rsync или scp для копирования бэкапов на него.
• Локальный NAS/сервер: Для личного использования, можно копировать бэкапы на домашний сетевой накопитель.

Пример добавления rclone для отправки бэкапов на S3-совместимое хранилище:

# Установка rclone
sudo apt install rclone -y

# Настройка rclone (следуйте инструкциям на экране, выберите S3-совместимый провайдер)
rclone config

# Добавьте в скрипт backup_shlink.sh строку для синхронизации после создания архива:
# rclone sync "$BACKUP_DIR" "your_rclone_remote_name:your_bucket_name/shlink_backups"

5. Обновления: rolling vs maintenance window

Регулярные обновления важны для безопасности и получения новых функций.

• Обновление ОС: Выполняйте sudo apt update && sudo apt upgrade -y раз в несколько недель или месяцев. Для этого может потребоваться перезагрузка сервера.
• Обновление Docker-контейнеров:
  • Shlink: Чтобы обновить Shlink до новой версии, вам нужно изменить тег образа в docker-compose.yml (например, с shlinkio/shlink:4.0.0 на shlinkio/shlink:4.1.0).
  • База данных и Caddy: Аналогично, обновите теги образов mariadb и caddy.

  После изменения docker-compose.yml выполните:

  
  cd ~/shlink-docker
  docker compose pull                         # Скачиваем новые версии образов
  docker compose up -d                        # Пересоздаем контейнеры с новыми образами
  docker compose prune                        # Удаляем старые, неиспользуемые образы
              

  Это приведет к кратковременному простою сервиса (несколько секунд или минут), поэтому лучше выполнять в "окно обслуживания" (maintenance window), когда трафик минимален. Перед обновлением всегда делайте бэкап!

Troubleshooting + FAQ

В процессе установки и эксплуатации Shlink могут возникнуть различные проблемы. Здесь мы рассмотрим наиболее распространенные из них и дадим рекомендации по их устранению.

Почему мой домен не работает или Caddy не получает сертификат?

Это одна из самых частых проблем.

Что проверить:

• DNS-записи: Убедитесь, что A-запись для вашего домена (например, s.example.com) правильно настроена и указывает на IP-адрес вашего VPS. Используйте dig your-shlink-domain.com на локальной машине, чтобы проверить это. Распространение DNS может занять до 24 часов, но обычно происходит быстрее.
• Порты 80 и 443: Проверьте, что порты 80 (HTTP) и 443 (HTTPS) открыты на вашем VPS. Caddy должен иметь возможность слушать эти порты для получения сертификатов Let's Encrypt. Используйте sudo ufw status или sudo ss -tulpn | grep -E ':(80|443)'. Убедитесь, что никакой другой сервис не занимает эти порты.
• Caddyfile: Проверьте синтаксис Caddyfile на опечатки. Убедитесь, что домен в Caddyfile точно совпадает с тем, который вы используете.
• Логи Caddy: Проверьте логи контейнера Caddy на наличие ошибок: docker compose logs caddy. Ищите сообщения об ошибках при получении сертификатов.

Как фиксить: Исправьте DNS-запись, откройте порты в брандмауэре, исправьте Caddyfile и перезапустите Caddy: docker compose restart caddy.

Shlink не сокращает ссылки или выдает ошибки API.

Если веб-интерфейс или API Shlink не работают должным образом, проблема может быть в конфигурации Shlink или подключении к базе данных.

Что проверить:

• Логи Shlink: Проверьте логи контейнера Shlink: docker compose logs shlink. Ищите ошибки, связанные с подключением к базе данных или ошибками приложения.
• Файл .env: Убедитесь, что все переменные окружения, особенно связанные с базой данных (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME) и доменом (DEFAULT_DOMAIN, API_KEY), настроены правильно и соответствуют действительности.
• Доступность базы данных: Убедитесь, что контейнер базы данных (db) запущен и работает: docker compose ps. Попробуйте подключиться к базе данных изнутри контейнера Shlink: docker exec -it shlink-docker-shlink-1 mariadb -u shlink -p (введите пароль).

Как фиксить: Исправьте ошибки в .env или docker-compose.yml, затем перезапустите сервисы: docker compose up -d --force-recreate shlink.

Какой VPS-конфиг минимально подойдёт?

Для минимальной установки Shlink с Docker, базой данных и Caddy, вам понадобится VPS с 1 vCPU, 1 GB RAM и 20 GB NVMe/SSD диска. Этого будет достаточно для личного использования или небольшого проекта с умеренным количеством ссылок и трафика. Однако, для более стабильной работы и возможности роста, а также для комфортной работы ОС и Docker-сервисов, рекомендуется иметь не менее 2 vCPU и 2-4 GB RAM. Диск NVMe/SSD значительно улучшит производительность базы данных. Можно рассмотреть варианты VPS с 2 vCPU и 4 GB RAM, что обеспечит хороший баланс между стоимостью и производительностью.

Что выбрать — VPS или dedicated для этой задачи?

Для большинства сценариев использования Shlink, VPS (виртуальный частный сервер) является оптимальным выбором. Shlink сам по себе не является чрезвычайно ресурсоемким приложением, и современные VPS предлагают достаточно производительности, гибкости и масштабируемости по доступной цене. VPS идеально подходит для индивидуальных разработчиков, небольших команд, SaaS-стартапов на ранних стадиях и личных проектов. Dedicated сервер (выделенный сервер) нужен только в очень специфических случаях: если вы ожидаете экстремально высокие нагрузки (десятки миллионов кликов в день), если вам требуется максимальная производительность ввода-вывода для базы данных, или если вы планируете размещать на этом же сервере множество других ресурсоемких приложений, требующих полной изоляции аппаратных ресурсов. В большинстве случаев переплачивать за dedicated сервер для Shlink не имеет смысла.

Как обновить Shlink или другие компоненты?

Обновление компонентов Docker Compose происходит путем изменения тега образа в файле docker-compose.yml на новую версию (например, shlinkio/shlink:4.0.0 на shlinkio/shlink:4.1.0) и последующего выполнения команд:

docker compose pull                 # Загружает новые версии образов
docker compose up -d                # Пересоздает контейнеры с новыми образами
docker image prune                  # Удаляет старые, неиспользуемые образы
    

Перед обновлением всегда создавайте полный бэкап базы данных и конфигурационных файлов. Обновления ОС выполняются через sudo apt update && sudo apt upgrade -y.

Могу ли я использовать другой веб-сервер вместо Caddy (например, Nginx)?

Да, вы можете использовать Nginx или любой другой обратный прокси. Для этого вам потребуется вручную настроить Nginx для проксирования запросов к контейнеру Shlink (обычно на внутренний порт 8080) и отдельно настроить получение и обновление TLS-сертификатов (например, с помощью Certbot). Caddy был выбран в этом руководстве из-за его простоты в настройке и автоматического управления HTTPS, что значительно упрощает процесс для большинства пользователей.

Как получить GeoLite2 License Key?

Для получения ключа GeoLite2 License Key, который Shlink использует для геоаналитики, вам нужно зарегистрироваться на сайте MaxMind. После регистрации вы сможете сгенерировать свой ключ в разделе "My Account" -> "Manage License Keys". Вставьте этот ключ в переменную GEOLITE_LICENSE_KEY в файле .env.

Выводы и следующие шаги

Поздравляем! Вы успешно настроили и развернули собственный URL-сокращатель Shlink на вашем VPS с использованием Docker. Теперь у вас есть мощный инструмент для управления ссылками, который обеспечивает полный контроль над вашими данными, брендирование через собственный домен и детальную аналитику переходов. Этот опыт не только дал вам функциональный сервис, но и укрепил ваши навыки в работе с Docker, Linux и администрировании серверов.

Куда двигаться дальше?

• Подключение веб-клиента Shlink: Разверните официальный веб-клиент Shlink (Shlink Web Client) в отдельном Docker-контейнере или на другом поддомене. Это предоставит вам удобный графический интерфейс для управления ссылками без необходимости использовать API или командную строку.
• Интеграция с другими сервисами: Используйте мощный API Shlink для интеграции сокращения ссылок в ваши собственные приложения, CRM-системы или скрипты автоматизации.
• Мониторинг и логирование: Настройте более продвинутый мониторинг вашего VPS и Docker-контейнеров с помощью таких инструментов, как Prometheus/Grafana или ELK Stack, чтобы отслеживать производительность и выявлять потенциальные проблемы.
• Масштабирование: Если ваш Shlink станет очень популярным, рассмотрите возможность масштабирования базы данных на отдельный сервер или использования кластера Docker Swarm/Kubernetes для обеспечения высокой доступности и обработки больших нагрузок.