SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-10-21

Tự host URL shortener với Shlink trên VPS và Docker

Tự host URL shortener với Shlink 5.1 trên VPS: cấu hình DNS, HTTPS, Postgres, API key, web client, QR code và thống kê click bằng Docker Compose.

Bạn sẽ xây dựng gì

Một URL shortener tự host là một server nhỏ biến một link dài thành một link ngắn do bạn sở hữu và đếm mọi lượt click vào link đó. Shlink là lựa chọn phù hợp: đây là phần mềm mã nguồn mở, được phát hành dưới dạng Docker image và thực hiện toàn bộ công việc trong một container cùng với một database. Hướng dẫn này triển khai Shlink trên VPS phía sau một domain rút gọn thực tế, kèm HTTPS, API key, QR code và thống kê lượt click.

Hai thành phần giúp hệ thống hoạt động giống một dịch vụ rút gọn link thương mại. API server xử lý redirect và lưu dữ liệu. Web client là một static app riêng, giao tiếp với API đó từ trình duyệt. Bạn có thể chạy cả hai, hoặc chỉ chạy API rồi điều khiển bằng command line.

Các số phiên bản trong bài là phiên bản hiện hành vào tháng 10 năm 2026: Shlink 5.1 và shlink-web-client 4.8.

Trỏ một domain ngắn đến server trước

Domain là phần người dùng nhìn thấy. s.example.com/abc123 là link được chia sẻ, nên hãy chọn một tên ngắn và quyết định trước khi cài bất kỳ thứ gì. Shlink lưu domain cùng với từng short URL. Nếu đổi domain sau này, mọi link bạn đã chia sẻ sẽ ngừng hoạt động.

Tạo một DNS A record cho domain ngắn và trỏ record đó đến địa chỉ IPv4 public của VPS. Nếu server có IPv6, hãy thêm cả một AAAA record. Sau đó xác nhận domain phân giải được trước khi tiếp tục.

dig +short s.example.com A

Kết quả phải là địa chỉ của server. Nếu kết quả rỗng, record chưa propagate. Khi đó mọi bước tiếp theo sẽ fail theo cách khó xác định, vì không thể cấp chứng chỉ TLS (transport layer security) cho một tên không phân giải được.

Tệp compose

Shlink cần một database. SQLite phù hợp để thử nghiệm, nhưng Postgres là lựa chọn đúng cho mọi thứ bạn định duy trì lâu dài, vì số bản ghi lượt truy cập sẽ tăng dần và Postgres xử lý index cũng như các lần ghi đồng thời tốt hơn. Đặt nội dung sau vào /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:

Cả hai port được publish đều bind vào 127.0.0.1, nên chưa có gì truy cập được từ Internet cho đến khi reverse proxy ở phần tiếp theo hoạt động. Docker ghi các rule forwarding riêng trước firewall của host. Vì vậy, chỉ một dòng 8080:8080 đơn giản cũng có thể expose app, ngay cả khi firewall của máy trông như đang đóng. Bind vào địa chỉ loopback sẽ tránh được việc này. Cách làm tương tự áp dụng cho mọi app bạn chạy theo kiểu này và được trình bày chi tiết hơn trong hướng dẫn Docker Compose trên VPS.

Mật khẩu database lấy từ một file .env nằm cạnh tệp compose, nên không xuất hiện trong 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

Khởi động nó và theo dõi API hoạt động.

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

Lần khởi động đầu tiên sẽ chạy các migration của database, nên mất nhiều thời gian hơn những lần sau. Khi service đã ổn định, hãy kiểm tra service có phản hồi cục bộ hay không.

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

