Установка Shlink на Ubuntu через Docker и Nginx

Оглавление

• Почему стоит использовать Shlink
• Требования и подготовка
• Установка Docker и зависимостей
• Получение ключа GeoLite2
• Развёртывание Shlink и PostgreSQL в Docker
• Установка и привязка веб‑интерфейса Shlink
• Создание обратного SSL‑прокси на Nginx
• Создание первой короткой ссылки
• Проверка, отладка и критерии приёмки
• Рекомендации по безопасности и обслуживание
• Чек‑листы, сценарии тестирования и справочник терминов

Почему использовать Shlink

Shlink — это самохостимый сервис для сокращения ссылок с поддержкой кастомного домена. Преимущества:

• Контроль над данными и конфиденциальностью — вы храните всё у себя.
• Поддержка кастомного домена и многофункциональные опции (QR‑коды, мультисегментные слуги, перенаправления).
• Лёгкое развёртывание в контейнерах и интеграция с Nginx/Certbot для SSL.

Пояснение терминов в одну строку:

• Слуг — читаемая часть короткой ссылки после домена (пример: example.com/slug).
• Reverse proxy — веб‑сервер, который принимает внешние соединения и проксирует их внутренним сервисам.

Требования и подготовка

Перед началом убедитесь, что у вас есть:

• VPS или сервер под управлением Ubuntu 22.04 LTS.
• Доступ с правами sudo.
• Зарегистрированный домен и доступ к управлению DNS (создание A‑записей).
• Минимум 1 CPU, 1–2 ГБ RAM для небольшой инсталляции; для боевой нагрузки — планируйте ресурсы по трафику.

Важно: в этом руководстве предполагается использование публичного домена и прямого назначения A‑записи на IP VPS. Если вы планируете работу за NAT/LoadBalancer, подстройте DNS и проксирование соответственно.

Установка Docker и зависимостей

1. Добавьте ключ подписи Docker и репозиторий:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
sudo nano /etc/apt/sources.list.d/docker.list

Внутри открытого файла вставьте строку:

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable

2. Обновите индексы и установите пакеты:

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin nginx

3. Установите базовые snap‑пакеты и certbot:

sudo snap install core
sudo snap install certbot --classic

Примечание: если на сервере уже установлен Docker другим способом (snap, apt из другого репозитория), убедитесь, что сервисы совместимы и что вы используете рекомендуемый upstream‑репозиторий Docker.

Получение ключа GeoLite2 (MaxMind)

Shlink может использовать GeoLite2 для грубой геолокации переходов. Для этого требуется ключ лицензии MaxMind.

1. Откройте страницу регистрации GeoLite2 Licensing Sign Up (MaxMind).
2. Заполните форму, подтвердите e‑mail и создайте пароль для учётной записи MaxMind.
3. Войдите в аккаунт, откройте Dashboard → Manage License Keys → Generate new license key → Confirm.
4. Скопируйте сгенерированный ключ в безопасный файл на сервере (например, /root/maxmind.key).

Важно: ключ — секретный параметр. Храните его безопасно и не выкладывайте в публичные репозитории.

Развёртывание Shlink и PostgreSQL в Docker

Создадим виртуальную Docker‑сеть для связи контейнеров:

sudo docker network create -d bridge --subnet=10.0.0.0/24 --gateway=10.0.0.1 shlink-network

Запустите PostgreSQL (привязываемый только к localhost контейнера и внутренней сети):

sudo docker run -d \
  --name shlink-db \
  -e POSTGRES_PASSWORD="REPLACE_WITH_STRONG_PASSWORD" \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_DB=shlink \
  -p 127.0.0.1:5432:5432 \
  --restart always \
  --network shlink-network \
  postgres:12.1

Совет: сгенерируйте сильный пароль, например:

cat /dev/urandom | tr -dc 'A-Za-z0-9' | fold -w 32 | head -n 1 > /root/shlink_db_password.txt

Запустите backend Shlink (замените переменные на ваши значения):

