Configurazione di Vault per il Self-Hosting

Switchbord memorizza i segreti per singolo workspace in Supabase Vault — un’estensione Postgres che cifra i segreti a livello di database. Questa pagina copre ciò che chi effettua il self-hosting deve sapere per far funzionare correttamente il vault, specialmente quando si gestiscono più workspace.

Panoramica: Due Modalità di Risoluzione dei Segreti

Switchbord supporta due approcci per fornire segreti a runtime come il token di accesso Meta: Modalità Vault (predefinita, consigliata) I segreti sono memorizzati per singolo workspace in vault.secrets, collegati a ciascun workspace tramite app_private.workspace_secret_bindings. Il worker li legge a runtime usando funzioni RPC di Supabase. Questo è l’approccio corretto per qualsiasi deployment con più di un workspace. Fallback su variabile d’ambiente (solo workspace singolo) Se SELF_HOSTED=true è impostato e una lettura del vault fallisce, il worker ricorre a WHATSAPP_META_ACCESS_TOKEN dall’ambiente. Questa è una comodità per gli operatori che gestiscono un singolo workspace e vogliono saltare del tutto la configurazione del vault.

SELF_HOSTED=true bypassa le ricerche nel vault e fornisce una credenziale condivisa a tutti i workspace. Se il tuo deployment ha più di un workspace, questo causerà l’invio dei messaggi del workspace A usando il token del workspace B. Non usare il fallback su variabile d’ambiente in deployment multi-workspace.

Perché i Deployment Multi-Tenant Devono Usare Vault

Quando il worker elabora un messaggio in uscita, risolve il token di accesso Meta cercando il workspace che possiede la conversazione. In modalità vault, chiama sb_read_workspace_secret(workspace_id, 'meta-access-token') — una ricerca delimitata che restituisce solo il segreto appartenente a quel workspace. Con SELF_HOSTED=true, la ricerca viene saltata del tutto e il valore della variabile d’ambiente viene restituito indipendentemente da quale workspace stia effettuando la richiesta. Non c’è alcun isolamento per singolo workspace. Un secondo workspace aggiunto successivamente utilizzerà silenziosamente il token del primo workspace, il che fallirà oppure — peggio — avrà successo con l’account sbagliato.

Se hai inizialmente effettuato il deployment con SELF_HOSTED=true per un singolo workspace e ora stai aggiungendo un secondo workspace, devi rimuovere quel flag, configurare i segreti del vault per entrambi i workspace e riavviare il worker prima che il secondo workspace funzioni correttamente.

Come i Segreti Fluiscono Attraverso il Sistema

L'operatore salva una credenziale in Settings

L’operatore apre Settings → Provider e inserisce un token di accesso Meta (o una API key per un provider AI). L’app web Switchbord lo invia a /api/settings/secrets.

L'API memorizza il segreto in Supabase Vault

La route API chiama storeWorkspaceSecret(workspaceId, secretKind, value), che chiama vault.create_secret() e inserisce una riga in app_private.workspace_secret_bindings che mappa l’ID workspace e il tipo di segreto all’ID del segreto nel vault.

Il worker legge il segreto al momento dell'invio

Quando il worker è sul punto di inviare un messaggio, chiama la funzione RPC di Supabase sb_read_workspace_secret con l’ID workspace e il tipo di segreto. La funzione viene eseguita con privilegi SECURITY DEFINER, legge da vault.secrets e restituisce il valore decifrato. Non è richiesta alcuna connessione diretta al database dal worker.

Il worker non memorizza mai in cache i segreti tra le richieste. Ogni operazione di invio innesca una nuova lettura del vault, quindi la rotazione di un segreto in Settings ha effetto immediato.

Requisiti di Configurazione Supabase

Estensione Vault

Supabase Vault è abilitata per impostazione predefinita su tutti i progetti Supabase Cloud. Se stai eseguendo un’istanza Supabase self-hosted, conferma che l’estensione sia abilitata:

-- Run in your Supabase SQL editor
SELECT * FROM pg_extension WHERE extname = 'supabase_vault';

