基于Vue 3与Node.js的文档图片批量提取工具Extractify开发实践

1. 项目概述与核心价值

最近在整理一个历史项目文档库，里面堆满了各种Word、PPT、PDF和Markdown文件，其中嵌入了大量有价值的图表和截图。手动一张张截图、另存为，不仅效率低下，还容易遗漏。为了解决这个痛点，我花了一周时间，基于Vue 3和Node.js，开发了一个名为Extractify的文档图片提取工具。它不是什么复杂的系统，但非常实用，能一站式从多种主流文档格式中批量提取图片，并提供了清晰的管理界面。

简单来说，Extractify就是一个部署在你本地或服务器上的Web应用。你通过浏览器上传一个文档，它会在后端自动解析文件结构，把里面所有的图片“抠”出来，然后在前端以画廊的形式展示给你预览、搜索，最后打包下载。整个过程无需安装任何桌面软件，对非技术同事也非常友好。它特别适合需要从大量报告、设计稿、技术文档中批量收集素材的编辑、运营、产品经理或开发者。核心的技术栈是前端Vue 3 + Element Plus，后端Node.js + Express，处理文档则用到了pdf.js、AdmZip等库。

2. 整体架构设计与技术选型解析

2.1 为什么选择这样的技术栈？

在项目启动前，我评估了几个方向。桌面工具（如Electron）虽然功能强大，但分发和更新麻烦；纯Python脚本对普通用户不友好。最终选择B/S架构的Web应用，核心考量是易用性和可访问性：用户只需一个浏览器，无需关心环境。技术栈的选型则基于“高效、现代、生态成熟”的原则。

前端选择Vue 3 + Element Plus：Vue 3的Composition API在构建这种以“任务”为中心的应用时，逻辑组织更清晰。比如，上传状态、图片列表、任务进度这些响应式数据，用ref和computed管理起来非常顺手。Element Plus提供了丰富的、开箱即用的UI组件，像上传组件、表格、分页、消息提示，能极大缩短开发时间，并且风格统一，省去了自己造轮子和调样式的功夫。

后端选择Node.js + Express：这是最自然的选择。一方面，我对Node.js生态更熟悉；另一方面，处理文档（尤其是解压.docx/.pptx这类ZIP包）本身就是I/O密集型操作，Node.js的非阻塞I/O模型能很好地应对，同时保持代码风格前后统一。Express框架轻量且灵活，足以支撑这个工具所需的RESTful API。

文档处理库的取舍：

• 对于PDF：pdf.js是首选。它是Mozilla开源的PDF渲染器，纯JavaScript实现，无需依赖系统库（如poppler），部署简单，且提取图片的精度很高。
• 对于Office文档（.docx/.pptx）：它们本质上是ZIP压缩包，图片文件存放在固定的媒体目录下（如word/media/）。使用adm-zip这个纯JS的ZIP库进行解压和文件遍历，是最直接、最可靠的方法。
• 对于旧版Office格式（.doc/.ppt）：这是难点。这些二进制格式没有公开的纯JS解析库。我的方案是借助LibreOffice的soffice命令行工具，在服务器端将其转换为.docx/.pptx，然后再按新格式处理。这引入了一个系统依赖，但换来了格式支持的完备性。
• 对于Markdown：解析.md文件中的图片引用（![]()）是正则表达式的用武之地。需要同时处理本地相对路径、绝对路径、网络URL以及Base64编码的Data URI。

2.2 核心流程与数据流设计

整个应用围绕“任务（Job）”这个概念运转。一个任务对应一次用户上传和处理过程。这样设计便于实现多用户隔离和任务状态管理。

