百度360必应搜狗淘宝本站头条
python类型转换python串口编程python计时python异常python进度条
当前位置：网站首页 > 技术资源 > 正文

在线文档预览kkFileView部署及使用指南

off999 2025-03-14 19:46 32 浏览 0 评论

项目简介

此项目为文件文档在线预览项目解决方案，对标业内付费产品有【永中office】【office365】【idocv】等。该项目使用流行的spring boot搭建，易上手和部署，基本支持主流办公文档的在线预览，如doc,docx,Excel,pdf,txt,zip,rar,图片等等。

项目特性

  • 支持word excel ppt，pdf等办公文档
  • 支持txt,java,php,py,md,js,css等所有纯文本
  • 支持zip,rar,jar,tar,gzip等压缩包
  • 支持jpg，jpeg，png，gif等图片预览（翻转，缩放，镜像）
  • 支持mp3，mp4，flv等多媒体文件预览
  • 使用spring boot开发，预览服务搭建部署非常简便
  • rest接口提供服务，跨平台特性(java,php,python,go,php，....)都支持，应用接入简单方便
  • 支持普通http/https文件下载url、http/https文件下载流url、ftp下载url等多种预览源
  • 提供zip，tar.gz发行包，提供一键启动脚本和丰富的配置项，方便部署使用
  • 提供Docker镜像发行包，方便在容器环境部署
  • 抽象预览服务接口，方便二次开发，非常方便添加其他类型文件预览支持

部署指南

1. 环境要求

  1. Java: 1.8+
  2. Maven：3.4+

2. 下载代码&编译打包

2.1. 从码云仓库拉取代码

git clone https://gitee.com/kekingcn/file-online-preview.git

2.2. 使用maven编译打包

cd file-online-preview
mvn clean package -DskipTests

2.3. 使用docker构建镜像

docker build -t keking/kkfileview:v4.0.0 .

Docker容器环境环境运行

  • 拉取镜像
docker pull keking/kkfileview
  • 运行
docker run -it -p 8012:8012 keking/kkfileview
  • 浏览器访问容器8012端口 http://xxx.xxx.xxx.xxx:8012 即可看到项目演示用首页

3. 项目接入使用

3.1.普通文件下载url预览

3.x.x 及以上版本

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));

2.x.x 及以下版本

var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));

3.2. http/https下载流url预览

很多系统内不是直接暴露文件下载地址，而是请求通过id、code等参数到通过统一的接口，后端通过id或code等参数定位文件，再通过OutputStream输出下载，此时下载url是不带文件后缀名的，预览时需要拿到文件名，传一个参数fullfilename=xxx.xxx来指定文件名，示例如下

3.x.x 版本

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1'; //要预览文件的访问地址
var previewUrl = originUrl + '&fullfilename=test.txt'
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));

2.x.x 及以下版本

var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1'; //要预览文件的访问地址
var previewUrl = originUrl + '&fullfilename=test.txt'
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));

3.3. FTP下载url预览

1). FTP匿名访问

如果要预览的FTP url是可以匿名访问的（不需要用户名密码），则可以直接通过下载url预览，示例如下

3.x.x 版本

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(url)));

2.x.x 及以下版本

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(url));

2). 非匿名访问，确定只有访问一台FTP服务器

如果预览服务只访问一台FTP服务器，只需要在配置文件中 配置FTP链接信息 ，则可以直接通过下载url预览，示例如下

3.x.x 版本

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(url)));

2.x.x 及以下版本

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(url));

3). 非匿名访问，不只访问一台FTP服务器

如果预览服务要访问多台FTP服务器，且用户名密码不一致，可以通过在url中加入用户名密码等参数预览(url参数中的优化于配置文件中的)，示例如下

3.x.x 版本

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var originUrl = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
var previewUrl = originUrl + '?ftp.username=xx&ftp.password=xx&ftp.control.encoding=xx';
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));

2.x.x 及以下版本

