remote-server-guide

远程服务指南

一个用于通过 SSH 连接远程服务、执行命令和管理容器的工作流。此技能与工具无关，可帮助你为当前任务选择合适的 SSH 工具，并引导你完成从连接到清理的整个生命周期。

何时使用此技能

• 用户需要连接远程服务（云 VM、本地部署的服务、开发机器等）
• 用户想在远程主机上运行命令
• 用户需要连接远程服务上的 Docker 容器
• 用户想向远程服务传输文件或从中传输文件
• 用户在 SSH 身份验证方面遇到问题

身份验证方法

方法	安全性	便利性	最适用场景
SSH 密钥	最高	高	生产环境、频繁使用
tmux（交互式）	高（密码绝不会暴露给 AI）	中	一次性访问、注重安全的用户
sshpass	中（密码会出现在命令中）	高	快速脚本、可信环境
paramiko/fabric	中	中	Python 自动化

工作流

阶段 1：收集连接详情

连接前，向用户收集以下信息：

1. 主机地址（IP 或主机名）
2. SSH 端口（默认值：22）
3. 用户名（例如 root、ubuntu、user）
4. 身份验证方法：
   • SSH 密钥（推荐）
   • 密码（需要选择工具，参见阶段 2）
5. 跳板主机（可选，用于堡垒机/代理设置）

阶段 2：设置身份验证

SSH 密钥（首选）

ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=no -i <key-path> <user>@<host> -p <port> "echo 'Connection successful'"

密码身份验证

如果用户需要使用密码身份验证，先检测可用工具：

which sshpass >/dev/null 2>&1 && echo "sshpass: available" || echo "sshpass: not found"
python3 -c "import paramiko" 2>/dev/null && echo "paramiko: available" || echo "paramiko: not found"
python3 -c "import fabric" 2>/dev/null && echo "fabric: available" || echo "fabric: not found"
which tmux >/dev/null 2>&1 && echo "tmux: available" || echo "tmux: not found"

如果用户担心密码安全，务必推荐使用 tmux 交互式方式——由用户直接输入密码，AI 绝不会看到密码。

工具选择指南：

场景	推荐工具	原因
注重安全的用户	tmux	密码绝不会暴露给 AI
一次性访问	tmux	无需存储凭据
快速 Shell 脚本	sshpass	简单，无需依赖项
Python 应用	paramiko	控制全面，底层级别更低
部署自动化	fabric	高级 API，代码更简洁
需要 SFTP	paramiko 或 fabric	内置支持
交互式终端	tmux 或 sshpass	原生 TTY 支持

如果没有可用工具，可以提议安装一个：

# tmux (Ubuntu/Debian)
sudo apt-get install -y tmux
# sshpass (Ubuntu/Debian)
sudo apt-get install -y sshpass
# paramiko
pip install paramiko
# fabric
pip install fabric

阶段 3：测试连接

继续之前，先验证连接是否正常。

sshpass：

sshpass -p '<password>' ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=no <user>@<host> -p <port> "echo 'Connection successful'"

tmux（交互式）：

tmux new-session -d -s remote_session "ssh -o StrictHostKeyChecking=no <user>@<host> -p <port>"
# Tell user: "Please run: tmux attach -t remote_session and enter your password"
# After user confirms, verify:
tmux capture-pane -t remote_session -p

paramiko：

import paramiko
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect(hostname='<host>', port=<port>, username='<user>', password='<password>')
print('Connection successful')
client.close()

fabric：

from fabric import Connection
conn = Connection(host='<host>', user='<user>', connect_kwargs={'password': '<password>'})
conn.run('echo "Connection successful"', hide=True)
conn.close()

如果连接失败，请排查以下问题：

• 检查主机地址和端口
• 验证凭据
• 检查网络/防火墙/VPN
• 验证跳板主机配置（如果使用）

阶段 4：选择执行环境

询问用户要在哪里运行命令：

1. 直接在主机上——最常见，无需额外设置
2. 在现有 Docker 容器内——连接到正在运行的容器
3. 在新的 Docker 容器内——先创建容器（对于专用工作负载，可考虑使用适用于特定硬件的技能，例如面向 NPU 服务的 npu-docker-launcher）

连接到现有容器

重要：tmux 与其他工具在容器操作中的行为大不相同。

**tmux（持久会话）：**进入容器 Shell 一次，然后直接发送后续所有命令——这些命令会自动在容器内执行。会话会保留状态（工作目录、环境变量、Shell 上下文）。

# List containers
tmux send-keys -t remote_session "docker ps" Enter
tmux capture-pane -t remote_session -p

# Enter container ONCE — all subsequent commands run inside the container
tmux send-keys -t remote_session "docker exec -it <container-name> bash" Enter

# Now you are INSIDE the container — just send commands directly, no need to repeat docker exec
tmux send-keys -t remote_session "cd /workspace" Enter
tmux send-keys -t remote_session "python inference.py" Enter
tmux send-keys -t remote_session "cat result.txt" Enter
tmux capture-pane -t remote_session -p

# Exit container when done (returns to host shell)
tmux send-keys -t remote_session "exit" Enter

