feat: 新增可选的签名预览，预览请求可携带带有效期的签名令牌（JWT），默认关闭

server/src/main/config/application.properties

@@ -436,6 +436,78 @@ kk.addTask = true
 # 启用后需要提供密钥才能调用API
 kk.key = false
 
+# 签名预览，默认为false（关闭）；关闭时预览接口的行为与参数完全不变
+# 开启后 /onlinePreview、/picturesPreview 只接受带有效签名令牌（JWT）的请求：
+#   1. 令牌由接入方的业务系统用下面的密钥签发，必须带有效期 exp（秒）
+#   2. 文件地址、文件名、水印、是否强制重新转换从令牌里取；请求参数只保留放行名单里的
+#   3. trust.host / not.trust.host、kk.key 照常生效，令牌里的文件地址同样要过信任站点检查
+# 令牌示例（HS256，载荷）：
+#   {"url":"https://files.example.com/demo/test.docx","watermarkTxt":"张三 0012","exp":1767225600}
+# 预览地址：/onlinePreview?token=<令牌>；多图预览的令牌用 urls 字段（数组，或用 | 分隔的字符串）
+signed.preview.enabled = ${KK_SIGNED_PREVIEW_ENABLED:false}
+
+# 签名密钥，默认为false（未配置）。开启签名预览或取件签名时必须配置，建议不少于32个字符
+signed.preview.secret = ${KK_SIGNED_PREVIEW_SECRET:false}
+
+# 签名算法，支持 HS256、HS384、HS512；令牌头里的 alg 必须与这里一致
+signed.preview.algorithm = ${KK_SIGNED_PREVIEW_ALGORITHM:HS256}
+
+# 令牌放在哪个请求参数里
+signed.preview.token.param = ${KK_SIGNED_PREVIEW_TOKEN_PARAM:token}
+
+# 令牌里各字段的名字：文件地址、多图地址、文件名、水印文字、是否强制重新转换
+# 其余水印参数（watermarkXSpace、watermarkYSpace、watermarkFont、watermarkFontsize、watermarkColor、
+# watermarkAlpha、watermarkWidth、watermarkHeight、watermarkAngle）在令牌里用与请求参数相同的名字
+signed.preview.claim.url = ${KK_SIGNED_PREVIEW_CLAIM_URL:url}
+signed.preview.claim.urls = ${KK_SIGNED_PREVIEW_CLAIM_URLS:urls}
+signed.preview.claim.filename = ${KK_SIGNED_PREVIEW_CLAIM_FILENAME:fullfilename}
+signed.preview.claim.watermark = ${KK_SIGNED_PREVIEW_CLAIM_WATERMARK:watermarkTxt}
+signed.preview.claim.force = ${KK_SIGNED_PREVIEW_CLAIM_FORCE:forceUpdatedCache}
+
+# 其余水印参数和 currentUrl 在令牌里的字段名映射，格式：请求参数名:令牌字段名，多个用逗号分隔，默认为default（同名）
+# 例如 watermarkAlpha:wmAlpha,currentUrl:cur。上面五项单独配置的字段不走这张表，写了也以单独那项为准
+signed.preview.claim.map = ${KK_SIGNED_PREVIEW_CLAIM_MAP:default}
+
+# 令牌里表示用途的字段名，以及三种令牌各自的用途值：接入方签发的预览令牌、
+# kkFileView 自己签发的压缩包令牌和取件令牌。三个值必须互不相同，否则签名预览拒绝全部请求、也不签发自己的令牌
+signed.preview.claim.use = ${KK_SIGNED_PREVIEW_CLAIM_USE:use}
+signed.preview.use.preview = ${KK_SIGNED_PREVIEW_USE_PREVIEW:preview}
+signed.preview.use.archive = ${KK_SIGNED_PREVIEW_USE_ARCHIVE:archive}
+signed.preview.use.fetch = ${KK_SIGNED_PREVIEW_USE_FETCH:fetch}
+
+# 预览令牌是否必须写用途，默认为false（不写用途字段的令牌也当作预览令牌）
+signed.preview.use.required = ${KK_SIGNED_PREVIEW_USE_REQUIRED:false}
+
+# 开启签名预览后仍允许浏览器自己带的请求参数，多个用逗号分隔，其余参数一律丢弃
+# 可以限定取值：officePreviewType=image|pdf|html,page 表示 officePreviewType 只放过这三个值（区分大小写，
+# 值不在其中或同一参数给了多个值时丢弃这个参数，不拒绝整个请求），page 任意值
+# 由令牌决定的参数（文件地址、水印、强制重新转换等）写进这里也不会生效
+signed.preview.allow.params = ${KK_SIGNED_PREVIEW_ALLOW_PARAMS:officePreviewType,tifPreviewType,page,highlightall,filePassword,key}
+
+# kkFileView 自己签发的令牌（压缩包内文件、取原文件）的有效期，单位秒
+signed.preview.ttl = ${KK_SIGNED_PREVIEW_TTL:600}
+
+# 压缩包令牌、取件令牌各自的有效期，单位秒，默认为default（使用上面的 signed.preview.ttl）
+signed.preview.archive.ttl = ${KK_SIGNED_PREVIEW_ARCHIVE_TTL:default}
+signed.fetch.ttl = ${KK_SIGNED_FETCH_TTL:default}
+
+# 校验有效期时允许的时钟误差，单位秒
+signed.preview.leeway = ${KK_SIGNED_PREVIEW_LEEWAY:30}
+
+# 取原文件时是否附带 kkFileView 自己签发的令牌，默认为false（关闭），与签名预览各自独立开关
+# 开启后用 http/https 下载原文件时在下面的请求头里带一枚令牌，密钥与算法同上，
+# 载荷为 {"use":"fetch","url":"<本次请求的地址>","iat":...,"exp":...}，文件来源一方可据此确认请求来自本服务
+signed.fetch.enabled = ${KK_SIGNED_FETCH_ENABLED:false}
+signed.fetch.header = ${KK_SIGNED_FETCH_HEADER:kk-fetch-token}
+
+# 请求头的值在令牌前面加的前缀，默认为default（不加）。不为空时与令牌之间用一个空格隔开，
+# 例如请求头配成 Authorization、前缀配成 Bearer，发出的就是 Authorization: Bearer <令牌>
+signed.fetch.header.prefix = ${KK_SIGNED_FETCH_HEADER_PREFIX:default}
+
+# 取件令牌里「本次请求的地址」放在载荷的哪个字段，支持用点分隔的嵌套对象，
+# 例如 payload.url 签成 {"payload":{"url":"<地址>"}}
+signed.fetch.claim.url = ${KK_SIGNED_FETCH_CLAIM_URL:url}
+
 # AES加密密钥，必须为16位字符
 # 启用AES加密时，接入方需使用相同的密钥
 # 用于敏感数据传输加密

server/src/main/config/test.properties

@@ -432,6 +432,78 @@ kk.addTask = true
 # 启用后需要提供密钥才能调用API
 kk.key = false
 
+# 签名预览，默认为false（关闭）；关闭时预览接口的行为与参数完全不变
+# 开启后 /onlinePreview、/picturesPreview 只接受带有效签名令牌（JWT）的请求：
+#   1. 令牌由接入方的业务系统用下面的密钥签发，必须带有效期 exp（秒）
+#   2. 文件地址、文件名、水印、是否强制重新转换从令牌里取；请求参数只保留放行名单里的
+#   3. trust.host / not.trust.host、kk.key 照常生效，令牌里的文件地址同样要过信任站点检查
+# 令牌示例（HS256，载荷）：
+#   {"url":"https://files.example.com/demo/test.docx","watermarkTxt":"张三 0012","exp":1767225600}
+# 预览地址：/onlinePreview?token=<令牌>；多图预览的令牌用 urls 字段（数组，或用 | 分隔的字符串）
+signed.preview.enabled = ${KK_SIGNED_PREVIEW_ENABLED:false}
+
+# 签名密钥，默认为false（未配置）。开启签名预览或取件签名时必须配置，建议不少于32个字符
+signed.preview.secret = ${KK_SIGNED_PREVIEW_SECRET:false}
+
+# 签名算法，支持 HS256、HS384、HS512；令牌头里的 alg 必须与这里一致
+signed.preview.algorithm = ${KK_SIGNED_PREVIEW_ALGORITHM:HS256}
+
+# 令牌放在哪个请求参数里
+signed.preview.token.param = ${KK_SIGNED_PREVIEW_TOKEN_PARAM:token}
+
+# 令牌里各字段的名字：文件地址、多图地址、文件名、水印文字、是否强制重新转换
+# 其余水印参数（watermarkXSpace、watermarkYSpace、watermarkFont、watermarkFontsize、watermarkColor、
+# watermarkAlpha、watermarkWidth、watermarkHeight、watermarkAngle）在令牌里用与请求参数相同的名字
+signed.preview.claim.url = ${KK_SIGNED_PREVIEW_CLAIM_URL:url}
+signed.preview.claim.urls = ${KK_SIGNED_PREVIEW_CLAIM_URLS:urls}
+signed.preview.claim.filename = ${KK_SIGNED_PREVIEW_CLAIM_FILENAME:fullfilename}
+signed.preview.claim.watermark = ${KK_SIGNED_PREVIEW_CLAIM_WATERMARK:watermarkTxt}
+signed.preview.claim.force = ${KK_SIGNED_PREVIEW_CLAIM_FORCE:forceUpdatedCache}
+
+# 其余水印参数和 currentUrl 在令牌里的字段名映射，格式：请求参数名:令牌字段名，多个用逗号分隔，默认为default（同名）
+# 例如 watermarkAlpha:wmAlpha,currentUrl:cur。上面五项单独配置的字段不走这张表，写了也以单独那项为准
+signed.preview.claim.map = ${KK_SIGNED_PREVIEW_CLAIM_MAP:default}
+
+# 令牌里表示用途的字段名，以及三种令牌各自的用途值：接入方签发的预览令牌、
+# kkFileView 自己签发的压缩包令牌和取件令牌。三个值必须互不相同，否则签名预览拒绝全部请求、也不签发自己的令牌
+signed.preview.claim.use = ${KK_SIGNED_PREVIEW_CLAIM_USE:use}
+signed.preview.use.preview = ${KK_SIGNED_PREVIEW_USE_PREVIEW:preview}
+signed.preview.use.archive = ${KK_SIGNED_PREVIEW_USE_ARCHIVE:archive}
+signed.preview.use.fetch = ${KK_SIGNED_PREVIEW_USE_FETCH:fetch}
+
+# 预览令牌是否必须写用途，默认为false（不写用途字段的令牌也当作预览令牌）
+signed.preview.use.required = ${KK_SIGNED_PREVIEW_USE_REQUIRED:false}
+
+# 开启签名预览后仍允许浏览器自己带的请求参数，多个用逗号分隔，其余参数一律丢弃
+# 可以限定取值：officePreviewType=image|pdf|html,page 表示 officePreviewType 只放过这三个值（区分大小写，
+# 值不在其中或同一参数给了多个值时丢弃这个参数，不拒绝整个请求），page 任意值
+# 由令牌决定的参数（文件地址、水印、强制重新转换等）写进这里也不会生效
+signed.preview.allow.params = ${KK_SIGNED_PREVIEW_ALLOW_PARAMS:officePreviewType,tifPreviewType,page,highlightall,filePassword,key}
+
+# kkFileView 自己签发的令牌（压缩包内文件、取原文件）的有效期，单位秒
+signed.preview.ttl = ${KK_SIGNED_PREVIEW_TTL:600}
+
+# 压缩包令牌、取件令牌各自的有效期，单位秒，默认为default（使用上面的 signed.preview.ttl）
+signed.preview.archive.ttl = ${KK_SIGNED_PREVIEW_ARCHIVE_TTL:default}
+signed.fetch.ttl = ${KK_SIGNED_FETCH_TTL:default}
+
+# 校验有效期时允许的时钟误差，单位秒
+signed.preview.leeway = ${KK_SIGNED_PREVIEW_LEEWAY:30}
+
+# 取原文件时是否附带 kkFileView 自己签发的令牌，默认为false（关闭），与签名预览各自独立开关
+# 开启后用 http/https 下载原文件时在下面的请求头里带一枚令牌，密钥与算法同上，
+# 载荷为 {"use":"fetch","url":"<本次请求的地址>","iat":...,"exp":...}，文件来源一方可据此确认请求来自本服务
+signed.fetch.enabled = ${KK_SIGNED_FETCH_ENABLED:false}
+signed.fetch.header = ${KK_SIGNED_FETCH_HEADER:kk-fetch-token}
+
+# 请求头的值在令牌前面加的前缀，默认为default（不加）。不为空时与令牌之间用一个空格隔开，
+# 例如请求头配成 Authorization、前缀配成 Bearer，发出的就是 Authorization: Bearer <令牌>
+signed.fetch.header.prefix = ${KK_SIGNED_FETCH_HEADER_PREFIX:default}
+
+# 取件令牌里「本次请求的地址」放在载荷的哪个字段，支持用点分隔的嵌套对象，
+# 例如 payload.url 签成 {"payload":{"url":"<地址>"}}
+signed.fetch.claim.url = ${KK_SIGNED_FETCH_CLAIM_URL:url}
+
 # AES加密密钥，必须为16位字符
 # 启用AES加密时，接入方需使用相同的密钥
 # 用于敏感数据传输加密