var originUrl = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
var previewUrl = originUrl + '?ftp.username=xx&ftp.password=xx&ftp.control.encoding=xx';
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));

配置说明

打开conf目录，下面有一个application.properties配置文件，有部分配置是可以在程序运行中变更的，其他的变更需要重新启动程序

不可动态配置，需要重启生效部分

server.context-path

说明：kkFileView运行时tomcat的ServletContext 默认值：/ 示例：server.context-path = /preview

file.dir

说明：预览文件存储路径，当有大量文件要预览时需要保证该目录所在磁盘有足够的容量
默认值：程序根目录下的file目录下
示例：file.dir = D:\\kkFileview\\

office.home

说明：openoffice或libreoffice安装目录，一般情况下不用配置，如果需要使用自己安装openoffice或libreoffice，可以自行指定
默认值：不同操作系统各自对应的默认安装目录
示例：office.home = C:\\Program Files (x86)\\OpenOffice 4

cache.type

说明：缓存实现方式，默认为内嵌RocksDB实现，可选项：'default', 'jdk', 'redis'

  • default：默认实现，使用RocksDB存储引擎，使用磁盘存储，会占用少量磁盘空间；Windows下需要使用管理员身份启动程序
  • jdk：java对象实现，使用纯内存对象存储，速度极快，外部依赖最少，调试部署方便，会占用内存，推荐调试时和预览文件量不是很大时（<50万）使用，预览文件量极大或有大量压缩包时不推荐使用
  • redis: redis作为缓存实现，速度快，不占用内存和磁盘空间，但是需要有外部redis服务

当配置为redis实现时，需要同时配置redis连接相关配置，如下：

spring.redisson.address = 127.0.0.1:6379
spring.redisson.password = xxxxxx

cache.clean

说明：是否需要自动定时清理缓存及预览过的文件，默认开启（如果不清理缓存，同一个url下如果文件发生变更是不会重新拉取新的文件再去预览的），开启的情况下会在每天凌晨3点清理所有缓存及预览文件，推荐预览量不大，对预览速度要求不高，且同一url下文件经常更新的用户开启，预览量大、预览速度要求高的用户不推荐开启

  • true: 默认值，开启
  • false: 不开启
  • 空：注释掉，不开启

可在运行时动态改变部分

base.url

说明：提供预览服务的地址，默认从接收请求url读，如果使用nginx等反向代理，需要手动设置为通过nginx访问预览服务的地址
默认值：未设置
示例：base.url =
https://file.keking.cn/preview
例如nginx的访问地址为 https://file.keking.cn 想要使用
https://file.keking.cn/preview/来做预览，kkFileView部署在内网192.168.1.233服务器上，需要在nginx中添加反向代理如下

location /preview {
    proxy_pass 192.168.1.233:8012;
}

修改kkFileView的配置文件如下两项

server.context-path = /preview
base.url = https://file.keking.cn/preview

使用如下地址来访问预览页面

var url = 'https://file.keking.cn/file/test.txt'; //要预览文件的访问地址
window.open('https://file.keking.cn/preview/onlinePreview?url='+encodeURIComponent(url));

trust.host

说明：信任站点，设置了之后，会限制只能预览来自信任站点列表的文件，默认不限制，多个用','隔开， 默认值：未设置 示例：trust.host = file.keking.cn,kkfileview.keking.cn

simText

说明：用来配置预览方式为纯文本的文件类型
默认值：txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd

media

说明：用来配置预览方式为多媒体（视频、音频）的文件类型
默认值：mp3,wav,mp4,flv

office.preview.type

说明：office文件（doc、docx、ppt、pptx）、pdf 文件预览方式，默认为图片方式，预览时也有按钮相互切换，可选项：'image', 'pdf'

  • image: 默认预览方式，将office文件每一页后台转成图片，前台懒加载（只加载当前页面内容），推荐预览文件大且前台加载慢的时候使用
  • pdf: 统一转成pdf加一次加载，推荐内网访问，网速快时使用

office.preview.switch.disabled

