SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor · Dikemas kini 2026-11-20

Cara Bina Pemendek URL Sendiri Menggunakan Shlink

Pasang pemendek URL Shlink 5.1 pada VPS menggunakan Docker Compose. Ketahui cara konfigurasi DNS, pangkalan data Postgres, kunci API, serta statistik klik untuk domain anda.

Apa yang anda sedang bina

Pemendek URL yang dihoskan sendiri ialah pelayan kecil yang menukar pautan panjang kepada pautan pendek milik anda, serta mengira setiap klik padanya. Shlink ialah pilihan terbaik: ia adalah sumber terbuka, diedarkan sebagai imej Docker, dan melakukan keseluruhan tugas dalam satu kontena berserta pangkalan data. Panduan ini memasangnya pada VPS di sebalik domain pendek sebenar, lengkap dengan HTTPS, kunci API, kod QR dan statistik klik.

Dua komponen menjadikannya berfungsi seperti pemendek komersial. Pelayan API menjawab pengalihan (redirect) dan menyimpan data. Pelanggan web pula ialah aplikasi statik berasingan yang berhubung dengan API tersebut daripada pelayar anda. Anda boleh menjalankan kedua-duanya, atau menjalankan API sahaja dan mengawalnya melalui baris perintah.

Nombor versi di sini adalah yang terkini setakat 19 November 2026: Shlink 5.1.8 dan shlink-web-client 4.9.0.

Halakan domain pendek ke pelayan terlebih dahulu

Domain adalah produknya. s.example.com/abc123 ialah pautan yang dilihat oleh pengguna, jadi pilih sesuatu yang pendek dan tentukannya sebelum anda memasang apa-apa. Shlink mengaitkan setiap URL pendek dengan domain lalai atau domain yang ditetapkan secara eksplisit. Menukarnya kemudian bermakna anda perlu mengekalkan domain lama agar terus menghala ke Shlink supaya pautan yang telah diedarkan tetap berfungsi.

Cipta satu rekod DNS A untuk domain pendek tersebut, yang menghala ke alamat IPv4 awam VPS anda. Tambahkan juga rekod AAAA jika pelayan mempunyai IPv6. Kemudian, sahkan bahawa ia telah diselesaikan (resolve) sebelum anda meneruskan langkah seterusnya.

dig +short s.example.com A

Outputnya mestilah alamat pelayan anda. Jika ia kosong, rekod tersebut belum lagi tersebar (propagate), dan setiap langkah seterusnya akan gagal dengan cara yang mengelirukan, kerana sijil TLS (transport layer security) tidak boleh dikeluarkan untuk nama yang tidak dapat diselesaikan.

Fail compose

Shlink memerlukan pangkalan data. SQLite memadai untuk ujian, namun Postgres ialah pilihan yang tepat untuk sebarang data yang ingin disimpan, kerana baris lawatan akan terkumpul dan Postgres mengendalikan indeks serta penulisan serentak dengan lebih baik. Letakkan ini dalam /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:

Kedua-dua port yang diterbitkan terikat pada 127.0.0.1, jadi tiada apa-apa yang boleh dicapai dari internet sehingga proksi terbalik (reverse proxy) dalam bahagian seterusnya disediakan. Docker menulis peraturan penghalaannya sendiri mendahului firewall hos, yang bermaksud baris 8080:8080 biasa akan mendedahkan aplikasi walaupun pada kotak yang firewall-nya kelihatan tertutup. Mengikat pada alamat loopback mengelakkan perkara tersebut. Corak yang sama terpakai pada mana-mana aplikasi yang anda jalankan dengan cara ini, dan ia diterangkan dengan lebih terperinci dalam panduan Docker Compose pada VPS.

Kata laluan pangkalan data datang daripada fail .env di sebelah fail compose, jadi ia tidak akan tersimpan dalam 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

Mulakan ia dan perhatikan API diaktifkan.

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

Permulaan pertama menjalankan migrasi pangkalan data, jadi ia mengambil masa lebih lama berbanding permulaan seterusnya. Apabila ia stabil, pastikan servis menjawab secara setempat.

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

200 bermaksud API aktif dan sambungan pangkalan data berfungsi. 503 bermaksud Shlink sedang berjalan tetapi semakan pangkalan datanya gagal. Endpoint kesihatan menjawab 503 untuk sebarang ralat pangkalan data, bukan 500. Jika curl mencetak 000 sebaliknya, ia tidak menerima kod respons HTTP; periksa ketersambungan dan log di atas sebelum membuat kesimpulan bahawa kontena telah berhenti atau sedang dimulakan semula. Jika log menunjukkan kegagalan pengesahan pangkalan data, pastikan DB_PASSWORD dalam .env sepadan dengan apa yang dicipta bersama Postgres, kerana imej Postgres membaca POSTGRES_PASSWORD hanya apabila ia memulakan direktori data yang kosong. Menyunting .env kemudian tidak akan mengubah kata laluan pangkalan data sedia ada; tukar juga kata laluan peranan pangkalan data, atau masukkan semula kata laluan sedia ada ke dalam .env.