1. 用户上传：前端通过Element Plus的<el-upload>组件将文件发送到后端/api/upload接口。
2. 任务创建：后端接收到文件后，立即生成一个唯一的jobId（如UUID），在uploads/jobs/jobId/目录下创建专属空间，存放上传的原始文件和后续提取的图片。同时，在内存或一个简单的Map中记录任务状态（等待中、处理中、完成、失败）。
3. 文件处理：根据文件后缀名，路由到不同的处理器（PDF Processor, Office Processor, Markdown Processor）。处理器会读取文件，提取图片，并将图片文件保存到任务目录下的images/子文件夹中。处理过程中的关键信息（如提取到的图片文件名、数量）会被记录。
4. 状态同步：后端通过WebSocket或更简单的长轮询/Server-Sent Events (SSE)，将任务处理进度（如“解析中...”、“已提取5张图片”）实时推送给前端。这里我选择了SSE，因为它实现简单，且符合“服务器向客户端推送事件”的场景。
5. 结果展示：任务完成后，后端将图片元数据（文件名、路径、缩略图）列表返回给前端。前端用画廊组件渲染，并提供搜索和下载功能。
6. 清理任务：每个任务都有一个生存时间（TTL），例如72小时。一个后台定时任务会定期扫描uploads/jobs/目录，删除超过TTL的旧任务文件夹，释放磁盘空间。

注意：会话隔离的设计。为了简单实现“用户只能看到自己上传的文件”，我没有引入复杂的用户数据库。而是利用了浏览器的会话Cookie。后端在创建任务时，会将jobId与当前会话的Session ID关联。当用户请求查看某个任务的图片时，后端会校验该jobId是否属于当前会话，从而实现轻量级的访问控制。这意味着如果你用另一个浏览器或者清除了Cookie，就无法访问之前任务的结果了。

3. 核心功能模块的深度实现

3.1 多格式文档解析器详解

这是工具的核心引擎。我设计了一个处理器（Processor）基类，不同的文档格式继承并实现具体的提取逻辑。

1. PDF文件处理器使用pdf.js，重点在于正确获取每一页的渲染内容并识别出图片对象。

// backend/processors/PdfProcessor.js const { getDocument, GlobalWorkerOptions } = require('pdfjs-dist/legacy/build/pdf'); const canvas = require('canvas'); const fs = require('fs').promises; const path = require('path'); class PdfProcessor { constructor(jobId, filePath) { this.jobId = jobId; this.filePath = filePath; this.outputDir = path.join(process.env.JOBS_ROOT, jobId, 'images'); // 设置pdf.js worker路径（在生产环境中，需要将pdf.worker.js文件复制到指定位置） GlobalWorkerOptions.workerSrc = path.join(__dirname, '../../node_modules/pdfjs-dist/legacy/build/pdf.worker.js'); } async extract() { const data = new Uint8Array(await fs.readFile(this.filePath)); const pdfDoc = await getDocument({ data }).promise; const imagePaths = []; for (let pageNum = 1; pageNum <= pdfDoc.numPages; pageNum++) { const page = await pdfDoc.getPage(pageNum); const ops = await page.getOperatorList(); // 关键：遍历操作符列表，寻找绘制图片的操作（通常是“paintImageXObject”） for (const op of ops.fnArray) { if (op === canvas.OPS.paintImageXObject) { // 获取图片数据并保存 const imgIndex = ops.argsArray[ops.fnArray.indexOf(op)][0]; const img = await page.objs.get(imgIndex); if (img && img.data) { const imgName = `page_${pageNum}_img_${Date.now()}.${img.ext}`; const imgPath = path.join(this.outputDir, imgName); await fs.writeFile(imgPath, img.data); imagePaths.push({ name: imgName, path: imgPath }); } } } } await pdfDoc.destroy(); return imagePaths; } }

实操心得：pdf.js的版本与worker。pdf.js的版本迭代很快，API可能有变化。我使用的是“legacy”构建版本，API相对稳定。最大的坑在于Worker文件。pdf.js需要在一个Web Worker中运行核心解析逻辑以不阻塞主线程。在Node.js环境中，你需要明确指定worker文件的物理路径，并确保该文件存在。通常需要从node_modules/pdfjs-dist/legacy/build/目录下将pdf.worker.js复制到你的项目目录中，或者在构建时将其打包进去。

2. Office Open XML处理器（.docx/.pptx）处理这类文件更像文件系统操作。

