Web SSH 的原理與在 ASP.NET Core SignalR 中的實現

Aoba_xu發表於2023-10-31

前言

有個專案，需要在前端有個管理終端可以 SSH 到主控機的終端，如果不考慮使用者使用 vim 等需要在控制檯內現實介面的軟體的話，其實使用 Process 型別去啟動相應程式就夠了。而這次的需求則需要考慮使用者會做相關設定。

原理

這裡用到的原理是偽終端。偽終端（pseudo terminal）是現代作業系統的一個功能，他會模擬一對輸入輸出裝置來模擬終端環境去執行相應的程式。偽終端通常會給相應的程式提供例如環境變數或檔案等來告知他在終端中執行，這樣像 vim 這樣的程式可以在最後一行輸出命令選單或者像 npm / pip 這樣的程式可以列印炫酷的進度條。通常在我們直接建立子程式的時候，在 Linux 上系統自帶了 openpty 方法可以開啟偽終端，而在 Windows 上則等到 Windows Terminal 推出後才出現了真正的系統級偽終端。下面付一張來自微軟部落格的偽終端原理圖，Linux 上的原理與之類似。

偽終端原理圖

基本設計

建立連線與監聽終端輸出

監聽前端輸入

graph TD; A[終端視窗收到鍵盤事件] --> B[SignalR 傳送請求]; B --> C[後臺轉發到對應終端]

超時與關閉

graph TD; A[當 SignalR 傳送斷開連線或終端超時] --> B[關閉終端程式];

依賴庫

portable_pty

這裡用到這個 Rust 庫來建立終端，這個庫是一個獨立的程式，每次建立連線都會執行。這裡當初考慮過直接在 ASP.NET Core 應用裡呼叫 vs-pty（微軟開發的，用在 vs 裡的庫，可以直接在 vs 安裝位置複製一份），但是 vs-pty 因為種種原因在 .NET 7 + Ubuntu 22.04 的環境下執行不起來故放棄了。

xterm.js

這個是前端展示終端介面用的庫，據說 vs code 也在用這個庫，雖然文件不多，但是用起來真的很簡單。

SignalR

這個不多說了，我們 .NET 系列 Web 實時通訊選他就沒錯。

程式碼

廢話不多講了，我們還是直接看程式碼吧，這裡程式碼還是比較長的，我節選了一些必要的程式碼。具體 SignalR 之類的配置，還請讀者自行參考微軟官方文件。

main.rs 這個 Rust 程式碼用於建立偽終端並和 .NET 服務通訊，這裡使用了最簡單的 UDP 方式通訊。

