@pyrokine/mcp-ssh 1.2.2 → 2.0.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/dist/file-ops.js CHANGED
@@ -1,15 +1,116 @@
1
1
  /**
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
- import { execSync } from 'child_process';
4
+ import { execSync, spawnSync } from 'child_process';
5
5
  import * as fs from 'fs';
6
6
  import * as os from 'os';
7
7
  import * as path from 'path';
8
8
  import { sessionManager } from './session-manager.js';
9
+ import { escapeShellArg, expandTilde } from './tools/utils.js';
9
10
  // 文件类型 mode 常量
11
+ const S_IFMT = 0o170000; // 文件类型位掩码
10
12
  const S_IFDIR = 0o40000;
11
13
  const S_IFREG = 0o100000;
12
14
  const S_IFLNK = 0o120000;
15
+ // rsync 可用性缓存(per alias,连接存续期内不变,disconnect 时由 SessionManager 主动清理)
16
+ const RSYNC_CACHE_TTL_MS = 5 * 60_000;
17
+ const rsyncCache = new Map();
18
+ /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
19
+ export function clearRsyncCache(alias) {
20
+ if (alias === undefined) {
21
+ rsyncCache.clear();
22
+ }
23
+ else {
24
+ rsyncCache.delete(alias);
25
+ }
26
+ }
27
+ /** SFTP 并发上限,避免单 SSH session 上太多 channel */
28
+ const SFTP_PARALLEL_LIMIT = Number(process.env.SSH_MCP_SFTP_PARALLEL) || 8;
29
+ /**
30
+ * 简单的并发控制:把异步任务限制在 limit 个 in-flight,串行入队
31
+ */
32
+ async function runWithConcurrency(items, limit, worker) {
33
+ if (items.length === 0) {
34
+ return;
35
+ }
36
+ const it = items[Symbol.iterator]();
37
+ const runners = [];
38
+ for (let i = 0; i < Math.min(limit, items.length); i++) {
39
+ runners.push((async () => {
40
+ while (true) {
41
+ const next = it.next();
42
+ if (next.done) {
43
+ return;
44
+ }
45
+ await worker(next.value);
46
+ }
47
+ })());
48
+ }
49
+ await Promise.all(runners);
50
+ }
51
+ /**
52
+ * 校验本地路径是否在 SSH_MCP_FILE_OPS_ALLOW_DIRS 白名单内
53
+ *
54
+ * 默认未设置环境变量时不限制(保留灵活性)
55
+ * 设置后,所有 upload/download/sync 的本地路径必须在白名单目录之一内,否则抛出错误
56
+ *
57
+ * 格式:path.delimiter 分隔的绝对路径列表(POSIX `:`,Windows `;`),如 `/tmp:/home/user/work`
58
+ * 安全性:路径会通过 fs.realpathSync 解析 symlink,防止 symlink 逃出白名单
59
+ */
60
+ function validateLocalPathAgainstAllowList(localPath) {
61
+ const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
62
+ if (!allowEnv) {
63
+ return;
64
+ }
65
+ const allowDirs = allowEnv
66
+ .split(path.delimiter)
67
+ .map((p) => p.trim())
68
+ .filter((p) => p.length > 0);
69
+ if (allowDirs.length === 0) {
70
+ return;
71
+ }
72
+ let resolvedLocal;
73
+ try {
74
+ // 路径不存在时,向上找到第一个存在的祖先 realpathSync 后再拼接剩余
75
+ resolvedLocal = resolvePathOrAncestor(localPath);
76
+ }
77
+ catch (e) {
78
+ throw new Error(`无法解析路径 ${localPath}: ${e instanceof Error ? e.message : String(e)}`);
79
+ }
80
+ const inAllowList = allowDirs.some((dir) => {
81
+ try {
82
+ const resolvedDir = fs.realpathSync(dir);
83
+ const rel = path.relative(resolvedDir, resolvedLocal);
84
+ return !rel.startsWith('..') && !path.isAbsolute(rel);
85
+ }
86
+ catch {
87
+ return false;
88
+ }
89
+ });
90
+ if (!inAllowList) {
91
+ throw new Error(`localPath "${localPath}" 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 白名单内(白名单: ${allowDirs.join(', ')})`);
92
+ }
93
+ }
94
+ function resolvePathOrAncestor(p) {
95
+ const absolute = path.isAbsolute(p) ? p : path.resolve(p);
96
+ try {
97
+ return fs.realpathSync(absolute);
98
+ }
99
+ catch {
100
+ // 不存在,向上找到第一个存在的祖先
101
+ let dir = absolute;
102
+ let tail = '';
103
+ while (dir !== path.dirname(dir)) {
104
+ const parent = path.dirname(dir);
105
+ tail = tail ? path.join(path.basename(dir), tail) : path.basename(dir);
106
+ if (fs.existsSync(parent)) {
107
+ return path.join(fs.realpathSync(parent), tail);
108
+ }
109
+ dir = parent;
110
+ }
111
+ return absolute;
112
+ }
113
+ }
13
114
  /**
14
115
  * sftp.stat 的 Promise 包装
15
116
  */