Shlink menyediakan HTTP biasa pada port 8080. TLS sepatutnya dikendalikan oleh reverse proxy, dan tetapan paling penting ialah menghantar nama hos asal (original host name) melalui proksi tersebut. Shlink menggunakan header Host untuk mencari kod pendek, dengan mekanisme fallback untuk memadankan pautan pada domain lalai. Oleh itu, hos yang ditulis semula (rewritten host) boleh menyebabkan pemilihan pautan yang salah atau mengembalikan ralat 404 bagi kod yang sebenarnya wujud pada domain lain.

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

Kemudian, keluarkan sijil tersebut. Panduan lengkap, termasuk pemasa pembaharuan, terdapat dalam panduan Certbot untuk nginx pada Ubuntu 24.04.

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

IS_HTTPS_ENABLED: "true" dalam fail compose adalah perkara yang menyebabkan Shlink mencetak https:// dalam URL pendek yang dikembalikannya. Ia tidak mengaktifkan TLS dengan sendirinya. Biarkan ia sebagai false di belakang proksi HTTPS supaya setiap pautan yang diberikan oleh API bukan pautan http:// yang memerlukan lencongan (redirect) tambahan, kerana ini akan menambah round trip dan kelihatan tidak tepat dalam web client.

Mencipta kunci API

API pengurusan memerlukan kunci; endpoint kesihatan adalah terbuka kepada umum. Jana satu kunci melalui CLI di dalam kontena.

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

Perintah ini memaparkan kunci tersebut sekali sahaja. Salin kunci itu sekarang, kerana ia disimpan dalam bentuk hash dan tidak boleh dipaparkan semula. shlink api-key:list memaparkan nama dan status sama ada setiap kunci diaktifkan atau tidak, tetapi tidak memaparkan kunci itu sendiri. Batalkan kunci dengan shlink api-key:disable dan nama kunci tersebut.

Hantar kunci dalam header X-Api-Key untuk panggilan pengurusan REST.

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

Objek JSON dengan kunci shortUrls bermaksud kunci tersebut berfungsi. 401 yang mempunyai type bernilai https://shlink.io/api/error/invalid-api-key, dengan tajuk Invalid API key, bermaksud kunci tersebut salah, dinyahaktifkan, atau telah melepasi tarikh luputnya.

Mencipta pautan pendek daripada baris perintah

CLI ialah cara terpantas untuk membuat pautan, dan ia merupakan kaedah yang berfungsi dengan baik dalam skrip.

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 memberikan anda pautan yang boleh dibaca dan bukannya kod yang dijana secara rawak. Slug adalah unik bagi setiap domain, jadi percubaan kedua pada slug yang telah digunakan akan gagal dan bukannya menimpa pautan pertama secara senyap. --tag boleh diulang, dan tag ialah cara anda mengumpulkan pautan yang anda ingin lihat statistik gabungannya nanti.

Senaraikan pautan yang sedia ada, kemudian lihat trafik bagi satu pautan.

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

short-url:visits mencetak satu baris bagi setiap klik dengan tarikh, perujuk (referrer) dan ejen pengguna (user agent). Lajur negara dan bandar akan kekal kosong melainkan anda menetapkan pemboleh ubah persekitaran GEOLITE_LICENSE_KEY, iaitu kunci MaxMind percuma yang digunakan oleh Shlink untuk memuat turun pangkalan data GeoLite2. Tanpanya, lawatan masih direkodkan, cuma ia tidak diletakkan lokasinya.

Pelanggan web dan kod QR

Pelanggan web kini berada pada 127.0.0.1:8081 dan memerlukan entri proksi sendiri, atau terowong SSH jika anda lebih suka untuk tidak menerbitkannya. Ia akan meminta URL pelayan dan kunci API pada muatan pertama. Masukkan https://s.example.com dan kunci yang telah anda jana. Pelanggan menyimpan kedua-duanya dalam storan pelayar dan memanggil API anda secara terus, jadi tiada data yang melalui pihak lain. Memisahkan antara muka daripada API adalah corak yang wajar diperhatikan, kerana ia merupakan corak yang sama yang membolehkan Halcyon menjadikan pustaka Jellyfin seperti kedai sewa video tahun 1990-an tanpa mengubah pelayan media di belakangnya.