说明：是否关闭office预览页面上的切换开关，默认不关闭
默认值：false

pdf.download.disable

说明：是否禁止下载转换生成的pdf文件，默认禁止
默认值：true

file.upload.disable

说明：是否禁用演示首页文件上传，默认不禁止
默认值：false

ftp.username

说明：预览url为FTP地址时，默认的ftp用户名，可过url参数中的ftp.username=xxx覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：null

ftp.password

说明：预览url为FTP地址时，默认的ftp密码，可过url参数中的ftp.password=xxx覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：null

ftp.control.encoding

说明：预览源为FTP时, FTP连接默认的ControlEncoding，根据FTP服务器的操作系统选择，Linux一般为设置UTF-8，Windows一般为设置GBK。可过url参数中的ftp.control.encoding=xxx覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：UTF-8

watermark.txt

默认水印内容，如需取消水印，内容设置为空即可，例如：watermark.txt = ${WATERMARK_TXT:}
默认值：''

watermark.x.space

水印x轴间隔
默认值：10

watermark.y.space

水印y轴间隔
默认值：10

watermark.font

水印字体
默认值：微软雅黑

watermark.fontsize

水印字体大小
默认值：18px

watermark.color

水印字体颜色
默认值：black

watermark.alpha

水印透明度，要求设置在大于等于0.005，小于1
默认值：0.2

watermark.width

水印宽度
默认值：180

watermark.height

水印高度 默认值：80

watermark.angle

水印倾斜度数，要求设置在大于等于0，小于90
默认值：10

常见问题

Q：怎么把这个项目集成到我的项目里

A：不需要集成，本项目只需要独立部署，向外提供http预览服务（外部系统只需要访问本项目预览接口并传入需要预览文件的url，就可以打开预览页面）

Q：怎么把这个项目放Tomcat里运行

A：不需要放进Tomcat里，编译好的发行包为zip包，直接解压运行一键启动脚本就可以完成部署（需要有java环境）具体部署步骤详见：部署指南

Q：预览并发问题&预览首次打开慢

A：可使用预览转码队列，将需要预览的文件url放入队列中，提前进行转码，本地访问接口为：
http://127.0.0.1:8012/addTask?url=http://xxx/test.txt (url参数为需要需要的文件访问地址)

Q：预览乱码

A：乱码问题可能有如下两个原因

  • 字体问题
    大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下： 下载如下字体包 http://kkfileview.keking.cn/fonts.zip 文件解压完整拷贝到Linux下的 /usr/share/fonts目录。然后依次执行mkfontscale 、mkfontdir 、fc-cache使字体生效
  • 编码问题

编码问题分为如下两方面

  1. Excel文件编码格式 Excel软件是可以选择用什么编码去保存文件的
    目前我们读取Eecel文件是用的服务器操作系统默认编码，可以通过在启动脚本里加入如-Dfile.encoding=UTF-8指定，详见 码云项目首页评论区讨论
  2. 生成html网页编码格式
    生成html网页也是用的服务器操作系统默认编码(java系统属性：sun.jnu.encoding)，比如用浏览器用手动更改编码格式为utf-8或gbk打开没有问题，但是用浏览器默认编码就有问题，此时可调整系统配置文件中的配置项converted.file.charset可解决此类乱码问题, 详见 编码配置

Q：Linux下运行startup.sh脚本报错：/bin/bash^M: bad interpreter: No such file or directory

A：一般为在Windows下用IDEA导入项目编译时，默认使用Windows(\r\n)下的文件换行符导致的，导入项目时设置默认换行符为Unix类操作系统换行符再编译即可（File->Settings->Editor->Code Style->Line separator 选择Unix and MacOs(\n)）

Q：Linux下启动项目后日志报错：org.artofsolving.jodconverter.office.OfficeException: office process died with exit code 127

A：操作系统缺少libXext.so.6包，请自行下载安装：
http://kkfileview.keking.cn/fonts.zip

