zhu-hailin/ssh-operator

SSH Operator

Opere servidores Linux remotos via SSH/SFTP para implantar aplicações, gerenciar contêineres Docker e inspecionar o estado de execução. Suporta projetos com vários arquivos e pastas e é adaptado para ambientes com painel Baota (宝塔).

Quando invocar

• O usuário pede para implantar, publicar ou liberar código em um servidor.
• O usuário pede para reiniciar, reconstruir ou atualizar um serviço remoto.
• O usuário pede para enviar arquivos ou pastas inteiras para um host remoto.
• O usuário pede para visualizar logs remotos ou verificar o status de serviços.
• O usuário pede para executar comandos ou diagnosticar problemas em um servidor remoto.
• O usuário pede para editar arquivos fonte remotos de sites/blogs.
• O usuário pede para publicar um post de blog ou detectar a API de publicação de uma plataforma de blog.
• O usuário menciona Baota / 宝塔 panel, /www/wwwroot/, ou hospedagem VPS em nuvem chinesa.

Capacidades

• Conectar-se a hosts remotos via SSH (autenticação por senha ou chave).
• Enviar/baixar arquivos e pastas recursivamente via SFTP.
• Executar comandos shell e transmitir a saída.
• Gerenciar cargas de trabalho Docker e docker-compose.
• Inspecionar saúde de serviços, logs, uso de disco e estado de processos.
• Validar se as alterações implantadas estão ativas (checksums, reinicializações de processos, verificações de saúde HTTP).
• Adaptar comandos para a estrutura de diretórios do painel Baota e configurações de proxy reverso Nginx.
• Editar arquivos fonte remotos de sites/blogs diretamente via SSH.
• Detectar APIs de publicação de blogs (WordPress, Ghost, Halo) e publicar posts Markdown via scripts Python.

Entradas necessárias

Colete estas informações do usuário ou do ambiente antes de agir:

1. HOST — IP ou hostname do servidor.
2. PORT — porta SSH (padrão 22).
3. USER — nome de usuário SSH.
4. AUTH — senha ou caminho da chave privada. Prefira chaves; nunca codifique segredos em arquivos versionados.
5. REMOTE_ROOT — caminho base do projeto no servidor (ex.: /www/wwwroot/ai-interviewer).
6. FILES_TO_UPLOAD — lista de pares caminho_local -> caminho_remoto_relativo, incluindo pastas inteiras.
7. COMMANDS — comandos de implantação ou diagnóstico a serem executados.

Implantação multi-arquivo / multi-pasta

A maioria dos projetos reais não é um único arquivo. Use uma das seguintes abordagens:

Opção 1: Usar o template de script fornecido

Copie scripts/deploy-folder.py para o repositório do projeto, configure a lista FILES_TO_UPLOAD e execute-o. Ele lida com upload recursivo de pastas e preserva caminhos relativos.

Para ambientes locais Unix-like, scripts/deploy-rsync.sh fornece uma alternativa incremental baseada em rsync com exclusões sensatas.

Opção 2: SFTP orientado pelo agente

Quando o agente possui ferramentas SFTP/SSH:

1. Estabeleça a sessão SSH.
2. Para cada pasta alterada, percorra seu conteúdo e envie os arquivos individualmente, recriando a árvore de diretórios remota.
3. Para cada arquivo alterado, envie para o caminho relativo remoto correspondente.
4. Execute os comandos de implantação e verifique.

Opção 3: Tarball único

Para projetos grandes, prefira empacotar localmente e extrair 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 automação prontos para uso. Scripts Python compartilham scripts/_ssh.py para carregamento de conexão/configuração e leem credenciais de um arquivo .env (veja .env.example). Copie o script junto com _ssh.py para o seu projeto.

Script	Propósito
scripts/_ssh.py	Ajudante compartilhado: carregar configuração .env e abrir uma conexão SSH/SFTP.
scripts/deploy-folder.py	Upload SFTP recursivo de arquivos e pastas e execução de comandos pós-implantação.
scripts/deploy-rsync.sh	Implantação incremental com rsync e exclusões comuns.
scripts/blog_api_probe.py	Detectar APIs comuns de publicação de blogs (WordPress, Ghost, Halo).
scripts/publish_post.py	Publicar um arquivo Markdown no WordPress ou Ghost via API REST.
scripts/backup_before_deploy.py	Fazer backup de código, configurações Nginx, volumes Docker e SQLite antes de implantar.
scripts/server_health.py	Coletar status de CPU, memória, disco, Docker, Nginx e saúde HTTP.
scripts/log_collector.py	Coletar logs do Docker, Nginx e Baota para arquivos locais para análise.
scripts/nginx_manager.py	Ler/backup/editar configurações de sites Nginx do Baota e recarregar com segurança.
scripts/bt_panel.py	Instalar Baota, visualizar informações do painel, recarregar Nginx e verificar status do Docker via SSH.

