周传炽1. kkfileview到底是什么，为什么要给它做反向代理
我先把这个项目背景捋清楚。kkfileview（也有叫kkFileView的）是一个开源的文件在线预览解决方案，服务端基于Java Spring Boot开发，核心功能是帮你把Office文档、PDF、图片、音视频这些格式统一的转成可以在浏览器里直接预览的形态。比如你传一个docx上去，它会调用OpenOffice或者LibreOffice把文档转成PDF，然后通过H5页面渲染出来，用户不需要安装Office套件，直接在网页里就能看。
这个项目在中小企业、OA系统、网盘类产品里使用率很高，因为它能省掉一堆重复造轮子的工作。你想，如果每次对接一个格式都要自己搞解析，那光是兼容Word、Excel、PPT、Visio、CAD这些格式就够你喝一壶的。kkfileview把这一层封装好了，有现成的预览接口，HTTP调用就行，部署也不算复杂。
那为什么还要给它做反向代理？很多人一开始不理解，觉得“服务起来了，直接访问IP加端口不就行了？”这句话对开发环境是对的，但放到真实的业务场景里，问题马上就来了。
第一种场景，你的业务系统是HTTPS的，而kkfileview内部跑的是HTTP。你想想看，用户访问的是 https://oa.example.com，页面里的预览功能要请求 http://192.168.1.100:8012 的资源，浏览器出于安全策略直接给拦了。这就是混用HTTPS和HTTP导致的“混合内容”问题，现代浏览器默认拦截。你要么给kkfileview也配上HTTPS证书，要么就在前面架一层Nginx做反向代理，把HTTPS请求转发到内部的HTTP服务，统一出口和入口。
第二种场景，域名和端口暴露得太裸。你直接告诉用户访问 http://服务器IP:8012/onlinePreview，地址栏里又带IP又带端口，一看就是内网服务，既不安全也不体面。通过Nginx做反向代理，可以把kkfileview挂到你的主域名下面，比如 https://oa.example.com/kkfile/onlinePreview，和主业务系统保持同源，Cookie也好管理，防火墙策略也好收紧。
第三种场景，kkfileview默认是单实例状态保持的，如果文件预览量大，后面你想搞负载均衡、加缓存、做灰度升级，都需要一个统一的入口层来做流量调度。Nginx就是这个入口层最成熟、最轻量的选择。
所以简单说，kkfileview是一个“干力气活”的预览服务，而反向代理就是给它套上一层“对外形象门面”，既解决协议不一致的问题，也解决暴露面过大的问题，还顺便把扩展能力留好了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 反向代理方案选型与整体设计思路
2.1 为什么首选Nginx而不是Apache或Caddy
反向代理的工具不止Nginx一个，Apache有mod_proxy，Caddy也可以做，商用一点的还有F5、HAProxy、云厂商的SLB。为什么我在实践中始终优先推荐Nginx？
首先是性能。Nginx是事件驱动架构，一个worker进程可以并发处理成千上万的连接，而Apache默认的prefork模式一个连接就要占用一个进程，在高并发场景下内存和CPU的开销差得非常多。kkfileview预览文档时要传输的文件体积往往不小，一个PDF几十MB很常见，这种大文件传输场景下Nginx的sendfile和epoll模型优势体感非常明显，瓶颈基本都在磁盘IO和网络带宽上，而不是代理层本身。
其次是配置灵活。Nginx的location匹配规则极其强大，支持前缀匹配、正则匹配、精确匹配，可以很精细地控制哪些路径转发给kkfileview，哪些路径直接返回静态资源，哪些路径需要加额外的请求头。这个特点恰好对上了kkfileview的一个棘手问题：它的预览地址和下载地址格式多样，不同的业务系统对接方式还不尽相同，有的走 /onlinePreview，有的走 /getCorsFile，有的还会带上?officePreviewType=这类查询参数。Nginx的location可以根据这些特征分别做处理，一个配置文件全搞定。
说实话Caddy近几年也做得不错，自动HTTPS非常香，但对中文社区和大多数运维来说，Nginx的生态更成熟，资料更多，遇到问题搜一搜基本都能解决。在中小企业里，团队里一般都有会写Nginx配置的同学，上手成本最低。
2.2 反向代理整体架构与请求流转路径
我实际部署过的一个典型结构是这样的：
客户端浏览器 → DNS解析 → Nginx（443端口，TLS终止） → 判断路径是否以 /kkfile/ 开头 → 转发 → 内网kkfileview服务（http://127.0.0.1:8012）
这样设计有三个好处。
第一，浏览器只和Nginx建立连接，安全证书只需要配一份在Nginx上，kkfileview完全不用碰证书的事，省心。第二，kkfileview监听在127.0.0.1或者内网IP上，外网根本访问不到它本身，只可能通过Nginx转发的流量进来，攻击面直接缩小。第三，以后如果要把kkfileview从单机迁移到集群，Nginx只需要在upstream里加几个后端节点，对客户端完全透明，无缝切换。
在实际配置的时候，一个最容易踩的坑就是路径前缀的处理。假设你的入口URL是：
https://oa.example.com/kkfile/onlinePreview
而后端kkfileview的原始URL是：
http://127.0.0.1:8012/onlinePreview
注意看，多了一个 /kkfile 前缀。nginx里的location如果用默认的proxy_pass不带URI形式，也就是proxy_pass http://127.0.0.1:8012; 这样写（末尾没有斜杠也没有路径），请求会被原样转发，也就是客户端请求 /kkfile/onlinePreview，后端接收到的也是 /kkfile/onlinePreview，kkfileview直接返回404或者不识别。但如果你在proxy_pass后面带了URI，比如proxy_pass http://127.0.0.1:8012/; 那么location匹配到的 /kkfile/ 前缀会被替换掉，客户端请求 /kkfile/onlinePreview，后端收到的是 /onlinePreview，路径就对了。
这个“代理时要不要保留前缀”的问题，是所有反向代理配置里最容易搞晕的细节，后面我会专门展开讲。