Как да хоствате Shlink самостоятелно през 2026 г.: домейни, API ключове и статистика
Практическо ръководство за самостоятелно хостване на Shlink с Docker, портове, постоянни данни, TLS, сигурност, backup-и и проблемите, които блокират използването в production. Стъпка по стъпка.
Самостоятелното хостване на Shlink става интересно при първото redeploy-ване, а не при първото docker run. Ако генерираните линкове използват HTTP или migrations не могат да достигнат до базата данни, Docker все още може да отчита напълно здрав процес. Разгръщането по-долу е организирано около наблюдаемо поведение: създаване на кратък URL чрез API, следване на неговия redirect, записване на посещения и преглеждане на статистиката от web клиента.
Предназначението на Shlink е ясно: API-first link shortener със статистика. Това описание показва какво трябва да остане публично, какво трябва да бъде private и какво трябва да може да възстанови един backup.
От какво зависи Shlink
Здравето на процеса и здравето на продукта са различни неща при Shlink. Порт 8080 може да отговаря, докато транзакцията, видима за потребителя, все още се проваля. Мрежовият contract за Shlink включва Postgres или MariaDB плюс optional Redis за production. Дръжте private endpoint-ите във вътрешен DNS, разрешавайте само необходимите outbound заявки и дайте на Shlink service credential с ограничен scope.
Използвайте това упражнение за readiness след значими промени в конфигурацията: създайте кратък URL чрез API, следвайте неговия redirect, запишете посещения и прегледайте статистиката от web клиента. Не включвайте скъпи външни проверки в liveness probe-овете, за да не предизвика прекъсване при проблем с даден provider. При работа по capacity следете throughput-а на redirect-ите, записите в базата данни, изтеглянията на geolocation данни и поведението на cache-а — това е по-близо до реалното натоварване на Shlink от заявките към страниците.
Volumes са само първият слой за възстановяване
В стандартния Shlink image не се очаква да има writable application state. Запазвайте базата данни, API ключовете и всички импортирани данни за посещения, включително pinned digest-а и прегледаната route конфигурация, вместо да архивирате празната filesystem на container-а.
Създайте Shlink от нулата на друг host и проверете дали домейните, short code-овете, tag-овете и записите за посещения се възстановяват и всеки тестван short URL се redirect-ва по идентичен начин. Ако добавите отделна база данни, room server или authentication layer, задайте на всеки компонент собствен изричен owner за възстановяването. Ръководството от Git до production показва как reproducible artifact заменя backup на container.
Запишете командата за rebuild и теста с очакван резултат заедно с release-а. Stateless планът за възстановяване успява, като възпроизвежда поведението от надеждни входни данни; той не трябва да зависи от копирането на непрозрачен работещ container.
Защитете ценната част на Shlink
Сигурното deployment-ване на Shlink започва с премахване на излишните права. Не излагайте REST API ключа и не променяйте публичния домейн, след като линковете са публикувани; вместо това дръжте API ключовете извън browser кода, използвайте HTTPS и ограничете администрацията, като оставите redirect-ите публични.
DEFAULT_DOMAIN е конфигурация, а не secret; дръжте стойността му изрично зададена, като същевременно защитавате отделните credentials, използвани от Shlink. Ограничете administrative route-овете, използвайте private DNS за dependency-тата и преглеждайте всеки bind mount. Когато log-овете се изпращат централизирано, филтрирайте secret-ите и private съдържанието, преди да напуснат сървъра.
Превърнете smoke теста на Shlink в release проверка
За Shlink дефинирайте транзакция с известен добър резултат преди launch: създайте кратък URL чрез API, следвайте неговия redirect, запишете посещения и прегледайте статистиката от web клиента. Съхранявайте в version control нейните prerequisites, очаквания response и стъпките за cleanup, без стойности на secret-и. Pin-нете image-а, използван за създаването на този reference.
Използвайте транзакцията, за да валидирате replacement и независимо restore-ване. Възстановената услуга е приемлива само когато домейните, short code-овете, tag-овете и записите за посещения се върнат и всеки тестван short URL се redirect-ва по идентичен начин. Едновременно с това наблюдавайте throughput-а на redirect-ите, записите в базата данни, изтеглянията на geolocation данни и поведението на cache-а и превърнете най-бавната или най-ограничената част в service-level alert.
Gate-ът трябва да включва и negative case: временно забранете на test identity-то достъпа до Postgres или MariaDB плюс optional Redis за production. Потвърдете, че Shlink генерира actionable error, като запазва данните, възстановете валидното състояние и повторете транзакцията с известен добър резултат. Поддържането и на двата резултата предотвратява превръщането на повърхностен health endpoint в единственото production доказателство.
Стартирайте Shlink, без да скривате движещите се части
Следващата команда показва ясно границата на container-а, без да претендира, че provision-ва всяка външна услуга.
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-а, mount-овете и listener-а. Добавете прегледаните connection настройки за Postgres или MariaDB плюс optional Redis за production; използвайте private имена за private услугите. Успешният launch приключва, когато можете да създадете кратък URL чрез API, да следвате неговия redirect, да запишете посещения и да прегледате статистиката от web клиента, а не когато docker ps изпише Up.
Дайте на Shlink един canonical адрес
Публичната граница на Shlink трябва да бъде един canonical hostname, automatic TLS и една вътрешна цел на 8080. Задайте DEFAULT_DOMAIN и IS_HTTPS_ENABLED преди създаването на кратки URL адреси, така че клиентите да се връщат към адрес, който услугата разпознава.
Ако acceptance транзакцията се провали, класифицирайте първата грешка. Проблемите с DNS, certificate и 502 принадлежат към checklist-а за TLS валидация. Условието „генерираните линкове използват HTTP или migrations не могат да достигнат до базата данни“ принадлежи към application страната, след като заявката успешно е достигнала до Shlink.
Диагностицирайте Shlink, който изглежда здрав
При Shlink наблюдавайте транзакция, а не процес: създайте кратък URL чрез API, следвайте неговия redirect, запишете посещения и прегледайте статистиката от web клиента. Комбинирайте latency и error rate на транзакцията с throughput-а на redirect-ите, записите в базата данни, изтеглянията на geolocation данни и поведението на cache-а, така че alert-ът да идентифицира ограничения компонент.
Rehearsal-ът за upgrade трябва да обхваща факта, че database migrations и API compatibility трябва да се подготвят поетапно, защото публикуваните short link-ове не могат да чакат ръчен repair. Направете restore, приложете migration и изпълнете транзакцията преди replacement-а в production. Ако генерираните линкове използват HTTP или migrations не могат да достигнат до базата данни, не изтривайте данни, за да направите startup-а зелен; сравнете version, променливите, mount-овете и reachability до dependency-тата в този ред.
Дръжте Shlink изричен, докато Dockup управлява routing-а
One-click deployment-ът на Shlink в Dockup трябва да прави replacement-а безопасен: route-ът продължава да сочи към 8080, secret-ите не са baked в image-а, а persistent path-овете се връщат в новия container. Същото deployment-ване може да работи върху Dockup compute или върху attached machine.
Завършете специфичната за приложението работа, като свържете и тествате Postgres или MariaDB плюс optional Redis за production, приложите canonical публичния адрес и изпълните тази acceptance проверка: създайте кратък URL чрез API, следвайте неговия redirect, запишете посещения и прегледайте статистиката от web клиента. Добавете резултата от restore-а към runbook-а, преди да пристигнат реални потребители.
Често задавани въпроси
Какво е необходимо на Shlink за production deployment?
Насочете container-а на Shlink през порт 8080 към един HTTPS origin. Поддържащото мрежово изискване е Postgres или MariaDB плюс optional Redis за production. Не обявявайте Shlink за готов, докато не можете да създадете кратък URL чрез API, да следвате неговия redirect, да запишете посещения и да прегледате статистиката от web клиента.
Кои данни на Shlink трябва да бъдат включени в backup?
Стандартният Shlink image няма задължителен mount за application data. Запазете deployment конфигурацията му и архивирайте всяко свързано state състояние отделно; възстановяването е успешно, когато домейните, short code-овете, tag-овете и записите за посещения се върнат и всеки тестван short URL се redirect-ва по идентичен начин.
Изисква ли Shlink HTTPS зад reverse proxy?
Използвайте HTTPS за публичния Shlink origin и оставете порт 8080 във вътрешния route. Приложете правилно настройката на Shlink: задайте DEFAULT_DOMAIN и IS_HTTPS_ENABLED преди създаването на кратки URL адреси. При Shlink HTTPS защитава credentials или потребителско съдържание при пренос и поддържа последователно клиентското поведение, чувствително към origin.
Как трябва да се тества upgrade на Shlink?
Възстановете текущото state състояние на Shlink в изолирано deployment-ване, приложете candidate версията и повторете acceptance транзакцията. Обърнете особено внимание, защото database migrations и API compatibility трябва да се подготвят поетапно, тъй като публикуваните short link-ове не могат да чакат ръчен repair. Запазете предишния Shlink image, докато не изясните границите на data migration-а и rollback-а.