Vai al contenuto
Menu della documentazione

Gateway

Raggiungi i database privati con un canale solo in uscita: installazione, registrazione, credenziali sigillate per il Gateway, gestione operativa.

Il Prynt Gateway è un piccolo servizio che installi su un server della tua rete in grado di raggiungere il database. Apre solo connessioni in uscita verso Prynt, esegue accanto al database le query in sola lettura dei tuoi template e rimanda i risultati. Il database non è mai esposto a Internet, e non servono porte in ingresso, port forwarding o VPN.

Perché un gateway

La maggior parte dei database ERP sta in una rete privata, dietro un firewall. Aprirli a un servizio cloud vorrebbe dire una porta in ingresso, una allow-list da mantenere e un database raggiungibile da Internet. Con il Gateway la direzione si inverte: è il Gateway a chiamare Prynt, in HTTPS sulla porta 443, esattamente come un browser. È il modo consigliato per collegare qualsiasi database che non sia già un database cloud gestito (per quelli, vedi le connessioni dirette).

Come funziona

  • Registrazione. In Prynt aggiungi un gateway e ottieni un token di registrazione monouso, valido 15 minuti. Sul server, il Gateway si registra con il token, genera le proprie coppie di chiavi (ECDSA P-256 per autenticarsi, ECDH P-256 per ricevere le credenziali) e invia a Prynt solo le chiavi pubbliche. Le chiavi private non lasciano mai il server; Prynt conserva solo un hash del token.
  • Connessione. Il Gateway tiene aperto un WebSocket verso la Prynt API (wss://, percorso /api/v1/gateway/connect). A ogni connessione Prynt invia una sfida casuale e il Gateway risponde firmandola con la sua chiave privata: non c'è alcun segreto condiviso da rubare. Un heartbeat ogni 20 secondi mantiene viva la connessione; dopo un'interruzione il Gateway si ricollega con un'attesa crescente, fino a un minuto.
  • Richieste firmate. Ogni richiesta di Prynt (eseguire una query, leggere il catalogo, provare una connessione) è firmata con la chiave della piattaforma, che il Gateway ha fissato alla registrazione, scade entro pochi minuti ed è accettata una volta sola. Una richiesta non firmata da Prynt viene rifiutata, anche se qualcuno riuscisse a parlare con il Gateway.
  • Difesa in profondità. Il Gateway ricontrolla che ogni istruzione sia in sola lettura con il parser SQL del dialetto del database, e applica limiti propri su righe, byte, timeout, richieste concorrenti e schemi, qualunque cosa chieda il cloud. Tiene un audit locale di ogni richiesta (l'hash dell'istruzione, mai dati o valori dei parametri).

Un gateway può servire più sorgenti dati e più ambienti del workspace. Un gateway supporta sorgenti dati Oracle e PostgreSQL.

Credenziali sigillate per il gateway

Quando inserisci utente e password del database nella connessione di una sorgente dati che usa un gateway, il tuo browser li cifra con la chiave pubblica di quel gateway prima di inviarli: Prynt Cloud conserva una busta sigillata che non può decifrare, e solo quel gateway può aprirla, solo per la connessione per cui è stata sigillata. La pagina lo dice: Cifrate per questo gateway — Prynt non può leggerle.

  • La busta usa ECIES: un accordo di chiave ECDH P-256 effimero, HKDF-SHA256 e AES-256-GCM, legato alla sorgente dati e all'ambiente. I browser possono farlo solo su pagine HTTPS (WebCrypto).
  • Sul server, chiavi e credenziali del Gateway sono cifrate a riposo: con DPAPI (ambito macchina) su Windows, in una cartella leggibile solo da Administrators, SYSTEM e dall'utente che ha installato; con AES-256-GCM e un file di chiave leggibile solo dall'utente del servizio su Linux e nei container.
  • In alternativa imposta le credenziali direttamente sul Gateway con prynt-gateway credentials set: non passano mai da Prynt e hanno la precedenza sulla busta sigillata.

Requisiti

Windowsx64 / ARM64
Windows PowerShell 5.1 o successivo, eseguito come amministratore. Installato come servizio PryntGateway.
Linuxx86_64 / aarch64
systemd, curl o wget, sha256sum, tar; root per installare. Installato come servizio prynt-gateway.
Dockerlinux/amd64
Qualsiasi host Docker; l'immagine si carica da Prynt, nessun registry necessario.
Rete443 in uscita
HTTPS e WebSocket verso l'host della Prynt API, più la porta del database dentro la tua rete. Niente in ingresso.

I pacchetti sono autonomi (nessun .NET da installare) e sono serviti da Prynt stesso, ognuno con il suo SHA-256. Il Gateway si collega direttamente: non ha un'impostazione per un proxy HTTP in uscita, quindi il server ha bisogno di un accesso diretto in uscita all'API sulla porta 443. Tieni sincronizzato l'orologio del server: le richieste firmate hanno una scadenza.

Installazione

1. Aggiungi un gateway in Prynt

Apri Gateway in un workspace (permesso datasources.manage: owner, admin e developer) e scegli Aggiungi gateway. Dagli un nome che dica dove gira. Il dialogo mostra il token monouso (una sola volta, con la sua scadenza) e i comandi di installazione per Windows, Linux e Docker con l'indirizzo dell'API e il token già inseriti. Copiali dal dialogo: gli esempi qui sotto ne mostrano la forma.

2a. Windows

In Windows PowerShell aperto con Esegui come amministratore:

Windows · PowerShell (amministratore)
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; & ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://api.prynt.it/downloads/gateway/install.ps1').Content)) -Url 'https://api.prynt.it' -Token '<TOKEN>'

Lo script sceglie x64 o ARM64, scarica il pacchetto da Prynt e ne verifica lo SHA-256 (in caso di differenza non installa nulla), lo installa in C:\Program Files\Prynt\Gateway, registra il Gateway passando il token solo nell'ambiente del processo (mai sulla riga di comando né nell'output) e crea il servizio PryntGateway con avvio automatico e riavvio in caso di errore. Opzioni: -Version, -InstallDir, -DataDir, -NoService, -Force, -Uninstall [-RemoveData].

