kkFileView

README

# kkFileView
文档在线预览项目解决方案，项目使用流行的spring boot搭建，易上手和部署。万能的文件预览开源项目，基本支持主流文档格式预览，如：
1. 支持 doc, docx, xls, xlsx, xlsm, ppt, pptx, csv, tsv, dotm, xlt, xltm, dot, dotx,xlam, xla ,pages ,pptm 等 Office 办公文档
2. 支持 wps, dps, et, ett, wpt 等国产 WPS Office 办公文档
3. 支持 odt, ods, ots, odp, otp, six, ott, fodt, fods 等OpenOffice、LibreOffice 办公文档
4. 支持 vsd, vsdx 等 Visio 流程图文件
5. 支持 wmf, emf 等 Windows 系统图像文件
6. 支持 psd ,eps 等 Photoshop 软件模型文件
7. 支持 pdf ,ofd, rtf 等文档
8. 支持 xmind 软件模型文件
9. 支持 bpmn 工作流文件
10. 支持 eml, msg 邮件文件
11. 支持 epub 图书文档
12. 支持 obj, 3ds, stl, ply, gltf, glb, off, 3dm, fbx, dae, wrl, 3mf, ifc, brep, step, iges, fcstd, bim 等 3D 模型文件
13. 支持 dwg, dxf, dwf, iges , igs, dwt, dng, ifc, dwfx, stl, cf2, plt 等 CAD 模型文件
14. 支持 txt, xml(渲染), xbrl(渲染), md(渲染), java, php, py, js, css 等所有纯文本
15. 支持 zip, rar, jar, tar, gzip, 7z 等压缩包
16. 支持 jpg, jpeg, png, gif, bmp, ico, jfif, webp ,heic ,heif等图片预览（翻转，缩放，镜像）
17. 支持 tif, tiff 图信息模型文件
18. 支持 tga 图像格式文件
19. 支持 svg 矢量图像格式文件
20. 支持 mp3,wav,mp4,flv 等音视频格式文件
21. 支持 avi,mov,rm,webm,ts,rm,mkv,mpeg,ogg,mpg,rmvb,wmv,3gp,ts 等视频格式转码预览
22. 支持 dcm 等医疗数位影像预览
23. 支持 drawio 绘图预览

> 基于当前良好的架构模式，支持的文件类型在进一步丰富中
### 项目特性

- 使用 spring-boot 开发，预览服务搭建部署非常简便
- rest 接口提供服务，跨语言、跨平台特性(java,php,python,go,php，....)都支持，应用接入简单方便
- 抽象预览服务接口，方便二次开发，非常方便添加其他类型文件预览支持
- 最最重要 Apache 协议开源，代码 pull 下来想干嘛就干嘛

### 官网及文档

