KKfile文件预览使用以及部署

1. 概述

KKfile文件预览是一款开源的文档在线预览项目。项目使用流行的spring boot搭建，易上手和部署，基本支持主流办公文档的在线预览，如doc,docx,Excel,pdf,txt,zip,rar,图片等等。

1. 项目特性

支持word excel ppt，pdf等办公文档

1. 支持txt,java,php,py,md,js,css等所有纯文本
2. 支持zip,rar,jar,tar,gzip等压缩包
3. 支持jpg，jpeg，png，gif等图片预览（翻转，缩放，镜像）
4. 支持mp3，mp4，flv等多媒体文件预览
5. 使用spring boot开发，预览服务搭建部署非常简便
6. rest接口提供服务，跨平台特性(java,php,python,go,php，....)都支持，应用接入简单方便
7. 支持普通http/https文件下载url、http/https文件下载流url、ftp下载url等多种预览源
8. 提供zip，tar.gz发行包，提供一键启动脚本和丰富的配置项，方便部署使用
9. 提供Docker镜像发行包，方便在容器环境部署
10. 抽象预览服务接口，方便二次开发，非常方便添加其他类型文件预览支持
11. 最最重要Apache协议开源，代码pull下来想干嘛就干嘛

 

1. 部署指南

1. 项目下载

可从码云中下载最新发行版本到本地：https://gitee.com/kekingcn/file-online-preview/releases

1. 将项目导入至IDEA。
2. 根据需求修改配置文件application.properties。具体参考文档：https://kkfileview.keking.cn/zh-cn/docs/config.html
3. 将项目打包放入linux服务器中，第一次打包可直接将生成的压缩包上传上去并解压。因为压缩包中包含了许多项目需要的配置文件以及启动命令，可以省去我们许多工作。

 

1. 项目启动：Windows下以管理员身份运行startup.bat，Linux以root用户运行startup.sh。如果不是root用户启动项目初始化启动时会失败。

1. 使用指南

当您的项目内需要预览文件时，只需要调用浏览器打开本项目的预览接口，并传入须要预览文件的url。

注意，如果要预览的url里包含需要转义的特殊字符，如下表格，请encodeURIComponent(url)转义

1. 1. 1. 普通文件下载url预览

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

1. 1. 2. http/https下载流url预览

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

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));

1. 1. 3. FTP下载url预览
      1. 1). FTP匿名访问

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

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

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

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

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

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

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

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));

1. Q&A
   1. 怎么把这个项目集成到我的项目里？

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

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

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

1. 1. 预览乱码

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

字体问题:
大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下： 将Windows下的C:\Windows\Fonts 目录下的文件完整拷贝到Linux下的 /usr/share/fonts/myfonts目录。然后依次执行mkfontscale 、mkfontdir 、fc-cache使字体生效(需要root用户权限)

编码问题:
编码问题分为如下两方面

Excel文件编码格式
Excel软件是可以选择用什么编码去保存文件的

目前我们读取Eecel文件是用的服务器操作系统默认编码，可以通过在启动脚本里加入如-Dfile.encoding=UTF-8指定，详见 码云项目首页评论区讨论

生成html网页编码格式
生成html网页也是用的服务器操作系统默认编码(java系统属性：sun.jnu.encoding)，比如用浏览器用手动更改编码格式为utf-8或gbk打开没有问题，但是用浏览器默认编码就有问题，此时可调整系统配置文件中的配置项converted.file.charset可解决此类乱码问题, 详见 编码配置

1. 1. 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)）

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

A：操作系统缺少libXext.so.6包，请自行下载安装：https://pkgs.org/download/libXext.so.6

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

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

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

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