# Qingcloud Terminal 使用指南

## 简介

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

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

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

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

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

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

  // 业务中任何需要触发打开终端的地方调用, 说见下方 API 说明
  createNewSession({ type: 'ssh'})
  ```
3. 集成独立 entry html 页面(它才是真正的终端页面)。 业务方需要在`router`中添加一个路由提页一个 html 页面即可。 例如:

  ```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 页面
```ts
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
```ts
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)
```