Instrucciones de uso

Esta guía está dirigida a los operadores: obtener la CLI y el agente del dispositivo, iniciar sesión, añadir un dispositivo, conectarlo y, después, ejecutar un comando remoto y abrir una shell. Los enlaces al final llevan a la consola web, la consola móvil, el agente Android, el emparejamiento y las actualizaciones; sus pasos se describen en esas páginas.

Sustituye las direcciones y los tokens de los ejemplos por los tuyos. Los tokens solo se muestran una vez, al crearlos; no los guardes en el repositorio.

Identidades con nombre y permisos de cuenta. La opción global --profile <name> tiene prioridad sobre REMOTE_CLI_PROFILE. config.toml, las claves privadas, la confianza raíz y las cachés de permisos se guardan en <config_base>/remote-cli/profiles/<name>/. config_base mantiene XDG_CONFIG_HOME, HOME/.config o Windows APPDATA. Los nombres admiten 1–64 letras ASCII, dígitos, puntos, guiones o guiones bajos, salvo . y ... Un perfil con nombre tiene prioridad sobre REMOTE_CLI_CONFIG; sin perfil se mantienen las rutas y el comportamiento de REMOTE_CLI_CONFIG. Inicie sesión por separado en cada perfil y selecciónelo en las llamadas posteriores.

operator set acepta un ID de cuenta o nombre único; los argumentos de dispositivo son IDs. --restricted limita la visibilidad a dispositivos autorizados explícitamente; --unrestricted restaura la visibilidad por rol. Solo superadmin puede cambiar el alcance. Superadmin gestiona roles y permisos; en su ausencia, los admins pueden actuar dentro de su alcance permitido, sin modificar sus propios derechos. operator grant list solo devuelve permisos visibles. Los permisos en la base de datos y los permisos firmados son comprobaciones separadas: cambiarlos no sustituye a seal approve. La creación no admite asignar el alcance de forma atómica. Guarde el token único de operator add y luego ejecute operator set / operator grant set como solicitudes separadas.

Todas las acciones operator admiten -o text|json|xml. JSON utiliza op=list|add|set|grant_list|grant_set|grant_remove. set recibe operator y al menos uno de role / restricted; grant_set recibe operator, device y el booleano obligatorio can_manage. grant_list admite operator opcional; grant_remove recibe operator y device. No combine --json con un subcomando.

remote-cli --profile alice login --server https://exchange.example.com
remote-cli --profile root operator set alice --restricted
remote-cli --profile root operator set alice --role readonly
remote-cli --profile root operator grant list --operator alice -o json
remote-cli --profile root operator grant set alice lab --view
remote-cli --profile root operator grant set alice lab --manage
remote-cli --profile root operator grant remove alice lab
remote-cli --profile root operator set alice --unrestricted
remote-cli --profile root operator --json '{"op":"grant_set","operator":"alice","device":"lab","can_manage":false}' -o json

Solicitudes y salida XML

Compruebe las opciones de la versión instalada con remote-cli --help. --xml y --xml-file añaden entrada XML a las solicitudes --json / --json-file existentes. Las cuatro entradas son excluyentes y proporcionan el cuerpo completo; no las mezcle con las mismas opciones o subcomandos. Las reglas de los argumentos posicionales del dispositivo no cambian. Entrada y salida son independientes; -o text|json|xml usa texto por defecto.

remote-cli device --xml '<request><op>list</op></request>' -o xml
remote-cli exec my-device --xml-file request.xml -o xml

Los elementos sin hijos son cadenas por defecto; con hijos son objetos. Use type="number", type="boolean", type="array" y type="null" para números, booleanos, matrices y null. Las matrices contienen <item>; los objetos vacíos requieren type="object". Use <field name="arbitrary key">value</field> para claves arbitrarias y <request type="object"/> para una solicitud vacía.

<request>
  <command>echo hello</command>
  <timeout_secs type="number">30</timeout_secs>
  <hold type="boolean">false</hold>
  <env><GREETING>hello &amp; welcome</GREETING></env>
</request>

La raíz de salida es <response type="...">, los miembros de objetos son <field name="..." type="..."> y los elementos de matrices <item type="...">. Los tipos son explícitos y el texto se escapa según XML 1.0. Los errores de ejecución devuelven ok=false / error y un código de salida distinto de cero; los errores de sintaxis siguen en stderr.

