Documentazione · Guida all'integrazione

Migrazione da Staging a Live

Questo documento spiega come migrare la configurazione del plugin ADP Car Market Hub da un sito di staging WordPress a un sito di produzione (live). Copre quali impostazioni devono essere aggiornate, quali dati transienti devono essere cancellati, come riconfigurare gli importi pianificati e i cron job, e come convalidare il sito live prima di abilitare gli importi automatici.

Quando utilizzare questo documento

Utilizzare questo documento se si sta:

Promuovendo per la prima volta un ambiente di staging completamente configurato e testato sul dominio di produzione.
Copiando un database di produzione in staging e si ha la necessità di sapere cosa modificare su staging affinché non interferisca con il sito live.
Eseguendo una migrazione del server o un cambio di dominio su un sito che ha già il plugin in esecuzione in produzione.
Coordinando la promozione di modifiche di configurazione (design, impostazioni, sovrascritture di mappatura) che sono state sviluppate in staging.

Il pubblico di riferimento è un amministratore WordPress o uno sviluppatore di agenzia che comprende come i database e i file system WordPress vengono spostati tra gli ambienti. È utile una conoscenza pratica di wp-config.php e di SSH o di un pannello di controllo dell'hosting.

Panoramica

Il plugin memorizza tutta la sua configurazione come opzioni WordPress nel database (tabella wp_options) e memorizza i post dei veicoli importati, i lead, gli eventi di analytics e le iscrizioni agli avvisi di ricerca in tabelle e post type separati. Quando un database viene spostato tra gli ambienti — ad esempio, copiando il database di staging in produzione — tutti questi dati si spostano con esso.

Un database copiato conserva valori che sono corretti per l'ambiente di origine ma errati o non sicuri per l'ambiente di destinazione. Gli esempi più importanti sono:

Credenziali API (Base URL, Seller IDs, Client ID, Client Secret). In staging potresti utilizzare un ambiente API sandbox o credenziali di test a sicurezza inferiore. Il sito live necessita delle credenziali di produzione effettive del concessionario.
Il token cron. Il token che autentica l'endpoint REST cron del plugin è specifico dell'ambiente. L'uso del token di staging sul sito live, o viceversa, significa che il cron job del server sta chiamando l'URL errato o utilizzando il segreto errato.
URL di destinazione dei webhook. I webhook di staging spesso puntano a ricevitori di test. I webhook live devono puntare al CRM di produzione o all'endpoint di notifica.
L'URL del sito WordPress. WordPress memorizza il proprio URL nelle opzioni siteurl e home. Questi devono corrispondere al dominio live affinché gli URL degli endpoint REST del plugin e qualsiasi altro URL assoluto vengano risolti correttamente.
Dati di cache transienti. I token di accesso OAuth memorizzati nella cache, i blocchi di esecuzione dell'importazione e la coda delle immagini contengono uno stato di staging che è privo di significato o dannoso sul sito live.
Eventi cron pianificati. Gli eventi WP-Cron che sono stati pianificati in staging portano timestamp relativi allo staging e devono essere ripianificati sul sito live.

Ognuno di questi aspetti viene affrontato passo dopo passo di seguito.

Requisiti preliminari

Prima di iniziare la migrazione:

Esiste un backup corrente e ripristinabile sia del database di staging che del database di produzione. Non migrare mai senza un backup dello stato corrente di ciascun sito.
L'installazione di WordPress in produzione soddisfa i requisiti del plugin. Vedere Technical System Requirements.
Si ha accesso al file wp-config.php del server di produzione e al servizio cron del server se viene utilizzato il cron del server.
Si conoscono le credenziali API di produzione (API Base URL, Seller IDs, Client ID, Client Secret) e sono state ricevute tramite un canale sicuro. Vedere External API Credentials.
Se il sito di produzione utilizza un dominio diverso rispetto allo staging, il cambio di dominio è pronto per essere applicato alle opzioni URL di WordPress contemporaneamente alla copia del database.

Istruzioni passo dopo passo

Esegui questi passaggi in ordine. I passaggi da 1 a 5 rappresentano la preparazione sull'ambiente di staging prima che il database venga copiato. I passaggi dal 6 in poi si applicano al sito di produzione dopo che il database o il plugin sono stati installati.

Passaggio 1 — Disabilitare gli importi automatici su staging prima della migrazione

Se sul sito di staging sono abilitati gli importi automatici, disabilitarli prima di copiare il database. Ciò evita una situazione in cui entrambi gli ambienti condividono lo stesso stato di pianificazione e tentano entrambi di eseguire gli importi contemporaneamente.

