企业官网建设流程全解析

kkFileView 在线预览水印一键配置：机密文档防泄密的 9 个参数速查表

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView

把合同、图纸、报价单丢进 kkFileView 做在线预览，最怕的就是访客右键另存图、截图外发。本文带你把 kkFileView 的预览水印从"0 配置"改到"全屏防泄密"，读完你能直接改 3 个配置项上线、用 URL 传参给不同访问者打不同水印，并掌握 9 个可调参数的默认值与生效机制。

一个真实场景：预览页成了泄密出口

想象一下：你给 50 个合作方开了同一个 kkFileView 预览链接，让他们在线看报价单和图纸。结果某天报价单出现在别家供应商的聊天群里——大家都能看，但没人知道是谁转发出去的。

传统做法是导出 PDF 再套水印，可导出这一步本身就绕过了你的预览系统。更省事的路子，是让 kkFileView 在预览页面直接铺满水印：用户能正常看，但每一帧都带字，截图外传也能追责到人。

这个能力藏在 kkFileView 的一个前端脚本和一组配置项里，不需要改代码。

水印底层原理：一层盖在内容上的绝对定位 div

一句话讲清原理：kkFileView 把水印当成一层覆盖在预览内容之上、不可点击的 div 网格，用transform旋转、用opacity调透明度，铺满整个可视区。

这套逻辑写在 server/src/main/resources/static/js/watermark.js 里。它做三件事：

1. 按窗口宽高等比算出要摆多少行、多少列水印
2. 每个位置生成一个绝对定位的 div，写入水印文字并旋转
3. 监听页面尺寸变化，窗口一缩放就重新铺一遍

所以水印是前端动态渲染的，不走后端转图，几乎不占服务器性能。它通过 server/src/main/resources/web/commonHeader.ftl 被 PDF、Office、图片等预览页统一引入，这也是为什么"改一次配置，所有格式都生效"。

三步开启全局水印：只改配置文件

全局水印（所有访问者、所有格式统一）只需编辑 server/src/main/config/application.properties 里第九段"水印配置"。

第一步，填文字。watermark.txt留空时水印不显示，这是开关本身：

# 水印文本内容（留空 = 不显示水印） watermark.txt = ${WATERMARK_TXT:机密资料_禁止外传}

第二步，控密度。两个间距项决定水印多密，值越小越密：

# 水印 X 轴间距（默认 10） watermark.x.space = ${WATERMARK_X_SPACE:10} # 水印 Y 轴间距（默认 10） watermark.y.space = ${WATERMARK_Y_SPACE:10}

第三步，定外观。字体、字号、颜色、透明度、旋转角各占一行：

watermark.font = ${WATERMARK_FONT:微软雅黑} watermark.fontsize = ${WATERMARK_FONTSIZE:18px} watermark.color = ${WATERMARK_COLOR:black} watermark.alpha = ${WATERMARK_ALPHA:0.2} watermark.angle = ${WATERMARK_ANGLE:10}

改完保存即可。注意watermark.alpha是 0.0~1.0 的透明度，0.2是很轻的灰，既不影响阅读又足够"上镜"。

9 个可调参数速查表

默认值统一收在 server/src/main/java/cn/keking/config/WatermarkConfigConstants.java，全部支持环境变量覆盖。记不清就照这张表抄：

优势：改配置不用重新打包，参数全部走环境变量，Docker 部署时加一行-e WATERMARK_TXT=xxx就行。适用场景：全员共用一个预览入口、需要"统一防泄密底纹"的内网系统。

进阶：用 URL 传参给每个人打不同水印

全局水印有个天花板——所有人都长一个样。想做到"谁访问就盖谁的名字"，得用请求级传参。

server/src/main/java/cn/keking/web/filter/AttributeSetFilter.java 里有个关键设计：每个水印参数都优先读 URL 里的同名参数，读不到才回落配置文件。也就是说，你在预览链接后追加查询串，就能临时覆盖全局设置。

10 个可传参数（注意驼峰命名，和配置项不同）：

watermarkTxt watermarkXSpace watermarkYSpace watermarkFont watermarkFontsize watermarkColor watermarkAlpha watermarkWidth watermarkHeight watermarkAngle

组合进预览地址（url参数是文件地址的 Base64）：

http://你的主机:8012/onlinePreview?url=<Base64编码的文件地址> &watermarkTxt=张三_工号0042 &watermarkAlpha=0.3 &watermarkAngle=25

这样就实现了"千人千面"：你的前端在跳转前，把当前登录用户的花名拼进watermarkTxt，每个访客打开的都是带自己名字的水印页。泄了图，一眼定位到人。

优势：无需改全局配置，水印随用户动态变化，追责到个人。适用场景：对接企业 SSO、按登录态区分访问者的场景。

热更新机制：改完配置不用重启服务

很多团队以为改application.properties必须重启。kkFileView 不是这样。

server/src/main/java/cn/keking/config/ConfigRefreshComponent.java 用一个WatchService盯着配置文件，文件一变就触发5 秒防抖后的重载：

private static final long DEBOUNCE_DELAY_SECONDS = 5; // 文件变动 → 取消旧任务 → 延迟 5 秒后 loadConfig()

这对水印的意义很直接：你调完watermark.txt，等几秒刷新预览页就生效，不需要重启进程。压测或调参时反复改配置也不会被打断。

顺带一提，代码里的默认宽是 240、配置里默认是 180，这类"代码默认 vs 配置默认"的小差异不影响使用——以配置文件为准，ConfigRefreshComponent重载时读的是文件值。

避坑：水印不显示的 3 个排查点

改完没水印？按这个顺序查，基本能覆盖 90% 的情况。

1. watermark.txt是不是空的。这是第一开关，留空前端直接return，后面全不生效。先确认文件里确实写了字，而不是只剩注释。
2. 传参名写错成配置名。配置文件是watermark.txt（点分、小写），URL 传参是watermarkTxt（驼峰）。两个世界，混用会读不到值而回落到默认。
3. 看的是缓存页。全局开启cache.enabled=true时，同一文件地址可能命中旧预览。换个文件、或清一下缓存再验证，排除"改了但看的还是老结果"的假象。

另外两点容易踩：

• watermark.color写纯黑 +alpha调太高，白底文档会一片刺眼，阅读体验崩掉。建议深灰 + 0.2。
• 水印是前端渲染，只盖预览页，不盖导出的原文件。如果目标是"导出的 PDF 也带水印"，那属于文档转换环节，和本文这套前端水印不是一回事，别指望它。

收尾

把 kkFileView 的预览水印用起来，核心就三块：配置文件开全局底纹、URL 传参做个性化、热更新省掉重启。它不碰服务器转图链路，纯前端铺网格，成本几乎为零，却能把"预览页即泄密口"这件事堵上大半。

下一篇想聊聊 kkFileView 的信任主机白名单trust.host——它决定了哪些外部文件地址能被预览，是这套系统安全性的另一道闸门，和今天的水印正好一个防"内鬼"、一个防"滥用"。

觉得有用就点个收藏，配置参数表可以存下来，调水印的时候直接对着抄 📌

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView