zhu-hailin/ssh-operator

SSH Operator

Betreibe entfernte Linux-Server über SSH/SFTP, um Anwendungen zu deployen, Docker-Container zu verwalten und den Laufzeitzustand zu überprüfen. Unterstützt Projekte mit mehreren Dateien/Ordnern und ist an die Baota-Panel-Umgebung angepasst.

Wann aufrufen

• Der Benutzer bittet darum, Code auf einem Server zu deployen, zu veröffentlichen oder freizugeben.
• Der Benutzer bittet darum, einen Remote-Dienst neu zu starten, neu zu bauen oder zu aktualisieren.
• Der Benutzer bittet darum, Dateien oder ganze Ordner auf einen Remote-Host hochzuladen.
• Der Benutzer bittet darum, Remote-Protokolle anzuzeigen oder den Servicestatus zu überprüfen.
• Der Benutzer bittet darum, Befehle auszuführen oder Probleme auf einem Remote-Server zu diagnostizieren.
• Der Benutzer bittet darum, Remote-Website-/Blog-Quelldateien zu bearbeiten.
• Der Benutzer bittet darum, einen Blogbeitrag zu veröffentlichen oder die Veröffentlichungs-API einer Blogplattform zu erkennen.
• Der Benutzer erwähnt Baota / 宝塔-Panel, /www/wwwroot/ oder chinesisches Cloud-VPS-Hosting.

Fähigkeiten

• Verbinde zu Remote-Hosts über SSH (passwort- oder schlüsselbasierte Authentifizierung).
• Lade Dateien hoch/herunter und lade Ordner rekursiv über SFTP hoch.
• Führe Shell-Befehle aus und stream die Ausgabe.
• Verwalte Docker- und Docker-Compose-Workloads.
• Überprüfe Servicezustand, Logs, Festplattennutzung und Prozessstatus.
• Validiere, dass bereitgestellte Änderungen aktiv sind (Checksummen, Prozessneustarts, HTTP-Health-Checks).
• Passe Befehle an das Baota-Panel-Verzeichnislayout und Nginx-Reverse-Proxy-Setups an.
• Bearbeite Remote-Website-/Blog-Quelldateien direkt über SSH.
• Erkenne Blog-Veröffentlichungs-APIs (WordPress, Ghost, Halo) und veröffentliche Markdown-Beiträge über Python-Skripte.

Erforderliche Eingaben

Sammle diese vom Benutzer oder der Umgebung, bevor du handelst:

1. HOST — Server-IP oder Hostname.
2. PORT — SSH-Port (Standard 22).
3. USER — SSH-Benutzername.
4. AUTH — Passwort oder Pfad zum privaten Schlüssel. Bevorzuge Schlüssel; hinterlege Geheimnisse niemals in committed Dateien.
5. REMOTE_ROOT — Basisprojektpfad auf dem Server (z. B. /www/wwwroot/ai-interviewer).
6. FILES_TO_UPLOAD — Liste von local_path -> remote_relative_path-Paaren, einschließlich ganzer Ordner.
7. COMMANDS — Die auszuführenden Deployment- oder Diagnosebefehle.

Deployment von mehreren Dateien / Ordnern

Die meisten realen Projekte sind nicht nur eine einzelne Datei. Verwende einen dieser Ansätze:

Option 1: Verwende die bereitgestellte Skriptvorlage

Kopiere scripts/deploy-folder.py in das Projekt-Repository, konfiguriere die FILES_TO_UPLOAD-Liste und führe es aus. Es handhabt rekursive Ordner-Uploads und bewahrt relative Pfade.

Für Unix-ähnliche lokale Umgebungen bietet scripts/deploy-rsync.sh eine inkrementelle rsync-basierte Alternative mit sinnvollen Ausschlüssen.

Option 2: Agent-gesteuertes SFTP

Wenn der Agent über SFTP/SSH-Tools verfügt:

1. Stelle die SSH-Sitzung her.
2. Durchlaufe für jeden geänderten Ordner dessen Inhalt und lade die Dateien einzeln hoch, wobei der entfernte Verzeichnisbaum neu erstellt wird.
3. Lade für jede geänderte Datei auf den passenden entfernten relativen Pfad hoch.
4. Führe Deployment-Befehle aus und überprüfe.

Option 3: Einmaliges Tarball

Für große Projekte empfiehlt es sich, lokal zu packen und remote zu extrahieren:

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

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

Skriptbibliothek

Einsatzbereite Automatisierungsskripte. Python-Skripte teilen scripts/_ssh.py für Verbindungs-/Konfigurationsladung und lesen Anmeldedaten aus einer .env-Datei (siehe .env.example). Kopiere das Skript zusammen mit _ssh.py in dein Projekt.

Skript	Zweck
scripts/_ssh.py	Geteiltes Hilfsprogramm: .env-Konfiguration laden und eine SSH/SFTP-Verbindung öffnen.
scripts/deploy-folder.py	Rekursiver SFTP-Upload von Dateien und Ordnern, dann Post-Deployment-Befehle ausführen.
scripts/deploy-rsync.sh	Inkrementelles rsync-Deployment mit üblichen Ausschlüssen.
scripts/blog_api_probe.py	Erkenne gängige Blog-Veröffentlichungs-APIs (WordPress, Ghost, Halo).
scripts/publish_post.py	Veröffentliche eine Markdown-Datei über die REST-API in WordPress oder Ghost.
scripts/backup_before_deploy.py	Sichere Code, Nginx-Konfigurationen, Docker-Volumes und SQLite vor dem Deployment.
scripts/server_health.py	Sammle CPU-, Speicher-, Festplatten-, Docker-, Nginx- und HTTP-Health-Status.
scripts/log_collector.py	Hole Docker-, Nginx- und Baota-Logs zur Analyse in lokale Dateien.
scripts/nginx_manager.py	Lese/sichere/bearbeite Baota-Nginx-Site-Konfigurationen und lade sie sicher neu.
scripts/bt_panel.py	Installiere Baota, zeige Panel-Informationen an, lade Nginx neu und überprüfe den Docker-Status über SSH.

