Integration Guide

5 分钟把 kkFileView 接进你的业务项目。

这里按常见接入场景提供示例，方便你直接按需选用。默认假设服务地址为 https://preview.luokuiai.com:443/。

HTTP / HTTPS FTP AES-GCM 附加参数

URL 所有预览能力统一汇总到 `onlinePreview` 入口。

Base64 普通接入默认对原始文件地址做 Base64 编码后再传入。

参数扩展 支持页码、高亮、水印、密码、跨域、AES-GCM 和秘钥等控制项。

Quick Start

接入思路

推荐入口

前端只需要拿到可访问的文件 URL，然后把它编码后拼到 `https://preview.luokuiai.com:443/onlinePreview` 上即可。对于大多数业务系统，这是最快的落地路径。

普通 HTTP/HTTPS 文件地址：直接 Base64 编码后传入。
下载流接口没有后缀名：补充 `fullfilename=xxx.xxx`。
鉴权或加密场景：附加 Basic、FTP、AES-GCM 等参数。

HTTP / HTTPS

普通文件地址预览

适用于系统已经直接暴露出可下载文件地址的情况。前端只需要编码后打开新窗口。

                        var url = 'http://127.0.0.1:8080/file/test.txt';
window.open('https://preview.luokuiai.com:443/onlinePreview?url=' + encodeURIComponent(base64Encode(url)));
                    

Streaming

流式接口预览

很多业务系统通过 `fileId`、`code` 等参数走统一下载接口，此时原始 URL 没有后缀名，需要额外指定完整文件名。

                        var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1';