地址：[https://kkview.cn](https://kkview.cn/)

### 在线体验
> 请善待公共服务，会不定时停用

地址：[https://file.kkview.cn](https://file.kkview.cn)

### 项目文档（Project documentation）
1. 详细使用文档：https://kkview.cn/zh-cn/docs/home.html

### 联系我们，加入组织
> 我们会用心回答解决大家在项目使用中的问题，也请大家在提问前至少 Google 或 baidu 过，珍爱生命远离无效的交流沟通

<img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/6b9f8ea2e69db6f3fb82e98d.png" width="60%">

### 文档预览效果
#### 1. 文本预览
支持所有类型的文本文档预览， 由于文本文档类型过多，无法全部枚举，默认开启的类型如下 txt,html,htm,asp,jsp,xml,xbrl,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd  
文本预览效果如下  
![文本预览效果如下](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/41d1dbebc0cdbc471e9ff5a0.png)      

#### 2. 图片预览
支持jpg，jpeg，png，gif等图片预览（翻转，缩放，镜像），预览效果如下  
![图片预览](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/5a85e7911566bf8b44e41020.png)  

#### 3. word文档预览
支持doc，docx文档预览，word预览有两种模式：一种是每页word转为图片预览，另一种是整个word文档转成pdf，再预览pdf。两种模式的适用场景如下  
* 图片预览：word文件大，前台加载整个pdf过慢
* pdf预览：内网访问，加载pdf快
图片预览模式预览效果如下  
![word文档预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/cc0169e836b1c616c48a9131.png)  
pdf预览模式预览效果如下  
![word文档预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/2d4dc2782c296f320143a106.png)  

#### 4. ppt文档预览
支持ppt，pptx文档预览，和word文档一样，有两种预览模式  
图片预览模式预览效果如下  
![ppt文档预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/1ebf1af9f7b1d8f6e5fc5360.png)  
pdf预览模式预览效果如下  
![ppt文档预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/9b9958162d10be2d3159139e.png)  

#### 5. pdf文档预览
支持pdf文档预览，和word文档一样，有两种预览模式   
图片预览模式预览效果如下  
![pdf文档预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/2d859696cdc34df98a0a6e8d.png)  
pdf预览模式预览效果如下   
![pdf文档预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/d3d034b6f1e524a736fb8a6e.png)    

#### 6. excel文档预览
支持xls，xlsx文档预览，预览效果如下  
![excel文档预览](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/d0ea9814d6832aca905667fe.png)  

#### 7. 压缩文件预览
支持zip,rar,jar,tar,gzip等压缩包，预览效果如下  
![压缩文件预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/156faeb6dac5455ec1d3513c.png)  
可点击压缩包中的文件名，直接预览文件，预览效果如下  
![压缩文件预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/c5c0c3efb0342adac2ffaa41.png)  

#### 8. 多媒体文件预览
理论上支持所有的视频、音频文件，由于无法枚举所有文件格式，默认开启的类型如下  
mp3,wav,mp4,flv  
视频预览效果如下  
![多媒体文件预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/86e1690aca8b9c0cacaf0016.png)  
音频预览效果如下  
![多媒体文件预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/aa0741868976cd0721cdb184.png)  

#### 9. CAD文档预览
支持CAD dwg文档预览，和word文档一样，有两种预览模式  
图片预览模式预览效果如下  
![cad文档预览1](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/3df6e52727be72290e93a5e6.png)  
pdf预览模式预览效果如下  
![cad文档预览2](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/4bdffe3c86e015abe3e9be7e.png)

#### 10. Excel文件纯前端渲染效果

![Excel文件纯前端渲染效果](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/236b0cea8219c0bb6c315a48.png)  

#### 11. 流程图bpmn文件预览效果

![流程图bpmn文件预览效果](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/ee3756c2f82ea85fd736feb5.png)  

#### 12. 3D模型文件预览效果：

![3D模型文件预览效果](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/0fe779cbf969b50318aea96a.png)  

#### 13. dcm医疗数位影像文件预览效果：

![dcm医疗数位影像文件预览效果](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/10d62dc471904ed16442057e.png) 

#### 14. drawio流程图预览效果：

![drawio流程图预览效果](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/fd4ea60e0cd764976a07e877.png) 

考虑说明篇幅原因，就不贴其他格式文件的预览效果了，感兴趣的可以参考下面的实例搭建下

### 快速开始
> 项目使用技术
- spring boot： [spring boot开发参考指南](http://www.kailing.pub/PdfReader/web/viewer.html?file=springboot)
- freemarker
- redisson 
- jodconverter

> 依赖外部环境
- redis (可选，默认不用)
- OpenOffice 或者 LibreOffice( Windows 下已内置，Linux 脚本启动模式会自动安装，Mac OS 下需要手动安装)

1. 第一步：pull 项目 https://github.com/kekingcn/file-online-preview.git

3. 第二步：运行 ServerMain 的 main 方法，服务启动后，访问 http://localhost:8012/
会看到如下界面，代表服务启动成功
   
![输入图片说明](https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/a1b6db8bb3442400912b4b18.png "屏幕截图.png")

### 历史更新记录

#### > 2026年10月08日，v5.0.3 安全补丁版本发布：

#### 安全修复
1. FTP 连接前校验命令参数，阻止控制字符注入
2. 上传和建目录限制在演示文件目录内，并检查符号链接
3. 校验所有预览源地址，阻止通过不同参数绕过信任策略
4. 预览页码和代理参数经过类型校验后再渲染模板
5. 在通过校验的压缩包预览中生成目录树，移除公开的 `/directory` 接口
6. 默认仅开放汇总健康状态，不再默认暴露健康详情、info 和 metrics

#### 升级说明
1. 建议所有 v5.0.2 及更早版本用户升级至 v5.0.3，继续要求 JDK 21 及以上
2. 已有外部配置文件需设置 `management.endpoints.web.exposure.include=health` 和 `management.endpoint.health.show-details=never`，才能应用监控配置加固
3. `/directory` 接口已移除，内置压缩包目录预览继续可用
4. 上传仍默认禁用；启用后，上传和建目录仅允许演示目录内的路径

#### > 2026年08月14日，v5.0.2 补丁版本发布 ：

#### 安全修复
1. 将不可信 HTML 预览放入不具有同源权限的 iframe 沙箱，并默认禁用其中的 JavaScript，避免被预览文件在 kkFileView 应用源中执行脚本（GHSA-9wcf-