Resume-Matcher 前端安全加固Next.js Server Actions 认证、授权与输入校验实战指南【免费下载链接】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 级别的技术指南。它直指 Next.js App Router 开发中最容易被忽视的安全盲区Server Actions 本质上是公开的 HTTP 端点仅靠前端隐藏按钮无法提供任何保护。读完本文你将掌握认证 → 授权 → 校验 → 执行的完整动作安全范式、可复用的高阶包装器写法以及如何将该范式落地到 Resume-Matcher 这类前端 Next.js 后端 FastAPI架构中让每一次动作调用都经得起攻击者直接构造请求的考验。核心事实Server Actions 是公开的 HTTP 端点在 Next.js App Router 中使用use server指令声明的函数看起来像普通函数——从 Client Component 里 import 后直接调用即可。但从源码结构看Next.js 会在构建期把每个 Server Action 暴露为一条可被 HTTP POST 请求直接命中的路由任何拥有 fetch 客户端的攻击者都可以绕过 UI 直接调用它。由此得出本系列文档的第一安全铁律永远不要信任调用方call site。这个按钮只对管理员显示不构成任何保护——攻击者完全无视 UI 状态以任意 payload 直接调用 action。这意味着每一个 Server Action 都必须在action 函数体内完成认证与授权检查而不是依赖组件层级的条件渲染。为什么隐藏 UI救不了你攻击者的完整攻击路径非常简单打开浏览器开发者工具的 Network 面板找到按钮触发时发出的 action 端点用任意 HTTP 客户端直接向该端点发起请求携带任意resourceId越权删除任何记录。文档中明确给出了这条攻击路径的唯一解客户端没有任何一种防护手段能修复这个问题校验必须落在服务端 action 内部。危险模式无校验的删除动作先看最常见的反例——一个看起来安全实则完全裸露的 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字符串未做任何身份确认未验证调用者是否为该资源的属主未对resourceId做格式与存在性校验一旦被直接 POST即可删除任意记录。文档强调看起来安全正是这种模式的迷惑性所在——按钮可能只在登录用户可见、甚至只在管理员可见但 action 端点是公开的。不存在任何客户端侧守卫能修复它。安全模式认证 → 授权 → 执行正确的姿势是在 action 内部按顺序完成三道检查再执行真正的业务操作// ✅ 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 }; }顺序至关重要先认证authenticate再授权authorize最后执行act。三道检查缺一不可且顺序不能颠倒——认证失败就无需继续查询资源授权检查必须基于已确认的会话身份进行。示例中还示范了两个容易被忽略的细节资源不存在!resource与资源不属于当前用户userId ! session.user.id统一返回Forbidden避免通过响应差异泄露资源存在性动作完成后调用revalidatePath(/dashboard)使相关页面缓存失效保证下次访问看到的是删除后的状态。三层检查认证、授权、校验文档用一张表总结了 Server Action 必须通过的三层防线层级要回答的问题失败响应Authentication认证是否存在已登录用户Unauthorized等价 401Authorization授权该用户是否有权操作此资源Forbidden等价 403Validation校验输入的结构与取值是否合理Invalid input等价 400跳过任意一层都是安全漏洞。最常见的错误是做了认证却跳过授权——已登录不等于有权触碰这条记录。以本文开头的deleteResource为例一个普通登录用户可以尝试删除任意resourceId只有属主校验resource.userId ! session.user.id才能真正阻止越权删除。输入校验永远不要信任传入的数据形状Server Actions 接受调用方传来的任何东西。文档要求任何接收结构化输入的 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, }); }该示例体现的实践要点入口类型声明为unknown先假定输入不可信必须经过 schema 解析才能获得可信类型schema 定义了明确的边界name非空且最长 100 字符bio最长 500 字符——字符串长度上限直接阻断超大 payload 型攻击校验先于数据库写入未经 schema 解析的原始input永远不进入 ORM 调用schema 即白名单字段被 schema 声明时已隐式地允许通过未声明的字段如role: admin在解析结果中被剔除。文档特别警告了不校验的后果攻击者可以传入{ name: huge string, role: admin }数据库写入可能静默覆盖你并未打算暴露的字段。schema 校验正是阻断这类字段注入的闸门。复用高阶包装器authedAction当多个 action 需要同样的认证检查时文档推荐将它们提炼为高阶函数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); }; }业务 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 } }); });设计要点包装器强制保证认证必发生——被包装的函数拿到的第一个参数就是已确认的userId业务函数无法忘记认证但文档明确提醒逐资源的授权检查仍然必须由业务函数自己编写这里没有任何捷径——authedAction解决的是是否登录解决不了是否允许动这条记录泛型参数TInput/TOutput让包装器保持类型安全fn(input, session.user.id)将认证结果显式注入业务逻辑便于测试时注入 mock 身份。心智模型把每个 Server Action 当成公开端点来审查文档在结尾给出了一个可执行的心智模型值得作为代码评审时的口头禅把每一个 Server Action 都当作一个未经认证的、攻击者正在阅读源码的 HTTP 端点来对待。用这个模型审视任意一个 action如果它让你产生不安这里好像少了点什么——说明它确实缺检查立刻修如果它没有让你产生不安——你大概率遗漏了一道检查。自检清单对应checklist.md中 Server Actions 一节的逐项要求路径见 checklist.md每个 Server Action 顶部都调用auth()或等价实现每个接收资源 ID 的 action 都验证了该资源的属主关系输入使用 schemaZod、Valibot 等校验——永远不信任输入形状错误以 throw 方式暴露而非静默记录日志。落地到 Resume-Matcher前端与后端的职责划分将上述范式落地到 Resume-Matcher 仓库时需要先理解其实际架构前端apps/frontendNext.js App Router与后端apps/backendFastAPI是分离的两层且当前仓库的前端源码中并未出现use server或revalidatePath的调用可通过在apps/frontend下检索确认。从源码结构看前端的数据变更统一走 REST 客户端再经 Next.js 代理到 FastAPI——这与文档中的纯 Server Actions 模式存在差异但三层检查范式与威胁模型完全通用1. 动作端点在服务端受信任边界内Resume-Matcher 的前端 API 客户端把所有请求收敛在 client.tsapiFetch统一封装超时默认DEFAULT_TIMEOUT_MS受NEXT_PUBLIC_REQUEST_TIMEOUT_MS环境变量控制区间 30s–30min缺省 240s与AbortController中止逻辑所有写操作经apiPost/apiPatch/apiPut/apiDelete发出并在 config.ts 中以credentials: include携带会话 Cookie。这套设计在概念上等同于前端永远通过受限的调用通道触达动作端点——但正如文档所警示的通道封装并不能替代服务端校验任何请求最终都会落到 FastAPI 路由上安全边界必须在那里收口。2. 服务端校验与文档三层检查一一对应以简历上传为例resumes.py 中的upload_resume端点完整体现了校验 → 授权边界 → 执行的落点输入校验Validation先检查content_type是否在ALLOWED_TYPES白名单内PDF/DOC/DOCX不合法直接400再读取内容校验MAX_FILE_SIZE4MB上限与空文件超限返回413解析后若提取不到文本扫描件/图片型 PDF返回422。这些与文档中输入结构不合理 → Invalid input等价 400一一对应动作隔离执行边界解析成功后才原子地创建 master 记录create_resume_atomic_master随后尝试结构化解析、更新processing_status并返回带request_id的ResumeUploadResponse兜底容错文档强调错误要 throw不要静默吞掉后端则以_raise_improve_error封装HTTPException(500)与各分支的logger.error/warning组合保证失败可观测且错误有明确的 HTTP 语义。再以改进简历流程为例improve_resume_preview_endpoint先验证resume_id、job_id存在否则 404再用asyncio.wait_for包裹整条 LLM 调用链并以settings.request_timeout_seconds限时超时返回504。这对应文档中在进入昂贵操作前完成校验/认证的原则——把校验放在昂贵异步工作之前与系列文档 01-waterfalls.md 中Validation/auth checks happen before expensive async work的检查项一致。3. 纵深防御LLM 输出同样不信任一个值得注意的仓库特色Resume-Matcher 在服务端对 LLM 生成内容施加了多道白名单/恢复防线本质上也是不信任输入思想的延伸_preserve_personal_info将原始简历的personalInfo深拷贝回写防止 AI 改写个人信息_restore_original_datesrestore_dates_from_markdown还原被 LLM 截断的日期精度_preserve_original_skills任何被 LLM 丢弃的原始技能/证书/语言/奖项都会被追加回来_protect_custom_sections裁剪 LLM 幻想的自定义条目、还原被篡改的空描述_hash_improved_data通过规范化后的一致性哈希保证 preview 与 confirm 两阶段的 payload 完全一致防止中间篡改否则直接 400 拒绝。这些实现与动作端点必须自证输入可信的文档思想同构可作为理解文档范式的绝佳仓库内实证详见 resumes.py。4. 若未来引入 Server Actions如果你计划在 Resume-Matcher 的前端或任何 Next.js 应用中新增 Server Actions 直接写数据请严格套用本文档的全部范式顶部auth()确认会话按资源执行属主/角色授权schema 校验所有结构化输入Zod/Valibot通过throw暴露错误配合revalidatePath同步缓存数量多时用authedAction之类的包装器收口认证逻辑。同时注意本仓库的代理约束当前 next.config.ts 通过 rewrites 将/api/:path*代理到 FastAPI默认http://127.0.0.1:8000并明确注释不要创建app/api/路由否则会遮蔽后端代理——新增 Server Actions 前需评估是否会与既有/api代理发生路由冲突。与同系列文档的关系本文是 Next.js 15 性能与安全系列的第 3 篇CRITICAL 级别同系列还包括01-waterfalls.md串行 await 瀑布流消除、Promise.all并行取数与 Suspense 流式渲染02-bundle-size.mdbarrel import 裁剪、动态导入与第三方脚本04-server-side-perf.mdReact.cache()请求去重、裁剪 Server→Client 序列化数据、after()非阻塞后置任务checklist.mdPR 前检查清单与next.config.js基线模板。按系列建议的阅读顺序前三篇瀑布流、bundle、Server Actions 安全属于不修必吃亏的 CRITICAL 级别其中本文虽然篇幅最短却是唯一与安全直接相关、没有商量余地的硬性要求——性能可以逐步优化越权漏洞必须当场修复。总结Server Actions 是公开 HTTP 端点UI 隐藏不等于安全攻击者可携带任意 payload 直接调用三道检查缺一不可认证是否登录→ 授权是否允许动这条记录→ 校验输入形状与取值是否合理顺序不能乱schema 校验前置unknown入口 Zod/Valibot 白名单解析阻断字段注入与超大 payload包装器收口认证authedAction强制认证发生但逐资源授权仍需手写心智模型把每个 action 当成攻击者在读源码的公开端点来审查不安就修不修就等着出事仓库实证Resume-Matcher 将同样的服务端信任边界 输入白名单 纵深防御思想贯彻在 resumes.py 的 FastAPI 端点中可作为对照实现。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考