sudo docker run -d \
  --name shlink-stable \
  -p 8081:8080 \
  -e DEFAULT_DOMAIN="YOUR-ROOT.DOMAIN" \
  -e IS_HTTPS_ENABLED=true \
  -e GEOLITE_LICENSE_KEY="REPLACE_WITH_MAXMIND_KEY" \
  -e DB_DRIVER=postgres \
  -e DB_USER=postgres \
  -e DB_PASSWORD="REPLACE_WITH_DB_PASSWORD" \
  -e DB_HOST=shlink-db \
  --network shlink-network \
  shlinkio/shlink:stable

Пояснения:

• DEFAULT_DOMAIN — ваш корневой домен, например helloserver.top.
• IS_HTTPS_ENABLED — укажите true, чтобы Shlink знал, что доступ идёт через HTTPS (Nginx будет SSL‑терминировать).

Если контейнер успешно стартовал, проверьте логи:

sudo docker logs -f shlink-stable

Установка и привязка веб‑интерфейса Shlink

Сгенерируйте API‑ключ на бэкенде:

sudo docker exec -it shlink-stable shlink api-key:generate

Скопируйте полученный ключ и запустите веб‑клиент Shlink:

sudo docker run -d \
  --name shlink-client \
  -p 8080:8080 \
  -e SHLINK_SERVER_URL="https://YOUR-ROOT.DOMAIN" \
  -e SHLINK_SERVER_API_KEY="REPLACE_WITH_API_KEY" \
  --network shlink-network \
  shlinkio/shlink-web-client

Проверьте список контейнеров:

sudo docker container ls

Создание SSL обратного прокси на Nginx

Цель: внешние запросы на ваши домены принимать через Nginx и проксировать к контейнерам, работающим на localhost:8080/8081.

1. Создайте A‑записи в DNS:
   • YOUR-ROOT.DOMAIN → IP вашего сервера
   • SUBDOMAIN.YOUR-ROOT.DOMAIN (например admin) → IP вашего сервера

2. Создайте конфигурацию сайта:

sudo nano /etc/nginx/sites-available/shlink

Вставьте следующий пример конфигурации и замените домены на ваши:

