dsh-db-tool 1.6.0 → 1.7.0

package/dist/http/index.js

@@ -262,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
     // 校验复用入口层既有链路。
@@ -433,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

@@ -4,6 +4,7 @@ import { ChallengeStore, classifyStatement, sqlHead, SQL_READ_HEADS, } from './g
 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 {
@@ -28,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;
@@ -64,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;
     }
@@ -76,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;
     }
@@ -221,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 即可） -- */
@@ -712,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/index.js

@@ -13,6 +13,7 @@ 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';
@@ -28,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'));
@@ -37,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);
     }
 }

package/dist/store/transfer-history.js

@@ -0,0 +1,114 @@
+/**
+ * transfer-log.jsonl：传输过程日志（追加式，逐行一条事件）。
+ * 事件类型：
+ *  - start    任务开始（statement 含源→目标/定位/模式）
+ *  - table    单表状态变化（开始传输 / 完成 / 失败，含已写入行数）
+ *  - progress 任务进度节流行（运行中各表实时行数，默认 5s 一条）
+ *  - finish   任务终态（全量表明细 + 失败清单；「传输历史」弹窗即取此类型）
+ * 追加写天然原子；损坏行跳过不影响其余。文件位于 <我的文档>/DSH/，用户可直接打开查看。
+ */
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+let cachedDocsDir;
+/** 检测「我的文档」真实位置（每台机器可能重定向到任意盘/目录） */
+function detectDocumentsDir() {
+    if (cachedDocsDir)
+        return cachedDocsDir;
+    let dir = '';
+    // Windows 官方途径：Shell API GetFolderPath('MyDocuments')——自动处理文档重定向。
+    // 不用 reg.exe：其中文系统输出为 GBK，utf8 解码会把重定向目录名变成乱码（实测踩坑）
+    if (process.platform === 'win32') {
+        try {
+            const out = childProcess.execFileSync('powershell', ['-NoProfile', '-Command', "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8; [Environment]::GetFolderPath('MyDocuments')"], { timeout: 15000, encoding: 'utf8' });
+            dir = out.trim();
+        }
+        catch {
+            // PowerShell 不可用：走候选路径回退
+        }
+    }
+    if (dir === '') {
+        const home = os.homedir();
+        const candidates = process.platform === 'win32'
+            ? [process.env.OneDrive ? path.join(process.env.OneDrive, 'Documents') : '', path.join(home, 'Documents')]
+            : [process.env.XDG_DOCUMENTS_DIR ?? '', path.join(home, 'Documents')];
+        dir = candidates.find((c) => c !== '' && fs.existsSync(c)) ?? path.join(home, 'Documents');
+    }
+    cachedDocsDir = dir;
+    return dir;
+}
+/** 传输日志存储目录：<我的文档>/DSH/；DSH_TRANSFER_DIR 环境变量可覆盖 */
+export function transferLogDir() {
+    const override = process.env.DSH_TRANSFER_DIR;
+    if (override && override !== '') {
+        fs.mkdirSync(override, { recursive: true });
+        return override;
+    }
+    const dir = path.join(detectDocumentsDir(), 'DSH');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export class TransferLog {
+    filePath;
+    /** JSONL 文件绝对路径（供「在本机查看」） */
+    get file() {
+        return this.filePath;
+    }
+    constructor(dir) {
+        this.filePath = path.join(dir, 'transfer-log.jsonl');
+        fs.mkdirSync(dir, { recursive: true }); // 目录不存在时 appendFileSync 会 ENOENT
+    }
+    /** 追加一条日志；ts 省略时自动填充当前 UTC 时间 */
+    append(entry) {
+        const full = { ...entry, ts: entry.ts ?? new Date().toISOString() };
+        fs.appendFileSync(this.filePath, JSON.stringify(full) + '\n', 'utf8');
+        return full;
+    }
+    /** 最近 n 条（时间正序）；projectKey/type 给定时过滤。损坏行跳过 */
+    tail(n, projectKey, type) {
+        if (!fs.existsSync(this.filePath))
+            return [];
+        const lines = fs.readFileSync(this.filePath, 'utf8').split('\n');
+        const out = [];
+        for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+            const line = lines[i]?.trim();
+            if (!line)
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (projectKey && e.projectPathKey !== projectKey)
+                    continue;
+                if (type && e.type !== type)
+                    continue;
+                out.push(e);
+            }
+            catch {
+                // 跳过损坏行
+            }
+        }
+        return out.reverse();
+    }
+    /** 清除全部日志。返回删除条数 */
+    clear() {
+        if (!fs.existsSync(this.filePath))
+            return 0;
+        const lines = fs.readFileSync(this.filePath, 'utf8').split('\n');
+        const kept = [];
+        let removed = 0;
+        for (const line of lines) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                JSON.parse(t);
+                removed += 1;
+            }
+            catch {
+                kept.push(t); // 损坏行原样保留
+            }
+        }
+        fs.writeFileSync(this.filePath, kept.length > 0 ? kept.join('\n') + '\n' : '', 'utf8');
+        return removed;
+    }
+}