SSH 远程操作 Linux 服务器（通用版）

从本机通过 SSH（22/TCP，paramiko） 远程驱动任意内网 Linux 服务器：
跑 shell、sudo 提权、SFTP 传文件、查状态。服务器信息不写死在代码里，由使用者配置。

依赖：本机 pip install paramiko（脚本缺失时会自动提示）。

第 0 步：检查配置（每次会话首次使用时做）

检查本技能 scripts/config.json 是否存在：

• 不存在 → 向用户要信息：服务器 IP、SSH 用户名、密码（可用 AskUserQuestion）；
  如 sudo 密码与登录密码不同，一并向用户要。然后参照 scripts/config.example.json
  写入 scripts/config.json。
• 已存在但用户提到的是另一台服务器 → 临时用环境变量覆盖，不改配置：
  set SSH_HOST=x.x.x.x&& set SSH_USER=xxx&& set SSH_PASSWORD=xxx&& python scripts/run_remote.py ...

支持的覆盖环境变量：SSH_HOST / SSH_PORT / SSH_USER / SSH_PASSWORD（或 SSH_PASS）/
SSH_SUDO_PASSWORD / SSH_KEY_FILE / SSH_CONFIG（指定其它配置文件路径）。

目标服务器前置条件：SSH 服务在跑（绝大多数 Linux 默认开启，systemctl status ssh），
防火墙放行 22/TCP。公钥认证可选：把 key_file 填进配置即可（优先于密码）。

第 1 步：连通性自检

python scripts/check_connection.py

输出主机名/用户/发行版/时间并打印 [OK] SSH 通道可用 即成功。失败时按提示排查
（超时→网络/防火墙；Permission denied→账号密码；详见 reference.md 排查表）。

第 2 步：执行命令（run_remote.py）

python scripts/run_remote.py cmd.sh           # 执行 .sh 文件（推荐，多行脚本）
python scripts/run_remote.py -c "hostname"    # 单条命令
type cmd.sh | python scripts/run_remote.py    # stdin
python scripts/run_remote.py -c "whoami" --sudo   # 以 root 执行

规则：

• 永远把命令写进 .sh 文件再传路径，不要在 bash 命令行内联复杂远程命令
  （git-bash 会吞 $、{{}} 等，见 reference.md 坑表）。
• --sudo 通过 sudo -S 从 stdin 喂密码（密码不出现在远端进程列表里）；
  sudo 密码默认取登录密码，可在配置里单独设 sudo_password。
• 以 RC + stdout 判定成败；stderr 的 sudo/进度噪音已过滤。
• 长任务要脱离会话：命令里加 nohup ... >log 2>&1 & 或 setsid（见 reference.md）。

第 3 步：文件传输（SFTP，MD5 双向校验）

python scripts/push_file.py 本地文件 /远端/路径/文件     # 上传
python scripts/pull_file.py /远端/路径/文件 本地文件     # 下载

• 单文件传输，自动建远端/本地父目录，两端 MD5 比对一致才报 [ok]。
• git-bash 调用时：以 / 开头的远端路径参数可能被 MSYS 改写成 Windows 路径，
  导致误报 PermissionError / “远端文件不存在”。调用这两条命令请前缀
  MSYS_NO_PATHCONV=1（或远端路径写成 //tmp/... 双斜杠）。
• 目录请先自行打包成 zip/tar 再传，到远端再解开（见 reference.md 配方）。
• 二进制安全：脚本内部全程二进制模式读写，勿用文本模式预处理待传文件
  （Windows 文本模式会把 \n 变 \r\n，导致 MD5 基准失真）。

安全红线

• config.json 含明文密码——分享/发布本技能时必须剔除，只留 config.example.json。
• 首次连接采用 TOFU（自动接受主机指纹）；高安全环境请预先核对指纹后改用严格模式。
• 远端破坏性操作（rm、重启服务）前先确认影响面：共享 VM 上可能有别人的服务，
  重启整机/容器引擎类命令要特别谨慎，优先精确操作单个服务。
• sudo 密码经 stdin 传入，不落远端命令行；但仍建议目标机逐步改用密钥认证并收紧弱密码。

更多

机制细节、坑速查、故障排查表、常用配方见 reference.md。