# kkFileView

**Repository Path**: liuchangng/file-online-preview

## Basic Information

- **Project Name**: kkFileView
- **Description**: 使用spring boot打造文件文档在线预览项目解决方案，支持doc、docx、ppt、pptx、xls、xlsx、zip、rar、mp4、mp3以及众多类文本如txt、html、xml、java、properties、sql、js、md、json、conf、ini、vue、php、py、bat、gitignore等文件在线预览
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://kkfileview.keking.cn
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 9260
- **Created**: 2021-05-21
- **Last Updated**: 2024-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# file-online-preview
### 快速开始
> 项目使用技术
- spring boot： [spring boot开发参考指南](http://www.kailing.pub/PdfReader/web/viewer.html?file=springboot)
- freemarker
- redisson 
- jodconverter
> 依赖外部环境
- redis (可选，默认不用)
- OpenOffice 或者 LibreOffice( Windows 下已内置，Linux 脚本启动模式会自动安装，Mac OS 下需要手动安装)

1. 第一步：pull 项目 https://github.com/kekingcn/file-online-preview.git

3. 第二步：运行 ServerMain 的 main 方法，服务启动后，访问 http://localhost:8012/
   会看到如下界面，代表服务启动成功
   

<img src="https://gitee.com/uploads/images/2017/1213/100221_ea15202e_492218.png" alt="输入图片说明" title="屏幕截图.png" style="zoom:80%;" />

# 部署指南

## 1. 环境要求 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#1.-环境要求)

1. Java: 1.8+
2. OpenOffice或LiberOffice(Windows下已内置，CentOS或Ubuntu下会自动下载安装，MacOS下需要自行安装)

## 2. 部署运行 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#2.-部署运行)

### 1). 物理机或虚拟机上运行 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#1).-物理机或虚拟机上运行)

1. 从 [码云发行版本](https://gitee.com/kekingcn/file-online-preview/releases) 下载最新版发行包
2. 解压kkFileView-x.x.x文件（Windows用.zip包，Linux/MacOS用.tar.gz包）
3. 打开解压后文件夹的bin目录，运行startup脚本（Windows下以管理员身份运行`startup.bat`，Linux以root用户运行`startup.sh`）
4. 浏览器访问本机8012端口 [http://127.0.0.1:8012](http://127.0.0.1:8012/) 即可看到项目演示用首页

### 2). Docker容器环境环境运行 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#2).-docker容器环境环境运行)

- 拉取镜像

```bash
docker pull keking/kkfileview
```

- 运行

```bash
docker run -it -p 8012:8012 keking/kkfileview
```

- 浏览器访问容器8012端口 `http://xxx.xxx.xxx.xxx:8012` 即可看到项目演示用首页

## 3. 项目接入使用 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#3.-项目接入使用)

当您的项目内需要预览文件时，只需要调用浏览器打开本项目的预览接口，并传入须要预览文件的url，示例如下：

### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#3.x.x-版本)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));
```

### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/production.html#2.x.x-及以下版本)

```javascript
var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));
```

详细使用说明见 [使用指南](https://kkfileview.keking.cn/zh-cn/docs/usage.html)



# 使用指南

当您的项目内需要预览文件时，只需要调用浏览器打开本项目的预览接口，并传入须要预览文件的url。

注意，如果要预览的url里包含需要转义的特殊字符，如下表格，请使用encodeURIComponent(url)转义

| 符号 | url中转义结果                | 转义码 |
| :--- | :--------------------------- | :----- |
| +    | URL 中+号表示空格            | %2B    |
| 空格 | URL中的空格可以用+号或者编码 | %20    |
| /    | 分隔目录和子目录             | %2F    |
| ？   | 分隔实际的URL和参数          | %3F    |
| %    | 指定特殊字符                 | %25    |
| #    | 表示书签                     | %23    |
| &    | URL 中指定的参数间的分隔符   | %26    |
| =    | URL 中指定参数的值           | %3D    |

## 1. 普通文件下载url预览 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#1.-普通文件下载url预览)

### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.x.x-版本)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(url)));
```

### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.x.x-及以下版本)

```javascript
var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(url));
```

## 2. http/https下载流url预览 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.-http%2Fhttps下载流url预览)

很多系统内不是直接暴露文件下载地址，而是请求通过id、code等参数到通过统一的接口，后端通过id或code等参数定位文件，再通过OutputStream输出下载，此时下载url是不带文件后缀名的，预览时需要拿到文件名，传一个参数`fullfilename=xxx.xxx`来指定文件名，示例如下

### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.x.x-版本-1)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1'; //要预览文件的访问地址
var previewUrl = originUrl + '&fullfilename=test.txt'
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));
```

### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.x.x-及以下版本-1)

```javascript
var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1'; //要预览文件的访问地址
var previewUrl = originUrl + '&fullfilename=test.txt'
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));
```

## 3. FTP下载url预览 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.-ftp下载url预览)

### 1). FTP匿名访问 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#1).-ftp匿名访问)

如果要预览的FTP url是可以匿名访问的（不需要用户名密码），则可以直接通过下载url预览，示例如下

#### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.x.x-版本-2)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(url)));
```

#### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.x.x-及以下版本-2)

```javascript
var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(url));
```

### 2). 非匿名访问，确定只有访问一台FTP服务器 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2).-非匿名访问，确定只有访问一台ftp服务器)

如果预览服务只访问一台FTP服务器，只需要在配置文件中 [配置FTP链接信息](https://kkfileview.keking.cn/zh-cn/docs/config.html) ，则可以直接通过下载url预览，示例如下

#### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.x.x-版本-3)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(url)));
```

#### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.x.x-及以下版本-3)

```javascript
var url = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(url));
```

### 3). 非匿名访问，不只访问一台FTP服务器 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3).-非匿名访问，不只访问一台ftp服务器)

如果预览服务要访问多台FTP服务器，且用户名密码不一致，可以通过在url中加入用户名密码等参数预览(url参数中的优化于配置文件中的)，示例如下

#### 3.x.x 版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#3.x.x-版本-4)

```javascript
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>

var originUrl = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
var previewUrl = originUrl + '?ftp.username=xx&ftp.password=xx&ftp.control.encoding=xx';
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(Base64.encode(previewUrl)));
```

#### 2.x.x 及以下版本 [#](https://kkfileview.keking.cn/zh-cn/docs/usage.html#2.x.x-及以下版本-4)

```javascript
var originUrl = 'ftp://127.0.0.1/file/test.txt'; //要预览文件的访问地址
var previewUrl = originUrl + '?ftp.username=xx&ftp.password=xx&ftp.control.encoding=xx';
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(previewUrl));
```

更多使用方面的问题，详见[常见问题](https://kkfileview.keking.cn/zh-cn/docs/faq.html)



# 配置说明

打开conf目录，下面有一个application.properties配置文件，有部分配置是可以在程序运行中变更的，其他的变更需要重新启动程序

## 不可动态配置，需要重启生效部分 [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#不可动态配置，需要重启生效部分)

### server.context-path [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#server.context-path)

说明：kkFileView运行时tomcat的ServletContext 默认值：`/` 示例：`server.context-path = /preview`

### file.dir [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#file.dir)

说明：预览文件存储路径，当有大量文件要预览时需要保证该目录所在磁盘有足够的容量
默认值：程序根目录下的file目录下
示例：`file.dir = D:\\kkFileview\\`

### office.home [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#office.home)

说明：openoffice或libreoffice安装目录，一般情况下不用配置，如果需要使用自己安装openoffice或libreoffice，可以自行指定
默认值：不同操作系统各自对应的默认安装目录
示例：`office.home = C:\\Program Files (x86)\\OpenOffice 4`

### cache.type [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#cache.type)

说明：缓存实现方式，默认为内嵌[RocksDB](https://rocksdb.org/)实现，可选项：'default', 'jdk', 'redis'

- default：默认实现，使用RocksDB存储引擎，使用磁盘存储，会占用少量磁盘空间；Windows下需要使用管理员身份启动程序
- jdk：java对象实现，使用纯内存对象存储，速度极快，外部依赖最少，调试部署方便，会占用内存，推荐调试时和预览文件量不是很大时（<50万）使用，预览文件量极大或有大量压缩包时不推荐使用
- redis: redis作为缓存实现，速度快，不占用内存和磁盘空间，但是需要有外部redis服务

当配置为redis实现时，需要同时配置redis连接相关配置，如下：

```properties
spring.redisson.address = 127.0.0.1:6379
spring.redisson.password = xxxxxx
```

### cache.clean [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#cache.clean)

说明：是否需要自动定时清理缓存及预览过的文件，默认开启（如果不清理缓存，同一个url下如果文件发生变更是不会重新拉取新的文件再去预览的），开启的情况下会在每天凌晨3点清理所有缓存及预览文件，推荐预览量不大，对预览速度要求不高，且同一url下文件经常更新的用户开启，预览量大、预览速度要求高的用户不推荐开启

- true: 默认值，开启
- false: 不开启
- 空：注释掉，不开启

## 可在运行时动态改变部分 [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#可在运行时动态改变部分)

### base.url [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#base.url)

说明：提供预览服务的地址，默认从接收请求url读，如果使用nginx等反向代理，需要手动设置为通过nginx访问预览服务的地址
默认值：未设置
示例：`base.url = https://file.keking.cn/preview`
例如nginx的访问地址为 `https://file.keking.cn` 想要使用 `https://file.keking.cn/preview/`来做预览，kkFileView部署在内网`192.168.1.233`服务器上，需要在nginx中添加反向代理如下