// backend/processors/OfficeProcessor.js const AdmZip = require('adm-zip'); const path = require('path'); const fs = require('fs').promises; class OfficeProcessor { constructor(jobId, filePath, fileType) { this.jobId = jobId; this.filePath = filePath; this.fileType = fileType; // 'docx' or 'pptx' this.outputDir = path.join(process.env.JOBS_ROOT, jobId, 'images'); // 定义媒体文件在ZIP包中的路径模式 this.mediaPathPatterns = { docx: /^word\/media\/.*\.(jpg|jpeg|png|gif|bmp|svg)$/i, pptx: /^ppt\/media\/.*\.(jpg|jpeg|png|gif|bmp|svg|wmf|emf)$/i, }; } async extract() { const zip = new AdmZip(this.filePath); const zipEntries = zip.getEntries(); const imagePaths = []; const pattern = this.mediaPathPatterns[this.fileType]; for (const entry of zipEntries) { if (pattern.test(entry.entryName) && !entry.isDirectory) { const imgBuffer = entry.getData(); const imgName = path.basename(entry.entryName); // 处理文件名冲突 const finalImgPath = await this.getUniqueFilePath(this.outputDir, imgName); await fs.writeFile(finalImgPath, imgBuffer); imagePaths.push({ name: path.basename(finalImgPath), path: finalImgPath }); } } return imagePaths; } async getUniqueFilePath(dir, filename) { // ... 实现一个函数，如果文件名存在，则添加(1)、(2)等后缀 } }

3. 旧版Office文档处理器（.doc/.ppt）这是通过调用外部命令实现的“曲线救国”方案。

// backend/processors/LegacyOfficeProcessor.js const { exec } = require('child_process'); const util = require('util'); const execPromise = util.promisify(exec); const path = require('path'); const fs = require('fs').promises; class LegacyOfficeProcessor { constructor(jobId, filePath, originalExt) { this.jobId = jobId; this.filePath = filePath; this.originalExt = originalExt; // 'doc' or 'ppt' this.tempDir = path.join(process.env.TEMP_ROOT, jobId); this.outputDir = path.join(process.env.JOBS_ROOT, jobId, 'images'); } async extract() { // 1. 确保LibreOffice已安装且soffice命令可用 const sofficePath = process.env.SOFFICE_PATH || 'soffice'; await this.checkCommandExists(sofficePath); // 2. 准备转换输出目录 await fs.mkdir(this.tempDir, { recursive: true }); // 3. 执行转换命令 // 例如：soffice --headless --convert-to docx --outdir /tmp input.doc const targetExt = this.originalExt + 'x'; // doc -> docx, ppt -> pptx const outFile = path.join(this.tempDir, `converted.${targetExt}`); const cmd = `"${sofficePath}" --headless --convert-to ${targetExt} --outdir "${this.tempDir}" "${this.filePath}"`; try { const { stdout, stderr } = await execPromise(cmd, { timeout: 60000 }); // 设置超时60秒 if (stderr && !stderr.includes('Overwriting')) { console.warn(`LibreOffice stderr: ${stderr}`); } } catch (error) { throw new Error(`文档转换失败: ${error.message}`); } // 4. 转换后的文件路径 const convertedFilePath = outFile; // 注意：soffice输出的文件名可能和输入名相同，但扩展名变了 // 需要实际查找一下转换生成的文件 const files = await fs.readdir(this.tempDir); const convertedFile = files.find(f => f.endsWith(`.${targetExt}`)); if (!convertedFile) { throw new Error('未找到转换后的文件'); } // 5. 将转换后的文件交给OfficeProcessor处理 const OfficeProcessor = require('./OfficeProcessor'); const processor = new OfficeProcessor(this.jobId, path.join(this.tempDir, convertedFile), targetExt); const images = await processor.extract(); // 6. 清理临时转换文件（可选，也可由统一的任务清理机制处理） // await fs.rm(this.tempDir, { recursive: true, force: true }); return images; } async checkCommandExists(cmd) { // ... 实现命令存在性检查 } }

重要警告：LibreOffice的部署依赖。这是生产部署中最容易出问题的一环。在Ubuntu上，你需要安装libreoffice或libreoffice-core包。此外，在无图形界面的服务器（headless）上运行，必须确保安装了必要的字体包（如fonts-liberation,fonts-dejavu），否则转换出的文档可能格式错乱或失败。命令是：sudo apt install libreoffice libreoffice-common fonts-liberation fonts-dejavu。同时，soffice进程可能比较消耗资源，处理大文件时需要设置合理的超时时间。

