前阵子帮一个做内部文档中台的朋友收拾一个预览故障：业务站点早就全站切到了 https，嵌在页面里的预览窗口却始终白屏，浏览器控制台红字刷了一屏。排查大半天，根因朴素得让人想笑——kkfile 这边的预览服务还老老实实跑在 http 上。这类问题在配置 https 预览文件的场景里出现频率高得离谱，尤其是把 kkFileView 单独部署成一台独立服务、业务系统另起炉灶的团队，几乎都绕不过这道坎。kkFileView 本身是个挺能打的开源预览服务，Office 文档、PDF、图片、音视频、压缩包都能接，但它的默认配置全是围绕本地调试走的，一旦放到真实网络环境里，TLS 这一环不补齐，前端预览就永远是个薛定谔的窗口——有时候出得来，有时候出不来，还挑浏览器。下面这份东西，是我这几年在好几个项目里反复折腾后沉淀下来的实操记录，从方案选型到参数计算、从配置片段到排障思路都有，做后端、做运维、做前端集成的都能找到用得上的部分。
1. 先搞清楚 kkFileView 在链路里的位置
1.1 它到底解决什么问题
很多人刚接触这个服务时会有一个误解，以为它是"把文件转成图片塞到页面上"，其实它的工作方式更接近一个中间人。业务系统手里只有文件的存储地址或者一个文件流，浏览器不具备直接渲染 docx、xlsx、pptx 这些格式的能力，于是 kkFileView 跳出来当翻译：它把远端文件抓下来，用底层能力（Office 文档走 LibreOffice 或 OpenOffice 转成 PDF，再转成图片切片；图片、音视频、纯文本直接透传）处理成浏览器认识的东西，然后吐给前端一个可以嵌 iframe 的页面地址。
理解这一点非常关键，因为它决定了后面所有配置的走向。业务系统交付给用户的，其实只是一串预览地址，形如http(s)://预览服务地址/onlinePreview?url=编码后的文件地址；真正打开这个地址、执行转换、返回页面的是 kkFileView 自己。也就是说，预览页面最终是以预览服务的域名和协议呈现给浏览器的，业务系统的协议是什么，并不能决定预览窗口的协议。
1.2 为什么一上 HTTPS 就白屏
浏览器从很久之前就开始执行一套叫做"混合内容"的拦截规则。简单说，如果一个页面是 https 打开的，它内部再去加载 http 的 iframe、脚本、样式或者发起 http 的 XHR 请求，浏览器会直接拦下来，控制台里留下一条Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure frame 'http://...'的记录。iframe 这种属于"可主动执行的内容"，属于最严格的一档，基本没有商量余地，不会降级放行，而是干脆不加载。
所以现象就很好解释了：业务系统切了 https，预览地址没跟着切，浏览器打开 iframe 时发现 src 是 http，拦掉，白屏。有的同学会问，那我本地开发为什么没事？因为本地业务系统多半还是 http，两边协议一致，自然没有拦截。这也是为什么这个问题总在测试环境或者上线那一刻才暴露出来。
还有一种更隐蔽的情况：预览服务本身已经是 https 了，但转换过程中生成的内部资源地址依旧是 http。比如 kkFileView 返回的页面里，图片切片的地址是根据它自己认为的"基础地址"拼出来的，如果这个基础地址配错了，页面主体能打开，图却一张都出不来，控制台照样一堆拦截记录。这个问题后面在讲base.url的时候会重点说。
1.3 三种落地路线怎么选
把预览服务搬到 https 上，业内常见三条路，各有各的适用场景。
| 方案 | 实现方式 | 优点 | 代价 | 适用场景 |
|---|---|---|---|---|
| 预览服务自身开启 SSL | 在 Spring Boot 配置里加server.ssl.* | 链路短，不依赖额外组件，配置项少 | 证书更新要动服务，需要重启；只能监听一个端口 | 服务数量少、部署简单、不想引入 Nginx 的小项目 |
| Nginx 反向代理做 TLS 终结 | Nginx 监听 443，转发到本地 http 端口 | 证书管理集中，可热更新，能顺带做限流、压缩、日志 | 多一层组件要维护，配置项稍多 | 大多数生产环境，尤其是已经有统一入口的团队 |
| 网关统一接管 | 由 API 网关或统一入口做证书和路径分发 | 与业务系统同域，天然规避混合内容 | 依赖网关能力，路径规则要精确 | 已经有成熟网关体系的中大型项目 |
我个人的倾向很明确：只要已经存在 Nginx 或者同类反向代理，就走第二条。原因不只是省事，而是证书这件事本质上属于运维范畴，让它待在运维熟悉的地方，比塞进一个 Java 应用的配置文件里要合理得多。真到了证书到期那天，改 Nginx 配置 reload 一下即可，业务服务毫发无损；如果证书写在应用里，就得重新打包或者重启进程，风险完全不是一个量级。
2. 动手前的准备工作
2.1 版本与部署形态确认
动手改之前，先确认两件事，这两件事没搞清楚，后面配出来的东西十有八九对不上。
第一是版本。kkFileView 从 3.x 到 4.x，配置项的命名有过一次比较大的调整，最典型的就是上下文路径。3.x 时代用的是server.context-path，到了 4.x 跟着 Spring Boot 的规范变成了server.servlet.context-path。如果你照着某个老教程配了半天路径死活不生效，八成就是踩了这个。版本号可以通过访问服务的首页看，也可以在启动日志的开头找到。
第二是部署形态。是java -jar直接跑一个包，还是解压在某个目录里通过脚本启动，还是塞进了 Docker。这决定了三件事：配置文件放哪儿、证书文件怎么让程序读到、证书更新时怎么替换。Docker 部署的，证书一般要通过挂载卷进去，而不是打进镜像，否则每次换证书都要重新构建镜像，非常麻烦。另外还要确认服务的实际监听端口，开源版本习惯用 8012，但很多团队会改掉，以实际启动日志里打印的端口为准。
2.2 域名、端口与证书的三件套
要让 https 真正可用，需要凑齐三个要素。
域名。最好给预览服务单独分配一个子域名，比如preview.你的域名.com，而不是挂在业务系统的某个路径下。原因在于 kkFileView 会生成大量相对路径资源，挂载在子路径下时，如果反向代理的路径转换没写对，很容易出现主页面能开、静态资源 404 的情况。独立子域名就简单很多，location /直接转发即可。
端口。443 是标准端口，但从安全运维的角度，很多团队会把 https 挪到非标准端口（比如 8443），再用统一入口做映射。这个没有硬性要求，关键是前端拼接的地址要和实际监听的端口一致，差一位数字就是连接被拒绝。
证书。生产环境用正规机构签发的证书，这里不展开；内网或测试环境可以用自签证书，但要注意自签证书在浏览器里会报不受信任，需要在客户端导入根证书，或者干脆在测试环境放行。有条件的团队可以用内部 CA 统一签发，省去每次手动导入的麻烦。证书文件一般会拿到两份：一份证书链（包含服务器证书和中间证书），一份私钥。这两份东西缺一不可，且顺序不能反。
2.3 证书格式转换的完整命令
Java 应用读证书的方式和 Nginx 不一样。Nginx 直接认 PEM 格式的证书链和私钥，而 Spring Boot 走的是 Java 的密钥库体系，认的是 JKS 或者 PKCS12。所以走"方案一"的时候，需要做一次格式转换。
如果你手上是 PEM 格式的两份文件，转成 PKCS12 的命令是：
openssl pkcs12 -export \ -in fullchain.pem \ -inkey privkey.pem \ -out kkfile.p12 \ -name kkfile \ -passout pass:你的密码如果手上拿到的是 pfx 或 p12 文件，需要转成 JKS：
keytool -importkeystore \ -srckeystore cert.pfx \ -srcstoretype PKCS12 \ -srcstorepass 源密码 \ -destkeystore kkfile.jks \ -deststoretype JKS \ -deststorepass 目标密码还有一种情况是什么都没有，只在测试环境自签一份。这时候关键点在于必须带上 SAN（Subject Alternative Name）扩展，因为现在的浏览器早就不看 CN 字段了，只看 SAN。命令大致是这样：
keytool -genkeypair \ -alias kkfile \ -keyalg RSA -keysize 2048 \ -storetype PKCS12 \ -keystore kkfile.p12 \ -validity 3650 \ -storepass 你的密码 \ -dname "CN=preview.example.com, OU=IT, O=Demo, L=Hangzhou, ST=Zhejiang, C=CN" \ -ext "SAN=dns:preview.example.com,ip:10.0.0.12"注意最后那个-ext SAN=的参数，里面把域名和 IP 都写上，这样无论别人用域名访问还是直接用 IP 访问，证书都不会报名字不匹配。我见过不止一次，同事自签完证书怎么都过不了校验，最后发现就是漏了 SAN。
提示：
-validity单位是天。自签证书别贪心签太长，测试环境签个 365 天足够，签十年反而容易忘掉它什么时候过期。
3. 方案一：让 kkFileView 自己开 HTTPS
3.1 application.properties 关键项逐条拆解
配置文件通常位于解压目录的config文件夹下，Docker 部署的则通过启动参数或挂载覆盖。要开启 SSL，需要补上这么几行：
server.ssl.enabled=true server.ssl.key-store=file:/opt/kkfileview/cert/kkfile.p12 server.ssl.key-store-password=你的密码 server.ssl.key-store-type=PKCS12 server.ssl.key-alias=kkfile逐条说说它们的含义和容易出错的地方。
server.ssl.enabled是总开关，设成 true 之后，整个应用就只会用 https 对外提供服务，原来的 http 监听会失效。这一点要特别注意：开启 SSL 之后，本机自检也不能再用 http 去访问了，用curl -k https://127.0.0.1:8012才对，-k是忽略证书校验，本地自签证书必备。
key-store指的是密钥库文件的位置。它支持classpath:和file:两种前缀。这里我强烈建议用file:加绝对路径，原因前面提过——打成 jar 包之后，classpath:下的证书会被打进包里，换证书就得重新打包，非常难受。用file:指向外部目录，换证书就是替换文件重启的事。
key-store-type要和实际文件格式对上。PKCS12 和 JKS 是两种不同的容器格式，写错了启动直接报错，日志里会提示 keystore 格式异常或者密码错误，这两种报错很容易混淆，看到"密码错误"先别急着怀疑密码，先确认类型写对了没。
key-alias是证书在库里的别名。如果是单个证书的库，这个可以不写；但如果一个库里放了多张证书，就必须指定，否则启动会报"找不到唯一别名"。生成证书时用-name或者-alias指定的名字，就是这里要填的值。
3.2 证书放 classpath 还是外部路径
上一节简单提了一下，这里再展开说说，因为这是很多人第一次配置时会忽略的细节。
打成可执行 jar 之后，jar 本质上是个压缩包，classpath:前缀指向的内容都在包内部。这意味着两件事：第一，证书文件必须先拷进源码目录再打包，流程变长；第二，证书更新要重新构建、重新分发、重新启动，一个证书的问题动到了整个发布流程。
用file:就简单多了。证书放在服务器某个固定目录，配置里写绝对路径。到期换证时，把新文件传上去，覆盖老文件，重启进程即可。如果还想更平滑，可以在应用前面套一层反向代理，代理层持有证书，应用本身完全不用关心证书这件事——这其实就是下一节要讲的方案二。
有一点要提醒：file:的路径建议写绝对路径，不要写相对路径。相对路径是相对于进程的工作目录，而工作目录取决于你用什么方式启动——systemd启动、nohup启动、Docker 启动，工作目录可能完全不同，相对路径很容易踩空。
3.3 base.url 改错会有什么后果
这个参数值得单独拿出来说，因为它是 https 改造里最容易出问题的一环。
base.url的作用是告诉 kkFileView："外界访问我的地址是什么"。程序内部生成预览页面里那些图片切片、PDF 分页、下载链接时，都会以这个值为前缀去拼。如果它写的是 http 地址，而页面本身是 https 打开的，那么页面主体能加载，里面的资源全是 http，浏览器照样拦，用户看到的就是一个灰扑扑的空壳子。
正确的写法是：
base.url=https://preview.example.com/注意三点。第一，协议必须是 https。第二，域名要是用户浏览器真真切切访问得到的那个域名，不能写 localhost 或者内网 IP，除非用户真的就是从内网访问。第三，结尾的斜杠保留，避免拼接时少一个分隔符导致路径变成https://preview.example.comonlinePreview这种诡异的东西。
另外还有一个上下文路径的概念要一起考虑。如果预览服务的访问路径带了前缀，比如https://preview.example.com/file/，那么base.url也要把这段前缀带上，同时server.servlet.context-path也要设成/file。这三者——实际访问路径、base.url、context-path——必须完全对齐，错一个就会出现"页面能打开但资源 404"或者"整个 404"。
注意：改完
base.url一定要清一次浏览器缓存再测。这个值会被前端页面以脚本形式引用，缓存命中老值的时候，你会怀疑自己改的配置根本没生效。
4. 方案二：Nginx 反代做 TLS 终结
4.1 为什么我更推荐这条路
把证书交给 Nginx 管，最直接的好处是三点。
第一是证书热更新。Nginx 的 reload 是优雅重启，旧连接处理完才退出，用户几乎无感。这对证书这类"必须定期更换"的资源来说，体验差距很大。相比之下，Java 应用重启期间预览服务是中断的，正在看文档的用户会直接看到报错。
第二是责任边界清晰。证书属于基础设施，放在运维统一管理的位置，比散落在各个应用的配置文件里要好维护得多。试想一下，十个服务十个证书十种配法，到期前挨个去翻配置文件是什么体验。
第三是顺手能做很多事。Nginx 天然支持限流、访问日志、请求体大小限制、压缩、跨域头注入。预览服务经常面临大文件上传和长时间连接，这些在代理层处理比在应用里处理要方便。
当然，方案二也有前提：你得先把 kkFileView 用 http 跑起来。这一点是好事，它意味着应用层面几乎不用改，只要保证base.url指向的是最终对外的 https 地址就行——因为用户浏览器看到的确实是这个地址。
4.2 一份能直接抄的 server 配置
下面这份配置是我在实际项目里用了挺久的版本，稍微改改域名和路径就能用：
server { listen 443 ssl; server_name preview.example.com; ssl_certificate /etc/nginx/cert/fullchain.pem; ssl_certificate_key /etc/nginx/cert/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; client_max_body_size 500m; access_log /var/log/nginx/preview.access.log; error_log /var/log/nginx/preview.error.log; location / { proxy_pass http://127.0.0.1:8012; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_send_timeout 300s; proxy_read_timeout 300s; proxy_buffering off; proxy_request_buffering off; } }几个关键点展开说。
ssl_protocols里我保留了 TLSv1.2 和 TLSv1.3，把更老的版本全部关掉。老的协议版本存在已知的安全弱点，而且现在的浏览器和主流客户端都支持 1.2 以上，关掉不会影响可用性。
ssl_session_cache和ssl_session_timeout是性能相关的。TLS 握手本身是有计算成本的，开启会话复用之后，同一个客户端短时间内的第二次连接可以直接复用会话，省掉一次完整握手。10MB 的共享缓存大概能支撑几万个会话，对内部系统来说绰绰有余。
client_max_body_size设成 500m，是因为预览服务可能会接收用户上传的文件。这个值按你业务里最大的文件来设，设小了会在上传大文件时返回 413，而且这个错误是 Nginx 直接返回的，应用日志里什么都看不到，很容易误判成应用问题。
X-Forwarded-Proto这一行很重要。它的作用是告诉后端"用户实际用的是 https"，有些框架会根据这个头去判断是否需要生成 https 链接。虽然 kkFileView 主要靠base.url判断，但加上这个头不会有坏处，属于规范做法。
4.3 大文件预览的超时与缓冲调优
代理大文件预览的时候，有两个参数是必须调的，否则用户体验会很差。
第一个是超时。proxy_read_timeout默认是 60 秒，意思是 Nginx 等待后端响应的最长时间。如果预览的是一个几百页的 PPT，后端转换过程可能就要一两分钟，这时候 Nginx 早就把连接掐了，用户看到的是 504。我一般会设到 300 秒，特别大的文档甚至可以到 600 秒。同时proxy_send_timeout也一起调大，它管的是向后端发送请求的超时。
第二个是缓冲。proxy_buffering默认是开的，Nginx 会先把后端的响应缓冲到磁盘或内存里，再发给客户端，这样可以早点释放后端连接。但预览场景不太一样：用户是边看边加载的，如果 Nginx 要等整个 PDF 都接收完才开始往外发，那用户就得干等。关掉proxy_buffering之后，数据是流式转发的，用户能更快看到第一屏内容。proxy_request_buffering off同理，上传大文件时不必等整个文件收完再转发。
还有一点值得一提的是，如果预览服务和应用服务器在同一台机器上，proxy_pass里用127.0.0.1走回环网卡，速度是最快的，也不受外网波动影响。别写成机器的公网 IP，那样数据要绕一圈出去再回来，白白浪费带宽还增加延迟。
5. 业务系统侧的对接细节
5.1 预览地址怎么拼才不出错
业务系统最终是要往 iframe 的 src 里塞一个地址的，这个地址的拼法有几个坑。
标准形式是预览服务域名 + 上下文路径 + /onlinePreview?url= + 编码后的文件地址。文件地址必须做 URL 编码，因为它本身带有://、?、&这些字符，不编码的话会被后端解析成不同的参数。有些版本的 kkFileView 还要求对地址做一层 Base64，具体以你所用版本的官方说明为准——这一步千万别靠记忆，去看一眼文档，版本差异主要就体现在这里。
更稳妥的做法是让后端来拼这个地址，而不是前端。原因是后端可以直接读到配置项里的预览服务地址，改地址只改一处配置；前端如果硬编码了域名，换个环境就得重新构建。可以约定一个接口，前端传文件 ID，后端返回拼好的完整预览地址，前端只管塞进 iframe。
还有一个细节是中文文件名。文件地址里如果带中文，编码的时候要用 UTF-8，用错编码会导致后端拿到的文件名乱码，进而找不到文件。
5.2 混合内容拦截的两种绕法
假设因为某些历史原因，预览服务暂时没法上 https，但又必须让 https 的业务页面能预览，还有两条路可走。
第一条是让业务系统的反向代理顺带把预览服务的路径也代理了。也就是说，浏览器请求的其实是业务系统自己的域名，只是路径是/preview/，反向代理在服务端把/preview/转发到后端的 http 预览服务。这样从浏览器的视角看，整个链路都是同域的 https，混合内容的问题自然不存在。
第二条是在预览页面所在的 iframe 上做文章，比如用srcdoc或者 Blob URL 的方式加载。这条路我不太推荐，因为 kkFileView 返回的页面内部还有大量相对路径的资源请求，脱离了原始的域名和路径之后，这些资源大概率加载不出来。要让它工作，等于要把整页资源都重写一遍，成本远高于给它配个证书。
从长期看，第一条路是过渡方案，最终还是要让预览服务自己有 https 能力。毕竟代理转发只是把问题藏起来了，链路里依然有一段明文传输。
5.3 若依这类框架集成时改哪几处
用若依或者类似的后台框架做集成的，改造点其实集中在几个地方。
后端配置里通常有一个预览服务的地址配置，把它从 http 改成 https。这个地址往往同时用于"服务端调用预览接口"和"返回给前端拼预览地址"，所以改完之后要确认两个场景都对。有些实现里服务端调用用的是内网地址，返回给前端用的是外网地址，这就需要拆成两个配置项，别一把梭改了。
如果预览服务用的是独立子域名，前端 iframe 可能要跨域。跨域本身对 iframe 加载没有限制（iframe 不受同源策略约束），但如果页面之间有脚本通信，就会受限制。kkFileView 的预览页面一般是自包含的，不太需要跟父页面通信，所以这个问题通常不出现。如果确实需要通信，就得在代理层补上合适的响应头。
还有一个容易忽略的点是路由权限。若依这类框架前端有路由守卫，如果预览地址被当成内部路由处理，可能会被拦截跳登录。解决办法是把预览地址放在框架的静态资源目录之外，或者明确加进白名单。
6. 排障实录：HTTPS 预览失败的常见坑
6.1 高频问题速查表
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 预览窗口全白，控制台报 Mixed Content | 业务站 https，预览服务 http | 预览侧上 https，或在业务域下统一反代 |
| 页面能开，图片切片全是空框 | base.url配成了 http 或配错域名 | 改成实际的 https 域名，清缓存重测 |
| 地址栏有小锁但预览 404 | context-path、base.url、代理路径三者不一致 | 逐项对齐，从启动日志确认实际路径 |
| 浏览器提示证书不受信任 | 自签证书缺 SAN，或证书链不完整 | 重新签发带 SAN，或拼上中间证书 |
| HTTPS 端口访问连接被重置 | 端口未监听、防火墙拦截、安全组未放行 | 检查监听状态和网络策略 |
| 大文件预览中途断流 | proxy_read_timeout过短或缓冲策略不当 | 调大超时，关闭proxy_buffering |
| 换证书后浏览器仍提示旧证书 | Nginx 未 reload，或 Java 进程未重启 | reload 配置或重启服务 |
| 上传文件报 413 | 代理层请求体大小限制 | 调整client_max_body_size |
6.2 定位问题的三把工具
遇到预览白屏，别急着改配置，先用工具把问题钉死在哪一层。
浏览器开发者工具是第一把。看 Console 面板有没有 Mixed Content 的警告，看 Network 面板里哪些请求是红色失败的、失败原因是什么。如果是blocked:mixed-content，那问题在协议不一致；如果是 404，那是路径问题；如果是net::ERR_CONNECTION_RESET，那多半是网络或服务没起来。
命令行是第二把。先在本机用curl -k https://域名/看能不能拿到页面，能拿到说明服务和证书没问题，问题在浏览器侧。再用curl -I看响应头，确认返回的是不是预期的内容和状态码。这一步能快速区分"服务端问题"和"客户端问题"。
看日志是第三把。Nginx 的 error.log 里会记录上游连接失败的详细信息，比如upstream timed out、connect() failed等等，这些措辞非常直白。kkFileView 自己的日志则会记录转换过程中的异常，比如某个文件格式处理失败。两边日志一起看，问题范围立刻缩小。
6.3 我踩过的三个具体坑
第一个坑是 context-path 的命名差异。当时照着网上老文章配了server.context-path，启动之后怎么访问都 404。翻启动日志才发现，应用实际监听的路径是另一个。后来才明白是版本差异，4.x 版本改用了新的写法。这件事教我的就是：配置项一定要对着当前版本的官方说明来，别信搜索引擎前几条的老帖。
第二个坑是证书链不完整。当时只把服务器证书配进去了，没带中间证书。结果在部分浏览器上正常，在另一些客户端上就报证书链不完整。后来把中间证书拼进fullchain.pem才解决。这个问题的麻烦之处在于它挑客户端，本地测着好好的，一换环境就翻车，非常具有迷惑性。
第三个坑是换证书之后忘了 reload。新证书传上去，文件也替换了，浏览器打开仍旧提示旧证书。当时排查了半天浏览器缓存、系统时间，最后nginx -t测试配置没问题，才想起要 reload 一下让配置真正生效。这件事之后我在运维手册里专门加了一条：证书替换的标准动作是"替换文件、测试配置、reload、验证生效"，四步缺一不可。
7. 上线之后还要做的几件事
7.1 证书续期与不停机更新
证书是有有效期的，短则三个月，长则一年。有效期越短，安全性越好，但对运维的要求也越高。无论用哪种方案，都应该把续期这件事纳入例行工作，而不是靠人肉记忆。
可行的做法是设置监控告警，在证书到期前 30 天开始提醒，到期前 15 天必须处理完。如果是用自动化工具申请的证书，续期本身可以自动化，但续期之后的动作要跟上——比如签发工具生成的证书文件路径和你在 Nginx 里配的路径是否一致，续期后是否需要 reload。这几个环节没打通，自动化续期反而会制造出"证书文件是新的，但服务用的是旧的"这种诡异状态。
不停机更新的关键就是前面说的 reload。Nginx 的 reload 会让老进程处理完存量连接再退出，新连接由新进程接管，整个过程用户基本感知不到。需要注意的是 reload 的频率不要太高，也不要和配置文件的批量修改搅在一起，每次改完先nginx -t校验，通过了再 reload。
7.2 防 SSRF 与访问控制
预览服务有个天然的安全隐患：它的核心能力是"根据一个地址去抓文件"。如果这个地址完全不加限制，别人就能拿你的服务当跳板，去访问内网的各种资源，这就是典型的 SSRF。
好在这个风险是有办法控制的。kkFileView 提供了信任主机配置，可以设置一个域名白名单，只有来自白名单的地址才允许被预览。生产环境里，无论如何都应该把这个配上去，把允许预览的文件来源域名全部列进去。具体配置项的名称和格式，看当前版本的官方说明，各版本之间有过调整。
另外，如果预览服务是可以被公网访问的，还应该加一层身份校验。最省事的做法是在反向代理层做，比如校验一个由业务系统签发的 token 参数，或者检查请求头里是否带有内部标识。这样即使地址被别人拿到，没有凭证也打不开。
注意：预览服务如果配置了信任主机白名单，本机进行的自测地址可能不在白名单里，会导致自测失败。调试时记得临时把测试地址加进去，别误判成服务故障。
7.3 一点性能上的小调整
上线之后如果发现预览响应偏慢，可以从几个方向看看。
如果你们的场景里同一份文档被反复预览，可以关注一下缓存相关的配置。预览服务会把转换结果落盘，重复访问时能省掉转换这一步。确认这个缓存目录所在磁盘空间够用，别哪天磁盘写满导致所有预览都失败——这个问题在日志里表现为文件写入异常，不看磁盘使用率的话很容易排查偏方向。
HTTPS 本身会带来一点性能开销，但在现代硬件上，TLSv1.2 以上协议的成本已经很低了，完全不至于成为瓶颈。真正影响体验的往往是转换耗时和网络传输。大文件传输可以考虑开压缩，不过 PDF 和 Office 转出来的图片本身已经是压缩格式，再压一遍意义不大，反而费 CPU。所以在代理层开压缩要挑对象，别一把全开。真正值得做的是在代理层加上合适的缓存策略，让静态资源在浏览器端多停留一会儿。
7.4 上线检查清单
正式上线前，我一般会按这份清单逐项确认一遍，避免漏项：
- 预览服务的实际访问地址与
base.url完全一致，协议为 https context-path与实际访问路径、反向代理路径三者对齐- 证书链完整，包含中间证书，SAN 覆盖所有访问用的域名和 IP
- 反向代理已 reload，浏览器确认真实生效的是新证书
- 大文件上传的请求体限制和超时时间已按业务最大值调整
- 用真实业务文档做一次端到端预览，Office、PDF、图片各挑一个
- 在业务系统的真实页面上验证 iframe 能正常加载，控制台无 Mixed Content 警告
- 信任主机白名单已配置，且不包含任何不该被访问的地址
- 监控已覆盖证书有效期，告警渠道确认能收到
这套流程走下来，基本能把 https 预览这条链路的所有关键点覆盖住。剩下的事情就是保持关注，证书快到期的时候别忘处理。
最后分享一个我个人觉得比较省心的习惯：把预览服务的所有配置项集中整理成一份说明文档，包括每个参数的含义、取值、修改后会影响到什么。这份文档平时看着没用，等到某天凌晨证书过期、别人给你打电话的时候，它的价值就体现出来了。踩过几次坑之后我越来越觉得，配置这件事真正难的不是把参数调对，而是半年后还能想起来当初为什么这么调。
