发帖|

关注JEECG发展历程 关注最新动态和版本, 记录JEECG成长点滴 更新日志 - 技术支持 - 招聘英才

JEECG最新版本下载 JEECG智能开发平台 - 显著提高开发效率 常见问题 - 入门视频 - 参与开源团队

商务QQ: 69893005、418799587 商务热线(5*8小时): 010-64808099 官方邮箱: jeecg@qq.com

查看: 27|回复: 0

kkFileView 4.x 高危漏洞已被利用,JeecgBoot 文档预览请升级 5.0.3

J小助2026-11-1627阅读1分钟版块:JeecgBoot经验分享
[复制链接]
发表于 昨天 16:01 | 显示全部楼层 |阅读模式

文档预览服务从旧版本升级到安全版本

先说结论: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
# 产物:server/target/kkFileView-5.0.3.tar.gz

编译时最常见的坑是依赖下载失败:项目依赖的 aspose-cad 只发布在 Aspose 官方仓库(https://repository.aspose.com/repo)。如果 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低代码侧的配置

Nginx 反向代理 + 容器化预览服务的部署结构

在 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 是容器自己,读不到宿主机上的文件。需要三处一起改:
    1. 把前端 .env.development 里的 VITE_GLOB_DOMAIN_URL 改成 http://<本机局域网IP>:8080/jeecg-boot;
    2. 把这个局域网 IP 加进 KK_TRUST_HOST;
    3. 从 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 免费开源的低代码平台团队撰写。

您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

点赞快速回复 分享
复制链接微信新浪微博QQ空间

微信扫一扫,分享给好友

返回顶部 返回列表