zhu-hailin/ssh-operator

SSH Operator

Opérez des serveurs Linux distants via SSH/SFTP pour déployer des applications, gérer des conteneurs Docker et inspecter l'état d'exécution. Prend en charge les projets multi-fichiers / multi-dossiers et est adapté aux environnements du panneau Baota (宝塔).

Quand l'invoquer

• L'utilisateur demande de déployer, publier ou mettre en production du code sur un serveur.
• L'utilisateur demande de redémarrer, reconstruire ou mettre à jour un service distant.
• L'utilisateur demande de télécharger des fichiers ou des dossiers entiers sur un hôte distant.
• L'utilisateur demande de consulter les logs distants ou de vérifier l'état d'un service.
• L'utilisateur demande d'exécuter des commandes ou de diagnostiquer des problèmes sur un serveur distant.
• L'utilisateur demande de modifier des fichiers sources d'un site web/blog distant.
• L'utilisateur demande de publier un article de blog ou de détecter une API de publication d'une plateforme de blog.
• L'utilisateur mentionne le panneau Baota / 宝塔, /www/wwwroot/, ou un hébergement VPS cloud chinois.

Capacités

• Se connecter à des hôtes distants via SSH (authentification par mot de passe ou clé).
• Télécharger/téléverser des fichiers et des dossiers de manière récursive via SFTP.
• Exécuter des commandes shell et diffuser leur sortie.
• Gérer des charges de travail Docker et docker-compose.
• Inspecter l'état des services, logs, utilisation du disque et état des processus.
• Valider que les modifications déployées sont actives (sommes de contrôle, redémarrages de processus, vérifications de santé HTTP).
• Adapter les commandes à la structure de répertoires du panneau Baota et aux configurations de proxy inverse Nginx.
• Modifier directement les fichiers sources d'un site web/blog distant via SSH.
• Détecter les API de publication de blog (WordPress, Ghost, Halo) et publier des articles Markdown via des scripts Python.

Entrées requises

Collectez ces informations auprès de l'utilisateur ou de l'environnement avant d'agir :

1. HOST — IP ou nom d'hôte du serveur.
2. PORT — Port SSH (par défaut 22).
3. USER — Nom d'utilisateur SSH.
4. AUTH — Mot de passe ou chemin vers une clé privée. Privilégiez les clés ; ne codez jamais de secrets en dur dans les fichiers versionnés.
5. REMOTE_ROOT — Chemin de base du projet sur le serveur (ex. /www/wwwroot/ai-interviewer).
6. FILES_TO_UPLOAD — Liste de paires local_path -> remote_relative_path, incluant des dossiers entiers.
7. COMMANDS — Les commandes de déploiement ou de diagnostic à exécuter.

Déploiement multi-fichier / multi-dossier

La plupart des projets réels ne se limitent pas à un seul fichier. Utilisez l'une de ces approches :

Option 1 : Utiliser le modèle de script fourni

Copiez scripts/deploy-folder.py dans le dépôt du projet, configurez la liste FILES_TO_UPLOAD et exécutez-le. Il gère le téléversement récursif des dossiers et préserve les chemins relatifs.

Pour les environnements locaux de type Unix, scripts/deploy-rsync.sh fournit une alternative incrémentielle basée sur rsync avec des exclusions pertinentes.

Option 2 : SFTP piloté par l'agent

Lorsque l'agent dispose d'outils SFTP/SSH :

1. Établissez la session SSH.
2. Pour chaque dossier modifié, parcourez son contenu et téléversez les fichiers individuellement, en recréant l'arborescence distante.
3. Pour chaque fichier modifié, téléversez-le vers le chemin relatif distant correspondant.
4. Exécutez les commandes de déploiement et vérifiez.

Option 3 : Archive unique

Pour les grands projets, privilégiez l'empaquetage local et l'extraction distante :

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

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

Bibliothèque de scripts

Scripts d'automatisation prêts à l'emploi. Les scripts Python partagent scripts/_ssh.py pour le chargement de la connexion/config et lisent les identifiants depuis un fichier .env (voir .env.example). Copiez le script avec _ssh.py dans votre projet.

Script	Objectif
scripts/_ssh.py	Assistant partagé : charger la config .env et ouvrir une connexion SSH/SFTP.
scripts/deploy-folder.py	Téléversement SFTP récursif de fichiers et dossiers, puis exécution de commandes post-déploiement.
scripts/deploy-rsync.sh	Déploiement incrémental rsync avec exclusions courantes.
scripts/blog_api_probe.py	Détecter les API de publication de blog courantes (WordPress, Ghost, Halo).
scripts/publish_post.py	Publier un fichier Markdown vers WordPress ou Ghost via l'API REST.
scripts/backup_before_deploy.py	Sauvegarder le code, les configs Nginx, les volumes Docker et SQLite avant le déploiement.
scripts/server_health.py	Collecter l'état CPU, mémoire, disque, Docker, Nginx et santé HTTP.
scripts/log_collector.py	Récupérer les logs Docker, Nginx et Baota dans des fichiers locaux pour analyse.
scripts/nginx_manager.py	Lire/sauvegarder/modifier les configs de sites Nginx de Baota et recharger en toute sécurité.
scripts/bt_panel.py	Installer Baota, afficher les infos du panneau, recharger Nginx et vérifier l'état Docker via SSH.

