Orbit
Configurazione di Reindirizzamenti e Riscritture
Orbit has a built-in redirect and rewrite engine that runs before your project is asked for anything, configured either in KPanel or as a file in your repository. This guide covers both, the pattern…
Orbit ha un motore integrato di reindirizzamento e riscrittura che funziona prima che il tuo progetto riceva richieste, configurabile sia in KPanel che come file nel tuo repository. Questa guida copre entrambi i metodi, la sintassi dei pattern e le loro acquisizioni, come vengono ordinate le regole, i limiti e il comportamento che sorprende gli utenti.
Dove configurare le regole
Ci sono due posti, e vengono valutati in un ordine fisso.
- In KPanel. Apri il tuo progetto in Orbit, vai su Settings, e scorri alla sezione redirects and rewrites per l'ambiente. Ogni ambiente ha il suo set di regole indipendente, quindi produzione e staging vengono configurati separatamente.
- Nel tuo repository, come file
kaps.json. Questo è coperto più avanti.
Le regole del panel vengono valutate per prime. Se nessuna di loro corrisponde, vengono provate le regole kaps.json.
Aggiungere una regola in KPanel
- Fai clic su Add rule.
- Compila l'origine, il pattern del percorso da abbinare alle richieste in arrivo. Il placeholder mostra le due forme che si aspetta:
/old-path or /blog/:slug. - Compila la destinazione. Il placeholder mostra
/new-path or https://..., quindi sono validi sia un percorso locale che un URL esterno completo. - Scegli il tipo di regola:
- 301 Permanent: l'URL si è spostato definitivamente. I browser e i motori di ricerca lo memorizzano nella cache.
- 302 Temporary: spostato per ora, non memorizzato nella cache. Usalo per campagne e esperimenti.
- Rewrite: servi il percorso di destinazione senza cambiare l'URL nella barra degli indirizzi del browser.
- Fai clic su Save rules.
Le regole entrano in vigore dal prossimo deployment, non immediatamente. Salvare una regola non cambia ciò che serve il deployment attualmente in esecuzione. Rideploya dopo il salvataggio, altrimenti le tue regole sembreranno non funzionare.
Un 301 è memorizzato nella cache dai browser, a volte per molto tempo, e non c'è nulla che puoi fare dal server per cancellarlo. Se non sei sicuro che uno spostamento sia permanente, usa prima un 302 e passalo a 301 una volta che ne sei sicuro. Sbagliare questo su un percorso ad alto traffico è genuinamente difficile da recuperare.
Pattern dei percorsi di origine
| Pattern | Corrisponde a | Acquisizioni |
|---|---|---|
/old-page | Esattamente /old-page | Niente |
/blog/* | Qualsiasi cosa che inizia con /blog/ | Il resto del percorso, referenziato come * nella destinazione |
/posts/:id | /posts/ più un segmento di percorso | Quel segmento, come :id |
/files/:rest* | /files/ più tutto ciò che segue, barre incluse | L'intero resto, come :rest |
La differenza tra :id e :rest* è quella importante. Un parametro denominato corrisponde a un singolo segmento e si ferma alla barra successiva. Un splat corrisponde a tutto il resto, incluse le barre.
Utilizzo delle acquisizioni nella destinazione
Referenzia un parametro denominato per nome, e un wildcard nudo come *:
| Origine | Destinazione | Risultato |
|---|---|---|
/blog/:slug | /articles/:slug | /blog/hello-world diventa /articles/hello-world |
/docs/:rest* | /help/:rest* | /docs/a/b/c diventa /help/a/b/c |
/old/* | /new/* | /old/a/b diventa /new/a/b |
Ordine delle regole
Le regole vengono testate dall'alto dell'elenco in basso e la prima corrispondenza vince. Una volta che una regola corrisponde, nessuna regola successiva viene considerata. Il panel lo dice sotto l'elenco: "Rules are tested in order. First match wins."
Posiziona le regole specifiche sopra quelle generali. Una regola /blog/* posizionata sopra /blog/2023/:slug inghiottirà ogni richiesta che la regola più specifica era destinata a gestire, e sembrerebbe che la regola specifica sia semplicemente rotta.
Se nessuna regola corrisponde, la richiesta viene servita normalmente.
Casi di utilizzo comuni
Rinominare una pagina
Hai rinominato /about-us in /about e vuoi che i vecchi link continuino a funzionare.
- Origine:
/about-us - Destinazione:
/about - Tipo: 301 Permanent
Spostare un'intera sezione
Il tuo blog si è spostato da /news/:slug a /blog/:slug.
- Origine:
/news/:slug - Destinazione:
/blog/:slug - Tipo: 301 Permanent
Proxying silenzioso di un percorso API
Vuoi che /api/v1/* venga servito da un diverso percorso interno senza esporre il cambiamento.
- Origine:
/api/v1/:path* - Destinazione:
/api/internal/:path* - Tipo: Rewrite
Una pagina di attesa temporanea
- Origine:
/checkout - Destinazione:
/maintenance - Tipo: 302 Temporary
Inviare traffico a un altro dominio
La destinazione può essere un URL assoluto, quindi una regola può puntare a un sito completamente diverso.
- Origine:
/shop/:rest* - Destinazione:
https://shop.example.com/:rest* - Tipo: 301 Permanent
Configurazione come codice con kaps.json
Le regole possono vivere nel tuo repository invece che nel panel. Aggiungi un file kaps.json, e assicurati che il tuo build lo copi nella output directory, perché Orbit lo legge dalla radice dell'artifact compilato piuttosto che dalla radice del repository.
{
"redirects": [
{ "source": "/about-us", "destination": "/about", "permanent": true },
{ "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
{ "source": "/promo", "destination": "/spring-sale", "permanent": false }
],
"rewrites": [
{ "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
],
"headers": [
{
"source": "/*",
"headers": [
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "X-Content-Type-Options", "value": "nosniff" }
]
}
]
}
permanent: true produce un 301 e permanent: false un 302. Ometterlo produce un 301.
kaps.json si applica ai deployment statici solamente. Se Server mode è attivo, la tua app gestisce il proprio routing e il file viene ignorato. Viene anche valutato solamente dopo che le regole del panel dell'ambiente hanno fallito la corrispondenza, quindi una regola del panel batte sempre una regola del file per lo stesso percorso.
Usa kaps.json quando le regole appartengono al codice, così vengono riviste in una pull request e si muovono con un rollback. Usa il panel quando hai bisogno che una regola sia in vigore adesso senza un deploy. Non mantenere la stessa regola in entrambi i posti: la regola del panel avrà sempre la precedenza e la regola del file sembrerebbe essere ignorata, e lo è.
Limiti
- Fino a 100 regole di redirect e rewrite per ambiente, e 100 in un
kaps.json. - Fino a 200 regole di intestazioni personalizzate per ambiente.
Le regole oltre il limite vengono eliminate silenziosamente piuttosto che generare un errore, quindi stai ben al di sotto di esso.
Intestazioni di risposta personalizzate
Insieme ai redirect, ogni ambiente ha una sezione di intestazioni di risposta in Settings per iniettare intestazioni HTTP su percorsi corrispondenti. Usa la stessa sintassi di pattern di percorso, e ci sono preset di aggiunta rapida per HSTS, CSP, no-embed, no-sniff, politica referrer e CORS.
A differenza dei redirect, tutte le regole di intestazione corrispondenti vengono applicate, non solo la prima, e una regola successiva sovrascrive una precedente quando impostano la stessa intestazione. Content-Length, Transfer-Encoding e Connection sono bloccate, perché impostarle corromperebbe la risposta.
Comportamento che vale la pena conoscere prima di fare affidamento su di esso
Le stringhe di query non vengono trasportate attraverso un redirect. Una regola corrisponde indipendentemente dal fatto che la richiesta abbia una stringa di query, ma la destinazione viene costruita dal tuo template e dai segmenti di percorso acquisiti solamente. Una richiesta a /old?utm_source=email reindirizza a /new, con i parametri eliminati. Se dipendi dal fatto che i parametri di tracciamento sopravvivano, gestisci il redirect in una funzione edge, dove controlli completamente l'URL di destinazione.
- Le regole corrispondono solo al percorso. I frammenti (
#section) non raggiungono mai il server; il browser li riattacca dopo un redirect. - Un rewrite a un percorso che non esiste produce un 404, piuttosto che cadere silenziosamente nel percorso originale. I target di rewrite devono esistere nel tuo output di build.
- Le regole vengono eseguite prima che il tuo progetto riceva richieste, quindi si applicano sia ai file statici che alle richieste server-mode.
- Ogni ambiente è indipendente. Le regole sulla produzione non si applicano a staging o preview. Copiale deliberatamente.
Eliminare una regola
Fai clic sull'icona del cestino sulla riga della regola, quindi fai clic su Save rules per applicare la modifica. Come con l'aggiunta di una, la modifica entra in vigore dal prossimo deployment.
Quando utilizzare invece una funzione edge
Il motore di redirect gestisce regole da percorso a percorso. Ricorri a una funzione edge quando hai bisogno di logica che il motore di regole non può esprimere: diramazione su un'intestazione o un cookie, conservazione o riscrittura di parametri di query, routing A/B ponderato, o qualsiasi cosa condizionale.