use portable_pty::{self, native_pty_system, CommandBuilder, PtySize};
use std::{io::prelude::*, sync::Arc};
use tokio::net::UdpSocket;
#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = std::env::args().collect::<Vec<_>>();
    // 啟動一個終端
    let pty_pair = native_pty_system().openpty(PtySize {
        rows: args.get(2).ok_or("NoNumber")?.parse()?,
        cols: args.get(3).ok_or("NoNumber")?.parse()?,
        pixel_width: 0,
        pixel_height: 0,
    })?;
    // 執行傳進來的命令
    let mut cmd = CommandBuilder::new(args.get(4).unwrap_or(&"bash".to_string()));
    if args.len() > 5 {
        cmd.args(&args[5..]);
    }
    let mut proc = pty_pair.slave.spawn_command(cmd)?;
    // 繫結輸入輸出
    let mut reader = pty_pair.master.try_clone_reader()?;
    let mut writer = pty_pair.master.take_writer()?;
    // 繫結網路
    let main_socket = Arc::new(UdpSocket::bind("localhost:0").await?);
    let recv_socket = main_socket.clone();
    let send_socket = main_socket.clone();
    let resize_socket = UdpSocket::bind("localhost:0").await?;
    // 連線到主服務後傳送地址
    main_socket
        .connect(args.get(1).ok_or("NoSuchAddr")?)
        .await?;
    main_socket
        .send(&serde_json::to_vec(&ClientAddr {
            main: main_socket.local_addr()?.to_string(),
            resize: resize_socket.local_addr()?.to_string(),
        })?)
        .await?;
    // 讀取終端資料併傳送
    let read = tokio::spawn(async move {
        loop {
            let mut buf = [0; 1024];
            let n = reader.read(&mut buf).unwrap();
            if n == 0 {
                continue;
            }
            println!("{:?}", &buf[..n]);
            send_socket.send(&buf[..n]).await.unwrap();
        }
    });
    // 接收資料並寫入終端
    let write = tokio::spawn(async move {
        loop {
            let mut buf = [0; 1024];
            let n = recv_socket.recv(&mut buf).await.unwrap();
            if n == 0 {
                continue;
            }
            println!("{:?}", &buf[..n]);
            writer.write_all(&buf[..n]).unwrap();
        }
    });
    // 接收調整視窗大小的資料
    let resize = tokio::spawn(async move {
        let mut buf = [0; 1024];
        loop {
            let n = resize_socket.recv(&mut buf).await.unwrap();
            if n == 0 {
                continue;
            }
            let size: WinSize = serde_json::from_slice(buf[..n].as_ref()).unwrap();
            pty_pair
                .master
                .resize(PtySize {
                    rows: size.rows,
                    cols: size.cols,
                    pixel_width: 0,
                    pixel_height: 0,
                })
                .unwrap();
        }
    });
    // 等待程式結束
    let result = proc.wait()?;
    write.abort();
    read.abort();
    resize.abort();
    if 0 == result.exit_code() {
        std::process::exit(result.exit_code() as i32);
    }
    return Ok(());
}
/// 視窗大小
#[derive(serde::Deserialize)]
struct WinSize {
    /// 行數
    rows: u16,
    /// 列數
    cols: u16,
}
/// 客戶端地址
#[derive(serde::Serialize)]
struct ClientAddr {
    /// 主要地址
    main: String,
    /// 調整視窗大小地址
    resize: String,
}