Se la query non restituisce righe, abilitala:

CREATE EXTENSION IF NOT EXISTS supabase_vault SCHEMA vault;

Le migrazioni di Switchbord creano automaticamente anche lo schema app_private e la tabella workspace_secret_bindings quando esegui supabase db push o applichi le migrazioni. Non è necessario crearle manualmente.

Funzioni RPC

Il worker usa due funzioni wrapper RPC pubbliche che devono essere presenti nel tuo database:

sb_read_workspace_secret(p_workspace_id uuid, p_kind text) — restituisce il valore decifrato del segreto per un workspace e un tipo di segreto
sb_resolve_workspace_by_verify_token(p_verify_token text) — restituisce l’ID workspace corrispondente a un dato verify token Meta

Queste funzioni sono create dalle migrazioni di Switchbord. Se incontri errori function does not exist, ri-esegui le tue migrazioni sul database target:

supabase db push --db-url "$SUPABASE_DB_URL"

Memorizzazione dei Segreti

Ci sono due modi per popolare i segreti del vault per un workspace: Interfaccia Settings (consigliata) Apri Settings → Provider nell’app web Switchbord e inserisci le credenziali direttamente. L’interfaccia chiama automaticamente l’API di scrittura del vault. Non è richiesto alcun accesso diretto al database. Editor SQL della Dashboard Supabase Per la configurazione iniziale o il caricamento massivo, puoi inserire i segreti direttamente:

-- Insert a secret and get back its vault ID
SELECT vault.create_secret(
  'your-token-value-here',
  'meta-access-token for workspace abc123',
  null
) AS vault_secret_id;

-- Then bind it to a workspace
INSERT INTO app_private.workspace_secret_bindings
  (workspace_id, secret_kind, vault_secret_id)
VALUES
  ('your-workspace-uuid', 'meta-access-token', 'the-vault-secret-id-from-above');

Non inserire segreti in chiaro in nessuna tabella di schema pubblico. Usa sempre vault.create_secret() così il valore viene cifrato prima della memorizzazione.

Variabili d’Ambiente del Worker

Il worker necessita solo di una chiave service role di Supabase per leggere dal vault. Non è richiesta alcuna connessione diretta al database per le letture. Obbligatorie:

Variabile	Descrizione
`NEXT_PUBLIC_SUPABASE_URL`	L’URL del tuo progetto Supabase, es. `https://xxxx.supabase.co`
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Chiave anon di Supabase
`SUPABASE_SECRET_KEY`	Chiave service role di Supabase — usata per le letture del vault tramite RPC
`WHATSAPP_PLATFORM_DATA_MODE`	Impostare su `supabase`
`WORKER_POLL_INTERVAL_MS`	Intervallo di polling in millisecondi, es. `5000`

Opzionali:

Variabile	Descrizione
`SUPABASE_DB_URL`	Stringa di connessione Postgres diretta. Necessaria solo se stai usando scritture del vault direttamente dal worker (non tipico — l’app web gestisce le scritture).
`SELF_HOSTED=true`	Abilita il fallback su variabile d’ambiente per deployment a workspace singolo. Non impostare questa variabile se hai più di un workspace.
`WHATSAPP_META_ACCESS_TOKEN`	Richiesta solo quando `SELF_HOSTED=true` è impostato. Il token di accesso Meta di fallback.

Se effettui il deployment su Railway, imposta queste come variabili di servizio nel pannello dell’ambiente del tuo servizio worker. Il worker le recepirà al prossimo deploy senza alcuna modifica al codice.

Riferimento dei Tipi di Segreto

Tipo di Segreto	Scopo
`meta-access-token`	Token di accesso Meta (WhatsApp Business API) per l’invio dei messaggi
`webhook-signing-secret`	Segreto di firma del payload dei webhook Meta per la verifica delle richieste
`meta-verify-token`	Token di verifica del webhook Meta
`openai-api-key`	API key OpenAI per la generazione di bozze AI
`anthropic-api-key`	API key Anthropic per la generazione AI basata su Claude
`openrouter-api-key`	API key OpenRouter per il routing AI multi-modello