Q：启动项目后日志报错：java.lang.IllegalStateException: a process with acceptString 'socket,host=127.0.0.1,port=8100' is already running; pid 26468

A：有正在运行的openoffice进程，kill掉相关进程再重新启动

Q：Windows系统下启动报错：Error creating bean with name 'cacheServiceRocksDBImpl'

A：本项目默认使用内嵌RocksDB存储引擎作缓存，需要以管理员身份运行，或配置使用其他缓存实现，详见：缓存配置

Q：如何水印文本内容动态传值

A：在预览url后面加上参数&watermarkTxt即可
例如：

var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url=' + encodeURIComponent(url) + '&watermarkTxt=' + encodeURIComponent('动态水印'));

Q：使用nginx代理时预览出现异常

A：一般是nginx和kkFileView配置有问题
例如nginx的访问地址为 https://file.keking.cn 想要使用
https://file.keking.cn/preview/来做预览，kkFileView部署在内网192.168.1.233服务器上，需要在nginx中添加反向代理如下：

location /preview {
    proxy_pass 192.168.1.233:8012;
}

修改kkFileView的配置文件如下两项

server.context-path = /preview
base.url = https://file.keking.cn/preview

使用如下地址来访问预览页面

var url = 'https://file.keking.cn/file/test.txt'; //要预览文件的访问地址
window.open('https://file.keking.cn/preview/onlinePreview?url='+encodeURIComponent(url));

Q：使用docker部署时如何指定配置文件中的配置项

A：针对docker运行的用户，所有配置项可以使用设置相应的环境变量来配置
环境变量的KEY为配置文件中每个配置项后${}中的KEY
例如，使用docker运行要指定base.url为http://file.keking.cn，docker运行命令如下

docker run -it -d -p 8012:8012 -e BASE_URL="http://file.keking.cn" keking/kkfileview:v2.2.1

Q：使用内网预览时没有问题，但是使用外网预览有问题