2b. Linux (systemd)

Linux · shell
curl -fsSL 'https://api.prynt.it/downloads/gateway/install.sh' | sudo bash -s -- --url 'https://api.prynt.it' --token '<TOKEN>'

Lo script verifica lo SHA-256, installa l'eseguibile in /opt/prynt-gateway, crea l'utente di sistema prynt-gateway con i suoi dati in /var/lib/prynt-gateway (permessi 0700), si registra come quell'utente e abilita la unit systemd prynt-gateway, che gira con restrizioni (nessun nuovo privilegio, sistema in sola lettura, cartella temporanea privata). Opzioni: --version, --install-dir, --data-dir, --no-service, --force, --uninstall [--purge].

2c. Docker

Docker
curl -fsSL 'https://api.prynt.it/downloads/gateway/latest/docker' | docker loaddocker run -d --name prynt-gateway --restart unless-stopped --read-only \  -v prynt-gateway:/var/lib/prynt-gateway \  -e PRYNT_GATEWAY_URL='https://api.prynt.it' -e PRYNT_GATEWAY_TOKEN='<TOKEN>' \  prynt/gateway:<version>

L'archivio dell'immagine arriva da Prynt, quindi l'host non ha bisogno di accedere a un registry. Il container si registra al primo avvio e conserva la sua identità nel volume prynt-gateway: mantieni il volume quando ricrei il container. Controllalo con docker exec prynt-gateway /opt/prynt-gateway/prynt-gateway status.

3. Attendi Online

In pochi secondi il gateway compare come Online nel dialogo e nell'elenco (la pagina si aggiorna ogni 10 secondi). Se il token scade prima, scegli Nuovo token di registrazione dal menu del gateway: il token precedente smette di funzionare.

Alta disponibilità

Installa due o più gateway su server diversi. Due processi con la stessa identità non sono attivo–attivo: il secondo resta in attesa di riserva e subentra quando il primo si ferma.

Usarlo in una sorgente dati

In una sorgente dati configura la connessione di un ambiente, scegli Prynt Gateway e il gateway, poi inserisci host, porta, service name (Oracle) o database (PostgreSQL) come li vede il gateway nella tua rete (per esempio erp-db.local o 10.0.0.12), e utente e password di un utente del database in sola lettura. Salva la connessione la prova anche attraverso il gateway.

Configurazione

I limiti si impostano in prynt-gateway.json, accanto all'eseguibile (C:\Program Files\Prynt\Gateway, /opt/prynt-gateway). Valgono in aggiunta ai limiti di Prynt: vince il più severo. Riavvia il servizio dopo una modifica; un aggiornamento mantiene il tuo file e scrive i nuovi valori predefiniti in prynt-gateway.json.new.

prynt-gateway.json
{  "Gateway": {    "MaxRows": 200000,    "MaxBytes": 268435456,    "MaxTimeoutSeconds": 900,    "MaxConcurrentRequests": 8,    "AllowedSchemas": [],    "SessionIdleSeconds": 600,    "AuditRetentionDays": 90  }}
MaxRowsintero
Righe massime che una query può restituire (predefinito 200.000).
MaxBytesintero
Dimensione massima del risultato di una query in byte (predefinito 256 MiB).
MaxTimeoutSecondsintero
Limite superiore del timeout di una query (predefinito 900 secondi).
MaxConcurrentRequestsintero
Richieste elaborate contemporaneamente (predefinito 8).
AllowedSchemaselenco
Gli schemi che il gateway può leggere; vuoto = quelli che l'utente del database vede. Limita anche l'esploratore del database e lo schema corrente.
SessionIdleSecondsintero
Le sessioni di lettura inattive si chiudono dopo questi secondi (predefinito 600).
AuditRetentionDaysintero
Giorni di file di audit locali conservati (predefinito 90).