server {
    server_name YOUR-ROOT.DOMAIN;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

server {
    server_name SUBDOMAIN.YOUR-ROOT.DOMAIN;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

3. Активируйте конфиг и перезагрузите Nginx:

sudo ln -s /etc/nginx/sites-available/shlink /etc/nginx/sites-enabled/
sudo systemctl reload nginx

4. Зарегистрируйте certbot и получите сертификат для обоих доменов:

sudo certbot register --agree-tos -m YOUR@EMAIL.ADDRESS
sudo certbot --nginx -d YOUR-ROOT.DOMAIN -d SUBDOMAIN.YOUR-ROOT.DOMAIN

После успешного получения сертификатов certbot автоматически обновит конфигурацию Nginx, добавив блоки для SSL и перенаправления HTTP → HTTPS.

Создание вашей первой короткой ссылки

1. Откройте веб‑интерфейс (например https://admin.helloserver.top).
2. В меню нажмите Shlink.

3. В поле «URL для сокращения» вставьте длинный URL.
4. При необходимости добавьте метаданные (описание, теги, пользовательский slug) и нажмите «Сохранить».

5. Откройте полученную короткую ссылку в новой вкладке, затем в панели Shlink нажмите Visits, чтобы просмотреть статистику переходов.

Проверка, отладка и критерии приёмки

Критерии приёмки:

• Frontend доступен по HTTPS на SUBDOMAIN.YOUR-ROOT.DOMAIN.
• Backend отвечает на YOUR-ROOT.DOMAIN (корневой домен) и возвращает статус 200 на корневой путь.
• Созданная короткая ссылка перенаправляет на целевой URL.
• Analytics/Visits показывают как минимум одно посещение при тесте.

Полезные команды для отладки:

# список контейнеров
sudo docker ps

# логи контейнера
sudo docker logs -f shlink-stable

# проверка статуса nginx
sudo systemctl status nginx

# проверка SSL сертификата
sudo certbot certificates

Flowchart принятия решения (какой домен куда проксировать):

flowchart TD
  A[Внешний запрос] --> B{Host}
  B -->|YOUR-ROOT.DOMAIN| C[Проксировать на 127.0.0.1:8081 'backend']
  B -->|SUBDOMAIN.YOUR-ROOT.DOMAIN| D[Проксировать на 127.0.0.1:8080 'frontend']
  C --> E[Shlink backend]
  D --> F[Shlink frontend]

Рекомендации по безопасности и обслуживание

• Регулярно обновляйте образы Docker (проверяйте changelog shlinkio/shlink).
• Храните секреты (пароли, API‑ключи, MaxMind key) в защищённом хранилище или в Docker secrets / vault.
• Отключите прямой внешний доступ к базе данных — используйте внутреннюю сеть Docker.
• Настройте автоматическое обновление Certbot и мониторинг статуса nginx.
• Ограничьте доступ к административному субдомену через VPN или базовую аутентификацию (htpasswd) при необходимости.

Пример настройки базовой защиты для админ‑субдомена (nginx):

location / {
  auth_basic "Restricted";
  auth_basic_user_file /etc/nginx/.htpasswd;
  proxy_pass http://127.0.0.1:8080;
  # остальные proxy_set_header ...
}

Создать .htpasswd:

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd adminuser
sudo systemctl reload nginx

Чек‑лист развёртывания (роли и задачи)

Администратор сервера:

• Проверить доступность VPS и права sudo.
• Настроить DNS A‑записи.
• Установить Docker и Nginx.

DevOps / Инженер развёртывания:

• Создать Docker‑сеть и запустить контейнер PostgreSQL.
• Запустить backend и frontend Shlink, получить API‑ключ.
• Настроить Nginx и Certbot.

Собственник продукта / менеджер:

• Подтвердить корректность корневого домена и subdomain.
• Проверить приватность данных и необходимость GeoLite.

Сценарии тестирования и приемочные тесты

Тест 1 — Доступность фронтенда:

• Открыть https://SUBDOMAIN.YOUR-ROOT.DOMAIN — страница должна загрузиться.

Тест 2 — Создание ссылки и перенаправление:

• Создать новую короткую ссылку. Открыв URL, получить редирект на целевой адрес.

Тест 3 — Геолокация и аналитика:

• Сделать тестовый клик и убедиться, что Visits отображает запись (время задержки обработки может варьироваться).

Частые проблемы и решения

• Ошибка при получении сертификата certbot: проверьте, что A‑запись указывает на ваш сервер и порты 80/443 открыты в брандмауэре.
• Backend не стартует: проверьте переменные окружения, особенно DB_HOST/DB_PASSWORD и доступность PostgreSQL.
• Неверные редиректы: убедитесь, что IS_HTTPS_ENABLED=true и что Nginx корректно проксирует заголовки Host и X‑Forwarded‑For.

Мини‑методология резервного восстановления

1. Регулярно делайте дамп PostgreSQL:

sudo docker exec shlink-db pg_dump -U postgres shlink > /root/shlink_dump_$(date +%F).sql

2. Резервируйте /root/maxmind.key и файлы конфигурации Nginx (+/etc/letsencrypt) в offsite‑хранилище.
3. Для восстановления: восстановить базу, пересоздать контейнеры с теми же переменными окружения, перезапустить Nginx.

Краткий справочник терминов

• Shlink: самохостимый сервис для сокращения ссылок.
• Backend: сервер, который отвечает за создание и хранение коротких ссылок.
• Frontend: веб‑интерфейс для управления ссылками.
• GeoLite2: база MaxMind для приблизительной геолокации по IP.

Итоги

Shlink — удобный инструмент для тех, кто хочет контролировать короткие ссылки и аналитику, оставаясь при этом в своей инфраструктуре. Следуя этому руководству, вы получите рабочую установку с HTTPS, отдельной базой данных и веб‑интерфейсом. Регулярное обновление, резервное копирование и базовая защита админ‑доступа помогут поддерживать инсталляцию в рабочем состоянии.

Важно: после развёртывания протестируйте все ключевые сценарии (создание ссылки, редирект, запись visits) и настройте мониторинг и резервные копии.

Image credit: Carlos Muza via Unsplash and Shlink.io Developers. All alterations and screenshots by Ramces Red.