Elastic Compute Service:Manage ECS instances by using Workbench CLI

Prasyarat

• Workbench CLI telah diinstal di komputer Anda, dan kredensial serta izin RAM minimum telah dikonfigurasi. Untuk informasi lebih lanjut, lihat Install Workbench CLI and configure credentials.

• Instance ECS target adalah Linux instance dalam status Running, dan Cloud Assistant agent telah diinstal dan berjalan.

• Komputer Anda harus dapat mengakses *.aliyuncs.com dan titik akhir WebSocket backend Workbench. Perintah upload dan download juga memerlukan agar instance dapat mengakses titik akhir internal OSS di wilayah yang sesuai.

Parameter global

Tiga parameter global berikut berlaku untuk semua subperintah workbench.

Wilayah ditentukan dalam urutan berikut: pemetaan awalan ID instans → lookup sesi aktif di daemon → error yang meminta Anda menentukan --region secara manual. Saat pertama kali menggunakan suatu instance, disarankan untuk menjalankan workbench list ecs -r <region> terlebih dahulu guna mengonfirmasi ID instans.

Kueri daftar instance (workbench list ecs)

Gunakan perintah ini untuk mengkueri instance ECS berdasarkan wilayah, status, tag, dan kondisi lainnya agar Anda dapat dengan cepat menemukan ID instance target. Secara default, workbench list setara dengan workbench list ecs. Berikut beberapa contoh umum:

# Kueri semua instance di wilayah tertentu
workbench list ecs -r cn-hangzhou

# Kueri hanya instance yang sedang berjalan
workbench list ecs -r cn-hangzhou --status Running

# Filter berdasarkan tag (beberapa opsi --tag menggunakan semantik AND)
workbench list ecs -r cn-hangzhou --tag env=prod --tag app=web

# Filter berdasarkan tipe instans, nama, VPC, dan kondisi lainnya
workbench list ecs -r cn-hangzhou --instance-type ecs.g7.large --instance-name "web-*"

# Output JSON untuk konsumsi oleh skrip atau AI agent
workbench list ecs -r cn-hangzhou --output json

Parameter:

Struktur respons dari --output json adalah sebagai berikut:

{
  "instances": [
    {
      "instance_id": "i-bp1xxxxx",
      "instance_name": "web-prod-01",
      "instance_type": "ecs.g7.large",
      "region_id": "cn-hangzhou",
      "status": "Running",
      "private_ip": "172.16.0.10",
      "public_ip": "",
      "os_type": "linux",
      "image_id": "aliyun_3_x64_20G_alibase_20230727.vhd",
      "tags": {"env": "prod"}
    }
  ]
}

Koneksi interaktif (workbench connect)

workbench connect membuka sesi PTY interaktif dan merupakan perintah inti CLI Workbench. Berikut contoh umumnya:

# Autentikasi default tanpa password (login tanpa password Workbench)
workbench connect -i i-bp1a2b3c4d5e6f

# Autentikasi password (masukkan password secara interaktif; input tidak ditampilkan)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type password

# Autentikasi sertifikat (masukkan path file kunci secara interaktif, seperti ~/.ssh/id_rsa)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type certificate

# Tentukan user dan port login
workbench connect -i i-bp1a2b3c4d5e6f -u admin -p 2222

# Paksa sesi baru (jangan gunakan kembali sesi yang sudah ada)
workbench connect -i i-bp1a2b3c4d5e6f --new

Parameter:

Agent> Tampilkan proses dengan penggunaan CPU tertinggi
  ┌─ Menjalankan perintah ──────────
  │ ps aux --sort=-%cpu | head -10
  └────────────────────────
  Menunggu konfirmasi (Y/n): y
  [Dieksekusi]
  ... (agent melanjutkan analisis dan memberikan kesimpulan)

Eksekusi perintah remote (workbench exec)

workbench exec menjalankan satu perintah pada instance dan mengembalikan hasilnya. Berbeda dengan shell persisten connect, setiap panggilan exec berjalan dalam lingkungan yang independen. Meskipun demikian, beberapa panggilan ke instance yang sama menggunakan kembali saluran koneksi dasar, sehingga tidak memerlukan pengaturan koneksi berulang. Contoh umum:

# Jalankan perintah
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h"

# Gabungkan perintah: cd + variabel lingkungan + jalankan
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/app && ./deploy.sh"

# Atur timeout
workbench exec -i i-bp1a2b3c4d5e6f -c "sleep 30" --timeout 10

# Output JSON untuk konsumsi oleh skrip atau AI agent
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

Parameter:

Struktur respons dari --output json adalah sebagai berikut:

{
  "output": "Filesystem ...\n",
  "stderr": "",
  "exit_code": 0
}

Dalam struktur ini, output adalah standar output perintah, stderr adalah standar error, dan exit_code adalah kode keluar perintah jarak jauh (berupa bilangan bulat).

Transfer file (workbench upload / download)

Jika Anda tidak memiliki alamat IP publik atau saluran SCP, gunakan workbench upload / workbench download untuk mentransfer file. Proses unggah menampilkan bilah progres secara real-time.