**其他工具（无状态）：**每条命令都会建立独立的 SSH 连接，不共享状态。每条命令前都必须加上 docker exec：

# Every command needs the full docker exec prefix
ssh <user>@<host> "docker exec <container-name> ls /workspace"
ssh <user>@<host> "docker exec <container-name> python inference.py"
ssh <user>@<host> "docker exec <container-name> cat result.txt"

阶段 5：执行命令

所有操作都要一致地使用已选定的 SSH 工具。

单条命令

tmux： 由于 tmux 会维护持久的 Shell 会话，直接发送命令即可。如果你之前进入过容器，命令会在容器内运行。

tmux send-keys -t remote_session "<command>" Enter
tmux capture-pane -t remote_session -p

其他工具（无状态，每条命令相互独立）：

工具	在主机上	在容器中
SSH 密钥	ssh -i <key> <user>@<host> "<command>"	ssh -i <key> <user>@<host> "docker exec <container> <command>"
sshpass	sshpass -p '<pwd>' ssh <user>@<host> "<command>"	sshpass -p '<pwd>' ssh <user>@<host> "docker exec <container> <command>"
paramiko	client.exec_command("<command>")	client.exec_command("docker exec <container> <command>")
fabric	conn.run("<command>")	conn.run("docker exec <container> <command>")

文件传输

工具	上传	下载
scp	scp <local> <user>@<host>:<remote>	scp <user>@<host>:<remote> <local>
sshpass+scp	sshpass -p '<pwd>' scp <local> <user>@<host>:<remote>	sshpass -p '<pwd>' scp <user>@<host>:<remote> <local>
paramiko	sftp.put('local', 'remote')	sftp.get('remote', 'local')
fabric	conn.put('local', 'remote/')	conn.get('remote', 'local')

多步骤脚本

对于复杂操作，上传脚本并执行：

# Upload script
scp setup.sh <user>@<host>:/tmp/
# Execute
ssh <user>@<host> "bash /tmp/setup.sh"
# Cleanup
ssh <user>@<host> "rm /tmp/setup.sh"

阶段 6：清理

完成后，清理资源：

• 关闭 SSH 连接（client.close()、conn.close()）
• 终止 tmux 会话（tmux kill-session -t remote_session）
• 如适用，停止或移除临时容器

---

操作参考

tmux（交互式）

# Create SSH session (user inputs password)
tmux new-session -d -s remote_session "ssh -o StrictHostKeyChecking=no <user>@<host> -p <port>"
# User runs: tmux attach -t remote_session

# Execute command after connection
tmux send-keys -t remote_session "<command>" Enter

# Get output
tmux capture-pane -t remote_session -p

# Kill session when done
tmux kill-session -t remote_session

sshpass

# Execute command
sshpass -p '<password>' ssh <user>@<host> "<command>"

# Upload file
sshpass -p '<password>' scp <local> <user>@<host>:<remote>

# Docker exec on remote
sshpass -p '<password>' ssh <user>@<host> "docker exec <container> <command>"

paramiko

import paramiko
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect(hostname='<host>', username='<user>', password='<password>')

# Execute command
stdin, stdout, stderr = client.exec_command('<command>')
print(stdout.read().decode())

# SFTP
sftp = client.open_sftp()
sftp.put('local.txt', '/remote/path/remote.txt')
sftp.get('/remote/file.txt', 'local.txt')

client.close()

fabric

from fabric import Connection
conn = Connection(host='<host>', user='<user>',
                  connect_kwargs={'password': '<password>'})

result = conn.run('<command>', hide=True)
print(result.stdout)

conn.put('local.txt', '/remote/path/')
conn.get('/remote/file.txt', 'local.txt')

conn.close()

---

错误处理

错误	原因	解决方案
连接被拒绝	SSH 未运行	检查远程服务上的 SSH 服务
权限被拒绝	凭据错误	验证用户名、密码或密钥
主机密钥验证失败	首次连接	添加 -o StrictHostKeyChecking=no
网络不可达	网络问题	检查防火墙、VPN
找不到工具	未安装	运行安装命令
找不到容器	名称错误	使用 docker ps -a 列出所有容器

安全最佳实践

1. 尽可能优先使用 SSH 密钥，而不是密码
2. 避免将密码硬编码——使用环境变量或 SSHPASS 环境变量
3. 限制密钥权限：chmod 600 ~/.ssh/id_rsa
4. 如果不想让 AI 处理密码，使用 tmux 方法
5. 完成后清理临时容器和会话

详细参考文件

如需深入了解各工具的用法，请参阅：

• tools/tmux.md — tmux 交互式 SSH（最安全）
• tools/sshpass.md — sshpass 详细用法
• tools/paramiko-basic.md — Paramiko 基本操作
• tools/paramiko-advanced.md — Paramiko Docker 和跳板主机
• tools/fabric-basic.md — Fabric 基本操作
• tools/fabric-advanced.md — Fabric Docker 和并行执行
• tool-comparison.md — 工具比较和选择指南
• ssh-examples.md — 通用 SSH 命令示例
• container-workflows.md — 容器生命周期工作流