4. Markdown文件处理器解析文本，提取所有图片引用。

// backend/processors/MarkdownProcessor.js const fs = require('fs').promises; const path = require('path'); const axios = require('axios'); // 用于下载网络图片 const { isDataURI, dataURItoBuffer } = require('../utils/dataUriHelper'); class MarkdownProcessor { constructor(jobId, filePath) { this.jobId = jobId; this.filePath = filePath; this.outputDir = path.join(process.env.JOBS_ROOT, jobId, 'images'); } async extract() { const content = await fs.readFile(this.filePath, 'utf-8'); // 匹配Markdown图片语法：![alt](src) const imageRegex = /!\[.*?\]\((.*?)\)/g; const matches = [...content.matchAll(imageRegex)]; const imageUrls = matches.map(m => m[1]); const imagePaths = []; for (let i = 0; i < imageUrls.length; i++) { const url = imageUrls[i]; let imgBuffer; let ext = 'png'; // 默认扩展名 try { if (isDataURI(url)) { // 处理Base64 Data URI const data = dataURItoBuffer(url); imgBuffer = data.buffer; ext = data.ext || 'png'; } else if (url.startsWith('http://') || url.startsWith('https://')) { // 下载网络图片 const response = await axios.get(url, { responseType: 'arraybuffer', timeout: 10000 }); imgBuffer = response.data; // 从Content-Type或URL推断扩展名 const contentType = response.headers['content-type']; ext = this.getExtensionFromContentType(contentType) || path.extname(url).slice(1) || 'jpg'; } else { // 处理本地相对/绝对路径（相对于Markdown文件位置） const resolvedPath = path.resolve(path.dirname(this.filePath), url); if (await this.fileExists(resolvedPath)) { imgBuffer = await fs.readFile(resolvedPath); ext = path.extname(resolvedPath).slice(1); } else { console.warn(`本地图片文件不存在: ${resolvedPath}`); continue; } } const imgName = `md_img_${i}_${Date.now()}.${ext}`; const imgPath = path.join(this.outputDir, imgName); await fs.writeFile(imgPath, imgBuffer); imagePaths.push({ name: imgName, path: imgPath, source: url }); } catch (error) { console.error(`处理图片失败 (${url}):`, error.message); // 可以选择记录失败，但不中断整个任务 } } return imagePaths; } getExtensionFromContentType(contentType) { const map = { 'image/jpeg': 'jpg', 'image/png': 'png', 'image/gif': 'gif', 'image/webp': 'webp', 'image/svg+xml': 'svg' }; return map[contentType]; } async fileExists(filePath) { // ... 检查文件是否存在 } }

3.2 前端状态管理与用户体验优化

前端采用Vue 3的Composition API，状态管理清晰。核心状态包括当前任务ID、上传进度、处理进度、图片列表等。

