JeecgBoot AI专题研究 | JeecgBoot低代码在线文档预览(kkFileView)安全升级实战

先说结论:4.x 及更早版本请尽快下线
JeecgBoot低代码的附件在线预览(Word、Excel、PDF、图片等)依赖开源组件 kkFileView。kkFileView 4.x 及更早版本存在任意文件写入、SSRF 等高危漏洞,而且已经不是纸面风险:对公网开放的预览服务,已经出现了被入侵、被写满磁盘的真实案例。
处理办法只有一条:升级到 kkFileView 5.0.3 及以上版本,并配置预览白名单。5.0.3 是 2026-10-08 发布的安全补丁版,运行环境要求 JDK 21 及以上(下文的 Docker 镜像已内置)。
这两个漏洞的危害可以这样理解:
- SSRF(服务端请求伪造):预览服务的本职工作就是「按别人给的地址去下载文件」。如果不限制地址,攻击者就能让它去访问内网服务、云服务器的元数据接口,把预览服务变成探测内网的跳板。
- 任意文件写入:攻击者可以让服务把内容写到服务器的任意路径,轻则写满磁盘导致整机不可用,重则覆盖程序文件、植入后门。
所以这次升级的重点不只是换版本号,更重要的是 5.x 引入的信任站点白名单:不在名单里的来源一律拒绝预览。
第一步:拿到 5.0.3 镜像
kkFileView 官方 Docker Hub 镜像只更新到 4.1.0,没有 5.x。JEECG 用 v5.0.3 源码制作了镜像,放在阿里云镜像仓库,x86 / amd64 服务器可以直接拉取:
docker pull registry.cn-hangzhou.aliyuncs.com/jeecgdocker/kkfileview:5.0.3
拉下来后可以直接跳到下一节「启动容器」。
ARM 服务器或想自己构建:从源码编译
如果服务器是 ARM 架构,或者团队要求镜像自己构建,先编译安装包:
git clone -b v5.0.3 --depth 1 https://github.com/kekingcn/kkFileView.git
cd kkFileView
mvn clean package -DskipTests
编译时最常见的坑是依赖下载失败:项目依赖的 aspose-cad 只发布在 Aspose 官方仓库。如果 Maven 的 settings.xml 把阿里云镜像配成了 mirrorOf *,所有请求都会被转到阿里云,自然找不到这个包。把镜像配置改成 <mirrorOf>*,!aspose-maven-repository</mirrorOf>,让 Aspose 仓库绕开镜像即可。
然后新建一个目录,放入 kkFileView-5.0.3.tar.gz 和下面的 Dockerfile:
FROM ubuntu:24.04
RUN sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g;s@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources && \
echo 'Acquire::Retries "5";' > /etc/apt/apt.conf.d/80retries && \
apt-get update && export DEBIAN_FRONTEND=noninteractive && \
apt-get install -y --no-install-recommends openjdk-21-jre-headless tzdata locales xfonts-utils fontconfig libreoffice-nogui \
fonts-wqy-microhei fonts-wqy-zenhei xfonts-wqy fonts-noto-cjk && \
echo 'Asia/Shanghai' > /etc/timezone && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
localedef -i zh_CN -c -f UTF-8 -A /usr/share/locale/locale.alias zh_CN.UTF-8 && \
fc-cache -f && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*
ENV LANG=zh_CN.UTF-8 LC_ALL=zh_CN.UTF-8
ADD kkFileView-5.0.3.tar.gz /opt/
ENV KKFILEVIEW_BIN_FOLDER=/opt/kkFileView-5.0.3/bin
EXPOSE 8012
ENTRYPOINT ["java","-Dfile.encoding=UTF-8","-Dspring.config.location=/opt/kkFileView-5.0.3/config/application.properties","-jar","/opt/kkFileView-5.0.3/bin/kkFileView-5.0.3.jar"]
docker build -t kkfileview:5.0.3 .
这个 Dockerfile 有几处值得留意:LibreOffice 负责把 Office 文档转成可预览的格式;文泉驿、Noto CJK 等中文字体决定了中文文档会不会出现方块乱码;时区和 zh_CN.UTF-8 语言环境则避免日期和编码问题。
镜像要和服务器的 CPU 架构一致。docker build 做出来的镜像架构和当前机器相同;如果在 M 系列芯片的 Mac 上给 x86 服务器做镜像,要用:
docker buildx build --platform linux/amd64 -t kkfileview:5.0.3 --load .
自己构建的话,把下一节启动命令最后一行的镜像名换成 kkfileview:5.0.3。
第二步:带白名单启动容器

