دسترسی ترمینال (Exec API)

🖼

تصویر: ترمینال تعاملی (exec) در داشبوردplaceholder — تصویر را اینجا جایگزین کنید

سیستم Exec API ابرکلیک یک ترمینال تعاملی مبتنی بر وب را برای دسترسی مستقیم به کانتینرهای در حال اجرا فراهم می‌کند. این قابلیت برای اجرای مایگریشن‌های پایگاه داده، خطایابی کدهای زنده، یا مدیریت سیستم فایل داخل کانتینر استفاده می‌شود.

دسترسی کامل به کانتینر

Exec دسترسی کامل به shell کانتینر را می‌دهد. فقط به کاربران مورد اعتماد اعطا کنید.

---

اتصال از طریق Socket.IO

ارتباط با ترمینال از طریق Socket.IO برقرار می‌شود. endpoint:

https://api.abrclick.ir/exec

namespace: /exec

احراز هویت

توکن JWT را در هنگام handshake Socket.IO ارسال کنید:

import { io } from "socket.io-client";

const socket = io("https://api.abrclick.ir/exec", {
  auth: {
    token: "<JWT>",
    appId: "<appId>"
  }
});

• token (الزامی): توکن JWT معتبر
• appId (الزامی): شناسه اپلیکیشن

---

رویدادها (Events)

رویدادهای کلاینت → سرور

stdin — ارسال ورودی به ترمینال

socket.emit("stdin", "ls -la\n");

پارامتر: string یا Buffer

resize — تغییر ابعاد ترمینال

socket.emit("resize", { cols: 120, rows: 30 });

پارامتر: { cols: number, rows: number }

---

رویدادهای سرور → کلاینت

stdout — خروجی ترمینال

socket.on("stdout", (data) => {
  // data: Buffer
  console.log(data.toString());
});

پارامتر: Buffer

exit — اتمام session

socket.on("exit", ({ code, reason }) => {
  console.log("Session ended:", code, reason);
});

پارامتر: { code: number | null, reason?: string }

دلایل ممکن:

• خروج عادی shell (exit)
• idle timeout (بیش از ۱۵ دقیقه بدون فعالیت)
• ری‌استارت یا حذف کانتینر

exec-error — خطا در برقراری session

socket.on("exec-error", ({ error, message }) => {
  console.error("Exec error:", error, message);
});

پارامتر: { error: string, message: string }

---

نمونه کلاینت JavaScript

import { io } from "socket.io-client";

const token = localStorage.getItem("auth_token");
const appId = "app-123";

const socket = io("https://api.abrclick.ir/exec", {
  auth: {
    token: token,
    appId: appId
  }
});

socket.on("connect", () => {
  console.log("Connected to exec terminal");
});

socket.on("stdout", (data) => {
  // data is Buffer — convert to string for display
  const output = data.toString("utf-8");
  terminalElement.append(output);
});

socket.on("exit", ({ code, reason }) => {
  console.log(`Session ended. Code: ${code}, Reason: ${reason}`);
  socket.disconnect();
});

socket.on("exec-error", ({ error, message }) => {
  console.error(`Exec error: ${error} - ${message}`);
});

// ارسال دستورات تایپ‌شده کاربر
function sendInput(text) {
  socket.emit("stdin", text);
}

// تغییر اندازه ترمینال
function handleResize(cols, rows) {
  socket.emit("resize", { cols, rows });
}

---

استفاده از xterm.js

برای یک تجربه ترمینال کامل، می‌توانید از کتابخانه xterm.js استفاده کنید:

import { Terminal } from "xterm";
import { io } from "socket.io-client";

const term = new Terminal();
term.open(document.getElementById("terminal"));

const socket = io("https://api.abrclick.ir/exec", {
  auth: {
    token: token,
    appId: appId
  }
});

socket.on("stdout", (data) => {
  term.write(data);
});

term.onData((data) => {
  socket.emit("stdin", data);
});

term.onResize(({ cols, rows }) => {
  socket.emit("resize", { cols, rows });
});

socket.on("exit", () => {
  term.write("\r\n[Session ended]\r\n");
});