SshPtyConnection.cs 這個程式碼用於維持一個後臺執行的 Rust 程式，並管理他的雙向通訊。

    public class SshPtyConnection : IDisposable
    {
        /// <summary>
        /// 客戶端地址
        /// </summary>
        private class ClientEndPoint
        {
            public required string Main { get; set; }
            public required string Resize { get; set; }
        }
        /// <summary>
        /// 視窗大小
        /// </summary>
        private class WinSize
        {
            public int Cols { get; set; }
            public int Rows { get; set; }
        }
        /// <summary>
        /// SignalR 上下文
        /// </summary>
        private readonly IHubContext<SshHub> _hubContext;
        /// <summary>
        /// 日誌記錄器
        /// </summary>
        private readonly ILogger<SshPtyConnection> _logger;
        /// <summary>
        /// UDP 客戶端
        /// </summary>
        private readonly UdpClient udpClient;
        /// <summary>
        /// 最後活動時間
        /// </summary>
        private DateTime lastActivity = DateTime.UtcNow;
        /// <summary>
        /// 是否已釋放
        /// </summary>
        private bool disposedValue;
        /// <summary>
        /// 是否已釋放
        /// </summary>
        public bool IsDisposed => disposedValue;
        /// <summary>
        /// 最後活動時間
        /// </summary>
        public DateTime LastActivity => lastActivity;
        /// <summary>
        /// 取消令牌
        /// </summary>
        public CancellationTokenSource CancellationTokenSource { get; } = new CancellationTokenSource();
        /// <summary>
        /// 視窗大小
        /// </summary>
        public event EventHandler<EventArgs> Closed = delegate { };
        /// <summary>
        /// 建構函式
        /// </summary>
        /// <param name="hubContext"></param>
        /// <param name="logger"></param>
        /// <exception cref="ArgumentNullException"></exception>
        public SshPtyConnection(IHubContext<SshHub> hubContext, ILogger<SshPtyConnection> logger)
        {
            _hubContext = hubContext ?? throw new ArgumentNullException(nameof(hubContext));
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
            lastActivity = DateTime.Now;
            udpClient = new(IPEndPoint.Parse("127.0.0.1:0"));
        }
        /// <summary>
        /// 開始監聽
        /// </summary>
        /// <param name="connectionId">連線 ID</param>
        /// <param name="username">使用者名稱</param>
        /// <param name="height">行數</param>
        /// <param name="width">列數</param>
        public async void StartAsync(string connectionId, string username, int height, int width)
        {
            var token = CancellationTokenSource.Token;
            _logger.LogInformation("process starting");
            // 啟動程式
            using var process = Process.Start(new ProcessStartInfo
            {
                FileName = OperatingSystem.IsOSPlatform("windows") ? "PtyWrapper.exe" : "pty-wrapper",
                // 這裡用了 su -l username，因為程式直接部署在主控機的 root 下，所以不需要 ssh 只需要切換使用者即可，如果程式部署在其他機器上，需要使用 ssh
                ArgumentList = { udpClient.Client.LocalEndPoint!.ToString() ?? "127.0.0.1:0", height.ToString(), width.ToString(), "su", "-l", username }
            });
            // 接收客戶端地址
            var result = await udpClient.ReceiveAsync();
            var clientEndPoint = await JsonSerializer.DeserializeAsync<ClientEndPoint>(new MemoryStream(result.Buffer), new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
            if (clientEndPoint == null)
            {
                CancellationTokenSource.Cancel();
                return;
            }
            process!.Exited += (_, _) => CancellationTokenSource.Cancel();
            var remoteEndPoint = IPEndPoint.Parse(clientEndPoint.Main);
            udpClient.Connect(remoteEndPoint);
            var stringBuilder = new StringBuilder();
            // 接收客戶端資料，併傳送到 SignalR，直到客戶端斷開連線或者超時 10 分鐘
            while (!token.IsCancellationRequested && lastActivity.AddMinutes(10) > DateTime.Now && !(process?.HasExited ?? false))
            {
                try
                {
                    lastActivity = DateTime.Now;
                    var buffer = await udpClient.ReceiveAsync(token);
                    await _hubContext.Clients.Client(connectionId).SendAsync("WriteDataAsync", Encoding.UTF8.GetString(buffer.Buffer));
                    stringBuilder.Clear();
                }
                catch (Exception e)
                {
                    _logger.LogError(e, "ConnectionId: {ConnectionId} Unable to read data and send message.", connectionId);
                    break;
                }
            }
            // 如果客戶端斷開連線或者超時 10 分鐘，關閉程式
            if (process?.HasExited ?? false) process?.Kill();
            if (lastActivity.AddMinutes(10) < DateTime.Now)
            {
                _logger.LogInformation("ConnectionId: {ConnectionId} Pty session has been closed because of inactivity.", connectionId);
                try
                {
                    await _hubContext.Clients.Client(connectionId).SendAsync("WriteErrorAsync", "InactiveTimeTooLong");
                }
                catch (Exception e)
                {
                    _logger.LogError(e, "ConnectionId: {ConnectionId} Unable to send message.", connectionId);
                }
            }
            if (token.IsCancellationRequested)
            {
                _logger.LogInformation("ConnectionId: {ConnectionId} Pty session has been closed because of session closed.", connectionId);
                try
                {
                    await _hubContext.Clients.Client(connectionId).SendAsync("WriteErrorAsync", "SessionClosed");
                }
                catch (Exception e)
                {
                    _logger.LogError(e, "ConnectionId: {ConnectionId} Unable to send message.", connectionId);
                }
            }
            Dispose();
        }
        /// <summary>
        /// 接收 SignalR 資料，併傳送到客戶端
        /// </summary>
        /// <param name="data">資料</param>
        /// <returns></returns>
        /// <exception cref="AppException"></exception>
        public async Task WriteDataAsync(string data)
        {
            if (disposedValue)
            {
                throw new AppException("SessionClosed");
            }
            try
            {
                lastActivity = DateTime.Now;
                await udpClient.SendAsync(Encoding.UTF8.GetBytes(data));
            }
            catch (Exception e)
            {
                CancellationTokenSource.Cancel();
                Dispose();
                throw new AppException("SessionClosed", e);
            }
        }
        /// <summary>
        /// 回收資源
        /// </summary>
        /// <param name="disposing"></param>
        protected virtual void Dispose(bool disposing)
        {
            if (!disposedValue)
            {
                if (disposing)
                {
                    CancellationTokenSource.Cancel();
                    udpClient.Dispose();
                }
                disposedValue = true;
                Closed(this, new EventArgs());
            }
        }
        public void Dispose()
        {
            Dispose(disposing: true);
            GC.SuppressFinalize(this);
        }
    }

SshService 這段程式碼用於管理 SshPtyConnection 和 SignalR 客戶端連線之間的關係

    public class SshService : IDisposable
    {
        private bool disposedValue;
        private readonly IHubContext<SshHub> _hubContext;
        private readonly ILoggerFactory _loggerFactory;
        private Dictionary<string, SshPtyConnection> _connections;

        public SshService(IHubContext<SshHub> hubContext, ILoggerFactory loggerFactory)
        {
            _hubContext = hubContext ?? throw new ArgumentNullException(nameof(hubContext));
            _connections = new Dictionary<string, SshPtyConnection>();
            _loggerFactory = loggerFactory ?? throw new ArgumentNullException(nameof(loggerFactory));
        }

        /// <summary>
        /// 建立終端連線
        /// </summary>
        /// <param name="connectionId">連線 ID</param>
        /// <param name="username">使用者名稱</param>
        /// <param name="height">行數</param>
        /// <param name="width">列數</param>
        /// <returns></returns>
        /// <exception cref="InvalidOperationException"></exception>
        public Task CreateConnectionAsync(string connectionId, string username, int height, int width)
        {
            if (_connections.ContainsKey(connectionId))
                throw new InvalidOperationException();
            var connection = new SshPtyConnection(_hubContext, _loggerFactory.CreateLogger<SshPtyConnection>());
            connection.Closed += (sender, args) =>
            {
                _hubContext.Clients.Client(connectionId).SendAsync("WriteErrorAsync", "SessionClosed");
                _connections.Remove(connectionId);
            };
            _connections.Add(connectionId, connection);
            // 執行一個後臺執行緒
            connection.StartAsync(connectionId, username, height, width);
            return Task.CompletedTask;
        }
        /// <summary>
        /// 寫入資料
        /// </summary>
        /// <param name="connectionId">連線 ID</param>
        /// <param name="data">資料</param>
        /// <exception cref="AppException"></exception>
        public async Task ReadDataAsync(string connectionId, string data)
        {
            if (_connections.TryGetValue(connectionId, out var connection))
            {
                await connection.WriteDataAsync(data);
            }
            else
                throw new AppException("SessionClosed");
        }
        /// <summary>
        /// 關閉連線
        /// </summary>
        /// <param name="connectionId">連線 ID</param>
        /// <exception cref="AppException"></exception>
        public Task CloseConnectionAsync(string connectionId)
        {
            if (_connections.TryGetValue(connectionId, out var connection))
            {
                connection.Dispose();
            }
            else
                throw new AppException("SessionClosed");
            return Task.CompletedTask;
        }
        /// <summary>
        /// 回收資源
        /// </summary>
        /// <param name="disposing"></param>
        protected virtual void Dispose(bool disposing)
        {
            if (!disposedValue)
            {
                if (disposing)
                {
                    foreach (var item in _connections.Values)
                    {
                        item.Dispose();
                    }
                }
                disposedValue = true;
            }
        }

        public void Dispose()
        {
            Dispose(disposing: true);
            GC.SuppressFinalize(this);
        }
    }

WebSsh.vue 這段程式碼是使用 vue 展示終端視窗的程式碼

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { Terminal } from 'xterm';
import { FitAddon } from 'xterm-addon-fit';
import { WebLinksAddon } from 'xterm-addon-web-links';
import { SearchAddon } from 'xterm-addon-search';
import { WebglAddon } from 'xterm-addon-webgl';
import * as signalR from '@microsoft/signalr';
import 'xterm/css/xterm.css';
const termRef = ref<HTMLElement | null>(null);
// 建立 xterm 終端
const term = new Terminal();
// 定義 SignalR 客戶端
const connection = new signalR.HubConnectionBuilder()
  .withUrl('/hubs/ssh', {
    accessTokenFactory: () => localStorage.getItem('token'),
  } as any)
  .build();
let isClosed = false;
// 監聽鍵盤事件併傳送到後端
term.onData((data) => {
  if (isClosed) {
    return;
  }
  connection.invoke('ReadDataAsync', data).then((result) => {
    if (result.code == 400) {
      isClosed = true;
      term.write('SessionClosed');
    }
  });
});
// 監聽後端資料回傳
connection.on('WriteDataAsync', (data) => {
  term.write(data);
});
// 監聽後端終端關閉
connection.on('WriteErrorAsync', () => {
  isClosed = true;
  term.write('SessionClosed');
});
// 載入外掛
const fit = new FitAddon();
term.loadAddon(fit);
term.loadAddon(new WebLinksAddon());
term.loadAddon(new SearchAddon());
term.loadAddon(new WebglAddon());

onMounted(async () => {
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
  term.open(termRef.value!);
  fit.fit();
  // 啟動 SignalR 客戶端
  await connection.start();
  // 建立終端
  connection.invoke('CreateNewTerminalAsync', term.rows, term.cols);
});
</script>

<template>
  <div ref="termRef" class="xTerm"></div>
</template>

<style scoped>
</style>

SshHub.cs 這個檔案是 SignalR 的 Hub 檔案，用來做監聽的。

    [Authorize]
    public class SshHub : Hub<ISshHubClient>
    {
        private readonly SshService _sshService;
        private readonly ILogger<SshHub> _logger;

        public SshHub(SshService sshService, ILogger<SshHub> logger)
        {
            _sshService = sshService ?? throw new ArgumentNullException(nameof(sshService));
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        }
        /// <summary>
        /// 建立一個新的終端
        /// </summary>
        /// <param name="height"></param>
        /// <param name="width"></param>
        /// <returns></returns>
        public async Task<BaseResponse> CreateNewTerminalAsync(int height = 24, int width = 80)
        {
            try
            {
                var username = Context.User?.FindFirst("preferred_username")?.Value;
                if (username == null)
                {
                    return new BaseResponse
                    {
                        Code = 401,
                        Message = "NoUsername"
                    };
                }
                if (!Context.User?.IsInRole("user") ?? false)
                {
                    username = "root";
                }
                _logger.LogInformation($"{username}");
                await _sshService.CreateConnectionAsync(Context.ConnectionId, username, height, width);
                return new BaseResponse();
            }
            catch (InvalidOperationException)
            {
                return new BaseResponse() { Code = 500, Message = "TerminalAlreadyExist" };
            }
            catch (Exception e)
            {
                _logger.LogError(e, "ConnectionId: {ConnectionId} No such pty session.", Context.ConnectionId);
                return new BaseResponse() { Code = 500, Message = "UnableToCreateTerminal" };
            }
        }
        /// <summary>
        /// 讀取輸入資料
        /// </summary>
        /// <param name="data"></param>
        /// <returns></returns>
        public async Task<BaseResponse> ReadDataAsync(string data)
        {
            try
            {
                await _sshService.ReadDataAsync(Context.ConnectionId, data);
                return new BaseResponse();
            }
            catch (Exception e)
            {
                _logger.LogError(e, "ConnectionId: {ConnectionId} No such pty session.", Context.ConnectionId);
                return new BaseResponse { Message = "NoSuchSeesion", Code = 400 };
            }
        }
    }
    /// <summary>
    /// 客戶端介面
    /// </summary>
    public interface ISshHubClient
    {
        /// <summary>
        /// 寫入輸出資料
        /// </summary>
        /// <param name="data"></param>
        /// <returns></returns>
        Task WriteDataAsync(string data);
        /// <summary>
        /// 寫入錯誤資料
        /// </summary>
        /// <param name="data"></param>
        /// <returns></returns>
        Task WriteErrorAsync(string data);
    }

參考文獻

ASP.NET Core+Vue3 實現SignalR通訊
2023-11-04
ASP.NETVueSignalR
【SignalR全套系列】之在.Net Core 中實現SignalR實時通訊
2022-06-09
SignalR
ASP.NET Core的實時庫: SignalR簡介及使用
2018-08-23
ASP.NETSignalR
ASP.NET Core的實時庫: SignalR -- 預備知識
2018-08-21
ASP.NETSignalR
實時web應用方案——SignalR（.net core）
2020-06-26
WebSignalR
ASP.NET Core Web API 與 SSL
2018-06-20
ASP.NETWebAPI
使用websocket連線（對接）asp.net core signalr
2020-10-24
WebASP.NETSignalR
ASP.NET Core中的中介軟體及其工作原理
2021-01-05
ASP.NET
jwt-在asp.net core中的使用jwt
2021-07-01
JWTASP.NET
ASP.NET Core 裝X利器SignalR：電子畫板
2019-02-16
ASP.NETSignalR
Asp.Net Core使用SignalR進行服務間呼叫
2018-12-21
ASP.NETSignalR
【ASP.NET Core】使用SignalR推送伺服器日誌
2024-01-01
ASP.NETSignalR伺服器
在Keycloak中實現多租戶並在ASP.NET Core下進行驗證
2024-04-06
ASP.NET
在 ASP.NET Core 中禁用HTTPS
2019-10-10
ASP.NETHTTP
SSH 的原理與應用
2020-10-22
IoC在ASP.NET Web API中的應用
2021-09-09
ASP.NETWebAPI
AQS與JUC中的鎖實現原理
2018-08-31
AQS
springboot中擴充套件ModelAndView實現asp.net core mvc的ActionResult效果
2021-02-06
Spring Boot套件ViewASP.NETMVC
如何在 ASP.Net Core 中實現健康檢查
2021-03-15
ASP.NET
ASP.NET Core Web API下基於Keycloak的多租戶使用者授權的實現
2024-04-22
ASP.NETWebAPI
堆的原理與實現
2021-09-21
【asp.net core 系列】14 .net core 中的IOC
2020-06-28
ASP.NET
ASP.NET Core 中的快取
2018-08-15
ASP.NET快取
聊聊ASP.NET Core中的配置
2021-02-20
ASP.NET
【asp.net core 系列】- 11 Service層的實現樣板
2020-06-21
ASP.NET
Thunk程式的實現原理以及在iOS中的應用
2019-01-31
iOS
.NET平臺系列16 .NET5/Asp.Net Core 在全球Web框架權威效能測試 Web Framework Benchmarks 中的吊炸天表現
2021-06-07
ASP.NETWeb框架Framework
ASP.NET Core - JWT認證實現
2021-01-17
ASP.NETJWT
Redis在Web專案中的應用與實踐
2019-02-17
RedisWeb
Redis 在 Web 專案中的應用與實踐
2019-02-21
RedisWeb
在.NET Core 中實現健康檢查
2021-01-24
SignalR簡版web聊天室（實現過程分析篇）
2019-05-11
SignalRWeb
MVC模式在Java Web應用程式中的實現
2020-04-07
MVC模式JavaWeb
剖析漢字描紅在flutter中的實現原理
2021-09-02
Flutter
ASP.NET Core Web API 索引 (更新Redis in .NET Core)
2018-06-13
ASP.NETWebAPI索引Redis
ASP.NET Core Web API 介面限流
2023-03-09
ASP.NETWebAPI
【asp.net core 系列】8 實戰之利用 EF Core 完成資料操作層的實現
2020-06-09
ASP.NET
淺談ASP.NET Core中IOC與DI的理解和使用
2019-07-02
ASP.NET