SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-11-20

Como instalar um encurtador de URLs com Shlink e Docker

Instale o Shlink 5.1 em um VPS com Docker Compose, domínio curto, Postgres, HTTPS, API, cliente web, QR codes e estatísticas de cliques.

O que você vai criar

Um encurtador de URLs autoalojado é um pequeno servidor que transforma um link longo num link curto seu e contabiliza cada clique. A escolha é o Shlink: é open source, é distribuído como uma imagem Docker e executa todo o trabalho num contentor e numa base de dados. Este guia instala-o numa VPS atrás de um domínio curto real, com HTTPS, uma chave de API, códigos QR e estatísticas de cliques.

Duas componentes fazem com que funcione como um encurtador comercial. O servidor da API responde aos redirecionamentos e armazena os dados. O cliente web é uma aplicação estática separada que comunica com essa API a partir do navegador. Pode executar ambos ou executar apenas a API e controlá-la pela linha de comandos.

Os números de versão apresentados correspondem ao estado atual em 19 de novembro de 2026: Shlink 5.1.8 e shlink-web-client 4.9.0.

Aponte primeiro um domínio curto para o servidor

O domínio é o produto. s.example.com/abc123 é a ligação que as pessoas veem, por isso escolha um nome curto antes de instalar qualquer componente. O Shlink associa cada URL curta ao domínio predefinido ou a um domínio atribuído explicitamente. Se alterar o domínio mais tarde, terá de manter o domínio antigo apontado para o Shlink para que as ligações já distribuídas continuem a funcionar.

Crie um registo DNS A para o domínio curto, apontado para o endereço IPv4 público do seu VPS. Adicione também um registo AAAA se o servidor tiver IPv6. Em seguida, confirme que o domínio é resolvido antes de continuar.

dig +short s.example.com A

O resultado tem de ser o endereço do seu servidor. Se estiver vazio, o registo ainda não foi propagado. Nesse caso, todos os passos seguintes falharão de forma pouco clara, porque não é possível emitir um certificado TLS (transport layer security) para um nome que não é resolvido.

O ficheiro compose

O Shlink precisa de uma base de dados. O SQLite serve para testes, mas o Postgres é a escolha certa para qualquer instalação que pretenda manter, porque as linhas de visitas se acumulam e o Postgres gere melhor os índices e as escritas concorrentes. Coloque isto em /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:

As duas portas publicadas estão associadas a 127.0.0.1, por isso nada fica acessível a partir da Internet até o reverse proxy da secção seguinte estar configurado. O Docker escreve as suas próprias regras de encaminhamento antes da firewall do anfitrião, o que significa que uma linha 8080:8080 simples exporia a aplicação mesmo num sistema cuja firewall pareça fechada. Associar as portas ao endereço de loopback evita isso. O mesmo padrão aplica-se a qualquer aplicação executada desta forma e é explicado com mais detalhe em o guia do Docker Compose numa VPS.

A palavra-passe da base de dados vem de um ficheiro .env junto ao ficheiro compose, por isso nunca fica no 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

Inicie-a e monitorize o arranque da API.

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

O primeiro arranque executa as migrações da base de dados, por isso demora mais do que os arranques seguintes. Quando estabilizar, confirme que o serviço responde localmente.

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

Um 200 significa que a API está ativa e que a ligação à base de dados funciona. Um 503 significa que o Shlink está em execução, mas a verificação da base de dados falhou. O endpoint de estado responde 503 para qualquer erro da base de dados, nunca 500. Se o curl apresentar 000, não recebeu nenhum código de resposta HTTP; verifique a conectividade e os logs acima antes de concluir que o contentor parou ou está a reiniciar. Se os logs mostrarem uma falha de autenticação da base de dados, confirme que o DB_PASSWORD em .env corresponde ao valor usado na criação do Postgres, porque a imagem do Postgres só lê POSTGRES_PASSWORD quando inicializa um diretório de dados vazio. Editar .env posteriormente não altera a palavra-passe existente da base de dados; altere também a palavra-passe da função da base de dados ou volte a colocar a palavra-passe existente em .env.

Terminar o HTTPS à frente

O Shlink disponibiliza HTTP simples na porta 8080. O TLS deve ser tratado por um reverse proxy, e a única configuração essencial é encaminhar o nome de host original. O Shlink usa o cabeçalho Host para procurar códigos curtos, com fallback para a correspondência de links no domínio predefinido. Por isso, um host reescrito pode selecionar o link errado ou devolver 404 para um código que só existe noutro domínio.

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

Em seguida, emita o certificado. O procedimento completo, incluindo o temporizador de renovação, está no guia do Certbot para nginx no Ubuntu 24.04.

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

IS_HTTPS_ENABLED: "true" no ficheiro compose faz o Shlink incluir https:// nos URLs curtos que devolve. Esta opção não ativa o TLS por si só. Deixe false atrás de um proxy HTTPS. Caso contrário, todos os links devolvidos pela API serão links http:// que depois fazem um redirecionamento. Isso acrescenta uma ida e volta e parece incorreto no cliente web.

Criar uma chave de API

A API de gestão precisa de uma chave; o endpoint de verificação de estado é público. Gere uma através da CLI dentro do contentor.

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

O comando apresenta a chave uma única vez. Copie-a agora, porque é armazenada com hash e não pode ser apresentada novamente. shlink api-key:list mostra os nomes e indica se cada chave está ativada, mas nunca mostra a própria chave. Revogue uma chave com shlink api-key:disable e o nome.

Envie a chave num cabeçalho X-Api-Key para chamadas REST de gestão.

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

