zhu-hailin/ssh-operator

SSH Operator

Opera servidores Linux remotos a través de SSH/SFTP para desplegar aplicaciones, gestionar contenedores Docker e inspeccionar el estado del runtime. Soporta proyectos multi-archivo / multi-carpeta y está adaptado para entornos del panel Baota (宝塔).

Cuándo invocar

• El usuario pide desplegar, publicar o lanzar código a un servidor.
• El usuario pide reiniciar, reconstruir o actualizar un servicio remoto.
• El usuario pide subir archivos o carpetas completas a un host remoto.
• El usuario pide ver logs remotos o verificar el estado de un servicio.
• El usuario pide ejecutar comandos o diagnosticar problemas en un servidor remoto.
• El usuario pide editar archivos fuente de un sitio web/blog remoto.
• El usuario pide publicar una entrada de blog o detectar la API de publicación de una plataforma de blog.
• El usuario menciona el panel Baota / 宝塔, /www/wwwroot/, o alojamiento VPS en la nube china.

Capacidades

• Conectarse a hosts remotos mediante SSH (autenticación por contraseña o clave).
• Subir/descargar archivos y subir carpetas de forma recursiva mediante SFTP.
• Ejecutar comandos de shell y transmitir la salida.
• Gestionar cargas de trabajo de Docker y docker-compose.
• Inspeccionar la salud del servicio, logs, uso de disco y estado de procesos.
• Validar que los cambios desplegados están activos (checksums, reinicios de proceso, comprobaciones de salud HTTP).
• Adaptar comandos para la estructura de directorios del panel Baota y configuraciones de proxy inverso Nginx.
• Editar archivos fuente de sitios web/blogs remotos directamente sobre SSH.
• Detectar APIs de publicación de blogs (WordPress, Ghost, Halo) y publicar entradas Markdown mediante scripts Python.

Entradas requeridas

Recopila estas del usuario o del entorno antes de actuar:

1. HOST — IP del servidor o nombre de host.
2. PORT — Puerto SSH (por defecto 22).
3. USER — Nombre de usuario SSH.
4. AUTH — contraseña o ruta de clave privada. Preferir claves; nunca codificar secretos en archivos comprometidos.
5. REMOTE_ROOT — ruta base del proyecto en el servidor (p. ej. /www/wwwroot/ai-interviewer).
6. FILES_TO_UPLOAD — lista de pares local_path -> remote_relative_path, incluyendo carpetas completas.
7. COMMANDS — los comandos de despliegue o diagnóstico a ejecutar.

Despliegue multi-archivo / multi-carpeta

La mayoría de los proyectos reales no son un solo archivo. Usa uno de estos enfoques:

Opción 1: Usar la plantilla de script proporcionada

Copia scripts/deploy-folder.py en el repositorio del proyecto, configura la lista FILES_TO_UPLOAD y ejecútalo. Maneja subidas recursivas de carpetas y preserva rutas relativas.

Para entornos locales tipo Unix, scripts/deploy-rsync.sh proporciona una alternativa incremental basada en rsync con exclusiones sensatas.

Opción 2: SFTP impulsado por el agente

Cuando el agente dispone de herramientas SFTP/SSH:

1. Establecer la sesión SSH.
2. Para cada carpeta modificada, recorrer su contenido y subir archivos individualmente, recreando el árbol de directorios remoto.
3. Para cada archivo modificado, subirlo a la ruta relativa remota correspondiente.
4. Ejecutar comandos de despliegue y verificar.

Opción 3: Tarball de una sola vez

Para proyectos grandes, es preferible empaquetar localmente y extraer remotamente:

# Local
 tar czf deploy.tar.gz backend/app frontend/.next docker-compose.yml .env.production
 scp deploy.tar.gz user@host:/tmp/

# Remoto
 ssh user@host "cd /www/wwwroot/project && tar xzf /tmp/deploy.tar.gz && docker-compose up -d --build"

Biblioteca de scripts

Scripts de automatización listos para usar. Los scripts Python comparten scripts/_ssh.py para carga de conexión/configuración y leen credenciales de un archivo .env (ver .env.example). Copia el script junto con _ssh.py en tu proyecto.

Script	Propósito
scripts/_ssh.py	Ayudante compartido: cargar configuración .env y abrir una conexión SSH/SFTP.
scripts/deploy-folder.py	Subida SFTP recursiva de archivos y carpetas, luego ejecutar comandos post-despliegue.
scripts/deploy-rsync.sh	Despliegue incremental rsync con exclusiones comunes.
scripts/blog_api_probe.py	Detectar APIs de publicación de blogs comunes (WordPress, Ghost, Halo).
scripts/publish_post.py	Publicar un archivo Markdown en WordPress o Ghost mediante API REST.
scripts/backup_before_deploy.py	Hacer copia de seguridad del código, configuraciones Nginx, volúmenes Docker y SQLite antes de desplegar.
scripts/server_health.py	Recopilar estado de CPU, memoria, disco, Docker, Nginx y salud HTTP.
scripts/log_collector.py	Obtener logs de Docker, Nginx y Baota a archivos locales para análisis.
scripts/nginx_manager.py	Leer/copiar/editar configuraciones de sitios Nginx de Baota y recargar de forma segura.
scripts/bt_panel.py	Instalar Baota, ver información del panel, recargar Nginx y verificar estado de Docker sobre SSH.