Identità, chiavi, credenziali locali e file di audit stanno nella cartella dei dati: %ProgramData%\Prynt\Gateway su Windows, /var/lib/prynt-gateway su Linux e nel container (--data-dir o PRYNT_GATEWAY_HOME per cambiarla). L'audit si scrive in audit/yyyy-MM-dd.jsonl. Fai il backup di questa cartella, oppure prevedi di registrare un nuovo gateway se perdi il server.

Riga di comando

prynt-gateway
prynt-gateway register --url <API_URL> --token <TOKEN> [--force]prynt-gateway runprynt-gateway statusprynt-gateway credentials set <DATA_SOURCE> [--username <user>] [--password-stdin]prynt-gateway credentials listprynt-gateway credentials remove <DATA_SOURCE>prynt-gateway rotate-keyprynt-gateway --version
registercomando
Registra con un token monouso (oppure PRYNT_GATEWAY_URL e PRYNT_GATEWAY_TOKEN). --force registra di nuovo sopra un'identità esistente.
runcomando
Esegue il gateway in primo piano; i servizi eseguono questo comando.
statuscomando
Nome e id, indirizzo dell'API, impronta della chiave, id della chiave di cifratura, chiave della piattaforma, credenziali locali, cartella dei dati.
credentialscomando
set, list o remove delle credenziali salvate solo su questo gateway, per codice di sorgente dati.
rotate-keycomando
Sostituisce entrambe le coppie di chiavi su una connessione autenticata. Dopo, inserisci di nuovo le credenziali sigillate in Prynt.
0ok
Riuscito (status: registrato).
1errore
Errore di rete, token rifiutato o scaduto, rifiuto da parte di Prynt.
2uso
Comando o opzioni errati.
3non registrato
status, run o rotate-key su un gateway non registrato.
4già registrato
register senza --force su un gateway registrato.

Le credenziali impostate sul gateway si leggono dallo standard input:

Linux · credenziali locali
# La password si legge dallo standard input, mai dalla riga di comandoprintf '%s' "$ERP_PASSWORD" | sudo -u prynt-gateway /opt/prynt-gateway/prynt-gateway \  credentials set ERP_MAIN --username prynt_reader --password-stdin --data-dir /var/lib/prynt-gatewaysudo systemctl restart prynt-gateway

Monitorare, aggiornare, disinstallare

  • Stato. La pagina Gateway mostra ogni gateway come In attesa di registrazione, Online, Offline o Revocato, con nome host, sistema operativo, versione, ultimo contatto e le connessioni che lo usano. Un gateway che serve connessioni di produzione e resta offline viene annotato nel registro attività.
  • Aggiornamento. Esegui di nuovo lo script di installazione: su un gateway registrato non serve il token e l'identità resta. Ferma il servizio, sostituisce l'eseguibile dopo averne verificato lo SHA-256, mantiene la tua configurazione e lo riavvia. Con Docker carica la nuova immagine e ricrea il container sullo stesso volume. Non c'è ancora un aggiornamento automatico.
  • Revoca. Revoca… nel menu del gateway lo disconnette subito e lo rifiuta per sempre; la conferma elenca le connessioni che lo usano. Per reinstallarlo aggiungi un nuovo gateway.
  • Disinstallazione. install.ps1 -Uninstall (aggiungi -RemoveData per eliminare identità e audit) oppure install.sh --uninstall (--purge rimuove anche dati e utente), poi revoca il gateway in Prynt.
  • Log. Su Linux: journalctl -u prynt-gateway -n 50. Con Docker: docker logs prynt-gateway.

Problemi frequenti

Token rifiutatoregister
Il token è sconosciuto, scaduto (15 minuti) o già usato: creane uno nuovo dal menu del gateway, oppure aggiungi un nuovo gateway.
Resta offlineservizio
Esegui prynt-gateway status; controlla l'accesso in uscita all'host dell'API sulla porta 443, l'orologio del server e che il gateway non sia stato revocato.
Gateway offlineDesigner, API
Query, anteprime e generazioni falliscono con GATEWAY_OFFLINE (l'API risponde 503 DATA_SOURCE_UNAVAILABLE) finché il servizio non torna.
GATEWAY_TIMEOUTquery
Il gateway è connesso ma non ha risposto in tempo: controlla il server e la sua connessione al database.
Nessuna credenzialequery
Inseriscile nella connessione della sorgente dati (sigillate per questo gateway) oppure con prynt-gateway credentials set.
Credenziali da reinseriresorgente dati
Dopo rotate-key, o quando la connessione passa a un altro gateway, le credenziali sigillate vanno inserite di nuovo.
GATEWAY_LIMIT_EXCEEDEDquery
È stato superato un limite di prynt-gateway.json (righe, byte, schemi).
Riservalog
Un altro processo con la stessa identità è connesso; questo resta in attesa. Registra gateway distinti per l'alta disponibilità.

Il lato database (utenti, grant, errori di rete) è trattato in Oracle e PostgreSQL; il modello di sicurezza di Prynt nel suo insieme in Panoramica sulla sicurezza.