@pyrokine/mcp-ssh 2.0.2 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -19
- package/README_zh.md +94 -18
- package/dist/file-ops.d.ts +67 -5
- package/dist/file-ops.js +400 -81
- package/dist/pty-manager.d.ts +6 -0
- package/dist/pty-manager.js +19 -0
- package/dist/session-manager.d.ts +14 -0
- package/dist/session-manager.js +254 -78
- package/dist/tools/connection.js +106 -20
- package/dist/tools/exec.js +201 -9
- package/dist/tools/file.js +288 -8
- package/dist/tools/forward.js +2 -2
- package/dist/tools/pty.js +1 -1
- package/dist/tools/utils.js +9 -1
- package/dist/types.d.ts +38 -0
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
English | [中文](README_zh.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://nodejs.org/)
|
|
@@ -88,7 +88,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
88
88
|
}
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
## Available Tools (
|
|
91
|
+
## Available Tools (30 tools)
|
|
92
92
|
|
|
93
93
|
### Connection Management
|
|
94
94
|
|
|
@@ -110,6 +110,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
110
110
|
| `ssh_exec_batch` | Execute multiple commands sequentially |
|
|
111
111
|
| `ssh_exec_parallel` | Execute command on multiple hosts in parallel |
|
|
112
112
|
| `ssh_quick_exec` | One-shot: connect, execute, disconnect |
|
|
113
|
+
| `ssh_exec_script` | Upload and run a temporary remote script |
|
|
113
114
|
|
|
114
115
|
### File Operations
|
|
115
116
|
|
|
@@ -196,18 +197,48 @@ Execute the same command on multiple connected hosts:
|
|
|
196
197
|
### Basic: Connect and Execute
|
|
197
198
|
|
|
198
199
|
```
|
|
199
|
-
ssh_connect(host="
|
|
200
|
+
ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
|
|
200
201
|
ssh_exec(alias="myserver", command="ls -la /home")
|
|
201
202
|
ssh_disconnect(alias="myserver")
|
|
202
203
|
```
|
|
203
204
|
|
|
205
|
+
### Connection Templates and runAs
|
|
206
|
+
|
|
207
|
+
Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
|
|
208
|
+
template values.
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{
|
|
212
|
+
"app-dev": {
|
|
213
|
+
"host": "<server-host>",
|
|
214
|
+
"port": 22,
|
|
215
|
+
"user": "root",
|
|
216
|
+
"runAs": "appuser",
|
|
217
|
+
"defaultEnv": {
|
|
218
|
+
"APP_ENV": "dev"
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
ssh_connect(template="app-dev", alias="app-dev")
|
|
226
|
+
ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
|
|
227
|
+
ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
`ssh_connect` returns `identity`, `loginUser`, `runAs`, `reused`, `defaultEnvKeys`, `envKeys`, and `reusableSessions`
|
|
231
|
+
for already connected aliases with the same `user@host:port` identity. Reusing an alias for a different identity is
|
|
232
|
+
rejected with the existing and requested identities. Missing templates include available template names when they can be
|
|
233
|
+
loaded. Missing `configHost` returns SSH config candidates and suggests `ssh_config_list`.
|
|
234
|
+
|
|
204
235
|
### Jump Host (Bastion)
|
|
205
236
|
|
|
206
237
|
Connect to internal server via jump host:
|
|
207
238
|
|
|
208
239
|
```
|
|
209
240
|
ssh_connect(
|
|
210
|
-
host="
|
|
241
|
+
host="<internal-host>",
|
|
211
242
|
user="root",
|
|
212
243
|
keyPath="/home/.ssh/id_rsa",
|
|
213
244
|
alias="internal",
|
|
@@ -224,7 +255,7 @@ ssh_connect(
|
|
|
224
255
|
Perfect for scenarios where you SSH as root but need to run commands as another user:
|
|
225
256
|
|
|
226
257
|
```
|
|
227
|
-
1. ssh_connect(host="
|
|
258
|
+
1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
|
|
228
259
|
2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
|
|
229
260
|
// Output: appuser
|
|
230
261
|
```
|
|
@@ -233,6 +264,13 @@ By default, shell profile is loaded to ensure environment variables are availabl
|
|
|
233
264
|
non-interactive shell which doesn't execute rc files). Supports bash (`.bashrc`), zsh (`.zshrc`), and other shells (
|
|
234
265
|
`.profile`). Disable with `loadProfile=false` if not needed.
|
|
235
266
|
|
|
267
|
+
`ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
|
|
268
|
+
`resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
|
|
269
|
+
hints. Large output returns `stdoutHead`, `stdoutTail`, `stderrHead`, `stderrTail`, and `recommendedReadCommand`.
|
|
270
|
+
Timeout errors include the same head/tail fields from output produced before the timeout. Commands with destructive,
|
|
271
|
+
process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
|
|
272
|
+
tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
|
|
273
|
+
|
|
236
274
|
### Interactive Commands (PTY mode)
|
|
237
275
|
|
|
238
276
|
For commands that need a terminal:
|
|
@@ -241,13 +279,32 @@ For commands that need a terminal:
|
|
|
241
279
|
ssh_exec(alias="server", command="top -b -n 1", pty=true)
|
|
242
280
|
```
|
|
243
281
|
|
|
282
|
+
### Temporary Script Execution and Log Query Recipe
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs="appuser")
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Use `ssh_exec_script` for log discovery and filtering, then use `ssh_read_file` to read large result files in chunks:
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
ssh_exec_script(
|
|
292
|
+
alias="server",
|
|
293
|
+
script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
|
|
294
|
+
timeout=30000
|
|
295
|
+
)
|
|
296
|
+
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
|
|
300
|
+
|
|
244
301
|
### With Environment Variables
|
|
245
302
|
|
|
246
303
|
```
|
|
247
304
|
ssh_connect(
|
|
248
|
-
host="
|
|
305
|
+
host="<server-host>",
|
|
249
306
|
user="root",
|
|
250
|
-
|
|
307
|
+
keyPath="/home/.ssh/id_rsa",
|
|
251
308
|
env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
|
|
252
309
|
)
|
|
253
310
|
```
|
|
@@ -258,9 +315,9 @@ No need to manage connections for single commands:
|
|
|
258
315
|
|
|
259
316
|
```
|
|
260
317
|
ssh_quick_exec(
|
|
261
|
-
host="
|
|
318
|
+
host="<server-host>",
|
|
262
319
|
user="root",
|
|
263
|
-
|
|
320
|
+
keyPath="/home/.ssh/id_rsa",
|
|
264
321
|
command="uptime"
|
|
265
322
|
)
|
|
266
323
|
```
|
|
@@ -270,14 +327,26 @@ ssh_quick_exec(
|
|
|
270
327
|
```
|
|
271
328
|
// Upload
|
|
272
329
|
ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
|
|
330
|
+
ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
|
|
331
|
+
// Directories return UPLOAD_PATH_IS_DIRECTORY. Large files complete with a suggestion and recommended ssh_sync call.
|
|
273
332
|
|
|
274
333
|
// Download
|
|
275
334
|
ssh_download(alias="server", remotePath="/var/log/app.log", localPath="/tmp/app.log")
|
|
276
335
|
|
|
277
336
|
// Read file content
|
|
278
337
|
ssh_read_file(alias="server", remotePath="/etc/hosts")
|
|
338
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", tail=true, maxBytes=65536)
|
|
339
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, maxBytes=65536)
|
|
340
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
|
|
279
341
|
```
|
|
280
342
|
|
|
343
|
+
`ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
|
|
344
|
+
verification checks. `atomic=true` uploads to a same-directory temporary file, then renames it to the target path.
|
|
345
|
+
`verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit post-transfer checks.
|
|
346
|
+
`ssh_read_file` defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`,
|
|
347
|
+
`read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
|
|
348
|
+
from a head, tail, byte range, or line range sample.
|
|
349
|
+
|
|
281
350
|
### Directory Sync (with rsync)
|
|
282
351
|
|
|
283
352
|
Smart sync automatically detects rsync availability and uses it for efficient incremental transfer:
|
|
@@ -313,7 +382,9 @@ ssh_sync(
|
|
|
313
382
|
ssh_sync(..., dryRun=true)
|
|
314
383
|
```
|
|
315
384
|
|
|
316
|
-
If rsync is not available on remote or local, it automatically falls back to SFTP.
|
|
385
|
+
If rsync is not available on remote or local, it automatically falls back to SFTP. Sync responses include `transport`,
|
|
386
|
+
`duration`, `dryRun`, `stats`, and `commandSummary`. SFTP single-file transfers include a `verification` object with
|
|
387
|
+
local and remote size, mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`.
|
|
317
388
|
|
|
318
389
|
**Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
|
|
319
390
|
If you require strict host key verification and management, use SFTP mode instead.
|
|
@@ -329,7 +400,7 @@ ssh_pty_start(alias="server", command="top", rows=24, cols=80)
|
|
|
329
400
|
|
|
330
401
|
// 2. Read current output (polling)
|
|
331
402
|
ssh_pty_read(ptyId="pty_1_1234567890")
|
|
332
|
-
// Returns: { "data": "top - 10:30:15 up 5 days...", "active": true }
|
|
403
|
+
// Returns: { "data": "top - 10:30:15 up 5 days...", "active": true, "unreadRawBytes": 123, "foregroundProcess": "top" }
|
|
333
404
|
|
|
334
405
|
// 3. Send commands (e.g., quit top)
|
|
335
406
|
ssh_pty_write(ptyId="pty_1_1234567890", data="q")
|
|
@@ -354,6 +425,9 @@ ssh_pty_read(ptyId="pty_1_xxx")
|
|
|
354
425
|
ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
355
426
|
```
|
|
356
427
|
|
|
428
|
+
`ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
|
|
429
|
+
`rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
|
|
430
|
+
|
|
357
431
|
Common control sequences:
|
|
358
432
|
|
|
359
433
|
- Enter: `\r` or `\n`
|
|
@@ -368,8 +442,8 @@ Common control sequences:
|
|
|
368
442
|
Access remote internal services or expose local services:
|
|
369
443
|
|
|
370
444
|
```
|
|
371
|
-
// Local forward: access remote MySQL (
|
|
372
|
-
ssh_forward_local(alias="server", localPort=13306, remoteHost="
|
|
445
|
+
// Local forward: access remote MySQL (<service-host>:3306) via localhost:13306
|
|
446
|
+
ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>", remotePort=3306)
|
|
373
447
|
|
|
374
448
|
// Remote forward: expose local dev server (3000) to remote port 8080
|
|
375
449
|
ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
|
|
@@ -393,17 +467,24 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
393
467
|
| `keyPath` | string | - | Path to SSH private key |
|
|
394
468
|
| `port` | number | 22 | SSH port |
|
|
395
469
|
| `alias` | string | auto-generated | Connection alias for reference |
|
|
470
|
+
| `template` | string | - | Template name |
|
|
396
471
|
| `env` | object | - | Environment variables |
|
|
472
|
+
| `defaultEnv` | object | - | Default env for this session |
|
|
473
|
+
| `runAs` | string | - | Default execution user |
|
|
397
474
|
| `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
|
|
398
475
|
|
|
399
476
|
### Exec Options
|
|
400
477
|
|
|
401
|
-
| Option
|
|
402
|
-
|
|
403
|
-
| `timeout`
|
|
404
|
-
| `cwd`
|
|
405
|
-
| `env`
|
|
406
|
-
| `pty`
|
|
478
|
+
| Option | Type | Default | Description |
|
|
479
|
+
|-----------------|---------|---------------|--------------------------------------------|
|
|
480
|
+
| `timeout` | number | 30000 | Command timeout in ms |
|
|
481
|
+
| `cwd` | string | - | Working directory |
|
|
482
|
+
| `env` | object | - | Additional environment variables |
|
|
483
|
+
| `pty` | boolean | false | Enable PTY mode for interactive commands |
|
|
484
|
+
| `maxOutputSize` | number | 10 MB chars | Output truncation limit |
|
|
485
|
+
| `runAs` | string | session runAs | Per-command execution user |
|
|
486
|
+
| `useLoginUser` | boolean | false | Skip session-level runAs |
|
|
487
|
+
| `loadProfile` | boolean | true | Load target user's shell profile for runAs |
|
|
407
488
|
|
|
408
489
|
## Security
|
|
409
490
|
|
package/README_zh.md
CHANGED
|
@@ -88,7 +88,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
88
88
|
}
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
## 可用工具(
|
|
91
|
+
## 可用工具(30 个)
|
|
92
92
|
|
|
93
93
|
### 连接管理
|
|
94
94
|
|
|
@@ -110,6 +110,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
110
110
|
| `ssh_exec_batch` | 批量执行多条命令 |
|
|
111
111
|
| `ssh_exec_parallel` | 在多台主机上并行执行命令 |
|
|
112
112
|
| `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
|
|
113
|
+
| `ssh_exec_script` | 上传并执行远端临时脚本 |
|
|
113
114
|
|
|
114
115
|
### 文件操作
|
|
115
116
|
|
|
@@ -196,18 +197,46 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
|
|
|
196
197
|
### 基础:连接和执行
|
|
197
198
|
|
|
198
199
|
```
|
|
199
|
-
ssh_connect(host="
|
|
200
|
+
ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
|
|
200
201
|
ssh_exec(alias="myserver", command="ls -la /home")
|
|
201
202
|
ssh_disconnect(alias="myserver")
|
|
202
203
|
```
|
|
203
204
|
|
|
205
|
+
### 连接模板和 runAs
|
|
206
|
+
|
|
207
|
+
模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json` 提供,工具显式参数优先于模板值
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"app-dev": {
|
|
212
|
+
"host": "<server-host>",
|
|
213
|
+
"port": 22,
|
|
214
|
+
"user": "root",
|
|
215
|
+
"runAs": "appuser",
|
|
216
|
+
"defaultEnv": {
|
|
217
|
+
"APP_ENV": "dev"
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
ssh_connect(template="app-dev", alias="app-dev")
|
|
225
|
+
ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
|
|
226
|
+
ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`ssh_connect` 返回 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一 `user@host:port` identity
|
|
230
|
+
下已连接 alias 的 `reusableSessions`,同一个 alias 连接到不同 identity 会被拒绝,并返回现有 identity 和请求
|
|
231
|
+
identity,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
|
|
232
|
+
|
|
204
233
|
### 跳板机
|
|
205
234
|
|
|
206
235
|
通过跳板机连接内网服务器:
|
|
207
236
|
|
|
208
237
|
```
|
|
209
238
|
ssh_connect(
|
|
210
|
-
host="
|
|
239
|
+
host="<internal-host>",
|
|
211
240
|
user="root",
|
|
212
241
|
keyPath="/home/.ssh/id_rsa",
|
|
213
242
|
alias="internal",
|
|
@@ -224,7 +253,7 @@ ssh_connect(
|
|
|
224
253
|
适用于 SSH 以 root 登录,但需要以其他用户执行命令的场景:
|
|
225
254
|
|
|
226
255
|
```
|
|
227
|
-
1. ssh_connect(host="
|
|
256
|
+
1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
|
|
228
257
|
2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
|
|
229
258
|
// 输出: appuser
|
|
230
259
|
```
|
|
@@ -232,6 +261,12 @@ ssh_connect(
|
|
|
232
261
|
默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
|
|
233
262
|
)及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
|
|
234
263
|
|
|
264
|
+
`ssh_exec` 和 `ssh_exec_as_user` 返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
|
|
265
|
+
`profileLoaded`、`envInjectedKeys`、`failureKind`、`stdoutBytes`、`stderrBytes` 和截断提示,大输出会返回 `stdoutHead`、
|
|
266
|
+
`stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`,timeout 错误也包含超时前已经产生的 head/tail 输出,包含
|
|
267
|
+
destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
|
|
268
|
+
`su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
|
|
269
|
+
|
|
235
270
|
### 交互式命令(PTY 模式)
|
|
236
271
|
|
|
237
272
|
用于需要终端的命令:
|
|
@@ -240,13 +275,32 @@ ssh_connect(
|
|
|
240
275
|
ssh_exec(alias="server", command="top -b -n 1", pty=true)
|
|
241
276
|
```
|
|
242
277
|
|
|
278
|
+
### 临时脚本执行和日志查询 recipe
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs="appuser")
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
日志发现和过滤使用 `ssh_exec_script`,大结果再用 `ssh_read_file` 分块读取:
|
|
285
|
+
|
|
286
|
+
```
|
|
287
|
+
ssh_exec_script(
|
|
288
|
+
alias="server",
|
|
289
|
+
script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
|
|
290
|
+
timeout=30000
|
|
291
|
+
)
|
|
292
|
+
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具
|
|
296
|
+
|
|
243
297
|
### 设置环境变量
|
|
244
298
|
|
|
245
299
|
```
|
|
246
300
|
ssh_connect(
|
|
247
|
-
host="
|
|
301
|
+
host="<server-host>",
|
|
248
302
|
user="root",
|
|
249
|
-
|
|
303
|
+
keyPath="/home/.ssh/id_rsa",
|
|
250
304
|
env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
|
|
251
305
|
)
|
|
252
306
|
```
|
|
@@ -257,9 +311,9 @@ ssh_connect(
|
|
|
257
311
|
|
|
258
312
|
```
|
|
259
313
|
ssh_quick_exec(
|
|
260
|
-
host="
|
|
314
|
+
host="<server-host>",
|
|
261
315
|
user="root",
|
|
262
|
-
|
|
316
|
+
keyPath="/home/.ssh/id_rsa",
|
|
263
317
|
command="uptime"
|
|
264
318
|
)
|
|
265
319
|
```
|
|
@@ -269,14 +323,24 @@ ssh_quick_exec(
|
|
|
269
323
|
```
|
|
270
324
|
// 上传
|
|
271
325
|
ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
|
|
326
|
+
ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
|
|
327
|
+
// 目录返回 UPLOAD_PATH_IS_DIRECTORY,大文件上传成功后会提示优先使用 ssh_sync,并返回推荐调用
|
|
272
328
|
|
|
273
329
|
// 下载
|
|
274
330
|
ssh_download(alias="server", remotePath="/var/log/app.log", localPath="/tmp/app.log")
|
|
275
331
|
|
|
276
332
|
// 读取文件内容
|
|
277
333
|
ssh_read_file(alias="server", remotePath="/etc/hosts")
|
|
334
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", tail=true, maxBytes=65536)
|
|
335
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, maxBytes=65536)
|
|
336
|
+
ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
|
|
278
337
|
```
|
|
279
338
|
|
|
339
|
+
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,再
|
|
340
|
+
rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,`ssh_read_file`
|
|
341
|
+
默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
|
|
342
|
+
`remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
|
|
343
|
+
|
|
280
344
|
### 目录同步(rsync)
|
|
281
345
|
|
|
282
346
|
智能同步会自动检测 rsync 可用性,使用 rsync 进行高效增量传输:
|
|
@@ -312,7 +376,9 @@ ssh_sync(
|
|
|
312
376
|
ssh_sync(..., dryRun=true)
|
|
313
377
|
```
|
|
314
378
|
|
|
315
|
-
如果远程或本地没有 rsync,会自动回退到 SFTP
|
|
379
|
+
如果远程或本地没有 rsync,会自动回退到 SFTP,同步响应包含 `transport`、`duration`、`dryRun`、`stats`、`commandSummary` 和
|
|
380
|
+
`diagnostics`,其中 `diagnostics` 包含本地路径策略和远端父目录探测结果,SFTP 单文件传输会返回 `verification`,包含本地和远端的
|
|
381
|
+
size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比
|
|
316
382
|
|
|
317
383
|
**注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
|
|
318
384
|
如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
@@ -328,7 +394,7 @@ ssh_pty_start(alias="server", command="top", rows=24, cols=80)
|
|
|
328
394
|
|
|
329
395
|
// 2. 读取当前输出(轮询)
|
|
330
396
|
ssh_pty_read(ptyId="pty_1_1234567890")
|
|
331
|
-
// 返回: { "data": "top - 10:30:15 up 5 days...", "active": true }
|
|
397
|
+
// 返回: { "data": "top - 10:30:15 up 5 days...", "active": true, "unreadRawBytes": 123, "foregroundProcess": "top" }
|
|
332
398
|
|
|
333
399
|
// 3. 发送命令(如退出 top)
|
|
334
400
|
ssh_pty_write(ptyId="pty_1_1234567890", data="q")
|
|
@@ -353,6 +419,9 @@ ssh_pty_read(ptyId="pty_1_xxx")
|
|
|
353
419
|
ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
354
420
|
```
|
|
355
421
|
|
|
422
|
+
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
|
|
423
|
+
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流
|
|
424
|
+
|
|
356
425
|
常用控制序列:
|
|
357
426
|
|
|
358
427
|
- 回车: `\r` 或 `\n`
|
|
@@ -367,8 +436,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
367
436
|
访问远程内网服务或暴露本地服务:
|
|
368
437
|
|
|
369
438
|
```
|
|
370
|
-
// 本地转发:通过 localhost:13306 访问远程 MySQL (
|
|
371
|
-
ssh_forward_local(alias="server", localPort=13306, remoteHost="
|
|
439
|
+
// 本地转发:通过 localhost:13306 访问远程 MySQL (<service-host>:3306)
|
|
440
|
+
ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>", remotePort=3306)
|
|
372
441
|
|
|
373
442
|
// 远程转发:将本地开发服务器 (3000) 暴露到远程端口 8080
|
|
374
443
|
ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
|
|
@@ -392,17 +461,24 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
392
461
|
| `keyPath` | string | - | SSH 私钥路径 |
|
|
393
462
|
| `port` | number | 22 | SSH 端口 |
|
|
394
463
|
| `alias` | string | 自动生成 | 连接别名,用于后续引用 |
|
|
464
|
+
| `template` | string | - | 连接模板名 |
|
|
395
465
|
| `env` | object | - | 环境变量 |
|
|
466
|
+
| `defaultEnv` | object | - | 连接级默认环境变量 |
|
|
467
|
+
| `runAs` | string | - | 默认执行用户 |
|
|
396
468
|
| `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
|
|
397
469
|
|
|
398
470
|
### 执行选项
|
|
399
471
|
|
|
400
|
-
| 选项
|
|
401
|
-
|
|
402
|
-
| `timeout`
|
|
403
|
-
| `cwd`
|
|
404
|
-
| `env`
|
|
405
|
-
| `pty`
|
|
472
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
473
|
+
|-----------------|---------|-----------|------------------------|
|
|
474
|
+
| `timeout` | number | 30000 | 命令超时(毫秒) |
|
|
475
|
+
| `cwd` | string | - | 工作目录 |
|
|
476
|
+
| `env` | object | - | 额外环境变量 |
|
|
477
|
+
| `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
|
|
478
|
+
| `maxOutputSize` | number | 10 MB 字符 | 输出截断上限 |
|
|
479
|
+
| `runAs` | string | 连接级 runAs | 本次命令执行用户 |
|
|
480
|
+
| `useLoginUser` | boolean | false | 跳过连接级 runAs |
|
|
481
|
+
| `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
|
|
406
482
|
|
|
407
483
|
## 安全
|
|
408
484
|
|
package/dist/file-ops.d.ts
CHANGED
|
@@ -5,6 +5,37 @@ import { SFTPWrapper } from 'ssh2';
|
|
|
5
5
|
import { FileInfo, TransferProgress } from './types.js';
|
|
6
6
|
/** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
|
|
7
7
|
export declare function clearRsyncCache(alias?: string): void;
|
|
8
|
+
export declare function probeLocalPath(localPath: string): {
|
|
9
|
+
exists: boolean;
|
|
10
|
+
inputPath: string;
|
|
11
|
+
expandedPath: string;
|
|
12
|
+
resolvedPath: string;
|
|
13
|
+
allowList: {
|
|
14
|
+
configured: boolean;
|
|
15
|
+
matched?: boolean;
|
|
16
|
+
};
|
|
17
|
+
size?: undefined;
|
|
18
|
+
mode?: undefined;
|
|
19
|
+
mtimeMs?: undefined;
|
|
20
|
+
isSymlink?: undefined;
|
|
21
|
+
isDirectory?: undefined;
|
|
22
|
+
isFile?: undefined;
|
|
23
|
+
} | {
|
|
24
|
+
exists: boolean;
|
|
25
|
+
inputPath: string;
|
|
26
|
+
expandedPath: string;
|
|
27
|
+
resolvedPath: string;
|
|
28
|
+
size: number;
|
|
29
|
+
mode: string;
|
|
30
|
+
mtimeMs: number;
|
|
31
|
+
isSymlink: boolean;
|
|
32
|
+
isDirectory: boolean;
|
|
33
|
+
isFile: boolean;
|
|
34
|
+
allowList: {
|
|
35
|
+
configured: boolean;
|
|
36
|
+
matched?: boolean;
|
|
37
|
+
};
|
|
38
|
+
};
|
|
8
39
|
/**
|
|
9
40
|
* 上传文件
|
|
10
41
|
*/
|
|
@@ -19,14 +50,31 @@ export declare function downloadFile(alias: string, remotePath: string, localPat
|
|
|
19
50
|
success: boolean;
|
|
20
51
|
size: number;
|
|
21
52
|
}>;
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
53
|
+
export declare const DEFAULT_READ_FILE_MAX_BYTES: number;
|
|
54
|
+
export declare const HARD_READ_FILE_MAX_BYTES: number;
|
|
55
|
+
type ReadFileSampleKind = 'full' | 'head' | 'tail' | 'range' | 'line_range';
|
|
56
|
+
type ReadFileOptions = {
|
|
57
|
+
maxBytes?: number;
|
|
58
|
+
offset?: number;
|
|
59
|
+
tail?: boolean;
|
|
60
|
+
lineRange?: string;
|
|
61
|
+
};
|
|
62
|
+
type ReadFileResult = {
|
|
26
63
|
content: string;
|
|
27
64
|
size: number;
|
|
65
|
+
total_size: number;
|
|
66
|
+
read_offset: number;
|
|
67
|
+
read_bytes: number;
|
|
68
|
+
remaining_bytes: number;
|
|
69
|
+
sample_kind: ReadFileSampleKind;
|
|
28
70
|
truncated: boolean;
|
|
29
|
-
|
|
71
|
+
line_start?: number;
|
|
72
|
+
line_end?: number;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* 读取远程文件内容
|
|
76
|
+
*/
|
|
77
|
+
export declare function readFile(alias: string, remotePath: string, options?: number | ReadFileOptions): Promise<ReadFileResult>;
|
|
30
78
|
/**
|
|
31
79
|
* 写入远程文件
|
|
32
80
|
*/
|
|
@@ -69,12 +117,26 @@ export declare function syncFiles(alias: string, localPath: string, remotePath:
|
|
|
69
117
|
/**
|
|
70
118
|
* 使用 SFTP 同步文件
|
|
71
119
|
*/
|
|
120
|
+
type SyncStats = {
|
|
121
|
+
added: number;
|
|
122
|
+
updated: number;
|
|
123
|
+
deleted: number;
|
|
124
|
+
skipped: number;
|
|
125
|
+
failed: number;
|
|
126
|
+
};
|
|
72
127
|
type SyncResult = {
|
|
73
128
|
success: boolean;
|
|
74
129
|
method: 'rsync' | 'sftp';
|
|
130
|
+
transport?: 'rsync' | 'sftp';
|
|
131
|
+
direction?: 'upload' | 'download';
|
|
132
|
+
dryRun?: boolean;
|
|
133
|
+
duration?: number;
|
|
75
134
|
filesTransferred?: number;
|
|
76
135
|
bytesTransferred?: number;
|
|
77
136
|
skippedSymlinks?: number;
|
|
137
|
+
stats?: SyncStats;
|
|
138
|
+
verification?: Record<string, unknown>;
|
|
139
|
+
commandSummary?: Record<string, unknown>;
|
|
78
140
|
output?: string;
|
|
79
141
|
};
|
|
80
142
|
export {};
|