kkFileView 部署指南30 秒启动文件在线预览服务5 条路线选 1 条【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView附件里一份 50 页的 PDF不下载就没法看对方回一句文件在网盘里你自己下沟通链又断了一次。kkFileView 就是一个把这类麻烦接住的文件在线预览服务基于 Spring Boot 的开源项目支持 50 多种格式本地化部署后一个文件 URL 就能在浏览器里直接看内容。这篇 kkFileView 部署教程只讲落地怎么起、怎么验、怎么调、怎么接进你自己的系统。部署完成你拥有什么按任意一条路线把服务跑起来你手里就有下面这些可以立刻验证的东西格式覆盖Officedoc/docx/xls/xlsx/ppt/pptx/csv、WPSwps/et/dps、OpenDocument、PDF/OFD/RTF、CADdwg/dxf/dwf、3D 模型stl/obj/glb 等、eml/msg 邮件、zip/rar/7z 压缩包、图片与音视频全走浏览器渲染统一预览入口http://服务器:8012/onlinePreview?url文件URL一个地址预览任何格式集成接口REST API 现成的 iframe 页面两种接法后文都有示例预览安全开关水印、trust.host域名白名单防 SSRF、Basic 认证、AES 传输加密参数热刷新改配置约 2 秒自动生效多数场景不用重启服务可观测性/actuator/health和/actuator/metrics端点开箱可用全部参数支持KK_前缀环境变量覆盖镜像升级时不用改代码30 秒跑起来Docker 一键启动命令这条命令是全文唯一需要背下来的部分# 拉取镜像并启动映射宿主机 8012 端口 docker run -d --name kkfileview -p 8012:8012 keking/kkfileview:5.0.0然后打开http://服务器IP:8012/。看到首页输入框部署就算成了。把任意外部 PDF 链接粘进去走一遍转换流程第一次较慢LibreOffice 在后台干活同样的 URL 第二次打开会直接命中缓存。镜像里已经装好 JDK 21、LibreOffice 和中文字体这一步没有任何环境前置。选一条适合你的部署路线三条路线的差异一张表说清楚先对号入座再动手维度Docker 镜像官方发布包源码编译适合人群有 Docker 环境的服务器生产与测试默认选择无 Docker 的内网 Windows 机器、只有一台 Windows 服务器的场景要改代码、打包定制镜像、跟进源码版本的人优点依赖JDK 21 LibreOffice 字体全部内置一条命令启动Windows 版内置便携版 LibreOffice不装办公软件完全可控改完直接出包缺点定制配置要改镜像或走环境变量Linux 发布包需自备 LibreOffice依赖环境要手动对齐编译耗时最长耗时约 5 分钟含拉镜像约 10~15 分钟30 分钟起推荐项有 Docker 就用 Docker 镜像它是默认答案只有没有 Docker或必须改代码两个条件成立时再分别走发布包或源码路线。部署操作详解路线一Docker 镜像准备# 确认 Docker 可用、8012 端口未被占用 docker version curl -sv http://127.0.0.1:8012/ # 连接拒绝属正常执行# 后台启动并映射 8012 docker run -d --name kkfileview -p 8012:8012 keking/kkfileview:5.0.0需要预览服务器本地文件时挂载白名单目录并指定存储路径# 白名单目录 转换产物目录 8012 端口 docker run -d --name kkfileview -p 8012:8012 \ -e KK_LOCAL_PREVIEW_DIR/data/files -e KK_FILE_DIR/data/kkfileview/file \ -v /data/files:/data/files -v /data/kkfileview:/data/kkfileview \ keking/kkfileview:5.0.0验证# 容器存活检查 首页检查 docker ps | grep kkfileview curl -I http://127.0.0.1:8012/ # 返回 200 即成功浏览器打开首页粘贴一个 URL 预览确认无乱码即完成。日志有异常时docker logs -f kkfileview追一下。路线二官方发布包准备JDK 21 已安装java -version确认Linux另装 LibreOffice如apt-get install libreoffice-writer libreoffice-calc libreoffice-impressWindows 发布包内置便携版 LibreOffice跳过此项执行发布包为kkFileView-版本号.tar.gz解压后包含 binjar 与启动脚本和 config 目录。先设两个环境变量再启动# 指向本机 LibreOffice 安装目录Windows 写实际安装路径 export KK_OFFICE_HOME/opt/libreoffice # 转换产物存储目录确认有写权限 export KK_FILE_DIR/data/kkfileview/file cd kkFileView-5.0.0 bin/start.sh验证# 首页状态码 健康检查 curl -I http://127.0.0.1:8012/ curl http://127.0.0.1:8012/actuator/healthhealth 返回 UP、首页可打开后用真实文件 URL 走一次完整预览。路线三源码编译准备JDK 21、MavenLibreOffice 按路线二补齐。执行# 克隆仓库并进入 server 模块 git clone https://gitcode.com/GitHub_Trending/kk/kkFileView cd kkFileView/server mvn clean package # 运行打包产物 java -jar target/kkFileView-*.jar验证启动日志出现 Tomcat 监听 8012 后打开http://localhost:8012/粘贴一个文件 URL 确认预览正常。这条路线与 Docker 路线的差别只在镜像帮你装好的 JDK 和 LibreOffice现在要你自己对齐版本。部署完成后的验收清单跑通首页只是起点逐项勾完这份清单再交接给团队首页http://服务器:8012/打开无报错输入框可用一份 docx、一份 xlsx、一份 pptx、一份 pdf 分别预览Office 文档默认走 PDF 模式排版与源文件一致xlsx 走前端解析默认 web 模式大表格不拖垮服务器 CPU一个 zip 能展开文件树包内 txt 或图片可点开一个 mp4 能正常播放不用先下载20MB 以上文件首次响应可接受同 URL 二次打开秒开缓存生效100 页以上 PDF 翻页流畅左侧缩略图侧边栏默认可用/actuator/health返回 UP接进监控系统磁盘占用确认自动清理已启用默认开启每天 3:00 执行file.dir所在分区容量充足故意预览一个坏文件页面给出明确错误日志里能定位到 预览核心转换逻辑 对应记录预览变慢或格式异常时的调优资源分配转换吃内存JVM 堆要给够。Docker 路线在启动命令加-e JAVA_OPTS-Xms1g -Xmx2g裸机路线直接java -Xms1g -Xmx2g -jar ...。并发量上去时把office.plugin.server.ports从默认的2001,2002扩成更多端口等于多开几个 LibreOffice 转换进程分摊负载。缓存策略单机保持默认的cache.typejdk即可重复 URL 不再二次转换。多实例部署时切成cache.typeredis并配spring.redisson.address指到共享 Redis。注意缓存是URL 级的同一个文件换了 URL 参数就会重新转换。大文件策略确认异步任务权限已开启kk.addTask默认 true大文件会转成异步任务轮询不会把请求线程卡死。PDF 按页数自动分档 DPI50 页以内 150200 页以上降到 72pdf.dpi.small到pdf.dpi.xxlarge想再快点可以继续调低。Office 转换默认超时 5 分钟office.plugin.task.timeout超过就拆文件或升内存。媒体文件视频转换对 CPU 和内存消耗最大media.convert.max.size默认限 300MB超出的直接拒绝不需要转码能力的业务环境建议直接media.convert.disabletrue关掉头。把预览接入你自己的系统三种接法按集成深度选直接跳转给前端拼http://kkfileview:8012/onlinePreview?url...最简单iframe 嵌入在你的页面里嵌一个预览框用户感知不到独立服务反向代理Nginx 把/preview/**转给 kkFileView业务侧不暴露服务真实地址iframe 最小示例!-- 注意url 参数要先做 URLEncode -- iframe srchttp://kkfileview:8012/onlinePreview?urlhttps%3A%2F%2Fexample.com%2Fa.pdf width100% height720 frameborder0/iframe跨域拉取文件需要在 配置文件位置 里保持kk.Getcorsfiletrue。走 Nginx 反代时记得两件事设base.url为对外域名把业务文件的域名加进trust.host白名单。前端页面模板在 templates 目录要改预览页样式从这里入手。高频踩坑与解法现象转换出的 PDF 里中文全是方块或乱码原因宿主机或容器缺中文字体Docker 官方镜像已内置自打镜像或裸机部署最容易漏解法装fonts-noto-cjk一类中文字体包后刷新字体缓存fc-cache -fv重启服务再验现象预览某个外部 URL 直接报未授权原因防 SSRF 默认策略trust.host没配该域名时拒绝所有外部文件请求解法把文件所在域名加进trust.host逗号分隔5.0.0 起支持通配符和 CIDR生产环境不要用*现象大文件转换到一半报超时原因默认 5 分钟任务超时且转换是重计算解法调大office.plugin.task.timeout和office.plugin.task.taskexecutiontimeout同时确认异步任务权限开着仍失败就升内存现象运行几天后磁盘被占满原因转换产物和缓存在file.dir下持续累积解法确认cache.clean.enabledtrue、cache.clean.cron按预期执行把file.dir指到容量充足的分区必要时把清理时间调频现象8012 端口冲突服务起不来原因同机已有服务占用该端口解法KK_SERVER_PORT8080覆盖端口同步改 Nginx 转发规则反代场景别忘了把base.url一起改成对外域名否则生成的链接指向内网地址结尾跑完部署、勾完验收清单你的团队看任何文件都不再需要先下载。下一步选一条路线把服务拉起来用真实业务文件过一遍验收清单。【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考