Jinsi ya Kuendesha Shlink kwa Docker Compose

Unachojenga

Kifupisha URL kinachojihifadhi ni seva ndogo inayobadilisha kiungo kirefu kuwa kiungo kifupi unachomiliki, na kuhesabu kila mbofyo kinachopokea. Shlink ndiyo chaguo linalofaa: ni programu huria, hutolewa kama taswira ya Docker, na hufanya kazi yote katika kontena moja pamoja na hifadhidata. Mwongozo huu huiweka kwenye VPS nyuma ya kikoa halisi kifupi, ikiwa na HTTPS, ufunguo wa API, misimbo ya QR na takwimu za mibofyo.

Vipengele viwili huifanya ifanane na kifupisha URL cha kibiashara. Seva ya API hushughulikia uelekezaji upya na huhifadhi data. Kisanifu cha wavuti ni programu tuli tofauti inayowasiliana na API hiyo kutoka kwenye kivinjari chako. Unaweza kuendesha vyote viwili, au kuendesha API pekee na kuiendesha kupitia mstari wa amri.

Nambari za matoleo hapa ndizo zilizokuwa za sasa kufikia Julai 2026: Shlink 5.1 na shlink-web-client 4.8.

Kwanza elekeza kikoa kifupi kwenye seva

Kikoa ndicho bidhaa. s.example.com/abc123 ndiyo kiungo ambacho watu huona, kwa hiyo chagua kikoa kifupi na ukikamilishe kabla ya kusakinisha chochote. Shlink huhifadhi kikoa pamoja na kila URL fupi, na kukibadilisha baadaye kutafanya kila kiungo ulichokwisha kusambaza kisisomeke.

Unda rekodi moja ya DNS A ya kikoa kifupi, na ielekeze kwenye anwani ya umma ya IPv4 ya VPS yako. Ongeza pia rekodi ya AAAA ikiwa seva ina IPv6. Kisha thibitisha kuwa kikoa hicho kinatatuliwa kabla ya kuendelea.

dig +short s.example.com A

Matokeo lazima yawe anwani ya seva yako. Ikiwa hakuna matokeo, rekodi bado haijasambaa, na kila hatua inayofuata itashindwa kwa njia isiyoeleweka, kwa sababu cheti cha TLS (usalama wa safu ya usafirishaji) hakiwezi kutolewa kwa jina ambalo halitatuliwi.

Faili ya compose

Shlink inahitaji hifadhidata. SQLite inafaa kwa majaribio, lakini Postgres ndiyo chaguo sahihi kwa chochote unachopanga kuhifadhi, kwa sababu rekodi za ziara huongezeka na Postgres hushughulikia faharasa pamoja na maandishi yanayoandikwa kwa wakati mmoja vizuri zaidi. Weka haya katika /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:

Port zote mbili zilizochapishwa zinafungwa kwenye 127.0.0.1, kwa hiyo hakuna kinachoweza kufikiwa kutoka kwenye intaneti hadi proksi ya kinyume katika sehemu inayofuata iwekwe. Docker huandika sheria zake za uelekezaji kabla ya ngome ya seva mwenyeji, ambayo inamaanisha kuwa mstari wa kawaida wa 8080:8080 ungeufanya programu ipatikane hata kwenye seva ambayo ngome yake inaonekana kuwa imefungwa. Kufunga kwenye anwani ya loopback huepusha hilo. Mtindo huu unatumika pia kwa programu yoyote unayoendesha kwa njia hii, na umeelezwa kwa undani zaidi katika mwongozo wa Docker Compose kwenye VPS.

Nenosiri la hifadhidata linatoka kwenye faili ya .env iliyo karibu na faili ya compose, kwa hiyo haliingii kwenye 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/.env

Iwashe na ufuatilie API inapoanza.

cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlink

Uanzishaji wa kwanza huendesha uhamishaji wa hifadhidata, kwa hiyo huchukua muda mrefu kuliko uanzishaji unaofuata. Ikishatulia, thibitisha kuwa huduma inajibu ndani ya seva.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health

200 inamaanisha kuwa API iko hai na muunganisho wa hifadhidata unafanya kazi. 500 hapa karibu kila mara husababishwa na hifadhidata: DB_PASSWORD katika .env hailingani na thamani ambayo Postgres iliundwa nayo, kwa sababu image ya Postgres husoma POSTGRES_PASSWORD tu inapoanzisha saraka tupu ya data. Kuhariri nenosiri baadaye hakutakuwa na athari hadi utakapoondoa volume na kuanzisha tena.

