Collegare un client SFTP

Connettiti a sftp.dosya.dev, porta 2222, con SFTP su SSH. Il nome utente è l’email dell’account dosya e la password è una chiave API completa. Il servizio offre solo operazioni sui file: non è FTP, FTPS né una shell SSH interattiva.

Crea credenziali utilizzabili dal client

Nell’app web scegli lo spazio di lavoro e apri Integrazioni → SFTP. Se appare Il tuo ruolo non consente di usare SFTP, chiedi accesso al proprietario o amministratore prima di creare un profilo nel client. Accesso SFTP e permessi di caricamento, download ed eliminazione sono decisioni separate del ruolo.

Apri Profilo → Chiavi API → Crea una chiave API. In A cosa serve? dai alla chiave un nome per questo computer e scegli Sola lettura per elenchi e download o Accesso completo per caricamento e gestione. Scegli Restrizioni e scadenza → Quale ambito di accesso ha? → Protocolli → Solo quelli che scelgo, seleziona SFTP e il vincolo Spazio di lavoro adatto. Generala e conserva il segreto mostrato una sola volta in privato.

Non scegliere Scegli cartella… per una credenziale SFTP: il protocollo rifiuta chiavi vincolate a cartelle. I vincoli a spazi di lavoro sono supportati. Una chiave Solo caricamento non può eseguire gli elenchi richiesti da questa guida. Evita anche restrizioni sugli IP consentiti: il gateway contatta l’API per tuo conto, quindi l’API non può verificare l’indirizzo originale e rifiuta la chiave limitata per IP. Restano valide scadenza, orari attivi e restrizioni d’uso applicabili.

Configura la connessione

Impostazione client	Valore dosya
Protocollo	SFTP / SSH File Transfer Protocol
Host	sftp.dosya.dev
Porta	2222
Nome utente	Email dell’account proprietario della chiave, rispettando maiuscole e minuscole
Autenticazione	Password
Password	Chiave API dos_… completa
Cartella iniziale	/ per l’elenco degli spazi di lavoro

Il server supporta l’autenticazione con password, non con chiave pubblica SSH. L’email non è un nome di spazio di lavoro e qui non si accede con la password dell’account. Salva la chiave solo nell’archivio privato delle credenziali del client.

Per OpenSSH tieni separata l’email dall’host usando l’opzione utente SSH:

sftp -P 2222 -o User=you@example.com -o PreferredAuthentications=password -o PubkeyAuthentication=no sftp.dosya.dev

Sostituisci l’email di esempio con la tua. Inserisci la chiave API solo alla richiesta di password; comandi, script salvati e cronologia della shell non devono contenere segreti. -P seleziona la porta SFTP; -p minuscola ha un altro significato. Il client deve essere installato sul computer.

Controlla l’host prima dell’autenticazione

Alla prima connessione può apparire un’impronta della chiave host SSH con richiesta di fiducia. La chiave host identifica il server, mentre la chiave API identifica il tuo account. Prima di accettare, confronta nome host, porta, tipo di chiave e impronta con un valore attendibile ottenuto dall’assistenza dosya o dall’amministratore tramite un altro canale. Questa guida non contiene un’impronta di produzione certificata; ottenere una chiave solo con ssh-keyscan non prova l’identità.

Se appare REMOTE HOST IDENTIFICATION HAS CHANGED!, fermati e conferma che la modifica sia legittima prima di cambiare le voci degli host noti. Non impostare StrictHostKeyChecking=no come soluzione abituale. La fiducia salvata è indipendente dalla password del client: sostituire la chiave API non risolve una chiave host diversa.

Passaggi: naviga e verifica un trasferimento

1. Connettiti e usa pwd e ls. In /, SFTP elenca gli spazi disponibili alla chiave e al ruolo. Non espone le raccolte All o viste intelligenti di WebDAV.
2. Usa cd "My Workspace", sostituendo l’esempio con un nome elencato. Funziona anche lo slug dello spazio. Usa di nuovo ls per vedere cartelle e file effettivi.
3. Entra in una cartella esistente o creane una di prova con mkdir "sftp-check", se consentito. Non puoi creare spazi dalla radice SFTP.
4. Carica un file locale di prova non vuoto con nome unico usando put sample.txt sftp-check-20261014.txt. Attendi il completamento e l’eventuale risposta finale di chiusura. Il gateway conferma al momento della chiusura: il 100% può precedere il completamento nel cloud.
5. Verifica nome e dimensione in File di dosya nello stesso spazio e cartella. Scarica con get sftp-check-20261014.txt ./sftp-check-downloaded.txt e confronta byte o SHA-256 con l’originale.
6. Riconnettiti e ripeti l’elenco per confermare la posizione salvata. Le modifiche da un altro client possono apparire con ritardo; la cache delle cartelle è di 10 secondi per impostazione predefinita, mentre le assenze sono ricontrollate.

