07/Documentation
Resolución de problemas de un durable agent
Un durable agent que no aparece o indica Unreachable: comprobaciones iniciales, cada causa y su solución, las filas de doctor y los casos que se presentan
Experimental. El protocolo de red, el SDK y esta página pueden cambiar, o la funcionalidad puede eliminarse, en una versión menor posterior. Durable agents indica el criterio para decidir si se mantiene.
Un agente duradero que no aparece, muestra Unreachable o no responde a un toque: tres comandos identifican la causa, y una tabla de motivos junto con una lista de casos proporcionan la solución. Resolución de problemas cubre Collie en su totalidad.
Primeras comprobaciones
Ejecute estos tres comandos, en este orden:
collie durable list
collie doctor
collie logs| comando | qué muestra para un agente duradero |
|---|---|
collie durable list | Una línea por entrada de sources.json, con el estado que le asigna el bridge en ejecución: loaded, not loaded (restart to apply), refused (<status>) o bridge not answering. loaded significa que el bridge cargó la entrada. No significa que el agente duradero responda. También se muestra un not loaded cuando el bridge responde HTTP 400 para el nombre |
collie doctor | Consulta al propio agente duradero. Imprime las filas de Filas de doctor para agentes duraderos e indica la comprobación con fallos junto con una solución |
collie logs | La línea de arranque de cada agente duradero, [bridge] program "desk": durable, private socket /run/user/1000/desk/app.sock, y su motivo cuando una configuración infringe una regla. Un sources.json incorrecto imprime [bridge] FATAL:. Una lectura fallida imprime [state] poll failed, marking disconnected: <reason> una vez por corte. Las líneas que comienzan con [durable] indican un rechazo de versión, un lead antiguo, elementos descartados y un registro eliminado |
El teléfono muestra menos información. La fila de un agente duradero muestra Starting o Unreachable y no indica ningún motivo. Un rechazo de versión del protocolo tiene su propio texto, Version mismatch, y un cuadro de advertencia en la página principal del agente duradero. Un token rechazado tiene sus propios textos en la barra de conexión. collie doctor y collie logs indican cualquier otro motivo.
La tabla de motivos
Cuando Collie no puede comunicarse con un agente duradero, el resto de Collie se inicia de todos modos y el agente duradero aparece como inaccesible con un motivo.
El motivo indica la variable de entorno incluso cuando el agente duradero es una entrada de sources.json. Interprete COLLIE_DURABLE_SOCKET como el socket de la entrada, COLLIE_DURABLE_URL como su url y COLLIE_DURABLE_TOKEN como su token. La solución para una entrada se encuentra en sources.json. La solución para el formato exclusivo de agente duradero se encuentra en .env, y luego en collie restart.
La configuración infringe una regla
Collie informa de estos errores sin llamar al agente duradero. Las reglas presentes en las entradas de sources.json también se rechazan al inicio del puente (Un error tipográfico en sources.json).
| motivo | significado y solución |
|---|---|
COLLIE_DURABLE_SOCKET is not set | El formato exclusivo de agente duradero no tiene ruta de socket. Configúrela o configure la URL con su token |
COLLIE_DURABLE_SOCKET must be an absolute path | Indique la ruta completa, comenzando por / |
COLLIE_DURABLE_SOCKET is longer than 103 bytes | Acorte la ruta. Manténgala por debajo de $XDG_RUNTIME_DIR |
the private socket transport is not available on Windows; set COLLIE_DURABLE_URL and COLLIE_DURABLE_TOKEN instead | Windows no tiene transporte por socket. Use una URL y un token |
COLLIE_DURABLE_SOCKET and COLLIE_DURABLE_URL are both set; set the socket, or the URL with its token, not both | El formato exclusivo de agente duradero recibió ambos. Conserve solo un transporte |
COLLIE_DURABLE_URL is set without COLLIE_DURABLE_TOKEN; the durable agent refuses a caller with no token | El formato exclusivo de agente duradero recibió una URL y ningún token. Configure el token |
COLLIE_DURABLE_TOKEN is set without COLLIE_DURABLE_URL; a token is only sent to a URL | El formato exclusivo de agente duradero recibió un token y ninguna URL. Configure la URL o elimine el token |
COLLIE_DURABLE_URL is longer than 2048 bytes | Acorte la URL a la dirección base del agente duradero |
COLLIE_DURABLE_URL is not a URL | Escríbalo como https://host |
COLLIE_DURABLE_URL must start with https:// | Se rechaza cualquier esquema que no sea https://. El protocolo http:// simple tiene su propia fila más abajo |
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 | Use https://. El protocolo http simple es para 127.0.0.1 o localhost con un puerto |
COLLIE_DURABLE_URL uses plain http on loopback without a port; name the port, for example http://127.0.0.1:8801 | Añada el puerto |
COLLIE_DURABLE_URL must not carry a user name or password; the token goes in COLLIE_DURABLE_TOKEN | Elimine el nombre de usuario y la contraseña de la URL |
COLLIE_DURABLE_URL must not carry a query or a fragment | Elimine la parte ? y la parte # de la URL |
COLLIE_DURABLE_URL names the durable agent's base only; leave out /session/v1, the adapter adds it | Quite /session/v1 de la ruta |
COLLIE_DURABLE_TOKEN is <n> bytes; it must be at least 32 bytes, for example 64 hex characters from openssl rand -hex 32 | Genere un token más largo y configure el mismo en el agente duradero |
COLLIE_DURABLE_TOKEN must be printable ASCII with no spaces | Elimine los espacios y otros caracteres del token |
COLLIE_DURABLE_TOKEN is longer than 4096 bytes | Un encabezado tan largo es un error. Use un token más corto |
El agente duradero no responde o responde de forma incorrecta
| motivo | significado y solución |
|---|---|
no socket at <path> | Todavía no hay nada en la ruta. Inicie el agente duradero o corrija la ruta |
cannot check <path>: <message> | Collie no pudo leer la ruta. Otorgue permisos de lectura a su usuario |
socket-not-private: <check> | El recorrido de la ruta falló y el texto después de los dos puntos indica la sección afectada. La comprobación de privacidad falla contiene los casos habituales |
connection refused | Nada escucha. Un durable agent que falló puede dejar su archivo de socket: Un archivo de socket obsoleto. Sobre https, nada escucha en la URL |
no answer within <n>ms | El durable agent se cuelga o está frío. Collie espera 1000 ms en un socket y 5000 ms sobre https |
tls refused: <message> | El certificado de la URL es rechazado. Collie no tiene ninguna opción para omitir la comprobación |
the host name does not resolve | El nombre de host en la URL es incorrecto, o la red no puede alcanzarlo |
token-refused: the durable agent answered 401 o 403 | El durable agent rechazó el token. El durable agent rechazó el token |
too-large | El durable agent respondió con más de lo que Collie lee: 16 KiB para hello, 4 MiB para una instantánea. Reduzca el tamaño de su respuesta |
incompatible: the durable agent speaks 2..3, this Collie speaks 1..1 | Los rangos de versión no coinciden. Actualice el extremo más antiguo. collie doctor muestra ambos rangos y el registro recibe una línea por rango |
incompatible: not a durable agent | Otro proceso responde en esa ruta o URL. Apunte la entrada al durable agent |
incompatible: the durable agent asks for a token | Un durable agent en un socket requiere un token, el cual un socket nunca transmite. Actualice el extremo más antiguo, o acceda a él por URL con un token |
unreadable hello: <detail> o unreadable snapshot: <detail> | El durable agent envió un documento que el protocolo de comunicación no permite. Lea el registro propio del durable agent |
the durable agent answered <status> o the durable agent answered 409 <code> | El durable agent respondió con un estado que el protocolo de comunicación no utiliza aquí. Lea el registro propio del durable agent |
starting | El durable agent está activo e indica que no está listo, o responde 503. Collie vuelve a consultar en el siguiente sondeo |
Filas de doctor para agentes duraderos
collie doctor hace a cada durable agent las mismas preguntas que el puente, en el orden en que el puente las hace. No envía nada excepto hello.
Cada entrada de sources.json recibe un bloque de seis filas, escritas durable-socket:desk para un durable agent llamado desk. Una fila sources antes de los bloques comprueba el archivo, y una fila durable-lead los sigue. Un Collie solo duradero imprime las mismas seis filas sin sufijo, y su fila mux indica durable, see the durable-* lines.
| fila | verde | advertencia o rojo |
|---|---|---|
sources | 2 durable agents in <path>, mode 0600 | Rojo cuando el archivo no se puede analizar. Su solución indica que el puente no se inicia mientras sea incorrecto. Rojo cuando el grupo u otros pueden leer el archivo, con chmod 600 como solución, porque una entrada puede contener un token |
durable-env | transport: private socket con la ruta, o transport: https with a bearer token | Rojo cuando la configuración infringe una regla de la tabla de motivos |
durable-socket | La ruta es un socket, propio, modo 0600, en una carpeta propia con modo 0700, sin enlaces en el trayecto | Rojo, y la fila nombra la comprobación fallida: nada allí, ilegible, no es un socket, un enlace simbólico, no es una carpeta, una carpeta de otro propietario, una carpeta con el modo incorrecto, una carpeta superior en la que otros pueden escribir, un socket de otro propietario o un socket con un modo abierto. Omitido en un durable agent tras https |
durable-url | La dirección, https o http de loopback, y su longitud en bytes | Rojo cuando la URL infringe una regla. Omitido en un socket |
durable-token | set, <n> bytes. Collie nunca imprime el valor | Rojo cuando el token infringe una regla. Omitido en un socket |
durable-hello | El durable agent respondió. Ambos rangos, la versión acordada | Rojo con la causa: se rechazó el token, nada respondió, respondió algo que no es un agente duradero, el agente duradero solicita un token en un socket, un hello ilegible o rangos que no coinciden. Una discrepancia de rango muestra ambos rangos |
durable-ready | ready, el nombre de host del agente duradero y su epoch | Una advertencia cuando el agente duradero indica que aún no está listo |
durable-lead | El hilo principal es lo bastante nuevo como para mostrar la tarjeta de pregunta | Consulte En una crew |
Una fila que falla detiene las filas posteriores. Se muestran como omitidas con el motivo fix the row above first, ya que Collie nunca consulta a un agente duradero a través de un socket que no supere la comprobación de privacidad o con un token que infrinja su regla. Una fila omitida no es un fallo.
Casos
Cada caso describe lo que se observa, el motivo y la solución.
Un error tipográfico en sources.json
Se observa que Collie está caído, no solo un agente duradero: el teléfono no puede conectarse. collie logs termina con [bridge] FATAL:, la ruta del archivo, la entrada y el campo.
El puente lee sources.json al inicio y se detiene ante un campo que desconoce, un kind que no es durable, un nombre que infringe la regla, un nombre duplicado, socket y url juntos, ninguno de los dos, un url sin token o un token con un socket. Corrija el archivo y ejecute collie restart. collie doctor muestra el mismo mensaje en su fila sources.
Cuando el puente no puede nombrar la entrada (no es un objeto, contiene un campo desconocido o el nombre infringe la regla), cuenta desde 0 y escribe entry 1 para la segunda. collie durable attach cuenta desde 1 y escribe entry 2 para la misma entrada. Ambos indican qué campo. Una vez que el nombre es válido, el puente escribe el nombre: entry "desk".
attach y detach rechazan escribir un archivo que no pueden leer, de modo que un error tipográfico nunca afecta al resto de las entradas. Se detienen con el código de salida 1.
Un agente duradero no aparece tras ejecutar attach
No se observa ningún agente duradero en el teléfono y collie durable list indica not loaded (restart to apply).
attach y detach solo escriben sources.json. El puente lo lee al inicio. Ejecute collie restart o agregue --restart al verbo la próxima vez. Si not loaded persiste tras un reinicio, lea collie logs: list formula un HTTP 400 del puente del mismo modo que un 404.
La comprobación de privacidad falla
Se observa socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700 y la fila durable-socket de doctor aparece en rojo.
Collie solo conecta a un socket si la ruta completa es privada. Las causas habituales son una carpeta con modo 0755, un socket ubicado directamente en /tmp u otra carpeta compartida, y un enlace simbólico en la ruta. Un enlace simbólico es fácil de pasar por alto: /var/run apunta a /run en muchos hosts Linux, por lo que una ruta que comienza con /var/run/ falla con /var/run is a symlink. Utilice la ruta real.
Ejecute chmod 700 en la propia carpeta del socket o muévalo debajo de $XDG_RUNTIME_DIR. Las reglas se encuentran en Seguridad de un durable agent. Un agente duradero compilado con el SDK rechaza iniciarse en una carpeta existente cuyo modo no sea 0700, y lo indica directamente.
Un archivo de socket obsoleto
Se observa connection refused en un socket y el archivo existe.
Un agente duradero que falla de forma anómala deja atrás su archivo de socket y nada escucha en él. Inicie el agente duradero de nuevo. El SDK elimina un archivo de socket inactivo antes de escuchar y se detiene con another instance is already listening si el socket está activo. Elimine el archivo manualmente solo si el agente duradero no lo borra.
Un nombre que coincide con una sesión de terminal
Se observa que el puente se detiene al inicio con the name is the terminal session's own; pick another, o bien falta una sesión de terminal en el teléfono.
Un agente duradero no puede tomar el nombre de la terminal desde la que se ejecuta Collie. Ese nombre es default en la mayoría de las instalaciones, y en un Collie exclusivo para agentes duraderos default pertenece a su agente duradero. El puente se detiene al inicio e indica el nombre de la entrada. Una sesión de Herdr que tenga el nombre de un agente duradero constituye otro caso: el agente duradero conserva el nombre, el teléfono no muestra esa sesión y el registro lo indica una vez. Cambie el nombre de uno de ellos.
Una advertencia de preparación de agente duradero que persiste
Se observa durable-ready como advertencia en cada ejecución de collie doctor.
El agente duradero responde hello e indica ready: false. El teléfono lo muestra como Iniciando. Un agente duradero indica que está listo solo después de haber dispuesto sus conversaciones y planteado de nuevo sus preguntas abiertas. Consulte el propio registro del agente duradero para saber qué está esperando.
El agente duradero se detiene al inicio en la comprobación de descendientes
Se observa que el agente duradero se detiene al inicio con the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it.
La comprobación requiere Bun en Linux. En macOS, ejecute el agente duradero con Node o pase callerCheck: "off" a openCollie y lea qué protege la comprobación primero. El error procede del agente duradero. Collie no interviene.
Una pregunta reaparece tras reiniciar
Se vuelve a ver una pregunta después de que el durable agent se reiniciara, o una tarjeta indicando que ya se respondió.
Una respuesta a una pregunta previa al reinicio recibe too-late, la tarjeta lo indica y desaparece. Un durable agent que deriva el id de la pregunta a partir de la llamada a su herramienta vuelve a plantear la misma pregunta; de este modo, la respuesta enviada a través del reinicio se recibe y la herramienta se ejecuta una vez. Un durable agent que genera un id nuevo cada vez plantea una pregunta nueva para la misma llamada a la herramienta. La tarjeta la muestra y Collie no envía una segunda notificación push, ya que la protección de notificaciones push toma como clave la llamada a la herramienta. Dicha protección también permite 3 notificaciones push por conversación por minuto, 10 por host por minuto y 30 por host por hora. La notificación push que supondría la número 31 en una hora se convierte en una única notificación de resumen para ese host, y el host no envía más hasta pasada una hora. Siempre se muestra una tarjeta.
403 caller-refused
El teléfono indica que la respuesta o el mensaje se rechazaron, y el motivo del durable agent es 403 caller-refused.
La comprobación de descendientes del durable agent rechazó al emisor de la llamada. Rechaza al propio durable agent, a cualquier proceso iniciado por el durable agent y a cualquier emisor que no pueda distinguir de ellos. Collie queda del lado del durable agent cuando este, o una herramienta que haya ejecutado, inició el proceso de Collie y dicho proceso sigue siendo su elemento secundario. Inicie Collie desde fuera del durable agent y vuelva a intentarlo.
Reintentar y una respuesta que podría haberse aplicado
Aparece «No es seguro que la respuesta haya llegado» con un botón Reintentar y, tras pulsarlo, «Puede que ya se haya aplicado. Compruebe el chat».
Un tiempo de espera agotado, una conexión interrumpida o un error 5xx tras la salida de la respuesta implican que esta podría haberse recibido. Reintentar envía el mismo id de petición, por lo que el durable agent responde replayed y nunca resuelve la pregunta dos veces. Si la pregunta ya está cerrada, es posible que el primer intento la haya cerrado, por lo que el teléfono indica comprobar el chat. Un envío, una detención y una pulsación de botón indican lo mismo con sus propios términos.
El durable agent rechazó el token
La barra de conexión indica «El durable agent rechazó el token. Compruebe COLLIE_DURABLE_TOKEN en este par» y el motivo es token-refused.
El durable agent respondió 401 o 403 al token. La causa más habitual es una rotación en la que una de las partes cambió primero. El texto del teléfono menciona COLLIE_DURABLE_TOKEN incluso para una entrada de sources.json: debe interpretarse como el token de la entrada. Proporcione el nuevo token al durable agent antes de reiniciar Collie. En Tokens se detallan los pasos de rotación. Un 403 también puede proceder de un proxy de acceso situado frente al durable agent.
Un cambio a Inaccesible que requiere dos lecturas
Se observa que un durable agent permanece en Listo durante una lectura fallida y luego cambia a Inaccesible.
Una lectura fallida tras una correcta mantiene la última disposición para ese sondeo. El segundo fallo consecutivo hace cambiar el estado del durable agent. Un token rechazado sigue la misma regla. Una ruta de socket que no supera la comprobación de privacidad es la única excepción: se muestra de inmediato.
A través de https, si un durable agent está caído o rechaza el token, se le consulta como máximo una vez cada 10 s, ya que cada intento supone una petición facturada. A través de un socket, el intervalo mínimo entre dos lecturas de un durable agent caído es de 250 ms.
En una crew
Un durable agent en un miembro de una crew se muestra en el teléfono del lead, por lo que el lead necesita reconocer qué es un durable agent.
Un lead anterior a 1.21.0 lista las conversaciones del durable agent sin la tarjeta de preguntas, y su pestaña Terminal sondea una conversación que carece de terminal. Nada en el miembro soluciona esto. El propio miembro lo indica: collie doctor advierte en durable-lead, y el registro añade una línea, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead, una vez por cada versión de la que recibe información. Actualice el lead.
durable-lead | lo que indica |
|---|---|
| omitido, no hay crew | Esta máquina no pertenece a una crew, por lo que no hay lead |
| omitido, lead | Esta máquina es el lead y muestra sus propios paneles |
| omitido, sin versión | El lead no indicó ninguna versión: una compilación de desarrollo, una actualización en curso o ninguna llamada desde que se inició el bridge |
| advertencia | El lead ejecuta una versión inferior a 1.21.0 |
| verde | El lead es 1.21.0 o posterior |
Un miembro anterior al lead presenta el fallo inverso. El teléfono indica «Esta máquina ejecuta una versión más antigua de Collie y no puede recibir respuestas aquí. Actualícela o responda en el durable agent». Actualice dicho miembro.