A：一般是公司网络使用的路由器不支持或没开启域内NAT，kkFileView无法通过外网地址下载要预览的文件
例如kkFileView部署在公司192.168.1.233服务器上，本地访问http://192.168.1.233:8012可以正常预览
公司运维把192.168.1.233的8012端口暴露到公网ip或域名(http://xxx.xxx.xxx:8012)，公网打首页也正常，但是预览就出错
这种一般是因为公司主路由器不支持或没开启域内NAT

预览展示

  • 文本预览


  • word文档预览

  • ppt文档预览

  • excel文档预览

  • 压缩文件预览

  • 多媒体文件预览

  • CAD文档预览

相关推荐

安全教育登录入口平台（安全教育登录入口平台官网）

122交通安全教育怎么登录:122交通网的注册方法是首先登录网址http://www.122.cn/，接着打开网页后，点击右上角的“个人登录”；其次进入邮箱注册，然后进入到注册页面，输入相关信息即可完...

大鱼吃小鱼经典版（大鱼吃小鱼经典版(经典版)官方版）

大鱼吃小鱼小鱼吃虾是于谦跟郭麒麟的《我的棒儿呢？》郭德纲说于思洋郭麒麟作诗的相声，最后郭麒麟做了一首，师傅躺在师母身上大鱼吃小鱼小鱼吃虾虾吃水水落石出师傅压师娘师娘压床床压地地动山摇。...

谷歌地球下载高清卫星地图（谷歌地球地图下载器）
  • 谷歌地球下载高清卫星地图（谷歌地球地图下载器）
  • 谷歌地球下载高清卫星地图（谷歌地球地图下载器）
  • 谷歌地球下载高清卫星地图（谷歌地球地图下载器）
  • 谷歌地球下载高清卫星地图（谷歌地球地图下载器）
哪个软件可以免费pdf转ppt（免费的pdf转ppt软件哪个好）
哪个软件可以免费pdf转ppt（免费的pdf转ppt软件哪个好）

要想将ppt免费转换为pdf的话，我们建议大家可以下一个那个wps，如果你是会员的话，可以注册为会员，这样的话，在wps里面的话，就可以免费将ppt呢转换为pdfpdf之后呢，我们就可以直接使用，不需要去直接不需要去另外保存，为什么格式转...

2026-02-04 09:03 off999

电信宽带测速官网入口（电信宽带测速官网入口app）

这个网站看看http://www.swok.cn/pcindex.jsp1.登录中国电信网上营业厅，宽带光纤，贴心服务，宽带测速2.下载第三方软件，如360等。进行在线测速进行宽带测速时，尽...

植物大战僵尸95版手机下载（植物大战僵尸95 版下载）

1可以在应用商店或者游戏平台上下载植物大战僵尸95版手机游戏。2下载教程：打开应用商店或者游戏平台，搜索“植物大战僵尸95版”，找到游戏后点击下载按钮，等待下载完成即可安装并开始游戏。3注意：确...

免费下载ppt成品的网站（ppt成品免费下载的网站有哪些）

1、Chuangkit（chuangkit.com）直达地址：chuangkit.com2、Woodo幻灯片（woodo.cn）直达链接：woodo.cn3、OfficePlus（officeplu...

2025世界杯赛程表（2025世界杯在哪个国家）

2022年卡塔尔世界杯赛程公布，全部比赛在卡塔尔境内8座球场举行，2022年，决赛阶段球队全部确定。揭幕战于当地时间11月20日19时进行，由东道主卡塔尔对阵厄瓜多尔，决赛于当地时间12月18日...

下载搜狐视频电视剧（搜狐电视剧下载安装）

搜狐视频APP下载好的视频想要导出到手机相册里方法如下1、打开手机搜狐视频软件，进入搜狐视频后我们点击右上角的“查找”，找到自已喜欢的视频。2、在“浏览器页面搜索”窗口中，输入要下载的视频的名称，然后...

pubg免费下载入口（pubg下载入口官方正版）
  • pubg免费下载入口（pubg下载入口官方正版）
  • pubg免费下载入口（pubg下载入口官方正版）
  • pubg免费下载入口（pubg下载入口官方正版）
  • pubg免费下载入口（pubg下载入口官方正版）
永久免费听歌网站（丫丫音乐网）

可以到《我爱音乐网》《好听音乐网》《一听音乐网》《YYMP3音乐网》还可以到《九天音乐网》永久免费听歌软件有酷狗音乐和天猫精灵，以前要跳舞经常要下载舞曲，我从QQ上找不到舞曲下载就从酷狗音乐上找，大多...

音乐格式转换mp3软件（音乐格式转换器免费版）

有两种方法：方法一在手机上操作：1、进入手机中的文件管理。2、在其中选择“音乐”，将显示出手机中的全部音乐。3、点击“全选”，选中所有音乐文件。4、点击屏幕右下方的省略号图标，在弹出菜单中选择“...

电子书txt下载（免费的最全的小说阅读器）

1.Z-library里面收录了近千万本电子书籍，需求量大。2.苦瓜书盘没有广告，不需要账号注册，使用起来非常简单，直接搜索预览下载即可。3.鸠摩搜书整体风格简洁清晰，书籍资源丰富。4.亚马逊图书书籍...

最好免费观看高清电影（播放免费的最好看的电影）

在目前的网上选择中，IMDb（互联网电影数据库）被认为是最全的电影网站之一。这个网站提供了各种类型的电影和电视节目的海量信息，包括剧情介绍、演员表、评价、评论等。其还提供了有关电影制作背后的详细信息，...

孤单枪手2简体中文版（孤单枪手2简体中文版官方下载）

要将《孤胆枪手2》游戏的征兵秘籍切换为中文，您可以按照以下步骤进行操作：首先，打开游戏设置选项，通常可以在游戏主菜单或游戏内部找到。然后，寻找语言选项或界面选项，点击进入。在语言选项中，选择中文作为游...

取消回复欢迎 你 发表评论:

一周热门
最近发表
标签列表
Copyright Your WebSite.Some Rights Reserved.