As dependências Python estão listadas em requirements.txt.

Fluxo de trabalho padrão de implantação

1. Estabeleça a sessão SSH com as credenciais fornecidas e um timeout razoável (≥20 s).
2. Faça backup antes de alterar qualquer coisa — execute scripts/backup_before_deploy.py ou equivalente.
3. Certifique-se de que REMOTE_ROOT existe (mkdir -p).
4. Envie arquivos/pastas preservando caminhos relativos sob REMOTE_ROOT.
5. Execute comandos em ordem; prefira encadear comandos dependentes com &&.
6. Aguarde os serviços iniciarem (use sleep + docker-compose ps ou um endpoint de saúde).
7. Verifique se o novo código está ativo (grep dentro do contêiner, acesse /health, verifique logs).
8. Relate os resultados de forma concisa: o que mudou, se os serviços estão saudáveis e quaisquer erros.

Padrões de comando comuns

# Parar, reconstruir e reiniciar um serviço
cd ${REMOTE_ROOT} && docker-compose stop backend \
  && docker-compose rm -f backend \
  && docker-compose build backend \
  && docker-compose up -d backend

# Verificar status do serviço
cd ${REMOTE_ROOT} && docker-compose ps

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

# Verificar código dentro do contêiner em execução
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py

# Limpeza de disco
docker system prune -a -f

Adaptação para Baota / 宝塔 panel

Consulte references/baota.md para o guia operacional completo e references/bt-commands.md para a folha de dicas da CLI bt. Pontos principais:

• Site oficial: https://www.bt.cn; script de instalação em https://www.bt.cn/new/download.html.
• Raiz padrão do projeto: /www/wwwroot/<nome-do-site>.
• Use scripts/bt_panel.py para instalar Baota, visualizar informações do painel ou recarregar Nginx via SSH.
• Use Docker Compose dentro do diretório do projeto; gerencie contêineres via CLI ou plugin Docker do Baota.
• Para frontends Node/Python, adicione um site Baota e use scripts/nginx_manager.py para adicionar locais de proxy reverso Nginx para 127.0.0.1:3000.
• Roteie /api/ para o contêiner backend (ex.: 127.0.0.1:8000) no Nginx.
• Abra portas tanto no firewall do Baota quanto no grupo de segurança do provedor de nuvem.
• Não exponha portas de numeração alta diretamente à internet; use Nginx nas portas 80/443.

Se algo der errado, consulte references/troubleshooting.md.

Regras de segurança

• Nunca submeta segredos. Armazene PASS ou caminhos de chave em variáveis de ambiente, arquivos .env excluídos do git ou em um gerenciador de segredos.
• Prefira listas de arquivos explícitas em vez de uploads amplos para evitar sobrescrever arquivos inesperados.
• Execute verificações não destrutivas primeiro ao diagnosticar (logs, ps, df) antes de reiniciar serviços.
• Evite git push --force ou rm -rf destrutivos a menos que o usuário solicite explicitamente.
• Confirme ações arriscadas (migrações de banco de dados, reinicializações completas de serviços, exclusões destrutivas) com o usuário quando possível.
• Limpe arquivos temporários (ex.: /tmp/deploy.tar.gz) após a implantação.

Notas multiplataforma

• Esta habilidade assume um host remoto Linux e um ambiente local com um cliente SSH ou uma biblioteca Python como paramiko.
• Em hosts locais Windows, caminhos podem precisar de normalização; sempre coloque caminhos remotos entre aspas em comandos.
• Em agentes sem ferramentas SSH diretas, recorra a: (1) gerar um script de implantação para o usuário executar, ou (2) usar a ferramenta de execução remota/terminal fornecida pela plataforma.
• Para máxima portabilidade entre Claude Code, Codex, TRAE e Cursor, mantenha o SKILL.md principal com menos de 500 linhas e mova referências detalhadas para references/.

Exemplo

Usuário: "Implante a correção mais recente do backend no meu servidor Baota."

Agente:

1. Pergunte ou carregue HOST, PORT, USER, autenticação e REMOTE_ROOT.
2. Pergunte quais arquivos mudaram ou infira a partir de edições recentes.
3. Envie os arquivos/pastas alterados para seus caminhos remotos sob REMOTE_ROOT.
4. Reconstrua e reinicie o(s) serviço(s) Docker afetado(s).
5. Verifique docker-compose ps e veja os logs para confirmar a saúde.
6. Responda com um breve resumo dos uploads e do status dos serviços.