200 nghĩa là API đang hoạt động và kết nối database thành công. 503 nghĩa là Shlink đang chạy nhưng bước kiểm tra database thất bại. Health endpoint trả về 503 cho mọi lỗi database, không bao giờ trả về 500. Nếu curl in ra 000, nghĩa là không có gì đang phản hồi trên port: container đã dừng trong quá trình kiểm tra khởi động và Docker đang restart nó, nên hãy đọc log ở trên. Trong cả hai trường hợp, nguyên nhân thường gặp là DB_PASSWORD trong .env không khớp với giá trị Postgres đã được tạo, vì image Postgres chỉ đọc POSTGRES_PASSWORD khi khởi tạo một data directory rỗng. Việc sửa mật khẩu sau đó không có tác dụng cho đến khi bạn xóa volume và khởi động lại.

Đặt HTTPS ở reverse proxy phía trước

Shlink phục vụ HTTP thuần trên cổng 8080. TLS phải được xử lý tại reverse proxy. Thiết lập quan trọng nhất là truyền hostname ban đầu qua proxy. Shlink xác định một short code thuộc domain nào bằng cách đọc header Host. Vì vậy, nếu proxy ghi đè header này, các link hợp lệ sẽ trả về 404 và thống kê lượt truy cập sẽ bị gắn vào sai domain.

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

Sau đó, hãy cấp certificate. Hướng dẫn đầy đủ, bao gồm cả timer gia hạn, có trong hướng dẫn Certbot cho nginx trên Ubuntu 24.04.

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

IS_HTTPS_ENABLED: "true" trong file compose khiến Shlink in https:// trong các short URL mà nó trả về. Thiết lập này không tự bật TLS. Hãy để false phía sau một HTTPS proxy. Khi đó, mọi link mà API trả về đều là link http:// rồi mới redirect, làm phát sinh thêm một round trip và hiển thị không đúng trong web client.

Tạo API key

API không thể nhận yêu cầu nếu không có key. Hãy tạo key bằng CLI bên trong container.

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

Lệnh chỉ hiển thị key một lần. Hãy sao chép ngay vì key được lưu dưới dạng hash và không thể hiển thị lại. shlink api-key:list hiển thị tên và trạng thái bật/tắt của từng key, không bao giờ hiển thị chính key đó. Thu hồi một key bằng shlink api-key:disable và tên của key.

Mỗi REST call gửi key trong header X-Api-Key.

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

Một JSON object có key shortUrls cho biết key hoạt động. Một 401 có type là https://shlink.io/api/error/invalid-api-key và title là Invalid API key cho biết key không đúng, đã bị tắt hoặc đã hết hạn.

CLI là cách nhanh nhất để tạo link và phù hợp với việc dùng trong script.

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 tạo link dễ đọc thay vì mã được sinh tự động. Slug là duy nhất trong từng domain, nên lần thử thứ hai với slug đã được dùng sẽ fail thay vì âm thầm ghi đè link đầu tiên. Có thể lặp lại --tag, còn tag dùng để nhóm các link mà sau này bạn muốn xem thống kê tổng hợp.

Liệt kê những gì đang có, sau đó xem traffic của một link.

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

short-url:visits in một dòng cho mỗi lượt click, gồm ngày, referrer và user agent. Các cột country và city sẽ để trống nếu bạn chưa đặt biến môi trường GEOLITE_LICENSE_KEY. Đây là key MaxMind miễn phí mà Shlink dùng để tải database GeoLite2. Nếu không có key này, các lượt truy cập vẫn được ghi nhận nhưng không được xác định vị trí.

Web client và QR code

Web client hiện chạy tại 127.0.0.1:8081 và cần một proxy entry riêng, hoặc một SSH tunnel nếu bạn không muốn public nó. Khi tải lần đầu, client yêu cầu server URL và API key. Nhập https://s.example.com cùng key bạn đã tạo. Client lưu cả hai trong browser storage và gọi trực tiếp API của bạn, nên không có dữ liệu nào đi qua bên thứ ba. Việc tách interface khỏi API là một pattern đáng chú ý, vì đây cũng là cách Halcyon biến thư viện Jellyfin thành giao diện cửa hàng cho thuê băng đĩa thập niên 1990 mà không cần thay đổi media server phía sau.

