與輸入校驗實戰(zhàn)指南)
Resume-Matcher 前端安全加固Next.js Server Actions 認證、授權(quán)與輸入校驗實戰(zhàn)指南【免費下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher本篇為 Resume-Matcher 倉庫docs/portable/nextjs-performance系列中Server Actions 安全CRITICAL 級別的技術(shù)指南。它直指 Next.js App Router 開發(fā)中最容易被忽視的安全盲區(qū)Server Actions 本質(zhì)上是公開的 HTTP 端點僅靠前端隱藏按鈕無法提供任何保護。讀完本文你將掌握認證 → 授權(quán) → 校驗 → 執(zhí)行的完整動作安全范式、可復用的高階包裝器寫法以及如何將該范式落地到 Resume-Matcher 這類前端 Next.js 后端 FastAPI架構(gòu)中讓每一次動作調(diào)用都經(jīng)得起攻擊者直接構(gòu)造請求的考驗。核心事實Server Actions 是公開的 HTTP 端點在 Next.js App Router 中使用use server指令聲明的函數(shù)看起來像普通函數(shù)——從 Client Component 里 import 后直接調(diào)用即可。但從源碼結(jié)構(gòu)看Next.js 會在構(gòu)建期把每個 Server Action 暴露為一條可被 HTTP POST 請求直接命中的路由任何擁有 fetch 客戶端的攻擊者都可以繞過 UI 直接調(diào)用它。由此得出本系列文檔的第一安全鐵律永遠不要信任調(diào)用方call site。這個按鈕只對管理員顯示不構(gòu)成任何保護——攻擊者完全無視 UI 狀態(tài)以任意 payload 直接調(diào)用 action。這意味著每一個 Server Action 都必須在action 函數(shù)體內(nèi)完成認證與授權(quán)檢查而不是依賴組件層級的條件渲染。為什么隱藏 UI救不了你攻擊者的完整攻擊路徑非常簡單打開瀏覽器開發(fā)者工具的 Network 面板找到按鈕觸發(fā)時發(fā)出的 action 端點用任意 HTTP 客戶端直接向該端點發(fā)起請求攜帶任意resourceId越權(quán)刪除任何記錄。文檔中明確給出了這條攻擊路徑的唯一解客戶端沒有任何一種防護手段能修復這個問題校驗必須落在服務(wù)端 action 內(nèi)部。危險模式無校驗的刪除動作先看最常見的反例——一個看起來安全實則完全裸露的 action// ? BAD: No auth check — anyone can delete any record use server; export async function deleteResource(resourceId: string) { await db.resource.delete({ where: { id: resourceId } }); return { success: true }; }問題分析逐條對照文檔中的攻擊路徑接受裸的resourceId字符串未做任何身份確認未驗證調(diào)用者是否為該資源的屬主未對resourceId做格式與存在性校驗一旦被直接 POST即可刪除任意記錄。文檔強調(diào)看起來安全正是這種模式的迷惑性所在——按鈕可能只在登錄用戶可見、甚至只在管理員可見但 action 端點是公開的。不存在任何客戶端側(cè)守衛(wèi)能修復它。安全模式認證 → 授權(quán) → 執(zhí)行正確的姿勢是在 action 內(nèi)部按順序完成三道檢查再執(zhí)行真正的業(yè)務(wù)操作// ? GOOD: Verify auth, then ownership, then act use server; import { auth } from /lib/auth; import { revalidatePath } from next/cache; export async function deleteResource(resourceId: string) { // 1. Authentication — is anyone logged in? const session await auth(); if (!session?.user) { throw new Error(Unauthorized); } // 2. Authorization — does this user own this resource? const resource await db.resource.findUnique({ where: { id: resourceId } }); if (!resource || resource.userId ! session.user.id) { throw new Error(Forbidden); } // 3. Now its safe to perform the action await db.resource.delete({ where: { id: resourceId } }); revalidatePath(/dashboard); return { success: true }; }順序至關(guān)重要先認證authenticate再授權(quán)authorize最后執(zhí)行act。三道檢查缺一不可且順序不能顛倒——認證失敗就無需繼續(xù)查詢資源授權(quán)檢查必須基于已確認的會話身份進行。示例中還示范了兩個容易被忽略的細節(jié)資源不存在!resource與資源不屬于當前用戶userId ! session.user.id統(tǒng)一返回Forbidden避免通過響應(yīng)差異泄露資源存在性動作完成后調(diào)用revalidatePath(/dashboard)使相關(guān)頁面緩存失效保證下次訪問看到的是刪除后的狀態(tài)。三層檢查認證、授權(quán)、校驗文檔用一張表總結(jié)了 Server Action 必須通過的三層防線層級要回答的問題失敗響應(yīng)Authentication認證是否存在已登錄用戶Unauthorized等價 401Authorization授權(quán)該用戶是否有權(quán)操作此資源Forbidden等價 403Validation校驗輸入的結(jié)構(gòu)與取值是否合理Invalid input等價 400跳過任意一層都是安全漏洞。最常見的錯誤是做了認證卻跳過授權(quán)——已登錄不等于有權(quán)觸碰這條記錄。以本文開頭的deleteResource為例一個普通登錄用戶可以嘗試刪除任意resourceId只有屬主校驗resource.userId ! session.user.id才能真正阻止越權(quán)刪除。輸入校驗永遠不要信任傳入的數(shù)據(jù)形狀Server Actions 接受調(diào)用方傳來的任何東西。文檔要求任何接收結(jié)構(gòu)化輸入的 action頂部都必須使用 schema 校驗器Zod、Valibot 等。use server; import { z } from zod; import { auth } from /lib/auth; const UpdateProfileSchema z.object({ name: z.string().min(1).max(100), bio: z.string().max(500), }); export async function updateProfile(input: unknown) { const session await auth(); if (!session?.user) throw new Error(Unauthorized); // Validate before touching the DB const data UpdateProfileSchema.parse(input); await db.user.update({ where: { id: session.user.id }, data, }); }該示例體現(xiàn)的實踐要點入口類型聲明為unknown先假定輸入不可信必須經(jīng)過 schema 解析才能獲得可信類型schema 定義了明確的邊界name非空且最長 100 字符bio最長 500 字符——字符串長度上限直接阻斷超大 payload 型攻擊校驗先于數(shù)據(jù)庫寫入未經(jīng) schema 解析的原始input永遠不進入 ORM 調(diào)用schema 即白名單字段被 schema 聲明時已隱式地允許通過未聲明的字段如role: admin在解析結(jié)果中被剔除。文檔特別警告了不校驗的后果攻擊者可以傳入{ name: huge string, role: admin }數(shù)據(jù)庫寫入可能靜默覆蓋你并未打算暴露的字段。schema 校驗正是阻斷這類字段注入的閘門。復用高階包裝器authedAction當多個 action 需要同樣的認證檢查時文檔推薦將它們提煉為高階函數(shù)higher-order function包裝器避免每個 action 重復粘貼認證代碼// lib/action.ts import { auth } from /lib/auth; export function authedActionTInput, TOutput( fn: (input: TInput, userId: string) PromiseTOutput ) { return async (input: TInput): PromiseTOutput { const session await auth(); if (!session?.user) throw new Error(Unauthorized); return fn(input, session.user.id); }; }業(yè)務(wù) action 隨后被大幅簡化use server; import { authedAction } from /lib/action; export const deleteResource authedAction(async (resourceId: string, userId) { const resource await db.resource.findUnique({ where: { id: resourceId } }); if (!resource || resource.userId ! userId) { throw new Error(Forbidden); } await db.resource.delete({ where: { id: resourceId } }); });設(shè)計要點包裝器強制保證認證必發(fā)生——被包裝的函數(shù)拿到的第一個參數(shù)就是已確認的userId業(yè)務(wù)函數(shù)無法忘記認證但文檔明確提醒逐資源的授權(quán)檢查仍然必須由業(yè)務(wù)函數(shù)自己編寫這里沒有任何捷徑——authedAction解決的是是否登錄解決不了是否允許動這條記錄泛型參數(shù)TInput/TOutput讓包裝器保持類型安全fn(input, session.user.id)將認證結(jié)果顯式注入業(yè)務(wù)邏輯便于測試時注入 mock 身份。心智模型把每個 Server Action 當成公開端點來審查文檔在結(jié)尾給出了一個可執(zhí)行的心智模型值得作為代碼評審時的口頭禪把每一個 Server Action 都當作一個未經(jīng)認證的、攻擊者正在閱讀源碼的 HTTP 端點來對待。用這個模型審視任意一個 action如果它讓你產(chǎn)生不安這里好像少了點什么——說明它確實缺檢查立刻修如果它沒有讓你產(chǎn)生不安——你大概率遺漏了一道檢查。自檢清單對應(yīng)checklist.md中 Server Actions 一節(jié)的逐項要求路徑見 checklist.md每個 Server Action 頂部都調(diào)用auth()或等價實現(xiàn)每個接收資源 ID 的 action 都驗證了該資源的屬主關(guān)系輸入使用 schemaZod、Valibot 等校驗——永遠不信任輸入形狀錯誤以 throw 方式暴露而非靜默記錄日志。落地到 Resume-Matcher前端與后端的職責劃分將上述范式落地到 Resume-Matcher 倉庫時需要先理解其實際架構(gòu)前端apps/frontendNext.js App Router與后端apps/backendFastAPI是分離的兩層且當前倉庫的前端源碼中并未出現(xiàn)use server或revalidatePath的調(diào)用可通過在apps/frontend下檢索確認。從源碼結(jié)構(gòu)看前端的數(shù)據(jù)變更統(tǒng)一走 REST 客戶端再經(jīng) Next.js 代理到 FastAPI——這與文檔中的純 Server Actions 模式存在差異但三層檢查范式與威脅模型完全通用1. 動作端點在服務(wù)端受信任邊界內(nèi)Resume-Matcher 的前端 API 客戶端把所有請求收斂在 client.tsapiFetch統(tǒng)一封裝超時默認DEFAULT_TIMEOUT_MS受NEXT_PUBLIC_REQUEST_TIMEOUT_MS環(huán)境變量控制區(qū)間 30s–30min缺省 240s與AbortController中止邏輯所有寫操作經(jīng)apiPost/apiPatch/apiPut/apiDelete發(fā)出并在 config.ts 中以credentials: include攜帶會話 Cookie。這套設(shè)計在概念上等同于前端永遠通過受限的調(diào)用通道觸達動作端點——但正如文檔所警示的通道封裝并不能替代服務(wù)端校驗任何請求最終都會落到 FastAPI 路由上安全邊界必須在那里收口。2. 服務(wù)端校驗與文檔三層檢查一一對應(yīng)以簡歷上傳為例resumes.py 中的upload_resume端點完整體現(xiàn)了校驗 → 授權(quán)邊界 → 執(zhí)行的落點輸入校驗Validation先檢查content_type是否在ALLOWED_TYPES白名單內(nèi)PDF/DOC/DOCX不合法直接400再讀取內(nèi)容校驗MAX_FILE_SIZE4MB上限與空文件超限返回413解析后若提取不到文本掃描件/圖片型 PDF返回422。這些與文檔中輸入結(jié)構(gòu)不合理 → Invalid input等價 400一一對應(yīng)動作隔離執(zhí)行邊界解析成功后才原子地創(chuàng)建 master 記錄create_resume_atomic_master隨后嘗試結(jié)構(gòu)化解析、更新processing_status并返回帶request_id的ResumeUploadResponse兜底容錯文檔強調(diào)錯誤要 throw不要靜默吞掉后端則以_raise_improve_error封裝HTTPException(500)與各分支的logger.error/warning組合保證失敗可觀測且錯誤有明確的 HTTP 語義。再以改進簡歷流程為例improve_resume_preview_endpoint先驗證resume_id、job_id存在否則 404再用asyncio.wait_for包裹整條 LLM 調(diào)用鏈并以settings.request_timeout_seconds限時超時返回504。這對應(yīng)文檔中在進入昂貴操作前完成校驗/認證的原則——把校驗放在昂貴異步工作之前與系列文檔 01-waterfalls.md 中Validation/auth checks happen before expensive async work的檢查項一致。3. 縱深防御LLM 輸出同樣不信任一個值得注意的倉庫特色Resume-Matcher 在服務(wù)端對 LLM 生成內(nèi)容施加了多道白名單/恢復防線本質(zhì)上也是不信任輸入思想的延伸_preserve_personal_info將原始簡歷的personalInfo深拷貝回寫防止 AI 改寫個人信息_restore_original_datesrestore_dates_from_markdown還原被 LLM 截斷的日期精度_preserve_original_skills任何被 LLM 丟棄的原始技能/證書/語言/獎項都會被追加回來_protect_custom_sections裁剪 LLM 幻想的自定義條目、還原被篡改的空描述_hash_improved_data通過規(guī)范化后的一致性哈希保證 preview 與 confirm 兩階段的 payload 完全一致防止中間篡改否則直接 400 拒絕。這些實現(xiàn)與動作端點必須自證輸入可信的文檔思想同構(gòu)可作為理解文檔范式的絕佳倉庫內(nèi)實證詳見 resumes.py。4. 若未來引入 Server Actions如果你計劃在 Resume-Matcher 的前端或任何 Next.js 應(yīng)用中新增 Server Actions 直接寫數(shù)據(jù)請嚴格套用本文檔的全部范式頂部auth()確認會話按資源執(zhí)行屬主/角色授權(quán)schema 校驗所有結(jié)構(gòu)化輸入Zod/Valibot通過throw暴露錯誤配合revalidatePath同步緩存數(shù)量多時用authedAction之類的包裝器收口認證邏輯。同時注意本倉庫的代理約束當前 next.config.ts 通過 rewrites 將/api/:path*代理到 FastAPI默認http://127.0.0.1:8000并明確注釋不要創(chuàng)建app/api/路由否則會遮蔽后端代理——新增 Server Actions 前需評估是否會與既有/api代理發(fā)生路由沖突。與同系列文檔的關(guān)系本文是 Next.js 15 性能與安全系列的第 3 篇CRITICAL 級別同系列還包括01-waterfalls.md串行 await 瀑布流消除、Promise.all并行取數(shù)與 Suspense 流式渲染02-bundle-size.mdbarrel import 裁剪、動態(tài)導入與第三方腳本04-server-side-perf.mdReact.cache()請求去重、裁剪 Server→Client 序列化數(shù)據(jù)、after()非阻塞后置任務(wù)checklist.mdPR 前檢查清單與next.config.js基線模板。按系列建議的閱讀順序前三篇瀑布流、bundle、Server Actions 安全屬于不修必吃虧的 CRITICAL 級別其中本文雖然篇幅最短卻是唯一與安全直接相關(guān)、沒有商量余地的硬性要求——性能可以逐步優(yōu)化越權(quán)漏洞必須當場修復?？偨Y(jié)Server Actions 是公開 HTTP 端點UI 隱藏不等于安全攻擊者可攜帶任意 payload 直接調(diào)用三道檢查缺一不可認證是否登錄→ 授權(quán)是否允許動這條記錄→ 校驗輸入形狀與取值是否合理順序不能亂schema 校驗前置unknown入口 Zod/Valibot 白名單解析阻斷字段注入與超大 payload包裝器收口認證authedAction強制認證發(fā)生但逐資源授權(quán)仍需手寫心智模型把每個 action 當成攻擊者在讀源碼的公開端點來審查不安就修不修就等著出事倉庫實證Resume-Matcher 將同樣的服務(wù)端信任邊界 輸入白名單 縱深防御思想貫徹在 resumes.py 的 FastAPI 端點中可作為對照實現(xiàn)?！久赓M下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Resume-Matcher 前端安全加固：Next.js Server Actions 認證、授權(quán)與輸入校驗實戰(zhàn)指南
Resume-Matcher 前端安全加固Next.js Server Actions 認證、授權(quán)與輸入校驗實戰(zhàn)指南【免費下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher本篇為 Resume-Matcher 倉庫docs/portable/nextjs-performance系列中Server Actions 安全CRITICAL 級別的技術(shù)指南。它直指 Next.js App Router 開發(fā)中最容易被忽視的安全盲區(qū)Server Actions 本質(zhì)上是公開的 HTTP 端點僅靠前端隱藏按鈕無法提供任何保護。讀完本文你將掌握認證 → 授權(quán) → 校驗 → 執(zhí)行的完整動作安全范式、可復用的高階包裝器寫法以及如何將該范式落地到 Resume-Matcher 這類前端 Next.js 后端 FastAPI架構(gòu)中讓每一次動作調(diào)用都經(jīng)得起攻擊者直接構(gòu)造請求的考驗。核心事實Server Actions 是公開的 HTTP 端點在 Next.js App Router 中使用use server指令聲明的函數(shù)看起來像普通函數(shù)——從 Client Component 里 import 后直接調(diào)用即可。但從源碼結(jié)構(gòu)看Next.js 會在構(gòu)建期把每個 Server Action 暴露為一條可被 HTTP POST 請求直接命中的路由任何擁有 fetch 客戶端的攻擊者都可以繞過 UI 直接調(diào)用它。由此得出本系列文檔的第一安全鐵律永遠不要信任調(diào)用方call site。這個按鈕只對管理員顯示不構(gòu)成任何保護——攻擊者完全無視 UI 狀態(tài)以任意 payload 直接調(diào)用 action。這意味著每一個 Server Action 都必須在action 函數(shù)體內(nèi)完成認證與授權(quán)檢查而不是依賴組件層級的條件渲染。為什么隱藏 UI救不了你攻擊者的完整攻擊路徑非常簡單打開瀏覽器開發(fā)者工具的 Network 面板找到按鈕觸發(fā)時發(fā)出的 action 端點用任意 HTTP 客戶端直接向該端點發(fā)起請求攜帶任意resourceId越權(quán)刪除任何記錄。文檔中明確給出了這條攻擊路徑的唯一解客戶端沒有任何一種防護手段能修復這個問題校驗必須落在服務(wù)端 action 內(nèi)部。危險模式無校驗的刪除動作先看最常見的反例——一個看起來安全實則完全裸露的 action// ? BAD: No auth check — anyone can delete any record use server; export async function deleteResource(resourceId: string) { await db.resource.delete({ where: { id: resourceId } }); return { success: true }; }問題分析逐條對照文檔中的攻擊路徑接受裸的resourceId字符串未做任何身份確認未驗證調(diào)用者是否為該資源的屬主未對resourceId做格式與存在性校驗一旦被直接 POST即可刪除任意記錄。文檔強調(diào)看起來安全正是這種模式的迷惑性所在——按鈕可能只在登錄用戶可見、甚至只在管理員可見但 action 端點是公開的。不存在任何客戶端側(cè)守衛(wèi)能修復它。安全模式認證 → 授權(quán) → 執(zhí)行正確的姿勢是在 action 內(nèi)部按順序完成三道檢查再執(zhí)行真正的業(yè)務(wù)操作// ? GOOD: Verify auth, then ownership, then act use server; import { auth } from /lib/auth; import { revalidatePath } from next/cache; export async function deleteResource(resourceId: string) { // 1. Authentication — is anyone logged in? const session await auth(); if (!session?.user) { throw new Error(Unauthorized); } // 2. Authorization — does this user own this resource? const resource await db.resource.findUnique({ where: { id: resourceId } }); if (!resource || resource.userId ! session.user.id) { throw new Error(Forbidden); } // 3. Now its safe to perform the action await db.resource.delete({ where: { id: resourceId } }); revalidatePath(/dashboard); return { success: true }; }順序至關(guān)重要先認證authenticate再授權(quán)authorize最后執(zhí)行act。三道檢查缺一不可且順序不能顛倒——認證失敗就無需繼續(xù)查詢資源授權(quán)檢查必須基于已確認的會話身份進行。示例中還示范了兩個容易被忽略的細節(jié)資源不存在!resource與資源不屬于當前用戶userId ! session.user.id統(tǒng)一返回Forbidden避免通過響應(yīng)差異泄露資源存在性動作完成后調(diào)用revalidatePath(/dashboard)使相關(guān)頁面緩存失效保證下次訪問看到的是刪除后的狀態(tài)。三層檢查認證、授權(quán)、校驗文檔用一張表總結(jié)了 Server Action 必須通過的三層防線層級要回答的問題失敗響應(yīng)Authentication認證是否存在已登錄用戶Unauthorized等價 401Authorization授權(quán)該用戶是否有權(quán)操作此資源Forbidden等價 403Validation校驗輸入的結(jié)構(gòu)與取值是否合理Invalid input等價 400跳過任意一層都是安全漏洞。最常見的錯誤是做了認證卻跳過授權(quán)——已登錄不等于有權(quán)觸碰這條記錄。以本文開頭的deleteResource為例一個普通登錄用戶可以嘗試刪除任意resourceId只有屬主校驗resource.userId ! session.user.id才能真正阻止越權(quán)刪除。輸入校驗永遠不要信任傳入的數(shù)據(jù)形狀Server Actions 接受調(diào)用方傳來的任何東西。文檔要求任何接收結(jié)構(gòu)化輸入的 action頂部都必須使用 schema 校驗器Zod、Valibot 等。use server; import { z } from zod; import { auth } from /lib/auth; const UpdateProfileSchema z.object({ name: z.string().min(1).max(100), bio: z.string().max(500), }); export async function updateProfile(input: unknown) { const session await auth(); if (!session?.user) throw new Error(Unauthorized); // Validate before touching the DB const data UpdateProfileSchema.parse(input); await db.user.update({ where: { id: session.user.id }, data, }); }該示例體現(xiàn)的實踐要點入口類型聲明為unknown先假定輸入不可信必須經(jīng)過 schema 解析才能獲得可信類型schema 定義了明確的邊界name非空且最長 100 字符bio最長 500 字符——字符串長度上限直接阻斷超大 payload 型攻擊校驗先于數(shù)據(jù)庫寫入未經(jīng) schema 解析的原始input永遠不進入 ORM 調(diào)用schema 即白名單字段被 schema 聲明時已隱式地允許通過未聲明的字段如role: admin在解析結(jié)果中被剔除。文檔特別警告了不校驗的后果攻擊者可以傳入{ name: huge string, role: admin }數(shù)據(jù)庫寫入可能靜默覆蓋你并未打算暴露的字段。schema 校驗正是阻斷這類字段注入的閘門。復用高階包裝器authedAction當多個 action 需要同樣的認證檢查時文檔推薦將它們提煉為高階函數(shù)higher-order function包裝器避免每個 action 重復粘貼認證代碼// lib/action.ts import { auth } from /lib/auth; export function authedActionTInput, TOutput( fn: (input: TInput, userId: string) PromiseTOutput ) { return async (input: TInput): PromiseTOutput { const session await auth(); if (!session?.user) throw new Error(Unauthorized); return fn(input, session.user.id); }; }業(yè)務(wù) action 隨后被大幅簡化use server; import { authedAction } from /lib/action; export const deleteResource authedAction(async (resourceId: string, userId) { const resource await db.resource.findUnique({ where: { id: resourceId } }); if (!resource || resource.userId ! userId) { throw new Error(Forbidden); } await db.resource.delete({ where: { id: resourceId } }); });設(shè)計要點包裝器強制保證認證必發(fā)生——被包裝的函數(shù)拿到的第一個參數(shù)就是已確認的userId業(yè)務(wù)函數(shù)無法忘記認證但文檔明確提醒逐資源的授權(quán)檢查仍然必須由業(yè)務(wù)函數(shù)自己編寫這里沒有任何捷徑——authedAction解決的是是否登錄解決不了是否允許動這條記錄泛型參數(shù)TInput/TOutput讓包裝器保持類型安全fn(input, session.user.id)將認證結(jié)果顯式注入業(yè)務(wù)邏輯便于測試時注入 mock 身份。心智模型把每個 Server Action 當成公開端點來審查文檔在結(jié)尾給出了一個可執(zhí)行的心智模型值得作為代碼評審時的口頭禪把每一個 Server Action 都當作一個未經(jīng)認證的、攻擊者正在閱讀源碼的 HTTP 端點來對待。用這個模型審視任意一個 action如果它讓你產(chǎn)生不安這里好像少了點什么——說明它確實缺檢查立刻修如果它沒有讓你產(chǎn)生不安——你大概率遺漏了一道檢查。自檢清單對應(yīng)checklist.md中 Server Actions 一節(jié)的逐項要求路徑見 checklist.md每個 Server Action 頂部都調(diào)用auth()或等價實現(xiàn)每個接收資源 ID 的 action 都驗證了該資源的屬主關(guān)系輸入使用 schemaZod、Valibot 等校驗——永遠不信任輸入形狀錯誤以 throw 方式暴露而非靜默記錄日志。落地到 Resume-Matcher前端與后端的職責劃分將上述范式落地到 Resume-Matcher 倉庫時需要先理解其實際架構(gòu)前端apps/frontendNext.js App Router與后端apps/backendFastAPI是分離的兩層且當前倉庫的前端源碼中并未出現(xiàn)use server或revalidatePath的調(diào)用可通過在apps/frontend下檢索確認。從源碼結(jié)構(gòu)看前端的數(shù)據(jù)變更統(tǒng)一走 REST 客戶端再經(jīng) Next.js 代理到 FastAPI——這與文檔中的純 Server Actions 模式存在差異但三層檢查范式與威脅模型完全通用1. 動作端點在服務(wù)端受信任邊界內(nèi)Resume-Matcher 的前端 API 客戶端把所有請求收斂在 client.tsapiFetch統(tǒng)一封裝超時默認DEFAULT_TIMEOUT_MS受NEXT_PUBLIC_REQUEST_TIMEOUT_MS環(huán)境變量控制區(qū)間 30s–30min缺省 240s與AbortController中止邏輯所有寫操作經(jīng)apiPost/apiPatch/apiPut/apiDelete發(fā)出并在 config.ts 中以credentials: include攜帶會話 Cookie。這套設(shè)計在概念上等同于前端永遠通過受限的調(diào)用通道觸達動作端點——但正如文檔所警示的通道封裝并不能替代服務(wù)端校驗任何請求最終都會落到 FastAPI 路由上安全邊界必須在那里收口。2. 服務(wù)端校驗與文檔三層檢查一一對應(yīng)以簡歷上傳為例resumes.py 中的upload_resume端點完整體現(xiàn)了校驗 → 授權(quán)邊界 → 執(zhí)行的落點輸入校驗Validation先檢查content_type是否在ALLOWED_TYPES白名單內(nèi)PDF/DOC/DOCX不合法直接400再讀取內(nèi)容校驗MAX_FILE_SIZE4MB上限與空文件超限返回413解析后若提取不到文本掃描件/圖片型 PDF返回422。這些與文檔中輸入結(jié)構(gòu)不合理 → Invalid input等價 400一一對應(yīng)動作隔離執(zhí)行邊界解析成功后才原子地創(chuàng)建 master 記錄create_resume_atomic_master隨后嘗試結(jié)構(gòu)化解析、更新processing_status并返回帶request_id的ResumeUploadResponse兜底容錯文檔強調(diào)錯誤要 throw不要靜默吞掉后端則以_raise_improve_error封裝HTTPException(500)與各分支的logger.error/warning組合保證失敗可觀測且錯誤有明確的 HTTP 語義。再以改進簡歷流程為例improve_resume_preview_endpoint先驗證resume_id、job_id存在否則 404再用asyncio.wait_for包裹整條 LLM 調(diào)用鏈并以settings.request_timeout_seconds限時超時返回504。這對應(yīng)文檔中在進入昂貴操作前完成校驗/認證的原則——把校驗放在昂貴異步工作之前與系列文檔 01-waterfalls.md 中Validation/auth checks happen before expensive async work的檢查項一致。3. 縱深防御LLM 輸出同樣不信任一個值得注意的倉庫特色Resume-Matcher 在服務(wù)端對 LLM 生成內(nèi)容施加了多道白名單/恢復防線本質(zhì)上也是不信任輸入思想的延伸_preserve_personal_info將原始簡歷的personalInfo深拷貝回寫防止 AI 改寫個人信息_restore_original_datesrestore_dates_from_markdown還原被 LLM 截斷的日期精度_preserve_original_skills任何被 LLM 丟棄的原始技能/證書/語言/獎項都會被追加回來_protect_custom_sections裁剪 LLM 幻想的自定義條目、還原被篡改的空描述_hash_improved_data通過規(guī)范化后的一致性哈希保證 preview 與 confirm 兩階段的 payload 完全一致防止中間篡改否則直接 400 拒絕。這些實現(xiàn)與動作端點必須自證輸入可信的文檔思想同構(gòu)可作為理解文檔范式的絕佳倉庫內(nèi)實證詳見 resumes.py。4. 若未來引入 Server Actions如果你計劃在 Resume-Matcher 的前端或任何 Next.js 應(yīng)用中新增 Server Actions 直接寫數(shù)據(jù)請嚴格套用本文檔的全部范式頂部auth()確認會話按資源執(zhí)行屬主/角色授權(quán)schema 校驗所有結(jié)構(gòu)化輸入Zod/Valibot通過throw暴露錯誤配合revalidatePath同步緩存數(shù)量多時用authedAction之類的包裝器收口認證邏輯。同時注意本倉庫的代理約束當前 next.config.ts 通過 rewrites 將/api/:path*代理到 FastAPI默認http://127.0.0.1:8000并明確注釋不要創(chuàng)建app/api/路由否則會遮蔽后端代理——新增 Server Actions 前需評估是否會與既有/api代理發(fā)生路由沖突。與同系列文檔的關(guān)系本文是 Next.js 15 性能與安全系列的第 3 篇CRITICAL 級別同系列還包括01-waterfalls.md串行 await 瀑布流消除、Promise.all并行取數(shù)與 Suspense 流式渲染02-bundle-size.mdbarrel import 裁剪、動態(tài)導入與第三方腳本04-server-side-perf.mdReact.cache()請求去重、裁剪 Server→Client 序列化數(shù)據(jù)、after()非阻塞后置任務(wù)checklist.mdPR 前檢查清單與next.config.js基線模板。按系列建議的閱讀順序前三篇瀑布流、bundle、Server Actions 安全屬于不修必吃虧的 CRITICAL 級別其中本文雖然篇幅最短卻是唯一與安全直接相關(guān)、沒有商量余地的硬性要求——性能可以逐步優(yōu)化越權(quán)漏洞必須當場修復?？偨Y(jié)Server Actions 是公開 HTTP 端點UI 隱藏不等于安全攻擊者可攜帶任意 payload 直接調(diào)用三道檢查缺一不可認證是否登錄→ 授權(quán)是否允許動這條記錄→ 校驗輸入形狀與取值是否合理順序不能亂schema 校驗前置unknown入口 Zod/Valibot 白名單解析阻斷字段注入與超大 payload包裝器收口認證authedAction強制認證發(fā)生但逐資源授權(quán)仍需手寫心智模型把每個 action 當成攻擊者在讀源碼的公開端點來審查不安就修不修就等著出事倉庫實證Resume-Matcher 將同樣的服務(wù)端信任邊界 輸入白名單 縱深防御思想貫徹在 resumes.py 的 FastAPI 端點中可作為對照實現(xiàn)?！久赓M下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考