# 黑白

**Repository Path**: organics/heibai

## Basic Information

- **Project Name**: 黑白
- **Description**: Web Terminal
- **Primary Language**: Go
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-10-03
- **Last Updated**: 2022-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 黑白

黑白 是一个灵活的 Web Terminal 代理服务，可以与 [Xterm](https://xtermjs.org/) 轻松集成。
支持接入 Linux SSH，Docker Container，Kubernetes Pod 等多种终端，并以统一的风格在您的浏览器上呈现。

- Support Linux SSH
- Support Docker Container
- Support Kubernetes Pod (beta)

## Features

- 采用 [木兰宽松许可证](http://license.coscl.org.cn/MulanPSL2) 个人和企业都能轻松使用和再分发，避免了使用商用Terminal时获取许可的麻烦。
- 极简的环境需求，只需要一个操作系统和一个现代浏览器就可以快速使用。您甚至不需要安装，也不会对您的系统造成任何修改，即下即用，用完即删。
- 非常灵活的扩展，您可以自己实现页面，甚至是开发自己的连接认证中心，并于黑白轻松对接。

## Getting Started

### 只需3步

1. 下载最新版本，这里以Linux为例，如果是Windows可以在当前项目的release目录寻找对应版本。

```shell
curl -LJO https://gitee.com/organics/heibai/releases/download/release/1.0.2/heibai_linux_amd64
```

2. Run！注意：被连接的主机需要支持SSH，并且连接用户需要有外部连接权限。这里以连接 127.0.0.1 22 使用私钥连接为例

```shell
./heibai_linux_amd64 -type host -host 127.0.0.1 -port 22 -user root -prikey ./id_rsa.key
```

3. 打开您的浏览器访问

```shell
http://127.0.0.1:22333
```

![](https://gitee.com/organics/heibai/raw/main/screenshot/chrome_CYo8wOSV3L.gif)

## Advanced Usage

### Optional

```shell
./heibai_linux_amd64 -help

Usage of C:\Users\Tony_PC\AppData\Local\Temp\go-build3517517535\b001\exe\heibai.exe:
  -serveport
        服务监听端口 (default "22333")
  -ui
        启用代理Terminal页面 (default "true")
  -type
        服务如何获取主机信息. opt:(host,docker,kube,serve) (default "host")
  -serve
        当需要使用自己的连接配置中心时,程序会通过GET请求访问该服务地址获取连接信息 like:(http://hostname:port?token=id&param=xxx)
  -host
        您要访问的主机
  -port
        您要访问的主机的端口 (default "0")
  -user
        主机的用户名
  -pass
        主机密码
  -prikey
        主机的私钥
  -cid
        docker容器的容器ID
  -pnamespace
        kubernetes namespace
  -pname
        kubernetes pod
```

### type

type参数决定了黑白的工作方式，有几个可选值 host,docker,kube,serve 默认：host

| 可选值  | 配合参数                                            | 会发生什么                                                                                        |
|--------|-------------------------------------------------|----------------------------------------------------------------------------------------------|
| host   | -host<br/>-port<br/>-user<br/>-pass<br/>-prikey | 连接一个支持SSH客户端的主机                                                                              |
| docker | -cid                                            | 连接一个docker容器。没有-host参数，这使程序只能工作在有docker engine的主机上，程序会自动读取本地环境变量并连接docker容器                  |
| kube   | -pnamespace<br/>-pname                          | 连接一个kubernetes pod。没有-host参数，这使程序只能工作在有kubernetes server的主机上，程序会自动读取本地环境变量并连接kubernetes pod  |
| serve  | -serve                                          | 以服务模式工作。程序会通过GET请求访问-serve服务地址获取连接信息。例如：-serve http://hostname:port?token=id&param=xxx       |

- 为什么程序只支持连接一个主机而不是多个？<br/>
  - 黑白的本质只是一个SSH客户端代理工具，并不具备主机的管理能力，也不存储主机的认证信息。如果您需要程序在一个实例下连接不同的主机，您需要自己管理您的连接信息，程序会携带您的主机token访问您配置的-serve服务并建立连接。<br/>
- 为什么当 type=docker|kube 时程序只能部署在有这些基础设施的主机上?<br/>
  - 远程连接这些服务容器需要复杂的证书配置，也存在一定的安全限制。同样的，您也可以使用-serve配置您的连接信息中心，以达到远程访问这些基础设施的目的。