package com.custom.webui.service.impl; import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.custom.webui.config.props.RagProperties; import com.custom.webui.config.props.StorageProperties; import com.custom.webui.security.CurrentUser; import com.custom.webui.dto.resp.FileDTO; import com.custom.webui.dto.resp.OcrResultDTO; import com.custom.webui.entity.RagCollection; import com.custom.webui.entity.UploadFile; import com.custom.webui.exception.BusinessException; import com.custom.webui.entity.KbCategory; import com.custom.webui.mapper.KbCategoryMapper; import com.custom.webui.mapper.RagCollectionMapper; import com.custom.webui.mapper.UploadFileMapper; import com.custom.webui.service.FileService; import com.custom.webui.service.CategoryService; import com.custom.webui.service.RagProxyService; import com.custom.webui.util.StoragePathUtil; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import org.springframework.web.multipart.MultipartFile; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.nio.file.StandardCopyOption; import java.time.LocalDate; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.List; import java.util.Locale; import java.util.Objects; import java.util.UUID; /** * 文件与知识库服务实现。 * *

安全设计(重点): *

    *
  1. 扩展名白名单:只允许配置中列出的类型,杜绝上传 .jsp/.php/.sh 等可执行文件
  2. *
  3. 服务端生成存储名:磁盘文件名是 {@code UUID.扩展名}, * 完全丢弃用户提供的文件名,从根上消除 {@code ../../etc/passwd} 式的路径穿越
  4. *
  5. 目录按日期分片:{@code 2025/01/15/uuid.pdf},避免单目录文件过多导致 * ext4/NTFS 的目录项查找退化成线性扫描
  6. *
  7. 规范化后校验前缀:写入前用 {@code toRealPath} 规范化, * 并断言最终路径确实位于存储根目录下 —— 防御符号链接攻击
  8. *
*/ @Slf4j @Service @RequiredArgsConstructor public class FileServiceImpl implements FileService { private static final DateTimeFormatter DATE_DIR_FORMAT = DateTimeFormatter.ofPattern("yyyy/MM/dd"); private final UploadFileMapper uploadFileMapper; private final RagCollectionMapper ragCollectionMapper; private final KbCategoryMapper kbCategoryMapper; private final StorageProperties storageProperties; private final RagProperties ragProperties; private final RagProxyService ragProxyService; private final CategoryService categoryService; // ============================================================ // 上传 // ============================================================ @Override @Transactional(rollbackFor = Exception.class) public FileDTO upload(Long userId, Long chatId, MultipartFile file, boolean autoIngest, Long categoryId) { // 普通上传一律私有:即使调用者是管理员,想设成全局必须显式走 // uploadGlobal 或事后调用 setGlobal —— 避免误把私人文件暴露给全员 FileDTO uploaded = saveUpload(userId, chatId, file, false); applyCategory(userId, uploaded, categoryId); return autoIngest ? tryAutoIngest(userId, uploaded) : uploaded; } @Override @Transactional(rollbackFor = Exception.class) public FileDTO uploadGlobal(Long userId, MultipartFile file, boolean autoIngest, Long categoryId) { requireAdmin(); log.info("管理员上传全局知识库 userId={} name={} autoIngest={}", userId, file == null ? null : file.getOriginalFilename(), autoIngest); // 全局文件不绑定具体会话(chatId=null),它面向所有会话 FileDTO uploaded = saveUpload(userId, null, file, true); applyCategory(userId, uploaded, categoryId); return autoIngest ? tryAutoIngest(userId, uploaded) : uploaded; } /** * 上传后归类。 * *

归类失败**不抛异常**:文件已经上传成功,因为分类参数有问题 * 就把整个上传判为失败,用户会以为文件丢了。改为记日志 + 文件保持未分类, * 用户可以在界面上重新归类。 */ private void applyCategory(Long userId, FileDTO uploaded, Long categoryId) { if (uploaded == null || uploaded.getId() == null || categoryId == null) { return; } try { categoryService.assignFile(userId, uploaded.getId(), categoryId); uploaded.setCategoryId(categoryId); } catch (Exception e) { log.warn("上传后归类失败,文件保持未分类 fileId={} categoryId={} err={}", uploaded.getId(), categoryId, e.getMessage()); uploaded.setCategoryId(null); } } /** * 上传后自动向量化。 * *

失败不抛异常,而是把原因写进返回的 {@code ingestMessage}。 * 理由:文件已经成功落盘并入库(元数据),此时因为 embedding 服务不可用 * 或代理问题把整个上传判为失败,会让用户以为文件丢了 —— 而实际上文件好好的, * 只是暂时没向量化,修好环境后点一次「向量化」即可。 */ private FileDTO tryAutoIngest(Long userId, FileDTO uploaded) { if (uploaded == null || uploaded.getId() == null) { return uploaded; } try { log.info("上传后自动向量化 fileId={} name={}", uploaded.getId(), uploaded.getFilename()); return ingest(userId, uploaded.getId()); } catch (Exception e) { log.warn("自动向量化失败,文件已保存,可稍后手动重试 fileId={} err={}", uploaded.getId(), e.getMessage()); uploaded.setIngested(false); uploaded.setIngestMessage("自动向量化失败:" + e.getMessage() + "(文件已保存,可稍后点「向量化」重试)"); return uploaded; } } /** 校验当前登录者是否为管理员,否则 403 */ private void requireAdmin() { if (!CurrentUser.isAdmin()) { throw BusinessException.forbidden("只有管理员可以维护全局知识库"); } } /** * 上传文件的共用实现。 * * @param isGlobal true 表示全局知识库(仅管理员可传入) */ private FileDTO saveUpload(Long userId, Long chatId, MultipartFile file, boolean isGlobal) { if (file == null || file.isEmpty()) { throw BusinessException.badRequest("上传文件为空"); } if (file.getSize() > storageProperties.getMaxFileSize()) { throw BusinessException.badRequest( "文件超过大小限制 " + (storageProperties.getMaxFileSize() / 1024 / 1024) + "MB"); } // 原始文件名可能包含路径,先剥掉目录部分 String originalName = sanitizeFilename(file.getOriginalFilename()); String extension = extractExtension(originalName); if (!storageProperties.getAllowedExtensions().contains(extension)) { throw BusinessException.badRequest( "不支持的文件类型 ." + extension + ",允许的类型: " + String.join(", ", storageProperties.getAllowedExtensions())); } // 存储名完全由服务端生成:UUID + 已校验的扩展名 String storedName = UUID.randomUUID().toString().replace("-", "") + "." + extension; String dateDir = LocalDate.now().format(DATE_DIR_FORMAT); Path root = storageRoot(); Path targetDir = root.resolve(dateDir).normalize(); // 防御符号链接:确保目标目录确实在存储根目录之下 if (!targetDir.startsWith(root)) { throw BusinessException.badRequest("非法的存储路径"); } try { Files.createDirectories(targetDir); Path targetFile = targetDir.resolve(storedName).normalize(); if (!targetFile.startsWith(root)) { throw BusinessException.badRequest("非法的存储路径"); } try (var in = file.getInputStream()) { // 已存在同名(UUID 冲突概率极低)则覆盖;REPLACE_EXISTING 也避免重复上传报错 Files.copy(in, targetFile, StandardCopyOption.REPLACE_EXISTING); } UploadFile entity = new UploadFile(); entity.setUserId(userId); entity.setChatId(chatId); entity.setFilename(originalName); entity.setSavePath(targetFile.toString()); entity.setFileSize(file.getSize()); entity.setMimeType(file.getContentType()); entity.setIsGlobal(isGlobal); entity.setCreatedAt(LocalDateTime.now()); uploadFileMapper.insert(entity); log.info("文件上传成功 userId={} fileId={} name={} size={}B chatId={} 全局={}", userId, entity.getId(), originalName, file.getSize(), chatId, isGlobal); return toDto(entity, null); } catch (IOException e) { log.error("文件写入失败 name={}", originalName, e); throw BusinessException.serverError("文件保存失败: " + e.getMessage()); } } // ============================================================ // 查询 // ============================================================ @Override public List list(Long userId, Long chatId) { // 可见范围 = 自己上传的 + 全局知识库。 // 用 OR 条件一次查完,而不是查两次再合并 —— 少一次往返,也不会漏。 var query = Wrappers.lambdaQuery() .and(w -> w.eq(UploadFile::getUserId, userId) .or() .eq(UploadFile::getIsGlobal, true)) .orderByDesc(UploadFile::getId); if (chatId != null) { query.eq(UploadFile::getChatId, chatId); } return attachCollectionInfo(uploadFileMapper.selectList(query)); } @Override public List listGlobal() { // 全局文件对任何登录用户都可见,不做用户过滤 return attachCollectionInfo(uploadFileMapper.selectList( Wrappers.lambdaQuery() .eq(UploadFile::getIsGlobal, true) .orderByDesc(UploadFile::getId))); } /** 批量补充 RAG 集合信息并转 DTO,避免逐个文件查库造成 N+1 */ private List attachCollectionInfo(List files) { if (files == null || files.isEmpty()) { return Collections.emptyList(); } List fileIds = files.stream().map(UploadFile::getId).toList(); var collections = ragCollectionMapper.selectList( Wrappers.lambdaQuery().in(RagCollection::getFileId, fileIds)); var byFileId = new java.util.HashMap(); for (RagCollection c : collections) { byFileId.put(c.getFileId(), c); } Long currentUserId = CurrentUser.requireUserId(); boolean admin = CurrentUser.isAdmin(); // 一次取出涉及到的分类名,避免逐条查库 Map categoryNames = new HashMap<>(); List categoryIds = files.stream() .map(UploadFile::getCategoryId) .filter(Objects::nonNull) .distinct() .toList(); if (!categoryIds.isEmpty()) { for (KbCategory c : kbCategoryMapper.selectBatchIds(categoryIds)) { categoryNames.put(c.getId(), c.getName()); } } List result = new ArrayList<>(files.size()); for (UploadFile f : files) { FileDTO dto = toDto(f, byFileId.get(f.getId())); // 批量场景下用上面一次查好的映射覆盖,避免逐条查库 if (f.getCategoryId() != null && categoryNames.containsKey(f.getCategoryId())) { dto.setCategoryName(categoryNames.get(f.getCategoryId())); } // 可管理 = 自己上传的,或本人是管理员。 // 注意:可见 ≠ 可管理。普通用户能看到全局知识库并绑定使用, // 但不能删除或重新向量化 —— 那会影响所有人的检索结果。 dto.setCanManage(admin || Objects.equals(f.getUserId(), currentUserId)); result.add(dto); } return result; } @Override @Transactional(rollbackFor = Exception.class) public FileDTO setGlobal(Long userId, Long fileId, boolean global) { requireAdmin(); UploadFile file = requireManageableFile(userId, fileId); UploadFile patch = new UploadFile(); patch.setId(fileId); patch.setIsGlobal(global); uploadFileMapper.updateById(patch); log.info("管理员{}全局知识库 fileId={} name={}", global ? "设为" : "取消", fileId, file.getFilename()); // 集合名与 isGlobal 无关,因此已绑定该知识库的会话不受影响 List refreshed = attachCollectionInfo(List.of(uploadFileMapper.selectById(fileId))); return refreshed.isEmpty() ? toDto(file, null) : refreshed.get(0); } @Override public List accessibleCollections(Long userId) { // 自己已入库的 List own = ragCollectionMapper.selectList( Wrappers.lambdaQuery() .eq(RagCollection::getUserId, userId) .eq(RagCollection::getStatus, RagCollection.STATUS_READY)) .stream().map(RagCollection::getCollectionName).toList(); // 全局已入库的:先找出全部全局文件,再取它们对应的集合 List globalFileIds = uploadFileMapper.selectList( Wrappers.lambdaQuery() .select(UploadFile::getId) .eq(UploadFile::getIsGlobal, true)) .stream().map(UploadFile::getId).toList(); List global = globalFileIds.isEmpty() ? Collections.emptyList() : ragCollectionMapper.selectList( Wrappers.lambdaQuery() .in(RagCollection::getFileId, globalFileIds) .eq(RagCollection::getStatus, RagCollection.STATUS_READY)) .stream().map(RagCollection::getCollectionName).toList(); List all = new ArrayList<>(own.size() + global.size()); all.addAll(own); // 去重:理论上不会重叠(own 按 userId,global 按 isGlobal), // 但管理员既上传了全局文件、自己又入库过同一个文件时可能重复 for (String c : global) { if (!all.contains(c)) { all.add(c); } } return all; } @Override public UploadFile requireManageableFile(Long userId, Long fileId) { UploadFile file = uploadFileMapper.selectById(fileId); if (file == null) { throw BusinessException.notFound("文件不存在或无权访问"); } // 权限:上传者本人,或任意管理员(管理员要能维护全局知识库) boolean isOwner = file.getUserId() != null && file.getUserId().equals(userId); if (!isOwner && !CurrentUser.isAdmin()) { // 统一返回 404 而非 403:避免暴露「这个 id 存在但不属于你」的信息 throw BusinessException.notFound("文件不存在或无权访问"); } return file; } // ============================================================ // 删除 // ============================================================ @Override @Transactional(rollbackFor = Exception.class) public void delete(Long userId, Long fileId) { UploadFile file = requireManageableFile(userId, fileId); // 先清理向量集合,再删元数据;顺序很重要: // 若先删元数据而向量清理失败,就会留下永远无法定位的僵尸向量数据。 List collections = ragCollectionMapper.selectList( Wrappers.lambdaQuery().eq(RagCollection::getFileId, fileId)); for (RagCollection c : collections) { try { ragProxyService.deleteCollection(c.getCollectionName()); } catch (Exception e) { log.warn("删除向量集合失败 collection={} err={}", c.getCollectionName(), e.getMessage()); } } ragCollectionMapper.delete(Wrappers.lambdaQuery().eq(RagCollection::getFileId, fileId)); // 删除磁盘文件:失败只告警不中断,避免因为文件被占用导致记录删不掉 try { Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath()); boolean deleted = Files.deleteIfExists(path); log.debug("磁盘文件删除 fileId={} path={} deleted={}", fileId, file.getSavePath(), deleted); } catch (IOException e) { log.warn("磁盘文件删除失败 fileId={} err={}", fileId, e.getMessage()); } uploadFileMapper.deleteById(fileId); log.info("文件删除完成 userId={} fileId={} name={}", userId, fileId, file.getFilename()); } // ============================================================ // 向量化入库 // ============================================================ /** * 把文件送入 Python 服务做向量化。 * *

刻意不加 {@code @Transactional}:向量化是一次可能持续数分钟的 * 外部 HTTP 调用。若把它包在事务里,一个数据库连接会被占住直到调用结束, * 并发十几个文档入库就能耗尽连接池,让整个系统不可用。 * 这里改为「短事务分步提交」: *

    *
  1. 写 pending 记录(独立提交)—— 保证崩了也能看到待处理痕迹
  2. *
  3. 无事务地调用 Python 服务
  4. *
  5. 写 ready/failed 结果(独立提交)
  6. *
*/ @Override public FileDTO ingest(Long userId, Long fileId) { UploadFile file = requireManageableFile(userId, fileId); if (!ragProperties.isEnabled()) { throw BusinessException.badRequest("RAG 功能已在配置中关闭(webui.rag.enabled=false)"); } Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath()); if (!Files.exists(path)) { throw BusinessException.badRequest("文件在磁盘上不存在,可能已被清理: " + file.getFilename()); } // 集合名规则:user_{userId}_file_{fileId} // 用确定性命名而非随机名,使得重复入库可以幂等覆盖,不会产生重复集合。 String collectionName = buildCollectionName(file); // 步骤 1:先写 pending 记录 upsertPending(userId, fileId, collectionName); try { // 步骤 2:无事务地调用 Python 服务 RagProxyService.IngestResult result = ragProxyService.ingest(path, collectionName, userId); // 步骤 3:写回成功状态 RagCollection record = findCollectionRecord(fileId, collectionName); if (record != null) { RagCollection patch = new RagCollection(); patch.setId(record.getId()); patch.setChunkCount(result.chunkCount()); patch.setStatus(RagCollection.STATUS_READY); patch.setMessage(result.message()); ragCollectionMapper.updateById(patch); } log.info("向量化入库成功 fileId={} collection={} chunks={}", fileId, result.collectionName(), result.chunkCount()); return toDto(file, findCollectionRecord(fileId, collectionName)); } catch (Exception e) { log.error("向量化入库失败 fileId={} collection={}", fileId, collectionName, e); RagCollection record = findCollectionRecord(fileId, collectionName); if (record != null) { RagCollection patch = new RagCollection(); patch.setId(record.getId()); patch.setStatus(RagCollection.STATUS_FAILED); patch.setMessage(abbreviate(e.getMessage(), 500)); ragCollectionMapper.updateById(patch); } throw e instanceof BusinessException be ? be : BusinessException.serverError("向量化失败: " + e.getMessage()); } } // ============================================================ // 文本读取 // ============================================================ @Override public OcrResultDTO recognizeImage(Long userId, Long fileId) { UploadFile file = requireManageableFile(userId, fileId); Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath()); if (!Files.exists(path)) { throw BusinessException.badRequest("图片在磁盘上不存在: " + file.getFilename()); } OcrResultDTO result = ragProxyService.recognizeImage(path); // 以用户上传时的原始文件名为准,OCR 服务返回的是磁盘存储名 result.setFilename(file.getFilename()); return result; } @Override public org.springframework.core.io.Resource loadAsResource(Long userId, Long fileId) { UploadFile file = requireManageableFile(userId, fileId); Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath()); if (!Files.exists(path)) { throw BusinessException.notFound("文件在磁盘上不存在,可能已被清理"); } try { return new org.springframework.core.io.FileSystemResource(path); } catch (Exception e) { throw BusinessException.serverError("读取文件失败: " + e.getMessage()); } } @Override public String readTextContent(UploadFile file) { String extension = extractExtension(file.getFilename()); // 只直接读取纯文本类,pdf/docx 必须走 Python 解析服务 List textTypes = List.of("txt", "md", "markdown", "csv", "json", "log"); if (!textTypes.contains(extension)) { throw BusinessException.badRequest( "文件类型 ." + extension + " 不是纯文本,请通过 RAG 服务解析"); } long maxReadBytes = 5L * 1024 * 1024; if (file.getFileSize() != null && file.getFileSize() > maxReadBytes) { throw BusinessException.badRequest("文本文件超过 5MB,请通过 RAG 服务处理"); } try { return Files.readString( StoragePathUtil.resolve(storageRoot(), file.getSavePath()), StandardCharsets.UTF_8); } catch (IOException e) { throw BusinessException.serverError("读取文件内容失败: " + e.getMessage()); } } // ============================================================ // 内部辅助 // ============================================================ /** * 清洗原始文件名:只保留最后的文件名部分,并剔除控制字符与路径分隔符。 * *

即便存储名由 UUID 生成(用户文件名不参与落盘路径), * 这里的净化依然必要 —— 原始名会入库并回显到前端, * 未净化的名字可能被用来做 XSS 或误导用户(如伪装成 .exe)。 */ private String sanitizeFilename(String raw) { if (raw == null || raw.isBlank()) { return "unnamed"; } // 去掉任何目录成分:同时处理 Unix 与 Windows 分隔符 String name = raw.replace('\\', '/'); int slash = name.lastIndexOf('/'); if (slash >= 0) { name = name.substring(slash + 1); } // 剔除控制字符 name = name.replaceAll("[\\p{Cntrl}]", ""); // 剔除会干扰展示的引号与尖括号 name = name.replaceAll("[<>\"']", ""); name = name.trim(); if (name.isEmpty() || ".".equals(name) || "..".equals(name)) { return "unnamed"; } return name.length() > 255 ? name.substring(0, 255) : name; } /** 提取小写扩展名;无扩展名返回空串 */ private String extractExtension(String filename) { int dot = filename.lastIndexOf('.'); if (dot < 0 || dot == filename.length() - 1) { return ""; } return filename.substring(dot + 1).toLowerCase(Locale.ROOT); } /** 配置的存储根目录(绝对路径),供路径兜底使用 */ private Path storageRoot() { return Paths.get(storageProperties.getLocation()).toAbsolutePath().normalize(); } /** 集合名:确定性生成,保证同一文件重复入库时幂等 */ private String buildCollectionName(UploadFile file) { // 集合名用确定性规则生成(而非随机名),使重复入库幂等、不产生重复集合。 // 全局文件用 global_ 前缀,运维在 Chroma 里一眼能分辨归属。 if (Boolean.TRUE.equals(file.getIsGlobal())) { return "global_file_" + file.getId(); } return "user_" + file.getUserId() + "_file_" + file.getId(); } /** 不存在则插入 pending 记录,存在则重置为 pending */ private void upsertPending(Long userId, Long fileId, String collectionName) { RagCollection existing = findCollectionRecord(fileId, collectionName); if (existing == null) { RagCollection record = new RagCollection(); record.setUserId(userId); record.setFileId(fileId); record.setCollectionName(collectionName); record.setChunkCount(0); record.setStatus(RagCollection.STATUS_PENDING); record.setCreatedAt(LocalDateTime.now()); ragCollectionMapper.insert(record); } else { RagCollection patch = new RagCollection(); patch.setId(existing.getId()); patch.setStatus(RagCollection.STATUS_PENDING); patch.setMessage(null); ragCollectionMapper.updateById(patch); } } private RagCollection findCollectionRecord(Long fileId, String collectionName) { return ragCollectionMapper.selectOne( Wrappers.lambdaQuery() .eq(RagCollection::getFileId, fileId) .eq(RagCollection::getCollectionName, collectionName) .last("LIMIT 1")); } private FileDTO toDto(UploadFile file, RagCollection collection) { FileDTO dto = new FileDTO(); dto.setId(file.getId()); dto.setFilename(file.getFilename()); dto.setFileSize(file.getFileSize()); dto.setMimeType(file.getMimeType()); dto.setChatId(file.getChatId()); dto.setCreatedAt(file.getCreatedAt()); // 不暴露 savePath:服务器的磁盘布局属于内部实现细节 dto.setIngested(collection != null && RagCollection.STATUS_READY.equals(collection.getStatus())); dto.setCollectionName(collection == null ? null : collection.getCollectionName()); dto.setChunkCount(collection == null ? null : collection.getChunkCount()); dto.setIngestMessage(collection == null ? null : collection.getMessage()); // canManage 需要当前登录者信息,由 attachCollectionInfo 统一填充 dto.setIsGlobal(Boolean.TRUE.equals(file.getIsGlobal())); dto.setCategoryId(file.getCategoryId()); // 分类名在这里查一次(单条查询,代价可忽略)。 // 不查的话,ingest / setGlobal 这些走 toDto 的接口会返回 // categoryId 有值、categoryName 为 null 的不完整对象, // 前端展示会出现「有分类但显示不出名字」的不一致。 if (file.getCategoryId() != null) { KbCategory category = kbCategoryMapper.selectById(file.getCategoryId()); dto.setCategoryName(category == null ? null : category.getName()); } return dto; } private String abbreviate(String s, int max) { if (s == null) { return null; } return s.length() <= max ? s : s.substring(0, max) + "..."; } }