var previewUrl = originUrl + '&fullfilename=test.txt';
window.open('https://preview.luokuiai.com:443/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

FTP

FTP 资源预览

FTP 如果允许匿名访问，可以直接预览；如果需要认证，则把连接参数拼到 URL 后面传入。

                        // 匿名 FTP
var url = 'ftp://127.0.0.1/file/test.txt';
window.open('https://preview.luokuiai.com:443/onlinePreview?url=' + encodeURIComponent(Base64.encode(url)));

// 认证 FTP
var originUrl = 'ftp://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?ftp.control.port=21&ftp.username=admin&ftp.password=123456&ftp.control.encoding=utf8';
window.open('https://preview.luokuiai.com:443/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

Basic Auth

带 Basic 鉴权的 HTTP 资源

如果文件源本身需要用户名和密码，可以直接把 Basic 鉴权参数拼到地址中，再交给 kkFileView。

                        var originUrl = 'http://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?basic.name=admin&basic.pass=123456';
window.open('https://preview.luokuiai.com:443/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

AES-GCM

业务后端加密接入

共享密钥只保存在业务后端和 kkFileView。密文格式为 Base64URL(12字节随机IV || 密文 || 16字节认证标签)，配置的密钥先用 SHA-256 派生 AES-256 密钥。不要在业务前端保存共享密钥。

                        import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLEncoder;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Base64;

private static final SecureRandom RANDOM = new SecureRandom();

static String aesGcmEncrypt(String url, String secret) throws Exception {
  byte[] iv = new byte[12];
  RANDOM.nextBytes(iv);
  byte[] key = MessageDigest.getInstance("SHA-256")
      .digest(secret.getBytes(StandardCharsets.UTF_8));
  Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
  cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(key, "AES"), new GCMParameterSpec(128, iv));
  byte[] encrypted = cipher.doFinal(url.getBytes(StandardCharsets.UTF_8));
  return Base64.getUrlEncoder().withoutPadding().encodeToString(
      ByteBuffer.allocate(iv.length + encrypted.length).put(iv).put(encrypted).array());
}

String url = "http://127.0.0.1/file/test.txt";
String encrypted = aesGcmEncrypt(url, System.getenv("KK_SOURCE_URL_SECRET"));
String previewUrl = "https://preview.luokuiai.com:443/onlinePreview?url="
    + URLEncoder.encode(encrypted, StandardCharsets.UTF_8) + "&encryption=aes";
                    

Parameters

预览参数

下面列出 onlinePreview 当前实际读取的公开参数。除“源地址参数”外，均附加在预览地址上。

预览入口

url: 必填。Base64 或 AES-GCM 编码后的原始文件地址。
key: 实例启用访问秘钥后传入。
encryption=aes: 声明 url 使用 AES-256-GCM 加密；未传时按 Base64 解码。
officePreviewType: Office/PDF 渲染模式：pdf、image、allImages 或 html。
forceUpdatedCache=true: 忽略已有转换缓存并重新生成。
filePassword: 加密 PDF 或 Office 文件的打开密码。
usePasswordCache=true: 允许加密文件复用转换缓存。
highlightall: PDF、文本、Markdown 和源码预览的高亮关键字。
kkagent=true: 由 kkFileView 代理读取跨域文件。

动态水印

watermarkTxt: 水印文本。
watermarkFullScreen=true: PDF 模式下，水印覆盖整个预览区及背景；默认只覆盖 PDF 页面。
watermarkXSpace / watermarkYSpace: 水印横向、纵向间距。
watermarkFont: 字体名称。
watermarkFontsize: 字号，例如 18px。
watermarkColor: 文字颜色。
watermarkAlpha: 透明度。
watermarkWidth / watermarkHeight: 单个水印区域的宽度、高度。
watermarkAngle: 旋转角度。

源地址参数（Base64/AES-GCM 编码前拼接）

fullfilename: 下载流 URL 没有扩展名时指定完整文件名。
basic.name / basic.pass: 源文件 HTTP Basic 鉴权账号和密码。
ftp.control.port: FTP 控制端口。
ftp.username / ftp.password: FTP 账号和密码。
ftp.control.encoding: FTP 文件名编码，例如 UTF-8 或 GBK。

请求头

kk-proxy-authorization: JSON 对象；代理下载源文件时，将其中的键值作为请求头转发。

page 和请求级 tifPreviewType 在当前版本没有完整生效，不建议业务接入依赖。

                        var url = 'http://127.0.0.1:8080/file/test.txt';
window.open(
  'https://preview.luokuiai.com:443/onlinePreview?url=' +
  encodeURIComponent(base64Encode(url)) +
  '&filePassword=123' +
  '&highlightall=kkfileview' +
  '&watermarkTxt=kkfileview' +
  '&kkagent=false' +
  '&key=123'
);
                    

Configuration

环境变量配置

只列出当前版本明确支持的环境变量，并关联对应的配置项与默认值；未映射环境变量的内部配置不在这里展示。

这里只展示配置结构和仓库默认值，不读取运行环境中的真实值；密钥、密码等敏感默认值已隐藏。

服务器基础配置 3 项

配置项环境变量默认值说明

server.port KK_SERVER_PORT 8012 服务器端口号，默认8012

server.servlet.context-path KK_CONTEXT_PATH / 应用上下文路径，默认为根路径 /

html.cache.max-age KK_HTML_CACHE_MAX_AGE 0 静态HTML页面缓存时间（秒），0表示每次使用前向服务器校验，修改后需重启

首页与文件管理配置 9 项

配置项环境变量默认值说明

home.page.enabled KK_HOME_PAGE_ENABLED true 是否展示首页、接入说明、版本记录等门户页面，默认为true（展示）

file.upload.disable KK_FILE_UPLOAD_DISABLE true 是否禁用首页文件上传功能，默认为true（禁用）

file.download.max-size KK_FILE_DOWNLOAD_MAX_SIZE 1GB 远程文件下载大小上限，支持 B、KB、MB、GB；默认1GB

beian KK_BEIAN default 网站备案信息，显示在首页底部，默认为空

home.pagenumber DEFAULT_HOME_PAGENUMBER 1 首页初始化加载的页码，默认为1（第一页）

home.pagesize DEFAULT_HOME_PAGSIZE 20 首页每页显示的文件数量，默认为20

delete.captcha KK_DELETE_CAPTCHA false 文件删除验证配置

delete.password KK_DELETE_PASSWORD false 删除文件密码，默认为false（禁用删除接口）

delete.source.file KK_DELETE_SOURCE_FILE true 是否删除转换后的源文件，默认为true（删除）

Office文档处理配置 11 项

配置项环境变量默认值说明

office.home KK_OFFICE_HOME default Office组件安装路径，默认为自动查找

office.pagerange KK_OFFICE_PAGERANGE false Office文档分页范围，支持动态配置

office.watermark KK_OFFICE_WATERMARK false Office文档水印功能，支持动态配置

office.quality KK_OFFICE_QUALITY 80 Office图片质量，1-100，默认80

office.maximageresolution KK_OFFICE_MAXIMAGERESOLUTION 150 Office图片最大分辨率，默认150

office.exportbookmarks KK_OFFICE_EXPORTBOOKMARKS true 导出Office书签，支持动态配置

office.exportnotes KK_OFFICE_EXPORTNOTES true 是否将Office文档中的批注作为PDF注释导出，默认为true（导出）

office.documentopenpasswords KK_OFFICE_DOCUMENTOPENPASSWORD true 加密文档生成的PDF是否添加密码，默认为true（添加）

office.type.web KK_OFFICE_TYPE_WEB web Excel文档(xlsx)的前端解析方式，默认为web（Web端解析）

office.preview.type KK_OFFICE_PREVIEW_TYPE pdf Office文档预览类型

office.preview.switch.disabled KK_OFFICE_PREVIEW_SWITCH_DISABLED true 是否关闭Office预览模式切换开关，默认为true（关闭切换）

CAD文件处理配置 3 项

配置项环境变量默认值说明

cad.preview.type KK_CAD_PREVIEW_TYPE svg CAD文件预览类型

cad.thread KK_CAD_THREAD 5 CAD文件处理线程数

cad.timeout KK_CAD_TIMEOUT 90 CAD文件处理超时时间（秒）

PDF文件处理配置 8 项

配置项环境变量默认值说明

pdf.presentationMode.disable KK_PDF_PRESENTATION_MODE_DISABLE true 是否禁止PDF演示模式，默认为true（禁止）

pdf.openFile.disable KK_PDF_OPEN_FILE_DISABLE true 是否禁止PDF文件菜单中的"打开文件"选项，默认为true（禁止）

pdf.print.disable KK_PDF_PRINT_DISABLE true 是否禁止PDF打印功能，默认为true（禁止）

pdf.download.disable KK_PDF_DOWNLOAD_DISABLE true 是否禁止PDF下载功能，默认为true（禁止）

pdf.bookmark.disable KK_PDF_BOOKMARK_DISABLE true 是否禁止PDF书签/大纲功能，默认为true（禁止）

pdf.disable.editing KK_PDF_DISABLE_EDITING false 是否禁止PDF编辑功能（注释、表单等），默认为false（允许编辑）

pdf.sidebar.open KK_PDF_SIDEBAR_OPEN false 是否默认打开PDF侧边栏（缩略图面板），默认为false（关闭）

pdf2jpg.dpi KK_PDF2JPG_DPI 144 PDF转图片的基准DPI，默认为144

TIF文件处理配置 1 项

配置项环境变量默认值说明

tif.preview.type KK_TIF_PREVIEW_TYPE tif TIF文件预览类型

媒体文件处理配置 3 项

配置项环境变量默认值说明

media KK_MEDIA mp3,wav,mp4,flv,mpd,m3u8,ts,mpeg,m4a 媒体文件类型（音频、视频）

convertMedias KK_CONVERTMEDIAS avi,mov,wmv,mkv,3gp,rm,mpeg 需要转换的媒体文件类型

media.convert.disable KK_MEDIA_CONVERT_DISABLE false 是否禁用视频格式转换功能，默认为false（禁用）

文件存储与缓存配置 10 项

配置项环境变量默认值说明

file.dir KK_FILE_DIR default 预览生成资源的存储路径，默认为应用根路径下的file目录

local.preview.dir KK_LOCAL_PREVIEW_DIR default 允许预览的本地文件夹路径，默认为default（禁止所有本地文件预览）

cache.enabled KK_CACHE_ENABLED true 是否启用缓存，支持动态配置

cache.type KK_CACHE_TYPE jdk 缓存实现类型，默认为jdk（使用JDK内置对象实现）

preview.token.secret KK_PREVIEW_TOKEN_SECRET （空） 预览资源令牌无有效期；多实例部署必须配置相同密钥，轮换密钥可使全部旧令牌失效

spring.redisson.address KK_SPRING_REDISSON_ADDRESS redis://127.0.0.1:6379 Redis连接地址，支持多种格式：

spring.redisson.password KK_SPRING_REDISSON_PASSWORD （空） Redis连接密码，无密码时留空

spring.redisson.database KK_SPRING_REDISSON_DATABASE 0 Redis数据库索引，默认为0（0-15）

cache.clean.enabled KK_CACHE_CLEAN_ENABLED true 缓存清理配置

cache.clean.cron KK_CACHE_CLEAN_CRON 0 0 3 * * ? 缓存自动清理时间，使用Quartz cron表达式，默认为每天凌晨3点执行

安全与访问控制配置 4 项

配置项环境变量默认值说明

base.url KK_BASE_URL default 提供预览服务的地址，默认从请求url读，如果使用nginx等反向代理，需要手动设置

trust.host KK_TRUST_HOST default 信任站点白名单配置，多个用','隔开

not.trust.host KK_NOT_TRUST_HOST default 不信任站点黑名单配置，多个用逗号隔开

prohibit KK_PROHIBIT exe,dll,dat 禁止访问的文件类型，安全限制

水印配置 10 项

配置项环境变量默认值说明

watermark.txt WATERMARK_TXT （空） 水印文本内容

watermark.x.space WATERMARK_X_SPACE 160 水印X轴间距

watermark.y.space WATERMARK_Y_SPACE 130 水印Y轴间距

watermark.font WATERMARK_FONT 微软雅黑 水印字体

watermark.fontsize WATERMARK_FONTSIZE 18px 水印字体大小

watermark.color WATERMARK_COLOR black 水印颜色

watermark.alpha WATERMARK_ALPHA 0.06 水印透明度，0.0-1.0

watermark.width WATERMARK_WIDTH 180 水印宽度

watermark.height WATERMARK_HEIGHT 80 水印高度

watermark.angle WATERMARK_ANGLE 10 水印旋转角度

权限与认证配置 1 项

配置项环境变量默认值说明

source.url.secret KK_SOURCE_URL_SECRET false 源地址 AES-256-GCM 共享密钥，false 表示禁用，请使用足够长的随机字符串

文件类型分类配置 1 项

配置项环境变量默认值说明

simText KK_SIMTEXT txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd 纯文本文件类型，直接显示

运行路径 1 项

配置项环境变量默认值说明

运行目录 KKFILEVIEW_BIN_FOLDER 当前工作目录 指定安装或运行目录，用于定位程序的 bin、config 等目录。