<!-- frontend/src/views/HomeView.vue 部分代码 --> <script setup> import { ref, computed, onUnmounted } from 'vue'; import { ElMessage } from 'element-plus'; import { uploadFile, getJobStatus, downloadImage, downloadAll } from '@/api'; import ImageGallery from '@/components/ImageGallery.vue'; const uploadFileList = ref([]); const currentJobId = ref(null); const jobStatus = ref('idle'); // 'idle', 'uploading', 'processing', 'done', 'error' const progress = ref(0); // 综合进度 const imageList = ref([]); const searchKeyword = ref(''); // 处理文件上传 const handleUpload = async (options) => { const { file } = options; jobStatus.value = 'uploading'; progress.value = 10; try { const formData = new FormData(); formData.append('file', file); const response = await uploadFile(formData, (event) => { // 上传进度回调 progress.value = 10 + (event.loaded / event.total) * 40; // 上传占40%权重 }); currentJobId.value = response.data.jobId; jobStatus.value = 'processing'; progress.value = 50; // 开始轮询任务状态 startPolling(response.data.jobId); } catch (error) { ElMessage.error(`上传失败: ${error.message}`); resetState(); } }; // 轮询任务状态 let pollingInterval = null; const startPolling = (jobId) => { pollingInterval = setInterval(async () => { try { const statusRes = await getJobStatus(jobId); const { state, message, progress: jobProgress, images } = statusRes.data; // 更新综合进度（处理阶段占50%权重） progress.value = 50 + (jobProgress || 0) * 0.5; if (state === 'done') { clearInterval(pollingInterval); jobStatus.value = 'done'; progress.value = 100; imageList.value = images; // 接收后端返回的图片列表 ElMessage.success('图片提取完成！'); } else if (state === 'error') { clearInterval(pollingInterval); jobStatus.value = 'error'; ElMessage.error(`处理失败: ${message}`); } // 其他状态（processing）继续轮询 } catch (error) { console.error('轮询失败', error); } }, 1000); // 每秒轮询一次 }; // 清理状态 const resetState = () => { jobStatus.value = 'idle'; progress.value = 0; currentJobId.value = null; imageList.value = []; uploadFileList.value = []; if (pollingInterval) { clearInterval(pollingInterval); pollingInterval = null; } }; // 计算过滤后的图片列表 const filteredImages = computed(() => { if (!searchKeyword.value) return imageList.value; const keyword = searchKeyword.value.toLowerCase(); return imageList.value.filter(img => img.name.toLowerCase().includes(keyword) ); }); // 组件卸载时清理定时器 onUnmounted(() => { if (pollingInterval) clearInterval(pollingInterval); }); </script>

用户体验细节：进度反馈与防抖。进度条是提升用户体验的关键。我将进度分为两段：上传（10%-50%）和处理（50%-100%）。上传进度通过Axios的onUploadProgress事件实时获取；处理进度则由后端在任务状态中返回一个估算值（如解析页数/总页数）。轮询间隔设为1秒，既能及时反馈，又不会对服务器造成过大压力。同时，在上传或处理过程中，禁用重复提交按钮，防止用户误操作。

3.3 后端API与任务队列设计

后端采用经典的Express路由设计。关键点在于异步任务处理和状态管理。

// backend/routes/upload.js const express = require('express'); const multer = require('multer'); const path = require('path'); const { v4: uuidv4 } = require('uuid'); const router = express.Router(); // 配置multer处理文件上传 const storage = multer.diskStorage({ destination: (req, file, cb) => { const jobId = uuidv4(); req.jobId = jobId; // 将jobId挂载到request对象上 const jobDir = path.join(process.env.UPLOAD_ROOT, 'jobs', jobId); require('fs').promises.mkdir(jobDir, { recursive: true }).then(() => cb(null, jobDir)); }, filename: (req, file, cb) => { const safeName = Buffer.from(file.originalname, 'latin1').toString('utf8'); // 处理中文文件名 cb(null, `${Date.now()}_${safeName}`); } }); const upload = multer({ storage, limits: { fileSize: parseInt(process.env.MAX_FILE_SIZE_MB) * 1024 * 1024 }, fileFilter: (req, file, cb) => { const allowedTypes = /\.(docx?|pptx?|pdf|md|markdown)$/i; if (allowedTypes.test(file.originalname)) { cb(null, true); } else { cb(new Error('不支持的文件格式'), false); } } }); // 上传接口 router.post('/', upload.single('file'), async (req, res) => { if (!req.file) { return res.status(400).json({ error: '未接收到文件' }); } const jobId = req.jobId; const filePath = req.file.path; const originalName = req.file.originalname; // 1. 立即响应，告知前端任务已创建 res.json({ jobId, message: '文件上传成功，开始处理', originalName }); // 2. 将耗时的处理任务放入队列或异步执行 // 这里使用一个简单的内存任务队列 const jobQueue = req.app.get('jobQueue'); jobQueue.add({ jobId, filePath, originalName, sessionId: req.sessionID // 关联会话 }).catch(err => { console.error(`任务 ${jobId} 处理失败:`, err); // 更新任务状态为失败 const jobManager = req.app.get('jobManager'); jobManager.updateJobStatus(jobId, 'error', err.message); }); }); // 查询任务状态接口 router.get('/status/:jobId', (req, res) => { const { jobId } = req.params; const jobManager = req.app.get('jobManager'); const job = jobManager.getJob(jobId); if (!job) { return res.status(404).json({ error: '任务不存在或已过期' }); } // 简单的会话校验（生产环境应更严谨） if (job.sessionId !== req.sessionID) { return res.status(403).json({ error: '无权访问此任务' }); } res.json({ jobId, state: job.state, message: job.message, progress: job.progress, // 处理进度，0-1之间的小数 images: job.images // 完成后返回图片列表 }); }); module.exports = router;

