# kkFileView: Self-Hosted Document Preview Service for Over 20 File Formats

> kkFileView is a Spring Boot application that converts and renders documents, spreadsheets, presentations, CAD files, 3D models, images, and archives in the browser through a REST API. It runs as a standalone Java service and requires JDK 21 or newer.

**kekingcn/kkFileView** — Universal File Online Preview Project based on Spring-Boot

- Repository: https://github.com/kekingcn/kkFileView
- Website: https://kkview.cn
- Stars: 14,740 · Forks: 3,326
- Language: Java
- License: not declared
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/kekingcn-kkfileview

## What kkFileView Does and Who It Is For

kkFileView solves the problem of displaying documents in a browser without requiring users to download and open files locally. The README describes it as a document online preview project solution built on Spring Boot. It converts and renders files through a REST API that accepts a file URL and returns a preview URL the application can embed in an iframe.

The intended users are web application developers who need to display attachments, reports, or user-uploaded documents inside their applications without building conversion infrastructure. The REST API and the abstract file preview interface make it possible to integrate kkFileView as a backend service and extend it with additional formats.

The technology stack listed in the README is Spring Boot for the web framework, Freemarker for templating, Redisson for caching, and Jodconverter for Office document conversion. LibreOffice or OpenOffice is required for Office format conversion: the README states that it is integrated on Windows, installed automatically on Linux, and must be installed manually on macOS.

## Supported File Formats

kkFileView's format coverage spans more than 20 categories. Office formats include doc, docx, xls, xlsx, xlsm, ppt, pptx, csv, tsv, and domestic WPS formats such as wps, dps, et, and ett. OpenOffice and LibreOffice formats including odt, ods, ots, odp, otp, fodt, and fods are also supported. PDF, OFD, and RTF are handled as distinct types.

Beyond documents, kkFileView handles Visio flowchart files (vsd, vsdx), Photoshop files (psd, eps), XMind files, BPMN workflow files, EML and MSG email files, and EPUB book documents.

The 3D model support covers obj, 3ds, stl, ply, gltf, glb, off, 3dm, fbx, dae, wrl, 3mf, ifc, brep, step, iges, fcstd, and bim files. CAD formats include dwg, dxf, dwf, igs, dwt, dng, ifc, dwfx, cf2, and plt. Compressed archives in zip, rar, jar, tar, gzip, and 7z formats are previewed as a browsable tree.

Image previewing includes jpg, jpeg, png, gif, bmp, ico, webp, heic, heif, tif, tiff, tga, and svg. Audio and video playback covers mp3, wav, mp4, flv, avi, mov, wmv, mkv, 3gp, and rm.

## Installing and Starting kkFileView

The README provides two setup paths. The first is cloning the repository and running the application directly:

```bash
git pull https://github.com/kekingcn/kkFileView.git
```

After cloning, run the main method in `/server/src/main/java/cn/keking/ServerMain.java`. After startup, visit `http://localhost:8012/`.

The second path is Docker. The Dockerfile packages the built JAR:

```dockerfile
FROM keking/kkfileview-base:5.0.0
ADD server/target/kkFileView-*.tar.gz /opt/
ENV KKFILEVIEW_BIN_FOLDER=/opt/kkFileView-5.0.2/bin
ENTRYPOINT ["java","-Dfile.encoding=UTF-8","-Dspring.config.location=/opt/kkFileView-5.0.2/config/application.properties","-jar","/opt/kkFileView-5.0.2/bin/kkFileView-5.0.2.jar"]
```

The Dockerfile sets the configuration location through the `spring.config.location` JVM argument, pointing to `application.properties` inside the extracted archive. JDK 21 or higher is required for both deployment paths. Redis is optional and disabled by default; LibreOffice is a dependency for Office format conversion and is handled automatically on Linux.

## Security History and v5.0.2 Changes

Three security fixes were issued across v5.0.1 and v5.0.2. In v5.0.1, the `/addTask` endpoint was found to bypass trusted-host and local-directory filters, enabling server-side request forgery (SSRF, tracked as GHSA-gwwj-52hv-6g2m). The `/listFiles` endpoint was found to allow the `directory` parameter to escape the demo directory through path traversal, enabling directory information disclosure (GHSA-pmp8-g8p2-p6jq). Both were fixed in v5.0.1.

In v5.0.2, HTML previews were found to execute JavaScript in the kkFileView application origin rather than in an isolated context. This was fixed by sandboxing untrusted HTML previews in an opaque-origin iframe with JavaScript execution disabled by default (GHSA-9wcf-jxxf-w2g2). A second v5.0.2 fix disabled the demo file deletion endpoint by default, changed it to require a POST request, and required an explicitly configured password in `KK_DELETE_PASSWORD` or the `delete.password` configuration key.

The v5.0.2 upgrade notes state that the `kk.scriptjs` setting now defaults to false. Users upgrading from v5.0.1 can reuse existing configuration. The JDK 21 requirement has not changed since v5.0.0.