Um objeto JSON com uma chave shortUrls indica que a chave funciona. Um 401 cujo type seja https://shlink.io/api/error/invalid-api-key, com o título Invalid API key, indica que a chave está incorreta, desativada ou ultrapassou a data de validade.

A CLI é a forma mais rápida de criar links e funciona bem com scripts.

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 fornece um link legível em vez de um código gerado. Os slugs são exclusivos por domínio. Por isso, uma segunda tentativa de usar um slug já ocupado falha, em vez de substituir silenciosamente o primeiro link. --tag pode ser repetida. As tags permitem agrupar links para os quais pretende obter estatísticas combinadas mais tarde.

Liste o que existe e, em seguida, consulte o tráfego de um link.

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

short-url:visits mostra uma linha por clique, com a data, o referenciador e o agente do utilizador. As colunas de país e cidade ficam vazias, a menos que defina uma variável de ambiente GEOLITE_LICENSE_KEY. Esta variável contém uma chave gratuita da MaxMind que o Shlink usa para transferir a base de dados GeoLite2. Sem ela, as visitas continuam a ser registadas, mas não são geolocalizadas.

O cliente web e os códigos QR

O cliente web está agora em 127.0.0.1:8081 e precisa da sua própria entrada de proxy, ou de um túnel SSH se preferir não o publicar. Na primeira utilização, pede o URL do servidor e uma chave de API. Introduza https://s.example.com e a chave que gerou. O cliente guarda ambos no armazenamento do navegador e chama diretamente a sua API, por isso nenhum dado passa por terceiros. Separar a interface da API é um padrão importante, porque é o mesmo que permite ao Halcyon transformar uma biblioteca Jellyfin numa locadora dos anos 1990 sem alterar o servidor de multimédia que está por trás.

Os códigos QR vêm do cliente web, não da API. O Shlink 5 removeu o método antigo de acrescentar /qr-code a um URL curto, por isso esse endereço já não devolve uma imagem. Em vez disso, o cliente web desenha o código no navegador, sem fazer um pedido ao Shlink. Abra a opção de código QR em qualquer ligação da lista de URLs curtos, defina o tamanho, o formato e a margem e descarregue o resultado. Aumente o nível de correção de erros para que o código continue a ser lido quando for impresso em tamanho pequeno ou ficar parcialmente coberto. A mesma caixa de diálogo também permite definir cores e um logótipo.

Mantenha o serviço em execução

Um encurtador pode falhar silenciosamente. Os links deixam de redirecionar e ninguém o informa, porque a pessoa que clicou presumiu que o link estava indisponível. Configure uma verificação de disponibilidade para um URL curto real, e não para a página inicial, e gere um alerta para qualquer resposta que não seja um redirecionamento. Uma instância auto-hospedada do Uptime Kuma faz isto bem e pode verificar um código de estado específico.

Faça uma cópia de segurança da base de dados, não do contentor. Um comando cria o dump.

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

Esse ficheiro, juntamente com o seu ficheiro compose e .env, reconstrói todo o serviço num servidor novo. Cada aplicação no servidor precisa da sua própria versão dessa cópia de segurança. Uma biblioteca de fotografias é o caso mais complexo, porque PhotoPrism e Immich guardam os originais no disco e também linhas numa base de dados. Por isso, um dump restaura os registos da base de dados, mas não restaura uma única fotografia nem as definições baseadas em ficheiros do PhotoPrism. Faça também uma cópia de segurança da configuração do PhotoPrism, incluindo o ficheiro settings.yml, que contém as preferências da interface, das transferências e da indexação. As atualizações são sudo docker compose pull seguidas de sudo docker compose up -d, e o Shlink executa as novas migrações durante o arranque. Faça o dump antes de executar o pull, porque não é possível reverter uma migração.

FAQ

O Shlink compara um código curto com o domínio do cabeçalho Host. Se o proxy enviar outro host, o Shlink verifica esse domínio e depois procura um link correspondente no domínio predefinido; devolve 404 se o código não existir em nenhum dos dois. Defina proxy_set_header Host $host; no bloco de localização do nginx e recarregue o proxy. Os links começam a funcionar imediatamente, sem reiniciar o contentor.

Preciso do Postgres ou o SQLite é suficiente?

O SQLite é adequado para experimentar o Shlink e não requer um segundo contentor. Mude para o Postgres antes de publicar links importantes, porque o número de registos de visitas aumenta a cada clique e o SQLite serializa as escritas. Mudar mais tarde implica exportar e importar novamente os links. Escolher o Postgres desde o início evita essa migração.

Posso recuperar uma chave de API que me esqueci de copiar?

Não. O Shlink armazena um hash da chave. Por isso, api-key:list mostra os nomes e o estado, mas nunca o valor. Gere uma substituta com shlink api-key:generate, cole-a no cliente web e desative a antiga com shlink api-key:disable para que deixe de funcionar.

Por que estão vazias as colunas de país nas estatísticas de visitas?

A geolocalização requer a base de dados GeoLite2. O Shlink só a descarrega quando lhe fornece um GEOLITE_LICENSE_KEY. A chave é gratuita e obtém-se na MaxMind. Adicione-a à secção de ambiente, recrie o contentor e as novas visitas serão localizadas. As visitas registadas antes disso continuam sem país até executar shlink visit:locate.

Mantenha o domínio e mova os dados. Faça um dump da base de dados com pg_dump. Copie o dump, o ficheiro compose e .env para o novo servidor. Inicie apenas a base de dados e restaure o dump na base de dados vazia. Depois, inicie o Shlink e o cliente web antes de chegar tráfego real. Altere o registo DNS por último. Os códigos curtos e o respetivo histórico de visitas são preservados, porque tudo fica na base de dados.

Este artigo foi útil?

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