Kamilisha HTTPS mbele yake

Shlink huhudumia HTTP isiyo na usimbaji kwenye port 8080. TLS inapaswa kushughulikiwa na reverse proxy. Mpangilio muhimu ni kupitisha jina asili la host. Shlink huamua msimbo mfupi ni wa domain gani kwa kusoma header ya Host. Kwa hiyo, proxy inayobadilisha header hiyo husababisha majibu ya 404 kwenye viungo vilivyopo. Pia husababisha takwimu za ziara kuhusishwa na domain isiyo sahihi.

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;
    }
}

Kisha toa certificate. Maelekezo kamili, pamoja na kipima muda cha renewal, yako katika mwongozo wa Certbot wa nginx kwenye Ubuntu 24.04.

sudo certbot --nginx -d s.example.com

IS_HTTPS_ENABLED: "true" katika faili ya compose ndiyo inayofanya Shlink ichapishe https:// kwenye URL fupi inazorejesha. Huwezeshi TLS yenyewe. Iache ikiwa false nyuma ya proxy ya HTTPS. Vinginevyo, kila kiungo ambacho API inarejesha kitakuwa kiungo cha http:// ambacho baadaye huelekeza kwingine. Hii huongeza mzunguko mmoja wa mawasiliano na huonekana si sahihi katika mteja wa wavuti.

Unda ufunguo wa API

Hakuna kinachoweza kuwasiliana na API bila ufunguo. Tengeneza ufunguo kupitia CLI ndani ya kontena.

sudo docker compose exec shlink shlink api-key:generate --name "web client"

Amri hiyo huonyesha ufunguo mara moja. Unakili sasa, kwa sababu huhifadhiwa ikiwa imesimbwa kwa heshi na hauwezi kuonyeshwa tena. shlink api-key:list huonyesha majina na ikiwa kila ufunguo umewezeshwa, lakini haionyeshi ufunguo wenyewe. Batilisha ufunguo kwa kutumia shlink api-key:disable na jina lake.

Kila ombi la REST hubeba ufunguo katika kichwa cha X-Api-Key.

curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urls

Kipengee cha JSON kilicho na ufunguo wa shortUrls kinamaanisha kuwa ufunguo unafanya kazi. 401 iliyo na INVALID_API_KEY inamaanisha kuwa ufunguo si sahihi, umezimwa, au muda wake wa matumizi umeisha.

Unda viungo vifupi kutoka kwenye mstari wa amri

CLI ndiyo njia ya haraka zaidi ya kuunda viungo, na inafaa kwa matumizi katika hati za kiotomatiki.

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 hukupa kiungo kinachosomeka badala ya msimbo unaozalishwa. Slug ni za kipekee kwa kila kikoa, kwa hiyo jaribio la pili la kutumia slug iliyokwisha tumika hushindwa badala ya kubatilisha kiungo cha kwanza bila taarifa. --tag inaweza kurudiwa, na lebo ndizo hutumika kupanga viungo ambavyo utahitaji takwimu zake za pamoja baadaye.

Orodhesha vilivyopo, kisha tazama trafiki ya kiungo kimoja.

sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docs

short-url:visits huchapisha safu moja kwa kila mbofyo, ikiwa na tarehe, anwani ya rejeleo na wakala wa mtumiaji. Safu za nchi na jiji hubaki tupu isipokuwa uweke kigezo cha mazingira cha GEOLITE_LICENSE_KEY, ambacho ni ufunguo wa bure wa MaxMind unaotumiwa na Shlink kupakua hifadhidata ya GeoLite2. Bila kigezo hicho, ziara bado hurekodiwa, lakini hazitambuliwi mahali zilipotoka.

Mteja wa wavuti na misimbo ya QR

Mteja wa wavuti sasa yuko kwenye 127.0.0.1:8081 na anahitaji ingizo lake la proksi, au handaki la SSH ikiwa hutaki kuuchapisha. Wakati wa kupakia mara ya kwanza, anaomba URL ya seva na ufunguo wa API. Weka https://s.example.com na ufunguo uliotengeneza. Mteja huhifadhi vyote viwili kwenye hifadhi ya kivinjari na huita API yako moja kwa moja, kwa hiyo hakuna data inayopitia kwa mtu mwingine.

