KKFileview如何使用Nginx进行反向代理实操

tassel_z

已于 2025-06-24 12:00:09 修改

阅读量683

点赞数 30

CC 4.0 BY-SA版权

分类专栏：开发实操文章标签： nginx spring javascript docker anti-design-vue spring boot gitee

于 2025-06-24 11:59:14 首次发布

本文链接：https://blog.youkuaiyun.com/weixin_39353771/article/details/148867738

开发实操专栏收录该内容

4 篇文章

订阅专栏

Spring Boot + Vue 前后端分离架构下配置 KKFileView 反向代理详解

在企业级文档管理系统中，常常需要支持在线预览各类 Office 文档（如 Word、Excel、PPT）、PDF、图片等格式。为此，我们通常会引入一个开源的文档在线预览服务 —— KKFileView，并将其集成到我们的前后端分离项目中。

本文将详细介绍如何在基于 Spring Boot + Vue 的前后端分离架构中，配置 KKFileView 的反向代理访问方案，包括前端处理、后端资源路径配置以及 Nginx 的代理设置，并对相关知识进行扩展说明。

一、KKFileView 简介

KKFileView 是一款开源的文件在线预览解决方案，支持多种主流办公文档格式（Word、Excel、PPT、PDF、TXT、图片等），底层基于 LibreOffice 转换为 PDF 再渲染成 HTML 页面进行展示。

主要特点：

支持主流文档格式在线预览
提供 RESTful API 接口调用
支持 Docker 部署，部署简单
开源免费，社区活跃度高

官方地址：

🔗 https://www.kkview.cn/zh-cn/index.html

你可以通过以下方式快速部署：

docker run -d \
    --name kkfileview \
    -p 8012:8012 \
    -v /your/local/path:/app/files \
    -v /path/to/custom/application.yml:/app/application.yml \
    keking/kkfileview

部署完成后，可通过访问 http://localhost:8012 查看预览页面。

二、前端配置：获取 KKFileView 在线预览地址

前端部分主要负责根据当前访问域名判断是否为内网环境，并动态拼接正确的 KKFileView 预览链接。

✅ 示例代码如下：

// 获取预览地址
export function getPreviewUrl(url) {
  // 统一使用正斜杠
  url = url.replaceAll('\\', '/');

  // 判断当前访问域名是否为指定公网IP
  const host = window.location.hostname;
  const proxyPath = host === 'xx.xx.xx.xx' ? '/fileview-online' : '/fileview';

  // 获取当前运行环境
  const baseUrl = process.env.VUE_APP_BASE_API;

  let previewUrl, fileUrl;

  if (baseUrl.includes('dev')) {
    // 开发环境直接指定 IP 地址
    previewUrl = 'http://xx.xx.xx.xx:xx';
    fileUrl = 'http://xx.xx.xx.xx:xx' + url;
  } else {
    // 生产环境使用当前域名+代理路径
    const origin = window.location.origin;
    previewUrl = origin + proxyPath;
    fileUrl = origin + url;
  }

  // 拼接完整的预览 URL
  return `${previewUrl}/onlinePreview?url=${encodeURIComponent(encode(fileUrl))}`;
}

🔍 说明：

proxyPath 根据域名判断使用内网还是外网代理路径。
使用 window.location.origin 获取当前页面基础路径，确保预览地址与当前页面同源。
encodeURIComponent(encode(fileUrl)) 对 URL 进行双重编码，防止特殊字符导致解析失败。

三、后端配置：文件上传路径映射

为了使用户上传的文件能够被正确访问，我们需要在 Spring Boot 中配置静态资源路径映射。

✅ 示例配置类：

@Configuration
public class ResourcesConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射本地文件上传路径 /profile/** 到对应物理目录
        registry.addResourceHandler("/profile/**")
                 .addResourceLocations("file:" + getProfile() + "/");
    }
}

🔍 说明：

/profile/** 是对外暴露的访问路径。
getProfile() 返回的是实际的文件存储路径（如 /opt/upload/profile/）。
该配置使得上传的文件可以通过类似 http://domain.com/profile/xxx.docx 的方式进行访问。

四、Nginx 配置：反向代理与跨域处理

在前后端分离架构中，Nginx 不仅承担了前端页面的静态资源托管，还负责后端接口及 KKFileView 的反向代理转发，解决跨域问题。

✅ 示例 Nginx 配置如下：

server {
    listen 8000;

    location / {
        root /www/wwwroot/client;
        try_files $uri $uri/ /index.html;
        index index.html index.htm;
    }

    # 后端接口代理（解决跨域）
    location /prod-api/ {
        proxy_pass http://localhost:9000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-Port $remote_port;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # 文件资源路径代理
    location /profile/ {
        proxy_pass http://localhost:9000/profile/;
    }

    # 内网 KKFileView 代理
    location /fileview/ {
        proxy_pass http://192.168.xx.xx:8012/;
    }

    # 外网 KKFileView 代理
    location /fileview-online/ {
        proxy_pass http://xx.xx.xx.xx:8012/;
    }
}