利用 kkFileView 实现在线预览文件

官方文档
KK 开源社区

Docker 容器环境运行

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

源码运行

1. 下载源码

# gitee
https://gitee.com/kekingcn/file-online-preview.git
# github
https://github.com/kekingcn/kkFileView.git

2. 运行

# 进入 kkFileView 目录
cd file-online-preview/server/src/main/java/cn.keking/serverMain
# 运行
main

3. 制作Docker镜像

cd docker/kkfileview-base
docker build --tag keking/kkfileview-base:5.0.0 .

cd ../..
docker build --tag keking/kkfileview:5.0.0 .

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

docker save -o kkfileview-5.0.0.tar keking/kkfileview:5.0.0

配置文件

file-online-preview/server/src/main/config/application.properties

###############################################################################
# 一、服务器基础配置（需要重启生效）
###############################################################################

# 服务器端口号，默认8012
# 可以通过环境变量 KK_SERVER_PORT 覆盖
server.port = ${KK_SERVER_PORT:8012}

# 应用上下文路径，默认为根路径 /
# 可以通过环境变量 KK_CONTEXT_PATH 覆盖
server.servlet.context-path = ${KK_CONTEXT_PATH:/}

# 字符编码设置，统一使用UTF-8
server.servlet.encoding.charset = utf-8

# 启用响应压缩，减少网络传输
server.compression.enabled = true
server.compression.min-response-size = 2048
server.compression.mime-types = application/javascript,text/css,application/json,application/xml,text/html,text/xml,text/plain,font/woff,application/font-woff,font/eot,image/svg+xml,image/x-icon

# 文件上传大小限制，默认500MB
# 注意：需要同时设置spring.servlet.multipart.max-file-size和max-request-size
spring.servlet.multipart.max-file-size = 500MB
spring.servlet.multipart.max-request-size = 500MB

# FreeMarker模板引擎配置
spring.freemarker.template-loader-path = classpath:/web/
spring.freemarker.cache = false
spring.freemarker.charset = UTF-8
spring.freemarker.check-template-location = true
spring.freemarker.content-type = text/html
spring.freemarker.expose-request-attributes = true
spring.freemarker.expose-session-attributes = true
spring.freemarker.request-context-attribute = request
spring.freemarker.suffix = .ftl

# Spring Boot Actuator监控端点配置
management.endpoints.web.exposure.include = health,info,metrics
management.endpoint.health.show-details = always
management.health.defaults.enabled = true


###############################################################################
# 二、Office文档处理配置（部分支持动态配置）
###############################################################################

# Office组件安装路径，默认为自动查找
# Windows示例（注意双反斜杠）：C:\\Program Files (x86)\\OpenOffice 4
# Linux示例：/opt/libreoffice
# MacOS示例：/Applications/LibreOffice.app/Contents
office.home = ${KK_OFFICE_HOME:default}

# Office组件服务端口，支持多个端口实现负载均衡
office.plugin.server.ports = 2001,2002

# Office组件任务超时时间，默认5分钟
office.plugin.task.timeout = 5m

# 每个进程最大任务数，防止内存溢出
office.plugin.task.maxtasksperprocess = 200

# 任务执行超时时间，默认5分钟
office.plugin.task.taskexecutiontimeout = 5m

# Office文档分页范围，支持动态配置
# 默认false，开启后可以指定转换的页面范围
office.pagerange = ${KK_OFFICE_PAGERANGE:false}

# Office文档水印功能，支持动态配置
# 默认false，开启后会在Office文档上添加水印
office.watermark = ${KK_OFFICE_WATERMARK:false}

# Office图片质量，1-100，默认80
# 值越高图片质量越好，但文件越大
office.quality = ${KK_OFFICE_QUALITY:80}

# Office图片最大分辨率，默认150
# 控制生成图片的最大分辨率
office.maximageresolution = ${KK_OFFICE_MAXIMAGERESOLUTION:150}

# 导出Office书签，支持动态配置
# 默认true，转换PDF时保留书签
office.exportbookmarks = ${KK_OFFICE_EXPORTBOOKMARKS:true}

# 是否将Office文档中的批注作为PDF注释导出，默认为true（导出）
# 保留批注便于文档审阅
office.exportnotes = ${KK_OFFICE_EXPORTNOTES:true}

# 加密文档生成的PDF是否添加密码，默认为true（添加）
# 密码为原始加密文档的密码，增强文档安全性
office.documentopenpasswords = ${KK_OFFICE_DOCUMENTOPENPASSWORD:true}