@@ -28,7 +129,7 @@ function sftpStat(sftp, remotePath) {
28
129
  /**
29
130
  * 带进度追踪的流传输
30
131
  */
31
- function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress) {
132
+ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, closeSftp = true) {
32
133
  return new Promise((resolve, reject) => {
33
134
  let settled = false;
34
135
  const cleanup = (err) => {
@@ -36,7 +137,30 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress)
36
137
  return;
37
138
  }
38
139
  settled = true;
39
- sftp.end();
140
+ // 先解管道并强制销毁两端,避免错误后流仍持有 sftp 资源
141
+ try {
142
+ readStream.unpipe(writeStream);
143
+ }
144
+ catch {
145
+ /* ignore */
146
+ }
147
+ try {
148
+ ;
149
+ readStream.destroy?.();
150
+ }
151
+ catch {
152
+ /* ignore */
153
+ }
154
+ try {
155
+ ;
156
+ writeStream.destroy?.();
157
+ }
158
+ catch {
159
+ /* ignore */
160
+ }
161
+ if (closeSftp) {
162
+ sftp.end();
163
+ }
40
164
  if (err) {
41
165
  reject(err);
42
166
  }
@@ -55,7 +179,9 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress)
55
179
  writeStream.on('close', () => {
56
180
  if (!settled) {
57
181
  settled = true;
58
- sftp.end();
182
+ if (closeSftp) {
183
+ sftp.end();
184
+ }
59
185
  resolve({ success: true, size: totalSize });
60
186
  }
61
187
  });
@@ -65,31 +191,42 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress)
65
191
  /**
66
192
  * 上传文件
67
193
  */
68
- export async function uploadFile(alias, localPath, remotePath, onProgress) {
194
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp) {
195
+ localPath = expandTilde(localPath);
196
+ validateLocalPathAgainstAllowList(localPath);
69
197
  if (!fs.existsSync(localPath)) {
70
198
  throw new Error(`Local file not found: ${localPath}`);
71
199
  }
72
- const sftp = await sessionManager.getSftp(alias);
73
- const totalSize = fs.statSync(localPath).size;
74
- return pipeWithProgress(fs.createReadStream(localPath), sftp.createWriteStream(remotePath), sftp, totalSize, onProgress);
200
+ // 用 lstat 拒绝顶层 symlink,与 ssh_sync 顶层 followSymlinks=false 行为一致;
201
+ // 单文件接口不引入 followSymlinks 选项,需走 symlink 请用 ssh_sync
202
+ const lstats = fs.lstatSync(localPath);
203
+ if (lstats.isSymbolicLink()) {
204
+ throw new Error(`Refusing to upload symlink at top level: ${localPath} (use ssh_sync with followSymlinks=true to traverse)`);
205
+ }
206
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
207
+ const totalSize = lstats.size;
208
+ return pipeWithProgress(fs.createReadStream(localPath), sftp.createWriteStream(remotePath), sftp, totalSize, onProgress, !sharedSftp);
75
209
  }
