dsh-db-tool 1.5.91 → 1.7.0

package/dist/http/index.js

@@ -148,6 +148,27 @@ async function route(req, res, service, path, q, opts) {
             }));
         }
     }
+    // 连接导出/导入（口令加密包）。必须置于 connMatch 之前：
+    // /api/connections/export 与 /api/connections/import 都是单层路径，
+    // 若落到 connMatch 会被当作连接 id 匹配（DELETE 无分支静默 404、PUT 误更新）。
+    if (path === '/api/connections/export' && req.method === 'POST') {
+        const b = await readBody(req);
+        const passphrase = str(b['passphrase']);
+        if (!passphrase)
+            return send(res, 400, { ok: false, error: '缺少 passphrase', code: 'INVALID_ARGUMENT' });
+        const count = service.listConnections().length; // 权威条数，前端不再用可能过期的本地列表
+        return sendOk(res, { json: service.exportConnections(passphrase), count });
+    }
+    if (path === '/api/connections/import' && req.method === 'POST') {
+        const b = await readBody(req);
+        const json = str(b['json']);
+        const passphrase = str(b['passphrase']);
+        if (!json)
+            return send(res, 400, { ok: false, error: '缺少 json', code: 'INVALID_ARGUMENT' });
+        if (!passphrase)
+            return send(res, 400, { ok: false, error: '缺少 passphrase', code: 'INVALID_ARGUMENT' });
+        return sendOk(res, service.importConnections(json, passphrase));
+    }
     // 测试未保存的连接草稿（保存前测试；不落库）
     if (path === '/api/test-draft' && req.method === 'POST') {
         const b = await readBody(req);
@@ -241,6 +262,54 @@ async function route(req, res, service, path, q, opts) {
         const b = await readBody(req);
         return await sendMaybeConfirm(res, service.runScript(projectOfBody(b), str(b['connId']), str(b['code']), optStr(b['challengeId'])));
     }
+    // 数据传输（并行任务）：start 需危险确认（challenge 往返）；GET :taskId 轮询进度
+    //（快照 JSON-safe，bigint 键已转字符串）；POST :taskId/cancel 取消
+    if (path === '/api/transfer/start' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.transferStart(projectOfBody(b), {
+            sourceConnId: str(b['sourceConnId']),
+            targetConnId: str(b['targetConnId']),
+            tables: Array.isArray(b['tables']) ? b['tables'].map(String) : [],
+            writeMode: b['writeMode'],
+            batchSize: num(b['batchSize']),
+            tableConcurrency: num(b['tableConcurrency']),
+            shardConcurrency: num(b['shardConcurrency']),
+            overwriteStructure: b['overwriteStructure'] === true,
+            sourceDatabase: optStr(b['sourceDatabase']),
+            sourceSchema: optStr(b['sourceSchema']),
+            targetDatabase: optStr(b['targetDatabase']),
+            targetSchema: optStr(b['targetSchema']),
+        }, optStr(b['challengeId'])));
+    }
+    // 传输历史：终态持久化（任何时候可查已传输/失败结果），支持按项目清除防积累
+    // 传输日志：全事件行（start/表完成/进度/终态），日志标签页 5s 轮询实时查看
+    if (path === '/api/transfer-log' && req.method === 'GET') {
+        const limit = q.get('limit') !== null ? Number(q.get('limit')) : undefined;
+        return sendOk(res, service.transferLogTail(projectOf(q), limit));
+    }
+    // 实时进度：运行中任务快照（含百分比所需行数），前端 2s 轮询
+    if (path === '/api/transfer/live' && req.method === 'GET') {
+        return sendOk(res, service.transferLive(projectOf(q)));
+    }
+    if (path === '/api/transfer-history' && req.method === 'GET') {
+        const limit = q.get('limit') !== null ? Number(q.get('limit')) : undefined;
+        return sendOk(res, service.transferHistory(projectOf(q), limit));
+    }
+    if (path === '/api/transfer-history/clear' && req.method === 'POST') {
+        return sendOk(res, service.transferHistoryClear());
+    }
+    const transferMatch = /^\/api\/transfer\/([^/]+)(\/cancel)?$/.exec(path);
+    if (transferMatch) {
+        const id = decodeURIComponent(transferMatch[1] ?? '');
+        if (transferMatch[2] === '/cancel' && req.method === 'POST') {
+            const b = await readBody(req);
+            return sendOk(res, await service.transferCancel(projectOfBody(b), id));
+        }
+        if (req.method === 'GET') {
+            // 进度快照含表清单/行数/错误详情：与 cancel 同样要求项目授权（query 带 project）
+            return sendOk(res, await service.transferProgress(projectOf(q), id));
+        }
+    }
     // 控制台事务会话（粘性连接）：begin 发 token；exec 语义等同 execute（可能
     // NEEDS_CONFIRMATION）；commit/rollback 提交/回滚后销毁会话。trust 与 body
     // 校验复用入口层既有链路。
