前言

企业知识库不只是 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 支持的文件格式矩阵

类别扩展名存储方式文本提取前端预览
文档.pdfRustFS S3PDFBox 标题/表格/图片提取react-pdf 逐页渲染
文档.docxRustFS S3POI XWPF 标题/列表/表格提取mammoth.js → HTML
文档.xlsxRustFS S3Tika (主) + POI (降级) → Markdown 表格SheetJS 多 Sheet HTML Table
文档.pptxRustFS S3POI XSLF 形状遍历 → Markdown后端渲染 Base64 幻灯片
文档.txtRustFS S3直接 UTF-8 读取<pre> 展示
文档.mdRustFS S3直接 UTF-8 读取ReactMarkdown + 代码高亮
图片.jpg/.png/.gif/.webp/.svg/.bmpRustFS S3不可提取<Image> + lightbox
视频.mp4/.avi/.mov/.mkv/.webm/.wmvRustFS S3不可提取HLS(转码后) / Range byte stream(转码前)
音频.mp3/.wav/.flac/.aac/.ogg/.m4aRustFS 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.maxSize2147483648 (2GB)全局上传限制(Spring servlet 另有 20MB 限制)
upload.allowedTypes29 种pdf, docx, xlsx, pptx, png, jpg, mp4, avi, mp3, aac 等
upload.enableFastUploadtrueSHA-256 秒传开关
upload.calculateHashtrue上传时是否计算文件哈希
upload.enableResumableUploadtrue断点续传开关
ffmpeg.path/usr/bin/ffmpegFFmpeg 可执行文件路径
ffmpeg.ffprobePath/usr/bin/ffprobeFFprobe 可执行文件路径
ffmpeg.hlsSegmentTime10HLS 分片时长(秒)
ffmpeg.thumbnailTime5缩略图截图时间点(秒)

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/jpeg

7. 文档解析: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 坐标位置插入 ![](url)。

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 解析能力一览

格式解析引擎输出能力
PDFApache PDFBox + Custom Stripper文本、标题层级(H1-H6)、段落分隔、Markdown 表格、代码块(等宽检测)、图片提取
DOCXApache POI XWPF文本、标题(outlineLvl/style/numbering)、列表(numPr/缩进)、表格、超链接、加粗/斜体/代码行内格式
XLSXApache Tika (主) + POI (降级)Markdown 表格
PPTXApache POI XSLF文本、标题(placeholder)、表格
TXT/MDJava 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 URI

8.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() 的输出质量
3Tika + POI 双引擎降级XLSX 解析 Tika 优先(高质量 Markdown),失败自动降级到 POI,兼顾质量与可用性
4异步转码 + 状态机PENDING → PROCESSING → DONE/FAILED,上传立即返回,转码不阻塞用户
5双播放模式切换转码完成前 Range 字节流,转码完成后 HLS 自适应码率,用户始终可播放
6RFC 5987 中文文件名filename*=UTF-8''%E6%96%87%E6%A1%A3.pdf 优先,filename="..." 回退,确保所有浏览器不乱码
7PDF 图片提取 + 位置保持从 PDResources 提取 XObject 图片,上传到 S3 后在 Markdown 的对应 Y 坐标插入 ![](url)
8RabbitMQ 队列隔离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 种文件格式的原生预览。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