1. 先弄清楚 KKFileView 到底干了什么1.1 它不是前端插件而是一臺(tái)文檔轉(zhuǎn)換服務(wù)很多人第一次聽(tīng)到 KKFileView會(huì)下意識(shí)以為它是某個(gè) JavaScript 庫(kù)裝進(jìn) Vue 或者 React 項(xiàng)目里就能直接把 Word 渲染出來(lái)。我當(dāng)初也是這么想的結(jié)果翻了一圈文檔才發(fā)現(xiàn)方向完全錯(cuò)了。KKFileView 本質(zhì)上是一個(gè)獨(dú)立部署的 Java 服務(wù)它做的事情是接收一個(gè)文件的訪問(wèn)地址把文件下載到自己的臨時(shí)目錄調(diào)用本機(jī)的 LibreOffice 或 OpenOffice 把它轉(zhuǎn)成 PDF再把 PDF 轉(zhuǎn)成網(wǎng)頁(yè)可以逐頁(yè)瀏覽的圖片或 HTML最后返回一個(gè)瀏覽器能直接打開(kāi)的預(yù)覽頁(yè)面。這個(gè)定位非常關(guān)鍵因?yàn)樗鼪Q定了你的前端幾乎不需要引入任何體積龐大的解析庫(kù)。前端要做的只是拼一個(gè) URL然后把這個(gè) URL 丟給 iframe 或者新窗口。真正的重活——格式解析、排版還原、字體嵌入、分頁(yè)切圖——全部在服務(wù)端完成。對(duì)于內(nèi)網(wǎng)項(xiàng)目來(lái)說(shuō)這個(gè)架構(gòu)簡(jiǎn)直是量身定做的內(nèi)網(wǎng)機(jī)器通常不能訪問(wèn)外部 CDN很多純前端的在線預(yù)覽庫(kù)需要加載字體包、Worker 腳本一斷網(wǎng)就歇菜而 KKFileView 是整套自包含的只要能訪問(wèn)到那臺(tái)部署了服務(wù)的機(jī)器剩下的全在局域網(wǎng)內(nèi)跑通。它支持的格式列表比大部分人想象的長(zhǎng)doc、docx、xls、xlsx、ppt、pptx、pdf、txt、csv、各類圖片、音頻視頻4.x 版本之后還加上了 3D 模型文件glb、gltf、fbx、obj 等的在線預(yù)覽用 three.js 在瀏覽器里渲染。所以如果你手里有個(gè)內(nèi)網(wǎng)項(xiàng)目需要點(diǎn)什么文件都能看一眼它基本是覆蓋率最高的那一個(gè)選擇。適合誰(shuí)來(lái)參考我的判斷是中小型內(nèi)網(wǎng)管理系統(tǒng)、電子檔案系統(tǒng)、OA 附件預(yù)覽、教學(xué)資源庫(kù)這類場(chǎng)景最合適如果你的需求是必須像素級(jí)還原 Word 排版并且能在線編輯那它不合適往下看我會(huì)專門講它的邊界在哪里。1.2 四類主流在線預(yù)覽方案橫向比一比在定方案之前我把市面上常見(jiàn)的幾條路都試了一遍這里把結(jié)論整理成一張表你對(duì)著自己的場(chǎng)景抄就行。方案類型代表做法優(yōu)點(diǎn)致命短板服務(wù)端轉(zhuǎn) PDF/圖片KKFileView、用 LibreOffice 自研格式覆蓋廣、還原度高、前端零負(fù)擔(dān)、可離線首次預(yù)覽有轉(zhuǎn)換耗時(shí)、原文件會(huì)被服務(wù)端讀取純前端解析庫(kù)docx-preview、SheetJS、pdf.js不依賴服務(wù)端、部署簡(jiǎn)單格式覆蓋窄、PPT 基本沒(méi)法看、樣式還原差商業(yè)云預(yù)覽各類云文檔預(yù)覽接口效果最好、維護(hù)省心必須外網(wǎng)、數(shù)據(jù)出內(nèi)網(wǎng)、按量計(jì)費(fèi)干脆下載原文件什么都不做零成本用戶體驗(yàn)差被業(yè)務(wù)方天天催我特別想說(shuō)說(shuō)第二行。很多做 Vue2 項(xiàng)目的同學(xué)第一反應(yīng)是找 npm 包比如用 docx-preview 做 Word 預(yù)覽用 SheetJS 做 Excel 預(yù)覽。這條路在小文件、簡(jiǎn)單排版上確實(shí)能跑但只要文檔里出現(xiàn)復(fù)雜表格、文本框、頁(yè)眉頁(yè)腳、公式圖渲染出來(lái)就是一團(tuán)糟。而且 PPT 這一塊純前端幾乎沒(méi)有成熟的免費(fèi)方案你總不能自己寫(xiě)一個(gè)渲染引擎。所以當(dāng)需求里明確出現(xiàn)Word、Excel、PPT 三種都要能看時(shí)純前端方案基本可以直接排除。商業(yè)云預(yù)覽的效果確實(shí)好但內(nèi)網(wǎng)項(xiàng)目的紅線通常就是數(shù)據(jù)不出網(wǎng)這一條直接把它卡死了。這也是為什么我在標(biāo)題里特意強(qiáng)調(diào)實(shí)測(cè)可用于內(nèi)網(wǎng)項(xiàng)目——這不是一句營(yíng)銷話而是整個(gè)方案選型的核心約束。至于第四種我之前待過(guò)的一個(gè)項(xiàng)目初期就是這么干的附件列表點(diǎn)一下直接觸發(fā)下載結(jié)果上線兩周業(yè)務(wù)方就受不了了他們只是想在系統(tǒng)里確認(rèn)一下文件內(nèi)容對(duì)不對(duì)不想每次都在本地開(kāi)一個(gè) Office。在線預(yù)覽不是錦上添花它實(shí)實(shí)在在降低了使用成本。2. 整體鏈路拆解一次預(yù)覽請(qǐng)求到底發(fā)生了什么2.1 服務(wù)端的兩段式轉(zhuǎn)換與緩存機(jī)制理解這條鏈路是后面排查所有問(wèn)題的前提。當(dāng)瀏覽器請(qǐng)求onlinePreview接口并帶上文件 URL 之后KKFileView 內(nèi)部大致走這么幾步第一步根據(jù)文件 URL 把源文件下載到本地臨時(shí)目錄。這一步用的是 HTTP 請(qǐng)求所以它既能讀你開(kāi)放的文件服務(wù)也能讀帶鑒權(quán)參數(shù)的地址。第二步對(duì)源文件做類型識(shí)別通常按擴(kuò)展名判斷。如果是 PDF 或圖片這類本身就是瀏覽器友好格式的文件直接進(jìn)入第五步如果是 Office 三件套就要走轉(zhuǎn)換。第三步調(diào)用本機(jī)安裝的 LibreOffice 無(wú)頭模式把文檔轉(zhuǎn)成 PDF。這個(gè)轉(zhuǎn)換是整套方案里最慢也最容易出問(wèn)題的一環(huán)它依賴本機(jī)的字體環(huán)境、LibreOffice 版本、以及一堆底層圖形庫(kù)。第四步把轉(zhuǎn)換出來(lái)的 PDF 再渲染成逐頁(yè)圖片也支持直接以 PDF 形式返回。圖片模式下前端看到的是一張張圖兼容性最好但也就意味著不能選中文字、不能復(fù)制內(nèi)容——后面我會(huì)專門講這個(gè)代價(jià)。第五步計(jì)算緩存 Key一般是文件路徑加最后修改時(shí)間的哈希把結(jié)果文件寫(xiě)進(jìn)緩存目錄。下次同一個(gè)文件再來(lái)請(qǐng)求直接命中緩存跳過(guò)整個(gè)轉(zhuǎn)換過(guò)程。注意第三步和第四步是整個(gè)系統(tǒng)的性能瓶頸也是 90% 故障的發(fā)生地。你排查問(wèn)題的時(shí)候永遠(yuǎn)不會(huì)錯(cuò)的第一步就是去看日志里卡在哪一步。這個(gè)兩段式設(shè)計(jì)有個(gè)隱含的好處轉(zhuǎn)換和渲染解耦了。你可以單獨(dú)替換 PDF 渲染引擎也可以單獨(dú)升級(jí) LibreOffice 版本而不動(dòng)上層邏輯。代價(jià)是磁盤會(huì)被吃得很厲害一個(gè) 5MB 的 PPT 轉(zhuǎn)成逐頁(yè)圖片之后可能膨脹到 30MB 以上。這個(gè)賬一定要提前算別等服務(wù)器磁盤滿了才想起來(lái)。2.2 前端真正要做的只有三件事把服務(wù)端鏈路理清之后前端的工作量其實(shí)少得可憐拿到文件的真實(shí)可訪問(wèn)地址能是內(nèi)網(wǎng) IP也能是帶簽名的臨時(shí)地址對(duì)地址做正確的編碼處理拼成預(yù)覽地址用 iframe 或新窗口打開(kāi)并處理加載中、失敗、超時(shí)這三種狀態(tài)。就這么多。不需要 npm install不需要構(gòu)建配置不需要擔(dān)心打包體積。這也是它相對(duì)純前端方案最大的工程優(yōu)勢(shì)升級(jí)預(yù)覽能力時(shí)你改的是服務(wù)端前端一行代碼都不用動(dòng)所有業(yè)務(wù)模塊同時(shí)受益。我在實(shí)際項(xiàng)目里的做法是把預(yù)覽地址生成邏輯封裝成一個(gè)工具函數(shù)所有需要預(yù)覽的地方都調(diào)它。這樣將來(lái)如果換了預(yù)覽服務(wù)或者要在 URL 里加統(tǒng)一的鑒權(quán) token改動(dòng)點(diǎn)只有一個(gè)。2.3 緩存目錄與磁盤規(guī)劃建議緩存目錄默認(rèn)在服務(wù)運(yùn)行目錄下的file文件夾里生產(chǎn)環(huán)境強(qiáng)烈建議改到一個(gè)獨(dú)立掛載的大磁盤分區(qū)上。我見(jiàn)過(guò)太多項(xiàng)目因?yàn)闆](méi)做這個(gè)跑了兩三個(gè)月磁盤打滿然后整個(gè)服務(wù)開(kāi)始報(bào)錯(cuò)表現(xiàn)還是有些文件能預(yù)覽有些不能特別難查。一個(gè)比較穩(wěn)妥的規(guī)劃是這樣的如果預(yù)估日預(yù)覽量在 500 次左右平均單文件轉(zhuǎn)換后 20MB緩存保留 7 天那大概需要 500 × 20MB × 7 ≈ 70GB。再留一倍冗余直接掛 150GB 的盤。這個(gè)數(shù)字不精確但比隨便給個(gè) 20G要靠譜得多。緩存清理策略后面第 6 章我會(huì)給出具體配置。3. 內(nèi)網(wǎng)離線部署實(shí)錄CentOS 7 JDK 113.1 選包與依賴CentOS 7 上的三個(gè)硬門檻先說(shuō)要命的版本問(wèn)題。KKFileView 4.x 版本要求 JDK 11 及以上而 CentOS 7 自帶的 yum 源里能直接裝的通常還是 JDK 8。所以第一件事是在內(nèi)網(wǎng)機(jī)器上準(zhǔn)備好 JDK 11 的離線包。如果你的項(xiàng)目組有統(tǒng)一的 JDK 規(guī)范那就用你們規(guī)范里的版本但別低于 11。第二個(gè)門檻是 LibreOffice。你可以選擇先單獨(dú)裝 LibreOffice再讓 KKFileView 通過(guò)office.home指向它也可以直接用官方提供的內(nèi)嵌 Office版本壓縮包解壓即用省掉一堆依賴麻煩。內(nèi)網(wǎng)離線場(chǎng)景我強(qiáng)烈推薦后者——因?yàn)槟阌?yum 裝 LibreOffice 的時(shí)候如果內(nèi)網(wǎng)沒(méi)有完整鏡像源缺一個(gè)底層庫(kù)就能卡你半天。第三個(gè)門檻是系統(tǒng)底層圖形庫(kù)。LibreOffice 即使跑無(wú)頭模式也還是會(huì)依賴一些 libX 系列庫(kù)。CentOS 7 最小化安裝的系統(tǒng)往往缺這些。需要補(bǔ)的通常是這幾類fontconfig 相關(guān)字體管理、libXrender、libXext、libSM、libICE、libXinerama。這幾個(gè)包如果沒(méi)有服務(wù)啟動(dòng)時(shí)soffice進(jìn)程會(huì)直接起不來(lái)日志里會(huì)看到類似沒(méi)有可用的圖形環(huán)境之類的報(bào)錯(cuò)。這個(gè)坑我踩過(guò)兩次第二次是因?yàn)閾Q了臺(tái)新機(jī)器忘了這批依賴是手動(dòng)裝的。部署包和依賴準(zhǔn)備好之后的傳輸方式內(nèi)網(wǎng)項(xiàng)目一般走堡壘機(jī)上傳或者 U 盤拷貝注意校驗(yàn)一下文件的 MD5大文件傳輸損壞是很常見(jiàn)的事而校驗(yàn)失敗的表現(xiàn)往往是解壓報(bào)錯(cuò)或者啟動(dòng)報(bào) class 格式錯(cuò)誤容易誤判成環(huán)境問(wèn)題。3.2 中文字體不處理這一步必然亂碼這是整篇里我最想強(qiáng)調(diào)的一條中文字體必須提前裝好。KKFileView 依賴 LibreOffice 做轉(zhuǎn)換LibreOffice 依賴操作系統(tǒng)的字體庫(kù)。如果系統(tǒng)里只有英文字體那么任何包含中文的文檔轉(zhuǎn)成 PDF 之后中文部分會(huì)變成方框或者直接消失。很多人第一反應(yīng)是Linux 系統(tǒng)不是自帶中文字體嗎CentOS 最小化安裝是不帶的fc-list :langzh命令執(zhí)行出來(lái)大概率是空的。你可以先跑一下這個(gè)命令確認(rèn)fc-list :langzh | wc -l如果輸出是 0那就必須裝。做法是從你已有的授權(quán)渠道獲取字體文件宋體、黑體、仿宋、楷體這幾款覆蓋了絕大多數(shù)公文和報(bào)表場(chǎng)景上傳到服務(wù)器放到/usr/share/fonts/chinese/目錄下然后執(zhí)行chmod -R 755 /usr/share/fonts/chinese/ fc-cache -fv fc-list :langzh | wc -l最后那行輸出應(yīng)該是一個(gè)大于 0 的數(shù)字說(shuō)明字體已經(jīng)注冊(cè)進(jìn)系統(tǒng)了。這時(shí)候再重啟 KKFileView 服務(wù)中文亂碼問(wèn)題基本一次性解決。注意字體換掉之后之前生成的緩存文件不會(huì)自動(dòng)更新因?yàn)榫彺嬷徽J(rèn)文件路徑和修改時(shí)間不認(rèn)字體環(huán)境。所以要么重啟后清空緩存目錄要么在文件 URL 里加一個(gè)版本參數(shù)來(lái)強(qiáng)制刷新。順便說(shuō)一句如果你預(yù)覽的文檔里用了很多非常規(guī)字體比如某些設(shè)計(jì)稿字體那不管你怎么配都可能對(duì)不齊。這是 LibreOffice 渲染的固有特性不是配置能解決的遇到這種文檔基本只能接受能看內(nèi)容但排版略有偏移。3.3 關(guān)鍵配置項(xiàng)逐條說(shuō)明配置文件在 jar 包同級(jí)的config/application.properties里下面這些是我實(shí)際項(xiàng)目里改過(guò)的項(xiàng)逐條說(shuō)下為什么server.port8012 file.upload.dir/data/kkfileview/data office.home/opt/libreoffice cache.enabledtrue cache.clean.enabledtrue cache.clean.cron0 0 3 * * ? spring.servlet.multipart.max-file-size100MB spring.servlet.multipart.max-request-size100MBserver.port挑一個(gè)沒(méi)被占用的端口就行8012 是社區(qū)里用得比較多的一個(gè)注意內(nèi)網(wǎng)防火墻或者安全組要放行。file.upload.dir指向獨(dú)立磁盤分區(qū)對(duì)應(yīng) 2.3 節(jié)講的規(guī)劃。這個(gè)目錄會(huì)同時(shí)存放下載的源文件和轉(zhuǎn)換后的產(chǎn)物。office.home指向 LibreOffice 的安裝根目錄不是 bin 目錄寫(xiě)錯(cuò)了會(huì)報(bào)找不到 soffice。cache.enabled打開(kāi)緩存生產(chǎn)環(huán)境必須開(kāi)否則每次預(yù)覽都重新轉(zhuǎn)換CPU 會(huì)被打滿。cache.clean.cron用 Cron 表達(dá)式控制清理時(shí)間我習(xí)慣放在凌晨 3 點(diǎn)業(yè)務(wù)低峰期。清理策略建議按最后訪問(wèn)時(shí)間保留一定天數(shù)具體在配置里可以調(diào)整。max-file-size這兩個(gè)要一起改。默認(rèn)值比較小業(yè)務(wù)方上傳一個(gè)大一點(diǎn)的 Excel 就會(huì)報(bào)文件超過(guò)限制。改完記得前后端都要檢查因?yàn)橛行┚W(wǎng)關(guān)也會(huì)有限制。改完配置記得先用-Dfile.encodingUTF-8之類的編碼參數(shù)啟動(dòng)看一遍日志確認(rèn)讀取配置沒(méi)有亂碼。3.4 啟動(dòng)方式與開(kāi)機(jī)自啟最樸素的啟動(dòng)方式就是java -jar直接跑適合調(diào)試cd /opt/kkfileview nohup java -jar kkfileview-4.x.jar /var/log/kkfileview.log 21 生產(chǎn)環(huán)境還是建議配成 systemd 服務(wù)好處是能開(kāi)機(jī)自啟、崩潰自動(dòng)拉起、日志統(tǒng)一走 journald。寫(xiě)一個(gè)/etc/systemd/system/kkfileview.service把 ExecStart 指向 java 命令和 jar 路徑WorkingDirectory 指向部署目錄然后在[Service]段里加上Restarton-failure和RestartSec10。這樣服務(wù)萬(wàn)一因?yàn)槟硞€(gè)異常文檔崩了十秒后會(huì)自己起來(lái)比你半夜被電話叫醒強(qiáng)。需要提醒的是LibreOffice 轉(zhuǎn)換進(jìn)程在異常情況下有可能變成僵尸進(jìn)程所以啟動(dòng)腳本里最好加一個(gè)定期清理的策略。我一般的做法是配合定時(shí)任務(wù)每周檢查一次殘留的 soffice 進(jìn)程超過(guò)一定時(shí)長(zhǎng)的直接殺掉。4. 前端接入Vue2 項(xiàng)目里的完整實(shí)現(xiàn)4.1 URL 拼裝的三個(gè)坑編碼、base64、跨域這是前端唯一容易出錯(cuò)的地方我把三個(gè)坑按踩到的概率排序。第一個(gè)坑是編碼層級(jí)。文件地址里經(jīng)常帶查詢參數(shù)比如帶簽名的臨時(shí)地址這些參數(shù)里的、?、如果不編碼拼進(jìn)預(yù)覽地址后會(huì)被瀏覽器解析成另一個(gè)參數(shù)服務(wù)端拿到的 URL 就是殘缺的。正確做法是先對(duì)文件地址做一次encodeURIComponent。第二個(gè)坑是base64 要求。較新版本的 KKFileView 對(duì)url參數(shù)做了安全處理要求傳入的是先 encodeURIComponent 再 base64 編碼的結(jié)果。如果你按老文檔只做了編碼訪問(wèn)時(shí)會(huì)直接報(bào)參數(shù)不合法。這個(gè)變化坑了不少?gòu)呐f版本升級(jí)上來(lái)的人。完整寫(xiě)法是// 生成 KKFileView 可識(shí)別的預(yù)覽地址 function buildPreviewUrl(fileUrl) { // 第一步對(duì)原始地址做編碼避免 ? 被解析成參數(shù) const encoded encodeURIComponent(fileUrl); // 第二步base64 編碼注意需要支持中文用 encodeURIComponent 包一層 const base64 window.btoa(encoded); // 第三步把 base64 結(jié)果再編碼一次拼進(jìn) url 參數(shù) return ${KK_BASE}/onlinePreview?url${encodeURIComponent(base64)}; }這三步看起來(lái)有點(diǎn)繞但每一步都有存在的理由第一次編碼是為了保護(hù)原始地址的完整性base64 是為了繞過(guò)特殊字符帶來(lái)的參數(shù)解析問(wèn)題最后一次編碼是為了讓 base64 里的、/、能安全地作為查詢參數(shù)傳輸。我曾經(jīng)因?yàn)槁┑糇詈笠徊降木幋a導(dǎo)致一部分文件能預(yù)覽一部分報(bào)錯(cuò)規(guī)律很難找最后定位到就是 base64 里出現(xiàn)了號(hào)被解析成了空格。這個(gè)坑值得你記一輩子。第三個(gè)坑是跨域與同源。KKFileView 是獨(dú)立部署的端口跟你的前端應(yīng)用不一樣所以是跨域訪問(wèn)。這里有個(gè)常見(jiàn)誤解預(yù)覽頁(yè)本身是在 iframe 里打開(kāi)的iframe 加載的是 KKFileView 自己返回的頁(yè)面跟你的前端頁(yè)面不構(gòu)成同源限制所以不需要給前端配代理。真正的跨域問(wèn)題出在如果 KKFileView 需要回讀你的文件服務(wù)——那需要在文件服務(wù)那一側(cè)放開(kāi)允許來(lái)源或者干脆讓 KKFileView 走內(nèi)網(wǎng)直連減少一次鑒權(quán)。如果你的前端頁(yè)面本身是 HTTPS而 KKFileView 是 HTTP瀏覽器會(huì)攔截混合內(nèi)容。這種情況要么給預(yù)覽服務(wù)也配上證書(shū)要么把預(yù)覽改成新窗口打開(kāi)新窗口不受混合內(nèi)容限制。內(nèi)網(wǎng)項(xiàng)目里 HTTP 居多但只要你前端上了 HTTPS這條就必須提前考慮。4.2 封裝一個(gè)可復(fù)用的預(yù)覽彈窗組件在 Vue2 項(xiàng)目里我習(xí)慣做一個(gè)全局的預(yù)覽組件掛在根節(jié)點(diǎn)上用事件或者 Vuex 調(diào)用。組件內(nèi)部就一個(gè)全屏遮罩加一個(gè) iframe再加一個(gè)關(guān)閉按鈕。核心邏輯其實(shí)就三行設(shè)置 iframe 的 src、顯示遮罩、監(jiān)聽(tīng) iframe 的 load 事件隱藏 loading。// 簡(jiǎn)化版預(yù)覽彈窗核心邏輯 data() { return { visible: false, loading: true, previewSrc: }; }, methods: { open(fileUrl) { this.previewSrc buildPreviewUrl(fileUrl); this.visible true; this.loading true; }, onIframeLoad() { this.loading false; }, close() { // 關(guān)鍵關(guān)閉時(shí)清空 src否則 iframe 會(huì)繼續(xù)保持連接 this.previewSrc ; this.visible false; } }這里有個(gè)細(xì)節(jié)值得說(shuō)關(guān)閉彈窗時(shí)一定要把iframe的 src 置空。如果只是隱藏遮罩而不清空 src那個(gè) iframe 仍然活著仍然占著連接和內(nèi)存用戶連著預(yù)覽十幾個(gè)文件之后頁(yè)面會(huì)明顯變卡。我當(dāng)初就是因?yàn)橥祽袥](méi)清被測(cè)試同學(xué)報(bào)了預(yù)覽十幾次之后瀏覽器標(biāo)簽頁(yè)卡死的問(wèn)題。另外如果有輪詢或者定時(shí)任務(wù)也記得在關(guān)閉時(shí)清掉。加載態(tài)的處理也很重要。Office 文檔首次預(yù)覽要經(jīng)歷下載加轉(zhuǎn)換小文件一般一兩秒大文件十幾秒都正常。如果沒(méi)有任何加載提示用戶會(huì)以為系統(tǒng)卡住然后反復(fù)點(diǎn)擊反而把并發(fā)打上去。我的做法是在 iframe 上層蓋一個(gè) loading 遮罩同時(shí)給一個(gè)文檔轉(zhuǎn)換中請(qǐng)稍候的文案超過(guò) 30 秒自動(dòng)提示文檔較大轉(zhuǎn)換時(shí)間較長(zhǎng)可稍后重試。用戶體驗(yàn)立刻不一樣。4.3 帶鑒權(quán)的私有文件怎么處理實(shí)際項(xiàng)目里的文件很少有真正公開(kāi)可訪問(wèn)的地址通常都需要鑒權(quán)。這里給你三個(gè)思路按推薦度排序。第一優(yōu)先是給 KKFileView 提供一個(gè)臨時(shí)的、帶簽名的直連地址。也就是說(shuō)你的后端生成一個(gè)幾分鐘內(nèi)有效的臨時(shí)地址KKFileView 服務(wù)端直接去拉取拉取時(shí)地址里自帶簽名參數(shù)完成校驗(yàn)。這個(gè)方案對(duì) KKFileView 最透明安全性也最可控缺點(diǎn)是后端要多寫(xiě)一個(gè)簽發(fā)接口。第二個(gè)思路是給 KKFileView 服務(wù)本身配置一個(gè)固定的內(nèi)網(wǎng)訪問(wèn)憑證然后在內(nèi)網(wǎng)層面網(wǎng)絡(luò)策略或者網(wǎng)關(guān)只允許 KKFileView 的機(jī)器訪問(wèn)文件服務(wù)前端不參與鑒權(quán)。這適合那種純內(nèi)網(wǎng)的封閉系統(tǒng)實(shí)現(xiàn)成本最低但需要運(yùn)維配合做網(wǎng)絡(luò)隔離。第三個(gè)思路最不推薦把文件先上傳到 KKFileView 自帶的文件上傳接口拿到一個(gè)它托管的地址再去預(yù)覽。這個(gè)方式簡(jiǎn)單粗暴但等于把文件在服務(wù)端存了第二份數(shù)據(jù)管理上會(huì)變復(fù)雜緩存清理的時(shí)候還得考慮這些上傳的文件。只有在確實(shí)沒(méi)有別的路可走的時(shí)候才用。提示無(wú)論用哪種方案都不要把長(zhǎng)期有效的固定憑證寫(xiě)死在前端代碼里。前端代碼在內(nèi)網(wǎng)也不等于安全這是一個(gè)很基礎(chǔ)但總有人犯的錯(cuò)誤。5. 踩坑記錄與問(wèn)題速查表5.1 轉(zhuǎn)換失敗類問(wèn)題先上一張速查表后面再展開(kāi)說(shuō)幾個(gè)典型案例?，F(xiàn)象大概率原因處理方向一直轉(zhuǎn)圈最終超時(shí)LibreOffice 進(jìn)程沒(méi)起來(lái)或缺圖形庫(kù)手動(dòng)執(zhí)行 soffice 看報(bào)錯(cuò)補(bǔ)齊依賴報(bào)文件不存在文件 URL 編碼錯(cuò)誤或需要鑒權(quán)打印服務(wù)端日志里實(shí)際請(qǐng)求的地址部分文檔失敗部分成功特定格式不兼容或字體缺失單獨(dú)下載失敗文檔到服務(wù)器手動(dòng)轉(zhuǎn)一次服務(wù)啟動(dòng)直接報(bào)錯(cuò)JDK 版本不夠或配置讀不到確認(rèn) JDK 11 與配置路徑轉(zhuǎn)換結(jié)果全是方框中文字體沒(méi)裝按 3.2 節(jié)處理并清緩存一直轉(zhuǎn)圈這個(gè)現(xiàn)象我遇到過(guò)三次三次原因都不一樣一次是缺 libX 系列庫(kù)一次是 LibreOffice 安裝目錄寫(xiě)錯(cuò)一次是系統(tǒng)內(nèi)存不足導(dǎo)致 soffice 被殺掉。所以定位這類問(wèn)題不要瞎猜最有效的動(dòng)作是登錄服務(wù)器切到office.home目錄手動(dòng)跑一次命令行的轉(zhuǎn)換試試。能跑通說(shuō)明是服務(wù)配置問(wèn)題跑不通說(shuō)明是環(huán)境問(wèn)題一刀就把問(wèn)題范圍切一半。還有一種比較隱蔽的情況文檔本身是加密的。帶密碼的 Office 文檔 LibreOffice 轉(zhuǎn)不了會(huì)直接失敗。這種要在業(yè)務(wù)層提前識(shí)別并給出友好提示別讓用戶對(duì)著轉(zhuǎn)圈干等。5.2 顯示效果類問(wèn)題亂碼前面講過(guò)字體問(wèn)題占九成。剩下那一成是編碼問(wèn)題比如純文本文件txt、csv的編碼不是 UTF-8尤其是從老系統(tǒng)導(dǎo)出的 GBK 文件。KKFileView 對(duì)文本文件有編碼猜測(cè)機(jī)制但猜錯(cuò)的時(shí)候會(huì)出現(xiàn)亂碼。穩(wěn)妥的做法是讓上傳方統(tǒng)一轉(zhuǎn)成 UTF-8或者在配置里指定文本文件的默認(rèn)編碼。表格列寬錯(cuò)亂這是 Office 轉(zhuǎn) PDF 過(guò)程中的常見(jiàn)損耗。原文檔里用了一些自動(dòng)適應(yīng)或者百分比列寬的時(shí)候LibreOffice 的計(jì)算結(jié)果可能和微軟 Office 不一致導(dǎo)致轉(zhuǎn)出來(lái)的 PDF 里列寬看著別扭。這種情況沒(méi)有完美解法能做的是把文檔模板里的列寬改成固定值盡量避免復(fù)雜的合并單元格。圖片模糊PDF 轉(zhuǎn)圖片時(shí)有個(gè)分辨率參數(shù)默認(rèn)值在普通屏幕上夠用但在高分屏上看會(huì)有點(diǎn)糊。如果你的用戶對(duì)清晰度要求高可以調(diào)高轉(zhuǎn)換 DPI代價(jià)是文件體積和轉(zhuǎn)換時(shí)間都會(huì)上升。這是一個(gè)需要根據(jù)實(shí)際場(chǎng)景權(quán)衡的參數(shù)沒(méi)有免費(fèi)的午餐。pdf 轉(zhuǎn)圖片后導(dǎo)出變糊這是另一個(gè)環(huán)節(jié)的問(wèn)題——如果用戶是在預(yù)覽頁(yè)里想另存為圖片那清晰度受限于預(yù)覽時(shí)生成的分辨率。真要高清輸出建議引導(dǎo)用戶直接下載原文件而不是從預(yù)覽頁(yè)截圖或者另存。5.3 交互受限類問(wèn)題Word 表格列寬拖不動(dòng)、Excel 復(fù)制不了數(shù)據(jù)這兩個(gè)問(wèn)題被問(wèn)得最多我把它們放在一起講因?yàn)樗鼈儽举|(zhì)上是同一個(gè)原因預(yù)覽模式下文檔是圖片化呈現(xiàn)的用戶看到的是一張張渲染好的圖不是可交互的文檔對(duì)象。圖片上的表格線不是真的表格線你當(dāng)然拖不動(dòng)Excel 里的單元格不是真的單元格你當(dāng)然復(fù)制不了。這個(gè)代價(jià)是必須提前跟業(yè)務(wù)方說(shuō)清楚的。我的經(jīng)驗(yàn)是在需求評(píng)審階段就把這句話擺出來(lái)預(yù)覽是為了快速確認(rèn)內(nèi)容需要編輯或者精細(xì)操作請(qǐng)下載原文件。把預(yù)期管理好上線之后就不會(huì)有人天天提 bug。如果你在界面上再加一個(gè)顯眼的下載原文件按鈕配合起來(lái)體驗(yàn)就很順。有沒(méi)有辦法做到可交互有比如把 Excel 單獨(dú)走一條路用前端表格庫(kù)解析后渲染成真正的表格這樣就能復(fù)制能選中。但這條路維護(hù)成本高而且樣式還原度會(huì)下降。我的建議是分場(chǎng)景如果某個(gè)業(yè)務(wù)模塊的核心訴求就是看 Excel 里的數(shù)據(jù)并復(fù)制出來(lái)那就為它單獨(dú)做結(jié)構(gòu)化渲染如果只是附件預(yù)覽圖片化完全夠用。至于Word 關(guān)閉時(shí)卡頓、Excel 無(wú)法復(fù)制粘貼這類現(xiàn)象很多時(shí)候跟在線預(yù)覽沒(méi)有關(guān)系是用戶本地 Office 軟件自身的問(wèn)題插件沖突、緩存異常、宏安全設(shè)置等。區(qū)分方法很簡(jiǎn)單讓用戶在沒(méi)打開(kāi)預(yù)覽系統(tǒng)的純凈環(huán)境下試一次如果照樣卡那就跟你的系統(tǒng)無(wú)關(guān)。這個(gè)判斷方法能幫你省下大量扯皮時(shí)間。5.4 性能與穩(wěn)定性問(wèn)題首次預(yù)覽慢這是架構(gòu)決定的接受它但可以用預(yù)轉(zhuǎn)換來(lái)緩解。如果某個(gè)文件被頻繁預(yù)覽可以在上傳完成之后異步觸發(fā)一次轉(zhuǎn)換讓緩存提前生成。這個(gè)做法對(duì)熱門附件效果非常明顯冷啟動(dòng)從十幾秒降到一秒內(nèi)。并發(fā)上來(lái)之后轉(zhuǎn)換排隊(duì)LibreOffice 的轉(zhuǎn)換是重 CPU 操作單機(jī)并發(fā)能力有限。如果同時(shí)有十幾個(gè)人預(yù)覽大文件就會(huì)出現(xiàn)集體變慢。緩解手段有幾個(gè)一是開(kāi)緩存減少重復(fù)轉(zhuǎn)換二是給轉(zhuǎn)換任務(wù)加個(gè)隊(duì)列控制并發(fā)數(shù)三是直接上多實(shí)例加負(fù)載均衡。中小項(xiàng)目用前兩個(gè)就夠了。大文件直接把內(nèi)存打高Java 堆內(nèi)存要給足同時(shí)注意上傳大小限制。我一般會(huì)把堆內(nèi)存設(shè)置成物理內(nèi)存的一半左右并配合監(jiān)控觀察 GC 情況。如果發(fā)現(xiàn)頻繁 Full GC要么加內(nèi)存要么限制單文件大小。磁盤寫(xiě)滿導(dǎo)致服務(wù)異常這是最典型的運(yùn)維事故表現(xiàn)是隨機(jī)文件預(yù)覽失敗特別有迷惑性。一定要配好緩存清理和磁盤監(jiān)控告警告警閾值設(shè)在 80%。這條建議看起來(lái)平平無(wú)奇但它救過(guò)我不止一次。6. 生產(chǎn)運(yùn)維與擴(kuò)展玩法6.1 緩存清理與磁盤守護(hù)緩存清理的配置在application.properties里cache.clean.enabled打開(kāi)后按 cron 定時(shí)執(zhí)行。但配置的清理只是按時(shí)間刪我建議再加一層磁盤水位保護(hù)寫(xiě)一個(gè)簡(jiǎn)單的腳本每小時(shí)檢查一次緩存目錄占用超過(guò)閾值就按最舊優(yōu)先刪一部分。兩層保險(xiǎn)疊加基本不會(huì)出現(xiàn)磁盤寫(xiě)滿的情況。還有一個(gè)細(xì)節(jié)服務(wù)重啟之后正在進(jìn)行的轉(zhuǎn)換任務(wù)會(huì)中斷可能留下半截的臨時(shí)文件。所以在啟動(dòng)腳本里加一句清理殘留臨時(shí)目錄的動(dòng)作比事后手工清理靠譜得多。臨時(shí)文件命名一般帶時(shí)間戳按時(shí)間過(guò)濾刪除就行別寫(xiě)成一刀切把整個(gè)目錄刪了——那樣會(huì)把有效緩存也清掉用戶體驗(yàn)會(huì)突然變差。6.2 并發(fā)、JVM 與轉(zhuǎn)換進(jìn)程池JVM 參數(shù)我一般這么配初始堆和最大堆設(shè)成一樣大避免運(yùn)行期反復(fù)擴(kuò)容新生代給大一點(diǎn)因?yàn)檗D(zhuǎn)換過(guò)程中會(huì)產(chǎn)生大量臨時(shí)對(duì)象GC 選 G1停頓更可控。這些參數(shù)沒(méi)有絕對(duì)標(biāo)準(zhǔn)要看你的機(jī)器規(guī)格和實(shí)際負(fù)載建議上線后開(kāi)著監(jiān)控觀察一周再調(diào)。并發(fā)控制方面如果你的項(xiàng)目規(guī)模不大一個(gè)簡(jiǎn)單做法是在網(wǎng)關(guān)層對(duì)預(yù)覽接口做限流比如單 IP 每分鐘多少次。這樣即使有人寫(xiě)腳本批量請(qǐng)求也不會(huì)把轉(zhuǎn)換進(jìn)程池打爆。KKFileView 本身對(duì)同時(shí)進(jìn)行的轉(zhuǎn)換數(shù)量有一定控制但結(jié)合你自己的業(yè)務(wù)特點(diǎn)做一層限流更穩(wěn)妥。6.3 還能擴(kuò)展成什么3D 模型、壓縮包與代碼文件最后說(shuō)說(shuō)這個(gè)方案的可擴(kuò)展性這是它比商業(yè)方案更討喜的地方。4.x 版本內(nèi)置了 three.js可以直接在線預(yù)覽 glb、gltf 這類三維模型文件。如果你的系統(tǒng)涉及產(chǎn)品模型庫(kù)、設(shè)備三維展示這個(gè)能力幾乎白送——上傳的模型文件直接丟給預(yù)覽接口就行瀏覽器端會(huì)自動(dòng)用 WebGL 渲染鼠標(biāo)能旋轉(zhuǎn)縮放。內(nèi)網(wǎng)環(huán)境下這個(gè)功能尤其實(shí)用因?yàn)楹芏嘣诰€三維查看服務(wù)都需要外網(wǎng)。另外壓縮包內(nèi)容列表、代碼文件高亮、音視頻播放這些它也都支持。等于你部署一個(gè)服務(wù)順手解決了系統(tǒng)里一大半文件類型的展示需求。我在一個(gè)教學(xué)資源項(xiàng)目里就靠它一次性覆蓋了課件、視頻、代碼示例和三維模型四類內(nèi)容省掉了至少三個(gè)獨(dú)立的預(yù)覽模塊開(kāi)發(fā)工作量。再往深一點(diǎn)如果你的系統(tǒng)里還有其他文件處理需求比如需要做格式轉(zhuǎn)換、批量導(dǎo)出可以考慮把 KKFileView 里那套轉(zhuǎn)換鏈路單獨(dú)抽出來(lái)復(fù)用。它的核心價(jià)值不在那個(gè) Web 界面而在內(nèi)網(wǎng)可離線運(yùn)行的文件格式轉(zhuǎn)換能力這件事本身。我在實(shí)際項(xiàng)目里的體會(huì)是這類獨(dú)立服務(wù)加輕量前端的架構(gòu)特別適合內(nèi)網(wǎng)系統(tǒng)。因?yàn)樗褟?fù)雜度和不確定性都收攏到一臺(tái)可控的機(jī)器上前端保持簡(jiǎn)單出問(wèn)題時(shí)排查半徑小升級(jí)時(shí)影響面也小。反過(guò)來(lái)把所有解析邏輯塞進(jìn)前端看著是省了一次部署實(shí)際是把風(fēng)險(xiǎn)分散到了每一個(gè)用戶的瀏覽器上遇到兼容性問(wèn)題根本沒(méi)法統(tǒng)一處理。最后再分享一個(gè)我用了很久的小技巧在預(yù)覽頁(yè)帶上文件的最后修改時(shí)間作為緩存版本標(biāo)識(shí)用戶替換文件之后預(yù)覽地址自動(dòng)變化緩存自然失效不用手動(dòng)清也不會(huì)看到舊內(nèi)容。這個(gè)改動(dòng)很小但能省掉很多我看到的是舊版本的溝通成本。