前言
企业知识库不只是 Markdown 文本。
用户上传的可能是 200 页的 PDF 投标书、带嵌图的 Word 技术报告、20 个 Sheet 的 Excel 数据表、或者 2GB 的 MP4 培训视频。
这些不是 "支持上传文件" 就能解决的。
它需要一个完整的多媒体管线:上传校验 → 存储分发 → 格式检测 → 元数据提取 → 异步转码 → 文本解析 → 前端预览/播放。
企业智能知识库系统的多媒体管线由 kb-file(文件微服务)、kb-document(文档微服务) 和 React 前端 三层协作完成。底层借助 RustFS S3 兼容存储、FFmpeg/FFprobe 命令行、RabbitMQ 异步转码队列、Apache PDFBox/POI/Tika 文档解析 实现了从上传到预览的完整闭环。
1. 从一个视频文件上传到在线播放的全链路
以用户上传一个 500MB 的 MP4 培训视频并在线播放为例,完整追踪多媒体处理管线:
用户在文件管理页拖拽 "企业安全培训.mp4" (500MB) 到上传区
→ FileManagementPage: handleUpload(file)
→ POST /document/file-management/upload
→ kb-document: FileManagementController → FileManagementServiceImpl
│
├── 1. 校验:扩展名 .mp4 ∈ allowedTypes,size=500MB < maxSize(2GB)
└── Feign → kb-file: POST /files/upload
│
├── 2. FileServiceImpl.uploadFile()
│ ├── validateFile(): 文件大小、扩展名、Content-Type 三重校验
│ ├── calculateFileHash(): SHA-256 哈希 → a3f8b2c9...
│ ├── 秒传检查: SELECT * FROM kb_file WHERE file_hash = 'a3f8b2c9...'
│ │ └── 不存在 → 继续
│ ├── generateRelativePath(): yyyy/MM/dd/{hash[:2]}/{hash}.ext
│ │ └── "2026/06/24/a3/a3f8b2c9....mp4"
│ ├── RustFileStorage.upload(stream, path)
│ │ └── S3 PutObject(bucket="knowledge-dev", key="2026/06/24/a3/...")
│ ├── FileInfo 入库: type=VIDEO, mime=video/mp4, size=524288000
│ └── 同步提取元数据 ↓
│
├── 3. MediaServiceImpl.probeMediaInfo(fileId)
│ ├── downloadToTemp(): S3 → /tmp/media_xxx.mp4
│ ├── ffprobe -v quiet -print_format json -show_format -show_streams /tmp/media_xxx.mp4
│ ├── 解析 JSON:
│ │ ├── duration: 3720 秒 (62分钟)
│ │ ├── resolution: "1920x1080"
│ │ ├── bitrate: 2000 kbps
│ │ ├── videoCodec: "h264"
│ │ └── audioCodec: "aac"
│ └── 更新 FileInfo 记录 ↑
│
├── 4. 发送转码任务(异步)
│ └── rabbitTemplate.convertAndSend(transcode.exchange,
│ transcode.{instanceId}, new TranscodeMessage(fileId, "hls"))
│
└── 5. 返回 FileInfoVO { id=789, url="...", transcodeStatus="PENDING" }
→ kb-document 入库 FileMetadata
→ 前端展示 "转码中..."
──── 异步线程(不阻塞上传) ────
├── 6. TranscodeConsumer 消费消息
│ ├── updateTranscodeStatus(789, "PROCESSING")
│ ├── transcodeToHls(789)
│ │ ├── S3 下载 → /tmp/media_789.mp4
│ │ ├── FFmpeg 360p: scale=640:360, crf=28, 64k AAC
│ │ ├── FFmpeg 720p: scale=1280:720, crf=23, 128k AAC
│ │ ├── 生成 master.m3u8(双码率自适应)
│ │ ├── 上传全部 .ts + .m3u8 → S3 /2026/06/24/a3/.../hls/
│ │ └── 更新 hlsPath
│ ├── generateThumbnail(789)
│ │ ├── ffmpeg -ss 00:00:05 -vframes 1 -q:v 2 → thumbnail.jpg
│ │ └── 上传 → S3 + 更新 thumbnailPath
│ └── updateTranscodeStatus(789, "DONE")
前端刷新或 WebSocket 推送 → transcodeStatus = "DONE"
用户在文件管理页点击 "企业安全培训.mp4" 预览
→ FileManagementPage 详情弹窗
→ getStreamUrl(fileId) → <video> 加载 master.m3u8:
│
├── GET /api/files/stream/789/master.m3u8
│ └── kb-file → S3 GetObject(hls/master.m3u8)
│ └── 返回 360p + 720p 双码率播放列表
│
└── 浏览器根据带宽自动选择码率 → 请求 TS 分片
├── GET /api/files/stream/789/360p/001.ts
└── GET /api/files/stream/789/720p/001.ts
└── HTML5 <video> 逐片播放 → 用户看到流畅视频整个过程涉及 3 个微服务(kb-document ↔ kb-file,通过 Feign + RabbitMQ),2 种存储介质(MySQL 存元数据 + RustFS S3 存文件),2 种传输模式(同步 API 上传 + 异步 MQ 转码),2 种前端播放模式(转码前 Range 字节流 + 转码后 HLS 自适应码率)。
2. 多媒体架构全景图
2.1 系统分层
┌────────────────────────────────────────────────────────────────────┐
│ 前端多媒体展示层 (React + TypeScript) │
│ │
│ FileManagementPage ── 多媒体管理中枢 │
│ ├── 图片预览: <Image> + Ant Design lightbox │
│ ├── 视频播放: <video> + HLS / HTTP Range streaming │
│ ├── 音频播放: <audio> + HTTP Range streaming │
│ ├── PDF 预览: react-pdf (<Document> + <Page>) + 缩放控制 │
│ ├── DOCX 预览: mammoth.js → 保留样式的 HTML │
│ ├── XLSX 预览: SheetJS → 合并单元格 + 背景色 Table │
│ ├── PPTX 预览: 后端渲染 Base64 幻灯片图片 + 缩略图导航 │
│ ├── TXT 预览: <pre> + 等宽字体 │
│ └── MD 预览: ReactMarkdown + remarkGfm + PrismJS │
└───────────────────────────────┬────────────────────────────────────┘
│ HTTP / SSE
▼
┌────────────────────────────────────────────────────────────────────┐
│ kb-document 文档微服务 (:8082) │
│ │
│ FileManagementController ── 文件管理 CRUD │
│ ├── POST /document/file-management/upload │
│ ├── GET /document/file-management/stream/{id} ── Range 字节流 │
│ └── GET /document/file-management/pptx/{id}/slides ── 幻灯片 │
│ │
│ FileParserServiceImpl ── 文档 → Markdown │
│ ├── parsePdf() → Apache PDFBox + CollectingPDFStripper │
│ ├── parseDocx() → Apache POI XWPF │
│ ├── parseXlsx() → Apache Tika (主) + Apache POI (降级) │
│ ├── parsePptx() → Apache POI XSLF │
│ └── parsePlainText() → Files.readString() │
│ │
│ Feign Client ──→ kb-file │
└───────────────────────────────┬────────────────────────────────────┘
│ Feign + 异步 RabbitMQ
▼
┌────────────────────────────────────────────────────────────────────┐
│ kb-file 文件微服务 (:8084) │
│ │
│ FileController ── 文件 CRUD + 流媒体 │
│ ├── POST /files/upload ── 上传 │
│ ├── GET /files/download/{id} ── 下载 (RFC 5987) │
│ ├── GET /files/stream/{id}/master.m3u8 ── HLS 播放列表 │
│ ├── GET /files/stream/{id}/*.ts ── HLS 分片 │
│ ├── GET /files/thumbnail/{id} ── 缩略图 │
│ └── POST /files/batch-convert ── URL 批量转换 │
│ │
│ FileServiceImpl ── 上传核心 │
│ MediaServiceImpl ── FFmpeg/FFprobe 命令行封装 │
│ TranscodeConsumer ── RabbitMQ 异步转码消费者 │
│ RustFileStorage ── S3 兼容存储适配器 │
└───────────────────────────────┬────────────────────────────────────┘
│ AWS S3 SDK
▼
┌────────────────────────────────────────────────────────────────────┐
│ RustFS S3 兼容对象存储 │
│ │
│ Endpoint: 117.72.88.11:9091 │
│ Bucket: knowledge-dev │
│ 目录结构: yyyy/MM/dd/{hash[:2]}/{hash}.{ext} │
│ yyyy/MM/dd/{hash[:2]}/hls/{360p,720p}/*.ts │
│ yyyy/MM/dd/{hash[:2]}/thumbnail.jpg │
└────────────────────────────────────────────────────────────────────┘2.2 支持的文件格式矩阵
| 类别 | 扩展名 | 存储方式 | 文本提取 | 前端预览 |
|---|---|---|---|---|
| 文档 | .pdf | RustFS S3 | PDFBox 标题/表格/图片提取 | react-pdf 逐页渲染 |
| 文档 | .docx | RustFS S3 | POI XWPF 标题/列表/表格提取 | mammoth.js → HTML |
| 文档 | .xlsx | RustFS S3 | Tika (主) + POI (降级) → Markdown 表格 | SheetJS 多 Sheet HTML Table |
| 文档 | .pptx | RustFS S3 | POI XSLF 形状遍历 → Markdown | 后端渲染 Base64 幻灯片 |
| 文档 | .txt | RustFS S3 | 直接 UTF-8 读取 | <pre> 展示 |
| 文档 | .md | RustFS S3 | 直接 UTF-8 读取 | ReactMarkdown + 代码高亮 |
| 图片 | .jpg/.png/.gif/.webp/.svg/.bmp | RustFS S3 | 不可提取 | <Image> + lightbox |
| 视频 | .mp4/.avi/.mov/.mkv/.webm/.wmv | RustFS S3 | 不可提取 | HLS(转码后) / Range byte stream(转码前) |
| 音频 | .mp3/.wav/.flac/.aac/.ogg/.m4a | RustFS S3 | 不可提取 | <audio> + Range stream |
3. 文件上传:校验、哈希、秒传与存储路径
3.1 上传全流程
// kb-file/.../service/impl/FileServiceImpl.java
@Override
@Transactional(rollbackFor = Exception.class)
public FileInfoVO uploadFile(MultipartFile file, FileUploadDTO dto) {
// 1. 三重校验
validateFile(file); // 大小 + 扩展名 + Content-Type
// 2. 计算文件哈希(SHA-256)
String fileHash = calculateFileHash(file.getInputStream());
// 3. 秒传检查:相同哈希的文件跳过上传
if (enableFastUpload) {
FileInfo existFile = fileMapper.selectOne(
new LambdaQueryWrapper<FileInfo>()
.eq(FileInfo::getFileHash, fileHash)
.eq(FileInfo::getStatus, 1));
if (existFile != null) {
return convertToVO(existFile); // 秒传直接返回
}
}
// 4. 生成存储路径
String relativePath = generateRelativePath(fileHash, originalFilename);
// 5. 上传到 RustFS S3
storage.upload(file.getInputStream(), relativePath, file.getSize());
// 6. 检测文件类型
String fileType = detectFileType(extension, contentType);
// 7. 保存元数据到 MySQL
fileMapper.insert(fileInfo);
// 8. 音视频文件:同步提取元数据
if (isMediaFile(fileInfo)) {
MediaMetadata metadata = mediaService.probeMediaInfo(fileInfo.getId());
fileInfo.setDuration(metadata.getDuration());
fileInfo.setResolution(metadata.getResolution());
fileInfo.setBitrate(metadata.getBitrate());
}
return convertToVO(fileInfo);
}3.2 三重文件校验
private void validateFile(MultipartFile file) {
if (file == null || file.isEmpty()) {
throw new BusinessException("文件不能为空");
}
if (file.getSize() > maxSize) {
throw new BusinessException("文件大小超过限制: " +
FileUtil.readableFileSize(maxSize));
}
String extension = FileUtil.extName(originalFilename).toLowerCase();
if (!allowedTypes.contains(extension)) {
throw new BusinessException("不支持的文件类型: " + extension);
}
}3.3 文件类型智能检测
系统通过双路检测确保类型准确:扩展名匹配 + MIME 回退。
// kb-file/.../service/impl/FileServiceImpl.java
private String detectFileType(String extension, String mimeType) {
if (FileUtil.IMAGE_EXTENSIONS.contains(extension)) return "IMAGE";
if (FileUtil.VIDEO_EXTENSIONS.contains(extension)) return "VIDEO";
if (FileUtil.AUDIO_EXTENSIONS.contains(extension)) return "AUDIO";
if (FileUtil.DOCUMENT_EXTENSIONS.contains(extension))return "DOCUMENT";
// MIME 回退
if (mimeType != null) {
if (mimeType.startsWith("image/")) return "IMAGE";
if (mimeType.startsWith("video/")) return "VIDEO";
if (mimeType.startsWith("audio/")) return "AUDIO";
}
return "OTHER";
}// kb-common/.../utils/FileUtil.java - 类型分类常量
IMAGE_EXTENSIONS = {"jpg","jpeg","png","gif","bmp","webp","svg","ico"};
DOCUMENT_EXTENSIONS = {"pdf","doc","docx","xls","xlsx","ppt","pptx","txt","md","csv"};
VIDEO_EXTENSIONS = {"mp4","avi","mov","wmv","flv","mkv","webm","m4v","3gp"};
AUDIO_EXTENSIONS = {"mp3","wav","flac","aac","ogg","m4a","wma"};3.4 存储路径设计
knowledge-dev/ ← RustFS Bucket
├── 2026/06/24/ ← 日期层级
│ ├── a3/ ← 哈希前 2 位
│ │ ├── a3f8b2c9....mp4 ← 原始文件
│ │ ├── a3f8b2c9....hls/ ← HLS 转码目录
│ │ │ ├── master.m3u8
│ │ │ ├── 360p/
│ │ │ │ ├── index.m3u8
│ │ │ │ ├── 001.ts
│ │ │ │ └── 002.ts
│ │ │ └── 720p/
│ │ │ ├── index.m3u8
│ │ │ ├── 001.ts
│ │ │ └── 002.ts
│ │ └── a3f8b2c9....thumbnail.jpg ← 缩略图
│ └── b1/
│ └── ...路径生成公式:yyyy/MM/dd/{sha256[0:2]}/{sha256}.{ext}
设计意图:日期层级便于按时间范围清理/归档;哈希前 2 位分散同一日期的文件到 256 个子目录,防止单目录文件过多。
3.5 秒传机制
上传前计算 SHA-256 哈希,查询数据库是否存在相同哈希且未删除的记录。存在则直接返回已有文件信息,跳过存储上传 —— 尤其适合团队内重复上传同一份参考资料。
3.6 RustFS S3 存储适配器核心操作
// kb-file/.../storage/RustFileStorage.java
public boolean upload(InputStream is, String path, long size) {
s3Client.putObject(PutObjectRequest.builder()
.bucket(bucketName)
.key(path)
.build(),
AsyncRequestBody.fromInputStream(is, size, executorService));
}
public InputStream getInputStream(String path) {
return s3Client.getObject(GetObjectRequest.builder()
.bucket(bucketName).key(path).build());
}
public boolean exists(String path) {
try {
s3Client.headObject(HeadObjectRequest.builder()
.bucket(bucketName).key(path).build());
return true;
} catch (NoSuchKeyException e) { return false; }
}3.7 配置参数总览
// kb-file/.../config/FileStorageProperties.java
@Component
@ConfigurationProperties(prefix = "file.storage")
public class FileStorageProperties {
private Rustfs rustfs = new Rustfs(); // endpoint, port, accessKey, bucketName
private Upload upload = new Upload(); // maxSize(2GB), allowedTypes(29), fastUpload, calculateHash
private Ffmpeg ffmpeg = new Ffmpeg(); // path, hlsSegmentTime(10s), thumbnailTime(5s)
private Url url = new Url(); // prefix, previewPrefix
}| 配置项 | 默认值 | 说明 |
|---|---|---|
upload.maxSize | 2147483648 (2GB) | 全局上传限制(Spring servlet 另有 20MB 限制) |
upload.allowedTypes | 29 种 | pdf, docx, xlsx, pptx, png, jpg, mp4, avi, mp3, aac 等 |
upload.enableFastUpload | true | SHA-256 秒传开关 |
upload.calculateHash | true | 上传时是否计算文件哈希 |
upload.enableResumableUpload | true | 断点续传开关 |
ffmpeg.path | /usr/bin/ffmpeg | FFmpeg 可执行文件路径 |
ffmpeg.ffprobePath | /usr/bin/ffprobe | FFprobe 可执行文件路径 |
ffmpeg.hlsSegmentTime | 10 | HLS 分片时长(秒) |
ffmpeg.thumbnailTime | 5 | 缩略图截图时间点(秒) |
4. 媒体元数据提取:FFprobe 深度集成
4.1 调用 FFprobe
上传视频/音频文件后,系统同步通过命令行调用 FFprobe 提取媒体元数据:
// kb-file/.../service/impl/MediaServiceImpl.java
public MediaMetadata probeMediaInfo(Long fileId) {
FileInfo fileInfo = fileMapper.selectById(fileId);
// 检查 ffprobe 是否可用
if (!new File(ffprobePath).exists()) {
log.warn("ffprobe 不可用,跳过媒体元数据提取:fileId={}", fileId);
return MediaMetadata.builder().build(); // 降级返回空元数据
}
// 从 RustFS 下载到临时文件
tempFile = downloadToTemp(fileInfo);
// 调用 ffprobe
ProcessBuilder pb = new ProcessBuilder(
ffprobePath,
"-v", "quiet", // 最小日志
"-print_format", "json", // JSON 输出便于解析
"-show_format", // 容器信息(时长、总码率)
"-show_streams", // 流信息(分辨率、编解码器)
tempFile.toString()
);
Process process = pb.start();
String output = readProcessOutput(process);
boolean completed = process.waitFor(30, TimeUnit.SECONDS); // 30s 超时
return parseFfprobeOutput(output);
}4.2 JSON 输出解析
private MediaMetadata parseFfprobeOutput(String jsonOutput) {
JSONObject root = JSONUtil.parseObj(jsonOutput);
JSONObject format = root.getJSONObject("format");
JSONArray streams = root.getJSONArray("streams");
Integer duration = format.getDouble("duration").intValue(); // 秒
Integer bitrate = format.getInt("bit_rate") / 1000; // bps → kbps
String resolution = null;
for (int i = 0; i < streams.size(); i++) {
JSONObject stream = streams.getJSONObject(i);
if ("video".equals(stream.getStr("codec_type"))) {
Integer width = stream.getInt("width");
Integer height = stream.getInt("height");
resolution = width + "x" + height; // "1920x1080"
videoCodec = stream.getStr("codec_name"); // "h264"
} else if ("audio".equals(stream.getStr("codec_type"))) {
audioCodec = stream.getStr("codec_name"); // "aac"
}
}
return MediaMetadata.builder()
.duration(duration)
.resolution(resolution)
.bitrate(bitrate)
.videoCodec(videoCodec)
.audioCodec(audioCodec)
.build();
}4.3 降级策略
FFprobe 提取失败或 ffprobe 不可用时不影响文件上传:返回空的 MediaMetadata.builder().build(),duration/resolution/bitrate 保持 null,前端展示时显示 "未知"。
4.4 扩展数据表字段
-- kb_file 对 tb_file 的媒体扩展
ALTER TABLE tb_file
ADD COLUMN duration INT COMMENT '时长(秒)',
ADD COLUMN resolution VARCHAR(20) COMMENT '分辨率 如1920x1080',
ADD COLUMN bitrate INT COMMENT '码率(kbps)',
ADD COLUMN transcode_status VARCHAR(20) DEFAULT NULL
COMMENT '转码状态: PENDING/PROCESSING/DONE/FAILED',
ADD COLUMN hls_path VARCHAR(500) COMMENT 'HLS播放列表目录路径',
ADD COLUMN thumbnail_path VARCHAR(500) COMMENT '缩略图路径';
CREATE INDEX idx_transcode_status ON tb_file(transcode_status);5. 异步视频转码:HLS 自适应码率 + RabbitMQ
5.1 为什么异步
2GB 视频的 HLS 转码可能耗时 5-30 分钟。如果在上传请求中同步等待,用户会超时,Tomcat 线程会阻塞。系统通过 RabbitMQ 将转码任务异步化:
上传完成 → 发送 TranscodeMessage 到 RabbitMQ → 立即返回 (transcodeStatus = "PENDING")
↓
TranscodeConsumer 异步消费 → 转码 360p + 720p → 更新状态为 "DONE"5.2 消息模型
// kb-file/.../message/TranscodeMessage.java
@Data
public class TranscodeMessage implements Serializable {
private Long fileId;
private String targetFormat; // "hls"
}发送端(FileServiceImpl 上传完成后):
if (isVideoFile(fileInfo)) {
TranscodeMessage message = new TranscodeMessage();
message.setFileId(fileInfo.getId());
message.setTargetFormat("hls");
rabbitTemplate.convertAndSend("transcode.exchange",
"transcode." + instanceIdentifier.getInstanceId(), message);
}5.3 消费者
// kb-file/.../consumer/TranscodeConsumer.java
@Component
@RequiredArgsConstructor
public class TranscodeConsumer {
private final MediaService mediaService;
@RabbitListener(queues = "#{@transcodeQueue.name}")
public void handleTranscodeMessage(TranscodeMessage message) {
try {
mediaService.updateTranscodeStatus(message.getFileId(), "PROCESSING");
mediaService.transcodeToHls(message.getFileId()); // FFmpeg HLS
mediaService.generateThumbnail(message.getFileId()); // 缩略图
mediaService.updateTranscodeStatus(message.getFileId(), "DONE");
} catch (Exception e) {
mediaService.updateTranscodeStatus(message.getFileId(), "FAILED");
}
}
}5.4 FFmpeg 双码率 HLS 转码
// kb-file/.../service/impl/MediaServiceImpl.java
public String transcodeToHls(Long fileId) {
tempFile = downloadToTemp(fileInfo); // S3 → /tmp/media_xxx.mp4
// 360p 低码率(移动端、弱网)
transcodeResolution(ffmpegPath, tempFile, hls360Dir, segmentTime,
640, 360, // width, height
28, // CRF: 高压缩比
64); // AAC 64k
// 720p 标准码率(桌面端、WiFi)
transcodeResolution(ffmpegPath, tempFile, hls720Dir, segmentTime,
1280, 720, // width, height
23, // CRF: 标准质量
128); // AAC 128k
// 生成 master playlist:浏览器自适应选择码率
String master = generateMasterPlaylist();
uploadHlsFiles(storage, hlsDir, hlsRelativePath); // 上传所有 .ts + .m3u8
}
private void transcodeResolution(String ffmpegPath, String input, Path output,
int segTime, int w, int h, int crf, int audioKbps) {
new ProcessBuilder(ffmpegPath,
"-i", input,
"-c:v", "libx264", // H.264 编码
"-preset", "fast", // 编码速度优先
"-crf", String.valueOf(crf), // 质量参数
"-vf", "scale=" + w + ":" + h,
"-c:a", "aac",
"-b:a", audioKbps + "k",
"-hls_time", String.valueOf(segTime), // 每 10 秒一个分片
"-hls_list_size", "0", // 无播放列表长度限制
"-hls_segment_filename", output + "/%03d.ts",
"-y",
output + "/index.m3u8"
).start().waitFor(300, TimeUnit.SECONDS); // 5 分钟超时
}5.5 Master Playlist 生成
private String generateMasterPlaylist() {
return """
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=600000,RESOLUTION=640x360
360p/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1500000,RESOLUTION=1280x720
720p/index.m3u8
""";
}浏览器播放器会自动检测当前带宽并选择码率。弱网切换到 360p,WiFi 使用 720p。
5.6 队列隔离
每个 kb-file 实例使用独立队列 transcode.queue.{instanceId},避免多个实例竞争同一任务:
// kb-file/.../config/RabbitMQConfig.java
@Bean
public Queue transcodeQueue() {
return new Queue("transcode.queue." + instanceIdentifier.getInstanceId(),
true, false, false); // durable, non-exclusive, non-auto-delete
}6. 缩略图生成:FFmpeg 关键帧截取
6.1 FFmpeg 截帧命令
// kb-file/.../service/impl/MediaServiceImpl.java
public String generateThumbnail(Long fileId) {
tempFile = downloadToTemp(fileInfo);
new ProcessBuilder(ffmpegPath,
"-i", tempFile.toString(),
"-ss", formatTime(thumbnailTime), // "00:00:05" — 第 5 秒
"-vframes", "1", // 只取 1 帧
"-q:v", "2", // 高质量 JPEG
"-y", // 覆盖已有文件
thumbnailFile.toString()
).start().waitFor(30, TimeUnit.SECONDS);
// 上传缩略图到 RustFS
storage.upload(new FileInputStream(thumbnailFile),
basePath + "/thumbnail.jpg", Files.size(thumbnailFile));
fileInfo.setThumbnailPath(relativePath);
fileMapper.updateById(fileInfo);
}6.2 缩略图访问
GET /api/files/thumbnail/789
→ FileController.getThumbnail(789)
→ FileService.getThumbnail(789, response)
→ RustFS S3 GetObject({hlsPath}/thumbnail.jpg)
→ 返回 Content-Type: image/jpeg7. 文档解析:PDF/DOCX/XLSX/PPTX → Markdown
7.1 解析器入口
// kb-document/.../service/impl/FileParserServiceImpl.java
public String parse(MultipartFile file) throws Exception {
String extension = getExtension(originalFilename);
if (!isSupported(extension)) {
throw new IllegalArgumentException("不支持的文件格式: " + extension);
}
return switch (extension.toLowerCase()) {
case "docx" -> parseDocx(file); // Apache POI XWPF
case "pdf" -> parsePdf(file); // Apache PDFBox
case "pptx" -> parsePptx(file); // Apache POI XSLF
case "xlsx" -> withFallback(file, ext, // Tika (主) → POI (降级)
() -> tika.parseXlsx(file),
this::parseXlsx);
case "txt", "md" -> parsePlainText(file); // 直接读取
default -> throw new IllegalArgumentException("不支持的格式");
};
}7.2 PDF 解析 —— 自定义 CollectingPDFStripper
系统没有使用默认的 PDFTextStripper.getText() 直接取纯文本,而是编写了 CollectingPDFStripper 继承 PDFTextStripper,覆盖 writeString() 方法在 PDFBox 的行级别输出处进行深度分析:
// kb-document/.../service/impl/FileParserServiceImpl.java
private static class CollectingPDFStripper extends PDFTextStripper {
private final List<PdfLine> lines = new ArrayList<>();
@Override
protected void writeString(String text, List<TextPosition> positions) {
// 从 TextPosition 提取每字的字体、字号、粗细、等宽特征
float maxFontSize = positions.stream()
.map(TextPosition::getFontSize).max(Float::compare).orElse(0f);
boolean isBold = positions.stream()
.anyMatch(p -> p.getFont().getName().toLowerCase().contains("bold"));
boolean isMono = positions.stream()
.allMatch(p -> p.getWidthOfSpace() > 0
&& Math.abs(p.getWidth() - p.getWidthOfSpace()) < 0.5f);
lines.add(new PdfLine(text, maxFontSize, isBold, isMono, y));
}
}标题检测(基于字号比例):
字号比例 → 标题级别
≥ 2.0x → H1 (#)
≥ 1.5x → H2 (##)
≥ 1.2x → H3 (###)
≥ 1.1x + bold → H4 (####)
≥ 1.05x + bold → H5 (#####)
相同 + bold → H6 (######)表格检测(基于字内间距分析):
// 当字间距超过平均字符宽度的 3 倍(12 点)时判定为列分隔
if (gap > avgCharWidth * 3) {
// 将此行拆分为多个列
columns.add(text);
}
// 按列输出为 Markdown pipe 表格代码块检测(基于等宽字体 + 关键字启发):
if (line.isMono && containsCodeKeywords(line.text)) {
// 相邻等宽行 → fenced code block (```)
}
// 关键字: function, class, def, import, var, const, SELECT, CREATE...图片提取(从 PDResources 遍历):
for (PDPage page : document.getPages()) {
PDResources resources = page.getResources();
for (COSName name : resources.getXObjectNames()) {
PDXObject xobj = resources.getXObject(name);
if (xobj instanceof PDImageXObject) {
byte[] imageBytes = extractImageBytes((PDImageXObject) xobj);
String url = fileUploadService.uploadBytes(imageBytes, "image.png");
imagePlacements.add(new ImagePlacement(y, url));
}
}
}提取的图片通过fileUploadService.uploadBytes()上传到 RustFS S3,在 Markdown 的对应 Y 坐标位置插入。
7.3 DOCX 解析
private String parseDocx(MultipartFile file) throws Exception {
XWPFDocument doc = new XWPFDocument(file.getInputStream());
List<IBodyElement> elements = doc.getBodyElements(); // 保留段落/表格交错顺序
for (IBodyElement element : elements) {
if (element instanceof XWPFParagraph) {
// 标题检测: outlineLvl → style name → 编号模式(如 "1.")
// 列表检测: numPr 存在 → 缩进层级 lvl
// 代码块: style 含 "code" + 等宽字体 + 背景色
// 行内格式: 加粗→** 斜体→* 代码→` 链接→[text](url)
} else if (element instanceof XWPFTable) {
// 遍历 rows/cells → Markdown pipe table + separator row
}
}
}7.4 XLSX 解析 —— Tika 优先 + POI 降级
// Tika 主路径:提供高质量的 Markdown 表格
String result = tikaConverter.parseXlsx(file);
// POI 降级路径:Tika 失败或不可用时
private String parseXlsx(MultipartFile file) {
XSSFWorkbook workbook = new XSSFWorkbook(file.getInputStream());
for (int i = 0; i < workbook.getNumberOfSheets(); i++) {
Sheet sheet = workbook.getSheetAt(i);
for (Row row : sheet) {
for (Cell cell : row) {
// 转换为 pipe table 格式
}
}
}
}7.5 PPTX 解析
private String parsePptx(MultipartFile file) throws Exception {
XMLSlideShow ppt = new XMLSlideShow(file.getInputStream());
int slideNum = 1;
for (XSLFSlide slide : ppt.getSlides()) {
result.append("## 幻灯片 ").append(slideNum++).append("\n\n");
for (XSLFShape shape : slide.getShapes()) {
if (shape instanceof XSLFTable) { /* 表格 */ }
else if (shape instanceof XSLFTextShape) {
// 标题检测: placeholder == TITLE / CENTER_TITLE
// 忽略注解放置框
}
}
}
}7.6 解析能力一览
| 格式 | 解析引擎 | 输出能力 |
|---|---|---|
| Apache PDFBox + Custom Stripper | 文本、标题层级(H1-H6)、段落分隔、Markdown 表格、代码块(等宽检测)、图片提取 | |
| DOCX | Apache POI XWPF | 文本、标题(outlineLvl/style/numbering)、列表(numPr/缩进)、表格、超链接、加粗/斜体/代码行内格式 |
| XLSX | Apache Tika (主) + POI (降级) | Markdown 表格 |
| PPTX | Apache POI XSLF | 文本、标题(placeholder)、表格 |
| TXT/MD | Java NIO Files.readString | 纯文本 |
8. 前端多媒体预览:从 react-pdf 到 HLS 播放器
8.1 预览调度
FileManagementPage 是前端的媒体管理中枢,根据 fileCategory 选择不同的预览策略:
fileCategory === 'image'
→ <Image> + Ant Design lightbox(点击放大)
fileCategory === 'video'
→ transcodeStatus === 'DONE'
→ <video src={streamUrl}> 播放 HLS (master.m3u8)
→ transcodeStatus !== 'DONE'
→ <video src={mediaStreamUrl}> 播放 HTTP Range 字节流
fileCategory === 'audio'
→ <audio src={mediaStreamUrl}> 播放 HTTP Range 字节流
fileCategory === 'document'
→ .pdf → react-pdf (<Document> + <Page>) + 0.5x-3.0x 缩放
→ .docx → mammoth.js 客户端转换 HTML
→ .xlsx → SheetJS 渲染 HTML Table
→ .pptx → 后端渲染 Base64 幻灯片 PNG
→ .md → ReactMarkdown + remarkGfm + PrismJS
→ .txt → <pre>8.2 视频播放双模式
转码完成后(HLS 模式):
// 前端 FileManagementPage
const streamUrl = fileManagementService.getStreamUrl(fileId);
// → /api/files/stream/{fileId}/master.m3u8
// <video> 标签原生支持 HLS → 浏览器自动码率切换转码未完成(Range Streaming 降级模式):
const mediaStreamUrl = fileManagementService.getMediaStreamUrl(fileId);
// → /api/document/file-management/stream/{fileId}
// kb-document 代理 Range 请求到 RustFS S3
// HTML5 <video> 默认使用 Range 请求实现拖动进度条8.3 PDF 预览(react-pdf)
<Document file={accessUrl} loading={<Skeleton />} error={<ErrorBoundary />}>
<Page pageNumber={currentPage}
renderTextLayer={true}
renderAnnotationLayer={true} />
</Document>
// 缩放控制: 0.5x / 1.0x / 1.5x / 2.0x / 3.0x
// 连续滚动模式: 所有页面垂直排列8.4 DOCX 预览(mammoth.js 客户端转换)
import mammoth from 'mammoth';
// 客户端将 DOCX 转换为 HTML
const result = await mammoth.convertToHtml({ arrayBuffer: fileBuffer });
setHtmlContent(result.value);
// <div dangerouslySetInnerHTML={{ __html: htmlContent }} />
// mammoth.js 自动处理:标题层级、列表、表格、加粗/斜体、图片转 Data URI8.5 XLSX 预览(SheetJS)
import * as XLSX from 'xlsx';
const workbook = XLSX.read(fileBuffer, { type: 'array' });
const firstSheet = workbook.SheetNames[0];
const html = XLSX.utils.sheet_to_html(workbook.Sheets[firstSheet], {
editable: false,
});
// 渲染: 合并单元格(rowSpan/colSpan)、背景色、对齐方式、字体格式8.6 PPTX 预览(后端渲染)
// 前端调用后端渲染 Base64 幻灯片
const slideUrls = await fileManagementService.getPptxSlideImages(fileId);
// kb-document: Apache POI XMLSlideShow → BufferedImage → data:image/png;base64,...
// 前端渲染幻灯片浏览器
<Image src={slideUrls[currentSlide]} />
<div className="thumbnail-strip">
{slideUrls.map((url, i) => (
<img key={i} src={url} onClick={() => setCurrentSlide(i)} />
))}
</div>// kb-document/.../FileManagementServiceImpl.java - 后端幻灯片渲染
for (XSLFSlide slide : ppt.getSlides()) {
BufferedImage img = new BufferedImage(960, 540, TYPE_INT_RGB);
Graphics2D g2d = img.createGraphics();
g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, VALUE_ANTIALIAS_ON);
slide.draw(g2d);
// 转 Base64 返回
}9. 下载与流式传输:Range 请求、RFC 5987 文件名
9.1 文件下载 —— RFC 5987 中文文件名
// kb-file/.../service/impl/FileServiceImpl.java
public void downloadFile(Long fileId, HttpServletResponse response) {
FileInfo fileInfo = fileMapper.selectById(fileId);
// RFC 5987 编码中文文件名
String encodedName = URLEncoder.encode(fileInfo.getOriginalName(),
StandardCharsets.UTF_8).replaceAll("\\+", "%20");
response.setHeader("Content-Disposition",
"attachment; filename=\"" + encodedName + "\"; " +
"filename*=UTF-8''" + encodedName);
response.setContentType(fileInfo.getMimeType());
response.setContentLengthLong(fileInfo.getFileSize());
// 从 RustFS 流式读取 → HTTP 响应
try (InputStream is = storage.getInputStream(fileInfo.getFilePath());
OutputStream os = response.getOutputStream()) {
IOUtils.copy(is, os);
}
}9.2 HTTP Range 字节流 —— 拖动进度条的支持
// kb-document/.../FileManagementServiceImpl.java
private void handleRangeRequest(String rangeHeader, long fileSize,
String accessUrl, HttpServletResponse response) {
// 解析 "bytes=start-end"
Matcher matcher = Pattern.compile("bytes=(\\d+)-(\\d*)").matcher(rangeHeader);
long start = Long.parseLong(matcher.group(1));
long end = matcher.group(2).isEmpty() ? fileSize - 1 : Long.parseLong(matcher.group(2));
// 206 Partial Content
response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT);
response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileSize);
response.setContentLengthLong(end - start + 1);
// 代理 Range 请求到上游存储
URLConnection conn = new URL(accessUrl).openConnection();
conn.setRequestProperty("Range", "bytes=" + start + "-" + end);
// 8KB buffer 流式传输
byte[] buffer = new byte[8192];
try (InputStream is = conn.getInputStream();
OutputStream os = response.getOutputStream()) {
int bytesRead;
while ((bytesRead = is.read(buffer)) != -1) {
os.write(buffer, 0, bytesRead);
}
}
}HTML5<video>和<audio>标签在播放时默认发送 Range 请求实现拖动进度条。转码完成后的 HLS 模式不需要 Range 请求(浏览器请求单独的.ts分片)。
9.3 HLS 流式分发
// kb-file/.../controller/FileController.java
@GetMapping("/stream/{fileId}/master.m3u8")
public void streamMasterPlaylist(@PathVariable Long fileId,
HttpServletResponse response) throws IOException {
fileService.streamMasterPlaylist(fileId, response);
// → S3 GetObject({hlsPath}/master.m3u8)
// → Content-Type: application/vnd.apple.mpegurl
}
@GetMapping("/stream/{fileId}/{segment:.+\\.ts}")
public void streamSegment(@PathVariable Long fileId,
@PathVariable String segment, HttpServletResponse response) throws IOException {
fileService.streamSegment(fileId, segment, response);
// → S3 GetObject({hlsPath}/{quality}/{segment})
// → Content-Type: video/MP2T
}10. 总结
| # | 亮点 | 说明 |
|---|---|---|
| 1 | 秒传机制 | SHA-256 去重,同一文件多人上传只存一份,节省存储和带宽 |
| 2 | 自定义 PDF 解析 | CollectingPDFStripper 从字体元数据推断标题层级、表格列、代码块,远超默认 getText() 的输出质量 |
| 3 | Tika + POI 双引擎降级 | XLSX 解析 Tika 优先(高质量 Markdown),失败自动降级到 POI,兼顾质量与可用性 |
| 4 | 异步转码 + 状态机 | PENDING → PROCESSING → DONE/FAILED,上传立即返回,转码不阻塞用户 |
| 5 | 双播放模式切换 | 转码完成前 Range 字节流,转码完成后 HLS 自适应码率,用户始终可播放 |
| 6 | RFC 5987 中文文件名 | filename*=UTF-8''%E6%96%87%E6%A1%A3.pdf 优先,filename="..." 回退,确保所有浏览器不乱码 |
| 7 | PDF 图片提取 + 位置保持 | 从 PDResources 提取 XObject 图片,上传到 S3 后在 Markdown 的对应 Y 坐标插入  |
| 8 | RabbitMQ 队列隔离 | transcode.queue.{instanceId} 每个实例独立队列,避免多个 kb-file 实例重复消费 |
| 9 | 前端多引擎预览 | react-pdf (PDF) + mammoth.js (DOCX) + SheetJS (XLSX) + 后端渲染 (PPTX) + HLS video — 9 种格式覆盖 |
| 10 | 存储路径分层设计 | yyyy/MM/dd/{hash[:2]}/{hash}.ext — 按时间归档 + 哈希分散 + 扩展名可见 |
企业智能知识库的多媒体支持管线以 "上传即处理、存储即索引、预览即原生" 为设计原则。
PDF/DOCX/XLSX/PPTX 在入库瞬间被解析为 Markdown,进入全文检索索引;视频在上传后异步转码为 HLS,用户在任何带宽下都能流畅播放;图片自动提取并上传到 S3,在文档的原始位置保留引用。
整个管线由 kb-file(文件微服务)和 kb-document(文档微服务)通过 Feign + RabbitMQ 松耦合协作,前端通过 react-pdf、mammoth.js、SheetJS、HLS video 等多引擎覆盖了 9 种文件格式的原生预览。