SSH 部署技能（SSH Deploy Skill）

一款通用的 SSH 远程部署工具，用于批量管理 Linux 服务器，支持远程命令执行、文件传输及基于模板的软件安装。针对国内网络环境深度优化，内置阿里云、清华大学等国内镜像源配置。

快速开始

1. 初始设置

cd /root/.openclaw/workspace/skills/ssh-deploy-skill

# 自动初始化（检查依赖、生成配置）
bash scripts/setup.sh

# 若自动初始化失败，手动安装依赖
pip3 install --user paramiko

2. 配置服务器（两种方式）

方式 A：使用 inventory.json（传统方式）

编辑 ~/.ssh-deploy/inventory.json，或通过 CLI 添加服务器：

python3 scripts/inventory.py add web-01 
  --host 192.168.1.101 
  --user root 
  --ssh-key ~/.ssh/id_rsa 
  --groups production,web 
  --tags "aliyun"

配置位置：所有服务器配置均保存于 ~/.ssh-deploy/inventory.json 中。

方式 B：直接读取 ~/.ssh/config（新特性！）

若你已在 ~/.ssh/config 中定义了 Host 条目，则可 无需额外配置直接使用：

# ~/.ssh/config 示例
Host dy-c1
    HostName 101.126.92.30
    User root
    IdentityFile ~/.ssh/mypc_id_rsa
    Port 22

# 直接使用主机名执行命令
python3 scripts/deploy.py exec dy-c1 "ls -la /opt"

该工具将自动解析 SSH 配置中的 Host、HostName、Port、User 和 IdentityFile 字段。

注意：从 SSH 配置加载的服务器为 只读状态，不会写入 inventory。如需添加分组或标签，请导入： inventory.py add --from-ssh-config。

3. 执行远程命令

# 单台服务器
python3 scripts/deploy.py exec web-01 "uptime && df -h"

# 按分组批量执行
python3 scripts/deploy.py exec group:production "docker ps"

# 按标签批量执行
python3 scripts/deploy.py exec tag:aliyun "systemctl status nginx"

# 串行执行（避免高负载）
python3 scripts/deploy.py exec group:large "apt update" --sequential

4. 文件传输

# 上传文件
python3 scripts/deploy.py upload web-01 ./nginx.conf /etc/nginx/nginx.conf

# 批量上传至分组内所有服务器
python3 scripts/deploy.py upload group:web ./config.json /opt/app/config.json

# 下载文件
python3 scripts/deploy.py download web-01 /var/log/nginx/access.log ./logs/

5. 使用模板安装软件

templates/ 目录下的所有模板均已预配置国内镜像源。

# 安装 Docker（自动启用国内镜像加速）
cat templates/install_docker.sh | python3 scripts/deploy.py exec tag:docker "bash -s"

# 安装 MySQL（密码通过环境变量传入）
MYSQL_ROOT_PASSWORD=YourPass123 cat templates/install_mysql.sh | 
  python3 scripts/deploy.py exec db-01 "bash -s"

# 基础环境初始化（系统更新 + 镜像配置）
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

📦 安装脚本模板

注意：所有新增的服务器配置均保存至 ~/.ssh-deploy/inventory.json。

🎯 核心功能

服务器清单管理（inventory.py）

# 列出全部服务器
python3 scripts/inventory.py list

# 按分组筛选
python3 scripts/inventory.py list --group production

# 按标签筛选
python3 scripts/inventory.py list --tag aliyun

# 添加服务器
python3 scripts/inventory.py add SERVER_NAME 
  --host IP_OR_HOSTNAME 
  --port 22 
  --user USERNAME 
  --ssh-key PATH_TO_KEY 
  --groups GROUP1,GROUP2 
  --tags TAG1,TAG2 
  --desc "description"

目标语法（在 deploy.py 中使用）：

• server-name —— 指定单台服务器
• group:groupname —— 指定分组内所有服务器
• tag:tagname —— 指定拥有该标签的所有服务器
• * —— 所有服务器

远程命令执行（deploy.py）

# 并行批量执行（默认行为）
python3 scripts/deploy.py exec group:web "docker pull nginx"

# 串行执行（适用于大批量操作或避免过载）
python3 scripts/deploy.py exec group:large "apt upgrade -y" --sequential

# 使用环境变量
export MYSQL_VERSION="8.0"
cat templates/install_mysql.sh | python3 scripts/deploy.py exec db-01 "bash -s"

文件操作

# 上传（单台）
python3 scripts/deploy.py upload web-01 ./local.conf /etc/app/conf.d/conf.conf

# 批量上传
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

# 下载
python3 scripts/deploy.py download web-01 /var/log/app.log ./logs/

🌏 国内网络优化

镜像配置

本技能默认使用 阿里云镜像源，并自动配置以下内容：

• Ubuntu/Debian → mirrors.aliyun.com
• CentOS/RHEL → mirrors.aliyun.com
• npm → registry.npmmirror.com（淘宝镜像）
• pip → mirrors.aliyun.com/pypi/simple
• Docker → 中科大、网易、百度镜像源
• Go → goproxy.cn
• Maven → 阿里云仓库

详细配置说明见：references/mirrors.md

一键镜像配置

# 在所有服务器上配置系统镜像源
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

# 手动配置 Docker 镜像（如有需要）
cat <<'EOF' | python3 scripts/deploy.py exec group:all "bash -s"
cat > /etc/docker/daemon.json <
🔒 安全最佳实践

SSH 密钥管理

