# SSH MCP 服务

SSH MCP 是一个 MCP Server，用于把 WebShell 网关能力封装成 MCP 工具并通过 HTTP 提供给客户端（如 LangChain 原生 tools）。它会调用 WebShell 网关的 API 来获取目标列表与创建一次性 WebShell 会话链接。

## 功能概览

- 提供 MCP HTTP 端点：/mcp 与 /stream
- 工具能力：list_ssh_targets、create_ssh_web_terminal、open_ssh_terminal
- 通过 HTTP API 连接内联 WebShell 网关

## 架构与主要逻辑

- 进程模型：单 Node.js 进程同时承载 MCP Server 与内联 WebShell Gateway
- 数据存储：MySQL 保存 SSH 目标与会话历史记录
- 典型调用链：
  - list_ssh_targets：从 MySQL 读取目标表并返回结构化 JSON
  - create_ssh_web_terminal：在数据库中生成一次性会话记录，返回一次性 WebShell 会话链接
  - open_ssh_terminal：根据用户输入匹配 SSH 目标，复用 create_ssh_web_terminal 逻辑返回会话链接
- 网络与端口（Docker Compose 部署）：
  - mysql 服务：提供 3306 端口，ssh-mcp 容器内通过主机名 mysql 访问
  - ssh-mcp 服务：对外暴露 3001（MCP 控制台 + HTTP 端点）和 9100（WebShell 会话页）
  - 容器内部 MCP 通过 `http://localhost:9100` 调用内联 WebShell Gateway

## 项目目录结构

```
ssh-mcp/
├── .env                      # 环境变量配置
├── Dockerfile                 # Docker 镜像构建文件
├── README.md                  # 项目说明文档
├── docker-compose.yml         # Docker Compose 配置
├── package.json               # Node.js 项目配置
├── package-lock.json          # 依赖版本锁定文件
├── tsconfig.json              # TypeScript 配置
├── dist/                      # 编译输出目录
├── node_modules/              # Node.js 依赖包
├── public/                    # 公共静态资源目录
│   └── index.html
└── src/                       # 源代码目录
    ├── index.ts               # 入口文件：MCP Server 主逻辑
    └── webshell-gateway/      # 内联 WebShell Gateway 模块
        ├── index.ts           # Gateway 主逻辑（HTTP/WS 服务）
        └── db.ts              # 数据库操作（SSH 目标与会话管理）
```

**目录说明：**

| 文件/目录 | 说明 |
|-----------|------|
| `package.json` | NPM 项目配置，包含依赖和脚本命令 |
| `tsconfig.json` | TypeScript 编译配置 |
| `Dockerfile` | 用于构建 Docker 镜像 |
| `docker-compose.yml` | 用于编排 Docker 容器 |
| `.env` | 环境变量配置文件 |
| `src/` | TypeScript 源代码目录 |
| `public/` | 静态资源目录（WebShell 终端页面） |
| `dist/` | 编译后的输出目录 |

## 快速开始

### 方式一：Docker Compose（推荐，用于生产与测试环境）

在 ssh-mcp 目录执行：

```bash
docker compose up -d --build
```

该命令会启动两个容器：

- mysql：WebShell 网关使用的 MySQL 数据库
- ssh-mcp：包含 MCP Server 与内联 WebShell Gateway

默认行为与端口：

- ssh-mcp 对外暴露 3001（MCP 控制台 + /mcp、/stream 等 HTTP 端点）
- ssh-mcp 对外暴露 9100（WebShell 会话页，对应一次性会话链接）
- 容器内部 MCP 通过 `SSH_WEBSHELL_API_URL=http://localhost:9100` 调用内联 Gateway
- 容器内部访问数据库使用主机名 `mysql` 与端口 `3306`

