Quando uno script di deploy tocca sitemap, redirect e canonical, il problema non è solo “farlo partire”. Il punto vero è capire cosa succede quando fallisce a metà. In SEO tecnico, un errore in uno step può lasciare file aggiornati a metà, cache incoerenti e URL fuori indice.
Qui vediamo un caso concreto: uno script Bash per pubblicare sitemap e regole di redirect, con controllo errori, rollback e ripristino. Il contesto è reale: un sito Next.js dietro CDN, con generazione di sitemap dinamiche, log di deploy e validazione post-pubblicazione.
Warning: non affidarti a uno script “felice” che esce con codice 0 anche quando fallisce un curl o un cp. In SEO, il falso positivo costa traffico e crawling budget.
Prerequisiti
Servono pochi strumenti, ma vanno usati bene.
- Shell Bash 4+ su Linux.
- set -euo pipefail per interrompere l’esecuzione su errori reali.
- curl per verificare endpoint pubblici.
- jq per leggere risposte JSON, se l’API del CMS lo richiede.
- rsync o cp per il backup dei file SEO critici.
- Accesso SSH al server o al runner CI.
Note: se lavori su Windows, puoi adattare il flusso in PowerShell. La logica resta la stessa: pre-check, esecuzione, verifica, rollback.
Step numerati
1. Metti in sicurezza lo script prima di toccare i file SEO
Il primo obiettivo è impedire che uno step fallito venga ignorato. In un deploy SEO, i file più delicati sono sitemap.xml, robots.txt e i redirect statici.
Con Bash, la base minima è questa:
#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
trap 'echo "ERRORE alla riga $LINENO" >&2' ERR
# Output: lo script si ferma al primo errore non gestito e stampa la riga precisa.
Perché serve: senza queste opzioni, un comando fallito dentro una pipeline può passare inosservato. Poi la sitemap viene pubblicata a metà, ma il log mostra “deploy ok”.
Warning: non usare set -e da solo come scusa per non controllare i return code. Alcuni costrutti Bash lo aggirano. Meglio scrivere check espliciti.
2. Crea un backup atomico prima della modifica
Il rollback funziona solo se hai uno stato precedente affidabile. Per SEO tecnico, conviene salvare i file pubblici e una copia dei redirect.
BACKUP_DIR="/var/backups/seo-$(date +%F-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp /var/www/site/public/sitemap.xml "$BACKUP_DIR/"
cp /var/www/site/public/robots.txt "$BACKUP_DIR/"
cp /var/www/site/config/redirects.conf "$BACKUP_DIR/"
# Output: una cartella con i tre file critici, pronta per il ripristino.
Perché serve: se un generator produce una sitemap vuota, puoi tornare alla versione precedente in pochi secondi. Senza backup, devi ricostruire tutto a mano e intanto i crawler leggono un file sbagliato.
Note: per ambienti più robusti, usa rsync con checksum e retention. Un backup locale è veloce, ma non sostituisce una copia esterna.
3. Esegui la generazione e controlla ogni uscita
Il problema classico è uno script esterno che genera la sitemap ma fallisce con exit code non zero solo in alcuni casi. Qui devi distinguere tra “file creato” e “file valido”.
generate_sitemap() {
node scripts/build-sitemap.mjs
}
if ! generate_sitemap; then
echo "Generazione sitemap fallita" >&2
exit 1
fi
if [ ! -s /var/www/site/public/sitemap.xml ]; then
echo "sitemap.xml assente o vuoto" >&2
exit 1
fi
# Output: la generazione termina solo se il file esiste ed è non vuoto.
Perché serve: un file vuoto è peggio di nessun file. Googlebot e altri crawler vedono un endpoint valido ma inutile. Il danno non è immediato, però l’effetto dura giorni.
Warning: non fidarti solo del timestamp del file. Un file recente può essere corrotto o troncato.
4. Valida HTTP, canonical e status code prima di pubblicare
Una sitemap corretta non basta. Devi controllare che le URL indicizzabili rispondano bene e che i canonical non puntino a versioni sbagliate.
curl -fsS https://www.example.com/sitemap.xml -o /tmp/sitemap.xml
curl -fsS -I https://www.example.com/
curl -fsS https://www.example.com/ | grep -i 'rel="canonical"'
# Output: sitemap scaricata, homepage con header validi, canonical presente nel markup.
Perché serve: spesso il deploy rompe il file, ma il problema vero è altrove. Un canonical che punta a HTTP, un 404 nascosto o un 301 catena lunga possono bloccare il valore SEO.
Se hai molte URL, aggiungi un controllo automatico sui codici risposta:
while read -r url; do
code=$(curl -o /dev/null -s -w '%{http_code}' "$url")
if [ "$code" != "200" ]; then
echo "URL non valida: $url -> $code" >&2
exit 1
fi
done < /var/www/site/public/important-urls.txt
# Output: lo script interrompe il deploy appena incontra un 404, 500 o altro codice anomalo.
5. Pubblica in modo atomico e conserva il rollback
Mai copiare direttamente il file finale sopra quello live senza una strategia. Se il copy si interrompe, rischi un file parziale. Meglio lavorare con un file temporaneo e un mv finale.
tmpfile="/var/www/site/public/.sitemap.xml.new"
cp /tmp/sitemap.xml "$tmpfile"
if grep -q '<urlset' "$tmpfile"; then
mv "$tmpfile" /var/www/site/public/sitemap.xml
else
echo "Sitemap non valida, nessun publish" >&2
rm -f "$tmpfile"
exit 1
fi
# Output: il file live viene sostituito solo dopo una verifica minima del contenuto.
Perché serve: mv sulla stessa filesystem è atomico. Un crawler non vedrà un file metà vecchio e metà nuovo.
Note: se distribuisci su più nodi, sincronizza prima su staging, poi fai il cutover. Evita copie dirette nodo per nodo senza check comune.
6. Esegui il rollback quando la verifica finale fallisce
Qui entra la parte che molti saltano. Se la validazione mostra un errore, il ripristino deve essere automatico. Non deve dipendere dal tempo o dalla memoria dell’operatore.
rollback() {
local backup_dir="$1"
cp "$backup_dir/sitemap.xml" /var/www/site/public/sitemap.xml
cp "$backup_dir/robots.txt" /var/www/site/public/robots.txt
cp "$backup_dir/redirects.conf" /var/www/site/config/redirects.conf
}
if ! curl -fsS https://www.example.com/sitemap.xml > /dev/null; then
echo "Verifica post-publish fallita, avvio rollback" >&2
rollback "$BACKUP_DIR"
exit 1
fi
# Output: i file tornano alla versione precedente se il controllo finale fallisce.
Perché serve: un errore dopo la pubblicazione è il caso peggiore. Hai già esposto il problema ai crawler. La correzione rapida riduce il tempo di esposizione del bug.
Verifica finale
Dopo il deploy, esegui sempre la stessa sequenza. Non improvvisare.
- Controlla che la sitemap sia raggiungibile con curl -fsS.
- Controlla che il file non sia vuoto e contenga le URL attese.
- Verifica che i redirect non abbiano introdotto catene nuove.
- Controlla i log del web server e del CDN per errori 4xx o 5xx.
- Valuta se la versione pubblicata corrisponde al backup appena creato.
curl -fsS https://www.example.com/sitemap.xml | head -n 5
curl -fsS -I https://www.example.com/old-url
grep -E 'sitemap|canonical|redirect' /var/log/deploy-seo.log | tail -n 20
# Output: header validi, redirect atteso, log finale leggibile e senza errori.
Se il tuo sito usa Search Console o strumenti equivalenti, aggiungi una notifica post-deploy. Un ping alla sitemap o un webhook interno riduce il tempo di diagnosi quando qualcosa va storto.
Troubleshooting
Errore 1: curl: (22) The requested URL returned error: 404
Causa: la sitemap è stata pubblicata nel percorso sbagliato o il rewrite del server punta a un file inesistente.
Fix:
ls -l /var/www/site/public/sitemap.xml
cp "$BACKUP_DIR/sitemap.xml" /var/www/site/public/sitemap.xml
# Output: il file torna disponibile e il 404 sparisce.
Errore 2: cp: cannot stat '/tmp/sitemap.xml': No such file or directory
Causa: lo step di generazione non ha prodotto il file, ma il flusso è andato avanti comunque.
Fix:
node scripts/build-sitemap.mjs || exit 1
test -s /tmp/sitemap.xml || exit 1
# Output: lo script si ferma prima della fase di pubblicazione.
Errore 3: grep: invalid option -- 'q'
Causa: variabile o input malformato ha trasformato il pattern in opzione, spesso per quoting sbagliato.
Fix:
grep -q -- '<urlset' "$tmpfile"
# Output: il pattern viene trattato come testo, non come opzione.
Warning: i tre errori sopra sembrano banali, ma in automazione ripetitiva sono quelli che generano rollback falsi o mancati.
Conclusione
Un’automazione SEO utile non è quella che pubblica veloce. È quella che sa fermarsi, diagnosticare e tornare indietro senza lasciare artefatti rotti.
Il prossimo passo concreto è trasformare questi controlli in uno script invocato da CI, con log strutturati e un canale di alert dedicato quando il rollback parte.
Se vuoi andare oltre, aggiungi una prova di ripristino programmata. Un rollback testato in anticipo vale più di dieci deploy “andati bene” per caso.
Commenti (0)
Nessun commento ancora.
Segnala contenuto
Elimina commento
Eliminare definitivamente questo commento?
L'azione non si può annullare.