Repository navigation
Description
Background / 背景
把 kkFileView 嵌入自己的业务系统时,「谁能预览哪个文件」通常是业务系统说了算的:用户在业务系统里登录、有某个文件的查看权限,业务系统才给他一个预览链接。
目前预览链接本身就是全部信息:onlinePreview?url=... 加上水印、预览方式等参数。接入方希望能做到两点,现在没有现成的办法:
- 预览链接有有效期,过了时间就不能再用;
- 预览链接里「看哪个文件、带什么水印」这些内容由业务系统决定,拿到链接的人不能自己改。
#369 提的是相近的诉求(预览链接复制给别人之后别人也能打开)。当时讨论里给出的办法是在 kkFileView 前面加一层反向代理做鉴权,或者让文件下载接口自己校验 token;回复里也提到前一种做法在预览页后续发起的请求上不好处理。这两种办法都需要接入方在 kkFileView 之外自己搭一套东西,而且管不到水印、预览方式这些参数。
Proposal / 建议方案
增加一个可选的、默认关闭的「签名预览」功能。
1. 默认关闭。 不开启时行为与现在完全一样,现有接入方不需要做任何改动。
2. 开启后,预览入口只接受带有效签名令牌(JWT)的请求。
- 令牌由接入方的业务系统用双方约定的密钥签发,带有效期(
exp); - 决定「看什么、怎么看」的参数从令牌里取,而不是从请求参数里取:要预览的文件地址、文件名、水印文字、是否强制重新转换等;
- 浏览器自己可以带的参数只保留一份放行名单,限于只影响显示的参数,例如切换预览方式(PDF / 图片)、翻页;
- 令牌缺失、签名不对或已过期时,返回明确的提示页。
3. 压缩包内的文件。 压缩包预览页里点开包内文件的链接,由 kkFileView 自己签发一枚只对该压缩包有效的短期令牌。这样接入方只需要为压缩包本身签一次,不需要为包内每个文件再签一次。
4. 取原文件时可选地带上 kkFileView 自己签发的令牌。 kkFileView 去文件来源地址下载原文件时,可以选择在请求上附带一枚它自己签的短期令牌,文件来源一方可以据此确认「来取文件的是我信任的那台预览服务」。这一项单独一个开关,同样默认关闭。
5. 配置项(名称仅为示意,欢迎调整):
| 配置项 | 说明 |
|---|---|
| 是否开启 | 默认 false |
| 密钥 | 与接入方约定的密钥 |
| 算法 | 例如 HS256,可扩展 |
| 令牌所在的参数名 | 令牌放在哪个请求参数里 |
| 令牌内的字段名 | 文件地址、文件名、水印等字段各叫什么 |
| 有效期 | kkFileView 自己签发的令牌(压缩包内文件、取原文件)的有效时长 |
都按现有习惯支持 ${KK_XXX:默认值} 的环境变量写法。
Use Case / 使用场景
Scenario 1:业务系统里的附件预览。用户在业务系统里点击附件,业务系统校验权限后签发一枚 5 分钟有效的令牌,拼出预览链接并在 iframe 中打开。链接被复制出去之后,过了有效期就打不开。
Scenario 2:按用户加水印。业务系统把当前用户的姓名或工号写进令牌里的水印字段,预览页按令牌里的内容显示水印;水印内容不出现在可以随手修改的请求参数里。
Scenario 3:压缩包预览。业务系统只为压缩包签发一枚令牌,用户在预览页里展开目录、点开包内的文档或图片时,不需要再回业务系统换令牌。
Alternatives / 备选方案
- 在 kkFileView 前面加反向代理做鉴权(kkFileView安全性问题 #369 里提到的做法):能挡住未登录的访问,但预览页后续发起的请求不容易带上鉴权信息,也管不到水印、预览方式等参数。
- 让文件下载接口自己校验 token(kkFileView安全性问题 #369 里的另一种做法):需要接入方改造文件下载接口,同样管不到水印、预览方式等参数。
- 现有的
kk.key:是所有请求共用的一个固定值,没有有效期,也不与具体文件绑定。
如果维护者认为其中某种方式已经能满足上面的场景,也请指点一下推荐的用法。
Acceptance Criteria / 验收标准
- 功能默认关闭;关闭时所有现有行为、现有接口参数与现在一致,现有测试全部通过
- 开启后,带有效令牌的预览请求正常预览;令牌缺失、签名错误、已过期时返回明确的提示页
- 开启后,文件地址、水印等参数以令牌内的为准;请求参数里只有放行名单内的参数生效
- 开启后,压缩包预览页里点开包内文件可以正常预览,接入方不需要额外签发令牌
- 「取原文件时附带令牌」可单独开关,默认关闭
- 密钥、算法、参数名、字段名、有效期均可配置,并支持环境变量
- 配置文件注释与文档里有接入说明和签发令牌的示例
其它说明
如果维护者认可这个方向,我愿意贡献实现,并且愿意先在这里把设计讨论清楚再动手,例如:
- 配置项的命名;
- 令牌里的字段名与含义;
- 与现有
kk.key、trust.host/not.trust.host的关系(并存、互斥还是叠加); - 是否拆成几个较小的 PR 分步提交,方便 review。
Checklist / 提交前检查
- I have searched existing issues and did not find a duplicate feature request. / 我已搜索现有 issue,未发现重复功能建议
- I provided concrete use cases and expected behavior. / 我已提供具体使用场景和期望行为
Activity
github-actions commentedon Oct 13, 2026
@Copilot 请自动分诊并直接给出可执行建议(无需人工先介入):
Issue #805
标题:[FEATURE] 可选的「签名预览」:预览请求携带带有效期的签名令牌(JWT),默认关闭
链接:#805
补充说明 / Support Notice:
https://wx.zsxq.com/group/48844125114258