Storage personalizzato

Capgo supporta soluzioni di storage personalizzate per i bundle della tua app, permettendoti di ospitare gli update sulla tua infrastruttura o su servizi di storage di terze parti. È l'ideale per le aziende con requisiti di sicurezza specifici, necessità di compliance o infrastrutture di storage già esistenti.

Panoramica

Lo storage personalizzato in Capgo funziona caricando il bundle su una location esterna e fornendo a Capgo l'URL per accedervi. Il Capgo SDK scaricherà quindi gli update direttamente dal tuo storage personalizzato invece che dal cloud storage predefinito di Capgo.

Tip

Lo storage personalizzato è ideale per:

• Organizzazioni con requisiti rigorosi di data residency
• Team con infrastrutture CDN o di storage esistenti
• Applicazioni che richiedono ulteriori livelli di sicurezza
• Ottimizzazione dei costi per bundle di grandi dimensioni

Upload tramite URL esterno

Il modo più semplice per usare uno storage personalizzato è caricare il bundle su qualsiasi URL accessibile pubblicamente e fornire quell'URL a Capgo.

Upload base tramite URL esterno

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip

Questo comando indica a Capgo di fare riferimento al bundle all'URL specificato invece di caricarlo sullo storage cloud di Capgo.

Con crittografia

Per uno storage esterno sicuro, puoi crittografare il tuo bundle e fornire le chiavi di decrittazione:

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip --iv-session-key YOUR_IV_SESSION_KEY

Integrazione S3

Capgo offre il supporto nativo per Amazon S3 e servizi di storage compatibili con S3. Il CLI può caricare automaticamente il tuo bundle su S3 e configurare Capgo per utilizzare l'URL S3.

Opzioni di upload S3

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-bucket-name your-bucket-name

Configurazione S3 completa

Per servizi compatibili con S3 o endpoint personalizzati:

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-endpoint https://s3.your-provider.com \
  --s3-bucket-name your-bucket-name \
  --s3-port 443 \
  --no-s3-ssl  # Only if your endpoint doesn't support SSL

Parametri di configurazione S3

Parametro	Descrizione	Necessario
--s3-region	Regione AWS per il tuo bucket S3	Sì
--s3-apikey	ID chiave di accesso S3	Sì
--s3-apisecret	Chiave segreta di accesso S3	Sì
--s3-bucket-name	Nome del tuo bucket S3	Sì
--s3-endpoint	URL endpoint S3 personalizzato	No
--s3-port	Porta per l'endpoint S3	No
--no-s3-ssl	Disabilita SSL per l'upload su S3	No

Preparazione e crittografia del bundle

Quando utilizzi uno storage personalizzato, specialmente con crittografia, devi preparare correttamente i tuoi bundle. Questo comporta la creazione di un file zip e, opzionalmente, la sua crittografia.

Passo 1: Crea un bundle Zip

Per prima cosa, crea un file zip del tuo bundle dell'app:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

Il comando zip restituirà il checksum del file zip. Puoi usare questo checksum per crittografare il file zip, se necessario. Usa l' --json opzione per ottenere un output strutturato che includa il checksum.

Opzioni del comando Zip

npx @capgo/cli@latest bundle zip [appId] \
  --path ./dist \
  --bundle 1.2.3 \
  --name myapp-v1.2.3 \
  --json \
  --no-code-check \
  --key-v2 \
  --package-json ../../package.json,./package.json

Opzione	Descrizione
--path	Percorso della cartella da zippare (default: webDir in capacitor.config)
--bundle	Numero di versione del bundle per il file zip
--name	Nome personalizzato per il file zip
--json	Output in formato JSON (include checksum)
--no-code-check	Salta il controllo di notifyAppReady() e del file index
--key-v2	Usa la crittografia v2
--package-json	Percorsi dei file package.json per monorepo (separati da virgola)

Passo 2: Crittografa il bundle (opzionale)

Per una maggiore sicurezza, crittografa il tuo bundle zip prima dell'upload:

# Using default local key
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

# Using custom key file
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key ./path/to/.capgo_key_v2

# Using key data directly
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key-data "PRIVATE_KEY_CONTENT"