La salida XML admite device list/update, operator list/add/set/grant, exec, session list/kill, ui, ubus, sensors, net, metrics, preset, audit, browser, incluidas las operaciones de tareas exec. Los demás comandos rechazan explícitamente -o xml; siguen admitiendo solicitudes XML con sus formatos de salida habituales.

Los flujos exec / sensors --live / browser session emiten un documento XML completo por línea; analice cada línea por separado. Los eventos de datos exec contienen stream / encoding=base64 / data; Base64 conserva los bytes originales. Un exec normal termina con su estado de salida. La entrada interactiva de browser session sigue siendo JSON Lines. ui xml sin -o xml conserva el XML original de la jerarquía UI.

Las solicitudes están limitadas a 1 MiB y 64 niveles. Se rechazan campos duplicados, texto mezclado con elementos hijos, DTD y entidades externas. Elija JSON si debe conservar caracteres de control no representables en XML 1.0. La configuración del Agent y el protocolo de red siguen en JSON; XML solo convierte la entrada y salida del CLI.

Obtener remote-cli y remote-agent

Compila desde la raíz del repositorio:

cargo build --release

La CLI es target/release/remote-cli. El mismo comando también genera target/release/remote-agent. Para dispositivos con poco espacio flash, utiliza el perfil que prioriza el tamaño:

cargo build -p agent --no-default-features --profile release-small

El resultado es target/release-small/remote-agent.

En Windows, Linux y macOS también puedes instalar cualquiera de los dos binarios con el script del sitio web; consulta Despliegue multiplataforma. Los comandos siguientes suponen que remote-cli y remote-agent están en PATH; si acabas de compilarlos localmente, utiliza las rutas target/... anteriores.

Si alojas tu propio servicio de retransmisión, sigue primero Desarrollo para iniciar exchange con DATABASE_URL y obtener el token de administrador en el registro de inicio. Para una instancia pública, solicita al administrador un token de operador.

Iniciar sesión

remote-cli login --server http://127.0.0.1:8080 --token '<运维令牌>'

--server acepta http:// o https://. La CLI deduce la dirección WebSocket con el mismo nivel de seguridad: https corresponde a wss y http a ws.

Tras iniciar sesión, la configuración se guarda en:

• Linux / macOS: $XDG_CONFIG_HOME/remote-cli/config.toml, o ~/.config/remote-cli/config.toml si XDG_CONFIG_HOME no está definido.
• Windows: %APPDATA%\remote-cli\config.toml.

El archivo solo contiene dos claves: server y token. Define REMOTE_CLI_CONFIG para usar otra ruta. Los comandos device, exec y shell leen esta configuración sin necesidad de volver a pasar el token.

Añadir un dispositivo

remote-cli device add lab-router --name "实验室路由"

<id> es el identificador del dispositivo: solo admite letras, números, -, _ y ., con un máximo de 64 caracteres. --name es opcional; si se omite, el nombre mostrado coincide con el ID. El token del dispositivo solo aparece esta vez en la salida.

Iniciar el agente

En la máquina que quieres gestionar, inicia el agente con el servidor, el ID del dispositivo y el token recién creado:

remote-agent --server wss://127.0.0.1:8080 --device-id lab-router --token '<设备令牌>'

También puedes proporcionar los tres parámetros mediante REMOTE_SERVER, REMOTE_DEVICE_ID y REMOTE_TOKEN.

--server debe empezar por ws:// o wss://. Si solo especificas el host, como wss://mgmt.example.com, el agente añade /ws/device; si ya hay una ruta, la utiliza sin cambios. Para un exchange local sin TLS, usa ws://127.0.0.1:8080.

Si prefieres no incluir el token en los argumentos del proceso, crea un archivo JSON con las claves server, device_id y token:

{
  "server": "wss://mgmt.example.com",
  "device_id": "lab-router",
  "token": "<设备令牌>"
}

Después ejecuta remote-agent --config /path/to/config.json. Para instalarlo y configurar el inicio automático en sistemas de escritorio, consulta Despliegue multiplataforma.