Sul sito di staging, apri Car Market Hub → Import & Limits.
Disabilita l'opzione Automatic import e salva.
Se un cron job del server punta all'endpoint REST del sito di staging, disabilita o rimuovi anche quel cron job.

Passaggio 2 — Eseguire i backup

Prima di apportare modifiche a uno dei due siti:

Esegui un backup del database del sito di staging.
Esegui un backup del database del sito di produzione.
Se il sito di produzione contiene già dati di veicoli importati e immagini caricate, esegui anche un backup completo del file system di wp-content/uploads/.

Passaggio 3 — Copiare il database

Copia il database di staging sul server di produzione utilizzando il metodo preferito (esportazione/importazione dal pannello di controllo dell'hosting, WP-CLI db export / db import, SSH + mysqldump, o un plugin come Duplicator o All-in-One WP Migration). La procedura esatta dipende dal tuo ambiente di hosting.

Se i domini differiscono tra staging e produzione, esegui un comando di ricerca e sostituzione per aggiornare tutte le occorrenze dell'URL di staging con l'URL di produzione. Utilizzando WP-CLI:

wp search-replace 'https://staging.example.com' 'https://www.example.com' --all-tables

Esegui questo comando sul database di produzione, non su quello di staging. Esegui un backup prima di avviarlo.

Passaggio 4 — Copiare i file del plugin

I file del plugin si trovano in wp-content/plugins/adp-car-market-hub/. Se i siti di staging e produzione eseguono la stessa versione del plugin, questo passaggio può essere saltato. Se le versioni differiscono, copia la directory del plugin da staging a produzione (oppure aggiorna alla stessa versione tramite l'amministrazione di WordPress su entrambi i siti prima di migrare).

Non copiare wp-config.php da staging a produzione. I due file wp-config.php contengono credenziali del database e costanti specifiche dell'ambiente diverse, e devono rimanere indipendenti.

Passaggio 5 — Copiare i template override se applicabile

Se il tema sul sito di staging contiene file di template override per il plugin (ad esempio single-as24ci_car.php o archive-as24ci_car.php nella root del tema), copia questi file nella stessa posizione all'interno del tema di produzione. Vedi la Guida ai template override per i dettagli sui template override.

Se nel tema non sono presenti template override, salta questo passaggio.

Passaggio 6 — Aggiornare le credenziali API di produzione

Dopo la copia del database, la tabella wp_options di produzione contiene ancora le credenziali che erano state salvate su staging. Sostituiscile con le credenziali di produzione.

Sul sito di produzione, apri Car Market Hub → Settings.
Nella scheda API Connection & General Settings, inserisci i valori di produzione per: - API Base URL — l'URL HTTPS dell'ambiente AutoScout24 di produzione. - Seller ID — il Seller ID (o i Seller ID) di produzione del concessionario. Più ID sono separati da virgole. - Client ID — l'identificativo client OAuth di produzione. - Client Secret — il client secret OAuth di produzione. Il campo Client Secret non viene precompilato all'apertura della pagina delle impostazioni; è necessario reinserire sempre il valore quando lo si modifica.
Salva le impostazioni.
Cancella il token di accesso OAuth memorizzato nella cache, se ne esiste uno proveniente dalla sessione di staging. Il token è memorizzato come transient di WordPress denominato as24ci_access_token. È possibile cancellarlo da Car Market Hub → Tools (cerca l'azione Clear token cache), oppure eseguendo: ``wp transient delete as24ci_access_token``
Esegui il Test di connessione su Car Market Hub → Tools. Non procedere finché il test non va a buon fine. Vedi Test di connessione.

Passaggio 7 — Aggiornare gli URL dei webhook

Se sono configurati dei webhook, la configurazione di staging potrebbe puntare a un ricevitore di test:

Apri Car Market Hub → Leads e individua la sezione Webhooks.
Aggiorna il New lead webhook URL e il New import webhook URL con gli endpoint del ricevitore di produzione, oppure cancellali se i webhook non vengono utilizzati in produzione.
Aggiorna il Webhook secret se il ricevitore di produzione utilizza un valore di secret differente. Vedi Webhook Integration.

Passaggio 8 — Confermare la configurazione dell'AI gestita

Se l'AI Assistant è abilitato:

Conferma con AD Promotion che la configurazione gestita di Google Gemini in AS24CI\Ai_Config sia predisposta per l'ambiente di produzione. Il cliente non inserisce un fornitore di intelligenza artificiale, un modello o una chiave API nel backend di WordPress, e nessuna chiave AI viene migrata tramite la copia del database.
Visita Car Market Hub → AI Assistant e conferma che la funzionalità risulti configurata.

Passaggio 9 — Cancellare i dati transient obsoleti

Il database migrato potrebbe contenere valori transient dell'ambiente di staging che non devono essere trasferiti in produzione:

Cancella il blocco dell'esecuzione dell'importazione (import run-lock), se impostato. Ciò impedisce al sito di produzione di rilevare uno stato obsoleto di "importazione già in corso" derivante da un'esecuzione di staging: ``wp transient delete as24ci_cron_import_running``
Cancella il blocco del worker della coda immagini, se impostato: ``wp transient delete as24ci_image_queue_running``
Facoltativamente, cancella la coda delle immagini stessa se la coda delle immagini di staging contiene processi di immagini dell'ambiente di staging. La coda delle immagini è memorizzata come opzione di WordPress (as24ci_image_queue) anziché come transient. Puoi cancellarla da Car Market Hub → System & Help → Clear image queue, o dalla riga di comando: ``wp option delete as24ci_image_queue wp option delete as24ci_image_queue_last_run``
Rimuovi qualsiasi altro elenco di modelli AI memorizzato nella cache da precedenti chiamate API di staging. Questi sono memorizzati come transient con il prefisso as24ci_. Su WP-CLI puoi ispezionarli con wp transient list --search="as24ci_".

Passaggio 10 — Rigenerare il token cron

Il token cron proveniente dallo staging non deve essere utilizzato in produzione. Un token diverso impedisce ai cron job di staging di attivare accidentalmente le importazioni di produzione.

Sul sito di produzione, apri Car Market Hub → Import & Limits.
Nella scheda Automation, fai clic su Regenerate Token. Il plugin genera un nuovo token casuale di 32 caratteri e lo salva.
Prendi nota del nuovo token; ti servirà al passaggio 11.

Se utilizzi l'endpoint REST con il token nell'URL, il nuovo URL di attivazione viene mostrato nella stessa scheda. Il vecchio URL restituirà un errore 403 dopo la rigenerazione.

Passaggio 11 — Riconfigurare la configurazione cron di produzione

Dopo la rigenerazione del token, qualsiasi cron job del server che puntava all'URL di staging non è più valido. Riconfigura la configurazione cron di produzione:

Se utilizzi la modalità cron del server, aggiorna i cron job del server con il nuovo URL di attivazione di produzione. Vedi Server Cron Setup per il formato esatto del comando.
Se utilizzi la modalità WP-Cron, conferma che la costante DISABLE_WP_CRON in wp-config.php sia impostata in modo appropriato: - Se il sito di produzione utilizza il cron del server, aggiungi o conferma define( 'DISABLE_WP_CRON', true ); in wp-config.php. - Se il sito di produzione si affida a WP-Cron, rimuovi o commenta DISABLE_WP_CRON da wp-config.php se era stato impostato per lo staging.
Riabilita gli importi automatici su Car Market Hub → Import & Limits una volta convalidate tutte le credenziali e la configurazione cron.

Passaggio 12 — Verificare le pagine predefinite

Quando il plugin viene attivato per la prima volta, crea due pagine di WordPress (archivio auto/veicoli e Confronta auto) e memorizza i loro ID post nelle opzioni as24ci_page_archive_id e as24ci_page_compare_id. Se il database di produzione era precedentemente vuoto, gli ID delle pagine migrate sono quelli creati su staging e si riferiscono ai post di staging. Dopo la copia del database, queste pagine esistono sul sito di produzione, ma i loro slug e contenuti dovrebbero essere verificati.

In WordPress → Pagine, conferma che la pagina dell'archivio veicoli (slug predefinito: cars) e la pagina Confronta auto esistano e siano pubblicate.
Visita entrambe le pagine sul front-end e conferma che vengano visualizzate correttamente.
Se le pagine mancano o i loro ID puntano a post eliminati, disattiva e riattiva il plugin per ricrearle (conferma che Create default pages sia abilitato in Car Market Hub → Settings prima della riattivazione).

Verifica questo comportamento nella versione corrente del plugin prima di fare affidamento su di esso, poiché il comportamento di creazione delle pagine può variare.

Passaggio 13 — Svuotare le regole dei permalink

Dopo qualsiasi modifica del dominio o aggiornamento dell'URL di WordPress, svuota le regole dei permalink di WordPress in modo che l'URL dell'archivio veicoli e gli URL delle pagine di dettaglio dei veicoli vengano risolti correttamente:

In WordPress, apri Impostazioni → Permalink.
Senza modificare nulla, fai clic su Salva le modifiche. Questo rigenera le regole di riscrittura di .htaccess.
Visita la pagina dell'archivio veicoli e la pagina di un singolo veicolo per confermare che si carichino senza errori 404.

Passaggio 14 — Convalidare il sito di produzione

Esegui i seguenti controlli di convalida dopo la migrazione:

Test di connessione. Apri Car Market Hub → Tools ed esegui il Test di connessione. Conferma che abbia successo con le API di produzione. Vedi Test di connessione.
Scheda System & Help. Apri Car Market Hub → System & Help e controlla tutti gli indicatori diagnostici. Risolvi eventuali badge rossi o arancioni.
Importazione manuale. Attiva un'importazione manuale da Car Market Hub → Import & Limits → Run now. Conferma che l'importazione venga completata senza errori.
Pagina dell'archivio veicoli. Visita l'URL dell'archivio veicoli e conferma che i veicoli importati appaiano con immagini, prezzi e diciture corretti.
Pagina del singolo veicolo. Fai clic sulla pagina di dettaglio di un veicolo e conferma che il layout completo dei dettagli, la galleria e il modulo di contatto siano funzionanti.
Prima importazione pianificata. Dopo aver abilitato la pianificazione automatica, attendi la prima esecuzione attivata dal cron e conferma che la scheda System & Help mostri un timestamp recente per Last import run.
Log. Apri Car Market Hub → Logs e conferma che non vi siano errori di autenticazione, errori API o altri errori imprevisti derivanti dalla prima esecuzione in produzione.

Riferimento di configurazione

I seguenti gruppi di opzioni del plugin sono rilevanti durante la migrazione tra ambienti. Tutti sono memorizzati come opzioni di WordPress.

Gruppo di opzioni	Esempi di chiavi	Azione sul sito live dopo la migrazione
Credenziali API	`as24ci_base_url`, `as24ci_seller_ids`, `as24ci_client_id`, `as24ci_client_secret`	Sostituisci con i valori di produzione.
Token cron	`as24ci_cron_token`	Rigenera sul sito live. Aggiorna i cron job del server.
Configurazione AI gestita	`AS24CI\Ai_Config::MANAGED_GEMINI_API_KEY`, `MANAGED_GEMINI_MODEL` (costanti PHP, non opzioni)	Conferma con AD Promotion che la configurazione gestita di Gemini sia predisposta per l'ambiente di produzione. Non migrata tramite copia del database.
URL dei webhook	`as24ci_webhook_url_new_lead`, `as24ci_webhook_url_new_import`, `as24ci_webhook_secret`	Aggiorna con gli URL del ricevitore di produzione e il secret.
Pagine del plugin	`as24ci_page_archive_id`, `as24ci_page_compare_id`	Verifica che le pagine di riferimento esistano e siano pubblicate.
Pianificatore	`as24ci_auto_import_enabled`, `as24ci_cron_mode`, `as24ci_cron_schedule`	Conferma che la pianificazione sia configurata per la produzione. Disabilita su staging prima della migrazione.
Cache transient	`as24ci_access_token` (transient), `as24ci_cron_import_running` (transient), `as24ci_image_queue_running` (transient)	Elimina i transient obsoleti dopo la migrazione.
Coda immagini	`as24ci_image_queue`, `as24ci_image_queue_last_run`	Cancella se la coda contiene dati di staging.

Note operative

Un solo ambiente attivo alla volta. Dopo aver promosso lo staging a live, disabilita gli importi automatici e qualsiasi cron job del server sul sito di staging. Avere entrambi gli ambienti collegati alle stesse credenziali API di produzione ed eseguire le importazioni contemporaneamente può causare risultati imprevedibili. Utilizza credenziali API separate per ciascun ambiente, ove possibile.
Lo staging deve utilizzare le proprie credenziali. Dopo che il database è stato copiato sullo staging, sostituisci le credenziali API su staging con i valori dell'ambiente sandbox o di staging. Non lasciare le credenziali di produzione su un sito di staging. Vedi External API Credentials.
Attenzione alla Sincronizzazione Completa (Full Sync). L'opzione Full Sync elimina i post dei veicoli locali che non sono più presenti nella risposta dell'API. Non abilitare il Full Sync sul sito live finché non è stato osservato e confermato come corretto almeno un ciclo di importazione completo. Abilitarlo prima della prima importazione pulita può causare eliminazioni premature.
Dati di analytics e lead. La migrazione copia tutti gli eventi di analytics e i post dei lead da staging a produzione. Si tratta di record sintetici o di test e potrebbero distorcere i report. A seconda dei requisiti del concessionario, potresti voler rimuovere gli analytics generati in staging dal database di produzione prima di abilitare il traffico reale. I dati di analytics sono memorizzati nella tabella del database {prefix}as24ci_analytics. Verifica prima di eliminare.
Iscrizioni agli avvisi di ricerca. Le iscrizioni agli avvisi di ricerca del plugin (nome del visitatore, email, criteri di ricerca) sono memorizzate nella tabella {prefix}as24ci_search_agents. Le iscrizioni di test dello staging devono essere rimosse dal database di produzione. Si tratta di record di dati personali e non devono essere conservati senza uno scopo legittimo.
Struttura dei permalink. L'URL dell'archivio veicoli (slug predefinito cars) e gli URL dei singoli veicoli (/cars/{slug}/) dipendono dall'abilitazione dei permalink personalizzati. Conferma dopo la migrazione che Impostazioni → Permalink non sia impostato sulla modalità semplice (query-string).
wp-config.php non viene migrato. Mantieni i file wp-config.php indipendenti tra gli ambienti. Le credenziali del database, DISABLE_WP_CRON, WP_DEBUG e altre costanti di ambiente devono riflettere la configurazione dell'ambiente di destinazione.
Directory dei log. Il plugin scrive i log di importazione e di errore in wp-content/uploads/as24ci-logs/. I file di log dello staging si troveranno in quella directory dopo una migrazione completa del file system. I dati di log non sono dannosi in produzione ma potrebbero creare confusione. Puoi ruotare o archiviare i file di log dello staging prima di abilitare le importazioni di produzione se preferisci uno stato iniziale pulito.
Invalidazione della cache. Dopo un cambio di dominio e la migrazione del database, svuota tutte le cache degli oggetti WordPress, le cache delle pagine, le cache CDN e le cache opcode PHP in modo che i nuovi URL e le opzioni aggiornate del plugin vengano serviti in modo coerente.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa controllare
Il Test di connessione fallisce in produzione ma è passato in staging.	Le credenziali di produzione non sono state aggiornate dopo la copia del database, oppure viene ancora utilizzato un token di staging memorizzato nella cache.	Reinserisci le credenziali API di produzione e cancella il transient del token di accesso (`as24ci_access_token`). Esegui nuovamente il Test di connessione.
Il cron del server restituisce 403 "Invalid or missing token" dopo la migrazione.	Il token cron è stato rigenerato nel passaggio 10 ma il cron job del server utilizza ancora il vecchio URL di staging.	Copia il nuovo URL di attivazione dalla scheda Automazione e aggiorna il cron job del server.
L'archivio veicoli o le pagine dei singoli veicoli restituiscono 404 dopo il cambio di dominio.	Le regole dei permalink non sono state aggiornate dal cambio di URL.	Apri Impostazioni → Permalink e fai clic su Salva le modifiche.
Sia lo staging che la produzione stanno importando contemporaneamente.	Le importazioni automatiche non sono state disabilitate sullo staging prima della migrazione.	Disabilita immediatamente le importazioni automatiche e qualsiasi cron job del server sul sito di staging.
Le immagini dei veicoli importati mancano sul sito live.	I file immagine in `wp-content/uploads/` non sono stati copiati dallo staging alla produzione (è stato spostato solo il database).	Copia la directory `wp-content/uploads/` dallo staging alla produzione, oppure avvia una nuova importazione sul sito live con l'opzione Importa immagini abilitata.
Le email di notifica dei lead vengono recapitate all'indirizzo del destinatario di staging.	L'opzione dell'email del destinatario dei lead è stata copiata dallo staging e non è stata aggiornata.	Apri le impostazioni di Car Market Hub → Leads e aggiorna l'email del destinatario con l'indirizzo di produzione.
I dati di analytics mostrano numeri gonfiati a causa dell'attività di test in staging.	Gli eventi di analytics dello staging sono stati copiati nel database di produzione.	Rimuovi le righe generate dai test dalla tabella `{prefix}as24ci_analytics`, oppure annota la data di migrazione e filtra i report di conseguenza.
La scheda Sistema & Aiuto mostra un timestamp "Ultima esecuzione cron esterna" non aggiornato.	Il cron job è in esecuzione ma utilizza l'URL errato (URL di staging) o il token errato.	Aggiorna l'URL e il token del cron job in modo che corrispondano ai valori della scheda Automazione di produzione.
Le importazioni si avviano ma terminano immediatamente con "Importazione già in corso".	Un transient di blocco dell'esecuzione obsoleto è stato copiato dallo staging.	Elimina il transient `as24ci_cron_import_running` e riprova.