whistle.mockbubu 2.0.0 → 2.1.1

package/lib/utils/archive-utils.js

@@ -0,0 +1,788 @@
+/**
+ * 文件名: archive-utils.js
+ * 功能: 压缩包工具函数（tar.gz 格式）
+ * 依赖: Node.js 内置 API（无需额外依赖）
+ *
+ * 职责:
+ * - 创建 tar.gz 压缩包（手动实现 tar 格式）
+ * - 解压 tar.gz 压缩包
+ * - 目录递归复制和遍历
+ * - 文件名安全处理（防止路径遍历攻击）
+ * - Multipart 文件上传解析（原生实现）
+ *
+ * tar 格式说明:
+ * - tar 文件由一系列 512 字节的块组成
+ * - 每个文件包含：header (512 bytes) + content (对齐到 512 bytes)
+ * - header 采用 POSIX ustar 格式
+ * - 文件结束标记：两个连续的 512 字节零块
+ *
+ * 使用场景:
+ * - 导出组数据为 tar.gz 压缩包
+ * - 导入 tar.gz 压缩包并恢复组数据
+ *
+ * 使用示例:
+ * ```javascript
+ * const { createTarGz, extractTarGz } = require('./archive-utils')
+ *
+ * // 创建压缩包
+ * await createTarGz('/path/to/source', '/path/to/output.tar.gz')
+ *
+ * // 解压压缩包
+ * await extractTarGz('/path/to/archive.tar.gz', '/path/to/dest')
+ * ```
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+const zlib = require('zlib')
+const { createReadStream, createWriteStream } = require('fs')
+const { pipeline } = require('stream/promises')
+const os = require('os')
+const { createLogger } = require('./logger')
+
+// 创建 logger 实例
+const logger = createLogger('archive-utils')
+
+/**
+ * 递归复制目录（包括所有子目录和文件）
+ * 使用深度优先遍历，保持目录结构
+ *
+ * 工作流程:
+ * 1. 创建目标目录（如果不存在）
+ * 2. 读取源目录下的所有条目
+ * 3. 对于每个条目：
+ *    - 如果是目录：递归复制
+ *    - 如果是文件：直接复制
+ *
+ * @param {string} src - 源目录路径
+ * @param {string} dest - 目标目录路径
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await copyDirectory('/path/to/source', '/path/to/dest')
+ * // 复制 source 目录下的所有内容到 dest 目录
+ */
+async function copyDirectory(src, dest) {
+  // 1. 创建目标目录（recursive: true 会自动创建父目录）
+  await fs.mkdir(dest, { recursive: true })
+
+  // 2. 读取源目录下的所有条目（withFileTypes 返回 Dirent 对象）
+  const entries = await fs.readdir(src, { withFileTypes: true })
+
+  // 3. 遍历所有条目
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      // 递归复制子目录
+      await copyDirectory(srcPath, destPath)
+    } else {
+      // 复制文件
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
+/**
+ * 递归读取目录，返回所有文件路径（用于打包）
+ * 使用深度优先遍历，收集所有文件的绝对路径和相对路径
+ *
+ * 工作流程:
+ * 1. 读取目录下的所有条目
+ * 2. 对于每个条目：
+ *    - 如果是目录：递归读取
+ *    - 如果是文件：添加到结果列表
+ * 3. 返回包含所有文件信息的数组
+ *
+ * @param {string} dir - 要读取的目录路径
+ * @param {string} baseDir - 基准目录（用于计算相对路径，默认为 dir）
+ * @returns {Promise<Array>} 文件列表，每个文件包含 path（绝对路径）和 name（相对路径）
+ *
+ * @example
+ * const files = await getAllFiles('/path/to/dir')
+ * files.forEach(file => {
+ *   console.log('绝对路径:', file.path)
+ *   console.log('相对路径:', file.name)
+ * })
+ * // 输出示例:
+ * // 绝对路径: /path/to/dir/file1.json
+ * // 相对路径: file1.json
+ * // 绝对路径: /path/to/dir/subdir/file2.json
+ * // 相对路径: subdir/file2.json
+ */
+async function getAllFiles(dir, baseDir = dir) {
+  const files = []
+
+  // 读取目录下的所有条目
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+
+  // 遍历所有条目
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      // 递归读取子目录（展开数组）
+      files.push(...await getAllFiles(fullPath, baseDir))
+    } else {
+      // 添加文件信息
+      files.push({
+        path: fullPath, // 绝对路径
+        name: path.relative(baseDir, fullPath), // 相对于基准目录的路径
+      })
+    }
+  }
+
+  return files
+}
+
+/**
+ * 创建 tar.gz 压缩包（两步法）
+ * 使用 Node.js 内置 zlib + tar 格式手动实现
+ *
+ * 工作流程:
+ * 1. 递归遍历源目录，获取所有文件列表
+ * 2. 创建 tar 文件（按 POSIX ustar 格式）
+ * 3. 使用 gzip 压缩 tar 文件
+ * 4. 删除临时 tar 文件
+ *
+ * 文件格式:
+ * - 输出文件: .tar.gz（gzip 压缩的 tar 归档）
+ * - 中间文件: .tar（临时文件，最后会被删除）
+ *
+ * @param {string} sourceDir - 源目录路径
+ * @param {string} outputFile - 输出文件路径（必须以 .tar.gz 结尾）
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await createTarGz('/path/to/source', '/path/to/output.tar.gz')
+ * // 将 source 目录打包为 output.tar.gz
+ */
+async function createTarGz(sourceDir, outputFile) {
+  // 1. 获取源目录下的所有文件
+  const files = await getAllFiles(sourceDir)
+  logger.log(`准备打包 ${files.length} 个文件`)
+
+  // 2. 创建 tar 文件（临时文件）
+  const tarPath = outputFile.replace(/\.gz$/, '')
+  await createTar(sourceDir, tarPath, files)
+
+  // 3. 使用 gzip 压缩 tar 文件
+  await new Promise((resolve, reject) => {
+    const input = createReadStream(tarPath)
+    const output = createWriteStream(outputFile)
+    const gzip = zlib.createGzip()
+
+    pipeline(input, gzip, output)
+      .then(() => {
+        // 4. 删除临时 tar 文件
+        fs.unlink(tarPath).catch(() => {})
+        logger.log(`压缩完成: ${outputFile}`)
+        resolve()
+      })
+      .catch(reject)
+  })
+}
+
+/**
+ * 创建 tar 文件（手动实现 POSIX ustar 格式）
+ *
+ * tar 文件结构:
+ * ```
+ * [File 1 Header (512 bytes)]
+ * [File 1 Content (对齐到 512 bytes)]
+ * [File 2 Header (512 bytes)]
+ * [File 2 Content (对齐到 512 bytes)]
+ * ...
+ * [End Marker (1024 bytes 的零)]
+ * ```
+ *
+ * 工作流程:
+ * 1. 对每个文件：
+ *    a. 读取文件状态（大小）和内容
+ *    b. 生成 tar header（512 字节）
+ *    c. 写入 header
+ *    d. 写入文件内容
+ *    e. 填充零字节，对齐到 512 字节边界
+ * 2. 写入结束标记（两个连续的 512 字节零块）
+ *
+ * 对齐规则:
+ * - tar 格式要求所有块都是 512 字节的倍数
+ * - 文件内容后需要填充零字节
+ * - 例如：文件大小 100 字节，需要填充 412 字节（512 - 100 = 412）
+ *
+ * @param {string} sourceDir - 源目录路径（未使用，保留用于扩展）
+ * @param {string} outputFile - 输出 tar 文件路径
+ * @param {Array} files - 文件列表（来自 getAllFiles）
+ * @returns {Promise<void>}
+ *
+ * @example
+ * const files = await getAllFiles('/path/to/source')
+ * await createTar('/path/to/source', '/path/to/output.tar', files)
+ */
+async function createTar(sourceDir, outputFile, files) {
+  const output = createWriteStream(outputFile)
+
+  // 遍历所有文件
+  for (const file of files) {
+    // 1. 读取文件状态和内容
+    const stat = await fs.stat(file.path)
+    const content = await fs.readFile(file.path)
+
+    // 2. 生成 tar header（512 字节）
+    const header = createTarHeader(file.name, stat.size)
+
+    // 3. 写入 header
+    output.write(header)
+
+    // 4. 写入文件内容
+    output.write(content)
+
+    // 5. 对齐到 512 字节边界
+    // 计算需要填充的字节数
+    const padding = 512 - (content.length % 512)
+    if (padding < 512) {
+      // 填充零字节
+      output.write(Buffer.alloc(padding, 0))
+    }
+  }
+
+  // 6. 写入结束标记（两个 512 字节的零块，共 1024 字节）
+  output.write(Buffer.alloc(1024, 0))
+  output.end()
+
+  // 等待写入完成
+  return new Promise((resolve, reject) => {
+    output.on('finish', resolve)
+    output.on('error', reject)
+  })
+}
+
+/**
+ * 创建 tar header（POSIX ustar 格式，512 字节）
+ *
+ * POSIX ustar header 结构（所有数值都是 8 进制 ASCII 字符串）：
+ * ```
+ * Offset | Size | Field         | Description
+ * -------|------|---------------|----------------------------------
+ * 0      | 100  | name          | 文件名（NUL 结尾）
+ * 100    | 8    | mode          | 文件权限（8进制，如 '0000644 '）
+ * 108    | 8    | uid           | 用户ID（8进制）
+ * 116    | 8    | gid           | 组ID（8进制）
+ * 124    | 12   | size          | 文件大小（8进制，11位数字 + 空格）
+ * 136    | 12   | mtime         | 修改时间（8进制，Unix 时间戳）
+ * 148    | 8    | chksum        | 校验和（8进制，6位数字 + NUL + 空格）
+ * 156    | 1    | typeflag      | 文件类型（'0' = 普通文件）
+ * 157    | 100  | linkname      | 链接目标名（本实现不使用）
+ * 257    | 6    | magic         | ustar 魔数（'ustar'）
+ * 263    | 2    | version       | ustar 版本（'00'）
+ * 265    | 32   | uname         | 用户名（本实现不使用）
+ * 297    | 32   | gname         | 组名（本实现不使用）
+ * 329    | 8    | devmajor      | 设备主号（本实现不使用）
+ * 337    | 8    | devminor      | 设备次号（本实现不使用）
+ * 345    | 155  | prefix        | 文件名前缀（本实现不使用）
+ * 500    | 12   | padding       | 填充（全零）
+ * ```
+ *
+ * Checksum 计算方法:
+ * 1. 将 checksum 字段填充为 8 个空格
+ * 2. 将 header 的所有字节值相加
+ * 3. 将总和转换为 8 进制字符串，写入 checksum 字段
+ *
+ * @param {string} filename - 文件名（相对路径）
+ * @param {number} size - 文件大小（字节）
+ * @returns {Buffer} 512 字节的 tar header
+ *
+ * @example
+ * const header = createTarHeader('path/to/file.json', 1024)
+ * // 返回 512 字节的 Buffer，符合 POSIX ustar 格式
+ */
+function createTarHeader(filename, size) {
+  // 分配 512 字节的 buffer，初始化为全零
+  const header = Buffer.alloc(512, 0)
+
+  // --- 字段 1: 文件名 (offset 0, size 100 bytes) ---
+  header.write(filename, 0, 100, 'utf8')
+
+  // --- 字段 2: 文件权限 (offset 100, size 8 bytes) ---
+  // 0644 = 所有者可读写，组和其他人只读
+  header.write('0000644 ', 100, 8, 'utf8')
+
+  // --- 字段 3: 用户ID (offset 108, size 8 bytes) ---
+  header.write('0000000 ', 108, 8, 'utf8')
+
+  // --- 字段 4: 组ID (offset 116, size 8 bytes) ---
+  header.write('0000000 ', 116, 8, 'utf8')
+
+  // --- 字段 5: 文件大小 (offset 124, size 12 bytes) ---
+  // 转换为 8 进制字符串，左侧补零到 11 位，末尾加空格
+  const sizeOctal = size.toString(8).padStart(11, '0') + ' '
+  header.write(sizeOctal, 124, 12, 'utf8')
+
+  // --- 字段 6: 修改时间 (offset 136, size 12 bytes) ---
+  // Unix 时间戳（秒），转换为 8 进制
+  const mtime = Math.floor(Date.now() / 1000).toString(8).padStart(11, '0') + ' '
+  header.write(mtime, 136, 12, 'utf8')
+
+  // --- 字段 7: Checksum (offset 148, size 8 bytes) ---
+  // 先填充 8 个空格（计算 checksum 时需要）
+  header.write('        ', 148, 8, 'utf8')
+
+  // --- 字段 8: 文件类型 (offset 156, size 1 byte) ---
+  // '0' 或 '\0' = 普通文件
+  header.write('0', 156, 1, 'utf8')
+
+  // --- 字段 9: ustar 魔数 (offset 257, size 6 bytes) ---
+  // 'ustar' + NUL 结尾（自动添加）
+  header.write('ustar', 257, 6, 'utf8')
+
+  // --- 字段 10: ustar 版本 (offset 263, size 2 bytes) ---
+  // '00' 表示 POSIX ustar 格式
+  header.write('00', 263, 2, 'utf8')
+
+  // --- 计算并写入 Checksum ---
+  // 1. 将 header 的所有字节值相加
+  let checksum = 0
+  for (let i = 0; i < 512; i++) {
+    checksum += header[i]
+  }
+
+  // 2. 转换为 8 进制字符串（6位数字 + NUL + 空格）
+  const checksumOctal = checksum.toString(8).padStart(6, '0') + '\0 '
+
+  // 3. 写入 checksum 字段
+  header.write(checksumOctal, 148, 8, 'utf8')
+
+  return header
+}
+
+/**
+ * 解压 tar.gz 文件到指定目录
+ * 这是 createTarGz 的反向操作
+ *
+ * 工作流程:
+ * 1. 使用 zlib.createGunzip() 解压 gzip 层，得到 .tar 文件（临时）
+ * 2. 调用 extractTar() 解压 tar 文件，提取所有文件到目标目录
+ * 3. 删除临时 .tar 文件
+ *
+ * 文件格式:
+ * - 输入文件: .tar.gz（gzip 压缩的 tar 归档）
+ * - 中间文件: .tar（临时文件，存储在系统临时目录）
+ * - 输出: 解压后的目录树
+ *
+ * 错误处理:
+ * - 如果 gzip 解压失败，会抛出异常
+ * - 如果 tar 解压失败，会抛出异常
+ * - 临时文件删除失败会被静默忽略
+ *
+ * @param {string} archiveFile - tar.gz 文件路径
+ * @param {string} destDir - 目标目录路径（会自动创建）
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await extractTarGz('/path/to/archive.tar.gz', '/path/to/output')
+ * // 将 archive.tar.gz 解压到 output 目录
+ */
+async function extractTarGz(archiveFile, destDir) {
+  // 先 gunzip 解压
+  const tarPath = path.join(os.tmpdir(), `extract-${Date.now()}.tar`)
+
+  await new Promise((resolve, reject) => {
+    const input = createReadStream(archiveFile)
+    const output = createWriteStream(tarPath)
+    const gunzip = zlib.createGunzip()
+
+    pipeline(input, gunzip, output)
+      .then(resolve)
+      .catch(reject)
+  })
+
+  // 解压 tar
+  await extractTar(tarPath, destDir)
+
+  // 删除临时 tar 文件
+  await fs.unlink(tarPath).catch(() => {})
+}
+
+/**
+ * 解压 tar 文件（手动实现 POSIX ustar 格式解析）
+ * 这是 createTar 的反向操作
+ *
+ * 工作流程:
+ * 1. 读取整个 tar 文件到内存（Buffer）
+ * 2. 从头开始逐块解析：
+ *    a. 读取 512 字节 header
+ *    b. 从 header 提取文件名（offset 0-100）
+ *    c. 从 header 提取文件大小（offset 124-136，8进制字符串）
+ *    d. 跳过 header（512 字节）
+ *    e. 读取文件内容（size 字节）
+ *    f. 创建目录（递归）并写入文件
+ *    g. 跳过填充字节（对齐到 512 字节边界）
+ * 3. 重复直到遇到结束标记（全零块）
+ *
+ * tar 文件结构:
+ * ```
+ * [File 1 Header (512 bytes)] ← 包含文件名和大小
+ * [File 1 Content (size bytes)]
+ * [Padding to 512 boundary]
+ * [File 2 Header (512 bytes)]
+ * [File 2 Content (size bytes)]
+ * [Padding to 512 boundary]
+ * ...
+ * [End Marker (1024 bytes of zeros)]
+ * ```
+ *
+ * Header 字段解析:
+ * - name (0-100): 文件名（NUL 结尾的 UTF-8 字符串）
+ * - size (124-136): 文件大小（8进制 ASCII 字符串）
+ *
+ * 安全性:
+ * - 自动创建目录结构（recursive: true）
+ * - 不验证路径安全性（调用方需使用 isPathSafe 检查）
+ *
+ * @param {string} tarFile - tar 文件路径
+ * @param {string} destDir - 目标目录路径（会自动创建子目录）
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await extractTar('/path/to/archive.tar', '/path/to/output')
+ * // 将 archive.tar 解压到 output 目录
+ *
+ * @example
+ * // 安全解压（防止路径遍历）
+ * const destDir = '/safe/path'
+ * await extractTar(tarFile, destDir)
+ * // 注意：需要在调用前使用 isPathSafe 验证文件名
+ */
+async function extractTar(tarFile, destDir) {
+  const buffer = await fs.readFile(tarFile)
+  let offset = 0
+
+  while (offset < buffer.length) {
+    // 检查是否到达结束标记
+    if (buffer[offset] === 0) {
+      break
+    }
+
+    // 读取 header
+    const header = buffer.subarray(offset, offset + 512)
+
+    // 读取文件名
+    const filename = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '')
+    if (!filename) break
+
+    // 读取文件大小
+    const sizeStr = header.subarray(124, 136).toString('utf8').trim()
+    const size = parseInt(sizeStr, 8)
+
+    // 跳过 header
+    offset += 512
+
+    // 读取文件内容
+    const content = buffer.subarray(offset, offset + size)
+
+    // 写入文件
+    const filepath = path.join(destDir, filename)
+    await fs.mkdir(path.dirname(filepath), { recursive: true })
+    await fs.writeFile(filepath, content)
+
+    // 移动到下一个文件（对齐到 512 字节）
+    const padding = 512 - (size % 512)
+    offset += size + (padding < 512 ? padding : 0)
+  }
+}
+
+/**
+ * 文件名安全处理（移除特殊字符）
+ * 将 Windows 和 Unix 系统禁止的字符替换为下划线
+ *
+ * 替换的字符:
+ * - Windows 保留字符: `< > : " / \ | ? *`
+ * - 控制字符: `\x00-\x1F`（ASCII 0-31，如 NUL、换行符等）
+ *
+ * 使用场景:
+ * - 处理用户上传的文件名
+ * - 从 URL 生成文件名
+ * - 创建导出文件名
+ *
+ * 注意事项:
+ * - 不验证文件名长度（调用方需检查）
+ * - 不处理路径遍历（如 `../`，需使用 isPathSafe）
+ * - 保留文件扩展名
+ *
+ * @param {string} filename - 原始文件名（可能包含特殊字符）
+ * @returns {string} 安全的文件名（特殊字符被替换为下划线）
+ *
+ * @example
+ * sanitizeFilename('test<file>.json')
+ * // 返回: 'test_file_.json'
+ *
+ * @example
+ * sanitizeFilename('path/to/file.txt')
+ * // 返回: 'path_to_file.txt'
+ *
+ * @example
+ * sanitizeFilename('file\x00name.txt')
+ * // 返回: 'file_name.txt'
+ */
+function sanitizeFilename(filename) {
+  // eslint-disable-next-line no-control-regex
+  return filename.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+}
+
+/**
+ * 检查路径是否在指定目录内（防止路径遍历攻击）
+ * 用于验证解压或文件操作时的路径安全性
+ *
+ * 工作原理:
+ * 1. 规范化文件路径（处理 `..`、`.`、多余斜杠）
+ * 2. 计算相对于基础目录的相对路径
+ * 3. 检查相对路径是否：
+ *    - 不以 `..` 开头（不能跳出基础目录）
+ *    - 不是绝对路径（不能访问系统其他位置）
+ *
+ * 安全性:
+ * - 防止路径遍历攻击（Path Traversal）
+ * - 防止访问基础目录之外的文件
+ * - 防止符号链接攻击（间接）
+ *
+ * 使用场景:
+ * - 解压 tar.gz 文件前验证文件路径
+ * - 处理用户上传的文件路径
+ * - 任何涉及文件系统操作的路径验证
+ *
+ * @param {string} filepath - 要检查的文件路径（可能包含 `..`）
+ * @param {string} baseDir - 基础目录路径（安全边界）
+ * @returns {boolean} true 表示路径安全（在基础目录内），false 表示不安全
+ *
+ * @example
+ * // 安全路径
+ * isPathSafe('/base/dir/file.txt', '/base/dir')
+ * // 返回: true
+ *
+ * @example
+ * // 路径遍历攻击
+ * isPathSafe('/base/dir/../../../etc/passwd', '/base/dir')
+ * // 返回: false（相对路径以 .. 开头）
+ *
+ * @example
+ * // 绝对路径攻击
+ * isPathSafe('/etc/passwd', '/base/dir')
+ * // 返回: false（是绝对路径）
+ *
+ * @example
+ * // 实际使用（解压 tar 文件）
+ * const destDir = '/safe/path'
+ * const filename = header.readFilename() // 从 tar header 读取
+ * const filepath = path.join(destDir, filename)
+ * if (!isPathSafe(filepath, destDir)) {
+ *   throw new Error('不安全的文件路径: ' + filename)
+ * }
+ * await fs.writeFile(filepath, content)
+ */
+function isPathSafe(filepath, baseDir) {
+  const normalized = path.normalize(filepath)
+  const relative = path.relative(baseDir, normalized)
+  return !relative.startsWith('..') && !path.isAbsolute(relative)
+}
+
+/**
+ * 解析 multipart/form-data 文件上传（原生实现）
+ * 从 Koa 请求中提取上传的文件，不依赖第三方库
+ *
+ * 工作流程:
+ * 1. 验证 Content-Type 是否为 `multipart/form-data`
+ * 2. 从 Content-Type 提取 boundary（分隔符）
+ * 3. 监听请求流，收集所有数据块到 Buffer
+ * 4. 调用 parseMultipartBuffer() 解析 Buffer
+ * 5. 返回第一个上传的文件对象
+ *
+ * HTTP multipart/form-data 格式:
+ * ```
+ * ------WebKitFormBoundary7MA4YWxkTrZu0gW
+ * Content-Disposition: form-data; name="file"; filename="test.txt"
+ * Content-Type: text/plain
+ *
+ * file content here
+ * ------WebKitFormBoundary7MA4YWxkTrZu0gW--
+ * ```
+ *
+ * 返回对象结构:
+ * ```javascript
+ * {
+ *   fieldname: 'file',      // 表单字段名
+ *   filename: 'test.txt',   // 原始文件名
+ *   buffer: Buffer          // 文件内容（Buffer）
+ * }
+ * ```
+ *
+ * 错误处理:
+ * - 非 multipart/form-data 请求会抛出异常
+ * - 缺少 boundary 会抛出异常
+ * - 解析失败会抛出异常
+ *
+ * @param {Object} ctx - Koa 上下文对象
+ * @param {Object} ctx.request - Koa 请求对象
+ * @param {Object} ctx.request.headers - 请求头
+ * @param {string} ctx.request.headers['content-type'] - Content-Type 头
+ * @param {Object} ctx.req - Node.js 原生请求对象（Stream）
+ * @returns {Promise<Object>} 文件对象 { fieldname, filename, buffer }
+ *
+ * @example
+ * // 在 Koa 路由中使用
+ * router.post('/upload', async (ctx) => {
+ *   try {
+ *     const file = await parseMultipartFile(ctx)
+ *     console.log('上传文件:', file.filename)
+ *     console.log('文件大小:', file.buffer.length)
+ *     await fs.writeFile(`/uploads/${file.filename}`, file.buffer)
+ *     ctx.body = { success: true, filename: file.filename }
+ *   } catch (err) {
+ *     ctx.status = 400
+ *     ctx.body = { error: err.message }
+ *   }
+ * })
+ */
+async function parseMultipartFile(ctx) {
+  return new Promise((resolve, reject) => {
+    const contentType = ctx.request.headers['content-type']
+    if (!contentType || !contentType.includes('multipart/form-data')) {
+      reject(new Error('不是 multipart/form-data 格式'))
+      return
+    }
+
+    // 提取 boundary
+    const boundaryMatch = contentType.match(/boundary=(.+)/)
+    if (!boundaryMatch) {
+      reject(new Error('缺少 boundary'))
+      return
+    }
+    const boundary = '--' + boundaryMatch[1]
+
+    const chunks = []
+    ctx.req.on('data', chunk => chunks.push(chunk))
+    ctx.req.on('end', () => {
+      try {
+        const buffer = Buffer.concat(chunks)
+        const file = parseMultipartBuffer(buffer, boundary)
+        resolve(file)
+      } catch (err) {
+        reject(err)
+      }
+    })
+    ctx.req.on('error', reject)
+  })
+}
+
+/**
+ * 解析 multipart buffer（底层解析器）
+ * 从原始 Buffer 中提取文件数据，由 parseMultipartFile 调用
+ *
+ * 工作流程:
+ * 1. 从头开始遍历 buffer，查找 boundary 分隔符
+ * 2. 对每个 boundary 之间的部分：
+ *    a. 查找下一个 boundary（确定部分边界）
+ *    b. 提取部分内容（header + body）
+ *    c. 查找 `\r\n\r\n`（header 和 body 的分隔符）
+ *    d. 解析 Content-Disposition 头提取 filename 和 name
+ *    e. 提取文件内容（去掉结尾的 `\r\n`）
+ *    f. 添加到 parts 数组
+ * 3. 返回第一个文件对象
+ *
+ * Multipart 部分结构:
+ * ```
+ * ------WebKitFormBoundary... ← boundary 开始
+ * Content-Disposition: form-data; name="file"; filename="test.txt" ← header
+ * Content-Type: text/plain
+ * \r\n ← header 结束
+ * file content here ← body
+ * \r\n ← body 结束
+ * ------WebKitFormBoundary... ← 下一个 boundary
+ * ```
+ *
+ * 解析逻辑:
+ * - header 和 body 之间用 `\r\n\r\n` 分隔
+ * - body 结尾有 `\r\n`（需要去除）
+ * - boundary 前有 `--` 前缀
+ * - 最后的 boundary 后有 `--` 后缀
+ *
+ * 返回对象结构:
+ * ```javascript
+ * {
+ *   fieldname: 'file',      // 表单字段名（从 name 提取）
+ *   filename: 'test.txt',   // 原始文件名（从 filename 提取）
+ *   buffer: Buffer          // 文件内容（Buffer，已去除 \r\n）
+ * }
+ * ```
+ *
+ * 注意事项:
+ * - 仅返回第一个文件（不支持多文件上传）
+ * - 不验证 Content-Type
+ * - 不处理非文件字段（如文本输入）
+ *
+ * @param {Buffer} buffer - 完整的 multipart 请求体
+ * @param {string} boundary - boundary 字符串（已包含 `--` 前缀）
+ * @returns {Object} 文件对象 { fieldname, filename, buffer }
+ *
+ * @example
+ * const buffer = Buffer.from(
+ *   '------WebKitFormBoundary...\r\n' +
+ *   'Content-Disposition: form-data; name="file"; filename="test.txt"\r\n' +
+ *   '\r\n' +
+ *   'file content\r\n' +
+ *   '------WebKitFormBoundary...--'
+ * )
+ * const file = parseMultipartBuffer(buffer, '------WebKitFormBoundary...')
+ * console.log(file.filename) // 'test.txt'
+ * console.log(file.buffer.toString()) // 'file content'
+ */
+function parseMultipartBuffer(buffer, boundary) {
+  const parts = []
+  let start = 0
+
+  while (start < buffer.length) {
+    // 查找 boundary
+    const boundaryIndex = buffer.indexOf(boundary, start)
+    if (boundaryIndex === -1) break
+
+    // 查找下一个 boundary
+    const nextBoundaryIndex = buffer.indexOf(boundary, boundaryIndex + boundary.length)
+    if (nextBoundaryIndex === -1) break
+
+    // 提取部分内容
+    const partBuffer = buffer.subarray(boundaryIndex + boundary.length, nextBoundaryIndex)
+
+    // 查找 headers 和 body 的分隔符（\r\n\r\n）
+    const headerEndIndex = partBuffer.indexOf('\r\n\r\n')
+    if (headerEndIndex !== -1) {
+      const headers = partBuffer.subarray(0, headerEndIndex).toString('utf8')
+      const body = partBuffer.subarray(headerEndIndex + 4, partBuffer.length - 2) // 去掉结尾的 \r\n
+
+      // 解析 Content-Disposition
+      const filenameMatch = headers.match(/filename="(.+?)"/)
+      const nameMatch = headers.match(/name="(.+?)"/)
+
+      if (filenameMatch) {
+        parts.push({
+          fieldname: nameMatch ? nameMatch[1] : 'file',
+          filename: filenameMatch[1],
+          buffer: body,
+        })
+      }
+    }
+
+    start = nextBoundaryIndex
+  }
+
+  return parts[0] // 返回第一个文件
+}
+
+module.exports = {
+  copyDirectory,
+  getAllFiles,
+  createTarGz,
+  extractTarGz,
+  sanitizeFilename,
+  isPathSafe,
+  parseMultipartFile,
+}