Los WebSocket de remote-cli y remote-agent consultan los proxies en este orden: HTTPS_PROXY / https_proxy → ALL_PROXY / all_proxy → HTTP_PROXY / http_proxy, y respetan NO_PROXY / no_proxy. Los modos sin interfaz y --ui del agente utilizan la misma ruta de conexión. El proxy debe admitir HTTP CONNECT; SOCKS no está soportado. El ALPN de WSS solo anuncia http/1.1. Para servicios en segundo plano, define las variables en el entorno del servicio; consulta Proxy de salida y mantenimiento de conexiones.

Una vez conectado el dispositivo:

remote-cli device list

La lista muestra su estado de conexión.

Ejecutar un comando remoto

El contenido posterior a -- se entrega al dispositivo y deja de ser interpretado por la CLI local:

remote-cli exec lab-router -- uname -a

La cantidad de argumentos después de -- determina cómo se interpretan en el destino:

• Varios argumentos se transmiten como argv, conservando sus límites, igual que al introducir esos argumentos directamente en el dispositivo. La CLI añade comillas cuando hace falta, siguiendo las reglas de PowerShell para dispositivos Windows.
• Un único argumento se entrega completo a la shell del dispositivo para que lo interprete como una línea de comandos, con tuberías, ;, comodines y variables.

remote-cli exec lab-router -- sh -c 'uname -a; cat /proc/uptime'   # 多个参数，第三个参数完整交给 sh -c
remote-cli exec lab-router -- 'dmesg | tail -20'                    # 一个参数，管道在设备上执行

Atención: con varios argumentos, los * y $VAR que la shell local transmita literalmente, algo habitual en PowerShell, se tratan como texto literal y no se expanden en el destino. Para que el dispositivo los expanda, usa un solo argumento, por ejemplo -- 'ls /etc/*.conf'.

exec activa hold de forma predeterminada: el tiempo límite predeterminado es de 3600 segundos, con un máximo absoluto de 86400. La desconexión del operador solo separa la salida y no termina el trabajo. Usa --timeout para establecer el límite, por ejemplo remote-cli exec lab-router --timeout 120 -- uname -a; --hold-timeout permite cambiar el límite de hold. --no-hold recupera el comportamiento de cancelar al desconectarse el operador, con un límite predeterminado de 60 segundos. Si el comando termina normalmente, su código de salida pasa a ser el de remote-cli.

Consultar y terminar trabajos y liberar sesiones

remote-cli exec-holds lab-router
remote-cli exec-hold-kill lab-router <job_id>
remote-cli exec-hold-tail lab-router <job_id>
remote-cli exec-hold-cat lab-router <job_id>
remote-cli exec-attach lab-router <job_id>
remote-cli sessions lab-router
remote-cli session-kill lab-router <session_id>

exec-holds enumera trabajos exec y descargas, subidas y consultas de directorios en curso. Muestra job_id, kind, status, age_secs, el session_id actual del dispositivo, si existe, y un resumen truncado del comando o la ruta. exec-hold-kill termina el grupo de procesos o cancela la transferencia según el ID del trabajo; tail, cat y attach solo se aplican a trabajos exec.

sessions lee directamente la tabla de rutas de Exchange y muestra count/limit y los identificadores de sesión del dispositivo. session-kill utiliza ese identificador del dispositivo, envía una cancelación y libera inmediatamente el cupo en Exchange, incluso si el dispositivo no responde. Ninguno abre sesiones adicionales ni consume cupos de concurrencia, por lo que sirven para resolver sesiones bloqueadas al alcanzar el límite. Las cuentas de solo lectura no pueden usarlos.

Al agotarse el tiempo de exec se termina todo el grupo de procesos; también hay límites para vaciar la salida y enviar el mensaje final. Cuando alcanza el límite de concurrencia, Exchange recupera primero las rutas que han perdido al operador o superado su plazo y después intenta abrir la nueva sesión. El plazo de exec es su límite real de ejecución más 15 segundos de margen; el de las transferencias es de 3600 segundos más 15 segundos, con otro límite de inactividad de 30 segundos en el dispositivo; el de las demás sesiones es de 24 horas. Un exec con hold no termina por la mera desconexión del operador dentro del plazo: solo se desvincula la sesión de salida. Un session-kill explícito o superar el plazo sí cancela el proceso con hold.

Abrir una shell

remote-cli shell lab-router