Contoh unggah:

workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f

Contoh unduh:

# Unduh ke direktori saat ini
workbench download /var/log/app.log ./ -i i-bp1a2b3c4d5e6f

# Unduh dan ganti nama
workbench download /var/log/app.log ./local-copy.log -i i-bp1a2b3c4d5e6f

Parameter:

Manajemen sesi (workbench session)

Perintah umum:

# Lihat semua sesi aktif
workbench session list
workbench session list --output json

# Tutup sesi tertentu
workbench session close <session-id>

# Tutup semua sesi
workbench session close --all

Transisi status sesi:

• OPEN: Sesi telah dibuat dan dapat dibaca maupun ditulis secara normal.

• RECONNECTING: WebSocket dasar telah terputus dan sedang mencoba menyambung kembali.

• BROKEN: Koneksi ulang gagal dan sesi tidak tersedia.

• CLOSED: Sesi telah ditutup (oleh pengguna, karena habis waktu, atau mencapai batas TTL).

Beberapa operasi connect, exec, upload, dan download pada instance yang sama berbagi sesi yang sama. Sesinya ditangani secara transparan oleh daemon, sehingga Anda tidak perlu khawatir tentang ID sesi. Hanya satu terminal (TTY) yang dapat dikaitkan ke sesi tersebut dalam satu waktu. Jika terminal sudah terkait, Anda dapat menggunakan --new untuk membuat sesi baru atau menutup koneksi yang ada terlebih dahulu.

Manajemen daemon (workbench daemon)

Workbench CLI bergantung pada daemon latar belakang ruang pengguna untuk mempertahankan koneksi WebSocket dan melakukan multiplexing sesi. Siklus hidup daemon sepenuhnya otomatis dan biasanya tidak memerlukan manajemen manual.

# Lihat status daemon
workbench daemon status

# Hentikan daemon (menutup semua sesi)
workbench daemon stop

• Startup otomatis: Daemon akan dimulai secara otomatis saat Anda menjalankan perintah workbench untuk pertama kalinya.

• Keluar otomatis: Daemon keluar secara otomatis 60 detik setelah sesi terakhir ditutup.

• Instans tunggal: Hanya satu instans daemon yang diizinkan per pengguna sistem operasi (diberlakukan oleh kunci file PID).

• Saluran IPC: CLI dan daemon berkomunikasi melalui ~/.workbench/run/daemon.sock (socket Unix) menggunakan protokol JSON-RPC.

Skenario khas

workbench upload ./app-2.0.tar.gz /opt/deploy/ -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz && ./deploy.sh"
workbench exec -i i-bp1a2b3c4d5e6f -c "curl -s http://localhost:8080/health"

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h && free -m" --output json | jq '.output'
workbench exec -i i-bp1a2b3c4d5e6f -c "systemctl status nginx" --output json | jq '.exit_code'

workbench connect -i i-bp1a2b3c4d5e6f
# Jalankan tail -f atau tugas berjalan lama dalam sesi
# Lalu masukkan /detach untuk melepaskan

# Mengaitkan ulang ke sesi asli nanti
workbench connect -i i-bp1a2b3c4d5e6f

Kode keluar

workbench exec meneruskan kode keluar perintah remote: CLI akan keluar dengan kode keluar yang sama dengan yang dikembalikan oleh perintah remote, konsisten dengan perilaku SSH. Dengan demikian, skrip dapat langsung menentukan keberhasilan perintah remote berdasarkan kode keluar workbench exec.

Sebagai contoh, perintah berikut menjalankan exit 42 pada instance, dan CLI juga keluar dengan kode 42:

workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $?   # Menghasilkan 42

Jika perintah gagal karena alasan seperti parameter tidak valid, autentikasi gagal, masalah jaringan, atau instance tidak ditemukan, penggunaan --output json akan menghasilkan detail kesalahan dalam format berikut:

{
  "code": 1,
  "message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}

Dalam struktur ini, code adalah pengidentifikasi error bukan nol, sedangkan message berisi deskripsi error yang dapat dibaca (biasanya mencakup kode error dan RequestId dari API dasar) yang dapat Anda gunakan untuk melokalisasi masalah.

Pemecahan Masalah

Gejala umum dan tindakan pertama yang harus diambil:

Perintah debugging:

# Lihat status daemon
workbench daemon status

# Output error JSON untuk penguraian mudah oleh skrip
workbench exec -i i-bp1a2b3c4d5e6f -c "echo test" --output json

Log daemon disimpan di ~/.workbench/log/daemon.log.

Referensi

• Connect to an instance by using Workbench CLI: topik induk, yang mencakup posisi tool dan quick start.

• Install Workbench CLI and configure credentials: instalasi CLI dan konfigurasi kredensial/izin.

• Operate ECS instances by using Workbench CLI in AI agents: agent memanggil perintah workbench di Wukong atau opencode.

• Install the Cloud Assistant agent: Workbench CLI bergantung pada Cloud Assistant agent.