强制使用密钥认证，禁用密码登录
密钥权限应设为 chmod 600 ~/.ssh/id_rsa
不同环境建议使用独立密钥


最小权限原则

创建专用部署用户（避免使用 root）
配置免密 sudo（仅授予必要命令权限）
服务端 sshd_config 中设置：PermitRootLogin no，PasswordAuthentication no


敏感数据保护

切勿在 inventory.json 中存储密码
密码类参数请通过环境变量传递（例如 MYSQL_ROOT_PASSWORD）
配置文件权限应设为 640，属主为 root:appgroup


审计追踪

保留全部部署日志
记录每次执行的命令、目标服务器、时间戳与执行结果



完整安全指南见：references/best-practices.md
🐛 故障排查
快速诊断
# 1. 网络连通性测试
ping 
telnet  22

# 2. 手动 SSH 测试
ssh -i ~/.ssh/id_rsa root@ "uptime"

# 3. 查看连接详情（含错误输出）
python3 scripts/deploy.py exec  "uptime" 2>&1

# 4. 验证密钥权限
ls -la ~/.ssh/id_rsa*

常见问题



现象
解决方案



连接被拒绝 / 超时
检查服务器运行状态、SSH 服务是否启动、防火墙或安全组策略


Permission denied (publickey)
确认公钥已正确写入服务器的 ~/.ssh/authorized_keys，且私钥权限为 600


sudo: a password is required
配置免密 sudo 或改用 root 用户执行


Command not found
使用绝对路径，或确保 PATH 环境变量包含对应命令路径


国内下载缓慢
运行 base_setup.sh 配置镜像源，详见 docs/mirrors.md


详细排错手册见：references/troubleshooting.md
📊 批量操作示例
场景 1：新服务器初始化
# 1. 将服务器加入清单
python3 scripts/inventory.py add web-01 --host 1.2.3.101 --groups web --tags production

# 2. 基础环境初始化（镜像源、常用工具）
cat templates/base_setup.sh | python3 scripts/deploy.py exec web-01 "bash -s"

# 3. 安装核心软件
cat templates/install_docker.sh | python3 scripts/deploy.py exec web-01 "bash -s"
cat templates/install_nginx.sh | python3 scripts/deploy.py exec web-01 "bash -s"

# 4. 上传应用配置
python3 scripts/deploy.py upload web-01 ./app-config.json /opt/app/config.json

# 5. 启动应用
python3 scripts/deploy.py exec web-01 "docker-compose up -d"

场景 2：多服务器滚动更新
# 金丝雀发布：先更新首批节点
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:"canary" "bash -s"

# 检查监控指标...

# 全量发布
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:production "bash -s"

场景 3：配置同步
# 同步配置文件至所有 Web 服务器
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

# 批量重启服务
python3 scripts/deploy.py exec group:web "nginx -t && systemctl reload nginx"

场景 4：健康检查与监控
# 收集所有服务器运行状态
python3 scripts/deploy.py exec "*" "uptime" > uptime-$(date +%F).log

python3 scripts/deploy.py exec "*" "df -h" > disk-$(date +%F).log

python3 scripts/deploy.py exec "*" "docker ps --format 'table {{.Names}}t{{.Status}}'" > containers-$(date +%F).log

🔄 CI/CD 集成
GitLab CI 示例
stages:
  - deploy

deploy_production:
  stage: deploy
  script:
    - pip3 install --user paramiko
    - export TARGET="group:production"
    - cat deploy.sh | python3 skills/ssh-deploy-skill/scripts/deploy.py exec "$TARGET" "bash -s"
  only:
    - main

GitHub Actions 示例
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install paramiko
        run: pip3 install paramiko
      - name: Deploy to servers
        run: |
          cat deploy.sh | python3 skills/ssh-deploy-skill/scripts/deploy.py exec "group:staging" "bash -s"

🛠️ 开发者指南
新增安装模板

在 templates/ 目录下新建 .sh 文件
以 #!/bin/bash 开头，并包含 set -e
检测操作系统类型并适配逻辑（参考已有模板）
使用环境变量传递参数，禁止硬编码敏感信息
在适用场景中加入国内镜像源配置

自定义脚本结构
#!/bin/bash
set -e

echo "===== Installing XXX ====="

# 1. 检测操作系统
if [ -f /etc/debian_version ]; then
    OS="debian"
elif [ -f /etc/redhat-release ]; then
    OS="redhat"
else
    echo "Unsupported OS"
    exit 1
fi

# 2. 配置国内镜像源（如需）
# ...

# 3. 安装软件
if [ "$OS" = "debian" ]; then
    apt-get update
    apt-get install -y xxx
elif [ "$OS" = "redhat" ]; then
    yum install -y xxx
fi

# 4. 启动服务
systemctl start xxx
systemctl enable xxx

echo "XXX installation complete!"

直接使用 Python API
from inventory import Inventory, Server
from deploy import SSHDeployer

# 加载服务器清单
inv = Inventory()
server = inv.get_server("web-01")

# 创建部署器实例
deployer = SSHDeployer()

# 执行命令
result = deployer.execute(server, "docker ps")
print(result.success, result.output)

# 上传文件
res = deployer.upload_file(server, "./local.conf", "/etc/conf.d/local.conf")

deployer.close()

📚 补充文档
详细文档（部分含中文）：

README.md —— 完整使用指南与 API 参考
README.zh-CN.md —— 全中文手册
references/mirrors.md —— 国内镜像源配置详情
references/best-practices.md —— 最佳实践与代码示例
references/troubleshooting.md —— 完整故障排查手册

🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
📄 许可证
MIT License