@lasting-beauty/chat-hub 0.1.0-beta.1

package/cli/server-verification.mjs

@@ -0,0 +1,562 @@
+import { execFileSync } from 'node:child_process';
+import { X509Certificate } from 'node:crypto';
+import { lstatSync, readFileSync, statSync } from 'node:fs';
+import { request as httpRequest } from 'node:http';
+
+import { deploymentPaths, verifiedPlatformCliVersionPatterns } from './deploy.mjs';
+import { ipCertificateAutomationPaths } from './ip-certificate.mjs';
+
+const internalPorts = new Map([
+  [4310, 'application'],
+  [8080, 'gateway'],
+]);
+
+export async function verifyServerDeployment({
+  domain,
+  publicHost = domain,
+  publicScheme = 'https',
+  certificateMode = publicScheme === 'https' ? 'managed-domain' : 'none',
+  larkCliPath = 'lark-cli',
+  dingtalkCliPath = 'dws',
+  nodePath = process.execPath,
+  runCommand = defaultRunCommand,
+  fetchImpl = fetch,
+  internalFetchImpl = fetchInternalGateway,
+  fileSystem = { lstatSync, readFileSync, statSync },
+  environment = process.env,
+  now = Date.now(),
+} = {}) {
+  if (!isValidEndpoint(publicHost, publicScheme)) throw new Error('服务器验收公网入口无效');
+  const publicPorts = new Map(
+    publicScheme === 'https'
+      ? [
+          [80, 'http'],
+          [443, 'https'],
+        ]
+      : [[80, 'http']],
+  );
+  const checks = [];
+
+  if (publicScheme === 'https') {
+    await record(checks, 'tls-validation-enabled', 'Node.js 未关闭 TLS 证书校验', () => {
+      if (environment.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
+        throw new Error('NODE_TLS_REJECT_UNAUTHORIZED=0 会使公网证书验收失真');
+      }
+      return 'enabled';
+    });
+  }
+
+  await record(checks, 'chat-hub-service', 'Chat Hub systemd 服务已启用并安全运行', () => {
+    const properties = parseProperties(
+      runCommand('systemctl', [
+        'show',
+        'chat-hub.service',
+        '--property=ActiveState,UnitFileState,User,Group,ProtectSystem,NoNewPrivileges',
+      ]),
+    );
+    assertEqual(properties.ActiveState, 'active', 'Chat Hub 服务未运行');
+    assertEnabled(properties.UnitFileState, 'Chat Hub 服务未启用开机启动');
+    assertEqual(properties.User, 'chat-hub', 'Chat Hub 服务用户不正确');
+    assertEqual(properties.Group, 'chat-hub', 'Chat Hub 服务组不正确');
+    assertEqual(properties.ProtectSystem, 'strict', 'ProtectSystem 未设为 strict');
+    assertEqual(properties.NoNewPrivileges, 'yes', 'NoNewPrivileges 未启用');
+    return properties;
+  });
+
+  await record(checks, 'caddy-service', 'Caddy 已启用并运行', () => {
+    const properties = parseProperties(
+      runCommand('systemctl', ['show', 'caddy.service', '--property=ActiveState,UnitFileState']),
+    );
+    assertEqual(properties.ActiveState, 'active', 'Caddy 服务未运行');
+    assertEnabled(properties.UnitFileState, 'Caddy 服务未启用开机启动');
+    return properties;
+  });
+
+  await record(checks, 'systemd-unit-valid', 'systemd 单元配置有效', () => {
+    runCommand('systemd-analyze', ['verify', deploymentPaths.service]);
+    return deploymentPaths.service;
+  });
+
+  await record(checks, 'caddy-config-valid', 'Caddy 配置有效', () => {
+    runCommand('caddy', [
+      'validate',
+      '--config',
+      deploymentPaths.caddyfile,
+      '--adapter',
+      'caddyfile',
+    ]);
+    return deploymentPaths.caddyfile;
+  });
+
+  if (certificateMode === 'ip-shortlived') {
+    await record(checks, 'ip-certificate', 'IP 证书覆盖当前公网 IP 且未进入危险窗口', () => {
+      const certificatePath = ipCertificateAutomationPaths.publishedFullchain;
+      const certificate = new X509Certificate(fileSystem.readFileSync(certificatePath));
+      if (!certificate.subjectAltName?.split(/,\s*/).includes(`IP Address:${publicHost}`)) {
+        throw new Error('当前证书没有覆盖部署公网 IP');
+      }
+      const expiresAt = Date.parse(certificate.validTo);
+      if (!Number.isFinite(expiresAt)) throw new Error('证书到期时间无法识别');
+      const remainingHours = (expiresAt - now) / 3_600_000;
+      if (remainingHours <= 24) throw new Error(`证书只剩 ${remainingHours.toFixed(1)} 小时`);
+      return { certificatePath, expiresAt: new Date(expiresAt).toISOString(), remainingHours };
+    });
+    await record(checks, 'certificate-renewal-timer', '短期证书续期 timer 已启用并运行', () => {
+      const properties = parseProperties(
+        runCommand('systemctl', [
+          'show',
+          'chat-hub-cert-renew.timer',
+          '--property=ActiveState,UnitFileState,LastTriggerUSec,NextElapseUSecRealtime',
+        ]),
+      );
+      assertEqual(properties.ActiveState, 'active', '证书续期 timer 未运行');
+      assertEnabled(properties.UnitFileState, '证书续期 timer 未启用');
+      return properties;
+    });
+    await record(checks, 'certificate-renewal-result', '证书续期验收最近成功', () => {
+      return validateCertificateRenewalResult(
+        fileSystem.readFileSync(ipCertificateAutomationPaths.result, 'utf8'),
+        now,
+      );
+    });
+  }
+
+  await record(checks, 'lark-cli-version', '飞书 CLI 版本经过验证', () => {
+    const invocation = cliInvocation(larkCliPath, nodePath);
+    const version = runCommand(invocation.executable, [...invocation.prefixArgs, '--version'])
+      .trim()
+      .split(/\r?\n/)[0];
+    if (!verifiedPlatformCliVersionPatterns['lark-cli'].test(version)) {
+      throw new Error(`未经验证的版本：${version}`);
+    }
+    return version;
+  });
+
+  await record(checks, 'dingtalk-cli-version', '钉钉 CLI 版本经过验证', () => {
+    const invocation = cliInvocation(dingtalkCliPath, nodePath);
+    const version = runCommand(invocation.executable, [...invocation.prefixArgs, '--version'])
+      .trim()
+      .split(/\r?\n/)[0];
+    if (!verifiedPlatformCliVersionPatterns.dws.test(version)) {
+      throw new Error(`未经验证的版本：${version}`);
+    }
+    return version;
+  });
+
+  for (const expected of expectedFileMetadata(certificateMode)) {
+    await record(checks, expected.id, expected.description, () => {
+      const metadata = fileSystem.lstatSync(expected.path);
+      if (metadata.isSymbolicLink()) throw new Error('不能是符号链接');
+      if (expected.type === 'file' && !metadata.isFile()) throw new Error('不是普通文件');
+      if (expected.type === 'directory' && !metadata.isDirectory()) throw new Error('不是目录');
+      const [owner, group, mode, size] = runCommand('stat', ['-c', '%U:%G:%a:%s', expected.path])
+        .trim()
+        .split(':');
+      assertEqual(owner, expected.owner, `所有者必须是 ${expected.owner}`);
+      assertEqual(group, expected.group, `所属组必须是 ${expected.group}`);
+      assertEqual(mode, expected.mode, `权限必须是 ${expected.mode}`);
+      if (expected.size !== undefined && Number(size) !== expected.size) {
+        throw new Error(`大小必须是 ${expected.size} 字节`);
+      }
+      return { path: expected.path, owner, group, mode, size: Number(size) };
+    });
+  }
+
+  await record(checks, 'listener-boundaries', '内部端口只监听回环且公网端口已监听', () => {
+    const sockets = parseListeningSockets(runCommand('ss', ['-ltnH']));
+    const details = {};
+    for (const [port, name] of internalPorts) {
+      const matches = sockets.filter((socket) => socket.port === port);
+      if (matches.length === 0) throw new Error(`${name} 端口 ${port} 未监听`);
+      if (matches.some((socket) => !isLoopback(socket.host))) {
+        throw new Error(`${name} 端口 ${port} 暴露在非回环地址`);
+      }
+      details[name] = matches.map((socket) => socket.host);
+    }
+    for (const [port, name] of publicPorts) {
+      const matches = sockets.filter((socket) => socket.port === port);
+      if (matches.length === 0) throw new Error(`公网 ${name} 端口 ${port} 未监听`);
+      details[name] = matches.map((socket) => socket.host);
+    }
+    return details;
+  });
+
+  await record(checks, 'internal-gateway-health', '内部安全网关健康', async () => {
+    const response = await fetchWithTimeout(internalFetchImpl, 'http://127.0.0.1:8080/api/health', {
+      headers: {
+        host: publicHost,
+        'x-forwarded-for': '127.0.0.1',
+        'x-forwarded-proto': publicScheme,
+      },
+    });
+    const body = await readJson(response);
+    if (!response.ok || body?.ok !== true || body.data?.status !== 'ready') {
+      throw new Error(`内部健康接口异常：HTTP ${response.status}`);
+    }
+    return { status: response.status, application: body.data.status };
+  });
+
+  if (publicScheme === 'https') {
+    await record(checks, 'http-redirect', '公网 HTTP 强制跳转到同域 HTTPS', async () => {
+      const response = await fetchWithTimeout(fetchImpl, `http://${publicHost}/api/health`, {
+        redirect: 'manual',
+      });
+      const location = response.headers.get('location');
+      if (![301, 302, 307, 308].includes(response.status)) {
+        throw new Error(`预期重定向，实际 HTTP ${response.status}`);
+      }
+      if (!location?.startsWith(`https://${publicHost}/`)) {
+        throw new Error('重定向目标不是同域 HTTPS');
+      }
+      return { status: response.status, location };
+    });
+  }
+
+  await record(
+    checks,
+    publicScheme === 'https' ? 'public-https-health' : 'public-http-health',
+    publicScheme === 'https'
+      ? '公网 HTTPS、证书和健康接口有效'
+      : '公网 HTTP 健康接口有效（传输未加密）',
+    async () => {
+      const response = await fetchWithTimeout(
+        fetchImpl,
+        `${publicScheme}://${publicHost}/api/health`,
+      );
+      const body = await readJson(response);
+      if (!response.ok || body?.ok !== true || body.data?.status !== 'ready') {
+        throw new Error(`公网健康接口异常：HTTP ${response.status}`);
+      }
+      return { status: response.status, application: body.data.status };
+    },
+  );
+
+  await record(checks, 'public-session-config', '公网管理员会话配置可读取', async () => {
+    const response = await fetchWithTimeout(
+      fetchImpl,
+      `${publicScheme}://${publicHost}/api/session/config`,
+    );
+    const body = await readJson(response);
+    if (
+      !response.ok ||
+      body?.ok !== true ||
+      body.data?.mode !== 'admin' ||
+      typeof body.data.initialized !== 'boolean'
+    ) {
+      throw new Error(`管理员会话配置异常：HTTP ${response.status}`);
+    }
+    return {
+      status: response.status,
+      mode: body.data.mode,
+      initialized: body.data.initialized,
+    };
+  });
+
+  let bootId;
+  await record(checks, 'boot-evidence', '记录当前 Linux 启动标识', () => {
+    bootId = fileSystem.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(bootId)) {
+      throw new Error('无法读取有效 boot ID');
+    }
+    return bootId;
+  });
+
+  const failed = checks.filter((check) => check.status === 'fail').length;
+  return {
+    command: 'verify-server',
+    domain: publicHost,
+    publicHost,
+    publicScheme,
+    checkedAt: new Date(now).toISOString(),
+    bootId,
+    passed: failed === 0,
+    summary: { total: checks.length, passed: checks.length - failed, failed },
+    checks,
+    rebootEvidence: '服务器重启后再次运行本命令；新的 bootId 与全通过结果共同作为开机自启证据。',
+  };
+}
+
+export function validateCertificateRenewalResult(rawResult, now = Date.now()) {
+  let result;
+  try {
+    result = JSON.parse(String(rawResult));
+  } catch {
+    throw new Error('续期结果不是有效 JSON');
+  }
+  if (result?.status !== 'succeeded' || !Number.isFinite(Date.parse(result.completedAt))) {
+    throw new Error('续期结果缺少成功时间');
+  }
+  const ageHours = (now - Date.parse(result.completedAt)) / 3_600_000;
+  if (ageHours < 0 || ageHours > 96) {
+    throw new Error(`最近一次成功续期已过去 ${ageHours.toFixed(1)} 小时`);
+  }
+  return { status: result.status, completedAt: result.completedAt, ageHours };
+}
+
+function isValidEndpoint(publicHost, publicScheme) {
+  if (publicScheme === 'https') {
+    return isPublicDomain(publicHost) || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(publicHost ?? '');
+  }
+  return publicScheme === 'http' && /^\d{1,3}(?:\.\d{1,3}){3}$/.test(publicHost ?? '');
+}
+
+export function parseListeningSockets(output) {
+  if (typeof output !== 'string') throw new Error('ss 输出必须是字符串');
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .flatMap((line) => {
+      const columns = line.split(/\s+/);
+      const local = columns[3];
+      if (!local) return [];
+      const match = local.match(/^(?:\[([^\]]+)\]|(.+)):(\d+)$/);
+      if (!match) return [];
+      return [{ host: (match[1] ?? match[2]).replace(/%.+$/, ''), port: Number(match[3]) }];
+    });
+}
+
+function expectedFileMetadata(certificateMode) {
+  const common = [
+    {
+      id: 'data-permissions',
+      description: '数据目录权限正确',
+      path: deploymentPaths.data,
+      type: 'directory',
+      owner: 'chat-hub',
+      group: 'chat-hub',
+      mode: '700',
+    },
+    {
+      id: 'backup-permissions',
+      description: '备份目录权限正确',
+      path: deploymentPaths.backups,
+      type: 'directory',
+      owner: 'chat-hub',
+      group: 'chat-hub',
+      mode: '700',
+    },
+    {
+      id: 'configuration-permissions',
+      description: '配置目录权限正确',
+      path: deploymentPaths.configuration,
+      type: 'directory',
+      owner: 'root',
+      group: 'chat-hub',
+      mode: '750',
+    },
+    {
+      id: 'credential-directory-permissions',
+      description: '凭证目录权限正确',
+      path: deploymentPaths.credentials,
+      type: 'directory',
+      owner: 'root',
+      group: 'root',
+      mode: '700',
+    },
+    {
+      id: 'master-key-permissions',
+      description: '主密钥是 root 独占的 32 字节普通文件',
+      path: deploymentPaths.masterKey,
+      type: 'file',
+      owner: 'root',
+      group: 'root',
+      mode: '600',
+      size: 32,
+    },
+    {
+      id: 'runtime-config-permissions',
+      description: '运行配置权限正确',
+      path: deploymentPaths.runtimeConfig,
+      type: 'file',
+      owner: 'root',
+      group: 'chat-hub',
+      mode: '640',
+    },
+    {
+      id: 'deployment-manifest-permissions',
+      description: '部署清单权限正确',
+      path: deploymentPaths.manifest,
+      type: 'file',
+      owner: 'root',
+      group: 'root',
+      mode: '644',
+    },
+    {
+      id: 'systemd-unit-permissions',
+      description: 'systemd 单元权限正确',
+      path: deploymentPaths.service,
+      type: 'file',
+      owner: 'root',
+      group: 'root',
+      mode: '644',
+    },
+    {
+      id: 'caddy-snippet-permissions',
+      description: 'Caddy 站点配置权限正确',
+      path: deploymentPaths.caddySnippet,
+      type: 'file',
+      owner: 'root',
+      group: 'root',
+      mode: '644',
+    },
+  ];
+  if (certificateMode !== 'ip-shortlived') return common;
+  return [
+    ...common,
+    {
+      id: 'ip-certificate-directory-permissions',
+      description: 'Caddy 的 IP 证书目录只允许 root 与 caddy 访问',
+      path: ipCertificateAutomationPaths.publishedDirectory,
+      type: 'directory',
+      owner: 'root',
+      group: 'caddy',
+      mode: '750',
+    },
+    {
+      id: 'ip-certificate-chain-permissions',
+      description: 'Caddy 可只读访问发布的 IP 证书链',
+      path: ipCertificateAutomationPaths.publishedFullchain,
+      type: 'file',
+      owner: 'root',
+      group: 'caddy',
+      mode: '640',
+    },
+    {
+      id: 'ip-certificate-key-permissions',
+      description: 'Caddy 可只读访问发布的 IP 私钥副本',
+      path: ipCertificateAutomationPaths.publishedPrivateKey,
+      type: 'file',
+      owner: 'root',
+      group: 'caddy',
+      mode: '640',
+    },
+  ];
+}
+
+async function record(checks, id, description, operation) {
+  try {
+    const evidence = await operation();
+    checks.push({ id, description, status: 'pass', evidence });
+  } catch (error) {
+    checks.push({
+      id,
+      description,
+      status: 'fail',
+      error: safeError(error),
+    });
+  }
+}
+
+function defaultRunCommand(executable, args) {
+  return execFileSync(executable, args, {
+    encoding: 'utf8',
+    timeout: 15_000,
+    maxBuffer: 1024 * 1024,
+    stdio: 'pipe',
+    env: { ...process.env, LC_ALL: 'C' },
+  });
+}
+
+async function fetchWithTimeout(fetchImpl, url, options = {}) {
+  return fetchImpl(url, {
+    ...options,
+    signal: AbortSignal.timeout(10_000),
+  });
+}
+
+export function fetchInternalGateway(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const request = httpRequest(
+      url,
+      {
+        headers: options.headers,
+        signal: options.signal,
+      },
+      (response) => {
+        const chunks = [];
+        let size = 0;
+        response.on('data', (chunk) => {
+          size += chunk.length;
+          if (size > 64 * 1024) {
+            request.destroy(new Error('验收接口响应超过 64 KiB'));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        response.on('end', () => {
+          resolve(
+            new Response(Buffer.concat(chunks), {
+              status: response.statusCode ?? 500,
+              headers: response.headers,
+            }),
+          );
+        });
+      },
+    );
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (text.length > 64 * 1024) throw new Error('验收接口响应超过 64 KiB');
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error('验收接口未返回有效 JSON');
+  }
+}
+
+function parseProperties(output) {
+  return Object.fromEntries(
+    output
+      .split(/\r?\n/)
+      .filter((line) => line.includes('='))
+      .map((line) => {
+        const separator = line.indexOf('=');
+        return [line.slice(0, separator), line.slice(separator + 1)];
+      }),
+  );
+}
+
+function cliInvocation(executable, nodePath) {
+  return executable.toLowerCase().endsWith('.js')
+    ? { executable: nodePath, prefixArgs: [executable] }
+    : { executable, prefixArgs: [] };
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) throw new Error(`${message}（实际 ${actual ?? '缺失'}）`);
+}
+
+function assertEnabled(value, message) {
+  if (value !== 'enabled' && value !== 'enabled-runtime') {
+    throw new Error(`${message}（实际 ${value ?? '缺失'}）`);
+  }
+}
+
+function isLoopback(host) {
+  return host === '127.0.0.1' || host === '::1';
+}
+
+function isPublicDomain(domain) {
+  return (
+    typeof domain === 'string' &&
+    domain.length <= 253 &&
+    domain.includes('.') &&
+    /^[a-z0-9.-]+$/.test(domain) &&
+    !domain
+      .split('.')
+      .some(
+        (label) => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'),
+      ) &&
+    !/^\d+(?:\.\d+){3}$/.test(domain)
+  );
+}
+
+function safeError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\r\n]+/g, ' ').slice(0, 500);
+}