# Excel文档(xlsx)的前端解析方式，默认为web（Web端解析）
# web: 使用前端SheetJS库解析，减轻服务器压力
# image: 服务器转换为图片，兼容性更好
office.type.web = ${KK_OFFICE_TYPE_WEB:web}

# Office文档预览类型
# 支持动态配置，可选值：image/pdf，默认使用pdf模式
office.preview.type = ${KK_OFFICE_PREVIEW_TYPE:pdf}

# 是否关闭Office预览模式切换开关，默认为true（关闭切换）
# 设置为false时，用户可以在图片和PDF模式间切换
office.preview.switch.disabled = ${KK_OFFICE_PREVIEW_SWITCH_DISABLED:true}


###############################################################################
# 三、CAD文件处理配置（支持动态配置）
###############################################################################

# CAD文件预览类型
#   svg: 转换为SVG矢量格式（缩放不失真）
#   pdf: 转换为PDF格式（便于打印和标注）
cad.preview.type = ${KK_CAD_PREVIEW_TYPE:svg}

# Cad转换模块设置(aspose-cad=1 ,cadviewer=3) 
# aspose-cad 默认集成到系统,但是特别吃服务器性能  (支持转换格式为 svg、pdf)
# cadviewer 下载地址 https://cadviewer.com/alldownloads/autoxchange/ 更具自己系统下载转换包(支持转换格式为 svg、svgz、pdf)
# 1=aspose-cad  转换格式为 pdf,svg,tif   支持类型最多
# 2=cadviewer   转换格式为 pdf,svg  支持的类型 dwg  dxf  dwf
cad.conversionmodule = 1

# Cad 后端转换包路径 （linux 严格注意大小写）
# cadviewer windows 修改名称为 cadviewer.exe   inux修改名称为  cadviewer   需要安装字体 
# cadviewer 字体下载 https://cadviewer.com/downloads/fonts/fonts.tar.gz  放在 cad.file.path 目录里面的fonts.
cad.cadconverterpath  = false


# CAD文件处理线程数
cad.thread = ${KK_CAD_THREAD:5}

# CAD文件处理超时时间（秒）
cad.timeout = ${KK_CAD_TIMEOUT:90}


###############################################################################
# 四、PDF文件处理配置（支持动态配置）
###############################################################################

# 是否禁止PDF演示模式，默认为true（禁止）
pdf.presentationMode.disable = ${KK_PDF_PRESENTATION_MODE_DISABLE:true}

# 是否禁止PDF文件菜单中的"打开文件"选项，默认为true（禁止）
pdf.openFile.disable = ${KK_PDF_OPEN_FILE_DISABLE:true}

# 是否禁止PDF打印功能，默认为true（禁止）
pdf.print.disable = ${KK_PDF_PRINT_DISABLE:true}

# 是否禁止PDF下载功能，默认为true（禁止）
pdf.download.disable = ${KK_PDF_DOWNLOAD_DISABLE:true}

# 是否禁止PDF书签/大纲功能，默认为true（禁止）
pdf.bookmark.disable = ${KK_PDF_BOOKMARK_DISABLE:true}

# 是否禁止PDF编辑功能（注释、表单等），默认为false（允许编辑）
pdf.disable.editing = ${KK_PDF_DISABLE_EDITING:false}

# PDF处理最大线程数，控制并发处理能力
pdf.max.threads = 10

# PDF处理超时配置
pdf.timeout.small = 90
pdf.timeout.medium = 180
pdf.timeout.large = 300
pdf.timeout.xlarge = 600

# PDF智能DPI优化
# 是否启用PDF DPI智能调整，默认为true（启用）
# 根据PDF页数自动调整DPI，平衡清晰度和性能
pdf.dpi.enabled = true

# PDF转图片的基准DPI，默认为144
# 当DPI优化禁用时使用此值
pdf2jpg.dpi = ${KK_PDF2JPG_DPI:144}

# 智能DPI分级配置
# 小文件（0-50页）：150 DPI（高质量）
pdf.dpi.small = 150
# 中等文件（50-100页）：120 DPI（平衡质量与性能）
pdf.dpi.medium = 120
# 大文件（100-200页）：96 DPI（优化性能）
pdf.dpi.large = 96
# 超大文件（200-500页）：72 DPI（快速转换）
pdf.dpi.xlarge = 72
# 巨量文件（>500页）：72 DPI（最小资源消耗）
pdf.dpi.xxlarge = 72


###############################################################################
# 五、TIF文件处理配置（支持动态配置）
###############################################################################

# TIF文件预览类型
#   tif: 使用前端Tiff.js插件直接浏览（需要浏览器支持）
#   jpg: 服务器转换为JPG格式后显示
#   pdf: 服务器转换为PDF格式显示
tif.preview.type = ${KK_TIF_PREVIEW_TYPE:tif}