## The REST API and Extension Model

kkFileView exposes a REST API that accepts a file URL and returns a rendered preview. The README describes an abstract file preview interface that makes it straightforward to extend the system with new file formats or override existing rendering logic.

The repository layout separates concerns by placing the Spring Boot server in the `server/` directory with its own Maven module. The `pom.xml` at the root coordinates the multi-module Maven build. The `doc/` directory contains documentation, and the `tests/` directory contains the test suite.

One practical limitation of the REST API design is that kkFileView must be able to retrieve the file by URL. Files that are only accessible on a private network, or that require authentication headers that kkFileView cannot pass, need additional configuration. The README notes that the trusted-host filter (fixed in v5.0.1) is part of the security model for controlling which URLs kkFileView will fetch.

For Excel files, the v5.0.0 changelog notes enhanced front-end parsing through LuckyExcel, and v5.0.1 moved large xlsx parsing into a Web Worker with automatic fallback to the main thread. This means large spreadsheets do not block the rendering thread in the browser. The  file in the repository root suggests the project documents agent or automation guidance alongside the regular contributor documentation, which is an unusual addition for a Java web service.

## Limitations and Cases Where kkFileView Is the Wrong Tool

kkFileView converts documents using LibreOffice under the hood for Office formats. Conversion fidelity depends on LibreOffice's rendering of the source format, which can differ from Microsoft Office. Complex formatting, embedded macros, and proprietary Office features may render incorrectly or not at all.

The service is stateful: it fetches, converts, and caches previews. Under high concurrency, the Jodconverter bridge to LibreOffice becomes a bottleneck. The README does not document concurrency limits or the behavior under heavy load. Teams expecting high-volume preview requests need to test this explicitly.

The license is listed as unknown in the repository metadata, which creates a legal ambiguity. Before deploying kkFileView commercially or including it in a product, review the LICENSE file in the repository for the actual license terms. Redistribution without clarifying the license is a compliance risk.

The three security advisories issued across v5.0.1 and v5.0.2 suggest that earlier versions should not be deployed in environments where untrusted users can submit arbitrary URLs or file paths. The  directory in the repository root indicates a CI workflow configuration separate from the main  workflows, which could affect how the build pipeline behaves across different environments.

## Release History and Maintenance

kkFileView reached version 5.0.0 on 2026-04-14, followed by v5.0.1 on 2026-07-13 and v5.0.2 on 2026-08-14. The last push to the repository was on 2026-09-18. The project is not archived and is receiving security and bug fixes on a regular schedule.

The v5.0.0 changelog lists improvements to xlsx front-end parsing through LuckyExcel, optimized image processing, enhanced SVG rendering, improved Markdown rendering, redesigned archive preview with a collapsible tree and inline file preview, and a post-based server-side pagination mechanism for the home page directory listing.

The repository includes a `SECURITY.md` and a `SECURITY_CONFIG.md` file, and the v5.0.1 release added a repository security policy and private vulnerability reporting guidance. This suggests the project now has a process for handling security disclosures.

## Conclusion

kkFileView is the right choice for teams that need to embed a document preview widget into a web application without building a conversion pipeline from scratch. The REST API and the broad format coverage make integration straightforward. It is not suitable for high-security environments without careful review: versions prior to v5.0.1 had SSRF and path traversal vulnerabilities, and v5.0.2 patched an XSS issue in HTML previews. Verify that you are running v5.0.2 or later and that the `KK_DELETE_PASSWORD` is set if the file deletion endpoint needs to be enabled. The license is not specified in the repository metadata, so legal review before commercial deployment is necessary.

## FAQ

### What file formats does kkFileView support?

kkFileView supports Office documents (doc, docx, xls, xlsx, ppt, pptx, csv), WPS formats, LibreOffice formats, PDF, OFD, RTF, CAD files (dwg, dxf), 3D models (stl, obj, gltf, fbx), images (jpg, png, gif, webp, heic, svg), audio and video (mp3, mp4, avi, mkv), and archives (zip, rar, 7z). The README lists over 20 format categories in total.

### What are the minimum system requirements to run kkFileView?

kkFileView requires JDK 21 or higher. LibreOffice or OpenOffice is required for Office document conversion: it is integrated on Windows, installed automatically on Linux, and must be installed manually on macOS. Redis is optional and disabled by default.

### Does kkFileView support Docker deployment?

Yes. The repository includes a Dockerfile that packages the built JAR using keking/kkfileview-base:5.0.0 as a base image. The container starts the application with the configuration file at /opt/kkFileView-5.0.2/config/application.properties. Docker Compose examples are referenced in the project documentation.

## Sources

- [Issues](https://github.com/kekingcn/kkFileView/issues)
- [kekingcn/kkFileView on GitHub](https://github.com/kekingcn/kkFileView)
- [Project website](https://kkview.cn)
- [README](https://github.com/kekingcn/kkFileView/blob/master/README.md)
- [Releases](https://github.com/kekingcn/kkFileView/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kekingcn-kkfileview