Python-Abhängigkeiten sind in requirements.txt aufgelistet.

Standard-Deployment-Workflow

1. Stelle die SSH-Sitzung her mit den bereitgestellten Anmeldedaten und einem angemessenen Timeout (≥20 s).
2. Erstelle ein Backup, bevor du etwas änderst — führe scripts/backup_before_deploy.py oder ein Äquivalent aus.
3. Stelle sicher, dass REMOTE_ROOT existiert (mkdir -p).
4. Lade Dateien/Ordner hoch, wobei relative Pfade unter REMOTE_ROOT erhalten bleiben.
5. Führe die Befehle der Reihe nach aus; bevorzuge das Verketten abhängiger Befehle mit &&.
6. Warte auf das Starten der Dienste (verwende sleep + docker-compose ps oder einen Health-Endpunkt).
7. Überprüfe, ob der neue Code live ist (grep im Container, Aufruf von /health, Log-Prüfung).
8. Berichte die Ergebnisse präzise: was geändert wurde, ob die Dienste gesund sind und etwaige Fehler.

Häufige Befehlsmuster

# Einen Dienst stoppen, neu bauen und neu starten
cd ${REMOTE_ROOT} && docker-compose stop backend \
  && docker-compose rm -f backend \
  && docker-compose build backend \
  && docker-compose up -d backend

# Servicestatus prüfen
cd ${REMOTE_ROOT} && docker-compose ps

# Aktuelle Logs anzeigen
cd ${REMOTE_ROOT} && docker-compose logs --tail=50 backend

# Code im laufenden Container überprüfen
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py

# Festplattenbereinigung
docker system prune -a -f

Baota / 宝塔 Panel-Anpassung

Vollständige Betriebsanleitung in references/baota.md und das bt CLI-Spickzettel in references/bt-commands.md. Die wichtigsten Punkte:

• Offizielle Website: https://www.bt.cn; Installationsskript unter https://www.bt.cn/new/download.html.
• Standard-Projektverzeichnis: /www/wwwroot/<site-name>.
• Verwende scripts/bt_panel.py, um Baota zu installieren, Panel-Informationen anzuzeigen oder Nginx über SSH neu zu laden.
• Verwende Docker Compose im Projektverzeichnis; verwalte Container über die CLI oder das Baota Docker-Plugin.
• Füge für Node/Python-Frontends eine Baota-Site hinzu und verwende scripts/nginx_manager.py, um Nginx-Reverse-Proxy-Standorte zu 127.0.0.1:3000 hinzuzufügen.
• Leite /api/ in Nginx an den Backend-Container weiter (z. B. 127.0.0.1:8000).
• Öffne Ports sowohl in der Baota-Firewall als auch in der Sicherheitsgruppe des Cloud-Anbieters.
• Setze hoch nummerierte Ports nicht direkt dem Internet aus; verwende Nginx auf 80/443.

Falls etwas schief geht, konsultiere references/troubleshooting.md.

Sicherheitsregeln

• Committe niemals Geheimnisse. Speichere PASS oder Schlüsselpfade in Umgebungsvariablen, .env-Dateien, die von git ausgeschlossen sind, oder einem Secrets-Manager.
• Bevorzuge explizite Dateilisten anstelle von breiten Uploads, um das Überschreiben unerwarteter Dateien zu vermeiden.
• Führe zuerst zerstörungsfreie Prüfungen durch, wenn du diagnostizierst (Logs, ps, df), bevor du Dienste neu startest.
• Vermeide git push --force oder destruktives rm -rf, es sei denn, der Benutzer fordert es ausdrücklich an.
• Bestätige riskante Aktionen (Datenbankmigrationen, dienstweite Neustarts, destruktive Löschungen) nach Möglichkeit mit dem Benutzer.
• Räume temporäre Dateien auf (z. B. /tmp/deploy.tar.gz) nach dem Deployment.

Plattformübergreifende Hinweise

• Diese Fähigkeit setzt einen Linux-Remote-Host und eine lokale Umgebung mit einem SSH-Client oder einer Python-Bibliothek wie paramiko voraus.
• Auf Windows-lokalen Hosts müssen Pfade möglicherweise normalisiert werden; setze Remote-Pfade in Befehlen immer in Anführungszeichen.
• Auf Agenten ohne direkte SSH-Tools verwende als Fallback: (1) Generiere ein Deployment-Skript, das der Benutzer ausführen kann, oder (2) verwende das von der Plattform bereitgestellte Terminal-/Remote-Ausführungstool.
• Für maximale Portabilität zwischen Claude Code, Codex, TRAE und Cursor halte die Haupt-SKILL.md unter 500 Zeilen und verschiebe detaillierte Referenzen in references/.

Beispiel

Benutzer: „Stelle den neuesten Backend-Fix auf meinem Baota-Server bereit."

Agent:

1. Frage nach oder lade HOST, PORT, USER, Authentifizierung und REMOTE_ROOT.
2. Frage, welche Dateien geändert wurden, oder leite dies aus den letzten Bearbeitungen ab.
3. Lade die geänderten Dateien/Ordner in ihre entfernten Pfade unter REMOTE_ROOT hoch.
4. Baue die betroffenen Docker-Dienste neu und starte sie neu.
5. Überprüfe docker-compose ps und die letzten Logs, um die Gesundheit zu bestätigen.
6. Antworte mit einer kurzen Zusammenfassung der Uploads und des Servicestatus.