如需调整端口或数据库账号，请编辑
[docker-compose.yml](file:///c:/Users/Administrator/Desktop/jenkins-mcp/ssh-mcp/docker-compose.yml)
或通过环境变量覆盖。

### 方式二：Docker build/run（单容器，依赖外部 MySQL）

```bash
docker build -t ssh-mcp:latest .
docker run -d \
  -p 3001:3001 \
  -e PORT=3001 \
  -e SSH_WEBSHELL_API_URL=http://localhost:9100 \
  -e MOCK_WEBSHELL_PORT=9100 \
  -e WEBSHELL_DB_HOST=<你的 MySQL 主机地址> \
  -e WEBSHELL_DB_PORT=3306 \
  -e WEBSHELL_DB_USER=webshell \
  -e WEBSHELL_DB_PASSWORD=webshell_pass \
  -e WEBSHELL_DB_DATABASE=webshell \
  --name ssh-mcp \
  ssh-mcp:latest
```

### 方式三：本地运行

```bash
npm install
npm run build
npm start
```

## 配置说明

### 服务端口

- PORT：MCP HTTP 服务端口，默认 3001

### WebShell 网关连接

- SSH_WEBSHELL_API_URL：WebShell 网关地址，默认建议为 `http://localhost:9100`
- SSH_WEBSHELL_HTTP_TIMEOUT_MS：请求超时，默认 15000
- SSH_WEBSHELL_API_TOKEN：调用 WebShell 网关受保护接口时使用的固定 API Token（内联 Gateway 当前不会强制校验，仅用于兼容旧配置）

### 内联 WebShell Gateway（已合并进 ssh-mcp）

从当前版本起，WebShell Gateway 的核心能力已经内联到 ssh-mcp 中，由同一进程启动并监听独立端口。

- MOCK_WEBSHELL_PORT：内联 WebShell Gateway HTTP/WS 端口，默认 9100
- WEBSHELL_PUBLIC_BASE_URL：会话链接对外暴露的基础地址，默认 `http://localhost:9100`

### 数据库连接（用于存储 SSH 目标与会话历史）

内联 Gateway 使用 MySQL 存储 SSH 目标和会话历史记录，对应原 WebShell Gateway 的数据结构：

- WEBSHELL_DB_HOST：数据库主机，默认 `mysql`
- WEBSHELL_DB_PORT：数据库端口，默认 `3306`
- WEBSHELL_DB_USER：数据库用户名，默认 `webshell`
- WEBSHELL_DB_PASSWORD：数据库密码，默认 `webshell_pass`
- WEBSHELL_DB_DATABASE：数据库名称，默认 `webshell`

### 数据库表结构

#### targets 表（SSH 目标）

| 字段名     | 类型            | 说明                     | 备注                           |
| ---------- | --------------- | ------------------------ | ------------------------------ |
| id         | varchar(191)    | 目标唯一 ID              | MCP 工具与 UI 侧使用此 ID 标识 |
| host       | varchar(255)    | SSH 主机地址或 IP        |                                |
| port       | int             | SSH 端口                 | 默认为 22                      |
| username   | varchar(255)    | 登录用户名               |                                |
| password   | text (nullable) | 登录密码                 | 可为空，生产建议优先用密钥认证 |
| privateKey | text (nullable) | 私钥内容（PEM）          | 可为空                          |
| name       | varchar(255)    | 目标展示名称（别名）     | 可为空                          |

索引：

- 主键：`PRIMARY KEY (id)`

#### sessions 表（SSH 会话历史 / 审计日志）

| 字段名    | 类型                                           | 说明                      | 备注                                     |
| --------- | ---------------------------------------------- | ------------------------- | ---------------------------------------- |
| id        | varchar(191)                                   | 会话 ID                   | 同时用于 `/session/:id` 链接中的 ID      |
| targetId  | varchar(191)                                   | 关联的 SSH 目标 ID        | 对应 `targets.id`                        |
| targetName| varchar(255)                                   | 目标名称冗余              | 便于审计查询                             |
| host      | varchar(255)                                   | 连接时使用的主机名或 IP   | 冗余存储，避免后续目标变更影响审计      |
| port      | int                                            | 连接时使用的端口          | 冗余存储                                 |
| username  | varchar(255)                                   | 连接时使用的账户名        | 冗余存储                                 |
| startTime | datetime                                       | 会话开始时间              | 创建会话链接时写入                       |
| endTime   | datetime (nullable)                            | 会话结束时间              | WebSocket 关闭或异常时更新               |
| status    | enum('connected','disconnected','error')       | 会话最终状态              | `connected`/`disconnected`/`error`       |
| reason    | text (nullable)                                | 创建会话时的原因说明      | 由上游调用方传入，用于审计               |

索引：

- `idx_targetId (targetId)`
- `idx_startTime (startTime)`

#### users 表（预留用户信息）

| 字段名      | 类型         | 说明               | 备注                           |
| ----------- | ------------ | ------------------ | ------------------------------ |
| id          | varchar(191) | 用户唯一 ID        |                                |
| username    | varchar(191) | 用户名             | 唯一索引                       |
| password_hash | varchar(255)| 密码哈希          | 存储加密后的口令               |
| provider    | varchar(32)  | 认证提供方标识     | 当前默认值为 `local`           |
| created_at  | datetime     | 创建时间           |                                |

索引：

- 主键：`PRIMARY KEY (id)`
- `idx_username (username)`

> 说明：当前内联 Gateway 尚未暴露基于 users 表的对外登录接口，该表为未来用户体系预留。

#### auth_sessions 表（预留认证会话）

| 字段名    | 类型         | 说明                     | 备注                                   |
| --------- | ------------ | ------------------------ | -------------------------------------- |
| token     | varchar(191) | 会话 Token（主键）       | 用于标识登录态或访问会话               |
| username  | varchar(191) | 关联的用户名             | 对应 `users.username`                  |
| provider  | varchar(32)  | 认证提供方标识           | 当前默认值为 `local`                   |
| created_at| datetime     | 会话创建时间             |                                        |
| expires_at| datetime     | 会话过期时间             | 用于失效判断和定期清理                 |

索引：

- 主键：`PRIMARY KEY (token)`
- `idx_username (username)`
- `idx_expires_at (expires_at)`

> 说明：auth_sessions 表用于记录认证会话 Token，`expires_at` 字段用于决定会话是否过期。当前代码中已提供按过期时间自动清理的能力，实际登录流程可在未来接入。

### 生产环境配置建议

- 数据库账号与密码：
  - 强烈建议在生产环境中为数据库创建独立账号，并替换默认密码
  - 建议限制数据库账号仅具备所需最小权限（最小权限原则）
- WebShell 会话访问地址：
  - 将 WEBSHELL_PUBLIC_BASE_URL 设置为经过反向代理或网关暴露的 HTTPS 域名
  - 对公网暴露时建议配合 WAF、IP 白名单等防护手段
- API 调用安全：
  - 如需在 MCP 侧做额外鉴权，可结合上层调用方实现 RBAC 或 Token 校验
  - SSH_WEBSHELL_API_TOKEN 可预留用于与外部 Gateway 集成时的签名/鉴权
- 资源与容量规划：
  - 为 MySQL 分配独立存储卷（docker-compose.yml 已默认配置）
  - 根据实际会话量评估连接数与超时配置，合理设置 SSH_WEBSHELL_HTTP_TIMEOUT_MS

## MCP 端点

- POST /mcp
- POST /stream

## 内联 WebShell Gateway 使用方式

### 1. 准备 MySQL

可以使用 Docker 启动一个 MySQL 实例（示例）：

```bash
docker run -d \
  --name webshell-mysql \
  -e MYSQL_ROOT_PASSWORD=webshell_root \
  -e MYSQL_DATABASE=webshell \
  -e MYSQL_USER=webshell \
  -e MYSQL_PASSWORD=webshell_pass \
  -p 3306:3306 \
  mysql:8.0
```

### 2. 配置 ssh-mcp 环境变量

在 ssh-mcp 目录下创建或编辑 `.env`（或通过 Docker 环境变量注入）：

```env
PORT=3001

# MCP 通过 HTTP 调用内联 Gateway
SSH_WEBSHELL_API_URL=http://localhost:9100
SSH_WEBSHELL_HTTP_TIMEOUT_MS=15000

# 内联 Gateway 监听端口与对外访问地址
MOCK_WEBSHELL_PORT=9100
WEBSHELL_PUBLIC_BASE_URL=http://localhost:9100

# MySQL 连接
WEBSHELL_DB_HOST=127.0.0.1
WEBSHELL_DB_PORT=3306
WEBSHELL_DB_USER=webshell
WEBSHELL_DB_PASSWORD=webshell_pass
WEBSHELL_DB_DATABASE=webshell
```

### 3. 启动服务并访问

```bash
cd ssh-mcp
npm install
npm run build
npm start
```

- MCP 控制台 UI：访问 `http://localhost:3001`
- 内联 WebShell Gateway 会话页：通过 MCP 工具返回的一次性会话链接，例如 `http://localhost:9100/session/<uuid>`

在 Docker Compose 场景下，默认映射为宿主机的 `http://localhost:3001` 与 `http://localhost:9100`，如修改端口请同步更新 WEBSHELL_PUBLIC_BASE_URL。

## 会话与失效策略

### WebShell SSH 会话（/session/:id）

- 会话生成：
  - MCP 工具调用内联 Gateway 的 `/api/session` 接口创建会话。
  - 内联 Gateway 为每次请求生成随机 UUID 作为 `sessionId`。
  - 会话信息写入两处：
    - 进程内内存 Map：键为 `sessionId`，值包含 `targetId`、`reason`、`createdAt` 等。
    - 数据库 `sessions` 表：写入一条会话历史记录（startTime、status、reason 等）。
- 会话访问：
  - 浏览器访问 `/session/<sessionId>` 时：
    - 如果内存 Map 中存在对应条目，则渲染 WebShell 终端页面并建立 WebSocket `/ws?sessionId=...`。
    - 如果不存在，则返回 404 文本：`会话不存在或已过期`。
- 会话结束：
  - WebSocket 正常关闭时：
    - 内联 Gateway 调用 `updateSessionEndTime`，将 `sessions` 表中的 `endTime` 更新为当前时间，`status` 置为 `disconnected`。
  - 连接远程主机出错时：
    - 会话记录的 `status` 置为 `error`，`endTime` 同样更新为当前时间。
- 失效策略（当前版本）：
  - `sessionId` 仅保存在内存 Map 中，不会被持久化用于恢复实时 SSH 通道。
  - 服务重启后内存 Map 清空，所有历史链接都会返回“会话不存在或已过期”。
  - 当前未对 `sessionId` 设置基于时间的自动 TTL 清理，在服务不重启的情况下同一链接可被多次访问。
  - 建议上层调用方将会话链接视为短期凭证，不长期缓存或下发到不可信环境。

### 认证会话（auth_sessions）

- auth_sessions 表用于保存认证会话 Token（预留能力）：
  - `token`：会话 Token 主键。
  - `username` / `provider`：标识对应用户与认证来源。
  - `expires_at`：过期时间。
- 失效判断：
  - 在读取会话时，如果 `expires_at <= 当前时间`，会被视为已过期并立刻从表中删除。
  - 提供批量清理能力，用于定期清理历史过期会话。
- 当前版本尚未对外暴露基于该表的登录接口，后续如启用认证体系，可基于此表实现登录态管理。

## 工具输出格式

### list_ssh_targets

输出为纯 JSON：

```json
{"targets":[{"index":1,"id":"prod-a","name":"prod","host":"8.140.200.0","port":22,"username":"root"}]}
```

失败时输出：

```json
{"error":"获取目标列表失败: ...","targets":[]}
```

### create_ssh_web_terminal

输出文本中包含一次性会话链接。

### open_ssh_terminal

输出文本中包含一次性会话链接，并包含匹配到的目标信息。

## 扩展方式

在 src/index.ts 中新增 MCP 工具，建议遵循以下步骤：

1. 通过 mcpServer.registerTool 定义工具名称、描述与 inputSchema
2. 在工具实现中调用 WebShell 网关 API 或其它后端服务
3. 返回结构化 JSON 或稳定格式的文本输出
4. 执行 npm run build 生成 dist

## 开发注意事项

- Node.js 版本：
  - 建议使用 Node.js 18+，以获得更好的性能与长期支持
- 本地开发：
  - 使用 `npm run dev` 以 TS 源码方式启动，默认监听 `PORT` 与内联 Gateway 端口
  - 修改 TypeScript 源码后无需手动编译，`tsx` 会实时加载
- 类型与质量检查：
  - 提交代码前建议执行 `npm run type-check` 确认类型检查无误
  - 若项目新增脚本或配置，请同步更新本文档相关章节
- 与数据库联调：
  - 本地调试时推荐使用 Docker 启动 MySQL，并通过 WEBSHELL_DB_HOST 指向容器或本机
  - 避免在生产数据库直接进行开发调试操作

## 日志与审计字段

### 会话审计（sessions 表）

`sessions` 表既承担会话历史记录，也可以作为基础的审计日志，核心字段含义如下：

- `id`：会话唯一标识，等同于 `/session/:id` 中的路径参数。
- `targetId` / `targetName`：关联的 SSH 目标 ID 和冗余名称，便于按业务目标检索。
- `host` / `port` / `username`：会话建立时实际使用的连接参数，冗余存储，避免目标后续修改影响历史数据。
- `startTime` / `endTime`：会话起止时间，可用于统计使用时长和活跃度。
- `status`：`connected` / `disconnected` / `error`，代表会话最终状态。
- `reason`：上游调用方传入的业务原因描述，例如工单号、变更单号等，建议生产环境按规范填充便于审计。

在生产环境中，可以基于 sessions 表构建报表或对接审计系统，例如统计单用户、单目标或单时间区间内的会话次数与失败率。

### UI 最近会话列表（/ui/recent-sessions）

MCP UI 通过 `/ui/recent-sessions` 接口返回内存中最近会话列表，其数据结构为：

- `id`：最近会话记录的内部 ID，与数据库 sessions 表的 `id` 不同。
- `targetId`：目标 ID，对应 `targets.id`。
- `reason`：创建会话时填写的原因。
- `sessionUrl`：内联 Gateway 返回的 WebShell 会话链接。
- `createdAt`：记录创建时间（毫秒时间戳）。

recentSessions 列表只保存在内存中，默认只保留最近 20 条记录，便于在 UI 侧快速查看最新发起的会话。

### 服务启动与错误日志（标准输出）

当前服务的日志主要通过标准输出/错误输出产生，典型包括：

- MCP HTTP 服务启动日志：
  - `SSH MCP HTTP server listening on http://localhost:<port>`
- 内联 WebShell Gateway 启动日志：
  - `SSH WebShell gateway listening on http://localhost:<MOCK_WEBSHELL_PORT>`
- HTTP Server 错误：
  - 在监听端口出错时，会将错误信息写入标准错误输出并退出进程。

生产环境中通常通过 Docker 日志、systemd 日志或容器编排平台（如 Kubernetes）集中采集上述输出，如需要更细粒度的结构化日志，可以在现有基础上引入统一的日志框架并扩展记录字段。

## 常见问题

### 端口被占用

- 启动失败并提示端口占用时：
  - 修改 PORT，或停止占用 3001 端口的进程后再启动
  - 若 Docker 场景下 3001/9100 被占用，可在 docker-compose.yml 中调整宿主机端口映射

### WebShell 网关不可达或会话链接打不开

- 检查 SSH_WEBSHELL_API_URL：
  - Docker Compose 默认在容器内使用 `http://localhost:9100`，无需修改
  - 若自行拆分 Gateway，请确保 URL 指向可访问的 HTTP 服务
- 检查会话访问地址：
  - 确认 WEBSHELL_PUBLIC_BASE_URL 与对外访问地址一致
  - 宿主机上确认 9100 端口已映射且未被防火墙拦截

### 无法连接 MySQL 或 list_ssh_targets 无返回数据

- 检查数据库连接配置：
  - 确认 WEBSHELL_DB_HOST/PORT/USER/PASSWORD/DATABASE 与实际数据库一致
  - Docker Compose 场景下应保持 WEBSHELL_DB_HOST=mysql
- 检查数据库服务状态：
  - 查看容器日志：`docker compose logs mysql`
  - 确认数据库已初始化完成且能正常接受连接
- 检查数据是否存在：
  - 登录数据库确认目标表中已写入 SSH 目标数据

### 容器反复重启

- 查看 ssh-mcp 容器日志：`docker compose logs ssh-mcp`
- 常见原因：
  - 数据库连接失败（账号密码不正确或网络不可达）
  - 环境变量缺失或配置错误
  - 宿主机资源不足导致进程被杀死