Kod QR datang daripada pelanggan web, bukan API. Shlink 5 telah membuang helah lama untuk menambah /qr-code pada URL pendek, jadi alamat tersebut tidak lagi mengembalikan imej. Pelanggan web melukis kod tersebut dalam pelayar anda sebaliknya, tanpa sebarang permintaan kepada Shlink. Buka pilihan kod QR pada mana-mana pautan dalam senarai URL pendek, tetapkan saiz, format dan margin, kemudian muat turun hasilnya. Tingkatkan tahap pembetulan ralat untuk kod yang masih boleh diimbas apabila dicetak kecil atau tertutup sebahagiannya. Dialog yang sama juga menerima warna dan logo.

Pastikan ia terus berjalan

Pemendek pautan gagal secara senyap. Pautan berhenti mengubah hala dan tiada sesiapa memberitahu anda, kerana pengguna yang mengklik menganggap pautan tersebut sudah mati. Halakan semakan uptime ke URL pendek yang sebenar dan bukannya ke halaman utama, serta berikan amaran bagi sebarang respons yang bukan pengalihan (redirect). Instans Uptime Kuma yang dihoskan sendiri melakukan perkara ini dengan baik, dan ia boleh memantau kod status yang khusus.

Buat sandaran pangkalan data, bukan kontena. Satu arahan sahaja sudah cukup untuk melakukan dump.

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

Fail tersebut berserta fail compose anda dan .env akan membina semula keseluruhan servis pada pelayan baharu. Setiap aplikasi pada pelayan memerlukan versi sandaran tersendiri, dan pustaka foto merupakan kes yang rumit, kerana PhotoPrism dan Immich kedua-duanya menyimpan fail asal pada cakera serta baris dalam pangkalan data. Oleh itu, dump sahaja hanya memulihkan rekod pangkalan data tetapi bukan satu pun foto atau tetapan berasaskan fail PhotoPrism. Sandarkan juga konfigurasi PhotoPrism, termasuk fail settings.yml yang menyimpan keutamaan antara muka pengguna, muat turun dan pengindeksan. Naik taraf dilakukan dengan sudo docker compose pull diikuti oleh sudo docker compose up -d, dan Shlink akan menjalankan sebarang migrasi baharu semasa permulaan. Lakukan dump sebelum anda melakukan pull, kerana migrasi tidak boleh dibatalkan (roll back).

FAQ

Mengapa pautan pendek saya memaparkan ralat 404 selepas saya menambah reverse proxy?

Shlink memadankan kod pendek dengan domain dalam header Host. Jika proksi menghantar host yang berbeza, Shlink akan menyemak domain tersebut dan kemudian beralih kepada pautan default-domain yang sepadan; ia akan memaparkan ralat 404 jika kedua-duanya tidak mempunyai kod tersebut. Tetapkan proxy_set_header Host $host; dalam blok location nginx dan muat semula proksi. Pautan akan berfungsi serta-merta tanpa perlu memulakan semula container.

Adakah saya perlukan Postgres, atau adakah SQLite sudah memadai?

SQLite memadai untuk mencuba Shlink dan tidak memerlukan container kedua. Beralihlah kepada Postgres sebelum anda menerbitkan pautan yang penting, kerana baris data lawatan akan bertambah dengan setiap klik dan SQLite melakukan penulisan secara bersiri (serialise). Penukaran pada masa hadapan bermakna anda perlu mengeksport dan mengimport semula pautan anda, jadi memilih Postgres dari awal akan menjimatkan masa anda daripada melakukan migrasi tersebut.

Bolehkah saya mendapatkan semula API key yang terlupa untuk disalin?

Tidak. Shlink menyimpan hash bagi kunci tersebut, jadi api-key:list hanya memaparkan nama dan status tetapi tidak akan memaparkan nilainya. Jana kunci gantian dengan shlink api-key:generate, tampalkannya ke dalam web client, kemudian nyahaktifkan kunci lama dengan shlink api-key:disable supaya ia berhenti berfungsi.

Mengapa ruangan negara kosong dalam statistik lawatan saya?

Geolokasi memerlukan pangkalan data GeoLite2, yang hanya dimuat turun oleh Shlink apabila anda memberikan GEOLITE_LICENSE_KEY. Kunci tersebut adalah percuma daripada MaxMind. Tambahkannya ke dalam bahagian environment, bina semula container, dan lawatan baharu akan dikesan lokasinya. Lawatan yang direkodkan sebelum itu akan kekal kosong sehingga anda menjalankan shlink visit:locate.

Kekalkan domain dan pindahkan data. Lakukan dump pangkalan data dengan pg_dump, salin fail dump, fail compose dan .env ke pelayan baharu, mulakan pangkalan data sahaja, pulihkan dump ke dalam pangkalan data yang kosong, kemudian mulakan Shlink dan web client sebelum trafik sebenar tiba. Tukar rekod DNS pada langkah terakhir. Kod pendek dan sejarah lawatannya akan kekal selamat, kerana semuanya disimpan di dalam pangkalan data.

Adakah artikel ini berguna?

#shlink#url-shortener#self-hosting#docker#postgres