前言

在日常工作或开发中，我们经常会遇到这样的困扰：对方发来一个文档，打开后排版乱了；或者想在网页上直接看文件内容，却总是要下载到本地。kkFileView就是专门解决这些问题的工具——它是一个开源的文档在线预览解决方案，简单说，你把它部署到服务器上，就能通过网址直接预览各种格式的文件，从Word、Excel、PPT到图片、PDF，甚至压缩包都能搞定。这篇文章会从最基础的部分开始，带你一步步在自己的服务器上把这个服务跑起来。

一、准备工作

1.1 准备一台具备公网IP的云服务器（推荐使用雨云）

优惠注册地址：https://www.rainyun.com/sn_

使用优惠码：sn

注: 使用优惠码注册后绑定微信可领取5折优惠券

服务器选购步骤：

1. 注册后，在"总览"页面找到"云服务器"入口，进入后点击"购买云服务器"
   ​
   2.根据需求选择合适的配置，建议选择国内的服务器，访问更快，选好后点击立即购买即可
   
   3.选好后进入控制台，使用SSH客户端远程连接服务器即可，SSH客户端建议选择FinalShell

1.2 检查Java环境

kkFileView依赖Java环境运行。登录你的服务器，输入下面这行命令看看Java装了没有：

java -version

如果看到类似下面的输出，说明Java已经存在：

openjdk version "1.8.0_xxx"

如果提示“command not found”，则需要先安装Java。根据你的系统选择对应命令：

CentOS系统：

sudo yum install -y java-1.8.0-openjdk-devel

Ubuntu/Debian系统：

sudo apt update
sudo apt install -y openjdk-8-jdk

装完之后再用java -version确认一下。

二、两种部署方式选择

kkFileView的部署主要有两条路：Docker方式和传统包方式。打个比方，Docker就像住酒店——拎包入住、省心省力；传统方式则像自己装修——灵活可控但步骤多。我建议新手直接选Docker，十分钟就能搞定。

对比项	Docker方式	传统包方式
上手难度	★☆☆☆☆	★★★☆☆
部署耗时	约5-10分钟	约15-30分钟
依赖处理	自动搞定	需要手动安装LibreOffice
适合人群	所有人	需要定制配置的进阶用户

方案一：Docker部署（推荐）

2.1 安装Docker

如果服务器上还没有Docker，执行下面的命令一键安装：

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

安装完成后，把当前用户加入docker组，这样就不用每次输sudo了：

sudo usermod -aG docker $USER

注意： 执行完这条命令后，需要退出并重新登录服务器才会生效。

2.2 拉取并运行镜像

从镜像仓库拉取kkFileView的镜像：

docker pull keking/kkfileview:4.1.0

拉取完成后，启动容器：

docker run -d -p 8012:8012 --name kkfileview keking/kkfileview:4.1.0

命令解释：

• -d：后台运行
• -p 8012:8012：把服务器的8012端口映射到容器的8012端口
• --name kkfileview：给容器起个名字，方便后续管理

2.3 验证是否成功

执行docker ps，看到容器状态是“Up”就说明跑起来了。然后用浏览器访问 http://你的服务器IP:8012，如果看到一个文件上传的测试页面，恭喜你，部署成功了。

方案二：传统包部署

如果你选择传统方式，需要自己下载部署包并手动配置。

2.4 下载并解压

进入你想安装的目录（比如/opt），下载kkFileView包。需要注意，从4.1.0版本开始官方不再免费提供发行包，建议使用4.0.0版本：

cd /opt
# 下载4.0.0版本（最后一个免费版本）
wget -O kkFileView-4.0.0.tar.gz "https://pan.baidu.com链接需要自行获取" 
# 或从其他镜像源下载

解压文件：

tar -zxvf kkFileView-4.0.0.tar.gz

2.5 启动服务

进入解压后的目录，执行启动脚本：

cd kkFileView-4.0.0/bin
./startup.sh

首次启动时，系统会自动下载并安装LibreOffice（文档转换的依赖），这个过程可能需要几分钟，耐心等待即可。

查看启动日志确认是否成功：

./showlog.sh

看到类似“Started ServerMain in x.xxx seconds”的日志就说明启动成功了。

三、让服务真正可用

服务启动后，还有两件重要的事情要做：安装字体和放行端口。

3.1 安装中文字体包

如果你不装中文字体，预览含中文的文档时就会出现一堆乱码或者方框。执行以下命令下载并安装字体：

# 进入字体目录
cd /usr/share/fonts
# 下载字体包
wget http://kkfileview.keking.cn/fonts.zip
# 解压
unzip fonts.zip
# 刷新字体缓存
mkfontscale
mkfontdir
fc-cache

如果你的服务器没有wget或unzip命令，先用yum install -y wget unzip或apt install -y wget unzip安装。

Docker用户的特殊情况： 如果你用的是Docker部署，需要进入容器内部执行字体安装：

# 进入容器
docker exec -it kkfileview /bin/bash
# 在容器内执行上面的字体安装命令
# 完成后退出容器
exit

装完字体后，重启一下kkFileView让配置生效：

# Docker方式
docker restart kkfileview

# 传统方式
./shutdown.sh
./startup.sh

3.2 开放服务器端口

云服务器默认只开了几个常用端口，8012需要手动放行。去你的云服务商控制台，找到“安全组”或“防火墙”设置，添加入站规则：端口填8012，来源填0.0.0.0/0（允许所有IP访问）。

如果你用的是宝塔面板，在“安全”菜单里添加端口放行即可。

四、接入你的项目使用

服务跑起来之后，怎么在自己的网站或应用里调用呢？非常简单。

4.1 核心调用方式

kkFileView提供了一个预览接口，你需要做两件事：

1. 把要预览的文件URL进行Base64编码
2. 把编码后的字符串拼接到预览地址后面

JavaScript示例：

// 要预览的文件地址
const fileUrl = "https://你的域名/文档.docx";

// 引入Base64编码库（在HTML中）
// <script src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

// 编码并拼接
const previewUrl = "http://你的服务器IP:8012/onlinePreview?url=" + encodeURIComponent(Base64.encode(fileUrl));

// 在新窗口打开预览
window.open(previewUrl);

Vue项目中使用：

npm install --save js-base64

<template>
  <iframe :src="previewUrl" width="100%" height="600px"></iframe>
</template>

<script setup>
import { Base64 } from 'js-base64';

const fileUrl = "https://你的域名/文件.pdf";
const previewUrl = "http://你的服务器IP:8012/onlinePreview?url=" + encodeURIComponent(Base64.encode(fileUrl));
</script>

写在最后

到这里，你应该已经成功搭建了一个属于自己的文档预览服务。整个过程下来，你会发现并没有想象中那么复杂——尤其是Docker方式，基本上就是几条命令的事。

如果你在部署过程中遇到了本文没提到的问题，可以去kkFileView的官方文档或者GitHub仓库看看，开源社区的维护者们通常都会及时回复问题。最后提醒一句，正式使用时建议用Nginx反向代理加上域名访问，既方便又安全。