SSH Deploy Skill

A universal SSH remote deployment tool for managing Linux servers with batch operations, file transfers, and templated software installations. Optimized for domestic network environments with built-in mirror configuration for Chinese mirrors (Aliyun, Tsinghua, etc.).

Quick Start

1. Initial Setup

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

# Auto setup (checks dependencies, creates config)
bash scripts/setup.sh

# Manual dependency install if auto fails
pip3 install --user paramiko

2. Configure Servers (Two Methods)

Method A: Use inventory.json (Traditional)

Edit ~/.ssh-deploy/inventory.json or add servers via 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"

Config location: All server configurations are saved in ~/.ssh-deploy/inventory.json.

Method B: Read Directly from ~/.ssh/config (New!)

If you already have Host entries in ~/.ssh/config, use them without any additional configuration:

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

# Execute directly using host name
python3 scripts/deploy.py exec dy-c1 "ls -la /opt"

The tool automatically parses Host, HostName, Port, User, IdentityFile fields from your SSH config.

Note: Servers loaded from SSH config are read-only and not saved to inventory. To add groups/tags, import them: inventory.py add --from-ssh-config.

3. Execute Remote Commands

# Single server
python3 scripts/deploy.py exec web-01 "uptime && df -h"

# Batch by group
python3 scripts/deploy.py exec group:production "docker ps"

# Batch by tag
python3 scripts/deploy.py exec tag:aliyun "systemctl status nginx"

# Sequential execution (avoid high load)
python3 scripts/deploy.py exec group:large "apt update" --sequential

4. File Transfers

# Upload file
python3 scripts/deploy.py upload web-01 ./nginx.conf /etc/nginx/nginx.conf

# Batch upload to all group servers
python3 scripts/deploy.py upload group:web ./config.json /opt/app/config.json

# Download file
python3 scripts/deploy.py download web-01 /var/log/nginx/access.log ./logs/

5. Use Templates for Software Installation

All templates in templates/ come pre-configured with domestic mirrors.

# Install Docker (auto-configured with China mirrors)
cat templates/install_docker.sh | python3 scripts/deploy.py exec tag:docker "bash -s"

# Install MySQL (password via environment variable)
MYSQL_ROOT_PASSWORD=YourPass123 cat templates/install_mysql.sh | \
  python3 scripts/deploy.py exec db-01 "bash -s"

# Base setup (system updates + mirrors)
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

📦 Installation Script Templates

Note: All added server configs are saved to ~/.ssh-deploy/inventory.json.

🎯 Core Features

Server Inventory Management (inventory.py)

# List all servers
python3 scripts/inventory.py list

# Filter by group
python3 scripts/inventory.py list --group production

# Filter by tag
python3 scripts/inventory.py list --tag aliyun

# Add server
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"

Target Syntax (used in deploy.py):

• server-name - Specific server
• group:groupname - All servers in that group
• tag:tagname - All servers with that tag
• * - All servers

Remote Command Execution (deploy.py)

# Parallel batch (default)
python3 scripts/deploy.py exec group:web "docker pull nginx"

# Sequential (large batches or to avoid overload)
python3 scripts/deploy.py exec group:large "apt upgrade -y" --sequential

# Use environment variables
export MYSQL_VERSION="8.0"
cat templates/install_mysql.sh | python3 scripts/deploy.py exec db-01 "bash -s"

File Operations

# Upload (single)
python3 scripts/deploy.py upload web-01 ./local.conf /etc/app/conf.d/conf.conf

# Batch upload
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

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

🌏 Domestic Network Optimization

Mirror Configuration

This skill uses Aliyun mirrors by default and configures:

• Ubuntu/Debian → mirrors.aliyun.com
• CentOS/RHEL → mirrors.aliyun.com
• npm → registry.npmmirror.com (Taobao)
• pip → mirrors.aliyun.com/pypi/simple
• Docker → USTC, NetEase, Baidu mirrors
• Go → goproxy.cn
• Maven → Aliyun repository

Detailed config: references/mirrors.md

