简介

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

项目特性

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

安装部署

环境要求

  1. 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版本,代表安装成功.

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

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

部署运行

  1. 物理机或虚拟机上运行
  • 码云发行版本 下载最新版发行包
  • 解压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 即可看到项目演示用首页
  1. Docker部署
    拉取镜像
    1
    2
    3
    4
    5
    # 网络环境方便访问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包:

  1. 需要安装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 即可看到项目演示用首页。

  1. 使用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

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

使用指南

  1. 普通文件下载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)));
  1. http/https下载流url预览
    很多系统内不是直接暴露文件下载地址,而是请求通过id、code等参数到通过统一的接口,后端通过id或code等参数定位文件,再通过OutputStream输出下载,此时下载url是不带文件后缀名的,预览时需要拿到文件名,传一个参数fullfilename=xxx.xxx来指定文件名,示例如下
    1
    2
    3
    4
    5
    <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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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文件,也让懒猫第一次知道原来镜像的构建,还能基于基础镜像进行定制化构建。学到一手。

1
2
3
4
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

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

1
2
3
4
<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)));