// backend/core/JobManager.js - 简易任务管理器 class JobManager { constructor() { this.jobs = new Map(); // jobId -> { state, message, progress, images, createdAt, sessionId } this.cleanupInterval = setInterval(() => this.cleanupJobs(), 60 * 60 * 1000); // 每小时清理一次 } createJob(jobId, sessionId) { this.jobs.set(jobId, { state: 'pending', message: '等待处理', progress: 0, images: [], createdAt: Date.now(), sessionId }); } updateJobStatus(jobId, state, message, progress, images) { const job = this.jobs.get(jobId); if (job) { job.state = state; job.message = message || job.message; if (progress !== undefined) job.progress = progress; if (images !== undefined) job.images = images; } } getJob(jobId) { return this.jobs.get(jobId); } cleanupJobs() { const retentionHours = parseInt(process.env.JOB_RETENTION_HOURS) || 72; const now = Date.now(); for (const [jobId, job] of this.jobs.entries()) { if (now - job.createdAt > retentionHours * 60 * 60 * 1000) { // 删除内存记录 this.jobs.delete(jobId); // 删除磁盘文件（异步） const jobDir = path.join(process.env.JOBS_ROOT, jobId); fs.rm(jobDir, { recursive: true, force: true }).catch(console.error); } } } }

生产环境优化建议：引入真正的消息队列。上述的jobQueue只是一个简单的数组。在生产环境中，如果并发量稍大，强烈建议引入专业的消息队列，如Bull（基于Redis）或Agenda（基于MongoDB）。它们能提供持久化、重试、优先级、并发控制等高级功能。例如，使用Bull可以轻松控制同时处理的任务数（concurrency），避免服务器资源被瞬间榨干。

4. 生产环境部署与运维实战

4.1 Ubuntu服务器部署全流程

在Ubuntu上部署Node.js应用已是标准操作，但针对Extractify，有几个特定细节需要关注。

1. 系统依赖的完整安装除了Node.js和Git，LibreOffice和字体包是关键。

sudo apt update && sudo apt upgrade -y sudo apt install -y curl git build-essential # 安装Node.js 18 LTS（更稳定） curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 安装LibreOffice及字体 sudo apt install -y libreoffice libreoffice-common fonts-liberation fonts-dejavu fonts-wqy-zenhei fonts-wqy-microhei # 验证soffice命令 which soffice # 输出应为 /usr/bin/soffice

2. 项目配置与环境变量环境变量文件.env是配置中心。除了端口、密钥等，有几个配置项直接影响功能：

• SOFFICE_PATH: 确认LibreOffice路径。通常就是/usr/bin/soffice。
• MAX_FILE_SIZE_MB: 必须与Nginx配置中的client_max_body_size保持一致，否则大文件上传会被Nginx拦截。
• JOB_QUEUE_CONCURRENCY: 控制同时处理的任务数。根据服务器CPU核心数设置，通常设为CPU核心数的1-2倍。设置太高会导致内存和CPU飙升。
• JOB_RETENTION_HOURS: 任务文件保留时间。权衡磁盘空间和用户可能需要重新下载的需求。

3. PM2配置的进阶调整ecosystem.config.js可以更精细地控制进程。

