Qingcloud Terminal 使用指南

简介

Qingcloud Terminal 是一个基于 Web 的终端工具，统一我们业务中各种终端实现，以方便使用和扩展新的类型。

本项目 UI 部分依赖 @pitrix/portal-ui, 业务集成方无需关心。它提供了两种业务打包方式, 一种是直接引入, 另一种是通过代理模式。

快速开始 (代理模式集成)

1. 工程 package.json 添加依赖 @pitrix/terminal
2. 在业务项目中引入 proxy 代码。 它是一段简单的helper函数，用于 parent 与 terminal 之间的通信。 它也是唯一段会被打包进现有业务中的代码。

import { init, createNewSession } from '@pitrix/terminal/lib/proxy';

// 初始一次, 传入必要的配置参数, 详见下方 API 说明
init({ entryUrl: '/terminal/' });

// 业务中任何需要触发打开终端的地方调用, 说见下方 API 说明
createNewSession({ type: 'ssh'})

3. 集成独立 entry html 页面(它才是真正的终端页面)。 业务方需要在router中添加一个路由提页一个 html 页面即可。 例如:

  <div id="q-terminal"></div>
  <script src="./dist/index.js"></script>
  <script>
    QTerminal.init({
      container: "#q-terminal",
      terminal_conn_mode: 'proxy',
    })
  </script>

API

注意: Entry 页 API 与 Proxy API 提供了一致使用方式，但它们本质是有些不同的，主要取决于业务的打包方式。在 init 与 createNewSession 时，都可以传入BaseSessionOptions它们的覆盖关系如下: entry init < proxy init < createNewSession, 即 createNewSession 传入有最高优化级。

终端 entry 页面

import { init, createNewSession } from '@pitrix/terminal';

// 1. init()
type BaseSessionOptions = {
  terminal_conn_mode?: 'proxy' | 'proxy-compatible' | 'direct';     // 当务中配置的终端连接模式, 默认为 direct
  user_id?: string;                                                 // 当前登录的 id
  project_id?: string;                                              // 当前项目的 id
  is_cluster_node?: number;                                         // 是否是集群节点, 1: 是, 0: 否
};

type InitOptions = {
  container?: string | Element;                                     // 承载终端 UI 的 DOM 容器
} & BaseSessionOptions;

init(options: InitOptions)

// 2. createNewSession()
type SessionOptions = {
  type: 'vnc' | 'lxc' | 'sol' | 'webssh' | 'webterm';                           // 支持的终端类型
  instance_id: string;                                              // 主机实例 id
  zone: string;                                                     // 主机所在区域
  // for webssh (deprecated)
  verification_method?: 0 | 1;                                      // 0: password, 1: private key
  username?: string;
  passwd?: string;
  key?: string;
} & BaseSessionOptions;

createNewSession(options: SessionOptions)

proxy API

import { init, createNewSession } from '@pitrix/terminal/lib/proxy';

// 1. init()
type BaseSessionOptions = {
  terminal_conn_mode?: 'proxy' | 'proxy-compatible' | 'direct';     // 当务中配置的终端连接模式, 默认为 direct
  user_id?: string;                                                 // 当前登录的 id
  project_id?: string;                                              // 当前项目的 id
  is_cluster_node?: number;                                         // 是否是集群节点, 1: 是, 0: 否
};

type ProxyOptions = {
  entryUrl: string                                                  // 终端 entry 页面的 url
} & BaseSessionOptions;

init(options: ProxyOptions)

// 2. createNewSession()
type SessionOptions = {
  type: 'vnc' | 'lxc' | 'sol' | 'webssh' | 'webterm';               // 支持的终端类型
  instance_id: string;                                              // 主机实例 id
  zone: string;                                                     // 主机所在区域
  // for webssh (deprecated)
  verification_method?: 0 | 1;                                      // 0: password, 1: private key
  username?: string;
  passwd?: string;
  key?: string;
} & BaseSessionOptions;

createNewSession(options: SessionOptions)