Subdomínio, Subdiretório ou Domínio Separado? Como Escolher uma Estrutura de URL para uma Aplicação Auto-Hospedada
Escolher onde uma aplicação auto-hospedada ficará afeta a configuração do proxy reverso, cookies, callbacks de autenticação, webhooks, TLS, trabalho de migração e limites administrativos. Use este guia para selecionar uma estrutura de URL e validá-la antes do lançamento.
Por que a estrutura de URL é uma decisão operacional, e não apenas uma decisão de marca
Uma URL faz parte do contrato público de uma aplicação. Os usuários a salvam, os navegadores aplicam a ela regras de origem e de cookies, provedores de identidade podem registrá-la, remetentes de webhook entregam conteúdo a ela, e clientes de API ou conteúdo incorporado podem armazená-la. Portanto, alterar a URL posteriormente pode afetar mais do que favoritos e links de busca.
Os três padrões mais comuns são um subdomínio dedicado, como https://app.example.com; um subdiretório atrás de um site existente, como https://example.com/app; e um domínio separado, como https://exampleapp.com. A melhor escolha depende do modelo de implantação documentado da aplicação e dos seus requisitos operacionais — não apenas de qual endereço parece mais curto.
Uma distinção técnica fundamental é a origem. Uma origem web é baseada em esquema, host e porta; o caminho não faz parte da origem. Como resultado, https://example.com/app compartilha uma origem com outros conteúdos em https://example.com, enquanto https://app.example.com usa um host diferente e, portanto, uma origem diferente. Essa diferença pode ser importante para o comportamento do navegador, o design de integrações e as expectativas de isolamento.
- Escolha a URL pública antes de convidar usuários, conectar um provedor de identidade ou publicar endpoints de webhook.
- Trate a URL canônica da aplicação como uma configuração que deve ser registrada e mantida.
- Não presuma que um proxy reverso consegue fazer qualquer aplicação funcionar corretamente sob um prefixo de caminho.
Os três padrões em resumo
Um subdomínio dedicado coloca a aplicação em um endereço como https://crm.example.com. Para muitas aplicações auto-hospedadas, esse é o arranjo público mais direto, pois a aplicação normalmente pode tratar / como seu caminho-base. O proxy reverso roteia pelo nome do host, e links gerados, recursos estáticos e redirecionamentos não precisam incluir um prefixo adicional de caminho público.
Um subdiretório coloca a aplicação sob um nome de host existente, por exemplo, https://example.com/analytics. Isso pode criar um site público unificado e ser útil quando uma empresa precisa apresentar um único host. No entanto, introduz o requisito de que tanto o proxy reverso quanto a aplicação entendam corretamente o caminho-base /analytics.
Um domínio separado coloca a aplicação em um nome distinto, como https://example-portal.com. Isso pode tornar mais claros os limites de produto, cliente, unidade de negócio ou governança. Também cria uma superfície separada de DNS, TLS, propriedade de domínio e ciclo de vida para gerenciar.
- Subdomínio dedicado: geralmente é o padrão de menor complexidade para uma aplicação com seu próprio login e integrações.
- Subdiretório: adequado somente após a documentação oficial da aplicação e uma implantação de homologação confirmarem o suporte a URLs relativas.
- Domínio separado: útil quando um limite público, administrativo ou organizacional claro é mais importante do que manter a aplicação sob o domínio principal da marca.
Comece pela aplicação: verifique o suporte documentado para URL-base e proxy reverso
Comece pela documentação da própria aplicação sobre instalação e proxy reverso. Procure especificamente configurações compatíveis chamadas URL-base, URL externa, URL do site, URL raiz, URL relativa, webroot, URL pública, proxy confiável, cabeçalhos encaminhados ou termos semelhantes. A terminologia varia conforme o produto, e o suporte é específico de cada produto.
Um proxy pode remover um prefixo público antes de encaminhar uma solicitação. Por exemplo, um proxy pode aceitar /app e encaminhar a solicitação a um backend que escuta em /. O middleware StripPrefix do Traefik realiza esse tipo de remoção de prefixo e fornece o prefixo removido em X-Forwarded-Prefix. Mas remover um caminho no proxy não faz automaticamente a aplicação saber que seu endereço público inclui esse caminho.
A aplicação ainda precisa gerar links públicos, URLs de recursos, redirecionamentos, destinos de formulários e URLs de callback com o prefixo correto. A documentação oficial também pode revelar limitações. O GitLab, por exemplo, documenta a instalação com URL relativa como alternativa, mas recomenda seu próprio domínio ou subdomínio em circunstâncias normais e descreve limitações. Isso é um lembrete útil para não generalizar o comportamento de um produto para outro.
- Leia a documentação de implantação do fornecedor antes de escolher um subdiretório.
- Confirme se a aplicação oferece suporte a URL relativa ou webroot, e não apenas a um proxy reverso genérico.
- Identifique os cabeçalhos de proxy e as configurações de proxy confiável necessários.
- Registre a URL externa canônica exata na documentação de implantação.
- Execute um teste de homologação usando a URL pública pretendida, não apenas um endereço direto de contêiner ou interno.
Autenticação e integrações: URLs de callback, links de e-mail, conteúdo incorporado e webhooks
A autenticação frequentemente torna visível uma migração de URL. Integrações OAuth podem exigir que endpoints de redirecionamento sejam registrados no servidor de autorização. Quando uma URI de redirecionamento completa é registrada, o OAuth 2.0 exige a comparação simples por string da URI solicitada. Uma mudança de https://example.com/app/callback para https://app.example.com/callback pode, portanto, exigir uma alteração de configuração no provedor de identidade, mesmo quando a própria aplicação está funcionando.
Faça um inventário de cada serviço externo que armazena ou exibe a URL pública. Isso normalmente inclui configurações de logon único, e-mails de redefinição de senha e convite, páginas incorporadas externamente, configuração de clientes de API, clientes móveis ou desktop e remetentes de webhook. Um valor antigo pode passar despercebido até que um usuário siga um fluxo raro de e-mail ou uma integração em segundo plano tente realizar uma entrega.
Webhooks merecem uma etapa de validação separada porque seu remetente é um cliente HTTP externo. A URL de payload configurada deve ser atualizada quando necessário, e a entrega deve ser testada depois que o novo endereço estiver ativo. Para serviços que validam certificados TLS, confirme que o endpoint apresenta o certificado válido esperado e está acessível publicamente na rota exigida.
- Liste cada URI de redirecionamento OAuth ou SSO antes do lançamento ou da migração.
- Envie convites reais de teste, redefinições de senha e e-mails de notificação para uma caixa de correio controlada.
- Teste o conteúdo incorporado a partir do site ou produto que efetivamente o hospedará.
- Faça o inventário dos remetentes de webhooks de entrada, atualize a configuração de endpoint deles e dispare uma entrega de teste.
- Verifique se há URLs-base codificadas diretamente em clientes de API e ferramentas de automação.
DNS, certificados TLS e roteamento para cada padrão
A escolha de um host cria trabalho de DNS e certificados. As autoridades certificadoras validam o controle dos nomes de domínio incluídos em um certificado; portanto, o host selecionado precisa resolver e rotear de uma forma que ofereça suporte ao método de validação escolhido. A validação HTTP-01 do Let’s Encrypt recupera um desafio em /.well-known/acme-challenge/ na porta 80. Assim, DNS e roteamento público fazem parte da preparação para o lançamento da aplicação, e não uma tarefa a deixar para depois da configuração da aplicação.
Um subdomínio normalmente precisa de um registro DNS para esse host e de um certificado que o cubra. Um domínio separado exige o mesmo trabalho para outro nome de domínio. Um subdiretório não adiciona um host, mas exige regras precisas de roteamento por caminho e coexistência com as rotas, os redirecionamentos e o tratamento de desafios do site principal.
Certificados curinga são uma escolha de design separada. O Let’s Encrypt documenta que HTTP-01 não pode emitir certificados curinga; a emissão de curinga exige a validação DNS-01. Não escolha uma abordagem curinga apenas para evitar o planejamento de hosts individuais, a menos que você possa operar com segurança o processo de validação DNS exigido.
- Confirme a propriedade do DNS e quem pode alterar os registros relevantes.
- Verifique se o host pretendido resolve antes da emissão do certificado e do lançamento público.
- Confirme que a porta 80 e a rota de desafio ACME podem ser acessadas ao usar a validação HTTP-01.
- Defina a precedência de roteamento para que o site principal, as rotas da aplicação e os caminhos de desafio não entrem em conflito.
- Ao usar Docker, exponha somente as portas que precisam de acesso externo; um proxy reverso pode alcançar serviços pela rede do host ou do Docker sem publicar todas as portas de contêineres publicamente.
Dados e governança: decida quem é responsável pelo limite
A estrutura de domínio deve refletir a propriedade operacional, assim como a experiência do usuário. Considere quem controla o registro do domínio, os registros DNS, as alterações relacionadas a certificados, a administração da aplicação, os contatos de cobrança e o acesso de emergência. Uma URL tecnicamente conveniente pode se tornar um risco operacional se depender de uma conta pessoal ou do acesso ao DNS de uma equipe não relacionada.
Um domínio separado pode ser útil quando um cliente, empresa adquirida, unidade regulada ou produto independente precisa de um limite público e administrativo mais claro. Um subdomínio dedicado pode fornecer um limite prático dentro de um domínio pai gerenciado centralmente. Um subdiretório geralmente deve ser reservado para casos em que um host compartilhado seja realmente necessário e o suporte da aplicação tenha sido verificado.
Nenhuma dessas escolhas resolve automaticamente a governança de acesso. Defina quem administra a aplicação, quem possui acesso ao DNS, quem aprova alterações de integração, onde os backups são governados e como o acesso é transferido se houver mudanças de pessoal ou fornecedores.
- Documente o proprietário legal e operacional de cada domínio e zona DNS.
- Evite o controle por uma única pessoa do registrador, DNS e acesso de administrador da aplicação.
- Atribua responsáveis pelas configurações do provedor de identidade, configurações de webhook e procedimentos de recuperação.
- Use um domínio separado quando um ciclo de vida independente ou um limite de propriedade for um requisito principal.
Planeje a migração: redirecionamentos ajudam, mas não atualizam todas as dependências
Um subdomínio costuma ser mais fácil de alterar do que uma implantação em subdiretório porque, em geral, a aplicação pode permanecer na raiz /. Isso não significa que mudanças de host não tenham consequências. O novo host muda a origem do navegador, pode precisar de um novo certificado e registro DNS, e pode exigir atualizações de callbacks registrados, destinos de webhook, clientes de API, modelos de e-mail e listas de permissões.
Uma migração de subdiretório para subdomínio pode simplificar a configuração futura do proxy, mas ainda altera a URL canônica. A orientação documentada de migração do GitLab é um exemplo concreto útil: alterar a URL muda as URLs de repositórios remotos, que os usuários talvez precisem atualizar manualmente. Redirecionamentos podem preservar links legados acessíveis pelo navegador, mas não reescrevem configurações remotas mantidas por todos os usuários ou sistemas de terceiros.
Teste os redirecionamentos de acordo com os tipos reais de solicitação que sua aplicação recebe. Redirecionamentos HTTP são um comportamento do cliente, não uma garantia de que todos os clientes responderão da mesma forma. A semântica HTTP também distingue o comportamento de métodos: 301 e 302 podem fazer com que um POST se torne um GET, enquanto 307 e 308 preservam o método. Não presuma que um redirecionamento testado em navegador comprova que um cliente de API ou remetente de webhook se comportará corretamente.
- Crie um inventário de URLs antigas antes de alterar o endereço canônico.
- Atualize a configuração da aplicação, provedores de identidade, remetentes de webhook, clientes de API, documentação e comunicações voltadas aos usuários.
- Mantenha um plano deliberado de redirecionamento para o tráfego de navegador, incluindo uma data de desativação e uma abordagem de monitoramento.
- Teste fluxos de trabalho baseados em POST e clientes externos separadamente da navegação GET comum.
- Avise os usuários quando eles precisarem atualizar manualmente remotos salvos, favoritos, configurações de clientes ou listas de permissões.
Perguntas frequentes
Um subdomínio ou subdiretório é melhor para uma aplicação auto-hospedada?
Um subdomínio dedicado normalmente é o padrão mais simples porque a aplicação pode operar a partir de /. Escolha um subdiretório apenas quando precisar de um host compartilhado e a documentação oficial da aplicação, juntamente com um teste de homologação, confirmar suporte confiável a URLs relativas ou webroot.
Um proxy reverso pode fazer qualquer aplicação funcionar em um subdiretório?
Não. Um proxy reverso pode remover um prefixo de caminho público antes de encaminhar solicitações, mas a aplicação ainda precisa gerar recursos, redirecionamentos, links e integrações usando o prefixo público. O roteamento do proxy, por si só, não fornece suporte de URL-base no nível da aplicação.
Os cookies tornam os subdiretórios inseguros?
O Path de cookie limita quando um navegador envia um cookie, mas não é um limite de segurança. Aplicações sob um único host precisam de configuração deliberada de cookies e não devem depender da separação por caminho como proteção entre serviços administrados de forma independente.
O que precisa mudar ao mover uma aplicação para um novo host?
Revise a URL canônica da aplicação, DNS, certificado TLS, URIs de redirecionamento OAuth ou SSO, links de redefinição de senha e convite, URLs de payload de webhook, clientes de API, conteúdo incorporado, documentação, listas de permissões e clientes configurados pelos usuários. Redirecionamentos podem ajudar com links de navegador, mas não atualizam automaticamente configurações externas.
Como a Airbip pode ajudar com o roteamento de URL em uma implantação gerenciada de aplicações?
A Airbip implanta aplicações do catálogo como cargas de trabalho Docker em servidores de nuvem da Airbip e automatiza o roteamento e os certificados TLS por meio do Traefik e do Let’s Encrypt. Também inclui verificações de DNS, gerenciamento do ciclo de vida dos serviços e backups diários, semanais e mensais configuráveis. Os clientes podem usar um subdomínio da Airbip ou um domínio personalizado compatível. O cliente ainda precisa escolher a URL apropriada para a aplicação, verificar o suporte da aplicação no nível da URL-base, configurar identidade e integrações e tomar as decisões relevantes sobre dados, acesso e governança.
Fontes e leituras adicionais
- Traefik StripPrefix middleware documentation — Traefik Labs
- GitLab: Install under a relative URL — GitLab
- GitLab: Migrate from a relative URL to a subdomain — GitLab
- Nextcloud Server Administration Manual — Nextcloud GmbH
- RFC 6265: HTTP State Management Mechanism — IETF
- RFC 6749: The OAuth 2.0 Authorization Framework — IETF
- RFC 6454: The Web Origin Concept — IETF
- RFC 9110: HTTP Semantics — IETF
- Challenge Types — Let’s Encrypt / Internet Security Research Group
- Docker networking overview — Docker