```propertis
location /preview {
    proxy_pass 192.168.1.233:8012;
}
```

修改kkFileView的配置文件如下两项

```propertis
server.context-path = /preview
base.url = https://file.keking.cn/preview
```

使用如下地址来访问预览页面

```javascript
var url = 'https://file.keking.cn/file/test.txt'; //要预览文件的访问地址
window.open('https://file.keking.cn/preview/onlinePreview?url='+encodeURIComponent(url));
```

### trust.host [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#trust.host)

说明：信任站点，设置了之后，会限制只能预览来自信任站点列表的文件，默认不限制，多个用','隔开， 默认值：未设置 示例：`trust.host = file.keking.cn,kkfileview.keking.cn`

### simText [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#simtext)

说明：用来配置预览方式为纯文本的文件类型
默认值：txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd

### media [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#media)

说明：用来配置预览方式为多媒体（视频、音频）的文件类型
默认值：mp3,wav,mp4,flv

### office.preview.type [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#office.preview.type)

说明：office文件（doc、docx、ppt、pptx）、pdf 文件预览方式，默认为图片方式，预览时也有按钮相互切换，可选项：'image', 'pdf'

- image: 默认预览方式，将office文件每一页后台转成图片，前台懒加载（只加载当前页面内容），推荐预览文件大且前台加载慢的时候使用
- pdf: 统一转成pdf加一次加载，推荐内网访问，网速快时使用

### office.preview.switch.disabled [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#office.preview.switch.disabled)

说明：是否关闭office预览页面上的切换开关，默认不关闭
默认值：false

### pdf.download.disable [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#pdf.download.disable)

说明：是否禁止下载转换生成的pdf文件，默认禁止
默认值：true

### file.upload.disable [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#file.upload.disable)

说明：是否禁用演示首页文件上传，默认不禁止
默认值：false

### ftp.username [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#ftp.username)

说明：预览url为FTP地址时，默认的ftp用户名，可过url参数中的`ftp.username=xxx`覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：null

### ftp.password [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#ftp.password)

说明：预览url为FTP地址时，默认的ftp密码，可过url参数中的`ftp.password=xxx`覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：null

### ftp.control.encoding [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#ftp.control.encoding)

