07/Documentation
Risoluzione dei problemi di un agente durevole
Un agente durevole che non compare o risulta Non raggiungibile: i primi controlli, ogni causa con la relativa soluzione, le righe del doctor e le casistiche che si presentano
Sperimentale. Il protocollo di rete, l'SDK e questa pagina potrebbero cambiare, oppure la funzionalità potrebbe essere rimossa, in una versione minor successiva. Agenti durevoli illustra i criteri in base ai quali viene deciso il mantenimento.
Un durable agent che non compare, mostra Unreachable o non risponde a un tocco: tre comandi ne individuano la causa, mentre una tabella dei motivi e un elenco di casi forniscono la soluzione. Risoluzione dei problemi riguarda Collie nel suo complesso.
Primi controlli
Eseguire questi tre comandi, in questo ordine:
collie durable list
collie doctor
collie logs| comando | cosa mostra per un durable agent |
|---|---|
collie durable list | Una riga per voce di sources.json, con lo stato assegnato dal bridge in esecuzione: loaded, not loaded (restart to apply), refused (<status>) o bridge not answering. loaded indica che il bridge ha caricato la voce. Non significa che il durable agent risponda. Viene mostrato anche not loaded quando il bridge restituisce HTTP 400 per il nome |
collie doctor | Interroga direttamente il durable agent. Stampa le righe di Righe di doctor per i durable agent e indica il controllo non riuscito con la relativa correzione |
collie logs | La riga di avvio di ogni durable agent, [bridge] program "desk": durable, private socket /run/user/1000/desk/app.sock, e il relativo motivo quando un'impostazione viola una regola. Un valore errato in sources.json stampa [bridge] FATAL:. Una lettura non riuscita stampa [state] poll failed, marking disconnected: <reason> una volta per interruzione. Le righe che iniziano con [durable] indicano un rifiuto della versione, un lead obsoleto, elementi scartati e un log eliminato |
Il telefono fornisce meno dettagli. La riga di un durable agent riporta Starting o Unreachable senza indicare alcun motivo. Il rifiuto della versione del protocollo ha una dicitura specifica, Version mismatch, e un riquadro di avviso nella schermata iniziale del durable agent. Un token rifiutato ha diciture dedicate nella barra di connessione. collie doctor e collie logs indicano ogni altro motivo.
La tabella dei motivi
Quando Collie non riesce a raggiungere un agent durevole, il resto di Collie si avvia comunque e l'agent durevole appare come non raggiungibile con un motivo.
Un motivo indica la variabile d'ambiente anche quando l'agent durevole è una voce di sources.json. Leggere COLLIE_DURABLE_SOCKET come il socket della voce, COLLIE_DURABLE_URL come il suo url e COLLIE_DURABLE_TOKEN come il suo token. La correzione per una voce si trova in sources.json. La correzione per la forma solo durevole si trova in .env, quindi collie restart.
L'impostazione viola una regola
Collie segnala questi errori senza contattare l'agent durevole. Le regole presenti nelle voci di sources.json vengono rifiutate anche all'avvio del bridge (Un errore di digitazione in sources.json).
| motivo | significato e correzione |
|---|---|
COLLIE_DURABLE_SOCKET is not set | La forma solo durevole non ha un percorso di socket. Impostarlo, oppure impostare l'URL con il relativo token |
COLLIE_DURABLE_SOCKET must be an absolute path | Fornire il percorso completo, a partire da / |
COLLIE_DURABLE_SOCKET is longer than 103 bytes | Accorciare il percorso. Mantenerlo sotto $XDG_RUNTIME_DIR |
the private socket transport is not available on Windows; set COLLIE_DURABLE_URL and COLLIE_DURABLE_TOKEN instead | Windows non dispone del trasporto socket. Usare un URL e un token |
COLLIE_DURABLE_SOCKET and COLLIE_DURABLE_URL are both set; set the socket, or the URL with its token, not both | La forma solo durevole ha ricevuto entrambi. Mantenere un solo trasporto |
COLLIE_DURABLE_URL is set without COLLIE_DURABLE_TOKEN; the durable agent refuses a caller with no token | La forma solo durevole ha ricevuto un URL e nessun token. Impostare il token |
COLLIE_DURABLE_TOKEN is set without COLLIE_DURABLE_URL; a token is only sent to a URL | La forma solo durevole ha ricevuto un token e nessun URL. Impostare l'URL, oppure rimuovere il token |
COLLIE_DURABLE_URL is longer than 2048 bytes | Accorciare l'URL all'indirizzo di base dell'agent durevole |
COLLIE_DURABLE_URL is not a URL | Scriverlo come https://host |
COLLIE_DURABLE_URL must start with https:// | Qualsiasi schema diverso da https:// viene rifiutato. La variante http:// semplice ha una propria riga più sotto |
COLLIE_DURABLE_URL uses plain http to <host>, so the token would cross the network unencrypted; use https://, or http://127.0.0.1:<port> for wrangler dev | Usare https://. La variante http semplice è riservata a 127.0.0.1 o localhost con una porta |
COLLIE_DURABLE_URL uses plain http on loopback without a port; name the port, for example http://127.0.0.1:8801 | Aggiungere la porta |
COLLIE_DURABLE_URL must not carry a user name or password; the token goes in COLLIE_DURABLE_TOKEN | Rimuovere nome utente e password dall'URL |
COLLIE_DURABLE_URL must not carry a query or a fragment | Rimuovere la parte ? e la parte # dall'URL |
COLLIE_DURABLE_URL names the durable agent's base only; leave out /session/v1, the adapter adds it | Eliminare /session/v1 dal percorso |
COLLIE_DURABLE_TOKEN is <n> bytes; it must be at least 32 bytes, for example 64 hex characters from openssl rand -hex 32 | Generare un token più lungo e assegnare lo stesso all'agent durevole |
COLLIE_DURABLE_TOKEN must be printable ASCII with no spaces | Rimuovere gli spazi e gli altri caratteri dal token |
COLLIE_DURABLE_TOKEN is longer than 4096 bytes | Un'intestazione così lunga è un errore. Usare un token più corto |
L'agent durevole non risponde o risponde in modo errato
| motivo | significato e correzione |
|---|---|
no socket at <path> | Non c'è ancora nulla nel percorso. Avviare l'agent durevole, oppure correggere il percorso |
cannot check <path>: <message> | Collie non ha potuto leggere il percorso. Renderlo leggibile per il proprio utente |
socket-not-private: <check> | L'esplorazione del percorso non è riuscita e il testo dopo i due punti indica la parte interessata. Il controllo della privacy non riesce elenca quelle consuete |
connection refused | Nessun processo in ascolto. Un durable agent andato in crash può lasciare residui del file socket: Un file socket obsoleto. Su https, nulla è in ascolto all'URL |
no answer within <n>ms | Il durable agent si è bloccato o è in fase di avvio a freddo. Collie attende 1000 ms su un socket e 5000 ms su https |
tls refused: <message> | Il certificato dell'URL viene rifiutato. Collie non dispone di un'opzione per saltare il controllo |
the host name does not resolve | Il nome host nell'URL non è corretto, o la rete non riesce a raggiungerlo |
token-refused: the durable agent answered 401 o 403 | Il durable agent ha rifiutato il token. Il durable agent ha rifiutato il token |
too-large | Il durable agent ha risposto con una quantità di dati superiore a quanto letto da Collie: 16 KiB per hello, 4 MiB per uno snapshot. Ridurre le dimensioni della risposta |
incompatible: the durable agent speaks 2..3, this Collie speaks 1..1 | Gli intervalli di versione non coincidono. Aggiornare il componente meno recente. collie doctor mostra entrambi gli intervalli e il log include una riga per intervallo |
incompatible: not a durable agent | Un altro servizio risponde a quel percorso o URL. Puntare la voce verso il durable agent |
incompatible: the durable agent asks for a token | Un durable agent su socket richiede un token, ma un socket non trasmette mai token. Aggiornare il componente meno recente o raggiungerlo tramite URL con un token |
unreadable hello: <detail> o unreadable snapshot: <detail> | Il durable agent ha inviato un documento non consentito dal protocollo. Consultare il log del durable agent |
the durable agent answered <status> o the durable agent answered 409 <code> | Il durable agent ha risposto con uno stato non utilizzato dal protocollo in questo contesto. Consultare il log del durable agent |
starting | Il durable agent è attivo e segnala di non essere pronto, oppure risponde con 503. Collie ritenta al poll successivo |
Righe di doctor per i durable agent
collie doctor invia a ciascun durable agent le stesse richieste inviate dal bridge, nello stesso ordine. Non trasmette altro che hello.
Ogni voce di sources.json riceve un blocco di sei righe, indicate come durable-socket:desk per un durable agent denominato desk. Una riga sources prima dei blocchi controlla il file, e una riga durable-lead li segue. Un Collie solo durable stampa le stesse sei righe senza suffisso, e la relativa riga mux indica durable, see the durable-* lines.
| riga | verde | avviso o rosso |
|---|---|---|
sources | 2 durable agents in <path>, mode 0600 | Rosso quando l'analisi del file non riesce. La correzione segnala che il bridge non si avvia finché il file non è corretto. Rosso quando gruppo o altri possono leggere il file, con correzione chmod 600, poiché una voce può contenere un token |
durable-env | transport: private socket con il percorso, o transport: https with a bearer token | Rosso quando l'impostazione viola una regola presente in la tabella dei motivi |
durable-socket | Il percorso è un socket, dell'utente, modalità 0600, in una cartella dell'utente con modalità 0700, senza collegamenti lungo il percorso | Rosso, e la riga specifica il controllo non superato: elemento inesistente, illeggibile, non è un socket, symlink, non è una cartella, cartella di un altro proprietario, cartella con modalità errata, cartella superiore scrivibile da altri, socket di un altro proprietario, o socket con permessi aperti. Ignorato per un durable agent dietro https |
durable-url | L'indirizzo, https o http su loopback, e la sua lunghezza in byte | Rosso quando l'URL viola una regola. Ignorato su un socket |
durable-token | set, <n> bytes. Collie non stampa mai il valore | Rosso quando il token viola una regola. Ignorato su un socket |
durable-hello | Il durable agent ha risposto. Entrambi gli intervalli, la versione concordata | Rosso con la causa: il token è stato rifiutato, nessuna risposta, ha risposto qualcosa che non è un durable agent, il durable agent richiede un token su un socket, un hello illeggibile oppure intervalli che non combaciano. Una mancata corrispondenza dell'intervallo mostra entrambi gli intervalli |
durable-ready | ready, il nome host del durable agent e la sua epoca | Un avviso quando il durable agent segnala di non essere ancora pronto |
durable-lead | Il lead è abbastanza recente da mostrare la scheda della domanda | Vedere In una crew |
Una riga che fallisce blocca le righe successive. Vengono mostrate come saltate con il motivo fix the row above first, perché Collie non interroga mai un durable agent tramite un socket che fallisce il controllo di riservatezza o con un token che viola la sua regola. Una riga saltata non è un errore.
Casi
Ogni caso indica cosa si osserva, il motivo e la soluzione.
Un errore di digitazione in sources.json
Collie risulta non attivo, non solo un singolo durable agent: il telefono non riesce a connettersi. collie logs termina con [bridge] FATAL:, il percorso del file, la voce e il campo.
Il bridge legge sources.json all'avvio e si arresta in presenza di un campo sconosciuto, un kind che non è durable, un nome che viola la regola, un nome usato due volte, socket e url insieme, nessuno dei due, un url senza token o un token con un socket. Correggere il file, poi eseguire collie restart. collie doctor mostra lo stesso messaggio nella sua riga sources.
Quando il bridge non può identificare la voce (non è un oggetto, ha un campo sconosciuto o il nome viola la regola), conta a partire da 0 e scrive entry 1 per la seconda voce. collie durable attach conta a partire da 1 e scrive entry 2 per la stessa voce. Entrambi indicano il campo. Una volta che il nome è valido, il bridge scrive il nome: entry "desk".
attach e detach rifiutano di scrivere un file che non possono leggere, perciò un errore di battitura non compromette mai le altre voci. Si arrestano con codice di uscita 1.
Un durable agent non compare dopo l'attach
Sul telefono non compare alcun durable agent e collie durable list indica not loaded (restart to apply).
attach e detach scrivono solo sources.json. Il bridge lo legge all'avvio. Eseguire collie restart, oppure aggiungere --restart al verbo la volta successiva. Se not loaded persiste dopo un riavvio, leggere collie logs: list formula un errore HTTP 400 dal bridge nello stesso modo di un 404.
Il controllo della privacy non riesce
Si osserva socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700 e la riga doctor durable-socket è rossa.
Collie si connette a un socket solo quando l'intero percorso è privato. Le cause consuete sono una cartella con permessi 0755, un socket posizionato direttamente in /tmp o in un'altra cartella condivisa, e un collegamento simbolico nel percorso. Un collegamento simbolico è facile da non notare: su molti host Linux /var/run punta a /run, quindi un percorso che inizia con /var/run/ fallisce con /var/run is a symlink. Usare il percorso reale.
Eseguire chmod 700 sulla cartella del socket, oppure spostare il socket sotto $XDG_RUNTIME_DIR. Le regole sono in Sicurezza di un agente durevole. Un durable agent compilato con l'SDK rifiuta di avviarsi in una cartella esistente la cui modalità non sia 0700, e lo segnala autonomamente.
Un file socket obsoleto
Si osserva connection refused su un socket, e il file è presente.
Un durable agent andato in crash lascia il proprio file di socket, e nulla rimane in ascolto su di esso. Avviare nuovamente il durable agent. L'SDK rimuove un file di socket inattivo prima di mettersi in ascolto, e si arresta con another instance is already listening quando il socket è attivo. Eliminare il file manualmente solo se il durable agent non lo rimuove.
Un nome che corrisponde anche a una sessione di terminale
Si osserva il bridge arrestarsi all'avvio con the name is the terminal session's own; pick another, oppure una sessione di terminale mancante sul telefono.
Un durable agent non può avere lo stesso nome del terminale da cui è eseguito Collie. Tale nome è default nella maggior parte delle installazioni, e in una configurazione Collie solo per durable default è quello del relativo durable agent. Il bridge si arresta all'avvio e indica la voce. Una sessione Herdr con il nome di un durable agent è un altro caso: il durable agent mantiene il nome, il telefono non mostra quella sessione e il log lo segnala una volta. Rinominare uno dei due.
Un avviso durable-ready che persiste
Si osserva durable-ready come avviso a ogni esecuzione di collie doctor.
Il durable agent risponde con hello e segnala ready: false. Il telefono lo mostra come In avvio. Un durable agent dichiara di essere pronto solo dopo aver predisposto le proprie conversazioni e ripresentato le domande aperte. Leggere il log del durable agent per verificare cosa stia attendendo.
Il durable agent si arresta all'avvio durante il controllo dei discendenti
Si osserva il durable agent arrestarsi all'avvio con the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it.
Il controllo richiede Bun su Linux. Su macOS, eseguire il durable agent con Node, oppure passare callerCheck: "off" a openCollie e leggere prima cosa protegge il controllo. L'errore proviene dal durable agent. Collie non è coinvolto.
Una domanda ricompare dopo un riavvio
Si visualizza di nuovo una domanda dopo il riavvio del durable agent, oppure una scheda che indica che ha già ricevuto risposta.
Una risposta a una domanda precedente al riavvio riceve too-late, la scheda lo segnala e scompare. Un durable agent che ricava l'id della domanda dalla chiamata del tool ripropone la stessa domanda; in questo modo una risposta inviata a cavallo del riavvio viene recapitata e il tool viene eseguito una sola volta. Un durable agent che genera un nuovo id ogni volta pone una nuova domanda per la stessa chiamata del tool. La scheda la mostra e Collie non invia una seconda notifica push, poiché il guardiano delle notifiche push usa come chiave la chiamata del tool. La protezione consente inoltre 3 push al minuto per conversazione, 10 al minuto per host e 30 all'ora per host. Il push che costituirebbe il 31º in un'ora diventa un singolo push di riepilogo per quell'host, dopodiché l'host non ne invia altri per un'ora. Viene sempre mostrata una scheda.
403 caller-refused
Sul telefono compare l'avviso che la risposta o il messaggio sono stati rifiutati, con motivo del durable agent impostato su 403 caller-refused.
Il controllo sui discendenti del durable agent ha rifiutato il chiamante. Rifiuta il durable agent stesso, qualsiasi processo avviato dal durable agent e qualsiasi chiamante che non riesca a distinguere da essi. Collie ricade tra questi quando il durable agent, o un tool da esso eseguito, ha avviato il processo di Collie e tale processo ne è ancora figlio. Avviare Collie dall'esterno del durable agent, quindi riprovare.
Riprovare, e una risposta che potrebbe essere applicata
Compare "Non è chiaro se la risposta sia arrivata" con il pulsante Riprova, e dopo il tocco "Potrebbe essere già applicata. Controllare la chat."
Un timeout, una connessione interrotta o un codice 5xx dopo l'invio della risposta indicano che potrebbe essere stata recapitata. Riprova invia lo stesso id di richiesta, quindi il durable agent risponde replayed e non risolve mai la domanda due volte. Quando la domanda è già chiusa, il primo tentativo potrebbe averla chiusa; per questo il telefono invita a controllare la chat. L'invio, l'arresto e il tocco di un pulsante indicano la stessa condizione con diciture specifiche.
Il durable agent ha rifiutato il token
Sulla barra di connessione compare "Il durable agent ha rifiutato il token. Controllare COLLIE_DURABLE_TOKEN su questo peer.", e il motivo è token-refused.
Il durable agent ha risposto 401 o 403 al token. La causa più frequente è una rotazione in cui una delle parti è stata modificata per prima. La dicitura sul telefono indica COLLIE_DURABLE_TOKEN anche per una voce di sources.json: va intesa come token della voce. Assegnare il nuovo token al durable agent prima di riavviare Collie. La procedura di rotazione è indicata in Token. Un errore 403 può derivare anche da un proxy di accesso posto davanti al durable agent.
Un passaggio a Non raggiungibile che richiede due letture
Si osserva un durable agent rimanere in stato Pronto per una lettura non riuscita, per poi passare a Non raggiungibile.
Una singola lettura non riuscita dopo una andata a buon fine mantiene l'ultimo layout per quel ciclo di poll. Il secondo fallimento consecutivo porta il durable agent nello stato non raggiungibile. La stessa regola vale per un token rifiutato. Il percorso di un socket che non supera il controllo di riservatezza rappresenta l'unica eccezione: viene mostrato immediatamente.
Su https, un durable agent non attivo o che rifiuta il token viene interrogato al massimo una volta ogni 10 s, poiché ogni tentativo rappresenta una richiesta fatturata. Su socket, l'intervallo minimo tra due letture di un durable agent non attivo è di 250 ms.
In una crew
Un durable agent su un membro di una crew viene mostrato sul telefono del lead; pertanto il lead deve essere in grado di riconoscere un durable agent.
Un lead precedente a 1.21.0 elenca le conversazioni del durable agent senza la scheda della domanda, e la sua scheda Terminal esegue il poll di una conversazione priva di terminale. Nessun intervento sul membro risolve il problema. È il membro stesso a segnalarlo: collie doctor avverte in durable-lead, e il log registra una riga, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead, per ciascuna versione rilevata. Aggiornare il lead.
durable-lead | messaggio visualizzato |
|---|---|
| ignorato, nessuna crew | Questa macchina non fa parte di una crew, pertanto non è presente alcun lead |
| ignorato, lead | Questa macchina funge da lead e mostra i propri riquadri |
| ignorato, nessuna versione | Il lead non ha indicato alcuna versione: build di sviluppo, aggiornamento in corso o nessuna chiamata dall'avvio del bridge |
| avviso | Il lead esegue una versione precedente a 1.21.0 |
| verde | Il lead è alla versione 1.21.0 o successiva |
Un membro precedente rispetto al lead presenta il problema opposto. Il telefono mostra "Questa macchina esegue una versione precedente di Collie e non può ricevere risposte qui. Aggiornarla, oppure rispondere nel durable agent." Aggiornare quel membro.
Modifica questa pagina su GitHub