Как самостоятельно разместить Shlink в 2026 году: домены, API-ключи и статистика
Практическое руководство по самостоятельному размещению Shlink: Docker, порты, постоянное хранение данных, TLS, безопасность, резервные копии и проблемы, которые мешают использовать сервис в production. Пошаговая инструкция.
Самостоятельное размещение Shlink становится интересным после первого redeploy, а не после первого docker run. Если сгенерированные ссылки используют HTTP или миграции не могут подключиться к базе данных, Docker всё равно может сообщать о полностью исправном процессе. Приведённое ниже развертывание построено вокруг наблюдаемого поведения: создать короткий URL через API, перейти по редиректу, записать посещения и посмотреть статистику в веб-клиенте.
Назначение Shlink сформулировано однозначно: API-first сервис сокращения ссылок со статистикой. Это описание подсказывает, что должно оставаться публичным, что следует держать приватным и какие данные должна восстанавливать резервная копия.
От чего зависит Shlink
Состояние процесса и состояние самого продукта — разные вещи для Shlink. Порт 8080 может отвечать, даже если пользовательская транзакция по-прежнему завершается ошибкой. Сетевой контракт Shlink в production — это Postgres или MariaDB, а также опциональный Redis. Держите приватные endpoints во внутреннем DNS, разрешайте только необходимые исходящие подключения и выдайте Shlink сервисные credentials с ограниченной областью действия.
Выполняйте эту проверку готовности после существенных изменений конфигурации: создайте короткий URL через API, перейдите по редиректу, запишите посещения и изучите статистику в веб-клиенте. Не включайте дорогостоящие внешние проверки в liveness probes, чтобы сбой провайдера не приводил к циклу перезапусков. При планировании ресурсов отслеживайте пропускную способность редиректов, записи в базу данных, загрузки геоданных и поведение cache — это лучше отражает реальные нагрузки Shlink, чем запросы страниц.
Volumes — только первый уровень восстановления
В стандартном образе Shlink не предполагается хранение доступного для записи состояния приложения. Сохраняйте базу данных, API-ключи и все импортированные данные о посещениях, включая зафиксированный digest и проверенную конфигурацию маршрутов, вместо резервного копирования пустой файловой системы контейнера.
Создайте Shlink с нуля на другом хосте и убедитесь, что домены, короткие коды, tags и записи о посещениях восстановились, а каждый проверенный короткий URL перенаправляет пользователя точно так же. Если добавляется отдельная база данных, room server или слой аутентификации, назначьте для каждого такого компонента отдельного ответственного за восстановление. В руководстве по переходу от Git к production показано, как воспроизводимый artifact заменяет резервную копию контейнера.
Зафиксируйте команду восстановления и тест с известным результатом вместе с release. План восстановления stateless-сервиса успешен, если поведение воспроизводится из доверенных входных данных; он не должен зависеть от копирования непрозрачного работающего контейнера.
Защитите ценную часть Shlink
Безопасное развертывание Shlink начинается с сокращения полномочий. Не выставляйте REST API key и не меняйте публичный домен после публикации ссылок; вместо этого храните API-ключи вне browser code, используйте HTTPS и ограничьте административный доступ, оставив редиректы публичными.
DEFAULT_DOMAIN — это настройка, а не секрет; храните её значение явно, защищая при этом отдельные credentials, используемые Shlink. Ограничьте административные routes, используйте private DNS для зависимостей и проверяйте каждый bind mount. При централизованной отправке логов фильтруйте секреты и приватное содержимое до того, как они покинут сервер.
Превратите smoke test Shlink в проверку release
Для Shlink заранее определите транзакцию, которая считается успешной: создайте короткий URL через API, перейдите по редиректу, запишите посещения и изучите статистику в веб-клиенте. Храните её prerequisites, ожидаемый ответ и шаги очистки в version control без секретных значений. Зафиксируйте image, использованный для создания этого эталона.
Используйте транзакцию для проверки замены и независимого восстановления. Восстановленный сервис можно считать приемлемым только тогда, когда домены, короткие коды, tags и записи о посещениях возвращаются, а каждый проверенный короткий URL перенаправляет пользователя точно так же. Одновременно отслеживайте пропускную способность редиректов, записи в базу данных, загрузки геоданных и поведение cache, а самый медленный или наиболее ограниченный компонент превратите в service-level alert.
В gate также должен входить негативный сценарий: временно запретите тестовой identity доступ к Postgres или MariaDB, а также к опциональному Redis для production. Убедитесь, что Shlink выдаёт понятную для диагностики ошибку, сохраняя данные, затем восстановите корректное состояние и повторите успешную транзакцию. Хранение обоих результатов не позволяет поверхностному health endpoint стать единственным свидетельством работоспособности production-сервиса.
Запустите Shlink, не скрывая важные компоненты
Следующая команда делает границу контейнера видимой и не создаёт видимость, будто все внешние сервисы уже настроены.
docker run -d \
--name shlink \
--restart unless-stopped \
-p 127.0.0.1:8080:8080 \
-e DEFAULT_DOMAIN=go.example.com \
shlinkio/shlink:stable
До открытия ingress проверьте итоговые environment variables, mounts и listener. Добавьте проверенные параметры подключения к Postgres или MariaDB, а также к опциональному Redis для production; для приватных сервисов используйте приватные имена. Успешный запуск завершается не тогда, когда docker ps выводит Up, а когда вы можете создать короткий URL через API, перейти по редиректу, записать посещения и изучить статистику в веб-клиенте.
Задайте для Shlink один canonical address
Публичная граница Shlink должна состоять из одного canonical hostname, автоматического TLS и одной внутренней цели на 8080. Установите DEFAULT_DOMAIN и IS_HTTPS_ENABLED до создания коротких URL, чтобы клиенты возвращались по адресу, который распознаёт сервис.
Если acceptance transaction завершается ошибкой, классифицируйте первую проблему. Проблемы с DNS, сертификатом и 502 относятся к чек-листу проверки TLS. Условие «сгенерированные ссылки используют HTTP или миграции не могут подключиться к базе данных» относится к уровню приложения после того, как запрос успешно достиг Shlink.
Диагностируйте Shlink, который выглядит исправным
Для Shlink отслеживайте не процесс, а транзакцию: создайте короткий URL через API, перейдите по редиректу, запишите посещения и изучите статистику в веб-клиенте. Сопоставляйте её latency и error rate с пропускной способностью редиректов, записями в базу данных, загрузками геоданных и поведением cache, чтобы alert указывал на ограниченный компонент.
Репетиция upgrade должна учитывать, что database migrations и API compatibility следует выполнять поэтапно, поскольку опубликованные короткие ссылки не могут ждать ручного восстановления. Выполните restore, migrate и транзакцию до замены production-сервиса. Если сгенерированные ссылки используют HTTP или миграции не могут подключиться к базе данных, не удаляйте данные ради успешного запуска; последовательно сравните version, variables, mounts и доступность зависимостей.
Оставьте Shlink явным, а маршрутизацию поручите Dockup
One-click deployment Shlink в Dockup должен делать замену безопасной: route продолжает указывать на 8080, секреты не встраиваются в image, а постоянные paths возвращаются в новый контейнер. Такое же развертывание можно запускать на compute-инфраструктуре Dockup или на подключённой машине.
Завершите работу, специфичную для приложения: подключите и протестируйте Postgres или MariaDB, а также опциональный Redis для production, задайте canonical public address и выполните эту acceptance check: создайте короткий URL через API, перейдите по редиректу, запишите посещения и изучите статистику в веб-клиенте. Добавьте результат restore в runbook до появления реальных пользователей.
Часто задаваемые вопросы
Что нужно Shlink для развертывания в production?
Направьте контейнер Shlink через порт 8080 на один HTTPS origin. Требование к поддерживающей сети — Postgres или MariaDB, а также опциональный Redis для production. Не считайте Shlink готовым, пока не сможете создать короткий URL через API, перейти по редиректу, записать посещения и изучить статистику в веб-клиенте.
Какие данные Shlink должны входить в резервную копию?
Стандартному образу Shlink не нужен обязательный mount с данными приложения. Сохраняйте конфигурацию его развертывания и отдельно создавайте резервные копии любого подключённого состояния; восстановление считается успешным, когда домены, короткие коды, tags и записи о посещениях возвращаются, а каждый проверенный короткий URL перенаправляет пользователя точно так же.
Требуется ли Shlink HTTPS за reverse proxy?
Используйте HTTPS для публичного origin Shlink, а порт 8080 оставьте во внутреннем route. Корректно задайте настройку Shlink: установите DEFAULT_DOMAIN и IS_HTTPS_ENABLED до создания коротких URL. Для Shlink HTTPS защищает credentials и пользовательское содержимое при передаче и обеспечивает согласованное поведение клиентов, зависящее от origin.
Как тестировать upgrade Shlink?
Восстановите текущее состояние Shlink в изолированном развертывании, примените candidate version и повторите acceptance transaction. Уделите этому особое внимание, поскольку database migrations и API compatibility следует выполнять поэтапно: опубликованные короткие ссылки не могут ждать ручного восстановления. Сохраняйте предыдущий image Shlink, пока не будут понятны границы data migration и rollback.