说明：预览源为FTP时, FTP连接默认的ControlEncoding，根据FTP服务器的操作系统选择，Linux一般为设置UTF-8，Windows一般为设置GBK。可过url参数中的`ftp.control.encoding=xxx`覆盖，即优先使用url参数中的，如果url参数中没有，则取本配置的
默认值：UTF-8

### watermark.txt [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.txt)

默认水印内容，如需取消水印，内容设置为空即可，例如：`watermark.txt = ${WATERMARK_TXT:}`
默认值：''

### watermark.x.space [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.x.space)

水印x轴间隔
默认值：10

### watermark.y.space [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.y.space)

水印y轴间隔
默认值：10

### watermark.font [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.font)

水印字体
默认值：微软雅黑

### watermark.fontsize [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.fontsize)

水印字体大小
默认值：18px

### watermark.color [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.color)

水印字体颜色
默认值：black

### watermark.alpha [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.alpha)

水印透明度，要求设置在大于等于0.005，小于1
默认值：0.2

### watermark.width [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.width)

水印宽度
默认值：180

### watermark.height [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.height)

水印高度 默认值：80

### watermark.angle [#](https://kkfileview.keking.cn/zh-cn/docs/config.html#watermark.angle)

水印倾斜度数，要求设置在大于等于0，小于90
默认值：10



# 常见问题

### Q：怎么把这个项目集成到我的项目里 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：怎么把这个项目集成到我的项目里)

A：不需要集成，本项目只需要独立部署，向外提供http预览服务（外部系统只需要访问本项目预览接口并传入需要预览文件的url，就可以打开预览页面）

### Q：怎么把这个项目放Tomcat里运行 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：怎么把这个项目放tomcat里运行)