module.exports = { apps: [{ name: 'extractify-backend', script: './server.js', cwd: '/path/to/extractify/backend', // 指定工作目录 instances: 2, // 根据CPU核心数设置，例如2个实例 exec_mode: 'cluster', // 集群模式，充分利用多核 watch: false, max_memory_restart: '800M', // 内存超过800M重启 env: { NODE_ENV: 'production', PORT: 13434 }, error_file: './logs/err.log', out_file: './logs/out.log', log_date_format: 'YYYY-MM-DD HH:mm:ss', // 设置生产环境特定的Node选项 node_args: '--max-old-space-size=1024' }] }

使用pm2 logs extractify-backend --lines 100可以方便地查看最新日志。

4. Nginx作为反向代理的优化配置/etc/nginx/sites-available/extractify的配置需要优化超时时间和缓冲区，以应对大文件上传和长时间处理。

server { listen 80; server_name your-domain.com; # 重定向到HTTPS（如果配置了SSL） # return 301 https://$server_name$request_uri; location / { proxy_pass http://localhost:13434; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下配置对文件上传和长轮询很重要 proxy_read_timeout 300s; # 后端处理可能较慢，延长读取超时 proxy_connect_timeout 75s; proxy_send_timeout 300s; client_max_body_size 50M; # 与后端设置一致 } # 可选：静态资源由Nginx直接服务，减轻Node负担 location /public/ { alias /path/to/extractify/backend/public/; expires 1y; add_header Cache-Control "public, immutable"; } }

配置完成后，务必运行sudo nginx -t测试配置语法，再sudo systemctl reload nginx重载。

4.2 安全与性能考量

安全措施：

1. 文件上传过滤：除了后缀名检查，还应在后端对文件内容进行简单的魔数（magic number）检查，防止伪装文件。
2. 路径遍历防护：处理用户提供的文件路径时（如Markdown中的本地图片路径），必须使用path.resolve并检查结果是否仍在允许的目录内。
3. 会话安全：使用express-session并配置安全的Cookie（secure: true,httpOnly: true,sameSite: 'lax'）。在生产环境使用像Redis或数据库作为session store，而不是内存。
4. 依赖安全：定期运行npm audit或使用npm audit fix修复已知漏洞。
5. 环境变量：敏感信息（如OAuth密钥）必须通过环境变量传入，绝不写死在代码中。

性能优化：

1. 图片缩略图：提取的原始图片可能很大。在前端预览时，可以要求后端生成缩略图（例如使用sharp库），只将缩略图的URL传给前端，大幅减少网络传输和数据加载时间。
2. 异步处理与队列：如前所述，使用Bull等队列将耗时处理与Web请求分离，避免请求超时。
3. 缓存策略：对于频繁访问的静态资源（如前端构建的JS、CSS），通过Nginx设置强缓存。
4. 数据库（可选）：如果任务量非常大，或者需要持久化任务记录供查询，可以考虑引入一个轻量级数据库（如SQLite或PostgreSQL）来存储任务元数据，而不是全部放在内存中。

5. 常见问题排查与实战技巧

在实际开发和部署中，我遇到了不少坑。这里总结一份速查表。

独家避坑技巧：

• “幽灵任务”清理：在JobManager的cleanupJobs函数中，不仅要删除内存记录和文件，最好也检查一下磁盘上是否有超过保留时间的“僵尸”任务目录（可能因进程意外退出而未清理），做一个双重保障。
• 前端上传进度“假死”：在开发环境下，Vite的Dev Server可能对上传进度事件支持不完美。如果发现进度条卡住，可以先尝试在生产构建后的版本中测试。
• 大PDF内存溢出：处理上百页的PDF时，pdf.js可能占用大量内存。可以考虑在Node启动时增加内存限制node --max-old-space-size=2048 server.js，并在PM2配置中设置max_memory_restart，让进程在内存超限后自动重启。
• 文件名乱码：Windows上传的中文文件名，在Linux服务器上可能显示为乱码。使用Buffer.from(name, 'latin1').toString('utf8')是一种常见的转换方法，但并非万能。更稳妥的方式是前端在上传前就对文件名进行编码（如URL编码），后端再解码。

这个工具从构思到上线，最大的体会是：技术选型要服务于核心场景的简单和稳定。最初想过用更“炫”的技术，但最终回归到最务实、生态最成熟的组合。另一个深刻的教训是：对于依赖外部命令行工具（如LibreOffice）的功能，一定要在目标部署环境中进行充分测试，写好清晰的安装文档和备选方案。现在，这个工具已经稳定运行在内部服务器上，每天帮助团队从各种文档中解放双手，那种“造轮子”并且真正用起来的成就感，是无可替代的。如果你也有类似的需求，不妨以这个项目为蓝本，定制属于你自己的文档图片提取流水线。