Chi ha sola lettura può verificare un campione remoto noto con get. I download ordinari possono leggere a offset; le letture grandi da 64 MiB in su usano intervalli limitati, quindi tempo al primo byte e velocità possono variare. Non è disponibile un comando hash sul server né una shell: calcola gli hash localmente sull’origine e sulla copia scaricata.

Risultato previsto

Il percorso dello spazio elenca i file previsti e un campione scaricato completo corrisponde all’originale. Un campione caricato diventa un normale file in File di dosya solo dopo la conferma nel cloud; non è un link pubblico.

Operazioni supportate e limiti

Il gateway gestisce elenco/stat, get, put, mkdir, rinomina/spostamento, rm e rmdir. Le richieste di attributi chmod/chown sono accettate senza cambiare i permessi dello spazio dosya. Link simbolici e shell/exec SSH non sono supportati. Un client che cerca una shell deve continuare in modalità solo SFTP.

La configurazione distribuita imposta un limite di caricamento di 352 MiB (369.098.752 byte). Una distribuzione può impostarne uno inferiore; l’errore indica il valore attivo in MB. Questo limite è indipendente dallo spazio totale del piano. Regole su dimensioni ed estensioni, spazio residuo e limiti espliciti di credenziale o ruolo possono rifiutare file più piccoli. Account gratuiti e a pagamento possono usare SFTP; i limiti del piano su richieste e simultaneità non si applicano al protocollo, ma restano validi traffico in uscita giornaliero e limiti espliciti. Inizia con un trasferimento e riduci la simultaneità se il servizio segnala limitazioni.

I caricamenti restano temporaneamente nella sessione SFTP fino a CLOSE; quelli vuoti attualmente non creano file. Un caricamento interrotto non è riprendibile in modo persistente. Non usare Resume, Append, reput o put -a per il caricamento: il server attuale non ricarica la parte precedente quando apre una scrittura. Ricomincia dall’offset zero, preferibilmente con un nuovo nome.

Caricare un file completo con un nome esistente passa l’ID esistente al percorso di caricamento con versioni di dosya. Può sostituire i byte correnti e aggiungere una versione; la cronologia è predefinita a 10, salvo configurazione diversa, ed è soggetta a conservazione e rimozione. Conserva originali indipendenti prima di sostituire. rm e l’eliminazione di cartelle spostano i contenuti idonei nel cestino e revocano i link. Il cestino conserva sette giorni per proprietari gratuiti o 30 per gli altri; l’eliminazione definitiva è irreversibile. Ripristinare contenuti non riattiva un vecchio URL revocato.

Diagnostica i rifiuti

Messaggio o stato	Azione
Autenticazione con password fallita	Controlla maiuscole nell’email, chiave completa, protocollo SFTP, vincolo allo spazio, scadenza e restrizioni di cartella o IP. Tentativi ripetuti possono bloccare temporaneamente l’IP.
Il tuo ruolo non consente di usare SFTP	Chiedi accesso allo spazio di lavoro; cambiare client non aggira il controllo del ruolo.
access to that workspace is not permitted for this credential (stato SFTP 3)	Verifica appartenenza e permesso SFTP del ruolo.
no such file or directory (stato 2)	Controlla nome e percorso elencati; risorse non visibili possono risultare assenti.
the parent directory does not exist or is not writable by this credential	Entra in uno spazio o cartella esistente e verifica i permessi di creazione e caricamento.
write past the 352 MB per-file limit (o altro valore attivo)	Usa il caricamento web o un protocollo adatto per un file oltre il limite; non dividere gli offset per aggirarlo.
close failed: API 403 … o close failed: API 429 (rate limited - back off and retry) …	Esamina il dettaglio di permesso o regola oppure attendi. WRITE riuscito non prova che CLOSE abbia confermato.
access to this workspace was revoked while the upload was in flight	La conferma finale è rifiutata; contatta il proprietario senza riprendere la scrittura parziale.

SFTP traduce API 403 in permesso negato, 404 in file inesistente e altri errori nello stato 4; un client può mostrare solo questi nomi generici. I dettagli del server sono limitati a 180 caratteri e oscurano segreti simili a chiavi. Annota operazione, errore e ora senza esporre credenziali.

Disconnetti e revoca

Usa bye o disconnetti il client. Rimuovi separatamente le credenziali salvate e revoca la chiave dedicata in Profilo → Chiavi API quando l’accesso deve terminare. Le cache degli accessi SFTP riusciti e dei permessi di ruolo durano ciascuna fino a 60 secondi, ma l’autorizzazione API ha cache separate: 60 secondi non garantiscono la revoca completa. Dopo la propagazione dell’invalidazione, riconnettiti e verifica che l’azione richiesta venga rifiutata. Una connessione già aperta non prova che una chiave revocata possa ancora confermare operazioni. Revocare credenziali non elimina i file esistenti.

Guide correlate

• Recuperare un trasferimento SFTP interrotto
• Configurazione e restrizioni delle chiavi API