Epic Stack 安全机制实战指南从 CSP 到限流与密钥管理的完整防护体系【免费下载链接】epic-stackThis is a Full Stack app starter with the foundational things setup and configured for you to hit the ground running on your next EPIC idea.项目地址: https://gitcode.com/GitHub_Trending/ep/epic-stack本指南以 Epic Stack 仓库中的安全文档docs/security.md为骨架结合server/index.ts、app/entry.server.tsx、app/utils/honeypot.server.ts、app/utils/session.server.ts等源码实现系统讲解这套全栈 Starter 内置的纵深防御体系内容安全策略CSP、Fly 内部网络隔离、密钥管理、XSS/CSRF 防护、蜜罐字段与分级限流并延伸覆盖会话安全、密码哈希与输入校验等实战要点。读完你既能按文档逐步开启更严格的默认安全配置也能从源码层面理解每一道防线的工作原理与取舍。安全架构总览默认开启、可渐进加固Epic Stack 的设计理念是开箱即用但默认不阻断它预置了严格的安全配置同时又刻意让部分最严格的策略处于报告而非强制模式避免新用户被安全策略误伤。你可以按需逐步拧紧这些开关。整体防线分布在两个层面HTTP 中间件层server/index.tsHTTPS 重定向、安全响应头Helmet、分级限流、关闭x-powered-by等应用框架层React Router 渲染管线与app/utils工具集CSP 指令、nonce 注入、会话 Cookie 安全属性、蜜罐、Zod 输入校验、bcrypt 密码哈希与 Pwned Passwords 弱口令检测。相关的设计决策都记录在 docs/decisions 目录下如 008-content-security-policy.md、022-report-only-csp.md、025-rate-limiting.md、033-honeypot.md、035-remove-csrf.md是本指南的权威依据。内容安全策略CSP严格策略 默认 report-onlyEpic Stack 使用严格的内容安全策略Content Security Policy浏览器只允许从受信任来源加载资源从而大幅压缩 XSS 攻击面。最初的决策文档 008-content-security-policy.md 明确了默认尽可能严格的方向CSP 过于宽松会失去防护意义过于严格又会在引入第三方库时带来困扰因此默认应用配置了一组紧凑的指令必要时可以按需追加来源。关键点默认是report-only模式。浏览器只上报违规行为不真正拦截资源。这是 022-report-only-csp.md 的决策结果——为了让新用户不被 CSP 误伤遵循最小化上手摩擦的指导原则把强制 CSP 变成了一项可选项。代价是默认安全性打折扣所以官方文档要求把如何开启强制执行写清楚。实际配置位置app/entry.server.tsx原文档提到在server/index.ts中移除reportOnly: true在当前仓库中CSP 指令的实际定义位于渲染入口 app/entry.server.tsxcontentSecurity(responseHeaders, { crossOriginEmbedderPolicy: false, contentSecurityPolicy: { // NOTE: Remove reportOnly when youre ready to enforce this CSP reportOnly: true, directives: { fetch: { connect-src: [ MODE development ? ws: : undefined, process.env.SENTRY_DSN ? *.sentry.io : undefined, self, ], font-src: [self], frame-src: [self], img-src: [self, data:], script-src: [ strict-dynamic, self, nonce-${nonce}, ], script-src-attr: [nonce-${nonce}], }, }, }, })要点解读reportOnly: true生产环境准备就绪后删掉这一行即可强制拦截违规资源。上线前请务必先收集一段时间的报告确认没有遗漏的合法来源再切换。strict-dynamic noncescript-src使用strict-dynamic配合每请求随机生成的nonce源码中crypto.randomBytes(16).toString(hex)生成见 app/entry.server.tsx这是现代严格 CSP 的核心范式只有带正确 nonce 的脚本才允许执行非内联白名单脚本一律被拒。环境感知的来源开发模式下放开ws:Vite HMR 需要配置了SENTRY_DSN时放开*.sentry.io。这些条件式来源展示了如何安全地追加第三方服务。服务器层安全头server/index.ts 中的 Helmet在 HTTP 层server/index.ts 用 Helmet 中间件统一设置安全响应头app.use((_, res, next) { // The referrerPolicy breaks our redirectTo logic helmet(res, { general: { referrerPolicy: false } }) next() })这里刻意关闭了referrerPolicy因为它会破坏项目的redirectTo跳转逻辑——这是安全配置必须与业务逻辑兼容的典型示例。Helmet 提供的默认头包括X-Content-Type-Options: nosniff、X-Frame-Options: DENY等。同文件还执行了app.disable(x-powered-by)server/index.ts避免泄露 Express 指纹。Fly 内部网络实例间通信与共享密钥校验Epic Stack 默认部署在 Fly.io 上。Fly 的内部网络允许同一组织内的服务互相连通而不暴露到公网——只有你组织内的服务与账号能访问。多实例运行时实例之间正是通过这条内部网络通信的其中大部分由 Fly 托管的 consul 服务在后台完成。除此之外还有一个让各实例连接主区域primary region更新缓存的专用端点。它使用内部 URL通过litefs-js见 app/utils/litefs.server.ts 的封装导出并额外用共享密钥校验请求合法性。源码级证据位于 app/routes/admin/cache/sqlite.server.ts非主实例调用updatePrimaryCacheValue时通过getInternalInstanceDomain(primaryInstance)解析主实例内部域名请求头携带Authorization: Bearer ${INTERNAL_COMMAND_TOKEN}L24-L31主实例侧的action校验request.headers.get(Authorization) \Bearer ${token}不匹配则直接重定向走人L42-L48。文档也坦承了这一方案的局限目前没有可靠办法判断请求是否真正来自内部网络所以只能靠共享密钥兜底文档作者在 docs/security.md 中标注了如果能找到判定内部网络来源的方法欢迎提交 PR。除此之外Epic Stack 不访问任何其他第一方服务或数据库。密钥管理Secrets.env 本地 fly secrets 线上当前推荐的密钥管理策略很直白本地把密钥放进项目根目录的.env文件已被.gitignore忽略。仓库提供了模板 .env.example若不需要连接真实服务可直接cp .env.example .env。线上在 Fly 上用fly secrets命令设置同样的变量。模板中的安全相关变量包括SESSION_SECRETsuper-duper-s3cret HONEYPOT_SECRETsuper-duper-s3cret INTERNAL_COMMAND_TOKENsome-made-up-token值得注意的是环境变量并非设置了就行——app/utils/env.server.ts 用 Zod schema 在启动时强制校验全部必填变量SESSION_SECRET、HONEYPOT_SECRET、INTERNAL_COMMAND_TOKEN、DATABASE_URL等任何缺失或类型错误都会在init()中抛错并打印具体的字段错误L37-L48实现快速失败。文档也承认该方案存在明显局限例如密钥轮换、集中管理未来大概率会演进——但就当前版本而言这是官方推荐做法。跨站脚本XSSReact 默认转义 严格禁止渲染用户 HTMLReact 内置了 XSS 防护所有值默认转义输出。这意味着只有显式使用dangerouslySetInnerHTML才会渲染 HTML——这是一把双刃剑好的一面是默认安全坏的一面是它给了开发者绕开防护的入口。硬性红线是永远不要把任何用户生成的内容传给dangerouslySetInnerHTML。在配合上述 CSP 的strict-dynamic nonce 机制后即使脚本注入发生也会因 nonce 不匹配而被浏览器拒绝执行形成双重防线。跨站请求伪造CSRF以 SameSiteLax 取代传统 token原文档提到项目早期使用remix-utils的 CSRF 工具但当前仓库实际上已经移除了 CSRF token。决策文档 035-remove-csrf.md 解释了原因现代浏览器全面支持SameSite: Lax而项目所有 Cookie 都设置了该属性跨站请求不会携带 CookieGET请求不受SameSite: Lax保护但项目没有任何执行写操作的 GET 端点POST /login本身不需要 Cookie攻击者若已知用户名密码就直接登录了无需 CSRF。因此判断在 Cookie 配置为Lax、配合蜜罐防护的前提下保留 CSRF token 的复杂度得不偿失。但如果把 Cookie 的sameSite改成none就必须把 CSRF 防护加回来——这个警告也作为注释写在了会话配置源码里app/utils/session.server.ts。蜜罐字段Honeypot低成本抗垃圾机器人垃圾机器人会填满表单里的每一个字段包括视觉隐藏字段蜜罐正是利用这一点在公开表单中加入视觉隐藏字段提交时若该字段非空即可判定为机器人。Epic Stack 使用remix-utils的 honeypot 工具实现位于 app/utils/honeypot.server.tsimport { Honeypot, SpamError } from remix-utils/honeypot/server export const honeypot new Honeypot({ validFromFieldName: process.env.NODE_ENV test ? null : undefined, encryptionSeed: process.env.HONEYPOT_SECRET, }) export async function checkHoneypot(formData: FormData) { try { await honeypot.check(formData) } catch (error) { if (error instanceof SpamError) { throw new Response(Form not submitted properly, { status: 400 }) } throw error } }要点encryptionSeed来自HONEYPOT_SECRET用于加密字段的时间戳防止机器人记录字段名后重放测试环境下关闭validFromFieldName校验避免拖慢测试命中蜜罐直接返回400不给机器人任何有效反馈。表单端与 Action 端的使用范式表单里渲染隐藏输入公开表单必加import { HoneypotInputs } from remix-utils/honeypot/react Form methodPOST {...getFormProps(form)} HoneypotInputs / {/* 其余字段 */} /FormAction 中第一时间校验fail fastimport { checkHoneypot } from #app/utils/honeypot.server.ts export async function action({ request }: Route.ActionArgs) { const formData await request.formData() // 先查蜜罐——是垃圾流量就直接拒绝 await checkHoneypot(formData) // 通过后再继续业务处理 const submission await parseWithZod(formData, { schema: SignupSchema }) // ... }决策文档 033-honeypot.md 明确了覆盖范围所有公开表单都需要蜜罐已认证表单无需机器人本来也够不到。动机很实际例如注册流程会发邮件垃圾机器人乱填邮箱会造成邮件被标记为垃圾邮件、损害发信方声誉。分级限流Rate Limiting三层策略抵御暴力破解与滥用Epic Stack 使用express-rate-limit默认内存存储实现分级限流。完整实现见 server/index.ts。基础配置与 IP 提取const maxMultiple !IS_PROD || process.env.PLAYWRIGHT_TEST_BASE_URL ? 10_000 : 1 const rateLimitDefault { windowMs: 60 * 1000, limit: 1000 * maxMultiple, standardHeaders: true, legacyHeaders: false, validate: { trustProxy: false }, // 恶意用户可伪造 IP因此不能直接信任 req.ip // 但 Fly-Client-Ip 无法伪造。若前端有 CDN如 Cloudflare // 把 fly-client-ip 换成对应头如 cf-connecting-ip keyGenerator: (req: express.Request) { const ip req.ip ?? req.socket?.remoteAddress return req.get(fly-client-ip) ?? ipKeyGenerator(ip ?? 0.0.0.0) }, }细节值得注意maxMultiple开发与 Playwright 测试环境下把限额放大 10000 倍等效于关闭限流避免测试互相等待源码注释明确说明了这一点keyGenerator优先取fly-client-ip因为req.ip可被伪造而 Fly 的客户端 IP 头不可伪造validate: { trustProxy: false }则避免 express-rate-limit 对trust proxy配置的多余告警。三层限额限流器限额每分钟适用场景generalRateLimit1000普通 GET/HEAD 流量strongRateLimit100非 GET/HEAD 的写操作strongestRateLimit10敏感路径的写操作登录、注册、验证等const strongestRateLimit rateLimit({ ...rateLimitDefault, limit: 10 * maxMultiple }) const strongRateLimit rateLimit({ ...rateLimitDefault, limit: 100 * maxMultiple }) const generalRateLimit rateLimit(rateLimitDefault) app.use((req, res, next) { const strongPaths [ /login, /signup, /verify, /admin, /onboarding, /reset-password, /settings/profile, /resources/login, /resources/verify, ] if (req.method ! GET req.method ! HEAD) { if (strongPaths.some((p) req.path.includes(p))) { return strongestRateLimit(req, res, next) } return strongRateLimit(req, res, next) } // verify 路由特殊它是 GET但 token 可能在查询串里需严格限流 if (req.path.includes(/verify)) { return strongestRateLimit(req, res, next) } return generalRateLimit(req, res, next) })设计逻辑详见 025-rate-limiting.md用户 GET 请求远多于写操作所以写操作整体收紧到 100 次/分钟登录、注册、验证、重置密码、管理后台等高危端点进一步收紧到 10 次/分钟抵御暴力破解与刷邮件攻击者反复触发/signup、/settings/profile/change-email会让你的域名被邮件服务商标记为垃圾/verify虽是 GET但携带验证 token因此同样走最强限流。文档同时指出了取舍与演进方向内存存储在多实例 负载均衡即 Fly 场景下不是全局共享的跨实例的全局限流需要外置到 Redis 或 memcached——而express-rate-limit内置了共享存储支持迁移成本不高。另外共享 IP如公司网络用户可能被误伤这是当前愿意接受的权衡。若需要更细的维度例如按 API Key 限流可自定义keyGeneratorconst apiRateLimit rateLimit({ ...rateLimitDefault, limit: 100, keyGenerator: (req) req.get(X-API-Key) ?? req.get(fly-client-ip) ?? req.ip, }) app.use(/api, apiRateLimit)会话安全Cookie 属性与过期校验会话存储配置在 app/utils/session.server.tsexport const authSessionStorage createCookieSessionStorage({ cookie: { name: en_session, sameSite: lax, // 若改成 none 必须重新引入 CSRF 防护 path: /, httpOnly: true, secrets: process.env.SESSION_SECRET.split(,), secure: process.env.NODE_ENV production, }, })每一项都是明确的攻击面决策httpOnly: trueJavaScript 无法读取 Cookie封堵 XSS 窃取会话secure: production 才为 true仅生产环境通过 HTTPS 发送sameSite: lax跨站请求不携带 Cookie这是替代传统 CSRF token 的根基见上文 CSRF 一节secrets: process.env.SESSION_SECRET.split(,)支持密钥轮换——逗号分隔数组中的第一个用于签名其余用于验证旧 Cookie轮换时新旧并存平滑过渡。同文件还有一个巧妙设计L14-L38由于每次 commit 会话都会覆盖 Cookie项目把过期时间写进会话本身并在每次 commit 时重置保证服务端与 Cookie 的过期语义一致。会话过期快速失败获取用户 ID 时立刻校验会话存在性与过期时间app/utils/auth.server.tsexport async function getUserId(request: Request) { const authSession await authSessionStorage.getSession(request.headers.get(cookie)) const sessionId authSession.get(sessionKey) if (!sessionId) return null const session await prisma.session.findUnique({ select: { userId: true }, where: { id: sessionId, expirationDate: { gt: new Date() } }, }) if (!session?.userId) { // 会话失效立即销毁 Cookie 并重定向 throw redirect(/, { headers: { set-cookie: await authSessionStorage.destroySession(authSession) }, }) } return session.userId }会话默认有效期 30 天SESSION_EXPIRATION_TIME 1000 * 60 * 60 * 24 * 30见 app/utils/auth.server.ts。requireUserId、requireAnonymous等封装在此基础上提供认证/匿名跳转的快速失败能力。密码安全bcrypt 哈希 Pwned Passwords 弱口令检测密码哈希与校验app/utils/auth.server.tsexport async function getPasswordHash(password: string) { const hash await bcrypt.hash(password, 10) // 10 轮成本因子 return hash } export async function verifyUserPassword(where, password) { const userWithPassword await prisma.user.findUnique({ where, select: { id: true, password: { select: { hash: true } } }, }) if (!userWithPassword || !userWithPassword.password) return null const isValid await bcrypt.compare(password, userWithPassword.password.hash) return isValid ? { id: userWithPassword.id } : null }bcrypt 成本因子为 10天然自带盐是密码存储的行业标准选择。注册时还会调用Have I Been Pwned 的 k-anonymity 接口app/utils/auth.server.ts检查弱口令把密码 SHA-1 哈希的前 5 位发给https://api.pwnedpasswords.com/range/{prefix}本地比对返回的哈希后缀是否匹配——完整哈希永远不会离开你的服务器。网络异常或超时1 秒超时时优雅降级为视为通过不影响用户体验。对应的决策文档是 043-pwnedpasswords.md。校验逻辑实现在 app/utils/user-validation.ts密码最短 6 位且用字节长度限制在 72 字节以内bcrypt 的硬上限。输入校验与规范化Zod 全量覆盖所有用户输入在进入业务逻辑前都用 Zod 校验参见 app/utils/user-validation.tsexport const UsernameSchema z .string({ required_error: Username is required }) .min(3, { message: Username is too short }) .max(20, { message: Username is too long }) .regex(/^[a-zA-Z0-9_]$/, { message: Username can only include letters, numbers, and underscores, }) .transform((value) value.toLowerCase()) // 统一小写存储 export const EmailSchema z .string({ required_error: Email is required }) .email({ message: Email is invalid }) .min(3, { message: Email is too short }) .max(100, { message: Email is too long }) .transform((value) value.toLowerCase()) // 统一小写存储规范化的核心思路是信任边界内统一形态邮箱、用户名统一转小写避免同一用户因大小写产生重复账号密码用.refine做字节长度校验。在注册/登录的 action 中配合parseWithZod使用校验失败立即返回400与结构化错误信息。HTTPS 与辅助安全头虽然 Fly 等平台通常会在边缘终止 TLSEpic Stack 仍在应用层做了兜底server/index.ts对 GET 请求检查X-Forwarded-Proto该头由 Fly 代理写入若为http则 301 重定向到https://${host}${req.originalUrl}。此外app.set(trust proxy, true)server/index.tsFly 是反向代理必须信任代理头才能拿到真实协议与 IPX-Robots-Tag: noindex, nofollowserver/index.ts当ALLOW_INDEXING不为false时可控制爬虫索引行为默认允许索引。安全开发铁律常见错误清单综合安全文档与仓库实现以下是应避免的典型错误延迟安全检查认证、授权、输入校验必须在处理请求前尽早完成——fail fast错误信息过泛提供可操作的清晰错误但绝不泄露敏感数据公开表单漏加蜜罐所有免认证表单必须包含HoneypotInputs并在 action 中checkHoneypot不校验会话过期取会话时务必用expirationDate: { gt: new Date() }提前判定对用户数据使用dangerouslySetInnerHTML永远不要直接渲染用户 HTML不做限流敏感路由必须分级限流密钥写进代码一律走环境变量fly secrets管理线上值输入不规范化用 Zod 的.transform()统一小写、清理空白不查弱口令接入 Pwned Passwords 校验常见密码会话 Cookie 缺少httpOnly始终开启并保持sameSite: lax生产环境不强制 HTTPS确保 HTTP 重定向到 HTTPSCSP 过于宽松或忘记强制执行按需调整并移除reportOnly: true不记录安全事件安全失败要带上下文日志但不含敏感信息便于排障。小结从报告到强制的加固路线图Epic Stack 的安全体系是分层、渐进、可验证的。以 docs/security.md 为主线配合 docs/skills/epic-security/SKILL.md 的实践指南与各决策文档推荐的加固顺序是生成强随机SESSION_SECRET、HONEYPOT_SECRET、INTERNAL_COMMAND_TOKEN本地写入.env、线上fly secrets set观察一段时间 CSP 报告后移除 app/entry.server.tsx 的reportOnly: true强制执行 CSP保持sameSite: lax会话配置不改none否则必须补回 CSRF token多实例规模扩大时将限流存储外置到 Redis持续用npm run test与 e2e 测试tests/e2e回归认证与表单流程确保安全改造不破坏业务。每一道防线都能在仓库源码中找到对应实现与测试依据这也是 Epic Stack 作为全栈 Starter 在安全工程上的核心价值默认不裸露升级有路径决策有记录。【免费下载链接】epic-stackThis is a Full Stack app starter with the foundational things setup and configured for you to hit the ground running on your next EPIC idea.项目地址: https://gitcode.com/GitHub_Trending/ep/epic-stack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考