docker run -d --name kkfileview5 --restart unless-stopped \
-p 127.0.0.1:8012:8012 --memory 2g \
--log-opt max-size=50m --log-opt max-file=3 \
-e KK_BASE_URL=https://fileview.your-domain.com/ \
-e KK_TRUST_HOST='your-domain.com,*.your-domain.com,your-bucket.oss-cn-beijing.aliyuncs.com' \
-e KK_NOT_TRUST_HOST='localhost,127.*,0.0.0.0,10.*,172.16.0.0/12,192.168.*,169.254.*,100.64.0.0/10,metadata.tencentyun.com' \
-e KK_PROHIBIT='exe,dll,dat,dwg,dxf,dwf,iges,igs,dwt,dng,ifc,dwfx,stl,cf2,plt' \
registry.cn-hangzhou.aliyuncs.com/jeecgdocker/kkfileview:5.0.3
这条命令里每一个参数都对应一项安全措施,逐个拆开看:
| 参数 / 环境变量 | 作用 | 要点 |
|---|---|---|
KK_TRUST_HOST |
预览白名单 | 5.x 必须配置,不配时拒绝所有外部文件。填存放附件的域名,逗号分隔,支持 *.example.com 通配和 192.168.0.0/16 网段写法,不建议填 * |
KK_NOT_TRUST_HOST |
预览黑名单 | 优先级高于白名单。填内网地址段和云服务器元数据地址(如 169.254.*),专门防 SSRF 探测内网 |
KK_PROHIBIT |
禁止预览的文件类型 | 示例把可执行文件和 CAD 格式一起禁用了 |
KK_BASE_URL |
对外访问地址 | 用 nginx 反向代理(尤其是 HTTPS)时必须配置,否则页面里的资源地址会出错 |
KK_PDF_PRINT_DISABLE |
PDF 打印按钮 | 默认 true(不显示),需要打印时加 -e KK_PDF_PRINT_DISABLE=false |
-p 127.0.0.1:8012:8012 |
只监听本机 | 8012 端口不直接暴露公网,统一由 nginx 对外 |
--memory、--log-opt |
资源上限 | 限制内存和容器日志大小,避免拖垮服务器或写满磁盘 |
之所以不用改镜像就能调这些参数,是因为配置文件里写的是 trust.host = ${KK_TRUST_HOST:default} 这种占位形式,docker run -e 传入的环境变量会直接生效。
两个运维细节:
- 重启容器用
docker restart kkfileview5。 - 环境变量只在容器创建时读取。改了白名单之后,
docker restart不会生效,要先docker rm -f kkfileview5,再重新执行docker run。建议把整条命令存成run.sh,以后改完直接执行。
另外,5.0.3 默认已经关闭了文件上传功能,保持默认即可,不要为了方便手动打开。
第三步:JeecgBoot低代码侧的配置

在 JeecgBoot低代码后端的 application-*.yml 里,把预览服务地址指向新部署的 kkFileView:
jeecg:
# 在线预览文件服务器地址配置
file-view-domain: https://fileview.your-domain.com
最关键的一点:附件的存储域名一定要加进 KK_TRUST_HOST。比如附件存在阿里云 OSS,就把 bucket 域名加进去;存在自己的文件服务器,就加上对应域名。漏掉的话,预览时会提示「预览源文件来自不受信任的站点」。
前端不用改。kkFileView 从 v3.3.0 起,预览地址采用 base64 + urlencode 双重编码,5.x 沿用同一规则,JeecgBoot低代码前端现有的调用方式可以直接用:
import {
encryptByBase64 } from "@/utils/cipher";
const url = encodeURIComponent(encryptByBase64(record.url));
const previewUrl = `${
glob.viewUrl}?url=${
url}`;
window.open(previewUrl, "_blank");
本地开发怎么调通
本地启动一个容器,后端配置 file-view-domain: http://127.0.0.1:8012,然后按附件的存储方式分两种情况:
- 附件存在 OSS 等云存储(
uploadType: alioss):白名单填 OSS 的域名即可,最省事。 - 附件存在本地(
uploadType: local):这是最容易踩坑的情况。kkFileView 跑在容器里,它访问的localhost是容器自己,读不到宿主机上的文件。需要三处一起改:- 把前端
.env.development里的VITE_GLOB_DOMAIN_URL改成http://<本机局域网IP>:8080/jeecg-boot; - 把这个局域网 IP 加进
KK_TRUST_HOST; - 从
KK_NOT_TRUST_HOST里去掉192.168.*,否则黑名单优先,白名单加了也不生效。
- 把前端
这里的第 3 点只适用于本地开发,生产环境的黑名单要保持完整。
CAD 预览的授权问题
kkFileView 的 CAD 预览(dwg、dxf 等)用的是 Aspose-CAD 试用版,官方说明商用需自行购买授权。这也是上面启动命令里把 CAD 格式写进 KK_PROHIBIT 的原因:不需要 CAD 预览就直接禁用;确实需要的,请先购买 Aspose 授权再放开。
常见问题
提示「预览源文件来自不受信任的站点」怎么办?
说明文件所在的域名不在 KK_TRUST_HOST 里。把提示中出现的域名加进白名单,然后删除并重新创建容器(只 restart 不生效)。
还能继续用 4.0.0 吗?
4.0.0 及更早版本存在上述安全漏洞,只能作为内网环境的参考,不要部署到公网。已经在公网跑着旧版本的,建议尽快排查磁盘占用、异常文件和访问日志,再按本文升级。
升级前后对比一览
| 对比项 | 4.x 及更早 | 5.0.3 + 本文配置 |
|---|---|---|
| 已知高危漏洞 | 任意文件写入、SSRF | 已修复 |
| 预览来源控制 | 不限制 | 白名单 + 黑名单 |
| 端口暴露 | 常见直接对外 | 只监听 127.0.0.1,经 nginx 对外 |
| 资源上限 | 无 | 限制内存和日志大小 |
| 文件上传 | 需手动关闭 | 默认关闭 |
总结
这次 kkFileView 升级可以归纳成三句话:版本升到 5.0.3 及以上;用 KK_TRUST_HOST 只放行自己的附件域名,用 KK_NOT_TRUST_HOST 挡住内网和元数据地址;端口只绑本机,由 nginx 对外,并限制内存和日志。JeecgBoot低代码侧只需要改一行 file-view-domain,再确认附件域名在白名单里,前端代码不用动。
文档预览服务天生要「替别人去取文件」,它的安全边界必须靠配置画出来。建议所有对公网提供预览的 JeecgBoot低代码项目,本周内完成排查和升级。
本文由 JEECG 免费开源的低代码平台团队撰写。