kkFileView国产化环境实战：23类文件格式在线预览的搭建与调优完整指南
【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView
国产化办公环境里有个高频场景：同事发来一份.wps合同、一个.ofd发票包，你的浏览器打不开，机器上又没装 WPS。传统做法是把文件下载下来、装好对应软件、再人工核对，一来一回半天过去了。
kkFileView 是一个基于 Spring Boot 的文件在线预览服务，把 Office 文档、WPS 国产办公文档、OFD、CAD、3D 模型、压缩包、音视频等 23 类格式统一转成网页可直接浏览的形式。你只需要把文件地址拼进预览 URL，就能在浏览器里看到渲染结果，不必在每台终端上装一堆办公软件。
先搞清楚：哪些文件能直接扔给它
选型前先看能力边界。kkFileView 覆盖的主流格式大致分五组：
- 办公文档：doc/docx、xls/xlsx、ppt/pptx、csv 等，同时支持国产 WPS 的
wps、dps、et、wpt，以及 ODF 系列（odt、ods、odp） - 国产化特色格式：OFD 版式文档（电子发票、公文归档常用）、dcm 医疗影像
- 工程文件：dwg/dxf 等 CAD 模型、obj/3ds/stl 等 3D 模型、bpmn/drawio/xmind 流程图
- 文本与代码：txt、md、xml、json 及各类源码，按语法高亮渲染
- 多媒体与压缩包：jpg/png 等图片、mp4/mp3 等音视频、zip/rar/7z（压缩包可逐层点开看里面的文件）
对你来说最实际的一句话：OA、邮件、网盘里那些"点不开"的附件，绝大多数丢给它都能出画面。具体支持列表见 README.cn.md 开头的 23 条说明。
最短上手路径：两条命令跑起来
依赖很少：JDK 21、一个可转换 Office 的 LibreOffice（Windows 版已内置在仓库的server/LibreOfficePortable，Linux 启动脚本会自动安装），Redis 可选不装。
方式一：本地直接运行（验证功能用）
git clone https://gitcode.com/GitHub_Trending/kk/kkFileView克隆后运行 server/src/main/java/cn/keking/ServerMain.java 的 main 方法，访问http://localhost:8012/即看到首页，把文件传上去或拼 URL 就能预览。
方式二：Docker 容器部署（正式环境推荐）
项目根目录的 Dockerfile 基于keking/kkfileview-base:5.0.0基础镜像构建，基础镜像在 docker/kkfileview-base/ 下，基于 Ubuntu 24.04，内置 OpenJDK 21、LibreOffice 和一批中文字体（文泉驿、mscorefonts），这一步对国产化环境很关键——中文文档转 PDF 时不会因为缺字体变成"□□□"。
两个细节：
- 仓库同时支持linux/amd64 和 linux/arm64两种架构镜像，构建方法在 docker/kkfileview-base/README.md，在 arm64 机器上（如国产飞腾、鲲鹏服务器）直接构建即可
- 5.0.0 起强制要求JDK 21，老环境升级前先看这个
国产化环境重点配置清单
所有配置集中在 server/src/main/config/application.properties，支持通过环境变量覆盖（如KK_TRUST_HOST、KK_FILE_DIR），容器化部署时不用改文件。按优先级给你排了序：
1. 信任主机白名单（不配就白搭）
4.4.0 之后版本默认拒绝所有外部文件预览请求以防 SSRF 攻击。你的文件服务器/对象存储域名要写进trust.host，例如trust.host = your-cdn.com,10.20.30.*（支持通配符和 CIDR）。不配置时只有本机测试可用，具体规则见 SECURITY_CONFIG.md。
2. Office 预览模式：office.preview.type
5.0.0 默认改为pdf模式（整个文档转 PDF 再渲染，内网访问体验流畅且保留书签批注）；如果常见的是几百页大 Word、前端加载吃力，可以切回image模式（逐页转图片）。Excel 则默认走office.type.web=web的前端 SheetJS 解析，服务器压力小，不需要转换。
3. 缓存策略：cache.type
单机部署用默认的jdk（进程内 Map）即可；集群或多实例部署切到redis，支持单机/集群/哨兵/主从四种模式。缓存默认每天凌晨 3 点自动清理磁盘产物，磁盘紧张可调整cache.clean.cron。
4. 转换并发与超时
PDF、CAD、TIF、视频各自有独立线程数和超时（pdf.max.threads、cad.thread、media.convert.disable等）。PDF 还内置了智能 DPI 分级：50 页以下 150 DPI，200 页以上自动降到 72 DPI，大文件转换不会把 CPU 打满。视频转码默认是关的（media.convert.disable默认 false 但转码极耗资源，小内存机器建议显式关闭）。
5. 水印与访问控制
office.watermark打开后 Office 转换会带水印，水印文案、颜色、透明度、角度都有独立配置项，适合对文档留痕有要求的单位。对外暴露时建议叠加kk.key（API 密钥）或 Basic 认证，并保留默认的prohibit = exe,dll,dat危险类型拦截。
部署运维注意事项
- 字体问题：Linux 下预览中文 WPS/OFD 若出现乱码或空白，先查容器内中文字体是否齐全，基础镜像已内置，自建镜像时参考 docker/kkfileview-base/Dockerfile 的字体安装段
- 路径与权限：
file.dir指定预览产物目录，local.preview.dir指定允许预览的本地目录（默认禁止，安全考虑），确保应用账号有读写权限 - 反向代理：用 Nginx 前置时记得设置
base.url，否则生成的预览地址会指向内网 IP - 资源预估：Office 转换依赖 LibreOffice 进程池（
office.plugin.server.ports = 2001,2002多端口可做负载均衡），高峰期可按maxtasksperprocess控制单进程任务数防内存溢出 - 完整的线上自动部署流程（拉码、Maven 打包、健康检查、失败回滚）可参考 doc/ci-auto-deploy.md 的思路
小结与下一步
kkFileView 的核心价值就三点：23 类格式（含 WPS、OFD 等国产化格式）统一转网页预览、REST 接口跨语言接入简单、Docker 双架构镜像适配国产服务器。上手路径是——克隆仓库、跑ServerMain或docker build起容器、配好trust.host，三条之内。
下一步建议：先用 5.0.0 的 Docker 镜像在测试机验证你要预览的实际业务文件（尤其是 OFD 和 CAD），确认效果后再按上文清单调线程数、缓存和安全白名单，最后接入你的业务系统（预览 URL 形如/onlinePreview?url=文件地址）。
【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