# TIF文件处理线程数
tif.thread = 5

# TIF文件处理超时时间（秒）
tif.timeout = 90


###############################################################################
# 六、媒体文件处理配置（支持动态配置）
###############################################################################

# 媒体文件类型（音频、视频）
media = ${KK_MEDIA:mp3,wav,mp4,flv,mpd,m3u8,ts,mpeg,m4a}

# 需要转换的媒体文件类型
convertMedias = ${KK_CONVERTMEDIAS:avi,mov,wmv,mkv,3gp,rm,mpeg}

# 媒体文件超时控制
media.timeout.enabled = true
media.small.file.timeout = 30
media.medium.file.timeout = 60
media.large.file.timeout = 180
media.xl.file.timeout = 300
media.xxl.file.timeout = 600
media.xxxl.file.timeout = 1200

# 媒体文件转换最大大小（MB）
media.convert.max.size = 300

# 是否禁用视频格式转换功能，默认为false（禁用）
# ⚠️ 重要：视频转换非常消耗CPU和内存资源
media.convert.disable = ${KK_MEDIA_CONVERT_DISABLE:false}


###############################################################################
# 七、文件存储与缓存配置（支持动态配置）
###############################################################################

# 预览生成资源的存储路径，默认为应用根路径下的file目录
# Windows示例：D:\\kkFileview\\（注意双反斜杠）
# Linux示例：/opt/kkfileview/file/
# 重要：确保应用有该目录的读写权限
file.dir = ${KK_FILE_DIR:default}

# 允许预览的本地文件夹路径，默认为default（禁止所有本地文件预览）
# ⚠️ 安全警告：配置此路径可能允许访问系统文件，请谨慎配置
# Windows示例（注意前面加反斜杠）：\D:\\kkFileview\\1\\1.txt
# Linux示例（注意前面加正斜杠）：/opt/1.txt
# 使用file协议访问：file://d:/1/1.txt（Windows）或 file:/opt/1/1.txt（Linux）
local.preview.dir = ${KK_LOCAL_PREVIEW_DIR:default}

# 是否启用缓存，支持动态配置
# 默认true，开启缓存提高性能
cache.enabled = ${KK_CACHE_ENABLED:true}

# 缓存实现类型，默认为jdk（使用JDK内置对象实现）
# 可选值：
#   jdk: JDK内置ConcurrentHashMap，单机部署推荐
#   redis: Redis分布式缓存，集群部署推荐
#   default: 内嵌RocksDB，支持持久化
cache.type = ${KK_CACHE_TYPE:jdk}

# Redis部署模式，默认为single（单机模式）
# 可选值：
#   single: 单机模式（默认）
#   cluster: 集群模式
#   sentinel: 哨兵模式（高可用）
#   master-slave: 主从模式
spring.redisson.mode = single
# Redis连接地址，支持多种格式：
# 单机模式：redis://127.0.0.1:6379
# 集群模式：redis://node1:6379,redis://node2:6379,redis://node3:6379
# 哨兵模式：redis://sentinel1:26379,redis://sentinel2:26379
spring.redisson.address = ${KK_SPRING_REDISSON_ADDRESS:redis://127.0.0.1:6379}
# Redis连接密码，无密码时留空
spring.redisson.password = ${KK_SPRING_REDISSON_PASSWORD:}
# Redis数据库索引，默认为0（0-15）
# 不同业务可使用不同数据库隔离
spring.redisson.database = ${KK_SPRING_REDISSON_DATABASE:0}

# 缓存清理配置
# 是否启用缓存自动清理，默认为true（启用）
# 定期清理过期缓存，避免磁盘空间无限增长
cache.clean.enabled = ${KK_CACHE_CLEAN_ENABLED:true}
# 缓存自动清理时间，使用Quartz cron表达式，默认为每天凌晨3点执行
# 表达式格式：秒 分 时 日 月 周 年（可选）
# 0 0 3 * * ? 表示每天3:00:00执行清理
cache.clean.cron = ${KK_CACHE_CLEAN_CRON:0 0 3 * * ?}


###############################################################################
# 八、安全与访问控制配置（支持动态配置）
###############################################################################

# 提供预览服务的地址，默认从请求url读，如果使用nginx等反向代理，需要手动设置
# base.url = https://file.keking.cn
base.url = ${KK_BASE_URL:default}

# 信任站点白名单配置，多个用','隔开
# ⚠️ 安全提示：为防止SSRF攻击，强烈建议配置信任主机白名单
# ⚠️ 如果不配置，系统将默认拒绝所有外部文件预览请求
# 配置示例：
# trust.host = kkview.cn,yourdomain.com,cdn.example.com
# 如果需要允许所有域名（不推荐，仅用于测试环境），请设置为：
# trust.host = *
# 当前配置：默认本机测试 （正式启用请修改）
trust.host = ${KK_TRUST_HOST:default}

# 不信任站点黑名单配置，多个用逗号隔开
# 黑名单优先级高于白名单，设置后将禁止预览来自这些站点的文件
# 建议配置：禁止访问内网地址和本地地址，防止内部信息泄露
# 配置示例：
# not.trust.host = localhost,127.0.0.1,0.0.0.0,192.168.*,10.*,172.16.*,172.17.*,172.18.*,172.19.*,172.20.*,172.21.*,172.22.*,172.23.*,172.24.*,172.25.*,172.26.*,172.27.*,172.28.*,172.29.*,172.30.*,172.31.*
not.trust.host = ${KK_NOT_TRUST_HOST:default}

# 禁止访问的文件类型，安全限制
# 支持动态配置，格式：exe,dll,dat
prohibit = ${KK_PROHIBIT:exe,dll,dat}

# 是否忽略SSL证书验证，默认为true（忽略）
# 用于开发环境或自签名证书场景
# 生产环境建议设置为false，启用完整的证书验证
kk.ignore.ssl = false

# 是否启用URL重定向功能，默认为true（启用）
# 用于处理文件下载、外部资源引用等场景
kk.enable.redirect = false


###############################################################################
# 九、水印配置（支持动态配置）
###############################################################################

# 水印文本内容
# 可以通过环境变量 WATERMARK_TXT 覆盖
watermark.txt = ${WATERMARK_TXT:}

# 水印X轴间距
# 可以通过环境变量 WATERMARK_X_SPACE 覆盖
watermark.x.space = ${WATERMARK_X_SPACE:10}

# 水印Y轴间距
# 可以通过环境变量 WATERMARK_Y_SPACE 覆盖
watermark.y.space = ${WATERMARK_Y_SPACE:10}

# 水印字体
# 可以通过环境变量 WATERMARK_FONT 覆盖
watermark.font = ${WATERMARK_FONT:微软雅黑}

# 水印字体大小
# 可以通过环境变量 WATERMARK_FONTSIZE 覆盖
watermark.fontsize = ${WATERMARK_FONTSIZE:18px}

# 水印颜色
# 可以通过环境变量 WATERMARK_COLOR 覆盖
watermark.color = ${WATERMARK_COLOR:black}

# 水印透明度，0.0-1.0
# 可以通过环境变量 WATERMARK_ALPHA 覆盖
watermark.alpha = ${WATERMARK_ALPHA:0.2}

# 水印宽度
# 可以通过环境变量 WATERMARK_WIDTH 覆盖
watermark.width = ${WATERMARK_WIDTH:180}

# 水印高度
# 可以通过环境变量 WATERMARK_HEIGHT 覆盖
watermark.height = ${WATERMARK_HEIGHT:80}

# 水印旋转角度
# 可以通过环境变量 WATERMARK_ANGLE 覆盖
watermark.angle = ${WATERMARK_ANGLE:10}


###############################################################################
# 十、FTP文件访问配置（支持动态配置）
###############################################################################

# FTP模块设置
# 预览源为FTP时，可在ftp url后面加参数?ftp.username=ftpuser&ftp.password=123456&ftp.control.encoding=GBK,指定,不指定默认用配置的 (为了安全我们强烈建议在配置中设置相关信息)
# ftp.control.encodin (根据FTP服务器操作系统选择，Linux一般为UTF-8，Windows一般为GBK)
# 使用方法,支持,分割第一个是域名或者IP地址后面是用户名在后面是密码,在后面是编码(用户名密码和编码用:分割, 域名用,分割),切记url不需要任何协议头
# ftp.username = 地址:端口:用户名:密码:编码,192.168.0.2:21:name:123456:UTF-8,www.xxx.com:21:admin:pass:UTF-8  多客户端,分割
# ftp.username =10.99.1.2:21:666:88888:GBK
ftp.username = false


###############################################################################
# 十一、首页与文件管理配置（支持动态配置）
###############################################################################

# 是否禁用首页文件上传功能，默认为true（禁用）
# 设置为true可关闭上传功能，仅用于预览
file.upload.disable = true

# 网站备案信息，显示在首页底部，默认为空
beian = ${KK_BEIAN:default}

# 首页初始化加载的页码，默认为1（第一页）
home.pagenumber = ${DEFAULT_HOME_PAGENUMBER:1}

# 首页每页显示的文件数量，默认为20
home.pagesize = ${DEFAULT_HOME_PAGSIZE:20}

# 文件删除验证配置
# 是否启用验证码验证删除文件，默认为false（不启用）
# 启用后删除文件需要输入验证码，防止误删
delete.captcha = ${KK_DELETE_CAPTCHA:false}

# 删除文件密码，默认为123456
delete.password = ${KK_DELETE_PASSWORD:123456}

# 是否删除转换后的源文件，默认为true（删除）
# 启用可节约磁盘空间，但会丢失原始文件
delete.source.file = ${KK_DELETE_SOURCE_FILE:true}


###############################################################################
# 十二、权限与认证配置（支持动态配置）
###############################################################################

# 是否启用图片预览权限，默认为true（启用）
# 设置为false可禁用所有图片预览功能
kk.Picturespreview = true

# 是否启用跨域文件获取权限，默认为true（启用）
kk.Getcorsfile = true

# 是否启用添加异步任务权限，默认为true（启用）
# 大文件转换通常使用异步任务处理
kk.addTask = true

# API密钥功能，默认为false（禁用）
# 启用后需要提供密钥才能调用API
kk.key = false

# AES加密密钥，必须为16位字符
# 启用AES加密时，接入方需使用相同的密钥
# 用于敏感数据传输加密
aes.key = 1234567890123456

# Basic认证配置，格式：域名:用户名:密码，多个用逗号分隔
# 用于保护特定域名的访问
# 示例：192.168.0.1:admin:pass123,example.com:user:pass456
basic.name = false

# User-Agent验证字符串，默认不启用
# 可用于简单的客户端验证
useragent = false


###############################################################################
# 十三、高级功能与兼容性配置（支持动态配置）
###############################################################################

# 异步配置刷新定时时间（秒）
kk.refreshschedule = 2

# 首页是否显示AES密钥 默认为false（禁用）
kk.isshowaeskey = false

# 是否允许XLSX编辑
kk.xlsxallowedit = false

# 是否显示XLSX工具栏
kk.xlsxshowtoolbar = false

# 首页是否显示key密钥 默认为false（禁用）
kk.isshowkey = false

# 预览html文件 是否启用JavaScript 默认为true（启用）
kk.scriptjs = true


###############################################################################
# 十四、文件类型分类配置（支持动态配置）
###############################################################################

# 纯文本文件类型，直接显示
simText = ${KK_SIMTEXT:txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd}

前端使用

普通文件地址预览

适用于系统已经直接暴露出可下载文件地址的情况。前端只需要编码后打开新窗口。

var url = 'http://127.0.0.1:8080/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(base64Encode(url)));

流式接口预览

很多业务系统通过 fileId、code 等参数走统一下载接口，此时原始 URL 没有后缀名，需要额外指定完整文件名。

var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1';
var previewUrl = originUrl + '&fullfilename=test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

FTP 资源预览

FTP 如果允许匿名访问，可以直接预览；如果需要认证，则把连接参数拼到 URL 后面传入。

// 匿名 FTP
var url = 'ftp://127.0.0.1/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(url)));

// 认证 FTP
var originUrl = 'ftp://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?ftp.control.port=21&ftp.username=admin&ftp.password=123456&ftp.control.encoding=utf8';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

带 Basic 鉴权的 HTTP 资源

如果文件源本身需要用户名和密码，可以直接把 Basic 鉴权参数拼到地址中，再交给 kkFileView。

var originUrl = 'http://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?basic.name=admin&basic.pass=123456';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

前后端同秘钥加密接入

如果不希望明文传递原始文件地址，可以在前端先做 AES 加密，再通过 encryption=aes 告知服务端按 AES 方式解密。

<script src="https://file.kkview.cn/js/crypto-js.js"></script>
<script src="https://file.kkview.cn/js/aes.js"></script>

function aesEncrypt(encryptString, key) {
  var keyBytes = CryptoJS.enc.Utf8.parse(key);
  var srcs = CryptoJS.enc.Utf8.parse(encryptString);
  var encrypted = CryptoJS.AES.encrypt(srcs, keyBytes, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  });
  return encrypted.toString();
}

var key = '1234567890123456';
var url = 'http://127.0.0.1/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(aesEncrypt(url, key)) + '&encryption=aes');

常见问题

预览乱码

大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下：

• 下载字体包 https://kkview.cn/resource/fonts.zip
• 文件解压完整拷贝到Linux下的 /usr/share/fonts 目录。
• 然后依次执行以下命令使字体生效
  • mkfontscale
  • mkfontdir
  • fc-cache

示例