Es una sesión PTY en el dispositivo. No utiliza SSH. Al salir de la shell, termina la sesión.

Otros puntos de acceso

• Consola del navegador: Consola web.
• Consola del teléfono: Cliente móvil.
• APK del agente Android: APK independiente de Android.
• Códigos QR, códigos de seis dígitos y cuentas: Inicialización y emparejamiento.
• Actualización de la CLI y el agente: Actualización del propio ejecutable.

Cifrado de extremo a extremo: sesiones selladas

remote-cli exec <设备> -- <命令> y remote-cli shell <设备> utilizan sesiones selladas de extremo a extremo, sin parámetros adicionales. Exchange solo retransmite texto cifrado y no puede ver comandos, salidas ni contenido de terminal. El dispositivo solo confía en la raíz del espacio de trabajo, la clave del superadministrador que se genera automáticamente cuando este inicia sesión, y en las autorizaciones emitidas por ella. El cliente raíz las emite automáticamente a los miembros según su rol. La configuración inicial se explica en Sesiones selladas de extremo a extremo.

Todas las sesiones de dispositivo de la CLI utilizan exclusivamente sellado de extremo a extremo, sin parámetros adicionales. Si falta información sobre las capacidades del dispositivo o falla la negociación sellada, no se utiliza texto en claro. Las conexiones LAN directas y las operaciones de navegador aplican los mismos requisitos de sellado.

Tareas persistentes en segundo plano

Los Agents con tasks ejecutan operaciones o DAG declarativos en el dispositivo. El trabajo continúa al desconectar la consola. Al reconectar se consultan progreso, salida y artefactos. Un reinicio marca el trabajo pendiente como interrupted, sin repetirlo automáticamente.

Crear requiere permisos sellados manage/owner. Los formularios admiten dependencias, condiciones fijas, referencias JSON Pointer a ancestros, política de fallos y hasta cinco reintentos explícitos. Los reintentos pueden repetir efectos; cancelar no los revierte. Web y móvil ofrecen formularios e importación/exportación JSON. Las interfaces locales de escritorio, Android, navegador y LuCI permiten historial, salida, cancelación y eliminación.

Consulte primero el catálogo de operaciones del dispositivo. Prepare los archivos antes de crear la tarea. Valores predeterminados: 30 días, 1000 tareas, 64 MiB totales, 8 MiB de texto por tarea, cuatro pasos paralelos (dos en OpenWrt) y 30 minutos por paso ampliables a 24 horas. Los Agents antiguos no muestran esta entrada.

remote-cli task DEVICE operations
remote-cli task DEVICE create pipeline.json --wait
remote-cli task DEVICE list
remote-cli task DEVICE get TASK_ID
remote-cli task DEVICE logs TASK_ID --offset 0
remote-cli task DEVICE cancel TASK_ID
remote-cli task DEVICE upload ./input.bin
remote-cli task DEVICE download TASK_ID STEP.artifact ./result.json
remote-cli task DEVICE delete TASK_ID

Servicios supervisados

El modo Service de Task supervisa comandos nativos en primer plano con estado deseado persistente, políticas de reinicio, espera exponencial, límites de arranque y recuperación tras reiniciar el Agent. Las definiciones se guardan detenidas por defecto. Detenga y espere antes de editar o eliminar. La autorización caducada o revocada detiene el servicio. Los DAG normales no se repiten. Gestión desde Web, móvil, escritorio y Android; configuración de LuCI mediante Console o CLI. Los Agents de navegador no supervisan procesos del sistema.

Use command.command o command.argv con cwd/env, restart (never/on_failure/always), start_secs, stop_grace_secs, backoff_secs, max_backoff_secs, restart_window_secs y max_starts. El cierre ordenado en Windows requiere stop_command; Unix envía SIGTERM y fuerza el cierre del árbol al vencer el plazo. Configure aparte el inicio del Agent al arrancar. service get devuelve run_id para task get/logs.

remote-cli task DEVICE service put worker.json
remote-cli task DEVICE service list
remote-cli task DEVICE service start worker
remote-cli task DEVICE service get worker
remote-cli task DEVICE service restart worker
remote-cli task DEVICE service stop worker
remote-cli task DEVICE service delete worker
remote-agent task service put worker.json