Les dépendances Python sont listées dans requirements.txt.

Workflow de déploiement standard

1. Établir la session SSH avec les identifiants fournis et un temps d'attente raisonnable (≥20 s).
2. Sauvegarder avant toute modification — exécutez scripts/backup_before_deploy.py ou équivalent.
3. Assurer que REMOTE_ROOT existe (mkdir -p).
4. Téléverser les fichiers/dossiers en conservant les chemins relatifs sous REMOTE_ROOT.
5. Exécuter les commandes dans l'ordre ; préférez enchaîner les commandes dépendantes avec &&.
6. Attendre que les services démarrent (utilisez sleep + docker-compose ps ou un point de terminaison santé).
7. Vérifier que le nouveau code est actif (grep dans le conteneur, appel à /health, consulter les logs).
8. Rendre compte des résultats de manière concise : ce qui a changé, si les services sont sains, et toute erreur.

Modèles de commandes courants

# Arrêter, reconstruire et redémarrer un service
cd ${REMOTE_ROOT} && docker-compose stop backend \
  && docker-compose rm -f backend \
  && docker-compose build backend \
  && docker-compose up -d backend

# Vérifier l'état du service
cd ${REMOTE_ROOT} && docker-compose ps

# Afficher les logs récents
cd ${REMOTE_ROOT} && docker-compose logs --tail=50 backend

# Vérifier le code dans le conteneur en cours d'exécution
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py

# Nettoyage du disque
docker system prune -a -f

Adaptation au panneau Baota / 宝塔

Consultez references/baota.md pour le guide opérationnel complet et references/bt-commands.md pour l'aide-mémoire de la CLI bt. Points clés :

• Site officiel : https://www.bt.cn ; script d'installation sur https://www.bt.cn/new/download.html.
• Racine du projet par défaut : /www/wwwroot/<nom-du-site>.
• Utilisez scripts/bt_panel.py pour installer Baota, afficher les infos du panneau ou recharger Nginx via SSH.
• Utilisez Docker Compose dans le répertoire du projet ; gérez les conteneurs via CLI ou le plugin Docker de Baota.
• Pour les fronts Node/Python, ajoutez un site Baota et utilisez scripts/nginx_manager.py pour ajouter des emplacements de proxy inverse Nginx vers 127.0.0.1:3000.
• Routez /api/ vers le conteneur backend (ex. 127.0.0.1:8000) dans Nginx.
• Ouvrez les ports à la fois dans le pare-feu Baota et le groupe de sécurité du fournisseur cloud.
• N'exposez pas directement les ports numérotés élevés sur Internet ; utilisez Nginx sur 80/443.

En cas de problème, consultez references/troubleshooting.md.

Règles de sécurité

• Ne jamais versionner de secrets. Stockez PASS ou les chemins de clé dans des variables d'environnement, des fichiers .env exclus de git, ou un gestionnaire de secrets.
• Préférez des listes de fichiers explicites plutôt que des téléversements larges pour éviter d'écraser des fichiers inattendus.
• Exécutez d'abord des vérifications non destructives lors du diagnostic (logs, ps, df) avant de redémarrer les services.
• Évitez git push --force ou les rm -rf destructeurs sauf demande explicite de l'utilisateur.
• Confirmez les actions risquées (migrations de base de données, redémarrages de services, suppressions destructrices) avec l'utilisateur dans la mesure du possible.
• Nettoyez les fichiers temporaires (ex. /tmp/deploy.tar.gz) après le déploiement.

Remarques multi-plateforme

• Cette compétence suppose un hôte distant Linux et un environnement local avec un client SSH ou une bibliothèque Python telle que paramiko.
• Sous Windows local, les chemins peuvent nécessiter une normalisation ; mettez toujours les chemins distants entre guillemets dans les commandes.
• Sur les agents sans outils SSH directs, repliez-vous sur : (1) génération d'un script de déploiement que l'utilisateur exécutera, ou (2) utilisation de l'outil terminal/d'exécution distant fourni par la plateforme.
• Pour une portabilité maximale entre Claude Code, Codex, TRAE et Cursor, gardez le SKILL.md principal sous 500 lignes et déplacez les références détaillées dans references/.

Exemple

Utilisateur : "Déploie le dernier correctif backend sur mon serveur Baota."

Agent :

1. Demander ou charger HOST, PORT, USER, l'authentification et REMOTE_ROOT.
2. Demander quels fichiers ont changé, ou les déduire des modifications récentes.
3. Téléverser les fichiers/dossiers modifiés vers leurs chemins distants sous REMOTE_ROOT.
4. Reconstruire et redémarrer le(s) service(s) Docker concerné(s).
5. Vérifier docker-compose ps et consulter les logs pour confirmer l'état de santé.
6. Répondre avec un court résumé des téléversements et de l'état du service.