L'oggetto CHECKSUM il parametro è richiesto e deve essere il checksum del tuo file zip. Puoi ottenere il checksum dall'output del comando zip (usa --json l'opzione per un output strutturato).

Di default, il comando encrypt userà la tua chiave di firma privata locale. Puoi specificare una chiave personalizzata usando --key o --key-data opzioni.

Il comando encrypt restituirà il ivSessionKey necessario per l'upload o la decrittazione.

Opzioni del comando di crittografia

Opzione	Descrizione
zipPath	Percorso del file zip da crittografare (obbligatorio)
checksum	Checksum del file zip (obbligatorio) - ottenuto tramite comando zip
--key	Percorso personalizzato per la chiave di firma privata (opzionale, usa la chiave locale di default)
--key-data	Dati della chiave di firma privata direttamente (opzionale)
--json	Output dei risultati in formato JSON

Attenzione

Il comando encrypt restituirà un ivSessionKey che dovrai fornire durante l'upload con l'opzione --iv-session-key opzione.

Esempi di workflow completi

Esempio 1: URL esterno con crittografia

1. Build della tua app:

   npm run build

2. Crea un bundle zip:

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --bundle 1.2.3

   Prendi nota del checksum restituito da questo comando.

3. Crittografa il bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app-1.2.3.zip CHECKSUM_FROM_STEP_2

   Prendi nota del ivSessionKey dall'output.

4. Carica sul tuo storage: Carica il file zip criptato sul tuo servizio di hosting.

5. Registrati con Capgo:

   npx @capgo/cli@latest bundle upload \
     --external https://your-cdn.com/bundles/com.example.app-1.2.3.zip \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_3

Esempio 2: Upload diretto su S3

1. Build della tua app:

   npm run build

2. Upload diretto su S3:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --channel Production

Esempio 3: S3 con crittografia

1. Build e zip:

   npm run build
   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. Crittografa il bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM

3. Upload su S3 con crittografia:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_2 \
     --channel Production

Considerazioni sulla sicurezza

Quando usi uno storage personalizzato, tieni presenti queste best practice di sicurezza:

Controllo degli accessi

• Assicurati che gli URL dello storage siano accessibili agli utenti della tua app, ma non individuabili pubblicamente
• Usa URL firmati o l'autenticazione tramite token quando possibile
• Implementa gli header CORS corretti per le app web

Crittografia

• Crittografa sempre i bundle sensibili usando gli strumenti di crittografia Capgo
• Conserva le chiavi di crittografia in modo sicuro e ruotale regolarmente
• Usa HTTPS per tutti gli URL dei bundle (obbligatorio per app mobile ed Electron)

Monitoraggio

• Monitora i log di accesso per rilevare pattern di download insoliti
• Configura degli alert per i download dei bundle falliti
• Effettua regolarmente audit sui permessi di storage

Risoluzione problemi

Problemi comuni

Il bundle non viene scaricato:

• Verifica che l'URL sia pubblico e utilizzi HTTPS (obbligatorio per app mobile ed Electron)
• Controlla gli header CORS per le web app
• Assicurati che il formato del bundle sia corretto

Errori di crittografia:

• Verifica che l' ivSessionKey corrisponde al bundle crittografato
• Verifica che il bundle sia stato crittografato con la chiave corretta
• Assicurati che venga usata la crittografia v2 per i nuovi bundle

Errori durante l'upload su S3:

• Verifica le credenziali e i permessi S3
• Controlla le policy del bucket e la configurazione CORS
• Assicurati che la regione specificata sia corretta

Comandi di Debug

Controlla lo stato del bundle:

npx @capgo/cli@latest app debug

Verifica l'integrità del bundle:

npx @capgo/cli@latest bundle list

Prossimi passi

• Scopri come Canali per gestire diversi ambienti di deployment
• Esplora Comportamento degli update per personalizzare come vengono applicati gli update
• Configurazione Integrazione CI/CD automatizzare il workflow del tuo custom storage

Continua da Custom Storage

Se stai usando Storage personalizzato per pianificare sicurezza e compliance, collegalo a Crittografia per i dettagli di implementazione in Encryption, Conformità per i dettagli di implementazione in Compliance, Scanner di sicurezza Capgo per il workflow di Capgo Security Scanner, Sicurezza Capgo per il workflow di Capgo Security, e Trust Center di Capgo per il workflow di Capgo Trust Center.