package/cli/windows-data-migration.mjs

@@ -0,0 +1,145 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+export function migrateLegacyWindowsData({
+  legacyDirectory,
+  currentDirectory,
+  backupRoot,
+  now = Date.now(),
+  verifyCopy,
+} = {}) {
+  for (const [name, value] of Object.entries({
+    legacyDirectory,
+    currentDirectory,
+    backupRoot,
+  })) {
+    if (typeof value !== 'string' || !isAbsolute(value)) {
+      throw new Error(`${name} 必须是绝对路径`);
+    }
+  }
+  const legacy = resolve(legacyDirectory);
+  const current = resolve(currentDirectory);
+  const backups = resolve(backupRoot);
+  assertSeparatePaths(legacy, current, backups);
+  const legacyExists = existsSync(legacy);
+  const currentExists = existsSync(current);
+  if (legacyExists && currentExists) {
+    throw new Error(`检测到新旧两个数据目录，已停止以避免打开错误数据库：${current}；${legacy}`);
+  }
+  if (!legacyExists) return { migrated: false, currentDirectory: current };
+  if (!lstatSync(legacy).isDirectory() || lstatSync(legacy).isSymbolicLink()) {
+    throw new Error('旧版 Windows 数据路径不是普通目录，已停止自动迁移');
+  }
+  const sourceManifest = directoryManifest(legacy);
+  mkdirSync(dirname(current), { recursive: true });
+  mkdirSync(backups, { recursive: true });
+  const suffix = `${new Date(now).toISOString().replaceAll(':', '').replaceAll('.', '-')}-${randomUUID().slice(0, 8)}`;
+  const staged = `${current}.migration-${suffix}`;
+  const backup = join(backups, `legacy-${suffix}`);
+  try {
+    copyAndVerify(legacy, staged, sourceManifest, verifyCopy);
+    copyAndVerify(legacy, backup, sourceManifest, verifyCopy);
+    renameSync(staged, current);
+    try {
+      rmSync(legacy, { recursive: true, force: false });
+    } catch (error) {
+      throw new Error(
+        `新目录和备份已创建，但旧目录无法移除；为避免歧义，下次启动会停止。请核对 ${legacy}：${error instanceof Error ? error.message : '未知错误'}`,
+      );
+    }
+    return {
+      migrated: true,
+      currentDirectory: current,
+      legacyDirectory: legacy,
+      backupDirectory: backup,
+      fileCount: sourceManifest.length,
+    };
+  } catch (error) {
+    if (!existsSync(current)) rmSync(staged, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function copyAndVerify(source, destination, expectedManifest, verifyCopy) {
+  cpSync(source, destination, {
+    recursive: true,
+    errorOnExist: true,
+    force: false,
+    preserveTimestamps: true,
+  });
+  const actualManifest = directoryManifest(destination);
+  if (JSON.stringify(actualManifest) !== JSON.stringify(expectedManifest)) {
+    rmSync(destination, { recursive: true, force: true });
+    throw new Error(`Windows 数据迁移副本校验失败：${basename(destination)}`);
+  }
+  try {
+    verifyCopy?.(destination);
+  } catch (error) {
+    rmSync(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function directoryManifest(directory) {
+  const entries = [];
+  const queue = [''];
+  while (queue.length > 0) {
+    const relativeDirectory = queue.shift();
+    const absoluteDirectory = join(directory, relativeDirectory);
+    const children = readdirSync(absoluteDirectory, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    for (const child of children) {
+      const relativePath = join(relativeDirectory, child.name);
+      const absolutePath = join(directory, relativePath);
+      const metadata = lstatSync(absolutePath);
+      if (metadata.isSymbolicLink()) {
+        throw new Error(`Windows 数据迁移不允许符号链接：${relativePath}`);
+      }
+      if (metadata.isDirectory()) {
+        entries.push({ path: relativePath, type: 'directory' });
+        queue.push(relativePath);
+      } else if (metadata.isFile()) {
+        entries.push({
+          path: relativePath,
+          type: 'file',
+          size: metadata.size,
+          sha256: createHash('sha256').update(readFileSync(absolutePath)).digest('hex'),
+        });
+      } else {
+        throw new Error(`Windows 数据迁移只接受普通文件和目录：${relativePath}`);
+      }
+    }
+  }
+  return entries.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function assertSeparatePaths(legacy, current, backups) {
+  const pairs = [
+    [legacy, current],
+    [legacy, backups],
+    [current, backups],
+  ];
+  for (const [left, right] of pairs) {
+    const leftToRight = relative(left, right);
+    const rightToLeft = relative(right, left);
+    if (
+      leftToRight === '' ||
+      (!leftToRight.startsWith('..') && !isAbsolute(leftToRight)) ||
+      (!rightToLeft.startsWith('..') && !isAbsolute(rightToLeft))
+    ) {
+      throw new Error('Windows 数据迁移的新、旧和备份目录不能互相包含');
+    }
+  }
+}