@@ -412,6 +481,11 @@ function parseSsl(v) {
 function optStr(v) {
     return typeof v === 'string' && v !== '' ? v : undefined;
 }
+/** 可选正整数字段：undefined/非法值返回 undefined（服务层兜底默认） */
+function num(v) {
+    const n = typeof v === 'number' ? v : typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
 function projectOf(q) {
     return q.has('project') ? (q.get('project') ?? undefined) : undefined;
 }

package/dist/manager.js

@@ -1,8 +1,10 @@
 import { randomBytes } from 'node:crypto';
 import { getAdapter } from './adapters/index.js';
 import { ChallengeStore, classifyStatement, sqlHead, SQL_READ_HEADS, } from './guard/index.js';
-import { mergeUrlCredentials, normalizeProjectKey, } from './store/index.js';
+import { mergeUrlCredentials, normalizeProjectKey, DECRYPT_FAIL_MESSAGE, } from './store/index.js';
 import { runScriptInChild } from './script/runner.js';
+import { decryptPayload, encryptPayload } from './store/export-crypto.js';
+import { startTransferTask } from './transfer.js';
 /* ---------------- 错误与结果类型 ---------------- */
 /** 携带机器可读 code 的业务错误（HTTP 层直接映射 {ok:false,error,code}） */
 export class DbToolError extends Error {
@@ -27,6 +29,12 @@ function assertNonEmpty(v, label) {
 }
 /** 单连接并发控制台事务会话上限（每会话独占驱动池 + checkout 连接，防连接耗尽） */
 const MAX_CONSOLE_SESSIONS_PER_CONN = 4;
+/** 全局并发传输任务上限（每任务独立 reader/writer 连接，防连接耗尽） */
+const MAX_TRANSFER_TASKS = 8;
+/** 终态快照保留窗口：前端轮询间隔 800ms + 慢网络余量；窗口后定时清除（不无限滞留） */
+const TRANSFER_SNAPSHOT_TTL_MS = 60_000;
+/** 单任务表清单上限：statement 进 challenge 响应与审计（表名全量 join），防兆级放大 */
+const MAX_TRANSFER_TABLES = 1000;
 /* ---------------- 服务核心 ---------------- */
 export class DbToolService {
     store;
@@ -63,9 +71,11 @@ export class DbToolService {
         if (!meta)
             throw new DbToolError('NOT_FOUND', `连接不存在: ${id}`);
         // url/凭证/ssl 变更后旧适配器仍持旧连接串，必须作废重建；
-        // 控制台事务会话的专用适配器不在缓存里，单独回收（否则旧凭据最长存活到空闲 TTL）
+        // 控制台事务会话的专用适配器不在缓存里，单独回收（否则旧凭据最长存活到空闲 TTL）；
+        // 传输任务持独立连接，同样回收（凭证变更后不得按旧凭据继续读写）
         void this.dropAdapters(id);
         void this.dropConsoleSessions(id);
+        this.cancelTransferTasksForConn(id);
         this.audit('', id, 'update_connection', id, 'none', false, true);
         return meta;
     }
@@ -75,6 +85,7 @@ export class DbToolService {
             throw new DbToolError('NOT_FOUND', `连接不存在: ${id}`);
         void this.dropAdapters(id);
         void this.dropConsoleSessions(id);
+        this.cancelTransferTasksForConn(id);
         this.audit('', id, 'remove_connection', id, 'none', false, true);
         return ok;
     }
@@ -144,6 +155,60 @@ export class DbToolService {
             throw this.toDriverError(e);
         }
     }
+    /* -- 连接导出/导入（口令加密，无需授权；口令不落审计） -- */
+    /** 口令下限：导出包含全部连接机密（明文密码/完整 URL），安全边界在服务端而非 UI */
+    static PASSPHRASE_MIN = 8;
+    /**
+     * 导出全部连接（含机密）为口令加密的 JSON 密文。
+     * 审计只记连接条数，绝不落口令与密文内容。
+     */
+    exportConnections(passphrase) {
+        const pp = assertNonEmpty(passphrase, 'passphrase');
+        if (pp.length < DbToolService.PASSPHRASE_MIN) {
+            throw new DbToolError('INVALID_ARGUMENT', `口令长度至少 ${DbToolService.PASSPHRASE_MIN} 位`);
+        }
+        const bundle = this.store.connections.exportBundle();
+        const json = encryptPayload(bundle, pp);
+        this.audit('', '', 'export_connections', `导出 ${bundle.connections.length} 个连接`, 'none', false, true);
+        return json;
+    }
+    /**
+     * 从口令加密的 JSON 密文导入连接。口令错误或密文损坏统一报
+     * INVALID_ARGUMENT(DECRYPT_FAIL_MESSAGE)（不区分原因，防口令探测）。
+     */
+    importConnections(encryptedJson, passphrase) {
+        const enc = assertNonEmpty(encryptedJson, 'json');
+        const pp = assertNonEmpty(passphrase, 'passphrase');
+        if (pp.length < DbToolService.PASSPHRASE_MIN) {
+            throw new DbToolError('INVALID_ARGUMENT', `口令长度至少 ${DbToolService.PASSPHRASE_MIN} 位`);
+        }
+        let bundle;
+        try {
+            bundle = decryptPayload(enc, pp);
+        }
+        catch {
+            // 口令错误/密文损坏/非合法 JSON 统一归一（decryptPayload 已统一文案，这里兜底）
+            throw new DbToolError('INVALID_ARGUMENT', DECRYPT_FAIL_MESSAGE);
+        }
+        // 结构校验：必须是含 connections 数组的对象，且每个元素为带非空 string id/kind 的对象。
+        // 畸形元素会让 importBundle 在 try 之外抛 TypeError（绕开统一文案），
+        // 或以 undefined id 静默落库成 UI 删不掉的幽灵记录
+        const conns = bundle?.connections;
+        if (!bundle ||
+            typeof bundle !== 'object' ||
+            !Array.isArray(conns) ||
+            conns.some((c) => c === null ||
+                typeof c !== 'object' ||
+                typeof c.id !== 'string' ||
+                c.id === '' ||
+                typeof c.kind !== 'string' ||
+                c.kind === '')) {
+            throw new DbToolError('INVALID_ARGUMENT', DECRYPT_FAIL_MESSAGE);
+        }
+        const summary = this.store.connections.importBundle(bundle);
+        this.audit('', '', 'import_connections', `导入 ${summary.imported} 个连接，跳过 ${summary.skipped.length} 个，失败 ${summary.errors.length} 个`, 'none', false, true);
+        return summary;
+    }
     /* -- 授权管理 -- */
     /** 项目路径归一化（/api/project-context 无会话解析器时的回退路径） */
     projectKey(projectPath) {
@@ -166,6 +231,7 @@ export class DbToolService {
         this.store.grants.revoke(key, connId);
         void this.dropAdapters(connId);
         void this.dropConsoleSessions(connId);
+        this.cancelTransferTasksForConn(connId); // 撤销后任务立即止损（否则写端全速跑完，管理员无系统内手段）
         this.audit(key, connId, 'revoke', connId, 'none', false, true);
     }
     /* -- 浏览（ro 即可） -- */
@@ -657,6 +723,177 @@ export class DbToolService {
             }
         }
     }
+    /* -- 数据传输（并行任务） -- */
+    /** 运行中的传输任务（taskId → 条目）；终态后保留一个轮询窗口再清除（见 finished 回调） */
+    transferTasks = new Map();
+    async transferStart(projectPath, input, challengeId) {
+        const tables = input.tables;
+        if (!Array.isArray(tables) || tables.length === 0) {
+            throw new DbToolError('INVALID_ARGUMENT', 'tables 必须是非空字符串数组');
+        }
+        // 编排层按表名反查进度条目：重复名会让两遍传输共享同一进度对象且第二条永久 pending
+        if (new Set(tables).size !== tables.length) {
+            throw new DbToolError('INVALID_ARGUMENT', 'tables 存在重复表名，请去重后重试');
+        }
+        if (tables.length > MAX_TRANSFER_TABLES) {
+            throw new DbToolError('INVALID_ARGUMENT', `单任务表数超上限（${tables.length} > ${MAX_TRANSFER_TABLES}），请分批传输`);
+        }
+        const writeMode = input.writeMode ?? 'insert';
+        if (writeMode !== 'insert' && writeMode !== 'ignore' && writeMode !== 'replace' && writeMode !== 'truncate') {
+            throw new DbToolError('INVALID_ARGUMENT', `writeMode 非法: ${String(writeMode)}（insert/ignore/replace/truncate）`);
+        }
+        // 源连接只读授权即可（传输读端自建专用连接）；目标连接需写
+        const { key: srcKey } = await this.authorize(projectPath, input.sourceConnId, false);
+        const { key: dstKey } = await this.authorize(projectPath, input.targetConnId, true);
+        const source = this.requireConn(input.sourceConnId);
+        const target = this.requireConn(input.targetConnId);
+        // 定位：optStr 语义（存在则 trim 非空才收，否则忽略）；缺省 = 连接默认上下文
+        const optLoc = (v) => {
+            const s = typeof v === 'string' ? v.trim() : '';
+            return s !== '' ? s : undefined;
+        };
+        const srcDb = optLoc(input.sourceDatabase);
+        const srcSchema = optLoc(input.sourceSchema);
+        const dstDb = optLoc(input.targetDatabase);
+        const dstSchema = optLoc(input.targetSchema);
+        // 定位进 statement（start/finish/cancel 三链审计与 challenge 绑定共用一条），
+        // 首次生成与带 challengeId 重放同 input 必同值；schema 附着于库（前端联动恒先选库）
+        const locSeg = (db, schema) => db ? (schema ? `${db}.${schema}` : db) : '';
+        const locPart = [
+            srcDb ? ` 源=${locSeg(srcDb, srcSchema)}` : '',
+            dstDb ? ` 目标=${locSeg(dstDb, dstSchema)}` : '',
+        ].join('');
+        const statement = `数据传输 ${source.meta.kind}(${source.meta.id}) → ${target.meta.kind}(${target.meta.id}) 表[${tables.join(', ')}] 模式=${writeMode}${locPart}`;
+        // 危险操作确认（批量建表+写入，对齐 runGuarded 的 danger 分支语义）
+        const scope = { connId: input.targetConnId, projectKey: dstKey };
+        if (!challengeId) {
+            const { id: cid } = this.challenges.create(statement, scope);
+            this.audit(dstKey, input.targetConnId, 'transfer', statement, 'danger', false, false, 'NEEDS_CONFIRMATION');
+            return {
+                needConfirmation: true,
+                challengeId: cid,
+                statement,
+                danger: 'danger',
+                reason: writeMode === 'truncate'
+                    ? `【危险】将清空目标库 ${target.meta.kind}(${target.meta.id}) 中 ${tables.length} 张表的全部已有数据，随后重新写入，清空不可恢复，需要确认`
+                    : `将向目标库 ${target.meta.kind}(${target.meta.id}) 建表并批量写入 ${tables.length} 张表，需要确认`,
+            };
+        }
+        if (!this.challenges.consume(challengeId, statement, scope)) {
+            this.audit(dstKey, input.targetConnId, 'transfer', statement, 'danger', false, false, 'INVALID_CHALLENGE');
+            throw new DbToolError('INVALID_CHALLENGE', '确认凭据无效（不存在、已使用、已过期或语句已变更），请重新发起');
+        }
+        // —— 同步段：预算检查 + 注册之间零 await，杜绝并发 start 双过检查（TOCTOU）——
+        this.sweepTransferTasks();
+        const running = [...this.transferTasks.values()].filter((e) => e.task.snapshot().status === 'running');
+        if (running.length >= MAX_TRANSFER_TASKS) {
+            throw new DbToolError('INVALID_ARGUMENT', `全局并发传输任务已达上限（${MAX_TRANSFER_TASKS}），请等待既有任务完成`);
+        }
+        if (running.some((e) => e.targetConnId === input.targetConnId)) {
+            throw new DbToolError('INVALID_ARGUMENT', '该目标连接已有传输任务在执行（同目标并发写入会互踩），请等待完成或先取消');
+        }
+        const task = startTransferTask(source, target, {
+            tables,
+            writeMode,
+            ...(input.batchSize !== undefined ? { batchSize: input.batchSize } : {}),
+            ...(input.tableConcurrency !== undefined ? { tableConcurrency: input.tableConcurrency } : {}),
+            ...(input.shardConcurrency !== undefined ? { shardConcurrency: input.shardConcurrency } : {}),
+            ...(input.overwriteStructure === true ? { overwriteStructure: true } : {}),
+            ...(srcDb !== undefined || srcSchema !== undefined ? { sourceDatabase: srcDb, sourceSchema: srcSchema } : {}),
+            ...(dstDb !== undefined || dstSchema !== undefined ? { targetDatabase: dstDb, targetSchema: dstSchema } : {}),
+            // 传输日志：任务开始/表完成/进度节流/终态逐行落 <我的文档>/DSH/transfer-log.jsonl
+            onLog: (ev) => {
+                this.store.transferLog.append({
+                    type: ev.type,
+                    taskId: task.id,
+                    projectPathKey: dstKey,
+                    statement,
+                    ...(ev.status !== undefined ? { status: ev.status } : {}),
+                    ...(ev.table !== undefined ? { table: ev.table } : {}),
+                    ...(ev.rows !== undefined ? { rows: ev.rows } : {}),
+                    ...(ev.totalRows !== undefined ? { totalRows: ev.totalRows } : {}),
+                    ...(ev.tables !== undefined ? { tables: ev.tables } : {}),
+                    ...(ev.failures !== undefined ? { failures: ev.failures } : {}),
+                });
+            },
+        });
+        this.transferTasks.set(task.id, { task, sourceConnId: input.sourceConnId, targetConnId: input.targetConnId, projectKey: dstKey, statement });
+        this.audit(dstKey, input.targetConnId, 'transfer', statement, 'danger', true, true);
+        void task.finished.then((s) => {
+            const failed = s.failures.length > 0;
+            this.audit(dstKey, input.targetConnId, 'transfer_finish', statement, 'danger', true, !failed, failed ? `${s.failures.length} 个分片/表失败` : undefined);
+            // 终态不无限滞留 Map：保留一个轮询窗口（前端 800ms 轮询 + 慢网络余量）供拉到
+            // 终态快照，之后定时清除；start 时的 sweepTransferTasks 兜底清同一批条目
+            setTimeout(() => {
+                this.transferTasks.delete(task.id);
+            }, TRANSFER_SNAPSHOT_TTL_MS);
+        });
+        return { taskId: task.id };
+    }
+    async transferProgress(projectPath, taskId) {
+        const entry = this.transferTasks.get(taskId);
+        if (!entry)
+            throw new DbToolError('NOT_FOUND', `传输任务不存在或已结束: ${taskId}`);
+        // 快照含表清单/行数/错误详情，非公开信息：与数据面接口一致要求项目授权，
+        // 且必须与发起项目同 key（taskId 可枚举，不能凭 id 越项目读取）
+        const { key } = await this.authorize(projectPath, entry.targetConnId, false);
+        if (key !== entry.projectKey) {
+            throw new DbToolError('UNAUTHORIZED_PROJECT', `传输任务不属于该项目: ${taskId}`);
+        }
+        return entry.task.snapshot();
+    }
+    async transferCancel(projectPath, taskId) {
+        const entry = this.transferTasks.get(taskId);
+        if (!entry)
+            throw new DbToolError('NOT_FOUND', `传输任务不存在或已结束: ${taskId}`);
+        // 取消需对目标连接有写授权（能发起即能取消，授权语义对齐）
+        await this.authorize(projectPath, entry.targetConnId, true);
+        entry.task.cancel();
+        // 取消是影响目标库状态的操作：与 start/finish 同链审计（ok 以 cancelled 语义恒真）
+        this.audit(entry.projectKey, entry.targetConnId, 'transfer_cancel', entry.statement, 'danger', true, true);
+        return { cancelled: true };
+    }
+    /** 授权/连接变更时回收该连接参与的传输任务（对齐控制台会话的对称回收；cancel 为协作式，检查点退出） */
+    cancelTransferTasksForConn(connId) {
+        for (const entry of this.transferTasks.values()) {
+            if (entry.sourceConnId === connId || entry.targetConnId === connId)
+                entry.task.cancel();
+        }
+    }
+    /** 传输历史：最近 n 条任务终态（可选按项目过滤）；对齐审计查询的公开语义 */
+    transferHistory(projectPath, limit = 50) {
+        const n = Math.min(Math.max(1, Math.floor(limit) || 50), 200);
+        return projectPath && projectPath.trim() !== ''
+            ? this.store.transferLog.tail(n, normalizeProjectKey(projectPath), 'finish')
+            : this.store.transferLog.tail(n, undefined, 'finish');
+    }
+    /** 实时进度：全部运行中任务的快照（可选按项目过滤），供「实时进度」子标签轮询 */
+    transferLive(projectPath) {
+        const key = projectPath && projectPath.trim() !== '' ? normalizeProjectKey(projectPath) : undefined;
+        return [...this.transferTasks.entries()]
+            .filter(([, e]) => e.task.snapshot().status === 'running' && (!key || e.projectKey === key))
+            .map(([taskId, e]) => ({ taskId, snapshot: e.task.snapshot() }));
+    }
+    /** 传输日志：最近 n 条全事件行（start/表完成/进度/终态），供日志标签实时查看 */
+    transferLogTail(projectPath, limit = 200) {
+        const n = Math.min(Math.max(1, Math.floor(limit) || 200), 2000);
+        return projectPath && projectPath.trim() !== ''
+            ? this.store.transferLog.tail(n, normalizeProjectKey(projectPath))
+            : this.store.transferLog.tail(n);
+    }
+    /** 清除传输历史：全量清除（历史区与文件同步清空）。留审计。 */
+    transferHistoryClear() {
+        const removed = this.store.transferLog.clear();
+        this.audit('', '', 'transfer_history_clear', '清除全部传输历史', 'none', false, true);
+        return { removed };
+    }
+    /** 清理终态任务（start 时调用；快照仅在 running 期间可查） */
+    sweepTransferTasks() {
+        for (const [id, entry] of this.transferTasks) {
+            if (entry.task.snapshot().status !== 'running')
+                this.transferTasks.delete(id);
+        }
+    }
     adapterFor(connId, mode) {
         const cacheKey = `${connId}@mode=${mode}`;
         let p = this.adapterCache.get(cacheKey);

package/dist/store/connections.js

@@ -10,6 +10,16 @@ import * as path from 'node:path';
 import { readJson, writeJsonAtomic } from './io.js';
 /** fields 中被视为机密的键，落盘前拆出到 secrets.json */
 const PASSWORD_KEY = 'password';
+/** id 冲突哨兵错误：importBundle 以此 instanceof 识别跳过项，
+ *  替代对 create() 中文错误文案的字符串匹配（文案改动不破坏幂等契约） */
+export class DuplicateConnectionError extends Error {
+    connId;
+    constructor(connId) {
+        super(`连接已存在: ${connId}`);
+        this.connId = connId;
+        this.name = 'DuplicateConnectionError';
+    }
+}
 /** authority 段定位：scheme:// 到首个 /?#（兼容可选 jdbc: 前缀，如 jdbc:gaussdb://），
  *  捕获组 1 为 scheme:// 部分、组 2 为 authority（多主机逗号串整体落在该段内）。
  *  redactUrl 与 mergeUrlCredentials 的字符串回退注入共用。 */
@@ -178,11 +188,11 @@ export class ConnectionStore {
         const rec = this.findRec(this.load(), id);
         return rec ? toMeta(rec, this.hasPassword(id)) : undefined;
     }
-    /** 新建连接；id 已存在时抛错 */
+    /** 新建连接；id 已存在时抛 DuplicateConnectionError */
     create(input) {
         const data = this.load();
         if (this.findRec(data, input.id)) {
-            throw new Error(`连接已存在: ${input.id}`);
+            throw new DuplicateConnectionError(input.id);
         }
         const rec = { id: input.id, kind: input.kind };
         if (input.name !== undefined)
@@ -296,4 +306,77 @@ export class ConnectionStore {
             rc.ssl = rec.ssl;
         return rc;
     }
+    /** 导出连接迁移包：全部连接记录 + 对应机密（含明文密码）。
+     *  调用方必须将整个返回值经 export-crypto 加密后方可落盘/传输，
+     *  本方法本身不加密（加密口令属于 HTTP 层入参，不应侵入存储层）。 */
+    exportBundle() {
+        const connections = this.load().connections;
+        const secrets = {};
+        for (const rec of connections) {
+            const sec = this.secrets.get(rec.id);
+            if (sec !== undefined)
+                secrets[rec.id] = sec;
+        }
+        return { connections, secrets };
+    }
+    /** 导入连接迁移包：逐条走既有 create()（机密拆分/脱敏逻辑全复用）。
+     *  - id 冲突（「连接已存在」）→ 记入 skipped，不覆盖已有数据；
+     *  - 其他异常 → 记入 errors 并继续处理后续条目；
+     *  - 幂等可重入：重复导入同一 bundle，已存在的全部落入 skipped。 */
+    importBundle(bundle) {
+        const result = { imported: 0, skipped: [], errors: [] };
+        for (const rec of bundle.connections) {
+            // per-record 校验：解密成功的包也可能内容畸形（schema 漂移/手工构造），
+            // 缺 id/kind 的记录不落库，计入 errors
+            if (rec === null ||
+                typeof rec !== 'object' ||
+                typeof rec.id !== 'string' ||
+                rec.id === '' ||
+                typeof rec.kind !== 'string' ||
+                rec.kind === '') {
+                result.errors.push({ id: String(rec?.id ?? ''), message: '记录结构非法（缺少 id/kind）' });
+                continue;
+            }
+            const sec = bundle.secrets?.[rec.id];
+            try {
+                // 重建 create 入参：脱敏 URL 回换完整 URL（机密在 sec.url 中）；
+                // fields 模式密码经 fields.password 传入由 create 自动拆分到 secrets
+                this.create({
+                    id: rec.id,
+                    kind: rec.kind,
+                    name: rec.name,
+                    url: sec?.url,
+                    fields: sec?.password !== undefined ? { ...(rec.fields ?? {}), password: sec.password } : rec.fields,
+                    ssl: rec.ssl,
+                });
+                // 覆盖式写回：create 成功后该 id 必无冲突，先清掉既有/孤儿机密
+                // （create 崩溃窗口可能残留旧条目），再整体重写，确保导入后机密与包一致。
+                // 合并写会残留旧键（如旧 url），适配器优先用 rc.url，会被静默错连旧主机。
+                this.secrets.delete(rec.id);
+                try {
+                    if (sec !== undefined)
+                        this.secrets.set(rec.id, sec);
+                }
+                catch (secErr) {
+                    // 写回机密失败：连接行已落盘，回滚避免「errors 里却已存在」的半导入门状态
+                    try {
+                        this.remove(rec.id);
+                    }
+                    catch { /* 尽力而为 */ }
+                    throw secErr;
+                }
+                result.imported += 1;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (err instanceof DuplicateConnectionError) {
+                    result.skipped.push(rec.id);
+                }
+                else {
+                    result.errors.push({ id: rec.id, message });
+                }
+            }
+        }
+        return result;
+    }
 }

package/dist/store/export-crypto.js

@@ -0,0 +1,78 @@
+/**
+ * 连接导出/导入的口令加解密（纯函数，仅用 Node stdlib crypto）。
+ *
+ * 方案：
+ *  - KDF：scryptSync(passphrase, salt, 32) 派生 AES-256 密钥；
+ *  - 算法：AES-256-GCM（机密性 + 完整性一体，tag 防篡改）；
+ *  - iv：12 字节随机（GCM 推荐长度）；salt：16 字节随机；
+ *  - 输出为 JSON 字符串：{ v: 1, kdf: 'scrypt', salt, iv, tag, data }，二进制段全部 base64。
+ *
+ * 失败统一抛 Error('口令错误或文件已损坏')，不向外泄漏是口令错还是文件坏，
+ * 避免给攻击者侧信道。口令本身为空/非字符串时单独抛 Error（参数错误，非解密失败）。
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+/** 解密失败/文件损坏的统一错误信息 */
+export const DECRYPT_FAIL_MESSAGE = '口令错误或文件已损坏';
+/** 口令断言：必须为非空字符串 */
+function assertPassphrase(passphrase) {
+    if (typeof passphrase !== 'string' || passphrase.length === 0) {
+        throw new Error('口令必须为非空字符串');
+    }
+}
+/** 加密任意可 JSON 序列化的 payload，返回信封 JSON 字符串 */
+export function encryptPayload(plain, passphrase) {
+    assertPassphrase(passphrase);
+    const salt = randomBytes(16);
+    // 显式固定 scrypt 成本参数（与 Node 当前默认一致），加解密两侧同步使用，
+    // 避免导出包跨运行时/跨 Node 版本时因默认值漂移而无法解密
+    const key = scryptSync(passphrase, salt, 32, { N: 16384, r: 8, p: 1 });
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const data = Buffer.concat([cipher.update(JSON.stringify(plain), 'utf8'), cipher.final()]);
+    const box = {
+        v: 1,
+        kdf: 'scrypt',
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+        data: data.toString('base64'),
+    };
+    return JSON.stringify(box);
+}
+/** 结构校验：缺字段/类型不符即视为文件损坏 */
+function isEncryptedBox(x) {
+    if (x === null || typeof x !== 'object')
+        return false;
+    const b = x;
+    return (b.v === 1 &&
+        b.kdf === 'scrypt' &&
+        typeof b.salt === 'string' &&
+        typeof b.iv === 'string' &&
+        typeof b.tag === 'string' &&
+        typeof b.data === 'string');
+}
+/** 解密信封 JSON，返回原始 payload；口令错误或任一环节损坏统一抛 DECRYPT_FAIL_MESSAGE */
+export function decryptPayload(encryptedJson, passphrase) {
+    assertPassphrase(passphrase);
+    try {
+        const box = JSON.parse(encryptedJson);
+        if (!isEncryptedBox(box))
+            throw new Error('结构非法');
+        const salt = Buffer.from(box.salt, 'base64');
+        const iv = Buffer.from(box.iv, 'base64');
+        const tag = Buffer.from(box.tag, 'base64');
+        const data = Buffer.from(box.data, 'base64');
+        // base64 解码静默容错，需显式校验解码后长度（iv 12B / tag 16B / salt 非空）
+        if (iv.length !== 12 || tag.length !== 16 || salt.length === 0)
+            throw new Error('长度非法');
+        const key = scryptSync(passphrase, salt, 32, { N: 16384, r: 8, p: 1 });
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const plain = Buffer.concat([decipher.update(data), decipher.final()]);
+        return JSON.parse(plain.toString('utf8'));
+    }
+    catch (err) {
+        // 对外统一文案（防侧信道），原始错误挂 cause 供服务端日志区分失败模式
+        throw new Error(DECRYPT_FAIL_MESSAGE, { cause: err });
+    }
+}

package/dist/store/index.js

@@ -13,12 +13,14 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { AuditLog } from './audit.js';
+import { TransferLog, transferLogDir } from './transfer-history.js';
 import { ConnectionStore } from './connections.js';
 import { GrantStore } from './grants.js';
 import { chmodBestEffort } from './io.js';
 import { SecretsBox } from './secrets.js';
 export { normalizeProjectKey } from './normalize.js';
-export { mergeUrlCredentials, redactUrl } from './connections.js';
+export { mergeUrlCredentials, redactUrl, DuplicateConnectionError } from './connections.js';
+export { encryptPayload, decryptPayload, DECRYPT_FAIL_MESSAGE } from './export-crypto.js';
 export { AuditLog, ConnectionStore, GrantStore, SecretsBox };
 export class DbToolStore {
     /** 数据目录：$DSH_HOME/db-tool */
@@ -27,6 +29,7 @@ export class DbToolStore {
     secrets;
     grants;
     audit;
+    transferLog;
     constructor(homeDir) {
         // || 而非 ??: DSH_HOME=""（空串）视为未设置，避免产出相对路径 'db-tool/'
         const home = homeDir ?? (process.env['DSH_HOME'] || path.join(os.homedir(), '.dsh'));
@@ -36,6 +39,9 @@ export class DbToolStore {
         this.secrets = new SecretsBox(this.dir);
         this.grants = new GrantStore(this.dir);
         this.audit = new AuditLog(this.dir);
+        // 传输历史独立于 store：存到 <我的文档>/DSH/ 供用户直接查看；
+        // vitest 运行时仍走 temp home，避免测试写用户真实文档目录
+        this.transferLog = new TransferLog(process.env.VITEST === 'true' ? this.dir : transferLogDir());
         this.connections = new ConnectionStore(this.dir, this.secrets, this.grants);
     }
 }