Las dependencias Python se enumeran en requirements.txt.

Flujo de trabajo de despliegue estándar

1. Establecer la sesión SSH con las credenciales proporcionadas y un tiempo de espera razonable (≥20 s).
2. Hacer copia de seguridad antes de cambiar nada — ejecutar scripts/backup_before_deploy.py o equivalente.
3. Asegurar que REMOTE_ROOT existe (mkdir -p).
4. Subir archivos/carpetas preservando rutas relativas bajo REMOTE_ROOT.
5. Ejecutar comandos en orden; preferir encadenar comandos dependientes con &&.
6. Esperar a que los servicios se inicien (usar sleep + docker-compose ps o un endpoint de salud).
7. Verificar que el nuevo código está activo (grep dentro del contenedor, acceder a /health, comprobar logs).
8. Informar resultados de forma concisa: qué cambió, si los servicios están saludables y cualquier error.

Patrones de comandos comunes

# Detener, reconstruir y reiniciar un servicio
cd ${REMOTE_ROOT} && docker-compose stop backend \
  && docker-compose rm -f backend \
  && docker-compose build backend \
  && docker-compose up -d backend

# Verificar estado del servicio
cd ${REMOTE_ROOT} && docker-compose ps

# Ver logs recientes
cd ${REMOTE_ROOT} && docker-compose logs --tail=50 backend

# Verificar código dentro del contenedor en ejecución
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py

# Limpieza de disco
docker system prune -a -f

Adaptación para Baota / 宝塔 panel

Consulta references/baota.md para la guía operativa completa y references/bt-commands.md para la hoja de referencia del CLI bt. Puntos clave:

• Sitio oficial: https://www.bt.cn; script de instalación en https://www.bt.cn/new/download.html.
• Raíz de proyecto por defecto: /www/wwwroot/<nombre-sitio>.
• Usar scripts/bt_panel.py para instalar Baota, ver información del panel o recargar Nginx sobre SSH.
• Usar Docker Compose dentro del directorio del proyecto; gestionar contenedores mediante CLI o el plugin Docker de Baota.
• Para frontends Node/Python, añadir un sitio en Baota y usar scripts/nginx_manager.py para añadir ubicaciones de proxy inverso Nginx a 127.0.0.1:3000.
• Enrutar /api/ al contenedor backend (p. ej. 127.0.0.1:8000) en Nginx.
• Abrir puertos tanto en el firewall de Baota como en el grupo de seguridad del proveedor cloud.
• No exponer puertos altos directamente a internet; usar Nginx en 80/443.

Si algo sale mal, consulta references/troubleshooting.md.

Reglas de seguridad

• Nunca comprometer secretos. Almacenar PASS o rutas de clave en variables de entorno, archivos .env excluidos de git, o un gestor de secretos.
• Preferir listas explícitas de archivos sobre subidas amplias para evitar sobrescribir archivos inesperados.
• Ejecutar comprobaciones no destructivas primero al diagnosticar (logs, ps, df) antes de reiniciar servicios.
• Evitar git push --force o rm -rf destructivos a menos que el usuario lo solicite explícitamente.
• Confirmar acciones riesgosas (migraciones de base de datos, reinicios de servicios completos, eliminaciones destructivas) con el usuario cuando sea posible.
• Limpiar archivos temporales (p. ej. /tmp/deploy.tar.gz) después del despliegue.

Notas multiplataforma

• Esta habilidad asume un host remoto Linux y un entorno local con un cliente SSH o una biblioteca Python como paramiko.
• En hosts locales Windows, las rutas pueden necesitar normalización; siempre entrecomillar rutas remotas en los comandos.
• En agentes sin herramientas SSH directas, recurrir a: (1) generar un script de despliegue para que el usuario lo ejecute, o (2) usar la herramienta de terminal/ejecución remota proporcionada por la plataforma.
• Para máxima portabilidad entre Claude Code, Codex, TRAE y Cursor, mantener el SKILL.md principal por debajo de 500 líneas y mover referencias detalladas a references/.

Ejemplo

Usuario: "Despliega la última corrección del backend en mi servidor Baota."

Agente:

1. Preguntar o cargar HOST, PORT, USER, autenticación y REMOTE_ROOT.
2. Preguntar qué archivos cambiaron, o inferirlo de ediciones recientes.
3. Subir los archivos/carpetas modificados a sus rutas remotas bajo REMOTE_ROOT.
4. Reconstruir y reiniciar el(los) servicio(s) Docker afectado(s).
5. Verificar docker-compose ps y revisar logs para confirmar salud.
6. Responder con un breve resumen de las subidas y el estado del servicio.