Esta referência explica como os links permanentes do Discourse redirecionam caminhos de URL antigos para novos destinos, como as normalizações de links permanentes funcionam e como testar e solucionar problemas de redirecionamentos após uma migração ou alteração na estrutura de URLs.
Nível de usuário necessário: Administrador
Acesso ao console necessário apenas ao criar links permanentes a partir de um importador, script ou console do Rails
Quando você migra de outro fórum ou altera a estrutura de URLs do seu site, os links antigos de mecanismos de busca, favoritos, e-mails ou outros sites podem não apontar mais para a página correta.
Os links permanentes permitem redirecionar caminhos de URL antigos para seus novos destinos usando redirecionamentos 301 Moved Permanently (Movido Permanentemente).
Os links permanentes são mapeamentos de caminho exatos. Por exemplo, se esta URL antiga não funcionar mais:
https://discourse.example.com/forum/topic/123
você pode criar um link permanente para que ele redirecione para o novo tópico:
https://discourse.example.com/t/welcome-to-our-community/456
O que são links permanentes
Um link permanente é um mapeamento exato de um caminho de URL antigo para um novo destino.
Por exemplo:
forum/topic/123 → /t/welcome-to-our-community/456
Os links permanentes são úteis quando:
- você migrou de outra plataforma de fórum
- links antigos estão indexados por mecanismos de busca
- links antigos são usados em e-mails, documentação ou outros sites
- você alterou a estrutura das URLs do seu site
- você deseja que um caminho antigo redirecione para um tópico, postagem, categoria, tag, usuário ou URL externo
Cada URL de link permanente mapeia para um único destino.
Os links permanentes são correspondências exatas. O campo de URL do link permanente não suporta curingas ou expressões regulares. Se muitas URLs antigas seguirem um padrão previsível, use normalizações de links permanentes para transformar os URLs de entrada antes da busca exata do link permanente.
Links permanentes e normalizações
Links permanentes e normalizações fazem coisas diferentes:
| Recurso | O que ele faz | Exemplo |
|---|---|---|
| Link permanente | Redireciona um caminho antigo salvo para um destino | old/topic/123 → Tópico 456 |
| Normalização | Altera o caminho de entrada antes da busca do link permanente | old/topic/123-title → old/topic/123 |
Uma normalização não redireciona por si só. Ela apenas altera o caminho usado para procurar um link permanente salvo.
Você ainda precisa de um link permanente correspondente após a normalização ser aplicada.
Exemplos rápidos
Redirecionar uma URL de tópico antigo
URL antiga:
https://discourse.example.com/forum/topic/123
URL do link permanente:
forum/topic/123
Tipo de destino:
Tópico
Destino:
456
Resultado:
/forum/topic/123 → /t/welcome-to-our-community/456
Redirecionar uma URL antiga com string de consulta
URL antiga:
https://discourse.example.com/viewtopic.php?t=123
URL do link permanente:
viewtopic.php?t=123
Tipo de destino:
Tópico
Destino:
456
Resultado:
/viewtopic.php?t=123 → /t/welcome-to-our-community/456
Redirecionar muitas URLs antigas com o mesmo padrão
URLs antigas:
/forum/support/123-how-do-i-reset-my-password.html
/forum/general/456-how-do-i-change-my-email.html
Você pode usar uma normalização para simplificá-las antes da busca:
/forum/support/123-how-do-i-reset-my-password.html → forum/123
/forum/general/456-how-do-i-change-my-email.html → forum/456
Em seguida, crie links permanentes exatos:
forum/123 → Tópico 1001
forum/456 → Tópico 1002
O que inserir como URL do link permanente
Insira o caminho antigo, não a URL completa.
Por exemplo, use:
forum/topic/123
ou:
/forum/topic/123
Não use a URL antiga completa:
https://discourse.example.com/forum/topic/123
Barras iniciais são aceitas, mas são removidas quando o link permanente é salvo. Estas duas entradas são equivalentes:
/forum/topic/123
forum/topic/123
Ambas são armazenadas como:
forum/topic/123
Espaços em branco iniciais e finais são removidos quando o link permanente é salvo.
Strings de consulta fazem parte da correspondência
Os links permanentes correspondem ao caminho completo da solicitação, incluindo a string de consulta.
Isso significa que estas duas URLs são correspondências de link permanente diferentes:
/old/topic/123
/old/topic/123?utm_source=example
Se a URL antiga tiver uma string de consulta, você deve:
- criar um link permanente que inclua a string de consulta, ou
- usar uma normalização de link permanente para remover ou simplificar a string de consulta antes da correspondência
Para a maioria dos parâmetros de análise ou rastreamento, usar uma normalização geralmente é melhor do que criar muitos links permanentes separados.
Por exemplo, este link permanente salvo:
docs/123
não necessariamente corresponderá a esta URL solicitada:
/docs/123?utm_source=newsletter
a menos que uma normalização remova a string de consulta antes da busca.
Ao copiar URLs antigas de ferramentas de análise, relatórios do console de pesquisa, navegadores ou campanhas de e-mail, verifique se parâmetros de rastreamento foram adicionados.
Fragmentos de URL não fazem parte da correspondência
Fragmentos de URL não são enviados ao servidor.
Por exemplo, esta URL:
/old/topic#post-12
chega ao servidor como:
/old/topic
Um link permanente ou normalização não pode corresponder a:
#post-12
a menos que o # seja codificado na solicitação real como %23.
Destinos de link permanente suportados
Um link permanente pode redirecionar para um dos seguintes tipos de destino:
- Tópico
- Postagem
- Categoria
- Tag
- Usuário
- URL externo ou relativo
Destinos de URL externo ou relativo podem ser usados para redirecionamentos como:
old/privacy-policy → https://archive.discourse.example.com/privacy
ou:
old/preferences → /my/preferences
Use destinos de URL externo com cuidado. Eles redirecionam os visitantes para fora do seu site e não verificam se a URL de destino existe.
Prefira tipos de destino internos ao redirecionar para tópicos, postagens, categorias, tags ou usuários migrados. Use um destino de URL externo quando a página de destino não for representada por um objeto interno.
Adicionar um link permanente manualmente
Para adicionar um link permanente manualmente:
- Acesse
/admin/config/permalinks. - Selecione a aba Permalinks (Links permanentes).
- Clique em Add permalink (Adicionar link permanente).
- Insira o caminho antigo no campo URL.
- Selecione o Tipo de link permanente.
- Insira ou selecione o destino.
- Salve o link permanente.
- Teste a URL antiga em um navegador ou com
curl.
Exemplo:
URL:
forum/topic/123
Tipo de link permanente:
Tópico
Destino:
456
Uma solicitação para:
https://discourse.example.com/forum/topic/123
redirecionará para o tópico 456.
Valores de destino
O valor do destino depende do tipo de link permanente.
| Tipo de link permanente | Destino |
|---|---|
| Tópico | Um tópico |
| Postagem | Uma postagem |
| Categoria | Uma categoria |
| Tag | Uma tag |
| Usuário | Um usuário |
| URL externo ou relativo | Uma URL externa completa ou um caminho relativo |
Exemplos:
forum/topic/123 → Tópico 456
forum/post/789 → Postagem 789
forum/category/support → Categoria support
forum/tag/example → Tag example
forum/user/alice → Usuário alice
old/privacy → https://archive.discourse.example.com/privacy
old/preferences → /my/preferences
Criando links permanentes durante uma migração
Muitos importadores oficiais criam links permanentes automaticamente para categorias, tópicos, postagens ou usuários migrados.
Para migrações grandes, os links permanentes são geralmente criados pelo importador ou por um script de migração, em vez de serem inseridos manualmente um por um.
Se você estiver escrevendo um importador personalizado, crie registros de link permanente para URLs antigas que devem continuar funcionando após a migração.
Por exemplo:
Permalink.create!(url: "discussion/12345", topic_id: 987)
Neste exemplo, discussion/12345 é o caminho antigo e 987 é o ID do tópico do Discourse.
Uma barra inicial também é aceita:
Permalink.create!(url: "/discussion/12345", topic_id: 987)
Ambos os exemplos armazenam a URL do link permanente como:
discussion/12345
Para redirecionar para um URL externo:
Permalink.create!(
url: "discussion/12345",
external_url: "https://archive.discourse.example.com/discussion/12345"
)
Ao criar links permanentes em um importador:
- armazene o caminho antigo, não o domínio antigo completo
- inclua a string de consulta apenas se for necessária para a correspondência
- certifique-se de que cada caminho antigo mapeie para um único destino
- verifique duplicatas antes de inserir registros
- lembre-se de que as URLs dos links permanentes devem ser únicas
Se você executar várias migrações de teste, os IDs finais de tópicos e postagens podem mudar entre as execuções. Gere ou verifique seus mapeamentos finais de link permanente quando os dados de migração de produção estiverem estáveis.
O que são normalizações de link permanente
Uma normalização de link permanente altera um caminho antigo de entrada antes de procurar um link permanente correspondente.
As normalizações são úteis quando muitas URLs antigas seguem o mesmo padrão previsível.
Por exemplo, suponha que seu fórum antigo usasse URLs como esta:
/forum/support/123-how-do-i-reset-my-password.html
mas seu link permanente salvo seja mais simples:
forum/123
Uma normalização pode transformar a solicitação de entrada no caminho do link permanente salvo:
/forum/support/123-how-do-i-reset-my-password.html
↓
forum/123
Em seguida, o link permanente pode redirecionar:
forum/123 → /t/how-do-i-reset-my-password/456
Uma normalização não redireciona por si só. Ela apenas altera o caminho usado para a busca do link permanente.
Você ainda precisa de um link permanente correspondente para o caminho normalizado.
A maioria dos sites não precisa de normalizações de link permanente. Use-as apenas quando muitas URLs antigas seguirem um padrão previsível e criar um link permanente por URL antigo for impraticável.
Como links permanentes e normalizações funcionam juntos
Quando uma URL antiga é solicitada, o processo é:
Visitante solicita URL antiga
↓
As normalizações de link permanente são aplicadas, se configuradas
↓
Uma busca de link permanente é realizada usando o caminho resultante
↓
Se um link permanente correspondente existir, o visitante é redirecionado
Por exemplo:
URL solicitada:
/old/topic/123?utm_source=newsletter
A normalização a altera para:
old/topic/123
O link permanente a redireciona para:
/t/new-topic-title/456
Adicionar uma normalização de link permanente
As normalizações de link permanente são configuradas nas configurações de link permanente.
Para adicionar uma:
- Acesse
/admin/config/permalinks. - Selecione a aba Settings (Configurações).
- Adicione uma regra à configuração
permalink normalizations. - Salve a configuração.
- Teste uma URL antiga que deve ser normalizada.
- Confirme que o caminho normalizado corresponde a um link permanente existente.
A sintaxe é:
/<regex>/<replacement>
Múltiplas regras são separadas por |.
Por exemplo:
/old\/topic\/(\d+).*/topic/\1
Isso pode transformar:
old/topic/123-my-old-title
em:
topic/123
A substituição usa a sintaxe de substituição do Ruby, então os grupos de captura são escritos como:
\1
\2
\3
Regras importantes de normalização
Mantenha as regras de normalização simples.
- As normalizações usam expressões regulares do Ruby.
- Caracteres
/literais na parte regex devem ser escapados como\/. - Caracteres
/literais na parte de substituição não precisam ser escapados. - Múltiplas regras de normalização são separadas por
|. - Como
|separa regras, evite usar alternância regex com|. - Cada regra usa uma única substituição, não uma substituição global.
- As regras são aplicadas em ordem.
- As regras correspondentes são aplicadas sequencialmente.
- As normalizações são aplicadas antes da busca do link permanente.
- As normalizações também são aplicadas ao salvar registros de link permanente.
- O validador de configuração detecta expressões regulares inválidas, mas pode não detectar todas as regras que se comportam de maneira diferente do pretendido.
Aviso: As normalizações são aplicadas quando os registros de link permanente são salvos. Se você inserir uma URL não normalizada na interface administrativa, ela pode ser armazenada como o resultado normalizado. Se você adicionar ou alterar normalizações após criar links permanentes, teste cuidadosamente e verifique como as URLs dos links permanentes recém-salvos são armazenadas.
Exemplos de normalização
Redirecionar uma URL antiga com texto de título extra
URLs antigas:
/forum/support/123-how-do-i-reset-my-password.html
/forum/general/456-how-do-i-change-my-email.html
Você pode normalizá-las para caminhos de link permanente mais simples:
forum/123
forum/456
Exemplo de normalização:
/forum\/[^\/]+\/(\d+).*/forum/\1
Em seguida, crie links permanentes:
forum/123 → Tópico 1001
forum/456 → Tópico 1002
Ignorar strings de consulta de rastreamento
URL antiga solicitada:
/docs/123?utm_source=newsletter
Link permanente salvo:
docs/123
Normalização:
/(docs\/\d+)\?.*/\1
Isso remove a string de consulta antes da busca do link permanente.
Preservar um parâmetro de consulta importante
Alguns fóruns antigos usam parâmetros de consulta como identificador estável do tópico.
Por exemplo:
viewtopic.php?f=10&t=123
viewtopic.php?t=123
Você pode querer normalizá-los para:
viewtopic.php?t=123
Exemplo de normalização:
/(viewtopic\.php\?)(?:.*&)?(t=\d+).*/\1\2
Em seguida, crie um link permanente:
viewtopic.php?t=123 → Tópico 456
Redirecionamentos de regex e curinga
O campo de URL do link permanente não suporta regexes ou curingas.
Isso não funcionará como uma URL de link permanente:
forum/topic/*
Isso também não funcionará como uma URL de link permanente:
forum/topic/(\d+)
Se você precisar de manipulação baseada em padrões, use uma normalização de link permanente para reescrever a URL de entrada em uma forma que possa corresponder a um link permanente salvo exato.
Por exemplo:
/forum/topic/123-title → forum/topic/123
Em seguida, crie um link permanente exato normal:
forum/topic/123 → Tópico 456
Precedência de rotas e caminhos embutidos
O roteamento de link permanente é verificado após as rotas de aplicativo padrão.
Isso significa que uma rota existente válida pode ser resolvida normalmente antes que um link permanente seja verificado.
Tenha cuidado com URLs antigas que começam com caminhos embutidos, como:
/t
/c
/u
/tag
/tags
Por exemplo, uma URL de fórum antigo como esta pode parecer uma rota de categoria embutida:
/c/blog/old-platform-url/ba-p/12345
Se uma URL antiga entrar em conflito com uma rota existente válida, a rota válida pode ter precedência sobre o link permanente.
Da mesma forma, se você criar um link permanente para um caminho que se parece com uma rota de tópico existente, como:
t/123
a rota normal do tópico pode ser tratada antes da busca do link permanente.
Algumas rotas embutidas de “não encontrado” têm comportamento de fallback adicional, mas você não deve depender disso. Sempre teste URLs antigas que se sobrepõem a caminhos embutidos.
Se você precisar que uma URL de tópico antigo redirecione para outro lugar, o tópico antigo geralmente não deve continuar sendo resolvido como uma rota de tópico válida.
Permissões e conteúdo privado
Links permanentes para destinos internos respeitam as permissões normais.
Se um link permanente apontar para um tópico, postagem, categoria, tag ou usuário privado ou restrito, os visitantes que não puderem acessar esse destino receberão um 404 em vez de um redirecionamento.
Links permanentes para URLs externos não verificam as permissões de conteúdo interno.
Caracteres especiais e URLs codificadas
Teste URLs com caracteres especiais cuidadosamente.
Isso inclui URLs com:
- espaços
+%&':- parênteses
- caracteres não latinos
A correspondência de link permanente usa o caminho da solicitação codificado após remover a barra inicial e aplicar as normalizações configuradas. Diferenças de codificação podem impedir que uma URL corresponda ao link permanente que você espera.
Por exemplo, estes podem não ser equivalentes dependendo de como a URL antiga é solicitada e armazenada:
old/topic/hello%20world
old/topic/hello+world
Use %20 para espaços em exemplos de URL. Em um caminho de URL, + não é o mesmo que um espaço.
Caracteres como &, ? e # têm significado especial em URLs. Se eles forem destinados a ser caracteres de caminho literais, eles devem ser codificados em porcentagem.
Em caso de dúvida, teste a URL antiga exata que os usuários ou mecanismos de busca solicitarão.
Limitações
Os links permanentes foram projetados para redirecionar caminhos antigos para novos destinos. Eles não são um mecanismo de redirecionamento ou reescrita de propósito geral.
Limitações importantes:
- As URLs dos links permanentes são armazenadas como caminho e strings de consulta, não URLs completos.
- URLs completos não são convertidos automaticamente em caminhos.
- As URLs dos links permanentes devem ser únicas após a normalização.
- Uma URL de link permanente pode ter apenas um destino.
- Os destinos suportados são limitados a tópicos, postagens, categorias, tags, usuários e URLs externos ou relativos.
- Os links permanentes usam
301 Moved Permanently; não há opção por link permanente para302. - O campo de URL do link permanente não suporta curingas ou expressões regulares.
- As strings de consulta fazem parte da chave de busca.
- Fragmentos de URL, como
#post-12, não são enviados ao servidor e não podem ser correspondidos. - A correspondência não usa o esquema ou host da solicitação.
- As rotas nativas são verificadas antes da rota de link permanente catch-all.
- Os destinos internos são verificados quanto a permissões.
- Os destinos de URL externo ignoram as verificações de permissão de conteúdo interno.
- As normalizações de link permanente usam expressões regulares do Ruby.
- As regras de normalização são separadas por
|, portanto, evite usar|como alternância regex. - As regras de normalização usam uma única substituição por regra, não uma substituição global.
- As normalizações são aplicadas tanto antes da busca quanto antes de salvar os registros de link permanente.
- O validador de configuração detecta expressões regulares inválidas, mas pode não detectar todas as regras que se comportam de maneira diferente do pretendido.
Para a maioria dos sites, links permanentes simples de um para um são mais fáceis de manter do que regras de normalização complexas. Use normalizações apenas quando as URLs antigas seguirem um padrão previsível.
Evite redirecionar todas as URLs antigas para a página inicial
Não redirecione todas as URLs antigas para a sua página inicial.
Redirecione cada URL antiga para a nova página mais relevante. Se não houver conteúdo equivalente, um 404 pode ser melhor do que enviar usuários e mecanismos de busca para uma página não relacionada.
Os bons redirecionamentos são específicos:
old/topic/123 → novo tópico sobre o mesmo assunto
Os redirecionamentos ruins são genéricos:
old/topic/123 → página inicial
old/topic/456 → página inicial
old/topic/789 → página inicial
Teste seus redirecionamentos
Após criar links permanentes ou normalizações, teste uma amostra de URLs antigas.
Você pode testar em um navegador ou usar:
curl -I https://discourse.example.com/forum/topic/123
Um redirecionamento de link permanente funcionando deve retornar um redirecionamento permanente semelhante a:
HTTP/2 301
location: https://discourse.example.com/t/welcome-to-our-community/456
Teste exemplos de cada padrão de URL antiga, incluindo:
- URLs de tópicos antigos
- URLs de categorias antigas
- URLs de postagens antigas
- URLs com strings de consulta
- URLs com caracteres especiais
- URLs de resultados de pesquisa
- URLs de e-mails ou documentações antigas
- URLs que começam com caminhos embutidos como
/t,/cou/u - redirecionamentos para URLs externos
Solução de problemas
Se uma URL antiga não redirecionar, verifique estas causas comuns:
- Confirme se o link permanente existe.
- Confirme se a URL do link permanente é o caminho antigo, não o domínio antigo completo.
- Verifique se a URL antiga inclui uma string de consulta.
- Se estiver usando uma normalização, confirme se o caminho normalizado corresponde a um link permanente salvo.
- Verifique se uma rota embutida está tendo precedência.
- Verifique se o destino é privado ou restrito.
- Verifique diferenças de codificação, como
%20vs+. - Verifique se uma normalização alterou a URL quando o link permanente foi salvo.
- Confirme se o conteúdo foi migrado.
- Teste com a URL antiga exata de um navegador ou com
curl -I.
Os problemas mais comuns são:
- inserir a URL antiga completa em vez do caminho antigo
- strings de consulta ausentes ou inesperadas
- esperar que curingas ou regexes funcionem no campo de URL do link permanente
- URLs antigas sobrepostas com caminhos embutidos
- destinos privados ou restritos
- diferenças de codificação
- normalizações alterando o caminho inesperadamente
Notas de SEO
Após uma migração, os mecanismos de busca podem relatar URLs antigos como redirecionados. Isso é esperado se essas URLs antigas agora redirecionarem para as novas páginas corretas.
Para melhores resultados:
- redirecione URLs antigas para páginas novas relevantes
- evite cadeias de redirecionamento desnecessárias
- evite redirecionar muitas URLs não relacionadas para a página inicial
- mantenha os redirecionamentos ativos por tempo suficiente para que usuários e mecanismos de busca atualizem
- teste URLs importantes a partir de dados do seu sitemap antigo, análise ou console de pesquisa