Como fazer self-host do Shlink em 2026: domínios, chaves de API e estatísticas

Fazer self-host do Shlink se torna interessante no primeiro redeploy, não no primeiro docker run. Se os links gerados usam HTTP ou as migrações não conseguem acessar o banco de dados, o Docker ainda pode informar que o processo está perfeitamente saudável. A implantação abaixo é organizada em torno de comportamentos observáveis: criar uma URL curta pela API, seguir o redirecionamento, registrar visitas e consultar estatísticas pelo cliente web.

A finalidade do Shlink é clara: um encurtador de links API-first com estatísticas. Essa descrição mostra o que precisa permanecer público, o que deve continuar privado e o que um backup precisa reconstruir.

Do que o Shlink depende

A saúde do processo e a saúde do produto são coisas distintas no Shlink. A porta 8080 pode responder enquanto a transação voltada ao usuário continua falhando. O contrato de rede do Shlink é Postgres ou MariaDB, além de Redis opcional para produção. Mantenha os endpoints privados em DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Shlink uma credencial de serviço com escopo limitado.

Use este exercício de prontidão após mudanças relevantes na configuração: crie uma URL curta pela API, siga o redirecionamento, registre visitas e consulte estatísticas pelo cliente web. Mantenha verificações externas dispendiosas fora das probes de liveness para que uma indisponibilidade do provedor não provoque um loop de reinicialização. O trabalho de capacidade deve acompanhar o throughput de redirecionamentos, as gravações no banco de dados, os downloads de geolocalização e o comportamento do cache, que refletem melhor a pressão real sobre o Shlink do que as solicitações de páginas.

Volumes são apenas a primeira camada de recuperação

Não se espera que exista estado gravável da aplicação dentro da imagem padrão do Shlink. Preserve o banco de dados, as chaves de API e quaisquer dados de visitas importados, incluindo o digest fixado e a configuração de rotas revisada, em vez de fazer backup de um sistema de arquivos vazio do container.

Crie o Shlink do zero em outro host e verifique se os domínios, códigos curtos, tags e registros de visitas são restaurados e se todas as URLs curtas testadas redirecionam de forma idêntica. Se um banco de dados separado, um servidor de sala ou uma camada de autenticação for adicionada, atribua a esse componente seu próprio responsável explícito pela recuperação. O guia do Git à produção mostra como um artefato reproduzível substitui um backup de container.

Registre o comando de reconstrução e o teste com saída conhecida junto ao release. Um plano de recuperação stateless é bem-sucedido ao reproduzir o comportamento a partir de entradas confiáveis; ele não deve depender da cópia de um container em execução e opaco.

Proteja a parte valiosa do Shlink

Uma implantação segura do Shlink começa pela remoção de autoridade. Evite expor a chave da API REST ou alterar o domínio público depois que os links forem publicados; em vez disso, mantenha as chaves de API fora do código do navegador, use HTTPS e restrinja a administração, deixando os redirecionamentos públicos.

DEFAULT_DOMAIN é uma configuração, não um segredo; mantenha seu valor explícito enquanto protege as credenciais separadas usadas pelo Shlink. Restrinja as rotas administrativas, use DNS privado para as dependências e revise cada bind mount. Quando os logs forem enviados para um sistema central, filtre segredos e conteúdo privado antes que deixem o servidor.

Transforme o smoke test do Shlink em uma verificação de release

Para o Shlink, defina uma transação conhecida como válida antes do lançamento: crie uma URL curta pela API, siga o redirecionamento, registre visitas e consulte estatísticas pelo cliente web. Coloque no controle de versão os pré-requisitos, a resposta esperada e as etapas de limpeza, sem valores secretos. Fixe a imagem usada para estabelecer essa referência.

Use a transação para validar uma substituição e uma restauração independente. O serviço restaurado só será aceitável quando os domínios, códigos curtos, tags e registros de visitas forem recuperados e todas as URLs curtas testadas redirecionarem de forma idêntica. Ao mesmo tempo, observe o throughput de redirecionamentos, as gravações no banco de dados, os downloads de geolocalização e o comportamento do cache, transformando a parte mais lenta ou mais limitada em um alerta de nível de serviço.

O gate também precisa de um caso negativo: negue temporariamente à identidade de teste o acesso ao Postgres ou MariaDB, além do Redis opcional para produção. Confirme que o Shlink produz um erro acionável enquanto preserva os dados, restaure a condição válida e repita a transação conhecida como válida. Manter os dois resultados impede que um endpoint de health superficial se torne a única evidência em produção.

