Як самостійно розгорнути Shlink у 2026 році: домени, API-ключі та статистика

Самостійне розгортання Shlink стає справді важливим після першого повторного розгортання, а не після першого docker run. Якщо згенеровані посилання використовують HTTP або міграції не можуть підключитися до бази даних, Docker усе одно може повідомляти про абсолютно справний процес. Наведене нижче розгортання побудоване навколо спостережуваної поведінки: створити коротке URL через API, перейти за його redirect, записати візити й переглянути статистику у web-клієнті.

Призначення Shlink чітко визначене: API-first сервіс скорочення посилань зі статистикою. Цей опис показує, що має залишатися публічним, що слід зберігати приватним і які дані має відновлювати резервна копія.

Від чого залежить Shlink

Справність процесу та справність продукту для Shlink — різні речі. Порт 8080 може відповідати, навіть якщо транзакція, яку виконує користувач, усе ще завершується помилкою. Мережевий контракт Shlink передбачає Postgres або MariaDB, а для production — опційно Redis. Тримайте приватні endpoints у внутрішньому DNS, дозволяйте лише необхідні вихідні запити й надайте Shlink service credential з обмеженими правами.

Виконуйте цю перевірку готовності після суттєвих змін конфігурації: створіть коротке URL через API, перейдіть за його redirect, запишіть візити й перегляньте статистику у web-клієнті. Не додавайте дорогі зовнішні перевірки до liveness probes, щоб збій у провайдера не спричинив цикл перезапусків. Під час роботи з capacity відстежуйте throughput redirect-запитів, записи в базу даних, завантаження геоданих і поведінку cache — це ближче до реального навантаження Shlink, ніж запити сторінок.

Volumes — лише перший рівень відновлення

У стандартному image Shlink не передбачається збереження стану застосунку, доступного для запису. Зберігайте базу даних, API-ключі та всі імпортовані дані про візити, а також pinned digest і перевірену конфігурацію маршрутів, замість резервного копіювання порожньої файлової системи контейнера.

Розгорніть Shlink з нуля на іншому хості та перевірте, що домени, короткі коди, теги й записи про візити відновилися, а кожне вибране коротке URL перенаправляє так само. Якщо додається окрема база даних, room server або authentication layer, призначте для кожного такого компонента окремого відповідального за відновлення. У посібнику з Git до production показано, як відтворюваний artifact замінює резервну копію контейнера.

Зберігайте команду відновлення та тест із відомим очікуваним результатом разом із release. План відновлення stateless-сервісу успішний, якщо відтворює поведінку з надійних вхідних даних; він не має залежати від копіювання непрозорого запущеного контейнера.

Захистіть найціннішу частину Shlink

Безпечне розгортання Shlink починається з обмеження повноважень. Не відкривайте REST API key і не змінюйте public domain після публікації посилань; натомість зберігайте API-ключі поза browser code, використовуйте HTTPS і обмежуйте адміністративний доступ, залишаючи redirect-запити публічними.

DEFAULT_DOMAIN — це конфігурація, а не секрет; зберігайте його значення явним, захищаючи окремі credentials, які використовує Shlink. Обмежте адміністративні маршрути, використовуйте private DNS для залежностей і перевіряйте кожен bind mount. Якщо логи надсилаються централізовано, відфільтровуйте секрети та приватний вміст до того, як вони залишать сервер.

Перетворіть smoke test Shlink на перевірку release

Для Shlink визначте транзакцію з відомим коректним результатом до запуску: створіть коротке URL через API, перейдіть за його redirect, запишіть візити й перегляньте статистику у web-клієнті. Зберігайте її prerequisites, очікувану відповідь і кроки очищення у version control без значень секретів. Зафіксуйте image, використаний для формування цього еталона.

