目錄一、今日概覽二、快速查詢前端接入一個配置該不該復(fù)用的判斷配置獨立的決策副線菜單導(dǎo)入生產(chǎn)的層級丟失三、數(shù)據(jù)看板從整頁空白到局部降級全局兜底 vs 局部處理四、PDF 導(dǎo)出排障一次方案的三段反復(fù)第一段要不要裝瀏覽器第二段能不能干脆不裝瀏覽器純前端第三段回到后端渲染但修了 Host 坑五、導(dǎo)出報告前端化原生 HTML拒絕截圖六、發(fā)版與收尾七、復(fù)盤一條暗線脫敏說明本文內(nèi)部項目以化名出現(xiàn)——lab-web前端、lab-aidoc/lab-biz后端、lab-agentAgent 服務(wù)、agent-web另一個前端項目。業(yè)務(wù)模塊泛化為某識別模塊/某核驗?zāi)K等具體角色、測試文件已化名。chromedp、pandoc、k3s、Chromium、UmiJS 等開源/通用技術(shù)名詞保留原稱。今天的工作密度不小21 個 codex 會話里真正落地的開發(fā)有五攤一攤前端接入、一攤?cè)蒎e改造、兩攤都圍繞導(dǎo)出打轉(zhuǎn)外加發(fā)版。有意思的是看似散活的幾件事背后有同一條暗線——“渲染質(zhì)量取決于數(shù)據(jù)是原生還是截圖而架構(gòu)位置決定了運維成本”。這個到復(fù)盤再串先按時間順序展開。一、今日概覽模塊事項類型lab-web快速查詢quick-query前端接入從 agent-web 遷移頁面功能lab-aidoc快速查詢硬編碼超時改為配置可調(diào)且配置獨立不復(fù)用 OCR 配置重構(gòu)lab-web數(shù)據(jù)看板局部降級單個服務(wù)失敗不再導(dǎo)致整頁空白修復(fù)lab-biz/aidocPDF 導(dǎo)出生產(chǎn)排障google-chrome not found→ k3s 獨立 chromium 服務(wù) Host 頭修復(fù)排障lab-web三個模塊導(dǎo)出報告從后端渲染改為前端原生 HTML 導(dǎo)出重構(gòu)后臺菜單導(dǎo)入生產(chǎn)層級丟失修復(fù)、菜單全量移除 icon修復(fù)全棧lab-agent、lab-web 發(fā)版發(fā)版二、快速查詢前端接入一個配置該不該復(fù)用的判斷快速查詢的后端模塊早就實現(xiàn)了但前端一直沒接。這攤活本以為是搬頁面實際牽出一個值得記的配置取舍。頁面本身從agent-web遷過來問題不大用一份 PDF 樣本跑通流程后重點轉(zhuǎn)到后端快速查詢的 OCR走不走版面感知layout_aware流程、超時怎么管。配置獨立的決策超時原本是硬編碼的要改成配置可調(diào)。第一版順手把它掛到了現(xiàn)成的 OCR LLM 配置ocrllm下面——反正都是 LLM 調(diào)用復(fù)用一套配置省事。但這個省事很快被否掉了理由很直接快速查詢應(yīng)該是它自己本身而不是 OCR 服務(wù)的附庸。第一版復(fù)用最終獨立被否快速查詢≠OCR快速查詢超時配置放哪?ocrllm 配置省事但耦合quick_query 自己的配置段獨立可演化這是個挺典型的判斷復(fù)用不是看現(xiàn)在像不像而是看以后會不會各自演化?？焖俨樵兒?OCR 固然都要調(diào) LLM但它們的模型選擇、超時容忍度、并發(fā)模式遲早會分叉。一旦塞進同一個配置段未來任何一方調(diào)整都得顧忌另一方。趁現(xiàn)在還沒有歷史依賴把它獨立出來成本最低。副線菜單導(dǎo)入生產(chǎn)的層級丟失接入過程中還插了一個后臺問題把菜單導(dǎo)出再導(dǎo)入生產(chǎn)環(huán)境后只有數(shù)據(jù)中心保留了原來的層級結(jié)構(gòu)其余模塊全攤平成了一級菜單。根因不在導(dǎo)入邏輯本身而在只導(dǎo)了菜單表、漏了角色綁定生產(chǎn)的唯一角色化名某角色丟失了對父級菜單的層級綁定。修復(fù)是重建core_role_menu_ref——把那 30 條菜單按最終結(jié)構(gòu)重新綁回角色。順帶把所有菜單的icon字段全量清空前端icon為空就不渲染純文本菜單更干凈。一個小教訓(xùn)導(dǎo)數(shù)據(jù)只導(dǎo)主表是常見坑。菜單的層級關(guān)系除了菜單表自身的parent_code還依賴角色-菜單綁定表漏了關(guān)聯(lián)表結(jié)構(gòu)就會在導(dǎo)入端塌掉。三、數(shù)據(jù)看板從整頁空白到局部降級數(shù)據(jù)看板頁面有個惱人的現(xiàn)象后端任意一個服務(wù)接口報錯整個頁面就空白其它正常的服務(wù)數(shù)據(jù)也一起看不到了。需求很明確一個服務(wù)出錯只把那一塊顯示為錯誤別拖垮整頁。全局兜底 vs 局部處理一開始想的是一勞永逸的路子——在請求層的全局回調(diào)里統(tǒng)一兜底或者加個統(tǒng)一封裝。但這條路的代價是侵入公共代碼要動utils/request.ts這種被全局引用的基礎(chǔ)設(shè)施影響面太大而且局部降級的策略每個頁面其實不一樣看板是分塊容錯別的頁面可能是整頁重試全局兜底很難精確表達。全局兜底局部 catch數(shù)據(jù)看板: 多個服務(wù)分塊某服務(wù)失敗整頁空白原行為僅該區(qū)塊顯示錯誤其它正常展示權(quán)衡之后走了指定頁面局部處理在每個分塊請求處單獨 catch失敗的那塊降級成錯誤態(tài)其余照常渲染。代價是每個用了多服務(wù)的頁面都得自己寫一遍 catch但它零侵入公共代碼且容錯策略完全由各頁面自己說了算。這個取舍背后有個原則容錯策略是頁面級語義不是請求級通用。一個 HTTP 500 在不同頁面的含義不同——在看板里是這一格暫時沒數(shù)據(jù)在表單提交里可能是必須重試。把它強行收進全局回調(diào)等于讓基礎(chǔ)設(shè)施去猜業(yè)務(wù)語義猜不準就會在某個頁面出錯。所以寧可每個頁面多寫幾行 catch也不讓公共代碼背上它不該懂的語義。順帶澄清了一個小疑惑登錄后落地頁其實是數(shù)據(jù)看板history.replace(/data-board)那個帶3 條熱點新聞/國產(chǎn)化率目標的歡迎頁是純靜態(tài)硬編碼、不調(diào)任何接口的備用入口——所以它永遠不會空白。四、PDF 導(dǎo)出排障一次方案的三段反復(fù)這攤最有故事性。生產(chǎn)環(huán)境arm下載報告 PDF 直接報錯chromedp PDF 生成失敗: exec: google-chrome: executable file not found in $PATH后端用 chromedp 驅(qū)動 Chrome 把頁面渲染成 PDF但生產(chǎn)鏡像里壓根沒裝 Chrome。圍繞怎么讓它能用方案來回擺了三下。鏡像爆炸大別的服務(wù)也需要不想裝瀏覽器截圖實現(xiàn)→模糊分頁生硬報錯: google-chrome not found方案1: 給業(yè)務(wù)鏡像裝 Chrome方案2: k3s 內(nèi)獨立 chromium 服務(wù)方案3: 純前端導(dǎo)出截圖質(zhì)量不達標Host 頭校驗坑修: 服務(wù)名解析成 ClusterIP用 IP 請求? 后端渲染方案打通第一段要不要裝瀏覽器給業(yè)務(wù)鏡像塞 Chrome 是最直覺的但立刻被否——鏡像會膨脹得很難看而且不止這一個服務(wù)需要瀏覽器。于是傾向k3s 里跑一個獨立的 chromium 服務(wù)大家共用。第二段能不能干脆不裝瀏覽器純前端期間認真評估了純前端導(dǎo)出想借此甩掉瀏覽器依賴。但實測下來踩了兩個坑截圖方式導(dǎo)出畫面發(fā)虛柵格化的天然短板而且分頁很生硬把一整頁 DOM 截成圖片再切表格/文字會被攔腰截斷。對于內(nèi)容是長文本情報速遞一期幾十條新聞全文的報告截圖方案的質(zhì)量過不了關(guān)。這一段的價值不在結(jié)論而在把純前端的邊界摸清了截圖導(dǎo)出只適合所見即所得的單屏內(nèi)容不適合長內(nèi)容、要分頁、要清晰文字的報告。第三段回到后端渲染但修了 Host 坑最終情報速遞還是走后端 chromedp k3s 獨立 chromium 服務(wù)。但獨立服務(wù)又撞出一個隱蔽的坑Chrome 的遠程調(diào)試端口會校驗 Host 頭只接受localhost或 IP。用 k8s 服務(wù)名比如某chromium服務(wù)去請求DNS 解析沒問題、路由也通請求確實到了瀏覽器 Pod卻被 Chrome 自己的 Host 校驗擋了回來。修復(fù)不在 k8s 配置層而在代碼里后端把服務(wù)名解析成 ClusterIP再用http://ClusterIP:9222發(fā)請求——Host 頭變成 IPChrome 就放行了。Service → Pod 的轉(zhuǎn)發(fā) k8s 本來就處理好了所以 yaml 一行不用改。http://某chromium服務(wù):9222Host服務(wù)名Host 校驗拒絕只認 localhost/IP先解析服務(wù)名→ClusterIPhttp://IP:9222HostIPHostIP 放行后端Chrome 遠程調(diào)試端口? 被擋ClusterIPChrome? 渲染成功這是個非常容易誤判的坑——報錯像網(wǎng)絡(luò)問題其實是瀏覽器自己的安全校驗。如果一味去查 k8s 網(wǎng)絡(luò)/DNS/Service會繞很大彎子。最后還差一塊節(jié)點上得放中文字體思源黑體否則渲染出來的 PDF 中文全是方塊。這是 arm 生產(chǎn)環(huán)境常見配置缺失和代碼無關(guān)但少了它整套方案就白搭。五、導(dǎo)出報告前端化原生 HTML拒絕截圖排障期間順帶推動了另一個方向的重構(gòu)把三個模塊情報速遞、某識別模塊、某核驗?zāi)K的導(dǎo)出報告從后端渲染改成前端導(dǎo)出。這里有個明確的硬約束必須用原生導(dǎo)出不能用截圖等捷徑——這正是上一節(jié)截圖模糊/分頁生硬教訓(xùn)的直接延伸。也評估過 pandocHTML → PDF但最終選定原生 HTML 渲染 瀏覽器打印/下載這條路建一個共享導(dǎo)出工具渲染一份 HTML 文檔走瀏覽器原生的打印/下載保留原報告模板的樣式不是另起爐灶而是把后端模板移植到前端某核驗?zāi)K的字段原本是后端預(yù)渲染好的改造成后端把原始字段放開給前端前端用原模板渲染——這樣前端拿的是原生數(shù)據(jù)而非截圖這條路和第四節(jié)的 chromedp 方案看似矛盾其實是按場景分工情報速遞內(nèi)容長、要分頁、且已有成熟后端渲染保留 chromedp而這三個模塊的報告結(jié)構(gòu)更適合前端原生渲染、且能省掉對瀏覽器服務(wù)的依賴。沒有銀彈按每個導(dǎo)出的內(nèi)容形態(tài)選方案。六、發(fā)版與收尾lab-agent前后端發(fā)版lab-web提交推送數(shù)據(jù)看板降級、快速查詢接入等PDF Host 修復(fù)提交發(fā)版構(gòu)建 #139新鏡像含修復(fù)七、復(fù)盤一條暗線把今天幾攤活串起來看有一條暗線渲染質(zhì)量取決于數(shù)據(jù)是原生還是截圖而在哪里渲染決定了運維成本。截圖永遠是下策。數(shù)據(jù)看板的降級、PDF 導(dǎo)出的反復(fù)、導(dǎo)出前端化的硬約束三次都指向同一個結(jié)論截圖/柵格化會丟掉原生 DOM 的清晰度和分頁能力。需要可讀、可分頁的內(nèi)容必須用原生數(shù)據(jù) 原生渲染。在哪里渲染是架構(gòu)選擇題不是技術(shù)細節(jié)。后端渲染chromedp質(zhì)量好但要養(yǎng)一個瀏覽器服務(wù)、還附帶 Host 校驗/字體/鏡像體積等運維成本前端渲染省依賴但要自己處理分頁和樣式。今天的每個導(dǎo)出模塊都按自己的內(nèi)容形態(tài)在這個光譜上選了位置沒有一刀切。復(fù)用看未來不看現(xiàn)在?？焖俨樵兣渲靡灰獟斓?OCR 配置下看的不是現(xiàn)在都調(diào) LLM而是以后會不會各自演化。耦合一旦形成拆的成本永遠比現(xiàn)在獨立高。容錯是頁面語義別塞進基礎(chǔ)設(shè)施。全局請求回調(diào)懂不了這一格失敗該不該拖垮整頁所以局部降級留給頁面自己寫。公共代碼保持不懂業(yè)務(wù)的克制。報錯像網(wǎng)絡(luò)問題未必是網(wǎng)絡(luò)問題。chromedp 的 Host 頭校驗坑偽裝成了 k8s 連通性問題。遇到路由通了但被拒先想想是不是目標服務(wù)自己的安全校驗。