文档上传功能技术架构与实现指南

一、功能概览

核心功能

文档上传功能支持多种格式文档（PDF、Word、Excel等）的上传与处理，系统将自动完成以下流程：

1. 文件接收与存储：安全保存用户上传的文档

2. 内容解析提取：智能提取文档文本内容

3. 向量化处理：将文本转换为语义向量

4. 智能检索存储：存入Elasticsearch供AI对话使用

技术架构

text

前端 → 后端API → 文件存储 → 消息队列 → 文档解析 → 向量化 → 搜索引擎
(Vue3)  (Spring Boot)  (MinIO)  (Kafka)    (解析服务)  (DashScope)  (Elasticsearch)

二、分步上传流程详解

第1步：前端文件分片处理

位置 ：frontend/src/store/modules/knowledge-base/index.ts
方法 ：uploadChunk()

分片优势：

• 避免大文件单次上传失败风险

• 支持断点续传，提升用户体验

• 提高网络不稳定环境下的上传成功率

前端操作流程：

1. 文件按5MB标准分片切割

2. 计算文件整体MD5作为唯一标识

3. 顺序或并行上传各分片

第2步：后端接收分片（核心接口）

接口 ：POST /api/v1/upload/chunk
文件 ：UploadController.java的uploadChunk()方法（第67行）

关键参数：

java

@RequestParam String fileMd5,        // 文件唯一标识
@RequestParam Integer chunkIndex,    // 当前分片索引（0起始）
@RequestParam Long totalSize,        // 文件总字节数
@RequestParam String fileName,       // 原始文件名
@RequestParam MultipartFile file     // 分片文件数据

后端处理：

1. 文件类型验证（仅首个分片）

   • 验证扩展名白名单

   • 支持格式：PDF、Word、Excel、PPT、TXT、Markdown

2. 权限标识处理

   • 自动获取用户主组织标签

   • 支持自定义组织权限控制

3. 分片存储

   • 调用uploadService.uploadChunk()

   • Redis缓存上传状态

4. 进度反馈

   • 实时计算上传百分比

   • 返回已成功上传的分片列表

第3步：文件合并与触发处理

接口 ：POST /api/v1/upload/merge

关键操作：

1. 完整性校验

   • 验证所有分片已完整上传

   • 数据库权限二次确认

2. 物理文件合并

   • Redis中分片数据合并

   • 完整文件上传至MinIO存储

3. 异步处理触发

   • 发送Kafka消息至file-processing-topic1

   • 启动文档解析流水线

第4步：消息队列处理

消费者 ：FileProcessingService.processFile()
职责：

• 监听Kafka主题消息

• 协调文档解析流程

• 异常处理与重试机制

第5步：智能文档解析

服务 ：DocumentParsingService

解析策略：

文件格式	解析引擎	备注
PDF	Apache PDFBox	支持扫描版OCR
Word/Excel	Apache POI	保留格式信息
其他格式	Apache Tika	通用解析器

文本分块：

• 每块512字符（适配AI模型输入限制）

• 重叠处理保证语义连贯性

第6步：语义向量化

服务 ：EmbeddingService

处理流程：

1. 调用阿里云DashScope API

2. 生成2048维语义向量

3. 向量归一化处理

第7步：搜索引擎存储

服务 ：ElasticsearchService

存储内容：

• 文档元数据（文件名、时间、用户等）

• 文本分块内容

• 语义向量（用于相似度检索）

• 权限控制信息

三、数据存储设计

1. MySQL元数据表（file_upload）

sql

CREATE TABLE file_upload (
    file_md5 VARCHAR(32) PRIMARY KEY,  -- 文件唯一标识
    file_name VARCHAR(255),             -- 原始文件名
    total_size BIGINT,                  -- 文件大小(字节)
    status TINYINT,                     -- 状态(0:上传中,1:完成)
    user_id VARCHAR(64),                -- 上传用户
    org_tag VARCHAR(64),                -- 组织标签
    is_public BOOLEAN,                  -- 公开标识
    created_at DATETIME                 -- 创建时间
);

2. Redis缓存设计

分片状态缓存：

• Key格式：upload:{fileMd5}:chunk:{chunkIndex}

• 过期时间：24小时（防数据堆积）

3. Elasticsearch索引结构

• 文档级索引：存储元数据和权限

• 向量索引：存储文本块和嵌入向量

• 权限过滤：基于orgTag和isPublic

四、调试与排错指南

调试等级建议

初级：主流程跟踪

断点位置：

1. UploadController.uploadChunk()入口

2. uploadService.uploadChunk()调用前

3. UploadController.mergeFile()入口

4. Kafka消息发送点

观察要点：

• 请求参数是否正确传递

• 文件分片逻辑是否正常

• 进度计算是否准确

中级：服务层深入

关键文件：

• UploadService.java：分片合并逻辑

• MinioService.java：存储操作

• Redis操作：分片状态管理

高级：全链路追踪

1. 前端上传到后端接收的完整数据流

2. 分片合并到MinIO存储过程

3. Kafka消息生产与消费

4. 文档解析到向量存储全流程

常见问题排查

问题1：断点调试不生效

排查步骤：

1. 确认Spring Boot以Debug模式启动

2. 检查IDEA断点为红色实心状态

3. 验证浏览器请求是否到达8081端口

4. 查看控制台是否有请求日志

问题2：文件上传失败

检查清单：

• MinIO服务（localhost:9000）正常运行

• Redis服务（localhost:6379）可连接

• Kafka服务（localhost:9092）已启动

• 后端控制台查看详细错误信息

问题3：文档解析异常

解决方案：

1. Elasticsearch服务状态检查（localhost:9200）

2. 文件格式支持性验证

3. Kafka消费者日志分析