Misimbo ya QR haihitaji usanidi wowote. Ongeza /qr-code kwenye URL yoyote fupi, na API itarudisha picha.

https://s.example.com/docs/qr-code?size=500&format=svg&margin=20

size ni upana kwa pikseli na unakubali 50 hadi 1000, huku 300 ikiwa thamani chaguo-msingi. format ni png au svg. margin ni nafasi tupu inayozunguka msimbo kwa pikseli, na picha ya mwisho hupima ukubwa pamoja na mara mbili ya ukingo. Ongeza errorCorrection=Q ili msimbo uendelee kusomeka unapochapishwa kwa ukubwa mdogo au kufunikwa kwa sehemu.

Iendelee kufanya kazi

Huduma ya kufupisha viungo hushindwa bila taarifa. Viungo huacha kuelekeza, na hakuna anayekujulisha kwa sababu mtu aliyebofya alidhani kiungo kilikuwa kimekufa. Elekeza ukaguzi wa upatikanaji kwenye URL halisi iliyofupishwa badala ya ukurasa wa mwanzo, na tuma tahadhari kwa hali yoyote ambayo si kuelekeza. Instansi ya Uptime Kuma inayojihudumia hufanya hivi vizuri, na inaweza kufuatilia msimbo mahususi wa hali.

Hifadhi nakala ya database, si container. Amri moja huitupa.

sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gz

Faili hiyo pamoja na faili yako ya compose hujenga upya huduma nzima kwenye server mpya. Maboresho ni sudo docker compose pull yakifuatiwa na sudo docker compose up -d, na Shlink huendesha migrations mpya wakati wa kuanza. Tengeneza dump kabla ya kufanya pull, kwa sababu migration haiwezi kurejeshwa nyuma.

FAQ

Kwa nini viungo vyangu vifupi vinarudisha 404 baada ya kuongeza reverse proxy?

Shlink inalinganisha msimbo mfupi na domain iliyo kwenye kichwa cha Host. Proxy inayotuma jina lake yenyewe au anwani ya ndani husababisha Shlink itafute msimbo huo chini ya domain isiyo na viungo. Kwa hiyo, inarudisha 404. Weka proxy_set_header Host $host; kwenye kizuizi cha nginx location, kisha upakie upya proxy. Viungo vitaanza kufanya kazi mara moja bila kuanzisha upya container.

Je, ninahitaji Postgres, au SQLite inatosha?

SQLite inafaa kujaribu Shlink na haihitaji container ya pili. Tumia Postgres kabla ya kuchapisha viungo muhimu, kwa sababu safu za ziara huongezeka kwa kila bofyo na SQLite husawazisha uandishi. Kubadilisha baadaye kunahitaji kuhamisha na kuingiza tena viungo vyako. Kwa hiyo, kuchagua Postgres mwanzoni kunakuondolea uhamishaji huo.

Je, ninaweza kurejesha API key niliyosaahau kunakili?

Hapana. Shlink huhifadhi hash ya key hiyo. Kwa hiyo, api-key:list huonyesha majina na hali, lakini si thamani yake. Tengeneza replacement kwa kutumia shlink api-key:generate, ibandike kwenye web client, kisha zima ya zamani kwa shlink api-key:disable ili isiendelee kufanya kazi.

Kwa nini safu za nchi hazina data katika takwimu za ziara?

Geolocation inahitaji database ya GeoLite2. Shlink huipakua tu unapompa GEOLITE_LICENSE_KEY. Key hiyo inapatikana bila malipo kutoka MaxMind. Iongeze kwenye sehemu ya environment, tengeneza container upya, na ziara mpya zitawekewa maeneo. Ziara zilizorekodiwa kabla ya hapo zitaendelea kuwa tupu hadi utakapoendesha shlink visit:locate.

Ninawezaje kuhamisha Shlink kwenye server tofauti?

Weka domain hiyo hiyo na uhamishe data. Tengeneza dump ya database kwa pg_dump, nakili dump na compose file kwenye server mpya, washa stack, kisha rejesha dump kwenye database tupu kabla ya traffic halisi kuanza. Badilisha rekodi ya DNS mwisho. Msimbo mifupi na historia yake ya ziara vitaendelea kuwepo, kwa sababu kila kitu huhifadhiwa kwenye database.