76
210
  /**
77
211
  * 下载文件
78
212
  */
79
- export async function downloadFile(alias, remotePath, localPath, onProgress) {
80
- const sftp = await sessionManager.getSftp(alias);
213
+ export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp) {
214
+ localPath = expandTilde(localPath);
215
+ validateLocalPathAgainstAllowList(localPath);
216
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
81
217
  const totalSize = (await sftpStat(sftp, remotePath)).size;
82
218
  // 确保本地目录存在
83
219
  const localDir = path.dirname(localPath);
84
220
  if (!fs.existsSync(localDir)) {
85
221
  fs.mkdirSync(localDir, { recursive: true });
86
222
  }
87
- return pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress);
223
+ return pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp);
88
224
  }
89
225
  /**
90
226
  * 读取远程文件内容
91
227
  */
92
- export async function readFile(alias, remotePath, maxBytes = 1024 * 1024) {
228
+ export async function readFile(alias, remotePath, maxBytes = 1024 * 1024 // 默认最大 1MB
229
+ ) {
93
230
  const sftp = await sessionManager.getSftp(alias);
94
231
  const actualSize = (await sftpStat(sftp, remotePath)).size;
95
232
  const truncated = actualSize > maxBytes;
@@ -146,12 +283,15 @@ export async function writeFile(alias, remotePath, content, append = false) {
146
283
  /**
147
284
  * 列出目录内容
148
285
  */
149
- export async function listDir(alias, remotePath, showHidden = false) {
150
- const sftp = await sessionManager.getSftp(alias);
286
+ export async function listDir(alias, remotePath, showHidden = false, sharedSftp) {
287
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
288
+ const closeWhenDone = !sharedSftp;
151
289
  return new Promise((resolve, reject) => {
152
290
  sftp.readdir(remotePath, (err, list) => {
153
291
  if (err) {
154
- sftp.end();
292
+ if (closeWhenDone) {
293
+ sftp.end();
294
+ }
155
295
  reject(err);
156
296
  return;
157
297
  }
@@ -161,9 +301,9 @@ export async function listDir(alias, remotePath, showHidden = false) {
161
301
  name: item.filename,
162
302
  path: path.posix.join(remotePath, item.filename),
163
303
  size: item.attrs.size,
164
- isDirectory: (item.attrs.mode & S_IFDIR) !== 0,
165
- isFile: (item.attrs.mode & S_IFREG) !== 0,
166
- isSymlink: (item.attrs.mode & S_IFLNK) !== 0,
304
+ isDirectory: (item.attrs.mode & S_IFMT) === S_IFDIR,
305
+ isFile: (item.attrs.mode & S_IFMT) === S_IFREG,
306
+ isSymlink: (item.attrs.mode & S_IFMT) === S_IFLNK,
167
307
  permissions: formatPermissions(item.attrs.mode),
168
308
  owner: item.attrs.uid,
169
309
  group: item.attrs.gid,
@@ -177,7 +317,9 @@ export async function listDir(alias, remotePath, showHidden = false) {
177
317
  }
178
318
  return a.name.localeCompare(b.name);
179
319
  });
180
- sftp.end();
320
+ if (closeWhenDone) {
321
+ sftp.end();
322
+ }
181
323
  resolve(files);
182
324
  });
183
325
  });
@@ -198,9 +340,9 @@ export async function getFileInfo(alias, remotePath) {
198
340
  name: path.posix.basename(remotePath),
199
341
  path: remotePath,
200
342
  size: stats.size,
201
- isDirectory: (stats.mode & S_IFDIR) !== 0,
202
- isFile: (stats.mode & S_IFREG) !== 0,
203
- isSymlink: (stats.mode & S_IFLNK) !== 0,
343
+ isDirectory: (stats.mode & S_IFMT) === S_IFDIR,
344
+ isFile: (stats.mode & S_IFMT) === S_IFREG,
345
+ isSymlink: (stats.mode & S_IFMT) === S_IFLNK,
204
346
  permissions: formatPermissions(stats.mode),
205
347
  owner: stats.uid,
206
348
  group: stats.gid,
@@ -216,7 +358,7 @@ export async function getFileInfo(alias, remotePath) {
216
358
  export async function mkdir(alias, remotePath, recursive = false) {
217
359
  if (recursive) {
218
360
  // 通过 exec 实现递归创建
219
- const result = await sessionManager.exec(alias, `mkdir -p "${remotePath}"`);
361
+ const result = await sessionManager.exec(alias, `mkdir -p ${escapeShellArg(remotePath)}`);
220
362
  return result.exitCode === 0;
221
363
  }
222
364
  const sftp = await sessionManager.getSftp(alias);
@@ -236,11 +378,18 @@ export async function mkdir(alias, remotePath, recursive = false) {
236
378
  * 检查远程是否安装 rsync
237
379
  */
238
380
  export async function checkRsync(alias) {
381
+ const cached = rsyncCache.get(alias);
382
+ if (cached !== undefined && cached.expiresAt > Date.now()) {
383
+ return cached.value;
384
+ }
239
385
  try {
240
386
  const result = await sessionManager.exec(alias, 'which rsync');
241
- return result.exitCode === 0 && result.stdout.trim().length > 0;
387
+ const available = result.exitCode === 0 && result.stdout.trim().length > 0;
388
+ rsyncCache.set(alias, { value: available, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
389
+ return available;
242
390
  }
243
391
  catch {
392
+ rsyncCache.set(alias, { value: false, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
244
393
  return false;
245
394
  }
246
395
  }
@@ -254,18 +403,14 @@ export async function checkRsync(alias) {
254
403
  * @param options 同步选项
255
404
  */
256
405
  export async function syncFiles(alias, localPath, remotePath, direction, options = {}) {
406
+ localPath = expandTilde(localPath);
407
+ validateLocalPathAgainstAllowList(localPath);
257
408
  const hasRsync = await checkRsync(alias);
258
409
  if (hasRsync) {
259
410
  return syncWithRsync(alias, localPath, remotePath, direction, options);
260
411
  }
261
412
  return syncWithSftp(alias, localPath, remotePath, direction, options);
262
413
  }
263
- /**
264
- * 转义 shell 路径参数
265
- */
266
- function escapeShellPath(p) {
267
- return `'${p.replace(/'/g, '\'\\\'\'')}'`;
268
- }
269
414
  /**
270
415
  * 使用 rsync 同步文件
271
416
  * 通过本地执行 rsync 连接到远程(需要密钥认证或 ssh-agent)
@@ -279,6 +424,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
279
424
  hasLocalRsync = true;
280
425
  }
281
426
  catch {
427
+ // rsync 不可用,由 hasLocalRsync 标记处理
282
428
  }
283
429
  if (!hasLocalRsync) {
284
430
  // 本地没有 rsync,回退到 SFTP
@@ -286,7 +432,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
286
432
  }
287
433
  // 获取会话信息以构建 rsync 命令
288
434
  const sessions = sessionManager.listSessions();
289
- const sessionInfo = sessions.find(s => s.alias === alias);
435
+ const sessionInfo = sessions.find((s) => s.alias === alias);
290
436
  if (!sessionInfo) {
291
437
  throw new Error(`Session '${alias}' not found`);
292
438
  }
@@ -303,24 +449,55 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
303
449
  }
304
450
  if (options.exclude) {
305
451
  for (const pattern of options.exclude) {
306
- args.push(`--exclude=${escapeShellPath(pattern)}`);
452
+ args.push(`--exclude=${pattern}`);
307
453
  }
308
454
  }
309
- // 构建 rsync 命令(本地执行)
310
- // 注意:这需要密钥认证或 ssh-agent,密码认证不支持
311
- const sshCmd = `ssh -p ${sessionInfo.port} -o StrictHostKeyChecking=no -o BatchMode=yes`;
312
- const remoteSpec = `${sessionInfo.username}@${sessionInfo.host}:${escapeShellPath(remotePath)}`;
313
- const rsyncCmd = direction === 'upload'
314
- ? `rsync ${args.join(' ')} -e "${sshCmd}" ${escapeShellPath(localPath)} ${remoteSpec}`
315
- : `rsync ${args.join(' ')} -e "${sshCmd}" ${remoteSpec} ${escapeShellPath(localPath)}`;
455
+ if (options.followSymlinks) {
456
+ // -L / --copy-links: 跟随 symlink,上传链接目标内容(与 SFTP 路径 followSymlinks=true 行为对齐)
457
+ // 默认不传则用 rsync -a 自带的 -l:保留 symlink 本身,不上传目标内容
458
+ args.push('-L');
459
+ }
460
+ // path 安全校验:以 `-` 起始的路径会被 rsync 当成选项解析(即便有 `--` 兜底,也避免 OS/rsync 实现差异)
461
+ if (localPath.startsWith('-') || remotePath.startsWith('-')) {
462
+ throw new Error(`Invalid path: must not start with '-' (localPath=${localPath}, remotePath=${remotePath})`);
463
+ }
464
+ // username/host 安全校验:拒绝 shell 元字符与 ssh 选项注入
465
+ const sshIdentifierAllowed = /^[a-zA-Z0-9.:_-]+$/;
466
+ if (!sshIdentifierAllowed.test(sessionInfo.username)) {
467
+ throw new Error(`Invalid username for rsync: "${sessionInfo.username}" 含非法字符`);
468
+ }
469
+ if (!sshIdentifierAllowed.test(sessionInfo.host)) {
470
+ throw new Error(`Invalid host for rsync: "${sessionInfo.host}" 含非法字符`);
471
+ }
472
+ // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
473
+ // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
474
+ const sshCmd = `ssh -p ${sessionInfo.port} -o StrictHostKeyChecking=accept-new -o BatchMode=yes -o ProxyCommand=none`;
475
+ // remoteSpec 作为单独 argv 元素,不经 shell 解析
476
+ const remoteSpec = `${sessionInfo.username}@${sessionInfo.host}:${remotePath}`;
477
+ // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
478
+ const rsyncArgs = direction === 'upload'
479
+ ? [...args, '-e', sshCmd, '--', localPath, remoteSpec]
480
+ : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
316
481
  try {
317
- const result = execSync(rsyncCmd, {
482
+ const result = spawnSync('rsync', rsyncArgs, {
318
483
  encoding: 'utf-8',
319
- timeout: 600000, // 10 分钟超时
484
+ timeout: 600000,
320
485
  stdio: ['pipe', 'pipe', 'pipe'],
321
486
  });
487
+ if (result.error || result.status !== 0) {
488
+ const stderr = (result.stderr ?? '').trim();
489
+ const reason = result.error?.message ?? `exit code ${result.status}`;
490
+ const fallback = await syncWithSftp(alias, localPath, remotePath, direction, options);
491
+ const warning = `rsync 失败原因: ${reason}${stderr ? ` | stderr: ${stderr}` : ''} | 已 fallback 到 SFTP(性能可能较差)`;
492
+ console.warn(`[mcp-ssh] ${warning}`);
493
+ return {
494
+ ...fallback,
495
+ output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
496
+ };
497
+ }
498
+ const output = result.stdout ?? '';
322
499
  // 解析 rsync 输出统计文件数
323
- const lines = result.split('\n');
500
+ const lines = output.split('\n');
324
501
  let filesTransferred = 0;
325
502
  for (const line of lines) {
326
503
  if (line.trim() &&
@@ -334,20 +511,30 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
334
511
  success: true,
335
512
  method: 'rsync',
336
513
  filesTransferred,
337
- output: result,
514
+ output,
338
515
  };
339
516
  }
340
- catch {
341
- // rsync 失败(可能是密码认证),回退到 SFTP
342
- return syncWithSftp(alias, localPath, remotePath, direction, options);
517
+ catch (e) {
518
+ // rsync 执行异常,回退到 SFTP(保留原因供调用方追溯)
519
+ const fallback = await syncWithSftp(alias, localPath, remotePath, direction, options);
520
+ const warning = `rsync 异常: ${e instanceof Error ? e.message : String(e)} | 已 fallback 到 SFTP(性能可能较差)`;
521
+ console.warn(`[mcp-ssh] ${warning}`);
522
+ return {
523
+ ...fallback,
524
+ output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
525
+ };
343
526
  }
344
527
  }
345
- function buildSyncResult(fileCount, totalSize, warnings) {
528
+ function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0) {
529
+ if (skippedSymlinks > 0) {
530
+ warnings.push(`skipped ${skippedSymlinks} symlink(s) (set followSymlinks=true to traverse)`);
531
+ }
346
532
  return {
347
533
  success: true,
348
534
  method: 'sftp',
349
535
  filesTransferred: fileCount,
350
536
  bytesTransferred: totalSize,
537
+ skippedSymlinks: skippedSymlinks > 0 ? skippedSymlinks : undefined,
351
538
  output: warnings.length ? `Warning: ${warnings.join('; ')}` : undefined,
352
539
  };
353
540
  }
@@ -366,10 +553,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
366
553
  }
367
554
  try {
368
555
  if (direction === 'upload') {
369
- const stats = fs.statSync(localPath);
556
+ const stats = options.followSymlinks ? fs.statSync(localPath) : fs.lstatSync(localPath);
557
+ if (stats.isSymbolicLink()) {
558
+ throw new Error(`Refusing to upload symlink at top level: ${localPath} (set followSymlinks=true to traverse)`);
559
+ }
370
560
  if (stats.isDirectory() && options.recursive !== false) {
371
- const { fileCount, totalSize } = await uploadDirectory(alias, localPath, remotePath, options.exclude);
372
- return buildSyncResult(fileCount, totalSize, warnings);
561
+ const { fileCount, totalSize, skippedSymlinks } = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false);
562
+ return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
373
563
  }
374
564
  const { size } = await uploadFile(alias, localPath, remotePath);
375
565
  return buildSyncResult(1, size, warnings);
@@ -377,8 +567,8 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
377
567
  // download
378
568
  const info = await getFileInfo(alias, remotePath);
379
569
  if (info.isDirectory && options.recursive !== false) {
380
- const { fileCount, totalSize } = await downloadDirectory(alias, remotePath, localPath, options.exclude);
381
- return buildSyncResult(fileCount, totalSize, warnings);
570
+ const { fileCount, totalSize, skippedSymlinks } = await downloadDirectory(alias, remotePath, localPath, options.exclude);
571
+ return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
382
572
  }
383
573
  const { size } = await downloadFile(alias, remotePath, localPath);
384
574
  return buildSyncResult(1, size, warnings);
@@ -387,106 +577,164 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
387
577
  return {
388
578
  success: false,
389
579
  method: 'sftp',
390
- output: err.message,
580
+ output: err instanceof Error ? err.message : String(err),
391
581
  };
392
582
  }
393
583
  }
394
584
  /**
395
585
  * 递归上传目录
396
586
  */
397
- async function uploadDirectory(alias, localPath, remotePath, exclude) {
587
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false) {
398
588
  let fileCount = 0;
399
589
  let totalSize = 0;
400
- // 确保远程目录存在
401
- await mkdir(alias, remotePath, true);
402
- const items = fs.readdirSync(localPath);
403
- for (const item of items) {
404
- // 检查排除模式
405
- if (exclude && exclude.some(pattern => matchPattern(item, pattern))) {
406
- continue;
590
+ let skippedSymlinks = 0;
591
+ // 顶层调用时开启一个 SFTP 会话,递归调用复用
592
+ const ownSftp = !sharedSftp;
593
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
594
+ try {
595
+ // 确保远程目录存在
596
+ await mkdir(alias, remotePath, true);
597
+ const items = fs.readdirSync(localPath);
598
+ // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
599
+ const subDirItems = [];
600
+ const fileItems = [];
601
+ for (const item of items) {
602
+ if (exclude && exclude.some((pattern) => matchPattern(item, pattern))) {
603
+ continue;
604
+ }
605
+ const itemLocalPath = path.join(localPath, item);
606
+ const stats = followSymlinks ? fs.statSync(itemLocalPath) : fs.lstatSync(itemLocalPath);
607
+ if (!followSymlinks && stats.isSymbolicLink()) {
608
+ console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
609
+ skippedSymlinks++;
610
+ continue;
611
+ }
612
+ if (stats.isDirectory()) {
613
+ subDirItems.push(item);
614
+ }
615
+ else if (stats.isFile()) {
616
+ fileItems.push({ name: item, stats });
617
+ }
407
618
  }
408
- const itemLocalPath = path.join(localPath, item);
409
- const itemRemotePath = path.posix.join(remotePath, item);
410
- const stats = fs.statSync(itemLocalPath);
411
- if (stats.isDirectory()) {
412
- const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude);
619
+ // 文件并发上传
620
+ await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
621
+ const itemLocalPath = path.join(localPath, name);
622
+ const itemRemotePath = path.posix.join(remotePath, name);
623
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
624
+ fileCount++;
625
+ totalSize += stats.size;
626
+ });
627
+ // 子目录串行递归
628
+ for (const item of subDirItems) {
629
+ const itemLocalPath = path.join(localPath, item);
630
+ const itemRemotePath = path.posix.join(remotePath, item);
631
+ const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks);
413
632
  fileCount += result.fileCount;
414
633
  totalSize += result.totalSize;
634
+ skippedSymlinks += result.skippedSymlinks;
415
635
  }
416
- else if (stats.isFile()) {
417
- await uploadFile(alias, itemLocalPath, itemRemotePath);
418
- fileCount++;
419
- totalSize += stats.size;
636
+ }
637
+ finally {
638
+ if (ownSftp) {
639
+ sftp.end();
420
640
  }
421
641
  }
422
- return { fileCount, totalSize };
642
+ return { fileCount, totalSize, skippedSymlinks };
423
643
  }
424
644
  /**
425
645
  * 递归下载目录
426
646
  */
427
- async function downloadDirectory(alias, remotePath, localPath, exclude) {
647
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp) {
428
648
  let fileCount = 0;
429
649
  let totalSize = 0;
430
- // 确保本地目录存在
431
- if (!fs.existsSync(localPath)) {
432
- fs.mkdirSync(localPath, { recursive: true });
433
- }
434
- const items = await listDir(alias, remotePath, true);
435
- for (const item of items) {
436
- // 检查排除模式
437
- if (exclude && exclude.some(pattern => matchPattern(item.name, pattern))) {
438
- continue;
650
+ let skippedSymlinks = 0;
651
+ // 顶层调用时开启一个 SFTP 会话,递归调用复用
652
+ const ownSftp = !sharedSftp;
653
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
654
+ try {
655
+ // 确保本地目录存在
656
+ if (!fs.existsSync(localPath)) {
657
+ fs.mkdirSync(localPath, { recursive: true });
439
658
  }
440
- const itemLocalPath = path.join(localPath, item.name);
441
- if (item.isDirectory) {
442
- const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude);
443
- fileCount += result.fileCount;
444
- totalSize += result.totalSize;
659
+ const items = await listDir(alias, remotePath, true, sftp);
660
+ // 分类:文件并发下载,目录串行递归
661
+ const fileItems = [];
662
+ const dirItems = [];
663
+ const symlinkItems = [];
664
+ for (const item of items) {
665
+ if (exclude && exclude.some((pattern) => matchPattern(item.name, pattern))) {
666
+ continue;
667
+ }
668
+ if (item.isDirectory) {
669
+ dirItems.push(item);
670
+ }
671
+ else if (item.isFile) {
672
+ fileItems.push(item);
673
+ }
674
+ else if (item.isSymlink) {
675
+ symlinkItems.push(item);
676
+ }
677
+ else {
678
+ console.warn(`[ssh_sync] skipping unknown item type: ${item.path}`);
679
+ }
445
680
  }
446
- else if (item.isFile) {
447
- await downloadFile(alias, item.path, itemLocalPath);
681
+ await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async (item) => {
682
+ const itemLocalPath = path.join(localPath, item.name);
683
+ await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
448
684
  fileCount++;
449
685
  totalSize += item.size;
686
+ });
687
+ for (const item of dirItems) {
688
+ const itemLocalPath = path.join(localPath, item.name);
689
+ const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp);
690
+ fileCount += result.fileCount;
691
+ totalSize += result.totalSize;
692
+ skippedSymlinks += result.skippedSymlinks;
693
+ }
694
+ for (const item of symlinkItems) {
695
+ console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);
696
+ skippedSymlinks++;
697
+ }
698
+ }
699
+ finally {
700
+ if (ownSftp) {
701
+ sftp.end();
450
702
  }
451
703
  }
452
- return { fileCount, totalSize };
704
+ return { fileCount, totalSize, skippedSymlinks };
453
705
  }
454
706
  /**
455
707
  * 简单的模式匹配(支持 * 和 ?)
456
708
  */
709
+ const matchPatternCache = new Map();
457
710
  function matchPattern(name, pattern) {
458
- const regexPattern = pattern
459
- .replace(/[.+^${}()|[\]\\]/g, '\\$&') // 转义特殊字符
460
- .replace(/\*/g, '.*')
461
- .replace(/\?/g, '.');
462
- return new RegExp(`^${regexPattern}$`).test(name);
711
+ let regex = matchPatternCache.get(pattern);
712
+ if (!regex) {
713
+ const regexPattern = pattern
714
+ .replace(/[.+^${}()|[\]\\]/g, '\\$&') // 转义特殊字符
715
+ .replace(/\*/g, '.*')
716
+ .replace(/\?/g, '.');
717
+ regex = new RegExp(`^${regexPattern}$`);
718
+ matchPatternCache.set(pattern, regex);
719
+ }
720
+ return regex.test(name);
463
721
  }
464
722
  /**
465
723
  * 格式化权限字符串
466
724
  */
467
725
  function formatPermissions(mode) {
468
- const types = [
469
- [S_IFDIR, 'd'],
470
- [S_IFLNK, 'l'],
471
- [S_IFREG, '-'],
472
- ];
473
- let type = '-';
474
- for (const [mask, char] of types) {
475
- if ((mode & mask) !== 0) {
476
- type = char;
477
- break;
478
- }
479
- }
726
+ const fileType = mode & S_IFMT;
727
+ const type = fileType === S_IFDIR ? 'd' : fileType === S_IFLNK ? 'l' : fileType === S_IFREG ? '-' : '?';
480
728
  const perms = [
481
- (mode & 0o400) ? 'r' : '-',
482
- (mode & 0o200) ? 'w' : '-',
483
- (mode & 0o100) ? 'x' : '-',
484
- (mode & 0o040) ? 'r' : '-',
485
- (mode & 0o020) ? 'w' : '-',
486
- (mode & 0o010) ? 'x' : '-',
487
- (mode & 0o004) ? 'r' : '-',
488
- (mode & 0o002) ? 'w' : '-',
489
- (mode & 0o001) ? 'x' : '-',
729
+ mode & 0o400 ? 'r' : '-',
730
+ mode & 0o200 ? 'w' : '-',
731
+ mode & 0o100 ? 'x' : '-',
732
+ mode & 0o040 ? 'r' : '-',
733
+ mode & 0o020 ? 'w' : '-',
734
+ mode & 0o010 ? 'x' : '-',
735
+ mode & 0o004 ? 'r' : '-',
736
+ mode & 0o002 ? 'w' : '-',
737
+ mode & 0o001 ? 'x' : '-',
490
738
  ];
491
739
  return type + perms.join('');
492
740
  }