前阵子帮一个做内部文档中台的朋友收拾一个预览故障业务站点早就全站切到了 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 文件需要转成 JKSkeytool -importkeystore \ -srckeystore cert.pfx \ -srcstoretype PKCS12 \ -srcstorepass 源密码 \ -destkeystore kkfile.jks \ -deststoretype JKS \ -deststorepass 目标密码还有一种情况是什么都没有只在测试环境自签一份。这时候关键点在于必须带上 SANSubject Alternative Name扩展因为现在的浏览器早就不看 CN 字段了只看 SAN。命令大致是这样keytool -genkeypair \ -alias kkfile \ -keyalg RSA -keysize 2048 \ -storetype PKCS12 \ -keystore kkfile.p12 \ -validity 3650 \ -storepass 你的密码 \ -dname CNpreview.example.com, OUIT, ODemo, LHangzhou, STZhejiang, CCN \ -ext SANdns:preview.example.com,ip:10.0.0.12注意最后那个-ext SAN的参数里面把域名和 IP 都写上这样无论别人用域名访问还是直接用 IP 访问证书都不会报名字不匹配。我见过不止一次同事自签完证书怎么都过不了校验最后发现就是漏了 SAN。提示-validity单位是天。自签证书别贪心签太长测试环境签个 365 天足够签十年反而容易忘掉它什么时候过期。3. 方案一让 kkFileView 自己开 HTTPS3.1 application.properties 关键项逐条拆解配置文件通常位于解压目录的config文件夹下Docker 部署的则通过启动参数或挂载覆盖。要开启 SSL需要补上这么几行server.ssl.enabledtrue server.ssl.key-storefile:/opt/kkfileview/cert/kkfile.p12 server.ssl.key-store-password你的密码 server.ssl.key-store-typePKCS12 server.ssl.key-aliaskkfile逐条说说它们的含义和容易出错的地方。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.urlhttps://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 域名清缓存重测地址栏有小锁但预览 404context-path、base.url、代理路径三者不一致逐项对齐从启动日志确认实际路径浏览器提示证书不受信任自签证书缺 SAN或证书链不完整重新签发带 SAN或拼上中间证书HTTPS 端口访问连接被重置端口未监听、防火墙拦截、安全组未放行检查监听状态和网络策略大文件预览中途断流proxy_read_timeout过短或缓冲策略不当调大超时关闭proxy_buffering换证书后浏览器仍提示旧证书Nginx 未 reload或 Java 进程未重启reload 配置或重启服务上传文件报 413代理层请求体大小限制调整client_max_body_size6.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完全一致协议为 httpscontext-path与实际访问路径、反向代理路径三者对齐证书链完整包含中间证书SAN 覆盖所有访问用的域名和 IP反向代理已 reload浏览器确认真实生效的是新证书大文件上传的请求体限制和超时时间已按业务最大值调整用真实业务文档做一次端到端预览Office、PDF、图片各挑一个在业务系统的真实页面上验证 iframe 能正常加载控制台无 Mixed Content 警告信任主机白名单已配置且不包含任何不该被访问的地址监控已覆盖证书有效期告警渠道确认能收到这套流程走下来基本能把 https 预览这条链路的所有关键点覆盖住。剩下的事情就是保持关注证书快到期的时候别忘处理。最后分享一个我个人觉得比较省心的习惯把预览服务的所有配置项集中整理成一份说明文档包括每个参数的含义、取值、修改后会影响到什么。这份文档平时看着没用等到某天凌晨证书过期、别人给你打电话的时候它的价值就体现出来了。踩过几次坑之后我越来越觉得配置这件事真正难的不是把参数调对而是半年后还能想起来当初为什么这么调。
kkFileView HTTPS在线预览配置与混合内容排障实战
前阵子帮一个做内部文档中台的朋友收拾一个预览故障业务站点早就全站切到了 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 文件需要转成 JKSkeytool -importkeystore \ -srckeystore cert.pfx \ -srcstoretype PKCS12 \ -srcstorepass 源密码 \ -destkeystore kkfile.jks \ -deststoretype JKS \ -deststorepass 目标密码还有一种情况是什么都没有只在测试环境自签一份。这时候关键点在于必须带上 SANSubject Alternative Name扩展因为现在的浏览器早就不看 CN 字段了只看 SAN。命令大致是这样keytool -genkeypair \ -alias kkfile \ -keyalg RSA -keysize 2048 \ -storetype PKCS12 \ -keystore kkfile.p12 \ -validity 3650 \ -storepass 你的密码 \ -dname CNpreview.example.com, OUIT, ODemo, LHangzhou, STZhejiang, CCN \ -ext SANdns:preview.example.com,ip:10.0.0.12注意最后那个-ext SAN的参数里面把域名和 IP 都写上这样无论别人用域名访问还是直接用 IP 访问证书都不会报名字不匹配。我见过不止一次同事自签完证书怎么都过不了校验最后发现就是漏了 SAN。提示-validity单位是天。自签证书别贪心签太长测试环境签个 365 天足够签十年反而容易忘掉它什么时候过期。3. 方案一让 kkFileView 自己开 HTTPS3.1 application.properties 关键项逐条拆解配置文件通常位于解压目录的config文件夹下Docker 部署的则通过启动参数或挂载覆盖。要开启 SSL需要补上这么几行server.ssl.enabledtrue server.ssl.key-storefile:/opt/kkfileview/cert/kkfile.p12 server.ssl.key-store-password你的密码 server.ssl.key-store-typePKCS12 server.ssl.key-aliaskkfile逐条说说它们的含义和容易出错的地方。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.urlhttps://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 域名清缓存重测地址栏有小锁但预览 404context-path、base.url、代理路径三者不一致逐项对齐从启动日志确认实际路径浏览器提示证书不受信任自签证书缺 SAN或证书链不完整重新签发带 SAN或拼上中间证书HTTPS 端口访问连接被重置端口未监听、防火墙拦截、安全组未放行检查监听状态和网络策略大文件预览中途断流proxy_read_timeout过短或缓冲策略不当调大超时关闭proxy_buffering换证书后浏览器仍提示旧证书Nginx 未 reload或 Java 进程未重启reload 配置或重启服务上传文件报 413代理层请求体大小限制调整client_max_body_size6.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完全一致协议为 httpscontext-path与实际访问路径、反向代理路径三者对齐证书链完整包含中间证书SAN 覆盖所有访问用的域名和 IP反向代理已 reload浏览器确认真实生效的是新证书大文件上传的请求体限制和超时时间已按业务最大值调整用真实业务文档做一次端到端预览Office、PDF、图片各挑一个在业务系统的真实页面上验证 iframe 能正常加载控制台无 Mixed Content 警告信任主机白名单已配置且不包含任何不该被访问的地址监控已覆盖证书有效期告警渠道确认能收到这套流程走下来基本能把 https 预览这条链路的所有关键点覆盖住。剩下的事情就是保持关注证书快到期的时候别忘处理。最后分享一个我个人觉得比较省心的习惯把预览服务的所有配置项集中整理成一份说明文档包括每个参数的含义、取值、修改后会影响到什么。这份文档平时看着没用等到某天凌晨证书过期、别人给你打电话的时候它的价值就体现出来了。踩过几次坑之后我越来越觉得配置这件事真正难的不是把参数调对而是半年后还能想起来当初为什么这么调。