One-Click Mirror Setup

# Configure system mirrors on all servers
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

# Manual Docker mirror config (if needed)
cat <<'EOF' | python3 scripts/deploy.py exec group:all "bash -s"
cat > /etc/docker/daemon.json <<DOCKER
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
DOCKER
systemctl restart docker
EOF

🔒 Security Best Practices

1. SSH Key Management

   • Use key auth, disable passwords
   • Key permissions: chmod 600 ~/.ssh/id_rsa
   • Different keys for different environments

2. Least Privilege

   • Create dedicated deploy users (not root)
   • Configure passwordless sudo (only necessary commands)
   • Server sshd_config: PermitRootLogin no, PasswordAuthentication no

3. Sensitive Data

   • Never store passwords in inventory.json
   • Use environment variables for passwords (e.g., MYSQL_ROOT_PASSWORD)
   • Config file permissions 640, owner root:appgroup

4. Audit

   • Keep all deployment logs
   • Record command, server, time, result

Full security guide: references/best-practices.md

🐛 Troubleshooting

Quick Diagnostics

# 1. Network test
ping <host>
telnet <host> 22

# 2. Manual SSH test
ssh -i ~/.ssh/id_rsa root@<host> "uptime"

# 3. View connection details
python3 scripts/deploy.py exec <server> "uptime" 2>&1

# 4. Verify key permissions
ls -la ~/.ssh/id_rsa*

Common Issues

Detailed troubleshooting: references/troubleshooting.md

📊 Batch Operations Examples

Scenario 1: New Server Initialization

# 1. Add server to inventory
python3 scripts/inventory.py add web-01 --host 1.2.3.101 --groups web --tags production

# 2. Base setup (mirrors, tools)
cat templates/base_setup.sh | python3 scripts/deploy.py exec web-01 "bash -s"

# 3. Install core software
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. Upload app config
python3 scripts/deploy.py upload web-01 ./app-config.json /opt/app/config.json

# 5. Start application
python3 scripts/deploy.py exec web-01 "docker-compose up -d"

Scenario 2: Rolling Updates Across Multiple Servers

# Canary release: update first batch
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:"canary" "bash -s"

# Check monitoring metrics...

# Full rollout
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:production "bash -s"

Scenario 3: Configuration Sync

# Sync config file to all Web servers
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

# Batch restart
python3 scripts/deploy.py exec group:web "nginx -t && systemctl reload nginx"

Scenario 4: Health Checks & Monitoring

# Collect status from all servers
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 Integration

GitLab CI Example

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 Example

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"

🛠️ Developer Guide

Adding New Installation Templates

1. Create .sh file in templates/
2. Use #!/bin/bash and set -e
3. Detect OS type and adapt (see existing templates)
4. Use env vars for parameters, never hardcode secrets
5. Add domestic mirror config where applicable

Custom Script Structure

#!/bin/bash
set -e

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

# 1. Detect OS
if [ -f /etc/debian_version ]; then
    OS="debian"
elif [ -f /etc/redhat-release ]; then
    OS="redhat"
else
    echo "Unsupported OS"
    exit 1
fi

# 2. Configure domestic mirrors (if needed)
# ...

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

# 4. Start service
systemctl start xxx
systemctl enable xxx

echo "XXX installation complete!"

Using Python API Directly

from inventory import Inventory, Server
from deploy import SSHDeployer

# Load inventory
inv = Inventory()
server = inv.get_server("web-01")

# Create deployer
deployer = SSHDeployer()

# Execute command
result = deployer.execute(server, "docker ps")
print(result.success, result.output)

# Upload file
res = deployer.upload_file(server, "./local.conf", "/etc/conf.d/local.conf")

deployer.close()

📚 Additional Documentation

Detailed documentation (some in Chinese):

• README.md - Complete usage guide with API reference
• README.zh-CN.md - Full Chinese manual
• references/mirrors.md - Domestic mirror configuration details
• references/best-practices.md - Best practices and code examples
• references/troubleshooting.md - Complete troubleshooting handbook

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License