Використовуйте цю транзакцію для перевірки заміни та незалежного restore. Відновлений сервіс можна вважати прийнятним лише тоді, коли домени, короткі коди, теги й записи про візити відновилися, а кожне вибране коротке URL перенаправляє так само. Одночасно спостерігайте за throughput redirect-запитів, записами в базу даних, завантаженнями геоданих і поведінкою cache, а найповільніший або найбільш обмежений компонент перетворіть на service-level alert.

Gate також має містити негативний сценарій: тимчасово забороніть тестовій identity доступ до Postgres або MariaDB, а для production — опційно до Redis. Переконайтеся, що 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, перевірте resolved environment, mounts і listener. Додайте перевірені connection settings для Postgres або MariaDB, а для production — опційно Redis; для приватних сервісів використовуйте приватні імена. Успішний запуск завершується тоді, коли ви можете створити коротке URL через API, перейти за його redirect, записати візити й переглянути статистику у web-клієнті, а не тоді, коли docker ps виводить Up.

Надайте 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, перейдіть за його redirect, запишіть візити й перегляньте статистику у web-клієнті. Поєднуйте її latency та error rate з throughput redirect-запитів, записами в базу даних, завантаженнями геоданих і поведінкою cache, щоб alert указував на обмежений компонент.

Репетиція upgrade має охоплювати поетапне виконання міграцій бази даних і перевірку сумісності API, оскільки опубліковані короткі посилання не можуть чекати на ручне виправлення. Виконайте restore, міграцію та транзакцію до заміни production-сервісу. Якщо згенеровані посилання використовують HTTP або міграції не можуть підключитися до бази даних, не видаляйте дані, щоб зробити запуск успішним; послідовно порівняйте version, variables, mounts і доступність залежностей.

Нехай Shlink залишається явним, а Dockup відповідає за routing

One-click deployment Shlink у Dockup має робити заміну безпечною: маршрут і далі має вести на 8080, секрети не повинні бути вбудовані в image, а persistent paths мають відновлюватися в новому контейнері. Те саме розгортання може працювати на compute Dockup або на підключеній машині.

Завершіть специфічні для застосунку налаштування підключенням і тестуванням Postgres або MariaDB, а для production — опційно Redis, застосуванням canonical public address і виконанням цієї acceptance check: створіть коротке URL через API, перейдіть за його redirect, запишіть візити й перегляньте статистику у web-клієнті. Додайте результат restore до runbook до того, як з’являться реальні користувачі.

Поширені запитання

Що потрібно Shlink для production deployment?

Спрямуйте контейнер Shlink через порт 8080 до одного HTTPS origin. Мережева вимога для залежностей — Postgres або MariaDB, а для production — опційно Redis. Не вважайте Shlink готовим, доки не зможете створити коротке URL через API, перейти за його redirect, записати візити й переглянути статистику у web-клієнті.

Які дані Shlink потрібно включати до резервної копії?

Стандартний image Shlink не має обов’язкового mount для даних застосунку. Зберігайте його deployment configuration і створюйте резервні копії всього підключеного стану окремо; відновлення успішне, коли домени, короткі коди, теги й записи про візити повернулися, а кожне вибране коротке URL перенаправляє так само.

Чи потрібен Shlink HTTPS за reverse proxy?

Використовуйте HTTPS для public origin Shlink, а порт 8080 залишайте у внутрішньому маршруті. Правильно застосуйте налаштування Shlink: установіть DEFAULT_DOMAIN та IS_HTTPS_ENABLED до створення коротких URL. Для Shlink HTTPS захищає credentials або користувацький вміст під час передавання й забезпечує узгоджену поведінку клієнта, залежну від origin.

Як тестувати upgrade Shlink?

Відновіть поточний стан Shlink в ізольованому deployment, застосуйте candidate version і повторіть acceptance transaction. Зверніть особливу увагу на поетапне виконання міграцій бази даних і перевірку сумісності API, оскільки опубліковані короткі посилання не можуть чекати на ручне виправлення. Зберігайте попередній image Shlink, доки не визначите межі міграції даних і rollback.