Inicie o Shlink sem ocultar as partes móveis

O comando a seguir torna visível o limite do container sem fingir provisionar todos os serviços externos.

docker run -d \
  --name shlink \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e DEFAULT_DOMAIN=go.example.com \
  shlinkio/shlink:stable

Antes de abrir o ingress, inspecione o ambiente resolvido, os mounts e o listener. Adicione as configurações de conexão revisadas para Postgres ou MariaDB, além do Redis opcional para produção; use nomes privados para serviços privados. Um lançamento bem-sucedido termina quando você consegue criar uma URL curta pela API, seguir o redirecionamento, registrar visitas e consultar estatísticas pelo cliente web, não quando o docker ps exibe Up.

Dê ao Shlink um endereço canônico

A fronteira pública do Shlink deve ser um único hostname canônico, com TLS automático e um único destino interno na porta 8080. Defina DEFAULT_DOMAIN e IS_HTTPS_ENABLED antes de criar URLs curtas para que os clientes retornem a um endereço reconhecido pelo serviço.

Se a transação de aceitação falhar, classifique o primeiro erro. Problemas de DNS, certificado e 502 pertencem ao checklist de validação de TLS. A condição “os links gerados usam HTTP ou as migrações não conseguem acessar o banco de dados” pertence ao lado da aplicação depois que uma solicitação alcançou o Shlink com sucesso.

Diagnostique um Shlink que parece saudável

No Shlink, monitore uma transação em vez de um processo: crie uma URL curta pela API, siga o redirecionamento, registre visitas e consulte estatísticas pelo cliente web. Combine a latência e a taxa de erros com o throughput de redirecionamentos, as gravações no banco de dados, os downloads de geolocalização e o comportamento do cache para que um alerta identifique o componente limitado.

O ensaio de upgrade deve abranger o staging das migrações do banco de dados e da compatibilidade da API, pois os links curtos publicados não podem esperar por uma correção manual. Restaure, faça a migração e execute a transação antes de substituir o serviço em produção. Se os links gerados usam HTTP ou as migrações não conseguem acessar o banco de dados, não apague dados para deixar a inicialização verde; compare, nessa ordem, a versão, as variáveis, os mounts e a conectividade com as dependências.

Mantenha o Shlink explícito enquanto o Dockup cuida do roteamento

A implantação do Shlink em um clique do Dockup deve tornar a substituição segura: a rota continua apontando para a porta 8080, os segredos não são incorporados à imagem e os caminhos persistentes retornam no novo container. A mesma implantação pode ser executada no compute do Dockup ou em uma máquina conectada.

Conclua o trabalho específico da aplicação conectando e testando Postgres ou MariaDB, além do Redis opcional para produção, aplicando o endereço público canônico e executando esta verificação de aceitação: crie uma URL curta pela API, siga o redirecionamento, registre visitas e consulte estatísticas pelo cliente web. Adicione o resultado da restauração ao runbook antes da chegada dos usuários reais.

Perguntas frequentes

O que o Shlink precisa para uma implantação em produção?

Encaminhe o container do Shlink na porta 8080 por meio de uma única origem HTTPS. O requisito de rede de suporte é Postgres ou MariaDB, além do Redis opcional para produção. Não considere o Shlink pronto até conseguir criar uma URL curta pela API, seguir o redirecionamento, registrar visitas e consultar estatísticas pelo cliente web.

Quais dados do Shlink devem fazer parte de um backup?

A imagem padrão do Shlink não tem nenhum mount obrigatório de dados da aplicação. Preserve a configuração da implantação e faça backup de qualquer estado conectado separadamente; a recuperação será aprovada quando os domínios, códigos curtos, tags e registros de visitas forem restaurados e todas as URLs curtas testadas redirecionarem de forma idêntica.

O Shlink exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Shlink e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do Shlink: defina DEFAULT_DOMAIN e IS_HTTPS_ENABLED antes de criar URLs curtas. No Shlink, o HTTPS protege credenciais ou conteúdo do usuário durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Shlink?

Restaure o estado atual do Shlink em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as migrações do banco de dados e a compatibilidade da API devem ser colocadas em staging, já que os links curtos publicados não podem esperar por uma correção manual. Mantenha a imagem anterior do Shlink até compreender os limites da migração de dados e do rollback.