billchurch/webssh2

WebSSH2

基于ssh2、socket.io、xterm.js和express的Web SSH客户端，提供HTML5网页终端模拟器和SSH客户端功能。通过在主机上使用SSH2作为客户端，将WebSocket/Socket.io连接代理到SSH2服务器，实现网页端SSH访问。

!WebSSH2 v0.2.0演示

镜像概述和主要用途

WebSSH2 Docker镜像封装了Web SSH客户端应用，允许用户通过浏览器访问和管理SSH服务器。无需安装本地SSH客户端，只需通过网页即可建立SSH连接，适用于远程服务器管理、跨平台访问等场景。

核心功能和特性

• Web-based终端：使用xterm.js提供HTML5终端模拟器，支持终端常用功能
• WebSocket代理：通过socket.io和WebSocket实现浏览器与SSH服务器的通信
• 灵活配置：支持通过环境变量、配置文件或请求参数自定义连接参数
• 跨域支持：可配置CORS源，限制允许的连接来源
• 客户端日志：支持在浏览器中记录终端输出并下载日志

使用场景和适用范围

• 远程服务器管理：无需安装本地SSH客户端，通过浏览器即可访问
• 共享终端访问：为团队提供统一的网页SSH入口
• 受限环境访问：在无法安装本地SSH客户端的环境中使用
• 嵌入式系统管理：通过网页界面管理嵌入式设备的SSH服务

Docker使用方法

镜像版本说明

• billchurch/webssh2:latest：最新稳定版，对应官方最新发布版本
• billchurch/webssh2:<版本号>：指定版本，如0.4.6、0.4.7-alpha.2

拉取镜像

bash
# 拉取最新稳定版
docker pull docker.xuanyuan.run/billchurch/webssh2

# 拉取指定版本
docker pull docker.xuanyuan.run/billchurch/webssh2:0.4.6

运行容器

基本运行

bash
docker run --name webssh2 -d -p 2222:2222 docker.xuanyuan.run/billchurch/webssh2

挂载自定义配置文件

bash
# 先准备配置文件（可从https://github.com/billchurch/webssh2/blob/0.4.6/app/config.json.sample获取模板）
docker run --name webssh2 -d -p 2222:2222 -v $(pwd)/config.json:/usr/src/config.json docker.xuanyuan.run/billchurch/webssh2

构建本地镜像（如需修改源码）

bash
# 克隆仓库
git clone https://github.com/billchurch/webssh2.git
cd webssh2
git checkout current  # 或指定版本标签

# 构建镜像
docker build -t webssh2 .

# 运行本地镜像
docker run --name docker.xuanyuan.run/webssh2 -d -p 2222:2222 webssh2

配置说明

环境变量

环境变量会覆盖config.json中的对应配置，适用于容器化环境：

POST请求参数（测试用）

通过POST请求传递连接参数：

GET请求参数

通过URL查询参数传递连接参数（与POST参数类似）：

示例：http://localhost:2222/ssh/host/192.168.1.1?port=2244&header=My%20Header&headerBackground=red

配置文件（config.json）

配置文件包含详细自定义选项，JSON格式：

json
{
  "listen": {
    "ip": "127.0.0.1",
    "port": 2222
  },
  "socketio": {
    "serveClient": false,
    "path": "/ssh/socket.io",
    "origins": "localhost:2222"
  },
  "user": {
    "name": null,
    "password": null,
    "overridebasic": false
  },
  "ssh": {
    "host": null,
    "port": 22,
    "term": "vt100",
    "readyTimeout": 20000
  },
  "terminal": {
    "cursorBlink": true,
    "scrollback": 10000,
    "tabStopWidth": 8,
    "bellStyle": "sound",
    "fontSize": 14
  }
}

关键配置项说明：

• listen.ip/port：服务监听地址和端口
• socketio.origins：限制跨域请求来源，增强安全性
• user.overridebasic：是否忽略客户端Basic Auth头，使用配置的用户名密码
• ssh.readyTimeout：SSH连接超时时间
• terminal.scrollback：终端回滚缓冲区大小，影响可查看历史记录行数

客户端日志

点击状态栏的Start logging开始记录终端数据，记录开始后会显示Download log选项，可随时下载日志。点击Logging - STOP LOG停止记录，再次点击Start logging会覆盖当前日志（建议先下载）。

使用示例

访问部署后的WebSSH2服务：

http://localhost:2222/ssh/host/192.168.1.1?port=2244&header=My%20Header&headerBackground=red

访问后会通过HTTP Basic Auth提示输入SSH用户名和密码，验证通过后即可在浏览器中使用SSH终端。

系统要求

• Node.js v14.x及以上（容器化部署无需单独安装，镜像已包含）
• 浏览器需支持HTML5和WebSocket
• 服务端需开放对应端口（默认2222）的网络访问权限