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 中使用 SignalR
2017-10-28
ASP.NETSignalR
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 MVC 中使用 SignalR 實現推送功能
2013-11-13
ASP.NETMVCSignalR
ASP.NET Core Web API 與 SSL
2018-06-20
ASP.NETWebAPI
comet在asp.net中的實現
2014-05-11
ASP.NET
ASP.NET SignalR 與 LayIM2.0 配合輕鬆實現Web聊天室（十四）之漏掉的客服訊息
2016-09-07
ASP.NETSignalRWeb
ASP.NET Core中的中介軟體及其工作原理
2021-01-05
ASP.NET
ASP.NET SignalR 與 LayIM2.0 配合輕鬆實現Web聊天室實戰系列。開源啦！！！
2016-08-15
ASP.NETSignalRWeb
jwt-在asp.net core中的使用jwt
2021-07-01
JWTASP.NET
在 Azure 上部署 Asp.NET Core Web App
2017-04-16
ASP.NETWebAPP
AQS與JUC中的鎖實現原理
2018-08-31
AQS
SSH 的原理與應用
2020-10-22
使用websocket連線（對接）asp.net core signalr
2020-10-24
WebASP.NETSignalR
在Asp.Net中實現類似DWR的功能
2009-10-23
ASP.NET
在Keycloak中實現多租戶並在ASP.NET Core下進行驗證
2024-04-06
ASP.NET
如何在 ASP.Net Core 中實現健康檢查
2021-03-15
ASP.NET
在 ASP.NET Core 中禁用HTTPS
2019-10-10
ASP.NETHTTP
SignalR實現web線上即時聊天（C#）
2016-05-11
SignalRWebC#
在.NET Core 中實現健康檢查
2021-01-24
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伺服器
IoC在ASP.NET Web API中的應用
2021-09-09
ASP.NETWebAPI
web service實現原理與非同步呼叫
2010-05-18
Web非同步
在asp.net中ListView的交替背景顏色實現
2010-02-25
ASP.NETView
Thunk程式的實現原理以及在iOS中的應用
2019-01-31
iOS
堆的原理與實現
2021-09-21
ASP.NET SignalR 與 LayIM2.0 配合輕鬆實現Web聊天室（六）之 Layim原始碼改造右鍵選單--好友、組管理功能的實現。
2016-08-15
ASP.NETSignalRWeb原始碼
ASP.NET SignalR 與 LayIM2.0 配合輕鬆實現Web聊天室（十三）之附加功能-自定義皮膚
2016-09-06
ASP.NETSignalRWeb
ASP.NET SignalR 與 LayIM2.0 配合輕鬆實現Web聊天室（三）之實現單聊，群聊，傳送圖片，檔案。
2016-08-09
ASP.NETSignalRWeb
【asp.net core 系列】14 .net core 中的IOC
2020-06-28
ASP.NET
Redis 在 Web 專案中的應用與實踐
2019-02-21
RedisWeb
Redis在Web專案中的應用與實踐
2019-02-17
RedisWeb
剖析漢字描紅在flutter中的實現原理
2021-09-02
Flutter