A：不需要放进Tomcat里，编译好的发行包为zip包，直接解压运行一键启动脚本就可以完成部署（需要有java环境）具体部署步骤详见：[部署指南](https://kkfileview.keking.cn/zh-cn/docs/production.html)

### Q：预览并发问题&预览首次打开慢 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：预览并发问题%26预览首次打开慢)

A：可使用预览转码队列，将需要预览的文件url放入队列中，提前进行转码，本地访问接口为：`http://127.0.0.1:8012/addTask?url=http://xxx/test.txt` (url参数为需要需要的文件访问地址)

### Q：预览乱码 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：预览乱码)

A：乱码问题可能有如下两个原因

- 字体问题
  大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下： 下载如下字体包 http://kkfileview.keking.cn/fonts.zip 文件解压完整拷贝到Linux下的 /usr/share/fonts目录。然后依次执行mkfontscale 、mkfontdir 、fc-cache使字体生效
- 编码问题

编码问题分为如下两方面

1. Excel文件编码格式 Excel软件是可以选择用什么编码去保存文件的
   ![Excel编码](https://kkfileview.keking.cn/img/faq/excel-encoding.png)
   目前我们读取Eecel文件是用的服务器操作系统默认编码，可以通过在启动脚本里加入如`-Dfile.encoding=UTF-8`指定，详见 [码云项目首页评论区讨论](https://gitee.com/kekingcn/file-online-preview#note_1841612)
2. 生成html网页编码格式
   生成html网页也是用的服务器操作系统默认编码(java系统属性：`sun.jnu.encoding`)，比如用浏览器用手动更改编码格式为`utf-8`或`gbk`打开没有问题，但是用浏览器默认编码就有问题，此时可调整系统配置文件中的配置项`converted.file.charset`可解决此类乱码问题, 详见 [编码配置](https://kkfileview.keking.cn/zh-cn/docs/config.html)

### Q：Linux下运行startup.sh脚本报错：/bin/bash^M: bad interpreter: No such file or directory [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：linux下运行startup.sh脚本报错：%2Fbin%2Fbash^m%3A-bad-interpreter%3A-no-such-file-or-directory)

A：一般为在Windows下用IDEA导入项目编译时，默认使用Windows(\r\n)下的文件换行符导致的，导入项目时设置默认换行符为Unix类操作系统换行符再编译即可（File->Settings->Editor->Code Style->Line separator 选择Unix and MacOs(\n)）
![设置换行符](https://kkfileview.keking.cn/img/faq/line-separator.png)

### Q：Linux下启动项目后日志报错：org.artofsolving.jodconverter.office.OfficeException: office process died with exit code 127 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：linux下启动项目后日志报错：org.artofsolving.jodconverter.office.officeexception%3A-office-process-died-with-exit-code-127)

A：操作系统缺少libXext.so.6包，请自行下载安装：[http://kkfileview.keking.cn/fonts.zip](https://pkgs.org/download/libXext.so.6)

### Q：启动项目后日志报错：java.lang.IllegalStateException: a process with acceptString 'socket,host=127.0.0.1,port=8100' is already running; pid 26468 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：启动项目后日志报错：java.lang.illegalstateexception%3A-a-process-with-acceptstring-'socket%2Chost%3D127.0.0.1%2Cport%3D8100'-is-already-running%3B-pid-26468)

A：有正在运行的openoffice进程，kill掉相关进程再重新启动

### Q：Windows系统下启动报错：Error creating bean with name 'cacheServiceRocksDBImpl' [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：windows系统下启动报错：error-creating-bean-with-name-'cacheservicerocksdbimpl')

A：本项目默认使用内嵌RocksDB存储引擎作缓存，需要以管理员身份运行，或配置使用其他缓存实现，详见：[缓存配置](https://kkfileview.keking.cn/zh-cn/docs/config.html)

### Q：如何水印文本内容动态传值 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：如何水印文本内容动态传值)

A：在预览url后面加上参数`&watermarkTxt`即可
例如：

```javascript
var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url=' + encodeURIComponent(url) + '&watermarkTxt=' + encodeURIComponent('动态水印'));
```

### Q：使用nginx代理时预览出现异常 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：使用nginx代理时预览出现异常)

A：一般是nginx和kkFileView配置有问题
例如nginx的访问地址为 `https://file.keking.cn` 想要使用 `https://file.keking.cn/preview/`来做预览，kkFileView部署在内网`192.168.1.233`服务器上，需要在nginx中添加反向代理如下：

```propertis
location /preview {
    proxy_pass 192.168.1.233:8012;
}
```

修改kkFileView的配置文件如下两项

```propertis
server.context-path = /preview
base.url = https://file.keking.cn/preview
```

使用如下地址来访问预览页面

```javascript
var url = 'https://file.keking.cn/file/test.txt'; //要预览文件的访问地址
window.open('https://file.keking.cn/preview/onlinePreview?url='+encodeURIComponent(url));
```

### Q：使用docker部署时如何指定配置文件中的配置项 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：使用docker部署时如何指定配置文件中的配置项)

A：针对docker运行的用户，所有配置项可以使用设置相应的环境变量来配置
环境变量的KEY为[配置文件](https://gitee.com/kekingcn/file-online-preview/blob/master/jodconverter-web/src/main/config/application.properties)中每个配置项后`${}`中的KEY
例如，使用docker运行要指定`base.url`为`http://file.keking.cn`，docker运行命令如下

```sh
docker run -it -d -p 8012:8012 -e BASE_URL="http://file.keking.cn" keking/kkfileview:v2.2.1
```

### Q：使用内网预览时没有问题，但是使用外网预览有问题 [#](https://kkfileview.keking.cn/zh-cn/docs/faq.html#q：使用内网预览时没有问题，但是使用外网预览有问题)

A：一般是公司网络使用的路由器不支持或没开启域内NAT，kkFileView无法通过外网地址下载要预览的文件
例如kkFileView部署在公司192.168.1.233服务器上，本地访问`http://192.168.1.233:8012`可以正常预览
公司运维把192.168.1.233的8012端口暴露到公网ip或域名(`http://xxx.xxx.xxx:8012`)，公网打首页也正常，但是预览就出错
这种一般是因为公司主路由器不支持或没开启域内NAT [参考资料](https://www.zhihu.com/question/266194635/answer/310560325)



# 编译指南

## 1. 环境要求 [#](https://kkfileview.keking.cn/zh-cn/docs/build.html#1.-环境要求)

1. Java: 1.8+
2. Maven：3.4+

## 2. 下载代码&编译打包 [#](https://kkfileview.keking.cn/zh-cn/docs/build.html#2.-下载代码%26编译打包)

### 1. 从码云仓库拉取代码 [#](https://kkfileview.keking.cn/zh-cn/docs/build.html#1.-从码云仓库拉取代码)

```bash
git clone https://gitee.com/kekingcn/file-online-preview.git
```

### 2. 使用maven编译打包 [#](https://kkfileview.keking.cn/zh-cn/docs/build.html#2.-使用maven编译打包)

```bash
cd file-online-preview
mvn clean package -DskipTests
```

### 3. 使用docker构建镜像 [#](https://kkfileview.keking.cn/zh-cn/docs/build.html#3.-使用docker构建镜像)

```bash
docker build -t keking/kkfileview:v4.0.0 .
```

# 应用监控
### 1,添加依赖
```
<!-- 应用监控 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```

### 2,默认暴露端点
``` 
访问地址增加/actuator

# 查看所有暴露的端点
http://127.0.0.1:8012/actuator 
http://127.0.0.1:8012/actuator/health
http://127.0.0.1:8012/actuator/info
```

### 3,配置端点
#### 3.1,JMX暴露属性
```
management.endpoints.jmx.exposure.exclude=
management.endpoints.jmx.exposure.include=*
```
#### 3.2,HTTP暴露属性
```
management.endpoints.web.exposure.exclude=
management.endpoints.web.exposure.exclude=info,health
```
#### 3.3,配置实例
+ 打开所有监控点
``` 
management.endpoints.web.exposure.include=*
```
+ 打开部分监控点,多个端点用","分割
``` 
management.endpoints.web.exposure.include=health,info,trace,beans
```
+ 修改默认监控点路径
``` 
management.endpoints.web.base-path=/minitor
```
+ /health端点
``` 
应用健康信息
management.endpoint.health.show-details=always

说明:
never	不展示详细信息，up或者down的状态，默认配置
when-authorized	详细信息将会展示给通过认证的用户。授权的角色可以通过management.endpoint.health.roles配置
always	对所有用户暴露详细信息

禁用某个组件的健康监测:
management.health.mongo.enabled=false

禁用所有自动配置的健康指示器:
management.health.defaults.enabled=false

自定义Health Indicator
需要实现HealthIndicator 接口或者继承AbstractHealthIndicator类
@Component
public class CustomHealthIndicator extends AbstractHealthIndicator {

    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        // 使用 builder 来创建健康状态信息
        // 如果你throw 了一个 exception，那么status 就会被置为DOWN，异常信息会被记录下来
        builder.up()
                .withDetail("app", "这个项目很健康")
                .withDetail("error", "Nothing, I'm very good");
    }
}
```
+ /metrics端点
``` 
/metrics端点用来返回当前应用的各类重要度量指标，比如：内存信息、线程信息、垃圾回收信息、tomcat、数据库连接池等

指标详情查看
http://localhost:8012/actuator/metrics/jvm.memory.max
```
+ /loggers端点
``` 
暴露了我们程序内部配置的所有logger的信息

访问单独的某个logger
http://127.0.0.1:8012/actuator/loggers/io

动态修改日志级别
url: http://127.0.0.1:8012/actuator/loggers/root
method: post
body: {"configuredLevel": "DEBUG"}
ps: 如果想重置成默认值，把value 改成 null
```
+ /info端点
``` 
用来展示程序的信息.默认情况下，该端点只会返回一个空的json内容
# 在 maven 项目中你可以直接用下列方式引用 maven properties的值
info.app.encoding=@project.build.sourceEncoding@
info.app.java.source=@java.version@
info.app.java.target=@java.version@
```
+ /beans端点
``` 
返回Spring 容器中所有bean的别名、类型、是否单例、依赖等信息
```
+ /heapdump端点
``` 
自动生成一个 Jvm 的堆文件 heapdump。可以使用 JDK 自带的VisualVM 打开此文件查看内存快照。
```
+ /threaddump端点
``` 
主要展示了线程名、线程ID、线程的状态、是否等待锁资源、线程堆栈等信息
```
+ /shutdown端点
``` 
可以优雅关闭 Spring Boot 应用
management.endpoint.shutdown.enabled=true

url: http://127.0.0.1:8012/actuator/shutdown
method: post
```

### 4,使用Spring Security保护端点
+ 依赖
``` 
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
</dependency>
```
+ 用户名密码
``` 
# Spring Security Default user name and password
spring.security.user.name=actuator
spring.security.user.password=actuator
spring.security.user.roles=ACTUATOR_ADMIN
```
+ 配置
``` 
 import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.boot.actuate.context.ShutdownEndpoint;
import org.springframework.boot.autoconfigure.security.servlet.PathRequest;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class ActuatorSecurityConfig extends WebSecurityConfigurerAdapter {

    /*
     * version1:
     * 1. 限制 '/shutdown'端点的访问，只允许ACTUATOR_ADMIN访问
     * 2. 允许外部访问其他的端点
     * 3. 允许外部访问静态资源
     * 4. 允许外部访问 '/'
     * 5. 其他的访问需要被校验
     * version2:
     * 1. 限制所有端点的访问，只允许ACTUATOR_ADMIN访问
     * 2. 允许外部访问静态资源
     * 3. 允许外部访问 '/'
     * 4. 其他的访问需要被校验
     */

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // version1
//        http
//                .authorizeRequests()
//                    .requestMatchers(EndpointRequest.to(ShutdownEndpoint.class))
//                        .hasRole("ACTUATOR_ADMIN")
//                .requestMatchers(EndpointRequest.toAnyEndpoint())
//                    .permitAll()
//                .requestMatchers(PathRequest.toStaticResources().atCommonLocations())
//                    .permitAll()
//                .antMatchers("/")
//                    .permitAll()
//                .antMatchers("/**")
//                    .authenticated()
//                .and()
//                .httpBasic();

        // version2
        http
                .authorizeRequests()
                .requestMatchers(EndpointRequest.toAnyEndpoint())
                    .hasRole("ACTUATOR_ADMIN")
                .requestMatchers(PathRequest.toStaticResources().atCommonLocations())
                    .permitAll()
                .antMatchers("/")
                    .permitAll()
                .antMatchers("/**")
                    .authenticated()
                .and()
                .httpBasic();
    }
}

```
### 5,Prometheus数据采集
+ 1,下载
``` 
https://prometheus.io/download/
```
+ 2,安装
``` 
解压
```
+ 3,启动
``` 
配置文件 prometheus.yml
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: "prometheus"

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
      - targets: ["localhost:9090"]
  
  #监控kkFileView应用
  - job_name: "kkFileView"
    metrics_path: '/actuator/prometheus' # 指标获取路径
    scrape_interval: 15s # 间隔
    #basic_auth: # Spring Security basic auth 
    #  username: 'actuator'
    #  password: 'actuator'
    static_configs:
     - targets: ['127.0.0.1:8012'] # 实例的地址，默认的协议是http

启动命令
prometheus.exe --config.file=prometheus.yml
```
+ 4,安装node_exporter
``` 
windows: https://github.com/prometheus-community/windows_exporter
```
### 6,Grafana可视化
+ 1,下载
``` 
https://grafana.com/grafana/download?pg=get&plcmt=selfmanaged-box1-cta1
```
+ 2,安装
``` 
https://dl.grafana.com/enterprise/release/grafana-enterprise-8.1.5.windows-amd64.zip
解压
```
+ 3,启动
``` 
bin/grafana-server.exe
```