Risoluzione dei Problemi

`vault_unavailable`

L’estensione vault non è abilitata oppure lo schema app_private è assente.

Conferma che l’estensione vault esista (vedi il controllo SQL sopra)
Ri-esegui le migrazioni di Switchbord: supabase db push
Conferma che SUPABASE_SECRET_KEY del worker sia una chiave service role valida, non la chiave anon

`vault_read_error`

La funzione RPC esiste ma ha restituito un errore durante il tentativo di leggere un segreto.

Controlla che sb_read_workspace_secret sia stata creata con successo dalle tue migrazioni
Conferma che SUPABASE_SECRET_KEY abbia i permessi service role (la chiave anon non può chiamare funzioni SECURITY DEFINER che verificano service_role)
Nell’editor SQL di Supabase, verifica che la funzione esista: \df sb_read_workspace_secret

`vault_secret_missing`

La funzione è stata eseguita con successo ma non ha trovato alcun binding per il workspace e il tipo di segreto richiesti. Il segreto non è mai stato memorizzato.

Apri Settings → Provider per il workspace interessato e salva la credenziale mancante
Oppure inserisci il binding manualmente usando l’SQL sopra
Verifica che l’ID workspace in app_private.workspace_secret_bindings corrisponda al workspace che effettua la richiesta

Il worker invia messaggi con l’account sbagliato

Questo è un sintomo di SELF_HOSTED=true impostato in un deployment multi-workspace. Viene usata la credenziale di fallback della variabile d’ambiente invece dei segreti del vault per singolo workspace. Rimuovi SELF_HOSTED=true dall’ambiente del worker e assicurati che tutti i workspace abbiano i propri segreti configurati nel vault.

Guide Correlate

Vault Architecture — dettagli interni, design dello schema e specifiche di cifratura
Secrets and Encryption — policy di sicurezza e controlli di accesso
Meta Credential Setup — come ottenere le credenziali che memorizzerai nel vault
Webhooks — configurazione del token di verifica del webhook Meta

Per iniziare

Funzionalità

WhatsApp

Guide

Contribuire

Piattaforma

Operazioni

Sicurezza e Conformità

Configurazione di Vault per il Self-Hosting

Configurazione di Vault per il Self-Hosting

Panoramica: Due Modalità di Risoluzione dei Segreti

Perché i Deployment Multi-Tenant Devono Usare Vault

Come i Segreti Fluiscono Attraverso il Sistema

Requisiti di Configurazione Supabase

Estensione Vault

Funzioni RPC

Memorizzazione dei Segreti

Variabili d’Ambiente del Worker

Riferimento dei Tipi di Segreto

Risoluzione dei Problemi

`vault_unavailable`

`vault_read_error`

`vault_secret_missing`

Il worker invia messaggi con l’account sbagliato

Guide Correlate

​Configurazione di Vault per il Self-Hosting

​Panoramica: Due Modalità di Risoluzione dei Segreti

​Perché i Deployment Multi-Tenant Devono Usare Vault

​Come i Segreti Fluiscono Attraverso il Sistema

​Requisiti di Configurazione Supabase

​Estensione Vault

​Funzioni RPC

​Memorizzazione dei Segreti

​Variabili d’Ambiente del Worker

​Riferimento dei Tipi di Segreto

​Risoluzione dei Problemi

​vault_unavailable

​vault_read_error

​vault_secret_missing

​Il worker invia messaggi con l’account sbagliato

​Guide Correlate

Configurazione di Vault per il Self-Hosting

Panoramica: Due Modalità di Risoluzione dei Segreti

Perché i Deployment Multi-Tenant Devono Usare Vault

Come i Segreti Fluiscono Attraverso il Sistema

Requisiti di Configurazione Supabase

Estensione Vault

Funzioni RPC

Memorizzazione dei Segreti

Variabili d’Ambiente del Worker

Riferimento dei Tipi di Segreto

Risoluzione dei Problemi

`vault_unavailable`

`vault_read_error`

`vault_secret_missing`

Il worker invia messaggi con l’account sbagliato

Guide Correlate