QR code được tạo bởi web client, không phải API. Shlink 5 đã bỏ cách cũ là nối /qr-code vào short URL, nên địa chỉ đó không còn trả về image. Thay vào đó, web client vẽ code ngay trong browser mà không gửi request đến Shlink. Mở tùy chọn QR code trên bất kỳ link nào trong danh sách short URL, đặt kích thước, format và margin, rồi download kết quả. Tăng mức error correction để code vẫn scan được khi được in nhỏ hoặc bị che một phần. Dialog này cũng cho phép đặt màu và logo.

Duy trì hoạt động

Một dịch vụ rút gọn URL có thể gặp lỗi mà không hiển thị thông báo. Các liên kết ngừng chuyển hướng nhưng không ai biết, vì người nhấp vào cho rằng liên kết đã hỏng. Hãy cấu hình kiểm tra uptime cho một short URL thực tế thay vì trang chủ, rồi cảnh báo khi phản hồi không phải là redirect. Một instance Uptime Kuma tự host làm việc này tốt và có thể kiểm tra một status code cụ thể.

Hãy backup database, không phải container. Một command sẽ dump database.

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

File đó cùng với compose file có thể dựng lại toàn bộ service trên server mới. Mỗi app trên máy cần có một bộ riêng gồm hai file này. Thư viện ảnh là trường hợp phức tạp, vì PhotoPrism và Immich lưu cả file gốc trên disk lẫn các row trong database. Vì vậy, chỉ dump database sẽ khôi phục tài khoản và cài đặt nhưng không khôi phục được ảnh nào. Quy trình nâng cấp là sudo docker compose pull rồi đến sudo docker compose up -d, và Shlink sẽ chạy mọi migration mới khi khởi động. Hãy tạo dump trước khi pull, vì migration không thể rollback.

FAQ

Shlink đối chiếu short code với domain trong header Host. Nếu proxy gửi tên của chính nó hoặc một địa chỉ nội bộ, Shlink sẽ tìm code đó dưới một domain không có link, nên trả về 404. Đặt proxy_set_header Host $host; trong block location của nginx rồi reload proxy. Link sẽ hoạt động ngay, không cần restart container.

Tôi có cần Postgres không, hay SQLite là đủ?

SQLite phù hợp để thử Shlink và không cần container thứ hai. Hãy chuyển sang Postgres trước khi public các link quan trọng, vì số bản ghi visit tăng sau mỗi lượt click và SQLite serialize các thao tác ghi. Nếu chuyển đổi sau này, bạn phải export rồi import lại các link. Chọn Postgres ngay từ đầu sẽ tránh lần migration đó.

Tôi có thể khôi phục API key đã quên copy không?

Không. Shlink chỉ lưu hash của key, nên api-key:list hiển thị tên và trạng thái nhưng không bao giờ hiển thị giá trị key. Tạo key thay thế bằng shlink api-key:generate, paste key đó vào web client, rồi disable key cũ bằng shlink api-key:disable để key cũ không còn hoạt động.

Vì sao các cột quốc gia trong thống kê visit bị trống?

Geolocation cần database GeoLite2. Shlink chỉ download database này khi bạn cung cấp GEOLITE_LICENSE_KEY. Key được cấp miễn phí từ MaxMind. Thêm key vào phần environment, recreate container, rồi các visit mới sẽ được xác định vị trí. Các visit được ghi nhận trước đó vẫn để trống cho đến khi bạn chạy shlink visit:locate.

Giữ nguyên domain và chuyển dữ liệu. Dump database bằng pg_dump, copy file dump và file compose sang server mới, start stack, rồi restore dump vào database trống trước khi có network traffic thực tế. Chỉ thay đổi bản ghi DNS sau cùng. Short code và lịch sử visit vẫn được giữ nguyên vì toàn bộ dữ liệu nằm trong database.

Bài viết này có hữu ích không?

#shlink#url-shortener#tự lưu trữ#Docker#postgres