kkfileview 文档在线预览项目解决方案

简介

万能的文件预览开源项目，基本支持主流文档格式预览. 官方文档

项目特性

使用spring boot开发，预览服务搭建部署非常简便
rest接口提供服务，跨平台特性(java,php,python,go,php，….)都支持，应用接入简单方便
支持普通http/https文件下载url、http/https文件下载流url、ftp下载url等多种预览源
提供zip，tar.gz发行包，提供一键启动脚本和丰富的配置项，方便部署使用
提供Docker镜像发行包，方便在容器环境部署
抽象预览服务接口，方便二次开发，非常方便添加其他类型文件预览支持

安装部署

环境要求

Java: 1.8+
jdk安装包下载需要注册/登录Oracle. (不翻墙会很卡，甚至打不开)
配置JDK环境变量
打开终端:打开访达,选择应用程序中的实用工具,双击打开终端，输入以下命令:
1
2
sudo nano /etc/paths
//点击Ctrl + X,选择Y保存修改.
查找文件目录 /Library/Java/JavaVirtualMachines/ 看一下目录jdk的版本号进入，直到找到bin目录，将bin目录的路径添加 nano /etc/paths内
写入/Library/Java/JavaVirtualMachines/jdk1.8.0_201.jdk/Contents/Home/bin

关闭终端.重新打开终端.输入命令: java -version 终端展示Java版本,代表安装成功.

LibreOffice或OpenOffice(Windows下已内置，CentOS或Ubuntu下会自动下载安装，MacOS下需要自行安装)

macOS:才需要安装LibreOffice或OpenOffice，CentOS或Ubuntu下会自动下载安装，MacOS下需要自行安装。
去官网下载安装即可 (都需要翻墙)
直接下载地址

部署运行

物理机或虚拟机上运行

从码云发行版本下载最新版发行包
解压kkFileView-x.x.x文件（Windows用.zip包，Linux/MacOS用.tar.gz包）
打开解压后文件夹的bin目录，运行startup脚本（Windows下以管理员身份运行startup.bat，Linux以root用户运行startup.sh）
浏览器访问本机8012端口 http://127.0.0.1:8012 即可看到项目演示用首页

Docker部署
拉取镜像

# 网络环境方便访问docker中央仓库
docker pull keking/kkfileview:4.1.0

# 网络环境不方便访问docker中央仓库
wget https://kkfileview.keking.cn/kkFileView-

运行

1	docker run -it -p 8012:8012 keking/kkfileview:4.1.0

浏览器访问容器8012端口 http://127.0.0.1:8012 即可看到项目演示用首页

编译处理

当环境安装好后，源码也进行了下载。如果需要进行一些调整，就要重新生成jar包：

需要安装maven(使用maven编译打包)
1
brew install maven
进入到源码根目录下进行编译打包：
1
2
cd file-online-preview
mvn clean package -DskipTests
生成的jar包在target目录下。

这时可以检测修改后生成的jar包是否正常运行。执行一下命令：

1	java -jar target/kkFileView-4.1.0.jar

浏览器访问 http://127.0.0.1:8012 即可看到项目演示用首页。

使用docker构建镜像
进入到源码根目录：
1
docker build -t keking/kkfileview:v4.3.0 .

当然如果不想重新生成镜像在启动容器，可以直接在远容器中通过：

1 2	#包编译好的jar包，发送到容器内，更换原容器jar名称（可在远名称后加.bak） docker cp target/kkFileView-4.1.0.jar 容器名称:/kkFileView-4.1.0.jar

然后启动容器. 也是可以完成更换启动。

使用指南

普通文件下载url预览

1
2
3

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

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

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

docker镜像构建

kkfileview源码内有两个dockerfile文件，分别是构建相关运行环境的基础镜像，后者则是根据基础镜像构建kkfileview镜像，包含了kkfileview运行所需的环境与相关处理的代码。
在kkfileview项目根目录下 file-online-preview-v4.4.0-beta/docker/kkfileview-jdk 执行：

1 2	# 执行如下命令构建基础镜像，加快kkfileview docker镜像构建与发布 docker build --tag keking/kkfileview-jdk:4.3.0 .

运行的是以下dockerfile文件，期内安装ubuntu，字体，java环境，libreoffice，并设置环境变量。重而生成一个新镜像，命名为 keking/kkfileview-jdk:4.3.0

FROM ubuntu:20.04

