Własny skracacz linków z Shlink i Docker Compose
Instalacja Shlink na własnym VPS krok po kroku. Konfiguracja kontenerów Docker, bazy Postgres, certyfikatów SSL oraz obsługa API, statystyk i kodów QR dla krótkich domen.
Co budujesz
Własny skracacz adresów URL to niewielki serwer, który zamienia długi link na krótki, należący do Ciebie, oraz zlicza każde kliknięcie w niego. Shlink jest właściwym wyborem: jest oprogramowaniem open source, jest dostarczany jako obraz Docker i wykonuje całe zadanie w jednym kontenerze oraz bazie danych. Ten przewodnik instaluje go na VPS za prawdziwą krótką domeną, z HTTPS, kluczem API, kodami QR i statystykami kliknięć.
Dwa elementy sprawiają, że działa on jak komercyjny skracacz. Serwer API odpowiada za przekierowania i przechowuje dane. Klient webowy to oddzielna statyczna aplikacja, która komunikuje się z tym API z poziomu przeglądarki. Możesz uruchomić oba elementy lub tylko samo API i zarządzać nim z wiersza poleceń.
Wersje oprogramowania podane w tym miejscu były aktualne na październik 2026: Shlink 5.1 oraz shlink-web-client 4.8.
Skieruj krótką domenę na serwer w pierwszej kolejności
Domena jest produktem. s.example.com/abc123 to link, który widzą użytkownicy, dlatego należy wybrać krótką nazwę przed rozpoczęciem instalacji. Shlink zapisuje domenę przy każdym krótkim adresie URL, a jej późniejsza zmiana spowoduje, że wszystkie udostępnione wcześniej linki przestaną działać.
Utwórz jeden rekord DNS typu A dla krótkiej domeny, wskazujący na publiczny adres IPv4 Twojego VPS. Dodaj również rekord AAAA, jeśli serwer posiada adres IPv6. Następnie potwierdź, że domena się rozwiązuje, zanim przejdziesz dalej.
dig +short s.example.com AWynikiem polecenia powinien być adres Twojego serwera. Jeśli wynik jest pusty, rekord nie został jeszcze rozpropagowany, a każdy kolejny krok zakończy się niepowodzeniem w niejasny sposób, ponieważ certyfikat TLS (transport layer security) nie może zostać wystawiony dla nazwy, która się nie rozwiązuje.
Plik compose
Shlink wymaga bazy danych. SQLite sprawdza się w testach, ale Postgres jest właściwym wyborem dla wszystkiego, co planujesz zachować, ponieważ wiersze z wizytami gromadzą się, a Postgres lepiej radzi sobie z indeksami i współbieżnymi zapisami. Umieść to w /opt/shlink/compose.yaml.
services:
shlink:
image: shlinkio/shlink:stable
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
environment:
DEFAULT_DOMAIN: s.example.com
IS_HTTPS_ENABLED: "true"
DB_DRIVER: postgres
DB_HOST: database
DB_NAME: shlink
DB_USER: shlink
DB_PASSWORD: ${DB_PASSWORD}
depends_on:
- database
database:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: shlink
POSTGRES_USER: shlink
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- shlink_db:/var/lib/postgresql/data
web-client:
image: shlinkio/shlink-web-client:stable
restart: unless-stopped
ports:
- "127.0.0.1:8081:8080"
volumes:
shlink_db:Oba opublikowane porty są powiązane z 127.0.0.1, więc nic nie jest dostępne z Internetu, dopóki nie zostanie skonfigurowane reverse proxy w następnej sekcji. Docker tworzy własne reguły przekierowania przed firewallem hosta, co oznacza, że zwykła linia 8080:8080 wystawiłaby aplikację nawet na maszynie, której firewall wydaje się zamknięty. Powiązanie z adresem loopback pozwala tego uniknąć. Ten sam schemat dotyczy każdej aplikacji uruchamianej w ten sposób i jest szerzej opisany w przewodniku po Docker Compose na VPS.
Hasło do bazy danych pochodzi z pliku .env znajdującego się obok pliku compose, dzięki czemu nigdy nie trafia do YAML.
sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.envUruchom go i obserwuj, jak API wstaje.
cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlinkPierwszy start wykonuje migracje bazy danych, więc trwa dłużej niż kolejne. Gdy usługa się ustabilizuje, sprawdź, czy odpowiada lokalnie.
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health200 oznacza, że API działa, a połączenie z bazą danych jest poprawne. 503 oznacza, że Shlink działa, ale test bazy danych nie powiódł się. Endpoint health zwraca 503 w przypadku jakiegokolwiek błędu bazy danych, nigdy 500. Jeśli curl wyświetla 000, oznacza to, że nikt nie odpowiada na porcie: kontener zatrzymał się podczas testów startowych i Docker go restartuje, więc przeczytaj powyższe logi. W obu przypadkach najczęstszą przyczyną jest to, że DB_PASSWORD w .env nie pasuje do tego, z którym utworzono Postgres, ponieważ obraz Postgres odczytuje POSTGRES_PASSWORD tylko podczas inicjalizacji pustego katalogu danych. Edycja hasła w późniejszym czasie nie przynosi efektu, dopóki nie usuniesz wolumenu i nie zaczniesz od nowa.
Terminacja HTTPS przed usługą
Shlink obsługuje zwykły protokół HTTP na porcie 8080. Obsługa TLS powinna odbywać się w reverse proxy, a kluczowym ustawieniem jest przekazywanie oryginalnej nazwy hosta. Shlink określa domenę, do której należy krótki kod, odczytując nagłówek Host, dlatego proxy zmieniające ten nagłówek spowoduje błędy 404 dla istniejących linków oraz przypisanie statystyk odwiedzin do niewłaściwej domeny.
server {
server_name s.example.com;
listen 80;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Następnie należy wygenerować certyfikat. Pełna procedura, w tym harmonogram odnawiania, znajduje się w przewodniku Certbot dla nginx na systemie Ubuntu 24.04.
sudo certbot --nginx -d s.example.comZmienna IS_HTTPS_ENABLED: "true" w pliku compose odpowiada za to, aby Shlink generował adresy https:// w zwracanych krótkich linkach. Sama w sobie nie włącza ona obsługi TLS. Należy pozostawić ją jako false za proxy HTTPS, w przeciwnym razie każdy link zwrócony przez API będzie linkiem http://, który wymaga dodatkowego przekierowania, co zwiększa opóźnienie i powoduje błędy wyświetlania w interfejsie webowym.
Utworzenie klucza API
Bez klucza żaden klient nie może komunikować się z API. Klucz należy wygenerować za pomocą CLI wewnątrz kontenera.
sudo docker compose exec shlink shlink api-key:generate --name "web client"Polecenie wyświetla klucz tylko raz. Należy skopiować go od razu, ponieważ jest przechowywany w postaci skrótu i nie można wyświetlić go ponownie. shlink api-key:list wyświetla nazwy kluczy oraz informację, czy każdy z nich jest włączony, ale nigdy nie wyświetla samego klucza. Klucz można unieważnić za pomocą shlink api-key:disable i jego nazwy.
Każde żądanie REST przekazuje klucz w nagłówku X-Api-Key.
curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urlsObiekt JSON zawierający klucz shortUrls oznacza, że klucz działa. Obiekt 401, którego type ma wartość https://shlink.io/api/error/invalid-api-key, oraz którego tytuł to Invalid API key, oznacza, że klucz jest nieprawidłowy, wyłączony albo wygasł.
Tworzenie krótkich linków z poziomu wiersza poleceń
Interfejs CLI jest najszybszym sposobem tworzenia linków i dobrze sprawdza się w skryptach.
sudo docker compose exec shlink shlink short-url:create https://example.com/a/very/long/path
sudo docker compose exec shlink shlink short-url:create https://example.com/docs --custom-slug docs --tag reference--custom-slug pozwala uzyskać czytelny link zamiast wygenerowanego kodu. Slugi są unikalne w obrębie domeny, więc kolejna próba użycia zajętego sluga zakończy się niepowodzeniem, zamiast cichego nadpisania pierwszego linku. --tag można powtarzać, a tagi służą do grupowania linków, dla których użytkownik może chcieć uzyskać łączne statystyki w przyszłości.
Wyświetl istniejące elementy, a następnie sprawdź ruch dla pojedynczego linku.
sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docsshort-url:visits wyświetla jeden wiersz na każde kliknięcie, zawierający datę, źródło odniesienia (referrer) oraz user agent. Kolumny kraju i miasta pozostają puste, chyba że ustawiona zostanie zmienna środowiskowa GEOLITE_LICENSE_KEY, która jest darmowym kluczem MaxMind używanym przez Shlink do pobrania bazy danych GeoLite2. Bez tego klucza wizyty są nadal rejestrowane, po prostu nie są lokalizowane.
Klient webowy i kody QR
Klient webowy jest teraz dostępny pod adresem 127.0.0.1:8081 i wymaga własnego wpisu proxy albo tunelu SSH, jeśli nie ma być publikowany. Przy pierwszym uruchomieniu żąda adresu serwera i klucza API. Należy wprowadzić https://s.example.com oraz wygenerowany klucz. Klient przechowuje oba elementy w pamięci przeglądarki i bezpośrednio wywołuje własne API, dlatego żadne dane nie przechodzą przez inne podmioty. Rozdzielenie interfejsu od API to rozwiązanie warte uwagi, ponieważ ten sam wzorzec pozwala projektowi Halcyon nadać bibliotece Jellyfin wygląd wypożyczalni z lat 1990. bez zmiany serwera multimediów.
Kody QR są generowane przez klienta webowego, a nie przez API. W Shlink 5 usunięto wcześniejsze rozwiązanie polegające na dopisywaniu /qr-code do krótkiego adresu URL, dlatego ten adres nie zwraca już obrazu. Zamiast tego klient webowy rysuje kod w przeglądarce, bez wysyłania żądania do Shlink. Należy otworzyć opcję kodu QR przy dowolnym odnośniku na liście krótkich adresów URL, ustawić rozmiar, format i margines, a następnie pobrać wynik. W przypadku kodu, który ma pozostać możliwy do zeskanowania po wydrukowaniu w małym rozmiarze lub częściowym zasłonięciu, należy zwiększyć poziom korekcji błędów. W tym samym oknie dialogowym można także ustawić kolory i logo.
Utrzymanie działania
Skracacz adresów może ulec awarii bez wyraźnych oznak. Odnośniki przestają przekierowywać, a nikt o tym nie informuje, ponieważ osoba, która kliknęła odnośnik, zakłada, że był nieaktywny. Monitorowanie dostępności należy kierować na rzeczywisty krótki adres URL, a nie na stronę główną, oraz generować alert dla każdej odpowiedzi, która nie jest przekierowaniem. Samodzielnie hostowana instancja Uptime Kuma dobrze sprawdza się w tym zadaniu i może monitorować konkretny kod statusu.
Należy tworzyć kopię zapasową bazy danych, a nie kontenera. Jedno polecenie wykonuje jej zrzut.
sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gzTen plik wraz z plikiem Compose pozwala odtworzyć całą usługę na nowym serwerze. Każda aplikacja na serwerze wymaga własnej wersji tych dwóch elementów. Wyjątkiem jest biblioteka zdjęć, ponieważ PhotoPrism i Immich przechowują oryginały na dysku oraz rekordy w bazie danych. Sam zrzut odtwarza konta i ustawienia, ale nie przywraca ani jednego zdjęcia. Aktualizacje wykonuje się za pomocą sudo docker compose pull, a następnie sudo docker compose up -d. Shlink uruchamia wszystkie nowe migracje podczas startu. Zrzut należy wykonać przed pobraniem nowej wersji, ponieważ migracji nie można wycofać.
FAQ
Dlaczego moje krótkie linki zwracają błąd 404 po dodaniu reverse proxy?
Shlink dopasowuje krótki kod do domeny w nagłówku Host. Proxy, które przesyła własną nazwę lub adres wewnętrzny, powoduje, że Shlink szuka kodu w domenie, która nie posiada żadnych linków, więc zwraca błąd 404. Ustaw proxy_set_header Host $host; w bloku location serwera nginx i przeładuj konfigurację proxy. Linki zaczną działać natychmiast, bez konieczności restartu kontenera.
Czy potrzebuję Postgres, czy wystarczy SQLite?
SQLite jest wystarczający do testowania Shlink i nie wymaga drugiego kontenera. Przejdź na Postgres przed publikacją ważnych linków, ponieważ wiersze z wizytami rosną z każdym kliknięciem, a SQLite szereguje zapisy. Późniejsza zmiana oznacza konieczność eksportu i ponownego importu linków, więc wybór Postgres na początku pozwala uniknąć tej migracji.
Czy mogę odzyskać klucz API, którego zapomniałem skopiować?
Nie. Shlink przechowuje skrót klucza, więc api-key:list wyświetla nazwy i statusy, ale nigdy samej wartości. Wygeneruj nowy klucz za pomocą shlink api-key:generate, wklej go do klienta webowego, a następnie wyłącz stary za pomocą shlink api-key:disable, aby przestał działać.
Dlaczego kolumny z krajami są puste w moich statystykach wizyt?
Geolokalizacja wymaga bazy danych GeoLite2, którą Shlink pobiera tylko po podaniu klucza GEOLITE_LICENSE_KEY. Klucz jest darmowy i dostępny w serwisie MaxMind. Dodaj go do sekcji environment, utwórz ponownie kontener, a nowe wizyty będą lokalizowane. Wizyty zarejestrowane wcześniej pozostaną puste, dopóki nie uruchomisz shlink visit:locate.
Jak przenieść Shlink na inny serwer?
Zachowaj domenę i przenieś dane. Wykonaj zrzut bazy danych za pomocą pg_dump, skopiuj zrzut oraz plik compose na nowy serwer, uruchom stos, a następnie przywróć zrzut do pustej bazy danych, zanim dotrze do niej rzeczywisty ruch. Zmień rekord DNS na samym końcu. Krótkie kody oraz historia wizyt zostaną zachowane, ponieważ wszystkie dane znajdują się w bazie.