# 内置一些常用的中文字体，避免普遍性乱码
COPY fonts/* /usr/share/fonts/chinese/
RUN apt-get clean && apt-get update &&\
	sed -i 's/http:\/\/archive.ubuntu.com/https:\/\/mirrors.aliyun.com/g' /etc/apt/sources.list &&\
	sed -i 's/# deb/deb/g' /etc/apt/sources.list &&\
	apt-get install -y --reinstall ca-certificates &&\
	apt-get clean && apt-get update &&\
	apt-get install -y locales language-pack-zh-hans &&\
	localedef -i zh_CN -c -f UTF-8 -A /usr/share/locale/locale.alias zh_CN.UTF-8 && locale-gen zh_CN.UTF-8 &&\
    export DEBIAN_FRONTEND=noninteractive &&\
	apt-get install -y tzdata && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime &&\
	apt-get install -y fontconfig ttf-mscorefonts-installer ttf-wqy-microhei ttf-wqy-zenhei xfonts-wqy &&\
	apt-get install -y wget &&\
    cd /tmp &&\
	wget https://kkview.cn/resource/server-jre-8u251-linux-x64.tar.gz &&\
	tar -zxf /tmp/server-jre-8u251-linux-x64.tar.gz && mv /tmp/jdk1.8.0_251 /usr/local/ &&\

# 安装 libreoffice
    apt-get install -y libxrender1 libxinerama1 libxt6 libxext-dev libfreetype6-dev libcairo2 libcups2 libx11-xcb1 libnss3 &&\
    wget https://downloadarchive.documentfoundation.org/libreoffice/old/7.5.3.2/deb/x86_64/LibreOffice_7.5.3.2_Linux_x86-64_deb.tar.gz -cO libreoffice_deb.tar.gz &&\
    tar -zxf /tmp/libreoffice_deb.tar.gz && cd /tmp/LibreOffice_7.5.3.2_Linux_x86-64_deb/DEBS &&\
    dpkg -i *.deb &&\

#  清理临时文件
	rm -rf /tmp/* && rm -rf /var/lib/apt/lists/* &&\
    cd /usr/share/fonts/chinese &&\
    mkfontscale &&\
    mkfontdir &&\
    fc-cache -fv

ENV JAVA_HOME /usr/local/jdk1.8.0_251
ENV CLASSPATH $JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
ENV PATH $PATH:$JAVA_HOME/bin
ENV LANG zh_CN.UTF-8
ENV LC_ALL zh_CN.UTF-8
CMD ["/bin/bash"]

然后基于基础镜像，构建kkfileview镜像，在 file-online-preview-v4.4.0-beta/dockerfiles 执行：

1 2	# 执行如下命令构建kkfileview镜像 docker build -t keking/kkfileview:v4.4.0 .

运行的是以下dockerfile文件，也让懒猫第一次知道原来镜像的构建，还能基于基础镜像进行定制化构建。学到一手。

FROM keking/kkfileview-jdk:latest
ADD server/target/kkFileView-*.tar.gz /opt/
ENV KKFILEVIEW_BIN_FOLDER /opt/kkFileView-4.4.0-beta/bin
ENTRYPOINT ["java","-Dfile.encoding=UTF-8","-Dspring.config.location=/opt/kkFileView-4.4.0-beta/config/application.properties","-jar","/opt/kkFileView-4.4.0-beta/bin/kkFileView-4.4.0-beta.jar"]

注意：docker镜像的构建需要连接到相关镜像源，当前国内很多镜像源都挂了，导致很多时候都无法构建，需要多找找可用的镜像源。懒猫分享了下自己用的镜像源在docker系列捏，需要的可以参考下。

常见问题

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

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

预览乱码

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

字体问题
大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下：下载如下字体包 https://kkfileview.keking.cn/fonts.zip 文件解压完整拷贝到Linux下的 /usr/share/fonts目录。然后依次执行mkfontscale 、mkfontdir 、fc-cache使字体生效
生成html网页编码格式
生成html网页也是用的服务器操作系统默认编码(java系统属性：sun.jnu.encoding)，比如用浏览器用手动更改编码格式为utf-8或gbk打开没有问题，但是用浏览器默认编码就有问题，此时可调整系统配置文件中的配置项converted.file.charset可解决此类乱码问题

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

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

1
2
3

location /preview {
    proxy_pass 192.168.1.233:8012;
}

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

1 2	server.servlet.context-path = /preview base.url = https://file.kkview.cn/preview

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

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

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